From 3fac309fb3636877b674cf05fff5e80ef85c22e5 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 13:30:22 -0700 Subject: [PATCH 01/12] =?UTF-8?q?docs(handoff):=20add=20local=E2=86=94clou?= =?UTF-8?q?d=20handoff=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new handoff section under cloud-agents that documents the three directions of handoff supported by the orchestration launch: - Overview (conceptual) explaining what handoff is, the three directions, and what carries over. - Local→cloud (procedural) for promoting a local Warp Agent conversation to a cloud agent run. - Cloud→local (procedural) for picking up a cloud run inside the Warp terminal via /continue-locally and equivalent UI entrypoints. - Cloud→cloud (procedural) for follow-ups that span multiple executions of the same run. Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 92 +++++++++++++++++++ .../cloud-agents/handoff/cloud-to-local.mdx | 90 ++++++++++++++++++ .../cloud-agents/handoff/index.mdx | 55 +++++++++++ .../cloud-agents/handoff/local-to-cloud.mdx | 74 +++++++++++++++ 4 files changed, 311 insertions(+) create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/index.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx new file mode 100644 index 00000000..ee3f2099 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -0,0 +1,92 @@ +--- +title: Handoff from cloud to cloud +description: >- + Send a follow-up to a cloud agent run after its sandbox shut down. Oz creates + a new execution on the same run and rehydrates the prior workspace state so + the agent picks up where it left off. +sidebar: + label: "Cloud to cloud" +--- + +Hand off a cloud agent run to a fresh cloud execution when the original sandbox has shut down but you still want to push the same unit of work further. Oz creates a new execution on the same run id, reuses the same agent conversation, and rehydrates the prior execution's workspace state so the new agent picks up where the old one left off — not from scratch. + +This direction is the right move when: + +* A cloud agent finished and you want to send a follow-up after the sandbox has already torn down. +* A scheduled or integration-triggered run completed and you want to keep iterating without losing context. +* You want to continue an ambient agent task across multiple cloud executions while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). + +## How cloud-to-cloud handoff works + +When you submit a follow-up to a cloud run, Oz routes the message based on the run's current state: + +* **Appended** - The run hasn't started yet, so the follow-up is appended to the prompt. +* **Injected** - The current execution is still reachable, so the follow-up is injected into the live shared session. +* **Requeued** - The sandbox has ended, so Oz creates a new execution on the same run. + +Cloud-to-cloud handoff is the **requeued** path. The user-facing effect is the same — you submit a follow-up and the run continues — but the underlying mechanics differ because the new execution starts on a fresh sandbox. + +## What the new execution receives + +Each cloud agent run captures a snapshot of its workspace at the end of its execution and uploads it to a per-execution prefix in storage (`snapshots/{run_id}/{execution_id}/`). When a new execution starts on the same run, Oz discovers the prior execution's snapshot and rehydrates from it. + +* **The same agent conversation** - The new execution writes to the same agent conversation id as the prior execution. From the user's perspective, the run is one continuous conversation across multiple sandboxes. +* **The prior workspace state** - The prior execution's repository diffs (tracked and untracked) and any orphan files declared in its `snapshot_state.json` manifest are downloaded into the new sandbox and applied via `git apply` before the agent answers the follow-up. +* **Stable run identity** - The run id, task id, and run metadata (creator, environment, schedule trigger, integration source) are preserved. Compute usage is recorded per execution but rolls up to the same run. + +The receiving agent's first turn applies the patches and reports any that failed. If a patch fails outright, the agent retries it with `git apply --3way` and only proceeds to the user's follow-up after every patch has been attempted. + +## Prerequisites + +* **An ended cloud agent run** - The run must have a `succeeded`, `failed`, `error`, `blocked`, or `cancelled` state and an associated agent conversation id. Runs with no conversation id (rare; mostly legacy) cannot be continued via handoff. +* **A snapshot from the prior execution** - The agent driver uploads a snapshot at the end of every cloud agent run by default. If the prior execution didn't upload a snapshot (for example, the snapshot upload itself failed), the new execution still proceeds — it just starts without rehydrated workspace state. +* **Access to the run** - You must have permission to submit follow-ups for the run. For team runs, this is normally any member of the team. + +## Sending a follow-up that triggers cloud-to-cloud handoff + +Cloud-to-cloud handoff is automatic. You don't choose between "send a follow-up" and "hand off" — you just send a follow-up, and Oz picks the routing. + +### From the Warp app + +1. **Open the ended cloud run.** Navigate to the run in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or via the conversation panel. +2. **Send your follow-up.** Type the next message into the conversation's input bar and submit it. Oz routes the message and, if the sandbox has ended, creates a new execution on the same run. +3. **Watch the new execution.** A new execution appears in the run's history with its own start time. The conversation continues in the same thread, and the new sandbox's first tool calls are the rehydration patches. + +### From the Oz web app + +1. **Open the run at oz.warp.dev.** Click into the run from the **Runs** tab in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). +2. **Send the follow-up.** Use the in-page input to send your next message. The same routing rules apply. + +### From an integration + +When a Slack-triggered or Linear-triggered cloud run ends, the integration can post follow-up messages into the same run. The server treats those follow-ups identically to ones sent from the Warp app — if the sandbox is gone, a new execution starts and rehydrates from the prior snapshot. See [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces. + +## Inspecting handoff executions + +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows a single row per run, even when the run spans multiple executions. To inspect each execution: + +1. **Open the run detail.** Click the run row to open the conversation transcript. +2. **Look at the execution timeline.** The run detail surfaces each execution separately. You can see which execution wrote each message and how long each execution ran. +3. **Check the rehydration tool calls.** The first tool calls in each requeued execution are the patch-apply commands. If any failed, the agent's report appears in that execution's transcript. + +## Troubleshooting + +**My follow-up didn't trigger a new execution — it just appended to the prompt.** +The original run hasn't started yet (state is still `queued` or `pending`). Oz appended your message to the prompt the new execution will pick up. This is the **appended** path, not handoff; the run hasn't ended yet so there's nothing to hand off from. + +**My follow-up injected into the live session instead of creating a new execution.** +The original sandbox is still reachable. Oz injected your message into the live shared session — the **injected** path. This is the cheapest routing and avoids spinning up a fresh sandbox. You don't need to do anything; the agent will handle the follow-up in the existing execution. + +**The new execution started but no patches were applied.** +The prior execution didn't upload a snapshot. This is rare but possible — snapshot upload is best-effort and can fail (for example, on a transient storage error). The new execution still proceeds with the same agent conversation, so the agent has the full transcript context even without the workspace state. + +**The run is in a terminal state with no conversation id and follow-ups are rejected.** +Some very old runs predate the agent conversation model and cannot be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over. +* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. +* [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/) - Take over a cloud run inside the Warp terminal. +* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. +* [Oz API and SDK](/reference/api-and-sdk/) - Programmatic follow-up submission via `POST /agent/runs/{runId}/followups`. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx new file mode 100644 index 00000000..5231044d --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx @@ -0,0 +1,90 @@ +--- +title: Handoff from cloud to local +description: >- + Pick up a cloud agent run inside the Warp terminal to verify, iterate, or + polish changes before shipping — without losing the cloud agent's + conversation history. +sidebar: + label: "Cloud to local" +--- + +Hand off a cloud agent run to your local Warp terminal when you want to take over the work in person. The local session forks the cloud conversation in place, so you keep the full transcript, can ask follow-up questions, and can make manual edits inside the same flow the cloud agent was using. + +This direction is the right move when: + +* A cloud agent has done the heavy lifting and you want to verify the changes against your local checkout. +* You want to make manual tweaks before approving a PR. +* You want to ask follow-up questions to a cloud run interactively rather than waiting on another cloud round-trip. +* A teammate triggered a cloud run from Slack or a schedule and you want to push it further from your machine. + +## What the local conversation receives + +When you continue a cloud run locally, the Warp client materializes a fork of the cloud conversation and opens it as a new pane next to your current one. The fork inherits: + +* **The full transcript** - Every user turn, agent turn, and tool call from the cloud run is visible in the local conversation. +* **Conversation attachments** - Files attached during the cloud run remain available to reference locally. +* **The agent's plan and artifacts** - Any plan documents, branch artifacts, or pull request links the cloud agent produced are accessible from the local view. + +Continuing a cloud run locally creates a fork rather than modifying the source. The original cloud run stays intact; your local conversation diverges from it as soon as you send a new prompt or make a manual edit. This matches [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) behavior — the cloud run continues to live in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) and can be revisited later. + +:::note +Cloud-to-local handoff brings the cloud agent's conversation and artifacts into your terminal. It does not automatically apply the cloud agent's uncommitted workspace changes to your local checkout — review the agent's PR or branch artifact to inspect and pull in those changes. +::: + +## Prerequisites + +* **A cloud agent run to pick up** - The run can be in any state: still working, completed, failed, or canceled. The conversation must be cloud-synced (cloud agent runs are stored in the cloud by default). +* **Cloud conversation storage enabled** - **Settings** > **Privacy** > **Store AI conversations in the cloud** must be on. Cloud agent conversations are always synced regardless of this setting, but storage must be on for the local fork to write back. +* **Warp desktop app** - Cloud-to-local handoff continues the conversation inside the Warp app. From the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), the equivalent action is **Open in Warp**, which launches Warp and starts the local fork. + +## Continuing a cloud run locally + +There are three entry points to continue a cloud run locally, depending on where you are in the workflow. + +### From the conversation details panel + +Use this when you're already inspecting a cloud run inside the Warp app. + +1. **Open the cloud run.** In the conversation panel or the [management view](/agent-platform/cloud-agents/managing-cloud-agents/), click the run you want to continue. +2. **Open the conversation details panel.** Click the info button in the pane header to open the side panel that shows run metadata. +3. **Click Continue locally.** Warp forks the conversation and opens it in a split pane next to the cloud run. The new pane is the local conversation; the cloud run pane remains on its side for reference. + +### From the ended-run tombstone + +Use this when a cloud run has just finished and you want to take over without leaving the pane. + +1. **Wait for the cloud agent to finish.** When the run ends, an ended-run tombstone card appears at the bottom of the pane with the run's metadata and artifacts. +2. **Click Continue locally on the tombstone.** Warp forks the conversation into a split pane the same way the details panel does. + +### Via the `/continue-locally` slash command + +Use this when you want to continue a cloud conversation by name without first navigating to it. + +1. **Open the cloud conversation in the Warp terminal.** Run `/continue-locally` from inside the cloud conversation pane (or from a fresh pane if the conversation panel surfaces a recent run you want to pick up). +2. **Confirm the fork.** Warp creates the local fork in a split pane and focuses the input so you can immediately type your follow-up. + +## Continuing in your next turn + +After the local fork opens, you can interact with the agent the same way you would in any local Warp conversation. + +1. **Send a follow-up prompt.** Anything you type in the local pane is now a turn in the forked conversation. The cloud run is unaffected. +2. **Inspect the agent's workspace changes.** If the cloud agent produced a branch or PR artifact, the local conversation surfaces the same buttons (visible in the artifacts row). Click through to review the changes in your local checkout or in GitHub. +3. **Make manual edits if needed.** The local conversation is a regular Warp Agent conversation. You can edit files, run commands, or use any other Warp surface alongside the agent. + +## Troubleshooting + +**The Continue locally button doesn't appear.** +The button is hidden when AI features are disabled. Confirm in **Settings** > **AI** that AI is enabled and that you're signed in. The button is also hidden while a conversation is still in progress in a few states — wait for the agent to enter a stable state (working, completed, blocked, failed, or canceled) and the button should appear. + +**The local fork opens but doesn't show the full transcript.** +The conversation data may not have finished syncing yet. Cloud agent conversations stream their state in near-real-time, so this is usually a few-second delay. If the transcript still looks truncated after a minute, refresh the conversation panel. + +**I'm in the Oz web app on a mobile device — there's no Continue locally button.** +Continuing locally requires the Warp desktop app. On mobile or in a browser, you'll see **Open in Warp** instead. Clicking it deep-links into the desktop app and runs the same fork-and-open flow. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over. +* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - The reverse direction, for promoting a local conversation to a cloud run. +* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How cloud conversations are stored, shared, and restored locally. +* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find cloud runs to continue locally. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx new file mode 100644 index 00000000..a3b627fb --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -0,0 +1,55 @@ +--- +title: Handoff between local and cloud agents +description: >- + Move an agent conversation between your terminal and the cloud, or between + cloud runs, without losing context. Three handoff directions, one continuous + unit of work. +sidebar: + label: "Handoff overview" +--- + +Handoff lets you move a single unit of agent work between your local terminal and the cloud, or between two cloud runs, without re-explaining the task. You start where it's convenient, hand the work off when you need different compute or visibility, and pick it back up wherever the agent left off. + +## Three directions of handoff + +Each direction solves a different gap in the local + cloud workflow. + +* **Local to cloud** - Start in the Warp terminal, then promote the conversation to a cloud agent run when you need more compute, longer-running execution, or to parallelize multiple variants. The cloud agent starts from your conversation history and your uncommitted workspace state. +* **Cloud to local** - Pick up a cloud run inside the Warp terminal to verify, iterate, or polish before shipping. Useful when a cloud agent has done the heavy lifting and you want to take over locally for the final mile. +* **Cloud to cloud** - Send a follow-up to a cloud run whose sandbox has already shut down. Oz creates a new execution on the same run and rehydrates the prior execution's workspace state so the agent continues the same task instead of starting fresh. + +## What carries over + +Handoff is designed to preserve enough state that the receiving agent can resume the work, not just read about it. + +* **Conversation history** - The receiving agent sees the full transcript of the prior session. For local-to-cloud, Oz materializes a server-side fork of the local conversation so the source isn't modified. For cloud-to-cloud, the same agent conversation id is reused across executions. +* **Workspace state** - Repository diffs (tracked and untracked changes) from the prior session are captured as patch files and applied in the receiving sandbox before the agent answers the next prompt. Local-to-cloud uploads patches from your local checkout; cloud-to-cloud reuses the snapshot the prior cloud execution wrote at the end of its run. +* **Snapshot manifest** - A `snapshot_state.json` manifest records the repo name, branch, and HEAD SHA at handoff time so the receiving agent can verify it's applying patches at the right checkout point. +* **Artifacts and attachments** - Files the prior session attached to the conversation remain available to the receiving agent. + +## How handoff works + +The three directions share one mechanism: a workspace snapshot stored in Google Cloud Storage plus a forked or continued agent conversation. The receiving agent's first turn applies the patches via `git apply` and then addresses the user's follow-up. + +* **Local to cloud** - The Warp client uploads workspace patches and a manifest to a token-scoped staging area (`handoff/{token}/`) and then creates a new cloud run that references both the token and a forked copy of the local conversation. The cloud sandbox downloads the snapshot, applies the patches, and starts the agent on a fresh execution. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). +* **Cloud to local** - The Warp client forks the cloud conversation locally and opens it in a split pane. You continue the conversation from the same point the cloud agent left off. See [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/). +* **Cloud to cloud** - Submitting a follow-up to an ended cloud run creates a new execution on the same run. The new execution discovers the prior execution's snapshot at `snapshots/{run_id}/{execution_id}/` and rehydrates from it. The run id, task id, and agent conversation id stay stable across executions. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). + +## When to use handoff + +Each direction has a clear motivating workflow. + +* **Local to cloud** - Use when a local conversation has spiraled into work that's better done in the cloud. Common reasons include: needing to run a long-running task without tying up your laptop, parallelizing variants of the same task across cloud sandboxes, or steering work from a mobile device once it's running in the cloud. +* **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over for verification, manual review, or polish before shipping. Also useful for inspecting the agent's changes against your local checkout. +* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up — even though the sandbox shut down — without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further from the Warp terminal. + +## Rehydration behavior + +Handoff is best-effort. When patches apply cleanly, the receiving agent picks up the work exactly where the prior session left off. When they don't, the agent reports which patches failed and proceeds with what it could apply rather than starting over silently. The same rehydration prompt is used across all three directions so the agent's pre-turn checklist is consistent regardless of where the work originated. + +## Related pages + +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. +* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. +* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. +* [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx new file mode 100644 index 00000000..1a113ee6 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -0,0 +1,74 @@ +--- +title: Handoff from local to cloud +description: >- + Promote a local Warp Agent conversation to a cloud agent run when you need + more compute, longer-running execution, or parallel work — without + re-explaining the task. +sidebar: + label: "Local to cloud" +--- + +Hand off a conversation from the Warp terminal to a cloud agent run when the work outgrows your local session. The cloud agent starts from a fork of your local conversation and a snapshot of your uncommitted workspace state, so it picks up where you left off instead of starting fresh. + +This direction is the right move when: + +* The task is going to run for a long time and you don't want to keep your laptop awake. +* You want to fan out variants of the same task across multiple cloud sandboxes in parallel. +* You want to walk away and check on the agent from a different device. +* You want the agent to keep working while you start a new conversation locally. + +## What the cloud agent receives + +When you hand off from local to cloud, Oz transfers three things to the receiving agent: + +* **A forked conversation** - Oz creates a server-side fork of your local conversation so the cloud agent inherits the full transcript without modifying the source. The fork is owned by you, not by the original conversation's owner. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related conversation-sync behavior. +* **A workspace snapshot** - Warp captures `git diff --binary HEAD` for every repo in your working directory (tracked and untracked changes), packages it as a set of `.patch` files plus a `snapshot_state.json` manifest, and uploads them to a token-scoped staging area. The cloud sandbox downloads and applies the patches before the agent answers your next prompt. +* **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. + +The receiving agent sees an explicit pre-turn checklist that tells it to read the manifest, apply each patch via `git apply`, and confirm the affected files are dirty before answering your follow-up. If a patch fails to apply, the agent retries with `git apply --3way` and then reports any unrecoverable failures rather than silently dropping changes. + +## Prerequisites + +* **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. +* **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repository (or repositories) you're working in locally. The environment's repos must match the local checkout so the workspace patches apply cleanly. +* **Cloud conversation storage enabled** - Cloud conversation storage must be on (**Settings** > **Privacy** > **Store AI conversations in the cloud**) so the conversation can be forked server-side. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). +* **Sufficient credits** - Cloud agent runs consume credits. See [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) for credit requirements. + +## Handing off a conversation to the cloud + +The handoff entry point is integrated into the cloud agent launch flow, so the same UI that starts a fresh cloud run can also continue an existing local conversation. + +1. **In the active conversation, open the cloud agent launch flow.** In the Warp terminal with the local conversation focused, run the `/cloud-agent` slash command (or press `⌘+Option+Enter` on macOS / `Ctrl+Alt+Enter` on Windows/Linux). When invoked from inside an active conversation, the cloud agent setup view offers to continue the current conversation rather than starting a new one. +2. **Choose the environment for the cloud run.** Pick the environment whose repos match the directories your local conversation has been editing. If you don't have a matching environment yet, run `/create-environment` first and add the repos you've been working in. +3. **Confirm the handoff and add a follow-up prompt.** Enter the next message you want the cloud agent to act on. This becomes the first user-facing message in the cloud run; the rehydration checklist runs invisibly before it. +4. **Submit the run.** Warp captures the workspace snapshot from your current working directory, uploads it to a token-scoped staging area, and creates the cloud run with both the snapshot token and a fork of the local conversation. You see the new cloud run appear in the conversation panel and in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). + +After submission, the cloud agent's first turn applies the patches and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. + +## Verifying the handoff + +Confirm the handoff is doing what you expect by inspecting the cloud run. + +1. **Open the cloud run.** Click the new run in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. +2. **Check the agent's first turn.** The first tool calls should be `cat snapshot_state.json` followed by one or more `git apply` invocations. If `git apply` fails for any patch, the agent reports the failure inline before continuing. +3. **Confirm the workspace is dirty.** The agent runs `git status` in each affected repo after applying patches; the output should show the same files you had modified locally. + +If the snapshot doesn't appear to land, the cloud agent still proceeds with the forked conversation and the agent's history — it just won't have your uncommitted changes. The conversation panel's run detail surfaces the snapshot files so you can confirm what was uploaded. + +## Troubleshooting + +**The cloud agent reports `git apply` failures.** +The most common cause is a repository mismatch between your local checkout and the environment. The patches are generated against the HEAD of your local repo; the environment must check out a compatible base for `git apply` to succeed. If the agent reports a 3-way merge failure, switch the environment's repo to the same branch you were on locally and re-run the handoff. + +**The cloud agent doesn't see my uncommitted changes.** +Cloud conversation storage must be enabled for handoff to work. Open **Settings** > **Privacy** in the Warp app and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked server-side and the run falls back to starting fresh. + +**The conversation doesn't appear in the cloud run.** +The source conversation may not have finished syncing to the cloud when you triggered the handoff. Warp returns a transient error in this case — wait a moment and retry the handoff. If it persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over. +* [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/) - The reverse direction, for taking over a cloud run locally. +* [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands that the cloud agent starts in. +* [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. From e1da8dd9b755a4073cb682824f4a3ede0a824ccb Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 13:56:25 -0700 Subject: [PATCH 02/12] docs(handoff): scrub internals, drop cloud-to-local, tighten copy Address PR review feedback and Slack-thread direction. - Drop cloud-to-local.mdx; existing fork-to-local docs in viewing-cloud-agent-runs.mdx already cover the capability. Overview now references that page for cloud-to-local. - Scope the snapshot rehydration mechanism in the overview to local-to-cloud and cloud-to-cloud only; cloud-to-local does not apply workspace patches. - Replace the inaccurate `git diff --binary HEAD` capture description in local-to-cloud with a high-level summary that covers tracked and untracked changes without committing to a specific git command. - Soften the local-to-cloud entry point: do not document a specific keyboard shortcut, add a note that the affordance may evolve during the Oz launch rollout. - Strip internal-only details from user-facing copy: GCS paths, manifest filenames, `git apply` mechanics, internal routing names (appended/injected/requeued), API endpoint paths, and rehydration checklist references. - Senior-writer pass: tighten descriptions to 50-160 chars, reduce marketing fluff, normalize cross-references. Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 76 ++++++++-------- .../cloud-agents/handoff/cloud-to-local.mdx | 90 ------------------- .../cloud-agents/handoff/index.mdx | 45 ++++------ .../cloud-agents/handoff/local-to-cloud.mdx | 55 ++++++------ 4 files changed, 85 insertions(+), 181 deletions(-) delete mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index ee3f2099..46c24e04 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -1,92 +1,90 @@ --- title: Handoff from cloud to cloud description: >- - Send a follow-up to a cloud agent run after its sandbox shut down. Oz creates - a new execution on the same run and rehydrates the prior workspace state so - the agent picks up where it left off. + Send a follow-up to a cloud run whose sandbox has shut down. A new execution + starts on the same run with the prior execution's workspace state restored. sidebar: label: "Cloud to cloud" --- -Hand off a cloud agent run to a fresh cloud execution when the original sandbox has shut down but you still want to push the same unit of work further. Oz creates a new execution on the same run id, reuses the same agent conversation, and rehydrates the prior execution's workspace state so the new agent picks up where the old one left off — not from scratch. +Hand off a cloud agent run to a fresh cloud execution when the original sandbox has shut down but you still want to push the same unit of work further. A new execution starts on the same run, reuses the same agent conversation, and rehydrates the prior execution's workspace state — so the new agent picks up where the old one left off, not from scratch. This direction is the right move when: * A cloud agent finished and you want to send a follow-up after the sandbox has already torn down. * A scheduled or integration-triggered run completed and you want to keep iterating without losing context. -* You want to continue an ambient agent task across multiple cloud executions while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +* You want to continue an ambient agent task across multiple executions while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). -## How cloud-to-cloud handoff works +## How follow-ups route -When you submit a follow-up to a cloud run, Oz routes the message based on the run's current state: +When you submit a follow-up to a cloud run, the routing depends on the run's current state: -* **Appended** - The run hasn't started yet, so the follow-up is appended to the prompt. -* **Injected** - The current execution is still reachable, so the follow-up is injected into the live shared session. -* **Requeued** - The sandbox has ended, so Oz creates a new execution on the same run. +* **The run is still queued and hasn't started.** Your message is added to the prompt the run will pick up when it starts. +* **The original sandbox is still alive.** Your message is delivered to the running agent in the existing execution. +* **The original sandbox has ended.** A new execution starts on the same run and rehydrates from the prior execution's workspace snapshot. This is the cloud-to-cloud handoff path. -Cloud-to-cloud handoff is the **requeued** path. The user-facing effect is the same — you submit a follow-up and the run continues — but the underlying mechanics differ because the new execution starts on a fresh sandbox. +The user-facing experience is the same — you submit a follow-up and the run continues — but the third case is where handoff happens. ## What the new execution receives -Each cloud agent run captures a snapshot of its workspace at the end of its execution and uploads it to a per-execution prefix in storage (`snapshots/{run_id}/{execution_id}/`). When a new execution starts on the same run, Oz discovers the prior execution's snapshot and rehydrates from it. +When a new execution starts on an existing run after the prior sandbox has ended, it inherits: -* **The same agent conversation** - The new execution writes to the same agent conversation id as the prior execution. From the user's perspective, the run is one continuous conversation across multiple sandboxes. -* **The prior workspace state** - The prior execution's repository diffs (tracked and untracked) and any orphan files declared in its `snapshot_state.json` manifest are downloaded into the new sandbox and applied via `git apply` before the agent answers the follow-up. -* **Stable run identity** - The run id, task id, and run metadata (creator, environment, schedule trigger, integration source) are preserved. Compute usage is recorded per execution but rolls up to the same run. +* **The same agent conversation** - The new execution writes to the same agent conversation as the prior execution. From your perspective, the run is one continuous conversation across multiple sandboxes. +* **The prior workspace state** - The prior execution's repository changes (tracked and untracked) are restored in the new sandbox before the agent answers your follow-up. +* **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per execution but rolls up to the same run. -The receiving agent's first turn applies the patches and reports any that failed. If a patch fails outright, the agent retries it with `git apply --3way` and only proceeds to the user's follow-up after every patch has been attempted. +If applying any change fails in the new sandbox, the agent reports what couldn't be applied and proceeds with what it could before continuing to your follow-up. ## Prerequisites -* **An ended cloud agent run** - The run must have a `succeeded`, `failed`, `error`, `blocked`, or `cancelled` state and an associated agent conversation id. Runs with no conversation id (rare; mostly legacy) cannot be continued via handoff. -* **A snapshot from the prior execution** - The agent driver uploads a snapshot at the end of every cloud agent run by default. If the prior execution didn't upload a snapshot (for example, the snapshot upload itself failed), the new execution still proceeds — it just starts without rehydrated workspace state. -* **Access to the run** - You must have permission to submit follow-ups for the run. For team runs, this is normally any member of the team. +* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, blocked, or canceled — and have an associated agent conversation. Very old runs that predate the agent conversation model can't be continued via handoff. +* **A snapshot from the prior execution** - Cloud agent runs capture a workspace snapshot at the end of each execution. If the prior execution couldn't capture one (for example, due to a transient storage error), the new execution still proceeds — it just starts without rehydrated workspace state. +* **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. -## Sending a follow-up that triggers cloud-to-cloud handoff +## Sending a follow-up -Cloud-to-cloud handoff is automatic. You don't choose between "send a follow-up" and "hand off" — you just send a follow-up, and Oz picks the routing. +Cloud-to-cloud handoff is automatic. You don't choose between "send a follow-up" and "hand off" — you send a follow-up, and the system handles the routing. ### From the Warp app -1. **Open the ended cloud run.** Navigate to the run in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or via the conversation panel. -2. **Send your follow-up.** Type the next message into the conversation's input bar and submit it. Oz routes the message and, if the sandbox has ended, creates a new execution on the same run. -3. **Watch the new execution.** A new execution appears in the run's history with its own start time. The conversation continues in the same thread, and the new sandbox's first tool calls are the rehydration patches. +1. **Open the ended cloud run.** Find it in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. +2. **Send your follow-up.** Type the next message into the conversation's input and submit it. +3. **Watch the new execution.** A new execution appears in the run's history with its own start time. The conversation continues in the same thread, and the new sandbox's first actions are the workspace rehydration. ### From the Oz web app -1. **Open the run at oz.warp.dev.** Click into the run from the **Runs** tab in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). +1. **Open the run.** In the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev), open the run from the **Runs** tab. 2. **Send the follow-up.** Use the in-page input to send your next message. The same routing rules apply. ### From an integration -When a Slack-triggered or Linear-triggered cloud run ends, the integration can post follow-up messages into the same run. The server treats those follow-ups identically to ones sent from the Warp app — if the sandbox is gone, a new execution starts and rehydrates from the prior snapshot. See [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces. +When a Slack-triggered or Linear-triggered cloud run ends, follow-ups posted from the integration are routed the same way. If the sandbox is gone, a new execution starts and rehydrates from the prior snapshot. See the [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces. ## Inspecting handoff executions -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows a single row per run, even when the run spans multiple executions. To inspect each execution: +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple executions. To inspect each execution: 1. **Open the run detail.** Click the run row to open the conversation transcript. -2. **Look at the execution timeline.** The run detail surfaces each execution separately. You can see which execution wrote each message and how long each execution ran. -3. **Check the rehydration tool calls.** The first tool calls in each requeued execution are the patch-apply commands. If any failed, the agent's report appears in that execution's transcript. +2. **Review the execution timeline.** The run detail surfaces each execution separately, including which execution wrote each message and how long each execution ran. +3. **Review the rehydration actions.** The first actions in each new execution are the workspace restore. If any change couldn't be applied, the agent's report appears in that execution's transcript. ## Troubleshooting **My follow-up didn't trigger a new execution — it just appended to the prompt.** -The original run hasn't started yet (state is still `queued` or `pending`). Oz appended your message to the prompt the new execution will pick up. This is the **appended** path, not handoff; the run hasn't ended yet so there's nothing to hand off from. +The original run hasn't started yet. Your message was added to the prompt the run will pick up when it starts. This isn't a handoff — the run hasn't ended yet, so there's nothing to hand off from. -**My follow-up injected into the live session instead of creating a new execution.** -The original sandbox is still reachable. Oz injected your message into the live shared session — the **injected** path. This is the cheapest routing and avoids spinning up a fresh sandbox. You don't need to do anything; the agent will handle the follow-up in the existing execution. +**My follow-up reached the live session instead of creating a new execution.** +The original sandbox is still alive. Your message was delivered to the running agent in the existing execution. This is the cheapest path and avoids starting a fresh sandbox; the agent handles the follow-up inline. -**The new execution started but no patches were applied.** -The prior execution didn't upload a snapshot. This is rare but possible — snapshot upload is best-effort and can fail (for example, on a transient storage error). The new execution still proceeds with the same agent conversation, so the agent has the full transcript context even without the workspace state. +**The new execution started but no workspace state was restored.** +The prior execution didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The new execution still proceeds with the same agent conversation, so the agent has the full transcript context even without the workspace state. -**The run is in a terminal state with no conversation id and follow-ups are rejected.** -Some very old runs predate the agent conversation model and cannot be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed. +**The run is in a terminal state with no conversation and follow-ups are rejected.** +Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed. ## Related pages -* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over. +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. -* [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/) - Take over a cloud run inside the Warp terminal. * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. -* [Oz API and SDK](/reference/api-and-sdk/) - Programmatic follow-up submission via `POST /agent/runs/{runId}/followups`. +* [Oz API and SDK](/reference/api-and-sdk/) - Submit follow-ups programmatically. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx deleted file mode 100644 index 5231044d..00000000 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Handoff from cloud to local -description: >- - Pick up a cloud agent run inside the Warp terminal to verify, iterate, or - polish changes before shipping — without losing the cloud agent's - conversation history. -sidebar: - label: "Cloud to local" ---- - -Hand off a cloud agent run to your local Warp terminal when you want to take over the work in person. The local session forks the cloud conversation in place, so you keep the full transcript, can ask follow-up questions, and can make manual edits inside the same flow the cloud agent was using. - -This direction is the right move when: - -* A cloud agent has done the heavy lifting and you want to verify the changes against your local checkout. -* You want to make manual tweaks before approving a PR. -* You want to ask follow-up questions to a cloud run interactively rather than waiting on another cloud round-trip. -* A teammate triggered a cloud run from Slack or a schedule and you want to push it further from your machine. - -## What the local conversation receives - -When you continue a cloud run locally, the Warp client materializes a fork of the cloud conversation and opens it as a new pane next to your current one. The fork inherits: - -* **The full transcript** - Every user turn, agent turn, and tool call from the cloud run is visible in the local conversation. -* **Conversation attachments** - Files attached during the cloud run remain available to reference locally. -* **The agent's plan and artifacts** - Any plan documents, branch artifacts, or pull request links the cloud agent produced are accessible from the local view. - -Continuing a cloud run locally creates a fork rather than modifying the source. The original cloud run stays intact; your local conversation diverges from it as soon as you send a new prompt or make a manual edit. This matches [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) behavior — the cloud run continues to live in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) and can be revisited later. - -:::note -Cloud-to-local handoff brings the cloud agent's conversation and artifacts into your terminal. It does not automatically apply the cloud agent's uncommitted workspace changes to your local checkout — review the agent's PR or branch artifact to inspect and pull in those changes. -::: - -## Prerequisites - -* **A cloud agent run to pick up** - The run can be in any state: still working, completed, failed, or canceled. The conversation must be cloud-synced (cloud agent runs are stored in the cloud by default). -* **Cloud conversation storage enabled** - **Settings** > **Privacy** > **Store AI conversations in the cloud** must be on. Cloud agent conversations are always synced regardless of this setting, but storage must be on for the local fork to write back. -* **Warp desktop app** - Cloud-to-local handoff continues the conversation inside the Warp app. From the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), the equivalent action is **Open in Warp**, which launches Warp and starts the local fork. - -## Continuing a cloud run locally - -There are three entry points to continue a cloud run locally, depending on where you are in the workflow. - -### From the conversation details panel - -Use this when you're already inspecting a cloud run inside the Warp app. - -1. **Open the cloud run.** In the conversation panel or the [management view](/agent-platform/cloud-agents/managing-cloud-agents/), click the run you want to continue. -2. **Open the conversation details panel.** Click the info button in the pane header to open the side panel that shows run metadata. -3. **Click Continue locally.** Warp forks the conversation and opens it in a split pane next to the cloud run. The new pane is the local conversation; the cloud run pane remains on its side for reference. - -### From the ended-run tombstone - -Use this when a cloud run has just finished and you want to take over without leaving the pane. - -1. **Wait for the cloud agent to finish.** When the run ends, an ended-run tombstone card appears at the bottom of the pane with the run's metadata and artifacts. -2. **Click Continue locally on the tombstone.** Warp forks the conversation into a split pane the same way the details panel does. - -### Via the `/continue-locally` slash command - -Use this when you want to continue a cloud conversation by name without first navigating to it. - -1. **Open the cloud conversation in the Warp terminal.** Run `/continue-locally` from inside the cloud conversation pane (or from a fresh pane if the conversation panel surfaces a recent run you want to pick up). -2. **Confirm the fork.** Warp creates the local fork in a split pane and focuses the input so you can immediately type your follow-up. - -## Continuing in your next turn - -After the local fork opens, you can interact with the agent the same way you would in any local Warp conversation. - -1. **Send a follow-up prompt.** Anything you type in the local pane is now a turn in the forked conversation. The cloud run is unaffected. -2. **Inspect the agent's workspace changes.** If the cloud agent produced a branch or PR artifact, the local conversation surfaces the same buttons (visible in the artifacts row). Click through to review the changes in your local checkout or in GitHub. -3. **Make manual edits if needed.** The local conversation is a regular Warp Agent conversation. You can edit files, run commands, or use any other Warp surface alongside the agent. - -## Troubleshooting - -**The Continue locally button doesn't appear.** -The button is hidden when AI features are disabled. Confirm in **Settings** > **AI** that AI is enabled and that you're signed in. The button is also hidden while a conversation is still in progress in a few states — wait for the agent to enter a stable state (working, completed, blocked, failed, or canceled) and the button should appear. - -**The local fork opens but doesn't show the full transcript.** -The conversation data may not have finished syncing yet. Cloud agent conversations stream their state in near-real-time, so this is usually a few-second delay. If the transcript still looks truncated after a minute, refresh the conversation panel. - -**I'm in the Oz web app on a mobile device — there's no Continue locally button.** -Continuing locally requires the Warp desktop app. On mobile or in a browser, you'll see **Open in Warp** instead. Clicking it deep-links into the desktop app and runs the same fork-and-open flow. - -## Related pages - -* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over. -* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - The reverse direction, for promoting a local conversation to a cloud run. -* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How cloud conversations are stored, shared, and restored locally. -* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find cloud runs to continue locally. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index a3b627fb..2320d5db 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -1,55 +1,48 @@ --- title: Handoff between local and cloud agents description: >- - Move an agent conversation between your terminal and the cloud, or between - cloud runs, without losing context. Three handoff directions, one continuous - unit of work. + Move an agent conversation between your terminal and the cloud without + re-explaining the task. Promote a local conversation to a cloud run, or + continue a finished cloud run with a fresh execution. sidebar: label: "Handoff overview" --- -Handoff lets you move a single unit of agent work between your local terminal and the cloud, or between two cloud runs, without re-explaining the task. You start where it's convenient, hand the work off when you need different compute or visibility, and pick it back up wherever the agent left off. +Handoff lets you move a unit of agent work between your local Warp terminal and the cloud, or between cloud executions, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. -## Three directions of handoff +## Directions of handoff -Each direction solves a different gap in the local + cloud workflow. +Two handoff directions are introduced with the Oz launch: -* **Local to cloud** - Start in the Warp terminal, then promote the conversation to a cloud agent run when you need more compute, longer-running execution, or to parallelize multiple variants. The cloud agent starts from your conversation history and your uncommitted workspace state. -* **Cloud to local** - Pick up a cloud run inside the Warp terminal to verify, iterate, or polish before shipping. Useful when a cloud agent has done the heavy lifting and you want to take over locally for the final mile. -* **Cloud to cloud** - Send a follow-up to a cloud run whose sandbox has already shut down. Oz creates a new execution on the same run and rehydrates the prior execution's workspace state so the agent continues the same task instead of starting fresh. +* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running execution, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). +* **Cloud to cloud** - Send a follow-up to a cloud run whose sandbox has already shut down. A new execution starts on the same run, reuses the same agent conversation, and rehydrates the prior execution's workspace state. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). -## What carries over - -Handoff is designed to preserve enough state that the receiving agent can resume the work, not just read about it. +A third direction — **cloud to local** — is already supported. Use **Continue locally** or `/continue-locally` to fork a cloud conversation into your local terminal. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). -* **Conversation history** - The receiving agent sees the full transcript of the prior session. For local-to-cloud, Oz materializes a server-side fork of the local conversation so the source isn't modified. For cloud-to-cloud, the same agent conversation id is reused across executions. -* **Workspace state** - Repository diffs (tracked and untracked changes) from the prior session are captured as patch files and applied in the receiving sandbox before the agent answers the next prompt. Local-to-cloud uploads patches from your local checkout; cloud-to-cloud reuses the snapshot the prior cloud execution wrote at the end of its run. -* **Snapshot manifest** - A `snapshot_state.json` manifest records the repo name, branch, and HEAD SHA at handoff time so the receiving agent can verify it's applying patches at the right checkout point. -* **Artifacts and attachments** - Files the prior session attached to the conversation remain available to the receiving agent. - -## How handoff works +## What carries over -The three directions share one mechanism: a workspace snapshot stored in Google Cloud Storage plus a forked or continued agent conversation. The receiving agent's first turn applies the patches via `git apply` and then addresses the user's follow-up. +Handoff preserves enough state that the receiving agent can resume the work, not just read about it. -* **Local to cloud** - The Warp client uploads workspace patches and a manifest to a token-scoped staging area (`handoff/{token}/`) and then creates a new cloud run that references both the token and a forked copy of the local conversation. The cloud sandbox downloads the snapshot, applies the patches, and starts the agent on a fresh execution. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). -* **Cloud to local** - The Warp client forks the cloud conversation locally and opens it in a split pane. You continue the conversation from the same point the cloud agent left off. See [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/). -* **Cloud to cloud** - Submitting a follow-up to an ended cloud run creates a new execution on the same run. The new execution discovers the prior execution's snapshot at `snapshots/{run_id}/{execution_id}/` and rehydrates from it. The run id, task id, and agent conversation id stay stable across executions. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). +* **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation server-side so the source isn't modified; cloud-to-cloud reuses the same agent conversation across executions. +* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving sandbox before the agent answers the next prompt. The cloud-to-local direction does not currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. +* **Conversation attachments** - Files attached during the prior session remain available to the receiving agent. ## When to use handoff Each direction has a clear motivating workflow. -* **Local to cloud** - Use when a local conversation has spiraled into work that's better done in the cloud. Common reasons include: needing to run a long-running task without tying up your laptop, parallelizing variants of the same task across cloud sandboxes, or steering work from a mobile device once it's running in the cloud. -* **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over for verification, manual review, or polish before shipping. Also useful for inspecting the agent's changes against your local checkout. -* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up — even though the sandbox shut down — without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further from the Warp terminal. +* **Local to cloud** - Use when a local conversation has spiraled into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, parallel variants of the same task, or steering work from another device once it's running. +* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further. +* **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping. ## Rehydration behavior -Handoff is best-effort. When patches apply cleanly, the receiving agent picks up the work exactly where the prior session left off. When they don't, the agent reports which patches failed and proceeds with what it could apply rather than starting over silently. The same rehydration prompt is used across all three directions so the agent's pre-turn checklist is consistent regardless of where the work originated. +Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could apply rather than starting over silently. ## Related pages * [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. +* [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. * [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. * [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index 1a113ee6..e0189a29 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -1,14 +1,14 @@ --- title: Handoff from local to cloud description: >- - Promote a local Warp Agent conversation to a cloud agent run when you need - more compute, longer-running execution, or parallel work — without - re-explaining the task. + Promote a local Warp Agent conversation to a cloud agent run with the full + transcript and your uncommitted workspace changes — without re-explaining + the task. sidebar: label: "Local to cloud" --- -Hand off a conversation from the Warp terminal to a cloud agent run when the work outgrows your local session. The cloud agent starts from a fork of your local conversation and a snapshot of your uncommitted workspace state, so it picks up where you left off instead of starting fresh. +Hand off a conversation from the Warp terminal to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh. This direction is the right move when: @@ -19,56 +19,59 @@ This direction is the right move when: ## What the cloud agent receives -When you hand off from local to cloud, Oz transfers three things to the receiving agent: +When you hand off from local to cloud, the receiving cloud agent inherits: -* **A forked conversation** - Oz creates a server-side fork of your local conversation so the cloud agent inherits the full transcript without modifying the source. The fork is owned by you, not by the original conversation's owner. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related conversation-sync behavior. -* **A workspace snapshot** - Warp captures `git diff --binary HEAD` for every repo in your working directory (tracked and untracked changes), packages it as a set of `.patch` files plus a `snapshot_state.json` manifest, and uploads them to a token-scoped staging area. The cloud sandbox downloads and applies the patches before the agent answers your next prompt. +* **A forked conversation** - Warp creates a server-side fork of your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. +* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud sandbox. The cloud agent applies them in its sandbox before answering your follow-up. * **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. -The receiving agent sees an explicit pre-turn checklist that tells it to read the manifest, apply each patch via `git apply`, and confirm the affected files are dirty before answering your follow-up. If a patch fails to apply, the agent retries with `git apply --3way` and then reports any unrecoverable failures rather than silently dropping changes. +If applying any change fails in the cloud sandbox, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. ## Prerequisites * **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. -* **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repository (or repositories) you're working in locally. The environment's repos must match the local checkout so the workspace patches apply cleanly. -* **Cloud conversation storage enabled** - Cloud conversation storage must be on (**Settings** > **Privacy** > **Store AI conversations in the cloud**) so the conversation can be forked server-side. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). +* **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. +* **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked server-side. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). * **Sufficient credits** - Cloud agent runs consume credits. See [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) for credit requirements. ## Handing off a conversation to the cloud The handoff entry point is integrated into the cloud agent launch flow, so the same UI that starts a fresh cloud run can also continue an existing local conversation. -1. **In the active conversation, open the cloud agent launch flow.** In the Warp terminal with the local conversation focused, run the `/cloud-agent` slash command (or press `⌘+Option+Enter` on macOS / `Ctrl+Alt+Enter` on Windows/Linux). When invoked from inside an active conversation, the cloud agent setup view offers to continue the current conversation rather than starting a new one. -2. **Choose the environment for the cloud run.** Pick the environment whose repos match the directories your local conversation has been editing. If you don't have a matching environment yet, run `/create-environment` first and add the repos you've been working in. -3. **Confirm the handoff and add a follow-up prompt.** Enter the next message you want the cloud agent to act on. This becomes the first user-facing message in the cloud run; the rehydration checklist runs invisibly before it. -4. **Submit the run.** Warp captures the workspace snapshot from your current working directory, uploads it to a token-scoped staging area, and creates the cloud run with both the snapshot token and a fork of the local conversation. You see the new cloud run appear in the conversation panel and in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +1. **Open the cloud agent launch flow from your active conversation.** In the Warp terminal with the local conversation focused, start a cloud agent the same way you would for a fresh run — for example, with the `/cloud-agent` slash command. When invoked from inside an active conversation, the launch flow offers to continue the current conversation rather than starting a new one. +2. **Choose the environment for the cloud run.** Pick the environment whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one first and add the repos you've been working in. +3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. This becomes the first user-facing message in the cloud run. -After submission, the cloud agent's first turn applies the patches and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. +After submission, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. + +:::note +The exact entry point may evolve during the Oz launch rollout. If the steps above don't match what you see, check the cloud agent launch flow's in-app guidance for the current handoff affordance. +::: ## Verifying the handoff Confirm the handoff is doing what you expect by inspecting the cloud run. 1. **Open the cloud run.** Click the new run in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. -2. **Check the agent's first turn.** The first tool calls should be `cat snapshot_state.json` followed by one or more `git apply` invocations. If `git apply` fails for any patch, the agent reports the failure inline before continuing. -3. **Confirm the workspace is dirty.** The agent runs `git status` in each affected repo after applying patches; the output should show the same files you had modified locally. +2. **Check the cloud agent's first actions.** Before answering your follow-up, the agent applies the workspace snapshot. You can see those actions at the top of the cloud run's transcript. +3. **Confirm the workspace is dirty.** The agent reports the modified files after applying changes; the list should match what you had modified locally. -If the snapshot doesn't appear to land, the cloud agent still proceeds with the forked conversation and the agent's history — it just won't have your uncommitted changes. The conversation panel's run detail surfaces the snapshot files so you can confirm what was uploaded. +If the snapshot doesn't appear to land, the cloud run still proceeds with the forked conversation and full transcript — it just won't have your uncommitted changes. ## Troubleshooting -**The cloud agent reports `git apply` failures.** -The most common cause is a repository mismatch between your local checkout and the environment. The patches are generated against the HEAD of your local repo; the environment must check out a compatible base for `git apply` to succeed. If the agent reports a 3-way merge failure, switch the environment's repo to the same branch you were on locally and re-run the handoff. +**The cloud agent reports that some changes couldn't be applied.** +The most common cause is a repository mismatch between your local checkout and the environment. Your workspace snapshot is generated against your local repo's `HEAD`; the environment must check out a compatible base for the changes to apply cleanly. Switch the environment's repo to the same branch you were on locally and retry the handoff. **The cloud agent doesn't see my uncommitted changes.** -Cloud conversation storage must be enabled for handoff to work. Open **Settings** > **Privacy** in the Warp app and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked server-side and the run falls back to starting fresh. +Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked server-side and the run falls back to starting fresh. **The conversation doesn't appear in the cloud run.** -The source conversation may not have finished syncing to the cloud when you triggered the handoff. Warp returns a transient error in this case — wait a moment and retry the handoff. If it persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. +The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. ## Related pages -* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over. -* [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/) - The reverse direction, for taking over a cloud run locally. -* [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands that the cloud agent starts in. -* [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. +* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with a fresh execution. +* [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. +* [Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. From 91cd3da62cbbd7556616f80fb3c0c7ec1afed99a Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 14:48:35 -0700 Subject: [PATCH 03/12] docs(handoff): second editor pass to drop residual internal jargon - Replace 'execution' with 'session' across cloud-to-cloud.mdx so the user-facing unit of work stays 'the run', not the internal model. - Drop 'rehydrate'/'rehydration' in favor of 'restore'/'carry over'; fold the standalone 'Rehydration behavior' section into 'What carries over' in the overview. - Drop the 'server-side' qualifier on 'fork' throughout; users don't care where the fork happens. - Collapse the cloud-to-cloud 'How follow-ups route' state-machine into a single user-facing description; remove the two routing-paths items from troubleshooting since they describe normal behavior, not problems. - Collapse local-to-cloud's 'Verifying the handoff' debugging walkthrough into one sentence pointing readers to the management view. - Cut meta self-descriptions: 'The handoff entry point is integrated into the cloud agent launch flow...' and 'Cloud-to-cloud handoff is automatic...'. - Drop the rollout caveat note on local-to-cloud. - Reduce 'sandbox' references where they leak infrastructure. Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 61 +++++++------------ .../cloud-agents/handoff/index.mdx | 18 +++--- .../cloud-agents/handoff/local-to-cloud.mdx | 36 ++++------- 3 files changed, 40 insertions(+), 75 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 46c24e04..456a8510 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -1,83 +1,64 @@ --- title: Handoff from cloud to cloud description: >- - Send a follow-up to a cloud run whose sandbox has shut down. A new execution - starts on the same run with the prior execution's workspace state restored. + Send a follow-up to a finished cloud run. The run continues with the prior + workspace state restored, so the agent picks up where it left off. sidebar: label: "Cloud to cloud" --- -Hand off a cloud agent run to a fresh cloud execution when the original sandbox has shut down but you still want to push the same unit of work further. A new execution starts on the same run, reuses the same agent conversation, and rehydrates the prior execution's workspace state — so the new agent picks up where the old one left off, not from scratch. +Hand off a cloud agent run to a fresh cloud session when the original session has ended but you still want to push the same unit of work further. The run continues in the same conversation, with the prior session's workspace state restored, so the agent picks up where it left off instead of starting fresh. This direction is the right move when: -* A cloud agent finished and you want to send a follow-up after the sandbox has already torn down. +* A cloud agent finished and you want to send a follow-up after the session has ended. * A scheduled or integration-triggered run completed and you want to keep iterating without losing context. -* You want to continue an ambient agent task across multiple executions while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +* You want to continue an ambient agent task while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). -## How follow-ups route +## What carries over -When you submit a follow-up to a cloud run, the routing depends on the run's current state: +When you send a follow-up to a run whose session has ended, the run continues with: -* **The run is still queued and hasn't started.** Your message is added to the prompt the run will pick up when it starts. -* **The original sandbox is still alive.** Your message is delivered to the running agent in the existing execution. -* **The original sandbox has ended.** A new execution starts on the same run and rehydrates from the prior execution's workspace snapshot. This is the cloud-to-cloud handoff path. +* **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. +* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. +* **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. -The user-facing experience is the same — you submit a follow-up and the run continues — but the third case is where handoff happens. - -## What the new execution receives - -When a new execution starts on an existing run after the prior sandbox has ended, it inherits: - -* **The same agent conversation** - The new execution writes to the same agent conversation as the prior execution. From your perspective, the run is one continuous conversation across multiple sandboxes. -* **The prior workspace state** - The prior execution's repository changes (tracked and untracked) are restored in the new sandbox before the agent answers your follow-up. -* **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per execution but rolls up to the same run. - -If applying any change fails in the new sandbox, the agent reports what couldn't be applied and proceeds with what it could before continuing to your follow-up. +If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could before continuing to your follow-up. ## Prerequisites * **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, blocked, or canceled — and have an associated agent conversation. Very old runs that predate the agent conversation model can't be continued via handoff. -* **A snapshot from the prior execution** - Cloud agent runs capture a workspace snapshot at the end of each execution. If the prior execution couldn't capture one (for example, due to a transient storage error), the new execution still proceeds — it just starts without rehydrated workspace state. +* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues — it just starts without restored workspace state. * **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. ## Sending a follow-up -Cloud-to-cloud handoff is automatic. You don't choose between "send a follow-up" and "hand off" — you send a follow-up, and the system handles the routing. +You don't take a separate "hand off" action — you send a follow-up, and the run continues. The handoff happens automatically when the original session has ended. ### From the Warp app 1. **Open the ended cloud run.** Find it in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. 2. **Send your follow-up.** Type the next message into the conversation's input and submit it. -3. **Watch the new execution.** A new execution appears in the run's history with its own start time. The conversation continues in the same thread, and the new sandbox's first actions are the workspace rehydration. + +The run picks up where it left off, with workspace state restored. ### From the Oz web app 1. **Open the run.** In the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev), open the run from the **Runs** tab. -2. **Send the follow-up.** Use the in-page input to send your next message. The same routing rules apply. +2. **Send the follow-up.** Use the in-page input to send your next message. ### From an integration -When a Slack-triggered or Linear-triggered cloud run ends, follow-ups posted from the integration are routed the same way. If the sandbox is gone, a new execution starts and rehydrates from the prior snapshot. See the [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces. - -## Inspecting handoff executions +When a Slack-triggered or Linear-triggered cloud run ends, follow-ups posted from the integration trigger the same handoff. See the [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces. -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple executions. To inspect each execution: +## Inspecting a run that's been handed off -1. **Open the run detail.** Click the run row to open the conversation transcript. -2. **Review the execution timeline.** The run detail surfaces each execution separately, including which execution wrote each message and how long each execution ran. -3. **Review the rehydration actions.** The first actions in each new execution are the workspace restore. If any change couldn't be applied, the agent's report appears in that execution's transcript. +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript and a timeline of each session, including which session wrote each message and how long each one ran. ## Troubleshooting -**My follow-up didn't trigger a new execution — it just appended to the prompt.** -The original run hasn't started yet. Your message was added to the prompt the run will pick up when it starts. This isn't a handoff — the run hasn't ended yet, so there's nothing to hand off from. - -**My follow-up reached the live session instead of creating a new execution.** -The original sandbox is still alive. Your message was delivered to the running agent in the existing execution. This is the cheapest path and avoids starting a fresh sandbox; the agent handles the follow-up inline. - -**The new execution started but no workspace state was restored.** -The prior execution didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The new execution still proceeds with the same agent conversation, so the agent has the full transcript context even without the workspace state. +**The run continued but no workspace state was restored.** +The prior session didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state. **The run is in a terminal state with no conversation and follow-ups are rejected.** Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index 2320d5db..760fe85a 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -3,19 +3,19 @@ title: Handoff between local and cloud agents description: >- Move an agent conversation between your terminal and the cloud without re-explaining the task. Promote a local conversation to a cloud run, or - continue a finished cloud run with a fresh execution. + continue a finished cloud run with workspace state restored. sidebar: label: "Handoff overview" --- -Handoff lets you move a unit of agent work between your local Warp terminal and the cloud, or between cloud executions, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. +Handoff lets you move a unit of agent work between your local Warp terminal and the cloud, or continue a finished cloud run, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. ## Directions of handoff Two handoff directions are introduced with the Oz launch: -* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running execution, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). -* **Cloud to cloud** - Send a follow-up to a cloud run whose sandbox has already shut down. A new execution starts on the same run, reuses the same agent conversation, and rehydrates the prior execution's workspace state. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). +* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). +* **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). A third direction — **cloud to local** — is already supported. Use **Continue locally** or `/continue-locally` to fork a cloud conversation into your local terminal. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). @@ -23,10 +23,12 @@ A third direction — **cloud to local** — is already supported. Use **Continu Handoff preserves enough state that the receiving agent can resume the work, not just read about it. -* **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation server-side so the source isn't modified; cloud-to-cloud reuses the same agent conversation across executions. -* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving sandbox before the agent answers the next prompt. The cloud-to-local direction does not currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. +* **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn't modified; cloud-to-cloud continues in the same conversation. +* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction does not currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. * **Conversation attachments** - Files attached during the prior session remain available to the receiving agent. +Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could rather than starting over silently. + ## When to use handoff Each direction has a clear motivating workflow. @@ -35,10 +37,6 @@ Each direction has a clear motivating workflow. * **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further. * **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping. -## Rehydration behavior - -Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could apply rather than starting over silently. - ## Related pages * [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index e0189a29..e5680d44 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -13,7 +13,7 @@ Hand off a conversation from the Warp terminal to a cloud agent run when the wor This direction is the right move when: * The task is going to run for a long time and you don't want to keep your laptop awake. -* You want to fan out variants of the same task across multiple cloud sandboxes in parallel. +* You want to fan out variants of the same task across multiple cloud agents in parallel. * You want to walk away and check on the agent from a different device. * You want the agent to keep working while you start a new conversation locally. @@ -21,50 +21,36 @@ This direction is the right move when: When you hand off from local to cloud, the receiving cloud agent inherits: -* **A forked conversation** - Warp creates a server-side fork of your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. -* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud sandbox. The cloud agent applies them in its sandbox before answering your follow-up. +* **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. +* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. * **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. -If applying any change fails in the cloud sandbox, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. +If applying any change fails in the cloud run, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. ## Prerequisites * **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. * **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. -* **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked server-side. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). +* **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). * **Sufficient credits** - Cloud agent runs consume credits. See [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) for credit requirements. ## Handing off a conversation to the cloud -The handoff entry point is integrated into the cloud agent launch flow, so the same UI that starts a fresh cloud run can also continue an existing local conversation. - -1. **Open the cloud agent launch flow from your active conversation.** In the Warp terminal with the local conversation focused, start a cloud agent the same way you would for a fresh run — for example, with the `/cloud-agent` slash command. When invoked from inside an active conversation, the launch flow offers to continue the current conversation rather than starting a new one. +1. **Open the cloud agent launch flow from your active conversation.** In the Warp terminal with the local conversation focused, start a cloud agent with the `/cloud-agent` slash command. When invoked from inside an active conversation, the launch flow offers to continue the current conversation rather than starting a new one. 2. **Choose the environment for the cloud run.** Pick the environment whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one first and add the repos you've been working in. -3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. This becomes the first user-facing message in the cloud run. +3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. After submission, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. -:::note -The exact entry point may evolve during the Oz launch rollout. If the steps above don't match what you see, check the cloud agent launch flow's in-app guidance for the current handoff affordance. -::: - -## Verifying the handoff - -Confirm the handoff is doing what you expect by inspecting the cloud run. - -1. **Open the cloud run.** Click the new run in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. -2. **Check the cloud agent's first actions.** Before answering your follow-up, the agent applies the workspace snapshot. You can see those actions at the top of the cloud run's transcript. -3. **Confirm the workspace is dirty.** The agent reports the modified files after applying changes; the list should match what you had modified locally. - -If the snapshot doesn't appear to land, the cloud run still proceeds with the forked conversation and full transcript — it just won't have your uncommitted changes. +To check on the new run, open it from the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or the conversation panel. ## Troubleshooting **The cloud agent reports that some changes couldn't be applied.** -The most common cause is a repository mismatch between your local checkout and the environment. Your workspace snapshot is generated against your local repo's `HEAD`; the environment must check out a compatible base for the changes to apply cleanly. Switch the environment's repo to the same branch you were on locally and retry the handoff. +The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo's current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment's repo to the branch you were on locally and retry the handoff. **The cloud agent doesn't see my uncommitted changes.** -Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked server-side and the run falls back to starting fresh. +Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked and the run falls back to starting fresh. **The conversation doesn't appear in the cloud run.** The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. @@ -72,6 +58,6 @@ The source conversation may not have finished syncing to the cloud when you trig ## Related pages * [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. -* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with a fresh execution. +* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored. * [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. * [Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. From 89ba1a22f9757365c6c93b78762688aadbbfd32f Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 16:14:44 -0700 Subject: [PATCH 04/12] docs(handoff): trim overview description to fit 50-160 char range Co-Authored-By: Oz --- .../docs/agent-platform/cloud-agents/handoff/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index 760fe85a..c631092d 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -1,9 +1,9 @@ --- title: Handoff between local and cloud agents description: >- - Move an agent conversation between your terminal and the cloud without - re-explaining the task. Promote a local conversation to a cloud run, or - continue a finished cloud run with workspace state restored. + Move an agent conversation between your terminal and the cloud, or continue + a finished cloud run with workspace state restored, without re-explaining + the task. sidebar: label: "Handoff overview" --- From e6bfba8bcab4e03a7e6aac16278c0bf0599671c7 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 16:30:48 -0700 Subject: [PATCH 05/12] docs(handoff): address audit findings - cloud-to-cloud.mdx: soften per-session timeline claim to API-only (UI render not present) - cloud-to-cloud.mdx: gloss 'ambient agent task' inline for clarity - local-to-cloud.mdx: switch primary credits link to credits page; fix link text casing for access page Co-Authored-By: Oz --- .../agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx | 4 ++-- .../agent-platform/cloud-agents/handoff/local-to-cloud.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 456a8510..40d458fb 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -13,7 +13,7 @@ This direction is the right move when: * A cloud agent finished and you want to send a follow-up after the session has ended. * A scheduled or integration-triggered run completed and you want to keep iterating without losing context. -* You want to continue an ambient agent task while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +* You want to continue an ambient agent run — an agent that runs in the background, such as a scheduled or integration-triggered run — while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). ## What carries over @@ -53,7 +53,7 @@ When a Slack-triggered or Linear-triggered cloud run ends, follow-ups posted fro ## Inspecting a run that's been handed off -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript and a timeline of each session, including which session wrote each message and how long each one ran. +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript; each execution is recorded as part of the run's history, and you can see when each execution started and ended via the API. ## Troubleshooting diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index e5680d44..e1542a11 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -32,7 +32,7 @@ If applying any change fails in the cloud run, the cloud agent reports what coul * **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. * **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. * **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). -* **Sufficient credits** - Cloud agent runs consume credits. See [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) for credit requirements. +* **Sufficient credits** - Cloud agent runs consume credits. See [Credits](/support-and-community/plans-and-billing/credits/) for how credit usage works, and [Access, billing, and identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for team-specific credit requirements. ## Handing off a conversation to the cloud From e4bdd4b9b6df3209c3c474518a3520c15ae45724 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sun, 17 May 2026 16:59:24 -0700 Subject: [PATCH 06/12] docs(handoff): address Safia's review feedback - index.mdx: drop launch-anchored framing; reframe Directions list as evergreen capability statement; add third-party-harness coverage subsection (cloud<->cloud works on 3P with Continue+input prompt; local->cloud is Warp Agent only). - local-to-cloud.mdx: replace /cloud-agent entry-point claim with the '&' shortcut and the '/handoff' slash command; add note that the model can't be changed during handoff. - cloud-to-cloud.mdx: consolidate duplicate scheduled/integration bullets; add 'same Git branch' detail to workspace-state carryover; add :::caution that handoff requires a prior-execution snapshot; note that local->cloud-originated runs can only be continued by the creating user; scope send-follow-up to the Warp app and drop the Oz-web-app/integration follow-up sections; add third-party harness Continue-button flow; soften per-execution timeline claim (transcript is the source of truth, not the API). Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 25 ++++++++----------- .../cloud-agents/handoff/index.mdx | 10 ++++++-- .../cloud-agents/handoff/local-to-cloud.mdx | 6 ++++- 3 files changed, 23 insertions(+), 18 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 40d458fb..3bb02061 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -12,7 +12,6 @@ Hand off a cloud agent run to a fresh cloud session when the original session ha This direction is the right move when: * A cloud agent finished and you want to send a follow-up after the session has ended. -* A scheduled or integration-triggered run completed and you want to keep iterating without losing context. * You want to continue an ambient agent run — an agent that runs in the background, such as a scheduled or integration-triggered run — while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). ## What carries over @@ -20,7 +19,7 @@ This direction is the right move when: When you send a follow-up to a run whose session has ended, the run continues with: * **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. -* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. +* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new execution runs on the same Git branch as the prior session. * **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could before continuing to your follow-up. @@ -29,31 +28,28 @@ If applying any change fails, the agent reports what couldn't be applied and pro * **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, blocked, or canceled — and have an associated agent conversation. Very old runs that predate the agent conversation model can't be continued via handoff. * **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues — it just starts without restored workspace state. -* **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. +* **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. -## Sending a follow-up +:::caution +Cloud-to-cloud handoff relies on a snapshot from the prior execution. Older cloud runs that don't have a snapshot on file can't be handed off; start a new run instead. +::: -You don't take a separate "hand off" action — you send a follow-up, and the run continues. The handoff happens automatically when the original session has ended. +## Sending a follow-up -### From the Warp app +You don't take a separate "hand off" action — you send a follow-up, and the run continues. The handoff happens automatically when the original session has ended. Send-follow-up support is available in the Warp app. 1. **Open the ended cloud run.** Find it in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. 2. **Send your follow-up.** Type the next message into the conversation's input and submit it. The run picks up where it left off, with workspace state restored. -### From the Oz web app - -1. **Open the run.** In the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev), open the run from the **Runs** tab. -2. **Send the follow-up.** Use the in-page input to send your next message. - -### From an integration +### Third-party harnesses -When a Slack-triggered or Linear-triggered cloud run ends, follow-ups posted from the integration trigger the same handoff. See the [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces. +Cloud-to-cloud handoff works for third-party harnesses too, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the end-of-run tombstone) and enter the next message you want the agent to act on. ## Inspecting a run that's been handed off -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript; each execution is recorded as part of the run's history, and you can see when each execution started and ended via the API. +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API; the transcript is the source of truth. ## Troubleshooting @@ -68,4 +64,3 @@ Very old runs predate the agent conversation model and can't be continued via ha * [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. -* [Oz API and SDK](/reference/api-and-sdk/) - Submit follow-ups programmatically. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index c631092d..475ecd89 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -12,12 +12,18 @@ Handoff lets you move a unit of agent work between your local Warp terminal and ## Directions of handoff -Two handoff directions are introduced with the Oz launch: +Handoff supports three directions: * **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). * **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). +* **Cloud to local** - Fork a cloud conversation into your local terminal with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). -A third direction — **cloud to local** — is already supported. Use **Continue locally** or `/continue-locally` to fork a cloud conversation into your local terminal. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). +### Third-party harness coverage + +Handoff coverage depends on which agent is running the conversation: + +* **Cloud to cloud** works for both the Warp Agent and third-party harnesses. On third-party harnesses, the affordance is a **Continue** button followed by an input prompt, instead of the streamlined follow-up flow you get with the Warp Agent. +* **Local to cloud** works for the Warp Agent. It isn't available for third-party harnesses. ## What carries over diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index e1542a11..a7b573d3 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -36,10 +36,14 @@ If applying any change fails in the cloud run, the cloud agent reports what coul ## Handing off a conversation to the cloud -1. **Open the cloud agent launch flow from your active conversation.** In the Warp terminal with the local conversation focused, start a cloud agent with the `/cloud-agent` slash command. When invoked from inside an active conversation, the launch flow offers to continue the current conversation rather than starting a new one. +1. **Open the handoff flow from your active conversation.** With the local conversation focused, trigger handoff with the `&` shortcut or the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn't an entry point for handoff. 2. **Choose the environment for the cloud run.** Pick the environment whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one first and add the repos you've been working in. 3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. +:::note +The cloud agent runs with the same model your local conversation was using. Changing the model during handoff isn't supported. +::: + After submission, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. To check on the new run, open it from the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or the conversation panel. From f2a224c4ef49eccbf31078a48729420ea9aa77b0 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 23:40:37 -0400 Subject: [PATCH 07/12] Update src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> --- .../agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 3bb02061..a356f0bb 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -44,9 +44,9 @@ You don't take a separate "hand off" action — you send a follow-up, and the ru The run picks up where it left off, with workspace state restored. ### Third-party harnesses +### Third-party agent runtimes -Cloud-to-cloud handoff works for third-party harnesses too, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the end-of-run tombstone) and enter the next message you want the agent to act on. - +Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the end-of-run tombstone) and enter the next message you want the agent to act on. ## Inspecting a run that's been handed off The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API; the transcript is the source of truth. From b45a4e88d8b8cea64837bc68c95900e189e9f25d Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 03:48:08 +0000 Subject: [PATCH 08/12] docs(handoff): apply Rachael's review suggestions and final copy polish Apply all 9 of @rachaelrenk's suggested edits on PR #85 and run a final senior-copywriter pass for consistency across the three handoff pages. index.mdx - Intro: "your local Warp terminal" -> "a local Warp session" so the intro talks about a session rather than the terminal application. - "Third-party harness coverage" -> "Third-party agent runtime coverage"; same swap in the two bullets underneath. "Harness" is internal vocabulary; "agent runtime" is the user-facing term. - "spiraled into work" -> "grown into work" (less idiomatic). - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages to match the sentence-case nav style used elsewhere. - Consistency polish: "Fork a cloud conversation into your local terminal" -> "into a local Warp session" so the cloud-to-local bullet uses the same terminology as the rewritten intro. local-to-cloud.mdx - Intro: "Hand off a conversation from the Warp terminal" -> "Hand off a local Warp conversation" (same reason as above). - "This direction is the right move when:" -> "Use this handoff direction when:" (less conversational, matches docs voice). - Post-handoff pointer: linked the management view doc -> deep-linked the [Runs page](https://oz.warp.dev/runs) in the Oz web app, which matches the pattern added in PR #84. - "Cloud Agents quickstart" -> "Cloud agents quickstart" (sentence case). cloud-to-cloud.mdx (consistency polish, same patterns Rachael called out in the other two pages) - "This direction is the right move when:" -> "Use this handoff direction when:". - Step 1 of "Sending a follow-up": linked the management view doc -> deep-linked the Runs page in the Oz web app. - Removed a stray duplicate `### Third-party harnesses` heading that was sitting directly above the correct `### Third-party agent runtimes` heading, and inserted a missing blank line before the next `## Inspecting a run that's been handed off` section. - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 8 ++++---- .../agent-platform/cloud-agents/handoff/index.mdx | 14 +++++++------- .../cloud-agents/handoff/local-to-cloud.mdx | 8 ++++---- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index a356f0bb..184de3e0 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -9,7 +9,7 @@ sidebar: Hand off a cloud agent run to a fresh cloud session when the original session has ended but you still want to push the same unit of work further. The run continues in the same conversation, with the prior session's workspace state restored, so the agent picks up where it left off instead of starting fresh. -This direction is the right move when: +Use this handoff direction when: * A cloud agent finished and you want to send a follow-up after the session has ended. * You want to continue an ambient agent run — an agent that runs in the background, such as a scheduled or integration-triggered run — while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). @@ -38,15 +38,15 @@ Cloud-to-cloud handoff relies on a snapshot from the prior execution. Older clou You don't take a separate "hand off" action — you send a follow-up, and the run continues. The handoff happens automatically when the original session has ended. Send-follow-up support is available in the Warp app. -1. **Open the ended cloud run.** Find it in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel. +1. **Open the ended cloud run.** Find it on the [Runs page](https://oz.warp.dev/runs) in the Oz web app or in the conversation panel. 2. **Send your follow-up.** Type the next message into the conversation's input and submit it. The run picks up where it left off, with workspace state restored. -### Third-party harnesses ### Third-party agent runtimes Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the end-of-run tombstone) and enter the next message you want the agent to act on. + ## Inspecting a run that's been handed off The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API; the transcript is the source of truth. @@ -63,4 +63,4 @@ Very old runs predate the agent conversation model and can't be continued via ha * [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. -* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index 475ecd89..f34e9d9f 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -8,7 +8,7 @@ sidebar: label: "Handoff overview" --- -Handoff lets you move a unit of agent work between your local Warp terminal and the cloud, or continue a finished cloud run, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. +Handoff lets you move a unit of agent work between a local Warp session and the cloud, or continue a finished cloud run, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. ## Directions of handoff @@ -16,14 +16,14 @@ Handoff supports three directions: * **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). * **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). -* **Cloud to local** - Fork a cloud conversation into your local terminal with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). +* **Cloud to local** - Fork a cloud conversation into a local Warp session with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). -### Third-party harness coverage +### Third-party agent runtime coverage Handoff coverage depends on which agent is running the conversation: -* **Cloud to cloud** works for both the Warp Agent and third-party harnesses. On third-party harnesses, the affordance is a **Continue** button followed by an input prompt, instead of the streamlined follow-up flow you get with the Warp Agent. -* **Local to cloud** works for the Warp Agent. It isn't available for third-party harnesses. +* **Cloud to cloud** works for both the Warp Agent and supported third-party agent runtimes. For supported third-party agent runtimes, the affordance is a **Continue** button followed by an input prompt, instead of the streamlined follow-up flow you get with the Warp Agent. +* **Local to cloud** works for the Warp Agent. It isn't available for supported third-party agent runtimes. ## What carries over @@ -39,14 +39,14 @@ Handoff is best-effort. When the receiving agent can apply the prior session's c Each direction has a clear motivating workflow. -* **Local to cloud** - Use when a local conversation has spiraled into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, parallel variants of the same task, or steering work from another device once it's running. +* **Local to cloud** - Use when a local conversation has grown into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, parallel variants of the same task, or steering work from another device once it's running. * **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further. * **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping. ## Related pages * [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. -* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. * [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. * [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. * [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index a7b573d3..f304e8d0 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -8,9 +8,9 @@ sidebar: label: "Local to cloud" --- -Hand off a conversation from the Warp terminal to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh. +Hand off a local Warp conversation to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh. -This direction is the right move when: +Use this handoff direction when: * The task is going to run for a long time and you don't want to keep your laptop awake. * You want to fan out variants of the same task across multiple cloud agents in parallel. @@ -46,7 +46,7 @@ The cloud agent runs with the same model your local conversation was using. Chan After submission, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. -To check on the new run, open it from the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or the conversation panel. +To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) in the Oz web app or the conversation panel. ## Troubleshooting @@ -64,4 +64,4 @@ The source conversation may not have finished syncing to the cloud when you trig * [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored. * [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. -* [Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. +* [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. From fed3817c4c86d7e9ae61a26cb4e541add5dc27b3 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 04:00:45 +0000 Subject: [PATCH 09/12] docs(handoff): second copy polish pass on handoff pages A senior-copywriter follow-up on commit b45a4e8. Focuses on terminology consistency, list parallelism, active voice, and a few style-guide nits caught on the second read. index.mdx - Frontmatter description: "Move an agent conversation between your terminal and the cloud" -> "Move agent work between a local Warp session and the cloud" so the description matches the body intro (which Rachael's review moved to "local Warp session" terminology). - "Directions of handoff" Local-to-cloud bullet: "more compute, longer-running work, or to fan out variants in parallel" -> "more compute, longer-running work, or parallel variants of the same task". Now all three list items are parallel noun phrases. - "Workspace state" bullet: "The cloud-to-local direction does not currently apply" -> "doesn't currently apply" (contractions are encouraged in the style guide for an approachable tone). local-to-cloud.mdx - "Use this handoff direction when:" list: first bullet started with "The task is going to run for a long time..." while the other three start with "You want...". Rewrote it to "You have a long-running task and don't want to keep your laptop awake." so all four bullets open the same way. - Step 1: "trigger handoff with the `&` shortcut or the `/handoff` slash command" -> "press `&` or run the `/handoff` slash command". Direct verbs match the style guide pattern for keyboard / slash commands. - Step 2: "Pick the environment whose..." -> "Pick the one whose..." (avoids repeating "environment" right after the bold header). "create one first and add" -> "create one and add" ("first" was doing no work). - Post-steps prose: "After submission, the cloud agent applies your workspace snapshot" -> "After you submit, the cloud agent...". Active voice; readers don't talk about "submission." - Troubleshooting (uncommitted changes): "Without it, the conversation can't be forked" -> "Otherwise, the conversation can't be forked". "Without it" had a fuzzy antecedent; "Otherwise" reads cleanly off the preceding sentence. cloud-to-cloud.mdx - "Use this handoff direction when:" list: first bullet "A cloud agent finished and you want to send a follow-up after the session has ended." -> "You want to send a follow-up to a cloud agent after its session has ended." Now parallel with the second bullet ("You want to continue an ambient agent run..."). - Cleaned up three lingering uses of "execution" that the earlier internals scrub missed. All three were re-introduced when applying Safia's audit-fix feedback in e4bdd4b. Replaced with "session": - "the new execution runs on the same Git branch as the prior session" -> "the new session continues on the same Git branch" (avoids both the internal term and the "new ... prior" cycle). - ":::caution Cloud-to-cloud handoff relies on a snapshot from the prior execution" -> "...the prior session". - "Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API..." -> all three "execution"s -> "session" / "Per-session". - "What carries over" trailing sentence: "...proceeds with what it could before continuing to your follow-up." -> "...rather than starting over silently." Now parallel with the same sentence on the other two handoff pages. - "Sending a follow-up" lead-in: dropped the orphan third sentence ("Send-follow-up support is available in the Warp app.") and folded it into the first: "you send a follow-up from the Warp app, and the run continues." - Step 2: "Type the next message into the conversation's input" -> "Enter the next message in the conversation's input" ("Enter" is the style guide's verb for text fields). - Troubleshooting (old runs): "Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed." -> "Start a new cloud agent run with the prompt you want, referencing the prior run if needed." (drops the "prompt" repetition). Final grep over the handoff folder for "execution", "harness", "spiraled", "right move", "Cloud Agents", "Warp terminal" -> zero hits. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 16 ++++++++-------- .../cloud-agents/handoff/index.mdx | 10 +++++----- .../cloud-agents/handoff/local-to-cloud.mdx | 10 +++++----- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 184de3e0..fc27c280 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -11,7 +11,7 @@ Hand off a cloud agent run to a fresh cloud session when the original session ha Use this handoff direction when: -* A cloud agent finished and you want to send a follow-up after the session has ended. +* You want to send a follow-up to a cloud agent after its session has ended. * You want to continue an ambient agent run — an agent that runs in the background, such as a scheduled or integration-triggered run — while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). ## What carries over @@ -19,10 +19,10 @@ Use this handoff direction when: When you send a follow-up to a run whose session has ended, the run continues with: * **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. -* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new execution runs on the same Git branch as the prior session. +* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch. * **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. -If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could before continuing to your follow-up. +If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could rather than starting over silently. ## Prerequisites @@ -31,15 +31,15 @@ If applying any change fails, the agent reports what couldn't be applied and pro * **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. :::caution -Cloud-to-cloud handoff relies on a snapshot from the prior execution. Older cloud runs that don't have a snapshot on file can't be handed off; start a new run instead. +Cloud-to-cloud handoff relies on a snapshot from the prior session. Older cloud runs that don't have a snapshot on file can't be handed off; start a new run instead. ::: ## Sending a follow-up -You don't take a separate "hand off" action — you send a follow-up, and the run continues. The handoff happens automatically when the original session has ended. Send-follow-up support is available in the Warp app. +You don't take a separate "hand off" action — you send a follow-up from the Warp app, and the run continues. The handoff happens automatically when the original session has ended. 1. **Open the ended cloud run.** Find it on the [Runs page](https://oz.warp.dev/runs) in the Oz web app or in the conversation panel. -2. **Send your follow-up.** Type the next message into the conversation's input and submit it. +2. **Send your follow-up.** Enter the next message in the conversation's input and submit it. The run picks up where it left off, with workspace state restored. @@ -49,7 +49,7 @@ Cloud-to-cloud handoff also works for supported third-party agent runtimes, but ## Inspecting a run that's been handed off -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API; the transcript is the source of truth. +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each session appears in order, and you can scan the transcript to see where one session ended and the next began. Per-session timestamps aren't currently exposed in the API; the transcript is the source of truth. ## Troubleshooting @@ -57,7 +57,7 @@ The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows The prior session didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state. **The run is in a terminal state with no conversation and follow-ups are rejected.** -Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed. +Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want, referencing the prior run if needed. ## Related pages diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index f34e9d9f..c343763f 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -1,9 +1,9 @@ --- title: Handoff between local and cloud agents description: >- - Move an agent conversation between your terminal and the cloud, or continue - a finished cloud run with workspace state restored, without re-explaining - the task. + Move agent work between a local Warp session and the cloud, or continue a + finished cloud run with workspace state restored, without re-explaining the + task. sidebar: label: "Handoff overview" --- @@ -14,7 +14,7 @@ Handoff lets you move a unit of agent work between a local Warp session and the Handoff supports three directions: -* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). +* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or parallel variants of the same task. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). * **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). * **Cloud to local** - Fork a cloud conversation into a local Warp session with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). @@ -30,7 +30,7 @@ Handoff coverage depends on which agent is running the conversation: Handoff preserves enough state that the receiving agent can resume the work, not just read about it. * **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn't modified; cloud-to-cloud continues in the same conversation. -* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction does not currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. +* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction doesn't currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. * **Conversation attachments** - Files attached during the prior session remain available to the receiving agent. Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could rather than starting over silently. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index f304e8d0..76c636f7 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -12,7 +12,7 @@ Hand off a local Warp conversation to a cloud agent run when the work outgrows y Use this handoff direction when: -* The task is going to run for a long time and you don't want to keep your laptop awake. +* You have a long-running task and don't want to keep your laptop awake. * You want to fan out variants of the same task across multiple cloud agents in parallel. * You want to walk away and check on the agent from a different device. * You want the agent to keep working while you start a new conversation locally. @@ -36,15 +36,15 @@ If applying any change fails in the cloud run, the cloud agent reports what coul ## Handing off a conversation to the cloud -1. **Open the handoff flow from your active conversation.** With the local conversation focused, trigger handoff with the `&` shortcut or the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn't an entry point for handoff. -2. **Choose the environment for the cloud run.** Pick the environment whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one first and add the repos you've been working in. +1. **Open the handoff flow from your active conversation.** With the local conversation focused, press `&` or run the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn't an entry point for handoff. +2. **Choose the environment for the cloud run.** Pick the one whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one and add the repos you've been working in. 3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. :::note The cloud agent runs with the same model your local conversation was using. Changing the model during handoff isn't supported. ::: -After submission, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. +After you submit, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) in the Oz web app or the conversation panel. @@ -54,7 +54,7 @@ To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo's current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment's repo to the branch you were on locally and retry the handoff. **The cloud agent doesn't see my uncommitted changes.** -Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked and the run falls back to starting fresh. +Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Otherwise, the conversation can't be forked and the run falls back to starting fresh. **The conversation doesn't appear in the cloud run.** The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. From b02509e71505b46756873fa3be0e6f7387728d29 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 04:07:57 +0000 Subject: [PATCH 10/12] docs(handoff): address two missed Rachael comments on cloud-to-cloud MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I missed two of @rachaelrenk's review comments on the cloud-to-cloud page in earlier passes because they weren't returned by the first `gh pr view` query. Applying them now. cloud-to-cloud.mdx - "ambient agent run" -> "background cloud agent run". Rachael flagged "ambient agent run" as abstract/internal-feeling; "background cloud agent run" keeps the example concrete and matches the user-facing framing on the surrounding pages. Per her suggested edit verbatim. - Removed `blocked` from the example list of terminal states. The API treats BLOCKED as terminal for cancellation purposes, but the spec describes it as "awaiting user input or approval" — so it isn't a natural place to send a follow-up via cloud-to-cloud handoff (responding to the prompt on the original run is the right path). Added a sentence to the prereq calling that out explicitly so readers don't try to hand off a blocked run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,439 internal links, 321 files). Co-Authored-By: Oz --- .../agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index fc27c280..943e3afb 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -12,7 +12,7 @@ Hand off a cloud agent run to a fresh cloud session when the original session ha Use this handoff direction when: * You want to send a follow-up to a cloud agent after its session has ended. -* You want to continue an ambient agent run — an agent that runs in the background, such as a scheduled or integration-triggered run — while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). ## What carries over @@ -26,7 +26,7 @@ If applying any change fails, the agent reports what couldn't be applied and pro ## Prerequisites -* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, blocked, or canceled — and have an associated agent conversation. Very old runs that predate the agent conversation model can't be continued via handoff. +* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, or canceled — and have an associated agent conversation. Blocked runs that are waiting on user input or approval aren't continued through cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can't be continued via handoff. * **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues — it just starts without restored workspace state. * **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. From 529a1f8caf6d4fc2ee3896b439136dedd6d42a2e Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 04:15:54 +0000 Subject: [PATCH 11/12] docs(handoff): audit polish for cloud-to-cloud prereqs Two small consistency fixes caught on a third audit round: - L29 "An ended cloud agent run" prereq: "Blocked runs ... aren't continued through cloud-to-cloud handoff" -> "...can't be continued via cloud-to-cloud handoff". Makes the carve-out parallel with the very next sentence ("Very old runs ... can't be continued via handoff"), and reads more directly than "aren't continued through". - L30 "A snapshot from the prior session" prereq: "the run still continues -- it just starts without restored workspace state" -> "the run still continues, just without restored workspace state". The em dash + "it just starts" was colloquial and a bit redundant ("continues" and "starts" describe the same event); the comma-led adjective phrase is cleaner. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,439 internal links, 321 files). Co-Authored-By: Oz --- .../agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 943e3afb..33b707d0 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -26,8 +26,8 @@ If applying any change fails, the agent reports what couldn't be applied and pro ## Prerequisites -* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, or canceled — and have an associated agent conversation. Blocked runs that are waiting on user input or approval aren't continued through cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can't be continued via handoff. -* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues — it just starts without restored workspace state. +* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, or canceled — and have an associated agent conversation. Blocked runs that are waiting on user input or approval can't be continued via cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can't be continued via handoff. +* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues, just without restored workspace state. * **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. :::caution From 9b58939c6ac77cdeaffc39b624b21dacacf9fceb Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 04:54:54 +0000 Subject: [PATCH 12/12] docs(handoff): add Handoff sidebar group + drop tombstone wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "cross-cutting sidebar PR" that the original PR description referred to doesn't exist — none of the orchestration-launch content is currently registered in `src/sidebar.ts`. PR #84 (multi-agent) doesn't touch the sidebar either; only PR #86 (memory) adds its own entries. Following that pattern: register the three handoff pages here so they actually appear in the docs sidebar when this branch merges. src/sidebar.ts - Added a new "Handoff" collapsible group inside the "Oz Cloud Agents & Orchestration" topic, slotted right after "Viewing cloud agent runs" since that's the closest thematic neighbor (it covers `Continue locally` / `/continue-locally`, the cloud-to-local path). The group contains: - Overview -> agent-platform/cloud-agents/handoff - Local to cloud -> agent-platform/cloud-agents/handoff/local-to-cloud - Cloud to cloud -> agent-platform/cloud-agents/handoff/cloud-to-cloud Mirrors the existing collapsible-group shape used by Triggers, Integrations, and Self-hosting in the same section. src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx - "(from the conversation details panel or the end-of-run tombstone)" -> "(from the conversation details panel or the artifacts shown after the run)". "Tombstone" is the internal code-level term for the post-run view (`shared_session/conversation_ended_tombstone_view.rs`). Even though it shows up in telemetry-event descriptions in `privacy.mdx`, it's not natural user-facing copy. Switched to a plainer reference to the artifacts surfaced after the run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues on the files this PR touches. (The pre-existing pricing-faqs.mdx warnings are out of scope.) - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,440 links, 322 files). - `npm run build` fails on an UNRELATED orphan page (`agent-platform/cloud-agents/agents.mdx` is not registered in the sidebar). That page was added earlier on this branch by a different PR and is pre-existing breakage on `hyc/orch/handoff` — my edits don't touch it. Co-Authored-By: Oz --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 2 +- src/sidebar.ts | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index 33b707d0..157138b8 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -45,7 +45,7 @@ The run picks up where it left off, with workspace state restored. ### Third-party agent runtimes -Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the end-of-run tombstone) and enter the next message you want the agent to act on. +Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the artifacts shown after the run) and enter the next message you want the agent to act on. ## Inspecting a run that's been handed off diff --git a/src/sidebar.ts b/src/sidebar.ts index c2e510a8..bd313b71 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -354,6 +354,15 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/cloud-agents/oz-web-app', label: 'Oz web app' }, { slug: 'agent-platform/cloud-agents/skills-as-agents', label: 'Skills as agents' }, { slug: 'agent-platform/cloud-agents/viewing-cloud-agent-runs', label: 'Viewing cloud agent runs' }, + { + label: 'Handoff', + collapsed: true, + items: [ + { slug: 'agent-platform/cloud-agents/handoff', label: 'Overview' }, + { slug: 'agent-platform/cloud-agents/handoff/local-to-cloud', label: 'Local to cloud' }, + { slug: 'agent-platform/cloud-agents/handoff/cloud-to-cloud', label: 'Cloud to cloud' }, + ], + }, 'agent-platform/cloud-agents/secrets', { slug: 'agent-platform/cloud-agents/mcp', label: 'MCP servers' }, { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' },