docs(handoff): add local↔cloud handoff documentation#85
Conversation
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 <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds four new handoff documentation pages covering local-to-cloud, cloud-to-local, cloud-to-cloud, and an overview. The structure is useful, but a few statements overpromise current behavior or document an unconfirmed/incorrect user flow, which could mislead users at launch.
Concerns
- The overview describes all handoff directions as sharing workspace-snapshot rehydration, but the cloud-to-local page says local continuation only forks the conversation and artifacts.
- The local-to-cloud procedure publishes a specific
/cloud-agent/shortcut handoff flow even though the client surface needs confirmation. - The local-to-cloud page says
git diff --binary HEADcaptures untracked changes, which that command does not do by itself.
Verdict
Found: 0 critical, 3 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
|
||
| ## 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. |
There was a problem hiding this comment.
git apply mechanism overpromises that direction. Scope this mechanism to local-to-cloud and cloud-to-cloud, or explicitly carve out cloud-to-local here.
| 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. |
There was a problem hiding this comment.
git diff --binary HEAD does not include untracked files by itself, so this line documents an incorrect capture mechanism for the promised untracked workspace state. Describe the actual untracked-file snapshot path, or remove the exact command if the implementation uses additional packaging steps.
|
|
||
| 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. |
There was a problem hiding this comment.
/cloud-agent plus the keyboard shortcut as the handoff entry point before that client surface is confirmed. If the shipped UX differs, users will follow a command that starts the wrong flow; gate this with a note or update the steps to the final launch surface before merging.
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 <oz-agent@warp.dev>
Revision passPushed What changed
Review comments addressed
Internal-only scrubStripped from all user-facing copy: GCS paths ( Validation
Open questions for PM
|
- 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 <oz-agent@warp.dev>
Second editor passPushed Terminology
Structural changes
Validation
|
Co-Authored-By: Oz <oz-agent@warp.dev>
- 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 <oz-agent@warp.dev>
|
Applied audit fixes for handoff pages. Summary of changes:
Co-authored-by: Oz oz-agent@warp.dev |
|
|
||
| * 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/). |
There was a problem hiding this comment.
This bullet seems to be saying the same one that the second one is saying. Maybe we consolidate them?
There was a problem hiding this comment.
Consolidated the duplicate bullets. The "scheduled or integration-triggered run" detail is now folded into the "ambient agent run" bullet, removing the redundancy.
| 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. |
There was a problem hiding this comment.
I might also add something here about the fact that you'll be on the same Git branch if you were in a git managed session.
There was a problem hiding this comment.
Added: "For git-managed sessions, the new execution runs on the same Git branch as the prior session." Folded into the "prior workspace state" carryover bullet.
|
|
||
| ## 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. |
There was a problem hiding this comment.
Also, runs that were created before the handoff model shipped to prod won't work for this. The implementation requires that snapshots exist for us to rehydrate from and runs that predate the feature won't have snapshots generated.
There was a problem hiding this comment.
Added a :::caution under Prerequisites: "Cloud-to-cloud handoff relies on a snapshot from the prior execution. Older cloud runs that do not have a snapshot on file can not be handed off; start a new run instead." Phrased as a current-state capability constraint rather than a launch-anchored timeline, per the cross-cutting guidance for this pass.
|
|
||
| * **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. |
There was a problem hiding this comment.
We discovered some interesting nuances around permissions for runs that start local then get moved to cloud. In that case, the team doesn't have access to continue that cloud run. Might be worth highlighting here?
There was a problem hiding this comment.
Highlighted. Added to the "Access to the run" prerequisite: "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 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. |
There was a problem hiding this comment.
We don't actually have a way to send follow-ups from Oz. It's only available in the Warp app.
There was a problem hiding this comment.
Fixed. Dropped the "From the Oz web app" and "From an integration" sections. The remaining surface in the procedural is the Warp app, with explicit copy: "Send-follow-up support is available in the Warp app." Also removed the misleading "Submit follow-ups programmatically" link from Related pages so the API does not look like a viable follow-up entry point.
|
|
||
| ## 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. |
There was a problem hiding this comment.
I don't think we surface executions in the API so an end-user couldn't find this information there. At the moment, it'll only be through visual inspection on the transcript.
There was a problem hiding this comment.
Rewrote the "Inspecting a run that has been handed off" section to drop the API claim. It now says you can scan the transcript to see where one execution ended and the next began, and explicitly notes: "Per-execution timestamps are not currently exposed in the API; the transcript is the source of truth."
|
|
||
| ## Directions of handoff | ||
|
|
||
| Two handoff directions are introduced with the Oz launch: |
There was a problem hiding this comment.
It feels weird to say Oz launch here but not sure what a better term would be.
There was a problem hiding this comment.
Dropped the "Oz launch" framing. The Directions list now opens with the evergreen "Handoff supports three directions:" instead of anchoring to a launch event, and the same approach is applied across all three pages in this pass.
|
|
||
| ## 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. |
There was a problem hiding this comment.
/cloud-agent will always start you with a new agent session, even if you're in an active conversation. The only entry points for local-cloud handoff are the & shortcut and the /handoff slash command.
There was a problem hiding this comment.
Updated. Step 1 now reads "trigger handoff with the & shortcut or the /handoff slash command," and the procedural explicitly notes that /cloud-agent "always starts a fresh cloud conversation and is not an entry point for handoff."
|
|
||
| 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. |
There was a problem hiding this comment.
We might want to add something here that changing the model when doing handoff is not currently permitted.
There was a problem hiding this comment.
Added a :::note immediately after the procedural steps: "The cloud agent runs with the same model your local conversation was using. Changing the model during handoff is not supported."
|
Some other thoughts that are not aligned with existing content:
|
- 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 <oz-agent@warp.dev>
Both points addressed in this pass:
|
2 participants
Adds documentation for the Handoff feature shipping with the Oz Orchestration Launch (Maestro). Four new pages under a new `agent-platform/cloud-agents/handoff/` directory cover the three handoff directions (local→cloud, cloud→local, cloud→cloud) plus an overview of what's preserved and how rehydration works.
New pages
Grounded against
Validation
File scope
Strictly within the listed handoff scope. No edits to `src/sidebar.ts`, `vercel.json`, or any top-level/cross-cutting landing pages — those are reserved for the follow-up sidebar PR.
Open questions / things to confirm with PM
Co-Authored-By: Oz oz-agent@warp.dev