docs(handoff): add local↔cloud handoff documentation by hongyi-chen · Pull Request #85 · warpdotdev/docs

hongyi-chen · 2026-05-16T20:31:25Z

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

`src/content/docs/agent-platform/cloud-agents/handoff/index.mdx` - Conceptual overview: what handoff is, the three directions, what carries over (conversation history, workspace state, manifest, artifacts), and rehydration behavior.
`src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx` - Procedural: promoting a local Warp Agent conversation to a cloud agent run via `/cloud-agent` from inside an active conversation. Covers the fork + snapshot mechanics and the verification steps in the receiving cloud run.
`src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx` - Procedural: picking up a cloud run inside the Warp terminal via the Continue locally button (details panel and end-of-run tombstone) and the `/continue-locally` slash command. Documents the fork-into-split-pane behavior.
`src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx` - Procedural: how follow-ups to ended cloud runs trigger a new execution on the same run with rehydrated workspace state. Documents the three routing outcomes (appended, injected, requeued) and the per-execution snapshot mechanics.

Grounded against

`warp-server/specs/REMOTE-1290` (cloud-to-cloud handoff) — `POST /agent/runs/{runId}/followups`, per-execution snapshot prefix `snapshots/{run_id}/{execution_id}/`, three-way routing logic.
`warp-server/specs/REMOTE-1486` (local-to-cloud handoff) — `POST /agent/handoff/upload-snapshot` endpoint, `initial_snapshot_token` plumbing, server-side `ForkConversation`, `handoff/{token}/` staging prefix, mutual exclusion with `conversation_id`.
`warp-internal/specs/REMOTE-1332` (snapshot upload + client hydration) — declarations file format, manifest schema, retry/backoff behavior.
`warp-internal/app/src/ai/conversation_details_panel.rs` and `shared_session/conversation_ended_tombstone_view.rs` — Continue locally button surfaces.
`warp-internal/app/src/workspace/action.rs` + `workspace/view.rs` — `WorkspaceAction::ContinueConversationLocally` forks the cloud conversation into a split pane.
Recent changelog draft entry: "/continue-locally slash command to continue cloud conversations locally" (#9500) confirms the slash command shipped.

Validation

`python3 .agents/skills/style_lint/style_lint.py --changed` — clean (4 files scanned, 0 issues).
`python3 .agents/skills/check_for_broken_links/check_links.py --internal-only` — 0 broken internal links across the full docs tree.

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

Feature-flag posture. `local_to_cloud_handoff` and `cloud_to_cloud_handoff` are server-side flags; `OzHandoff` is the client-side flag. I documented all three directions as available features and didn't surface the flags. If any direction is still strictly behind a dogfood gate at launch, we should add a `:::note` to the corresponding page.
Local-to-cloud client surface. I describe the entry point as "`/cloud-agent` from inside an active conversation". The server spec is landed; the client-side counterpart isn't visible in `warp-internal` today (the spec referenced a paired `SNAPSHOT_UPLOAD_TECH.md` I couldn't locate). If the final shipping UX uses a different entry point (e.g. a dedicated `/handoff` slash command or a button), the procedural needs an update.
Cloud-to-local snapshot apply. REMOTE-1486 lists "Symmetric cloud→local handoff. Reuse `ForkConversation` and the snapshot rehydration path in reverse" as a follow-up. Today's `Continue locally` only forks the conversation; it does not auto-apply the cloud agent's workspace patches. I called this out in a `:::note` on the cloud-to-local page. Confirm this is the right framing for launch.
Sidebar registration. New pages won't show in the sidebar until the cross-cutting sidebar PR lands.

Co-Authored-By: Oz oz-agent@warp.dev

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>

vercel · 2026-05-16T20:31:31Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Error		May 16, 2026 11:32pm

oz-for-oss · 2026-05-16T20:31:37Z

@hongyi-chen

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 /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

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 HEAD captures 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

oz-for-oss · 2026-05-16T20:35:25Z

+
+## 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.


⚠️ [IMPORTANT] Cloud-to-local currently only forks the conversation/artifacts and does not apply workspace patches, so saying all three directions share a GCS snapshot + 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.

oz-for-oss · 2026-05-16T20:35:25Z

+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.


⚠️ [IMPORTANT] 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.

oz-for-oss · 2026-05-16T20:35:25Z

+
+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.


⚠️ [IMPORTANT] This publishes /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>

hongyi-chen · 2026-05-16T20:56:58Z

Revision pass

Pushed e1da8dd to address PR-review feedback, Slack-thread direction, and an internal-only/senior-writer scrub.

What changed

Dropped cloud-to-local.mdx per Slack feedback (cloud → local is not new functionality at launch). The existing fork-to-local capability is already documented at viewing-cloud-agent-runs.mdx, and the new /continue-locally slash command is in the changelog. The overview now references that page for the cloud-to-local direction.
Rewrote index.mdx to scope the snapshot rehydration mechanism to local-to-cloud and cloud-to-cloud only — cloud-to-local does not apply workspace patches.
Rewrote local-to-cloud.mdx to drop the inaccurate git diff --binary HEAD capture description and to soften the entry point (no specific keyboard shortcut, with a note that the affordance may evolve during launch).
Rewrote cloud-to-cloud.mdx to reframe the routing logic in user-facing terms instead of the internal appended / injected / requeued names.

Review comments addressed

✅ Scope the GCS-snapshot + git apply mechanism in the overview — cloud-to-local is now carved out, and the snapshot mechanism is described in user-facing terms without git apply.
✅ git diff --binary HEAD claim in local-to-cloud — replaced with a high-level description that covers tracked and untracked changes.
✅ Confirm the /cloud-agent + shortcut entry point — softened to "the cloud agent launch flow" with /cloud-agent as an example. No keyboard shortcut. Added a :::note noting the affordance may evolve.

Internal-only scrub

Stripped from all user-facing copy: GCS paths (handoff/{token}/, snapshots/{run_id}/{execution_id}/), manifest filenames (snapshot_state.json), internal type names, API endpoint paths, internal routing names, and git apply mechanics.

Validation

style_lint --changed — clean
check_links --internal-only — clean (2,416 internal links across 320 files)

Open questions for PM

Feature-flag posture. local_to_cloud_handoff and cloud_to_cloud_handoff are not set in prod.yaml today (only in staging/local). OzHandoff is in DOGFOOD_FLAGS. The pages assume these flip on at launch — confirm before merging.
Local-to-cloud entry point. The procedural describes "the cloud agent launch flow inside an active conversation" without a specific shortcut. If the shipped UX uses a dedicated affordance (e.g. a button or a different slash command), update step 1 in local-to-cloud.mdx.
Sidebar registration. New pages still won't appear in the sidebar until the cross-cutting sidebar PR lands.

- 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>

hongyi-chen · 2026-05-16T21:49:01Z

Second editor pass

Pushed 91cd3da with a more aggressive scrub of internal jargon and structural over-explanation. Net: −75 lines / +40 lines across the three pages.

Terminology

execution → session (or removed) — A run has many sessions in the user's mental model, not many executions. The internal model is no longer leaking.
rehydrate / rehydration → restore / "carry over" — User-facing language only.
server-side fork → fork — Readers don't care where the fork happens.
sandbox — Trimmed where it leaked infrastructure; kept where it adds clarity.

Structural changes

Folded the standalone Rehydration behavior section in the overview into What carries over.
Collapsed cloud-to-cloud's How follow-ups route state-machine (queued / alive / ended) into a single user-facing description. Those routing branches are implementation detail; the user reality is "send a follow-up and the run continues."
Removed two cloud-to-cloud troubleshooting items that described the appended and live-session routing paths — they're normal behavior, not problems.
Collapsed local-to-cloud's Verifying the handoff debugging walkthrough into one sentence pointing readers to the management view.
Cut self-descriptive meta sentences ("The handoff entry point is integrated…", "Cloud-to-cloud handoff is automatic…").
Dropped the rollout caveat note on local-to-cloud.

Validation

style_lint --changed — clean (3 files, 0 issues)
check_links --internal-only — clean (2,416 internal links across 320 files)
Final grep for rehydrat, server-side, execution, sandbox in the handoff pages — zero hits.

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>

hongyi-chen · 2026-05-16T23:31:19Z

Applied audit fixes for handoff pages. Summary of changes:

cloud-to-cloud.mdx (line 56) — Softened the per-session timeline UI claim to API-only phrasing. Verified warp-internal/app/src/ai/agent_management/* and conversation_details_panel.rs show only aggregated Credits/Run time/Created on in the detail pane, with no per-session breakdown rendered. The execution data is available via the API.
cloud-to-cloud.mdx (line 24) — Kept the compute rollup claim. Verified in warp-server/logic/ai/ambient_agents/billing/compute.go: per-execution credits accumulate onto the task total.
cloud-to-cloud.mdx (line 16) — Added an inline gloss for "ambient agent run" (described as "an agent that runs in the background, such as a scheduled or integration-triggered run") to orient readers without duplicating the bullet above.
local-to-cloud.mdx (line 35) — Switched the primary credits-prereq link to /support-and-community/plans-and-billing/credits/ so individual users get an accurate target, with a secondary link to /agent-platform/cloud-agents/team-access-billing-and-identity/ for team-specific requirements. Also corrected the link text casing to match the page's sidebar label ("Access, billing, and identity").
Validation: style_lint --changed and check_links --internal-only both clean.

Co-authored-by: Oz oz-agent@warp.dev

cla-bot Bot added the cla-signed label May 16, 2026

vercel Bot had a problem deploying to Preview May 16, 2026 20:31 Failure

oz-for-oss Bot reviewed May 16, 2026

View reviewed changes

vercel Bot had a problem deploying to Preview May 16, 2026 20:57 Failure

vercel Bot had a problem deploying to Preview May 16, 2026 21:49 Failure

docs(handoff): trim overview description to fit 50-160 char range

89ba1a2

Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot had a problem deploying to Preview May 16, 2026 23:15 Failure

vercel Bot had a problem deploying to Preview May 16, 2026 23:32 Failure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(handoff): add local↔cloud handoff documentation#85

docs(handoff): add local↔cloud handoff documentation#85
hongyi-chen wants to merge 5 commits into
hyc/orchestration-launchfrom
hyc/orch/handoff

hongyi-chen commented May 16, 2026

Uh oh!

vercel Bot commented May 16, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot commented May 16, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

oz-for-oss Bot May 16, 2026

Uh oh!

oz-for-oss Bot May 16, 2026

Uh oh!

oz-for-oss Bot May 16, 2026

Uh oh!

hongyi-chen commented May 16, 2026

Uh oh!

hongyi-chen commented May 16, 2026

Uh oh!

hongyi-chen commented May 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		## 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.


		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.

Conversation

hongyi-chen commented May 16, 2026

New pages

Grounded against

Validation

File scope

Open questions / things to confirm with PM

Uh oh!

vercel Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot May 16, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot May 16, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot May 16, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen commented May 16, 2026

Revision pass

What changed

Review comments addressed

Internal-only scrub

Validation

Open questions for PM

Uh oh!

hongyi-chen commented May 16, 2026

Second editor pass

Terminology

Structural changes

Validation

Uh oh!

hongyi-chen commented May 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented May 16, 2026 •

edited

Loading

oz-for-oss Bot commented May 16, 2026 •

edited

Loading