feat(server): delegate_task to a linked environment#16719

Part of cross-environment orchestration. An agent can now delegate a task to a linked environment and get woken by its result, the same way a local subagent wakes it.

How it works

• The call. delegate_task takes target.environmentId and, optionally, target.projectId. Without a project, it picks the project there with the same repository canonicalKey as this thread's. Both sides resolve the identity with RepositoryIdentityResolver, because a project's cached identity is blank until enrichment runs. If none or several match, it fails with invalid_request and lists the candidates.
• Launch there. The child is an ordinary thread on the other side. RemoteDelegation launches it through PeerForwarding, and uses a key derived from clientRequestId and the caller's namespace, so a retry hits the same thread there via #16654.
  • The provider and model inherit from the parent, as for a local task. A different provider there needs target.model.
  • Modes the caller asks for are checked against the parent. Omitted modes are left to the other side, which inherits the parent's modes capped by the link's access. A narrower link (say auto-accept-edits under a full-access parent) still takes the task instead of refusing it.
• Record here. A new internal command, delegated_task.remote.request, records the task on the parent: node, subagent row and turn item, with remoteChild: {environmentId, threadId, label} instead of a local child thread. childThreadId is null for these tasks; it becomes nullable in the MCP result, and every reader handles that.
• Completion. A follower waits on the remote thread (in ≤50 s pieces, per #16684), reads its last reply, and dispatches delegated_task.remote.complete. That command reuses planDelegatedCompletionDelivery and offerDelegatedCompletionDeliveries, so the parent's live run claims the result and wakes exactly as it does for a local child. A second report is refused, so the first result stands.
• Failure handling. A revoked or expired link fails the task with the reason. Anything else, such as the other machine asleep or a dropped route, backs off up to 5 minutes and tries again.
• Restart. At startup the follower re-follows every open remote task (ProjectionStore.getOpenRemoteDelegatedTasks). Restart recovery (ProviderRuntimeRecoveryService) no longer cancels a remote task as abandoned provider work.
• Task tools.
  • task_status: answers from the row.
  • mode=wait: wakes on the parent's subagent.updated.
  • task_cancel: interrupts the thread there, then completes the task as cancelled.
• Lineage across environments. The launch carries delegatedFrom: {environmentId, threadId, title}. Like linkOrigin, only the server keeps it: thread.create drops it unless the launch is stamped with a link origin, and a client cannot set it.
  • Parent (web). The inline task card and a Lineage row in the thread panel say "on box". They open the thread there when this client is connected to that environment, and are plain labels otherwise.
  • Child (web). The timeline opens with "Subagent of on ", with "Open parent thread" when that environment is connected. The parent's live title is used once the client sees it.
  • Mobile. Subagent rows say "on box" and open the remote thread when the environment is known. The thread header reads "Subagent of ".
  • Thread lists. A client connected to both machines lists the child under its parent, as it does a local subagent, not as a thread of its own. The web sidebar and its project ordering, mobile's thread lists and notifications leave it out. When the child, or one of its own subagents there, asks for approval or input, the parent here is flagged and shows the "Subagent needs …" banner. A child whose parent the client can't list (that machine switched off, or the parent gone) stays listed on its own, so its work is never out of reach.
• Docs. docs/user/remote-access.md and docs/internals/remote.md get a short note each.

Verification

• peer/RemoteDelegation.test.ts runs the laptop's real orchestrator (replay harness, SQLite), real toolkit and RemoteDelegation against the box's real /mcp behind real OAuth, on a real socket. The box's thread store is modelled, and the test finishes its thread. Three tests:
  • Delegate and complete. Delegating launches in the box project with the matching repository. A retry with the same key launches and records nothing new. When the box thread finishes, the task completes with its reply, the parent's live run claims it (delegatedCompletion.delivery.taskIds), the parent is offered a wake, and task_status reports the result.
  • Restart. The laptop delegates and is torn down. The task finishes on the box meanwhile. A new laptop on the same database starts the follower, which completes the task.
  • Cancel and revoke. task_cancel interrupts the box thread and completes the task as cancelled. A second task fails with "no longer accepts this link" once the box revokes the link.
• orchestration-v2/RemoteDelegatedTask.test.ts covers the deciders directly:
  • A replayed request records one task, with no local thread.
  • The task is open until it completes, then it isn't.
  • Completion claims the delivery and offers one wake.
  • A late second report is refused.
• Mutation-checked: each of these fails its test when removed:
  • the parent wake after completion;
  • the delivery plan (writing the bare task);
  • first-result-wins;
  • re-following at startup;
  • the open-task query's result filter;
  • failing on revocation (it would retry forever);
  • cancel's interrupt there;
  • the retry key;
  • the remote turn item.
• Also ran all of mcp, peer and cli, plus ProviderRuntimeRecoveryService, DelegatedCompletionDelivery, ThreadManagementService, ProviderTurnControlService, ProjectionStore and Orchestrator: 49 files, 491 tests. Contracts orchestratorMcp and orchestrationV2: 40 tests. All passed. Server, contracts, client-runtime, web and mobile typecheck clean, and lint is clean on the changed lines.

Review fixes (bots plus three rounds of adversarial review by GPT 6.1 Sol and Claude Fable 5.1)

• The task there gets what a local child gets. The role prompt, and the parent's provider and model unless the caller names others. Modes the caller omits are left to the other side, which caps the parent's modes at the link's access.

• Its own run, read whole. The launch's run id is kept on remoteChild.runId. The follower waits on that run and takes the result from that run's last reply, paging through the whole thread and reading a long reply to its end (itemId + textOffset). A later run's reply is never taken as the result.

• Retries and keys. The local record's command id carries the provider session's namespace, matching the forwarder's launch key, so a reused clientRequestId from another session is a new task on both sides. Each completion attempt has its own command id, and a report refused because the task already ended counts as done.

• Terminal failures end the task. A revoked or expired link, a link forgotten here, or a thread or run gone there fails the task with the reason, instead of retrying forever.

• Stopping stops the whole thread there. Cancel, and the parent's Stop, send t3_thread_interrupt with stop: true (#16684), which also holds the thread's queue there and stops the tasks it delegated. A cancel after the result still stops follow-up work there.

• A stop owed survives. remoteChild.stoppedThere records that nothing is left to stop there. A task cancelled or stopped here without it is followed again after a restart, and the follower keeps sending the stop until it lands. A run that ends there while the parent's Stop lands here doesn't count as stopped (stoppedThere: "ran-out" vs "stopped"), so its queued work is still stopped. A stop the other side refuses on mode grounds, say after the parent was lowered, ends instead of retrying.

• Smaller fixes.

  • A failed local record interrupts the thread it just launched.
  • The follower reaches the peer with this environment's id.
  • Matching a project there pages through every project.
  • A local target.projectId naming another project is refused.
  • Delegating reads the one link it needs without probing every peer.

• Tests. RemoteDelegation.test.ts went from 4 to 15 tests. They cover:

  • a 45,000-character reply and a later run's reply present;
  • namespacing;
  • the thread gone there and the link forgotten here;
  • cancel without a link, and cancel after the result;
  • the parent's Stop, while the box is unreachable, across a restart, while the result is being read, and when the box refuses it.

  Each was mutation-checked.

• Client tests. threadShell.test.ts runs both environments' shell atoms: the child is left out of navigation while its parent is listed, and listed again when the parent is gone or its machine is switched off; an approval from the child's own subagent flags the parent and fills its banner. Each rule was mutation-checked. Sidebar.logic.test.ts covers the sidebar filter.

• Deferred: recording the task here before launching it there, to cover a crash or lost response between the two without a retry. That's #17051, with a design. Today a failed record interrupts the launched thread, and a retry with the same clientRequestId replays the launch and records it.

Demo: link, delegate, follow the lineage (dev servers on this PR's head, hostnames laptop and box, real Codex agents)

Steps, in order:

1. Create a pairing link on the box.
2. Link it from the laptop's Settings → Connections.
3. The box lists the laptop as a client it can revoke.
4. A laptop agent gets a plain prompt ("delegate this to my box environment…"), with no model or modes.
5. It calls delegate_task with only target.environmentId. The task runs on the box under the link's auto-accept-edits, while the parent has full access.
6. The parent wakes with the box's result. Only the box's pricing.ts changed.
7. With the box added as an environment on the laptop client, the "on box" card opens the box's thread, which shows "From T3 Code · laptop" and "Subagent of …". "Open parent thread" returns.

Pairing codes are blurred.

https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/7edb274b45c1a49f/peer-delegation-demo.mp4

The first take of this demo found two gaps, which this PR now fixes:

• The agent's first two delegate_task calls failed. One had no target.model (target_required). The other used the parent's full access, which was broader than the link's auto-accept-edits (runtime_mode_escalation_denied). The model and modes now inherit as described above, and a new test covers both: a task named only by environment inherits the parent's model, within the link. Restoring the old mode handling fails that test with the same runtime_mode_escalation_denied the demo hit.
• The child's divider showed the title the parent had at delegation, before the parent renamed itself. It now uses the parent's live title when this client can see it.

End to end, two real servers (t3 serve built from this PR's head, d1f9fbd237, so nothing above it in the stack)

• A laptop and a box on one machine, each with its own data directory and a project cloned from one bare origin. Linked with t3 environment link … --access auto and a pairing code from the box. A real Claude Sonnet 5.5 agent on the laptop calls delegate_task with target.environmentId set to the box, and the child is a real Claude turn there.
• Delegate and complete. The child edited math.ts in the box's checkout and replied BOX DONE cups …/box-repo M math.ts. The task went from running to completed in 13 s with that reply, and the parent woke with PARENT GOT BOX DONE …. The laptop's checkout stayed clean. The box's thread carries the link's origin ("From T3 Code · cups").
• Restart mid-task. The laptop was stopped 1 s after delegating and restarted 9 s later, while the box child was still running a 60 s command. The follower picked the task up at startup. The task completed when the box run did (21:06:40), and the parent woke with PARENT GOT BOX SURVIVED RESTART.
• Cancel. With the box child mid-command, the parent agent called task_cancel, which returned cancel_requested. The task became cancelled and the box run interrupted at the same moment (21:07:47), and the parent reported PARENT GOT Cancelled.
• Revoke. With a child running, t3 auth session revoke on the box. The laptop's next poll failed the task in under a minute with "The linked environment no longer accepts this link. It may have been revoked there; link it again.", the parent woke with that reason, and t3 environment list shows it as the link's last error.

Laptop: the parent wakes with the box's result. Box: the child that ran there, labelled From T3 Code · cups, with its math.ts change

task_cancel interrupts the run on the box, and a revoked link fails the task with the reason

Opus 5.5 via Claude Code.

🤖 Generated with Claude Code

Devin Review

Closes discussions

• #19309 Let MCP choose the environment for t3_thread_launch and delegate_task (with #16684)