Skip to content

Commit e6d85ee

Browse files
feat(server): agents use linked environments
An agent can now work on a linked environment's threads through the same T3 MCP tools. t3_project_list, orchestrator_capabilities, t3_thread_launch, t3_thread_list, t3_thread_read, t3_thread_send, t3_thread_wait and t3_thread_interrupt take an optional environmentId; t3_environment_links lists the links. Each tool's own access declaration still runs here first, so a read-only or ended caller is refused before anything leaves. The forwarded call carries the caller's modes in T3-Mode-Limit, and the linked environment holds it to those and the link's access. Retry keys are hashed with the caller's namespace, since every caller here shares the link's one session there. A forwarded wait goes out in pieces of at most 50 s so no route drops it idle. A remote launch cannot carry attachments yet. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 84324d1 commit e6d85ee

17 files changed

Lines changed: 1031 additions & 201 deletions

File tree

‎apps/server/src/mcp/McpHttpServer.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -849,7 +849,7 @@ const layerEnvironmentRegistration = toolkitRegistration(
849849
EnvironmentHandlers.layer,
850850
);
851851

852-
const layerProjectRegistration = toolkitRegistration(ProjectToolkit, ProjectHandlers.layer);
852+
export const layerProjectRegistration = toolkitRegistration(ProjectToolkit, ProjectHandlers.layer);
853853

854854
const layerAttachmentRegistration = toolkitRegistration(
855855
AttachmentToolkit,

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

Lines changed: 86 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,45 @@
1-
import { OrchestratorToolkit } from "./tools.ts";
1+
import type { EnvironmentId } from "@t3tools/contracts";
22
import * as Effect from "effect/Effect";
3+
import type { Tool } from "effect/ai";
4+
5+
import { OrchestratorToolkit } from "./tools.ts";
36

7+
import * as PeerForwarding from "../../../peer/PeerForwarding.ts";
48
import * as McpInvocationContext from "../../McpInvocationContext.ts";
59
import * as McpToolAccess from "../../McpToolAccess.ts";
610
import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts";
711
import * as ThreadMetadataMcpService from "../../ThreadMetadataMcpService.ts";
812

13+
const { tools } = OrchestratorToolkit;
14+
15+
/**
16+
* Runs `here` in this environment, or the same tool in the linked
17+
* environment `input.environmentId` names. The tool's declaration has already
18+
* checked the caller here either way.
19+
*/
20+
const routed = <T extends (typeof tools)[keyof typeof tools], A, E, R>(
21+
tool: T,
22+
input: Tool.Parameters<T> & { readonly environmentId?: EnvironmentId | undefined },
23+
here: Effect.Effect<A, E, R>,
24+
) =>
25+
Effect.gen(function* () {
26+
const scope = yield* McpInvocationContext.McpInvocationContext;
27+
if (PeerForwarding.remoteTarget(scope, input.environmentId) === undefined) return yield* here;
28+
const forwarding = yield* PeerForwarding.PeerForwarding;
29+
return yield* forwarding.route(scope, tool, input, here);
30+
});
31+
932
const handlers = {
10-
orchestrator_capabilities: McpToolAccess.reads(() =>
11-
Effect.gen(function* () {
12-
const scope = yield* McpInvocationContext.McpInvocationContext;
13-
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
14-
return yield* service.capabilities(scope);
15-
}),
33+
orchestrator_capabilities: McpToolAccess.reads((input) =>
34+
routed(
35+
tools.orchestrator_capabilities,
36+
input,
37+
Effect.gen(function* () {
38+
const scope = yield* McpInvocationContext.McpInvocationContext;
39+
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
40+
return yield* service.capabilities(scope);
41+
}),
42+
),
1643
),
1744
delegate_task: McpToolAccess.actsAsCaller((input) =>
1845
Effect.gen(function* () {
@@ -81,21 +108,29 @@ const handlers = {
81108
}),
82109
),
83110
t3_thread_list: McpToolAccess.reads((input) =>
84-
Effect.gen(function* () {
85-
const scope = yield* McpInvocationContext.McpInvocationContext;
86-
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
87-
return yield* service.listThreads(scope, input);
88-
}),
111+
routed(
112+
tools.t3_thread_list,
113+
input,
114+
Effect.gen(function* () {
115+
const scope = yield* McpInvocationContext.McpInvocationContext;
116+
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
117+
return yield* service.listThreads(scope, input);
118+
}),
119+
),
89120
),
90121
// Reading a child's finished result also acknowledges its delivery to the
91122
// reader's own thread. That is bookkeeping on the caller's own subagent, not
92123
// a change to anything it reads, so this stays a read.
93124
t3_thread_read: McpToolAccess.reads((input) =>
94-
Effect.gen(function* () {
95-
const scope = yield* McpInvocationContext.McpInvocationContext;
96-
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
97-
return yield* service.readThread(scope, input);
98-
}),
125+
routed(
126+
tools.t3_thread_read,
127+
input,
128+
Effect.gen(function* () {
129+
const scope = yield* McpInvocationContext.McpInvocationContext;
130+
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
131+
return yield* service.readThread(scope, input);
132+
}),
133+
),
99134
),
100135
t3_thread_update: McpToolAccess.writesThreads(
101136
(input) => [input.threadId],
@@ -107,29 +142,51 @@ const handlers = {
107142
}),
108143
),
109144
t3_thread_send: McpToolAccess.writesThreads(
110-
(input) => [input.threadId],
145+
// A thread in a linked environment is checked there, where it lives.
146+
(input) => (input.environmentId === undefined ? [input.threadId] : []),
111147
(input) =>
112-
Effect.gen(function* () {
113-
const scope = yield* McpInvocationContext.McpInvocationContext;
114-
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
115-
return yield* service.sendToThread(scope, input);
116-
}),
148+
routed(
149+
tools.t3_thread_send,
150+
input,
151+
Effect.gen(function* () {
152+
const scope = yield* McpInvocationContext.McpInvocationContext;
153+
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
154+
return yield* service.sendToThread(scope, input);
155+
}),
156+
),
117157
),
118158
t3_thread_wait: McpToolAccess.reads((input) =>
119159
Effect.gen(function* () {
120160
const scope = yield* McpInvocationContext.McpInvocationContext;
161+
const target = PeerForwarding.remoteTarget(scope, input.environmentId);
162+
if (target !== undefined) {
163+
const forwarding = yield* PeerForwarding.PeerForwarding;
164+
return yield* forwarding.waitForThread(scope, target, input);
165+
}
121166
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
122167
return yield* service.waitForThread(scope, input);
123168
}),
124169
),
170+
t3_environment_links: McpToolAccess.reads(() =>
171+
Effect.gen(function* () {
172+
const scope = yield* McpInvocationContext.McpInvocationContext;
173+
const forwarding = yield* PeerForwarding.PeerForwarding;
174+
return yield* forwarding.links(scope);
175+
}),
176+
),
125177
t3_thread_interrupt: McpToolAccess.writesThreads(
126-
(input) => [input.threadId],
178+
// A thread in a linked environment is checked there, where it lives.
179+
(input) => (input.environmentId === undefined ? [input.threadId] : []),
127180
(input) =>
128-
Effect.gen(function* () {
129-
const scope = yield* McpInvocationContext.McpInvocationContext;
130-
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
131-
return yield* service.interruptThread(scope, input);
132-
}),
181+
routed(
182+
tools.t3_thread_interrupt,
183+
input,
184+
Effect.gen(function* () {
185+
const scope = yield* McpInvocationContext.McpInvocationContext;
186+
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
187+
return yield* service.interruptThread(scope, input);
188+
}),
189+
),
133190
),
134191
} satisfies McpToolAccess.Handlers<typeof OrchestratorToolkit.tools>;
135192

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

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import {
2+
OrchestratorMcpCapabilitiesInput,
23
OrchestratorMcpCapabilitiesResult,
4+
OrchestratorMcpEnvironmentLinksResult,
35
OrchestratorMcpCreateThreadsInput,
46
OrchestratorMcpCreateThreadsResult,
57
OrchestratorMcpDelegateTaskInput,
@@ -33,6 +35,7 @@ import {
3335
import { Tool, Toolkit } from "effect/ai";
3436

3537
import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
38+
import * as PeerForwarding from "../../../peer/PeerForwarding.ts";
3639
import * as McpInvocationContext from "../../McpInvocationContext.ts";
3740
import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts";
3841
import * as ThreadMetadataMcpService from "../../ThreadMetadataMcpService.ts";
@@ -42,6 +45,8 @@ const dependencies = [
4245
ThreadManagementService.ThreadManagementService,
4346
OrchestratorMcpService.OrchestratorMcpService,
4447
];
48+
/** Tools that also run in a linked environment, when `environmentId` names one. */
49+
const forwardingDependencies = [...dependencies, PeerForwarding.PeerForwarding];
4550
const threadMetadataDependencies = [
4651
McpInvocationContext.McpInvocationContext,
4752
ThreadManagementService.ThreadManagementService,
@@ -50,11 +55,12 @@ const threadMetadataDependencies = [
5055

5156
const OrchestratorCapabilitiesTool = Tool.make("orchestrator_capabilities", {
5257
description:
53-
"List the V2 provider instances and their current models from the same live catalog as the composer, including configured custom models, inherited runtime settings, and app-owned orchestration features available to this caller. For a separate top-level thread in a new or existing worktree, use t3_thread_launch with workspaceStrategy.",
58+
"List the V2 provider instances and their current models from the same live catalog as the composer, including configured custom models, inherited runtime settings, and app-owned orchestration features available to this caller. For a separate top-level thread in a new or existing worktree, use t3_thread_launch with workspaceStrategy. Pass environmentId to list a linked environment's providers instead.",
59+
parameters: OrchestratorMcpCapabilitiesInput,
5460
success: OrchestratorMcpCapabilitiesResult,
5561
failure: OrchestratorMcpFailure,
5662
failureMode: "return",
57-
dependencies,
63+
dependencies: forwardingDependencies,
5864
})
5965
.annotate(Tool.Title, "Get orchestration capabilities")
6066
.annotate(Tool.Readonly, true)
@@ -178,12 +184,12 @@ export const CreateThreadsTool = Tool.make("create_threads", {
178184

179185
const ThreadListTool = Tool.make("t3_thread_list", {
180186
description:
181-
"List T3 threads in a project, newest first. Omit projectId for the calling thread's project. Filter by durable run status, title, or settled state (settled=true lists threads the user or auto-settlement moved out of the active list), or snoozed state, and paginate with the returned cursor. A snoozed thread wakes early when it asks for something, fails, or completes. Each thread has a link: paste it when you mention the thread so the user can open it.",
187+
"List T3 threads in a project, newest first. Omit projectId for the calling thread's project. Pass environmentId to list a linked environment's threads; projectId is then required. Filter by durable run status, title, or settled state (settled=true lists threads the user or auto-settlement moved out of the active list), or snoozed state, and paginate with the returned cursor. A snoozed thread wakes early when it asks for something, fails, or completes. Each thread has a link: paste it when you mention the thread so the user can open it.",
182188
parameters: OrchestratorMcpThreadListInput,
183189
success: OrchestratorMcpThreadListResult,
184190
failure: OrchestratorMcpFailure,
185191
failureMode: "return",
186-
dependencies,
192+
dependencies: forwardingDependencies,
187193
})
188194
.annotate(Tool.Title, "List T3 threads")
189195
.annotate(Tool.Readonly, true)
@@ -192,12 +198,12 @@ const ThreadListTool = Tool.make("t3_thread_list", {
192198

193199
const ThreadReadTool = Tool.make("t3_thread_read", {
194200
description:
195-
"Read durable state and a paginated timeline from any T3 thread in this environment. The default messages view returns user messages, assistant messages, and proposed plans; activity returns all summarized timeline items. Reading an untruncated terminal assistant result from this parent thread's direct app-owned child acknowledges that child's automatic completion delivery. Continue with afterPosition=nextPosition. Recover long item text with itemId and textOffset=nextTextOffset until nextTextOffset is null; offsets count UTF-16 code units. The thread has a link and snooze state: paste the link when you mention the thread so the user can open it.",
201+
"Read durable state and a paginated timeline from any T3 thread in this environment, or in a linked one with environmentId. The default messages view returns user messages, assistant messages, and proposed plans; activity returns all summarized timeline items. Reading an untruncated terminal assistant result from this parent thread's direct app-owned child acknowledges that child's automatic completion delivery. Continue with afterPosition=nextPosition. Recover long item text with itemId and textOffset=nextTextOffset until nextTextOffset is null; offsets count UTF-16 code units. The thread has a link and snooze state: paste the link when you mention the thread so the user can open it.",
196202
parameters: OrchestratorMcpThreadReadInput,
197203
success: OrchestratorMcpThreadReadResult,
198204
failure: OrchestratorMcpFailure,
199205
failureMode: "return",
200-
dependencies,
206+
dependencies: forwardingDependencies,
201207
})
202208
.annotate(Tool.Title, "Read a T3 thread")
203209
.annotate(Tool.Readonly, false)
@@ -219,25 +225,25 @@ export const ThreadUpdateTool = Tool.make("t3_thread_update", {
219225

220226
const ThreadSendTool = Tool.make("t3_thread_send", {
221227
description:
222-
"Send a message to any T3 thread in this environment. The target cannot have broader permission modes than the caller. Do not use a delegated task's childThreadId to start another review round here; use delegate_task with the full review context and a new clientRequestId for that round. Thread messages do not create a new delegated task or reopen a completed task. mode='auto' starts an idle thread, steers a fully active turn, or queues behind a turn that is not yet steerable. Use queue for a separate follow-up turn, steer for an in-flight update, or restart to interrupt-and-restart the active turn. clientRequestId makes retries idempotent.",
228+
"Send a message to any T3 thread in this environment, or in a linked one with environmentId. The target cannot have broader permission modes than the caller. Do not use a delegated task's childThreadId to start another review round here; use delegate_task with the full review context and a new clientRequestId for that round. Thread messages do not create a new delegated task or reopen a completed task. mode='auto' starts an idle thread, steers a fully active turn, or queues behind a turn that is not yet steerable. Use queue for a separate follow-up turn, steer for an in-flight update, or restart to interrupt-and-restart the active turn. clientRequestId makes retries idempotent.",
223229
parameters: OrchestratorMcpThreadSendInput,
224230
success: OrchestratorMcpThreadSendResult,
225231
failure: OrchestratorMcpFailure,
226232
failureMode: "return",
227-
dependencies,
233+
dependencies: forwardingDependencies,
228234
})
229235
.annotate(Tool.Title, "Send to a T3 thread")
230236
.annotate(Tool.Destructive, true)
231237
.annotate(Tool.OpenWorld, true);
232238

233239
const ThreadWaitTool = Tool.make("t3_thread_wait", {
234240
description:
235-
"Wait for a T3 thread run to reach a terminal durable state. Without runId, the latest run at call time is selected; an idle thread returns immediately. Timeout does not interrupt work, so call again or use t3_thread_read/list after timedOut=true. Waiting reports status only and does not acknowledge a delegated result.",
241+
"Wait for a T3 thread run to reach a terminal durable state, here or in a linked environment with environmentId. Without runId, the latest run at call time is selected; an idle thread returns immediately. Timeout does not interrupt work, so call again or use t3_thread_read/list after timedOut=true. Waiting reports status only and does not acknowledge a delegated result.",
236242
parameters: OrchestratorMcpThreadWaitInput,
237243
success: OrchestratorMcpThreadWaitResult,
238244
failure: OrchestratorMcpFailure,
239245
failureMode: "return",
240-
dependencies,
246+
dependencies: forwardingDependencies,
241247
})
242248
.annotate(Tool.Title, "Wait for a T3 thread")
243249
.annotate(Tool.Readonly, true)
@@ -246,16 +252,29 @@ const ThreadWaitTool = Tool.make("t3_thread_wait", {
246252

247253
const ThreadInterruptTool = Tool.make("t3_thread_interrupt", {
248254
description:
249-
"Request interruption of a running turn in any T3 thread in this environment. Without runId, the newest interruptible run is selected. Terminal runs and threads without an active turn return without another side effect. clientRequestId makes retries idempotent.",
255+
"Request interruption of a running turn in any T3 thread in this environment, or in a linked one with environmentId. Without runId, the newest interruptible run is selected. Terminal runs and threads without an active turn return without another side effect. clientRequestId makes retries idempotent.",
250256
parameters: OrchestratorMcpThreadInterruptInput,
251257
success: OrchestratorMcpThreadInterruptResult,
252258
failure: OrchestratorMcpFailure,
253259
failureMode: "return",
254-
dependencies,
260+
dependencies: forwardingDependencies,
255261
})
256262
.annotate(Tool.Title, "Interrupt a T3 thread")
257263
.annotate(Tool.Destructive, true);
258264

265+
const EnvironmentLinksTool = Tool.make("t3_environment_links", {
266+
description:
267+
"List the other T3 Code environments this one is linked to, such as the user's other machines, and whether each answers now. Pass one's environmentId to t3_project_list, t3_thread_launch, t3_thread_list, t3_thread_read, t3_thread_send, t3_thread_wait, t3_thread_interrupt, or orchestrator_capabilities to act there. A linked environment lets this one's agents do at most its access there, and never more than the calling agent may do here. An expired link has to be linked again from a new pairing code.",
268+
success: OrchestratorMcpEnvironmentLinksResult,
269+
failure: OrchestratorMcpFailure,
270+
failureMode: "return",
271+
dependencies: forwardingDependencies,
272+
})
273+
.annotate(Tool.Title, "List linked environments")
274+
.annotate(Tool.Readonly, true)
275+
.annotate(Tool.Destructive, false)
276+
.annotate(Tool.Idempotent, true);
277+
259278
export const OrchestratorToolkit = Toolkit.make(
260279
OrchestratorCapabilitiesTool,
261280
DelegateTaskTool,
@@ -273,4 +292,5 @@ export const OrchestratorToolkit = Toolkit.make(
273292
ThreadSendTool,
274293
ThreadWaitTool,
275294
ThreadInterruptTool,
295+
EnvironmentLinksTool,
276296
);

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import * as ThreadManagement from "../../../orchestration-v2/ThreadManagementSer
2121
import * as ServerConfig from "../../../config.ts";
2222
import * as Project from "../../../project/ProjectService.ts";
2323
import * as ManagedProjectFolders from "../../../project/ManagedProjectFolders.ts";
24+
import * as PeerForwarding from "../../../peer/PeerForwarding.ts";
2425
import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
2526
import * as VcsProcess from "../../../vcs/VcsProcess.ts";
2627
import * as McpInvocationContext from "../../McpInvocationContext.ts";
@@ -77,6 +78,7 @@ it.effect("attributes a launched thread's first message to the calling thread",
7778
},
7879
}),
7980
Layer.mock(Project.ProjectService)({}),
81+
Layer.mock(PeerForwarding.PeerForwarding)({}),
8082
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/projects" }),
8183
Layer.mock(GitVcsDriver.GitVcsDriver)({}),
8284
NodeServices.layer,
@@ -157,6 +159,7 @@ it.effect("launches a scratch thread into the Scratch project", () =>
157159
},
158160
}),
159161
Layer.mock(Project.ProjectService)({}),
162+
Layer.mock(PeerForwarding.PeerForwarding)({}),
160163
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({
161164
namedProjectsRoot: "/projects",
162165
ensureScratchProject: Effect.succeed({ projectId: scratchProjectId }),
@@ -252,6 +255,7 @@ it.effect("starts a project from just a title when workspaceRoot is omitted", ()
252255
projectId === createdProjectId ? Option.some(createdProject) : Option.none(),
253256
),
254257
}),
258+
Layer.mock(PeerForwarding.PeerForwarding)({}),
255259
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({
256260
namedProjectsRoot: "/projects",
257261
createNamedProject: (input) =>
@@ -358,6 +362,7 @@ const clientLaunchHarness = (input: {
358362
: Option.none(),
359363
),
360364
}),
365+
Layer.mock(PeerForwarding.PeerForwarding)({}),
361366
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/projects" }),
362367
NodeServices.layer,
363368
).pipe(

0 commit comments

Comments
 (0)