Skip to content

Commit 8a5e546

Browse files
feat(server): hand a thread off to a linked environment
A thread can now move to a linked environment with its conversation and its git work, with exactly one copy live. ThreadHandoff marks it departing, which refuses new turns and keeps queued runs from starting; packs the branch and working tree with HandoffGit; uploads the bundle through the other side's signed attachment route; and calls t3_thread_import there, which now takes the bundle and applies it in a new worktree before creating the thread. Only then is the thread departed here and read-only. A failed move marks it failed, which takes turns again, and nothing is left there. An agent can move its own thread with t3_thread_handoff. The move then waits as pending until its turn ends, starts the thread there with the agent's continuationPrompt, and is cancelled by a user message sent before the turn ends. A startup sweep runs moves that a restart cut short; import ids derive from the handoff, so a retry finds the thread already there. threadHandoff.options / start / cancel serve the clients. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent f73f29d commit 8a5e546

31 files changed

Lines changed: 1930 additions & 103 deletions

‎apps/server/src/auth/RpcAuthorization.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ export const RPC_REQUIRED_SCOPES = {
8787
[WS_METHODS.serverGetDatabaseStorage]: AuthOrchestrationReadScope,
8888
[WS_METHODS.serverGetSettings]: AuthOrchestrationReadScope,
8989
[WS_METHODS.peerLinksList]: AuthAccessReadScope,
90+
// Moving a thread drives the linked environment through this one's link.
91+
[WS_METHODS.threadHandoffOptions]: AuthOrchestrationReadScope,
92+
[WS_METHODS.threadHandoffStart]: AuthOrchestrationOperateScope,
93+
[WS_METHODS.threadHandoffCancel]: AuthOrchestrationOperateScope,
9094
[WS_METHODS.serverUpdateSettings]: AuthSettingsWriteScope,
9195
[WS_METHODS.serverSearchAcpRegistry]: AuthOrchestrationReadScope,
9296
[WS_METHODS.serverPrepareAcpRegistryAgent]: AuthProvidersManageScope,

‎apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ import * as McpInvocationContext from "./McpInvocationContext.ts";
5050
import * as PeerForwarding from "../peer/PeerForwarding.ts";
5151
import * as PeerLinkRequests from "../peer/PeerLinkRequests.ts";
5252
import * as PeerLinks from "../peer/PeerLinks.ts";
53+
import * as ThreadHandoff from "../peer/handoff/ThreadHandoff.ts";
5354

5455
const layerOrchestratorToolkit = McpHttpServer.layerOrchestratorToolkit.pipe(
5556
Layer.provide(Layer.mock(ThreadLaunchService.ThreadLaunchService)({})),
@@ -233,6 +234,7 @@ describe("orchestrator MCP toolkit", () => {
233234
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
234235
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
235236
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
237+
Layer.provide(Layer.mock(ThreadHandoff.ThreadHandoff)({})),
236238
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
237239
Layer.provideMerge(
238240
SecretRequests.layer.pipe(

‎apps/server/src/mcp/linkOrigin.test.ts‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ import * as ThreadSearch from "../orchestration-v2/ThreadSearch.ts";
4747
import * as PeerLinkRequests from "../peer/PeerLinkRequests.ts";
4848
import * as PeerLinks from "../peer/PeerLinks.ts";
4949
import * as ThreadImportService from "../orchestration-v2/ThreadImportService.ts";
50+
import * as ThreadHandoff from "../peer/handoff/ThreadHandoff.ts";
51+
import * as HandoffImport from "../peer/handoff/HandoffImport.ts";
5052

5153
// A linked environment's session drives this one's real orchestrator through
5254
// its real T3 tools. What the link starts carries its origin, and the link
@@ -158,13 +160,20 @@ const layerTools = Layer.mergeAll(
158160
}),
159161
}),
160162
),
161-
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
162-
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
163-
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
164-
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
165-
Layer.provide(Layer.mock(ThreadImportService.ThreadImportService)({})),
166-
Layer.provide(Layer.mock(ThreadSearch.ThreadSearch)({})),
167-
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
163+
// Services the toolkits declare that these calls never reach.
164+
Layer.provide(
165+
Layer.mergeAll(
166+
Layer.mock(SecretRequests.SecretRequests)({}),
167+
Layer.mock(PeerForwarding.PeerForwarding)({}),
168+
Layer.mock(PeerLinkRequests.PeerLinkRequests)({}),
169+
Layer.mock(PeerLinks.PeerLinks)({}),
170+
Layer.mock(ThreadImportService.ThreadImportService)({}),
171+
Layer.mock(ThreadHandoff.ThreadHandoff)({}),
172+
Layer.mock(HandoffImport.HandoffImport)({}),
173+
Layer.mock(ThreadSearch.ThreadSearch)({}),
174+
Layer.mock(RemoteDelegation.RemoteDelegation)({}),
175+
),
176+
),
168177
Layer.provide(
169178
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/p" }),
170179
),

‎apps/server/src/mcp/toolkits/core.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ import * as AttachmentHandlers from "./attachment/handlers.ts";
5858
import * as PeerForwarding from "../../peer/PeerForwarding.ts";
5959
import * as PeerLinkRequests from "../../peer/PeerLinkRequests.ts";
6060
import * as PeerLinks from "../../peer/PeerLinks.ts";
61+
import * as ThreadHandoff from "../../peer/handoff/ThreadHandoff.ts";
6162

6263
const layerOrchestratorToolkit = McpHttpServer.layerOrchestratorToolkit.pipe(
6364
Layer.provide(Layer.mock(ThreadLaunchService.ThreadLaunchService)({})),
@@ -79,6 +80,7 @@ const layerThreadToolkit = McpHttpServer.layerThreadToolkit.pipe(
7980
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
8081
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
8182
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
83+
Layer.provide(Layer.mock(ThreadHandoff.ThreadHandoff)({})),
8284
);
8385

8486
const threadId = ThreadId.make("mcp-core-thread");
@@ -608,6 +610,7 @@ it.effect("refuses act-as-caller tools to a client caller", () =>
608610
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
609611
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
610612
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
613+
Layer.provide(Layer.mock(ThreadHandoff.ThreadHandoff)({})),
611614
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
612615
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
613616
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
@@ -669,6 +672,7 @@ it.effect("a caller cannot rewrite a scheduled task that runs above its own mode
669672
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
670673
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
671674
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
675+
Layer.provide(Layer.mock(ThreadHandoff.ThreadHandoff)({})),
672676
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
673677
),
674678
),
@@ -758,6 +762,7 @@ it.effect.each(["t3_thread_interrupt", "t3_workflow_stop"])(
758762
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
759763
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
760764
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
765+
Layer.provide(Layer.mock(ThreadHandoff.ThreadHandoff)({})),
761766
),
762767
),
763768
),
@@ -851,6 +856,7 @@ it.effect("discovers workflow stop targets and requires orchestration capability
851856
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
852857
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
853858
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
859+
Layer.provide(Layer.mock(ThreadHandoff.ThreadHandoff)({})),
854860
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
855861
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
856862
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),

‎apps/server/src/mcp/toolkits/orchestrator/handlers.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import * as Effect from "effect/Effect";
55
import * as PeerForwarding from "../../../peer/PeerForwarding.ts";
66
import * as PeerLinkRequests from "../../../peer/PeerLinkRequests.ts";
77
import * as PeerLinks from "../../../peer/PeerLinks.ts";
8+
import * as ThreadHandoff from "../../../peer/handoff/ThreadHandoff.ts";
89
import { readCaller } from "../../threadAccess.ts";
910
import * as McpInvocationContext from "../../McpInvocationContext.ts";
1011
import * as McpToolAccess from "../../McpToolAccess.ts";
@@ -184,6 +185,50 @@ const handlers = {
184185
return yield* service.waitForThread(scope, input);
185186
}),
186187
),
188+
t3_thread_handoff: McpToolAccess.writesThreads(
189+
(input) => [input.threadId],
190+
(input) =>
191+
Effect.gen(function* () {
192+
const scope = yield* McpInvocationContext.McpInvocationContext;
193+
const handoff = yield* ThreadHandoff.ThreadHandoff;
194+
const state = yield* handoff
195+
.start({
196+
threadId: input.threadId,
197+
callerThreadId: scope.thread?.threadId,
198+
environmentId: input.environmentId,
199+
projectId: input.projectId,
200+
continuationPrompt: input.continuationPrompt,
201+
})
202+
.pipe(
203+
Effect.mapError(
204+
(error) =>
205+
new OrchestratorMcpFailure({
206+
code:
207+
error.reason === "not_found"
208+
? "thread_not_found"
209+
: error.reason === "refused"
210+
? "invalid_request"
211+
: "orchestration_error",
212+
message: error.message,
213+
}),
214+
),
215+
);
216+
return {
217+
state: state.state,
218+
environmentId: state.environmentId,
219+
label: state.label,
220+
threadId: state.state === "departed" ? state.threadId : null,
221+
message:
222+
state.state === "pending"
223+
? `This thread moves to ${state.label} when this turn ends. End the turn now; a message to this thread before then cancels the move.`
224+
: state.state === "departed"
225+
? `The thread moved to ${state.label}.`
226+
: state.state === "failed"
227+
? `The move failed: ${state.lastError}`
228+
: `The thread is moving to ${state.label}.`,
229+
};
230+
}),
231+
),
187232
t3_environment_links: McpToolAccess.reads(() =>
188233
Effect.gen(function* () {
189234
const scope = yield* McpInvocationContext.McpInvocationContext;

‎apps/server/src/mcp/toolkits/orchestrator/tools.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ import {
77
OrchestratorMcpEnvironmentLinksResult,
88
OrchestratorMcpEnvironmentUnlinkInput,
99
OrchestratorMcpEnvironmentUnlinkResult,
10+
OrchestratorMcpThreadHandoffInput,
11+
OrchestratorMcpThreadHandoffResult,
1012
OrchestratorMcpCreateThreadsInput,
1113
OrchestratorMcpCreateThreadsResult,
1214
OrchestratorMcpDelegateTaskInput,
@@ -46,6 +48,7 @@ import * as ThreadManagementService from "../../../orchestration-v2/ThreadManage
4648
import * as PeerForwarding from "../../../peer/PeerForwarding.ts";
4749
import * as PeerLinkRequests from "../../../peer/PeerLinkRequests.ts";
4850
import * as PeerLinks from "../../../peer/PeerLinks.ts";
51+
import * as ThreadHandoff from "../../../peer/handoff/ThreadHandoff.ts";
4952
import * as McpInvocationContext from "../../McpInvocationContext.ts";
5053
import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts";
5154
import * as ThreadMetadataMcpService from "../../ThreadMetadataMcpService.ts";
@@ -305,6 +308,19 @@ const ThreadInterruptTool = Tool.make("t3_thread_interrupt", {
305308
.annotate(Tool.Title, "Interrupt a T3 thread")
306309
.annotate(Tool.Destructive, true);
307310

311+
const ThreadHandoffTool = Tool.make("t3_thread_handoff", {
312+
description:
313+
"Move a thread to a linked environment (t3_environment_links), such as the user's VPS, with its conversation and its git work: unpushed commits, uncommitted edits and new files. It continues there in a new worktree of the project with the same repository, and the copy here becomes read-only. Omit threadId to move the calling thread: the move then happens as soon as this turn ends, and continuationPrompt becomes its first message there, so end the turn after saying what you will do there. A message to the thread before then cancels the move. Another thread must be idle to move.",
314+
parameters: OrchestratorMcpThreadHandoffInput,
315+
success: OrchestratorMcpThreadHandoffResult,
316+
failure: OrchestratorMcpFailure,
317+
failureMode: "return",
318+
dependencies: [...dependencies, ThreadHandoff.ThreadHandoff],
319+
})
320+
.annotate(Tool.Title, "Move a thread to a linked environment")
321+
.annotate(Tool.Destructive, true)
322+
.annotate(Tool.OpenWorld, true);
323+
308324
const EnvironmentLinksTool = Tool.make("t3_environment_links", {
309325
description:
310326
"List linked environments (the user's other machines) and whether each answers now. Pass one's `environmentId` to a tool to act there; `delegate_task` takes `target.environmentId`. Expired: link it again with `t3_environment_link`.",
@@ -368,4 +384,5 @@ export const OrchestratorToolkit = Toolkit.make(
368384
EnvironmentLinksTool,
369385
EnvironmentLinkTool,
370386
EnvironmentUnlinkTool,
387+
ThreadHandoffTool,
371388
);

‎apps/server/src/mcp/toolkits/project/handlers.ts‎

Lines changed: 33 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import * as FileSystem from "effect/FileSystem";
1212
import * as Option from "effect/Option";
1313
import * as ThreadLaunch from "../../../orchestration-v2/ThreadLaunchService.ts";
1414
import * as ThreadImportService from "../../../orchestration-v2/ThreadImportService.ts";
15+
import * as HandoffImport from "../../../peer/handoff/HandoffImport.ts";
1516
import * as ThreadMessageIntake from "../../../orchestration-v2/ThreadMessageIntake.ts";
1617
import * as Claims from "../../../orchestration-v2/AttachmentClaims.ts";
1718
import * as Project from "../../../project/ProjectService.ts";
@@ -264,21 +265,43 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
264265
code: "invalid_request",
265266
message: "The project was not found.",
266267
});
268+
if (input.worktreePath !== undefined && input.bundle !== undefined)
269+
return yield* new OrchestratorMcpFailure({
270+
code: "invalid_request",
271+
message: "A bundle lands in a new worktree; omit worktreePath.",
272+
});
267273
if (input.worktreePath !== undefined)
268274
yield* assertProjectWorktree(project.workspaceRoot, input.worktreePath);
269275
const imports = yield* ThreadImportService.ThreadImportService;
276+
const handoffs = yield* HandoffImport.HandoffImport;
277+
const bundle = input.bundle;
278+
const workspace =
279+
bundle === undefined
280+
? undefined
281+
: handoffs.applyBundle({
282+
repoRoot: project.workspaceRoot,
283+
handoffId: input.source.handoffId,
284+
bundle,
285+
});
270286
return yield* imports
271-
.importThread({ ...input, runtimeMode, interactionMode, linkOrigin })
287+
.importThread({
288+
...input,
289+
runtimeMode,
290+
interactionMode,
291+
linkOrigin,
292+
...(workspace === undefined ? {} : { workspace }),
293+
})
272294
.pipe(
273-
Effect.mapError(
274-
(error) =>
275-
new OrchestratorMcpFailure({
276-
code:
277-
error._tag === "ThreadImportProjectMismatchError"
278-
? "invalid_request"
279-
: "orchestration_error",
280-
message: error.message,
281-
}),
295+
Effect.mapError((error) =>
296+
error._tag === "OrchestratorMcpFailure"
297+
? error
298+
: new OrchestratorMcpFailure({
299+
code:
300+
error._tag === "ThreadImportProjectMismatchError"
301+
? "invalid_request"
302+
: "orchestration_error",
303+
message: error.message,
304+
}),
282305
),
283306
);
284307
}),

‎apps/server/src/mcp/toolkits/project/tools.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import * as DocumentText from "../../../provider/DocumentText.ts";
2727
import * as ServerConfig from "../../../config.ts";
2828
import * as ServerSettings from "../../../serverSettings.ts";
2929
import * as ThreadImportService from "../../../orchestration-v2/ThreadImportService.ts";
30+
import * as HandoffImport from "../../../peer/handoff/HandoffImport.ts";
3031
import * as ThreadLaunchService from "../../../orchestration-v2/ThreadLaunchService.ts";
3132
import * as Crypto from "effect/Crypto";
3233
import * as Schema from "effect/Schema";
@@ -184,6 +185,7 @@ const ThreadImportTool = Tool.make("t3_thread_import", {
184185
dependencies: [
185186
...shared.dependencies,
186187
ThreadImportService.ThreadImportService,
188+
HandoffImport.HandoffImport,
187189
GitVcsDriver.GitVcsDriver,
188190
FileSystem.FileSystem,
189191
],

‎apps/server/src/observability/RpcInstrumentation.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ const RPC_AGGREGATES = {
6363
[WS_METHODS.peerLinksLink]: "peerLinks",
6464
[WS_METHODS.peerLinksUnlink]: "peerLinks",
6565
[WS_METHODS.peerLinksAnswerRequest]: "peerLinks",
66+
[WS_METHODS.threadHandoffOptions]: "threadHandoff",
67+
[WS_METHODS.threadHandoffStart]: "threadHandoff",
68+
[WS_METHODS.threadHandoffCancel]: "threadHandoff",
6669
[WS_METHODS.serverUpdateSettings]: "server",
6770
[WS_METHODS.serverSearchAcpRegistry]: "server",
6871
[WS_METHODS.serverPrepareAcpRegistryAgent]: "server",

0 commit comments

Comments
 (0)