The best way to control Claude Code, Codex and more from any computer or phone

main
ts 512 lines 19.5 KB
Raw
1 import { expect, it } from "@effect/vitest";
2 import {
3 EnvironmentId,
4 OrchestratorMcpEnvironmentTarget,
5 OrchestratorMcpFailure,
6 ProviderInstanceId,
7 ProviderInteractionMode,
8 RuntimeMode,
9 ThreadId,
10 } from "@t3tools/contracts";
11 import * as Cause from "effect/Cause";
12 import * as Effect from "effect/Effect";
13 import * as Exit from "effect/Exit";
14 import * as Layer from "effect/Layer";
15 import * as Schema from "effect/Schema";
16 import * as Sink from "effect/Sink";
17 import * as Stream from "effect/Stream";
18 import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
19
20 import { OrchestratorProjectionError } from "../orchestration-v2/Orchestrator.ts";
21 import * as PeerForwarding from "../peer/PeerForwarding.ts";
22 import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
23 import * as McpHttpServer from "./McpHttpServer.ts";
24 import * as McpInvocationContext from "./McpInvocationContext.ts";
25 import * as McpToolAccess from "./McpToolAccess.ts";
26 import { liveThreadShell } from "./McpToolAccess.testkit.ts";
27
28 const supervisedThreadId = ThreadId.make("thread:supervised");
29 const planThreadId = ThreadId.make("thread:plan");
30 const fullAccessThreadId = ThreadId.make("thread:full-access");
31 const endedThreadId = ThreadId.make("thread:ended");
32 const backgroundThreadId = ThreadId.make("thread:background");
33 const oldProviderThreadId = ThreadId.make("thread:old-provider-background");
34 const archivedThreadId = ThreadId.make("thread:archived-background");
35 const unknownOwnerThreadId = ThreadId.make("thread:unknown-background-owner");
36
37 const backgroundShell = (threadId: ThreadId, providerInstanceId: ProviderInstanceId) => ({
38 ...liveThreadShell(threadId, { activeRunId: null }),
39 pendingBackgroundTasks: [
40 { taskId: "task:background", kind: "subagent" as const, providerInstanceId },
41 ],
42 });
43
44 const shells = new Map([
45 [supervisedThreadId, liveThreadShell(supervisedThreadId, { runtimeMode: "approval-required" })],
46 [
47 planThreadId,
48 liveThreadShell(planThreadId, { runtimeMode: "approval-required", interactionMode: "plan" }),
49 ],
50 [fullAccessThreadId, liveThreadShell(fullAccessThreadId)],
51 [endedThreadId, liveThreadShell(endedThreadId, { activeRunId: null })],
52 [backgroundThreadId, backgroundShell(backgroundThreadId, ProviderInstanceId.make("codex"))],
53 [oldProviderThreadId, backgroundShell(oldProviderThreadId, ProviderInstanceId.make("claude"))],
54 [
55 archivedThreadId,
56 {
57 ...backgroundShell(archivedThreadId, ProviderInstanceId.make("codex")),
58 archivedAt: liveThreadShell(archivedThreadId).updatedAt,
59 },
60 ],
61 [
62 unknownOwnerThreadId,
63 {
64 ...liveThreadShell(unknownOwnerThreadId, { activeRunId: null }),
65 pendingBackgroundTasks: [{ taskId: "task:unknown", kind: "subagent" as const }],
66 },
67 ],
68 ]);
69
70 const threadCaller = (threadId: ThreadId): McpInvocationContext.McpInvocationScope => ({
71 environmentId: EnvironmentId.make("environment"),
72 requestNamespace: `provider:${threadId}`,
73 thread: {
74 threadId,
75 providerSessionId: `provider:${threadId}`,
76 providerInstanceId: ProviderInstanceId.make("codex"),
77 },
78 client: undefined,
79 capabilities: new Set(["orchestration"]),
80 issuedAt: 0,
81 });
82
83 const clientCaller = (
84 access: McpInvocationContext.McpClientCaller["access"],
85 ): McpInvocationContext.McpInvocationScope => ({
86 environmentId: EnvironmentId.make("environment"),
87 requestNamespace: "client:session",
88 thread: undefined,
89 client: { sessionId: "session", label: "Claude Code", access },
90 capabilities: new Set(["orchestration"]),
91 issuedAt: 0,
92 });
93
94 const mcpClient = McpSchema.McpServerClient.of({
95 clientId: 1,
96 protocolVersion: "2025-06-18",
97 clientCapabilities: {},
98 clientInfo: { name: "mcp-test", version: "1" },
99 initializePayload: {
100 protocolVersion: "2025-06-18",
101 capabilities: {},
102 clientInfo: { name: "mcp-test", version: "1" },
103 },
104 getClient: Effect.die("unused"),
105 });
106
107 const probe = {
108 success: Schema.Struct({ ran: Schema.String }),
109 failure: OrchestratorMcpFailure,
110 failureMode: "return" as const,
111 dependencies: [
112 McpInvocationContext.McpInvocationContext,
113 ThreadManagement.ThreadManagementService,
114 ],
115 };
116 const ProbeToolkit = Toolkit.make(
117 Tool.make("reads", probe),
118 Tool.make("reads_as_caller", probe).annotate(
119 McpSchema.EnabledWhen,
120 McpInvocationContext.hiddenFromOutsideClients,
121 ),
122 Tool.make("acts_as_caller", probe).annotate(
123 McpSchema.EnabledWhen,
124 McpInvocationContext.hiddenFromOutsideClients,
125 ),
126 Tool.make("writes", probe),
127 Tool.make("writes_with_capability", probe),
128 Tool.make("writes_threads", {
129 ...probe,
130 parameters: Schema.Struct({ threadId: Schema.optional(ThreadId) }),
131 }),
132 Tool.make("starts_threads", {
133 ...probe,
134 parameters: Schema.Struct({
135 runtimeMode: Schema.optional(RuntimeMode),
136 interactionMode: Schema.optional(ProviderInteractionMode),
137 }),
138 }),
139 Tool.make("writes_environment", probe),
140 );
141 const ran = Effect.succeed({ ran: "ran" });
142 const probeHandlers: McpToolAccess.Handlers<typeof ProbeToolkit.tools> = {
143 reads: McpToolAccess.reads(() => ran),
144 reads_as_caller: McpToolAccess.readsAsCaller(() => ran),
145 acts_as_caller: McpToolAccess.actsAsCaller(() => ran),
146 writes: McpToolAccess.writes(() => ran),
147 writes_with_capability: McpToolAccess.writesWithCapability(() => ran),
148 writes_threads: McpToolAccess.writesThreads(
149 (input) => [input.threadId],
150 () => ran,
151 ),
152 starts_threads: McpToolAccess.startsThreads(
153 (input) => input,
154 (_, modes) => Effect.succeed({ ran: `${modes.runtimeMode}/${modes.interactionMode}` }),
155 "stamped",
156 ),
157 writes_environment: McpToolAccess.writesEnvironment(() => ran),
158 };
159 const layerProbeHandlers = McpToolAccess.toLayer(ProbeToolkit, probeHandlers);
160
161 const unchecked = () => ran;
162
163 // `@ts-expect-error` fails the build if one ever compiles. Never called.
164 export const refusedAtCompileTime = () => {
165 McpToolAccess.toLayer(ProbeToolkit, {
166 ...probeHandlers,
167 // @ts-expect-error a handler that skips its declaration
168 reads: unchecked,
169 });
170 McpToolAccess.toLayer(ProbeToolkit, {
171 ...probeHandlers,
172 // @ts-expect-error a declaration's fields copied onto an unchecked handler
173 reads: Object.assign(
174 unchecked,
175 McpToolAccess.reads(() => ran),
176 ),
177 });
178 // @ts-expect-error a declaration built outside McpToolAccess
179 McpToolAccess.Declaration.make(unchecked);
180 // @ts-expect-error a declaration constructed directly
181 new McpToolAccess.Declaration(unchecked); // oxlint-disable-line eslint/no-new -- This type-contract test checks direct construction.
182 // @ts-expect-error a handlers layer built outside McpToolAccess
183 McpToolAccess.HandlersLayer.make(Layer.empty);
184 // @effect-diagnostics-next-line anyUnknownInErrorContext:off
185 McpHttpServer.toolkitRegistration(
186 ProbeToolkit,
187 // @ts-expect-error a handlers layer that skipped `McpToolAccess.toLayer`
188 ProbeToolkit.toLayer({
189 reads: unchecked,
190 reads_as_caller: unchecked,
191 acts_as_caller: unchecked,
192 writes: unchecked,
193 writes_with_capability: unchecked,
194 writes_threads: unchecked,
195 starts_threads: unchecked,
196 writes_environment: unchecked,
197 }),
198 );
199 };
200
201 const probeServer = (threads: Layer.Layer<ThreadManagement.ThreadManagementService>) =>
202 McpHttpServer.toolkitRegistration(ProbeToolkit, layerProbeHandlers).pipe(
203 Layer.provideMerge(McpHttpServer.layerInProcessMcpServer),
204 Layer.provideMerge(threads),
205 );
206
207 const decodeOutcome = Schema.decodeUnknownEffect(
208 Schema.fromJsonString(
209 Schema.Union([Schema.Struct({ ran: Schema.String }), Schema.Struct({ code: Schema.String })]),
210 ),
211 );
212
213 const call = (
214 tool: string,
215 scope: McpInvocationContext.McpInvocationScope,
216 args: Record<string, unknown> = {},
217 ) =>
218 McpServer.McpServer.pipe(
219 Effect.flatMap((server) => server.callTool({ name: tool, arguments: args })),
220 Effect.flatMap(({ content }) =>
221 decodeOutcome(content.map((part) => (part.type === "text" ? part.text : "")).join("")),
222 ),
223 Effect.map((outcome) => ("code" in outcome ? outcome.code : outcome.ran)),
224 Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
225 Effect.provideService(McpSchema.McpServerClient, mcpClient),
226 );
227
228 const supervised = threadCaller(supervisedThreadId);
229 const plan = threadCaller(planThreadId);
230 const fullAccess = threadCaller(fullAccessThreadId);
231 const ended = threadCaller(endedThreadId);
232 const background = threadCaller(backgroundThreadId);
233 const oldProviderBackground = threadCaller(oldProviderThreadId);
234 const archivedBackground = threadCaller(archivedThreadId);
235 const unknownOwnerBackground = threadCaller(unknownOwnerThreadId);
236 const mismatchedProvider = {
237 ...background,
238 thread: { ...background.thread!, providerInstanceId: ProviderInstanceId.make("claude") },
239 };
240 const supervisedClient = clientCaller("approval-required");
241 const fullAccessClient = clientCaller("full-access");
242 const readOnlyClient = clientCaller("read-only");
243 const linkedClient: McpInvocationContext.McpInvocationScope = {
244 ...supervisedClient,
245 client: { ...supervisedClient.client!, linked: true },
246 };
247 // A full-access link's agents can do anything this environment's user can.
248 const fullAccessLinkedClient: McpInvocationContext.McpInvocationScope = {
249 ...fullAccessClient,
250 client: { ...fullAccessClient.client!, linked: true },
251 };
252 const previewOnly = { ...fullAccess, capabilities: new Set(["preview"] as const) };
253
254 it.effect.each([
255 ["reads", ended, {}, "ran"],
256 ["reads", supervisedClient, {}, "ran"],
257 ["reads", readOnlyClient, {}, "ran"],
258
259 ["writes", readOnlyClient, {}, "capability_denied"],
260 ["writes_threads", readOnlyClient, { threadId: supervisedThreadId }, "capability_denied"],
261 ["starts_threads", readOnlyClient, {}, "capability_denied"],
262 ["writes_environment", readOnlyClient, {}, "capability_denied"],
263
264 ["reads_as_caller", ended, {}, "ran"],
265 ["acts_as_caller", supervised, {}, "ran"],
266 ["acts_as_caller", ended, {}, "parent_not_active"],
267 ["acts_as_caller", background, {}, "ran"],
268 ["acts_as_caller", oldProviderBackground, {}, "parent_not_active"],
269 ["acts_as_caller", mismatchedProvider, {}, "parent_not_active"],
270 ["acts_as_caller", archivedBackground, {}, "parent_not_active"],
271 ["acts_as_caller", unknownOwnerBackground, {}, "parent_not_active"],
272
273 ["writes", supervised, {}, "ran"],
274 ["writes", ended, {}, "parent_not_active"],
275 ["writes", background, {}, "ran"],
276 ["writes", oldProviderBackground, {}, "parent_not_active"],
277 ["writes", supervisedClient, {}, "ran"],
278 ["writes", previewOnly, {}, "capability_denied"],
279 ["writes_environment", previewOnly, {}, "capability_denied"],
280
281 ["writes_with_capability", previewOnly, {}, "ran"],
282 ["writes_with_capability", readOnlyClient, {}, "capability_denied"],
283 ["writes_with_capability", ended, {}, "parent_not_active"],
284 ["writes", linkedClient, {}, "capability_denied"],
285 ["writes_with_capability", linkedClient, {}, "capability_denied"],
286 ["writes", fullAccessLinkedClient, {}, "ran"],
287 ["writes_with_capability", fullAccessLinkedClient, {}, "ran"],
288
289 ["writes_threads", supervised, {}, "ran"],
290 ["writes_threads", supervised, { threadId: planThreadId }, "ran"],
291 [
292 "writes_threads",
293 supervised,
294 { threadId: fullAccessThreadId },
295 "runtime_mode_escalation_denied",
296 ],
297 ["writes_threads", plan, { threadId: supervisedThreadId }, "interaction_mode_escalation_denied"],
298 ["writes_threads", fullAccess, { threadId: supervisedThreadId }, "ran"],
299 ["writes_threads", ended, { threadId: supervisedThreadId }, "parent_not_active"],
300 ["writes_threads", supervisedClient, { threadId: supervisedThreadId }, "ran"],
301 [
302 "writes_threads",
303 supervisedClient,
304 { threadId: fullAccessThreadId },
305 "runtime_mode_escalation_denied",
306 ],
307 ["writes_threads", supervised, { threadId: "thread:missing" }, "ran"],
308
309 ["starts_threads", supervised, {}, "approval-required/default"],
310 ["starts_threads", supervised, { runtimeMode: "full-access" }, "runtime_mode_escalation_denied"],
311 ["starts_threads", plan, {}, "approval-required/plan"],
312 ["starts_threads", plan, { interactionMode: "default" }, "interaction_mode_escalation_denied"],
313 ["starts_threads", fullAccess, { runtimeMode: "auto", interactionMode: "plan" }, "auto/plan"],
314 ["starts_threads", ended, {}, "parent_not_active"],
315 ["starts_threads", supervisedClient, {}, "approval-required/default"],
316 ["starts_threads", supervisedClient, { runtimeMode: "auto" }, "runtime_mode_escalation_denied"],
317 ["starts_threads", fullAccessClient, { runtimeMode: "full-access" }, "full-access/default"],
318
319 ["writes_environment", fullAccess, {}, "ran"],
320 ["writes_environment", supervised, {}, "capability_denied"],
321 ["writes_environment", plan, {}, "capability_denied"],
322 ["writes_environment", fullAccessClient, {}, "ran"],
323 ["writes_environment", supervisedClient, {}, "capability_denied"],
324 ] as const)("%s from %o with %o: %s", ([tool, scope, args, expected]) =>
325 call(tool, scope, args).pipe(
326 Effect.map((outcome) => expect(outcome).toBe(expected)),
327 Effect.provide(
328 probeServer(
329 Layer.mock(ThreadManagement.ThreadManagementService)({
330 getThreadShell: (threadId) => Effect.succeed(shells.get(threadId) ?? null),
331 }),
332 ),
333 ),
334 ),
335 );
336
337 it("refuses a declaration or handlers layer that only wears another's fields", () => {
338 const copiedDeclaration = Object.assign(
339 unchecked,
340 McpToolAccess.reads(() => ran),
341 );
342 expect(() =>
343 McpToolAccess.toLayer(ProbeToolkit, {
344 ...probeHandlers,
345 // @ts-expect-error a declaration's fields copied onto an unchecked handler
346 reads: copiedDeclaration,
347 }),
348 ).toThrow(TypeError);
349 const copiedLayer = Object.assign(Layer.empty, layerProbeHandlers);
350 expect(() => McpToolAccess.HandlersLayer.layer(copiedLayer)).toThrow(TypeError);
351 });
352
353 it.effect("refuses a change when the calling thread cannot be read", () =>
354 call("writes", supervised).pipe(
355 Effect.map((outcome) => expect(outcome).toBe("orchestration_error")),
356 Effect.provide(
357 probeServer(
358 Layer.mock(ThreadManagement.ThreadManagementService)({
359 getThreadShell: (threadId) =>
360 Effect.fail(new OrchestratorProjectionError({ threadId, cause: "unreadable" })),
361 }),
362 ),
363 ),
364 ),
365 );
366
367 const box = EnvironmentId.make("environment-box");
368 const here = EnvironmentId.make("environment");
369 const linkedProbe = {
370 ...probe,
371 parameters: Schema.Struct({
372 environmentId: OrchestratorMcpEnvironmentTarget,
373 threadId: Schema.optional(ThreadId),
374 runtimeMode: Schema.optional(RuntimeMode),
375 interactionMode: Schema.optional(ProviderInteractionMode),
376 }),
377 };
378 const LinkedProbeToolkit = Toolkit.make(
379 Tool.make("reads", linkedProbe),
380 Tool.make("writes", linkedProbe),
381 Tool.make("writes_with_capability", linkedProbe),
382 Tool.make("writes_threads", linkedProbe),
383 Tool.make("starts_threads", linkedProbe),
384 Tool.make("writes_environment", linkedProbe),
385 );
386 /** Runs here, and tells whether `environmentId` reached the handler. */
387 const ranHere = <P extends object>(params: P) =>
388 Effect.succeed({ ran: "environmentId" in params ? "saw environmentId" : "here" });
389
390 const linkedProbeServer = McpHttpServer.toolkitRegistration(
391 LinkedProbeToolkit,
392 McpToolAccess.toLayer(LinkedProbeToolkit, {
393 reads: McpToolAccess.reads(ranHere),
394 writes: McpToolAccess.writes(ranHere),
395 writes_with_capability: McpToolAccess.writesWithCapability(ranHere),
396 writes_threads: McpToolAccess.writesThreads((input) => [input.threadId], ranHere),
397 starts_threads: McpToolAccess.startsThreads((input) => input, ranHere, "stamped"),
398 writes_environment: McpToolAccess.writesEnvironment(ranHere),
399 }),
400 ).pipe(
401 Layer.provideMerge(McpHttpServer.layerInProcessMcpServer),
402 Layer.provideMerge(
403 Layer.mock(ThreadManagement.ThreadManagementService)({
404 getThreadShell: (threadId) => Effect.succeed(shells.get(threadId) ?? null),
405 }),
406 ),
407 // Stands in for the linked environment, answering with where the call went.
408 Layer.provide(
409 Layer.mock(PeerForwarding.PeerForwarding)({
410 call: (_scope, tool, environmentId) =>
411 Effect.succeed({ ran: `${tool.name} in ${environmentId}` } as never),
412 }),
413 ),
414 );
415
416 it.effect.each([
417 ["reads", supervised, { environmentId: box }, "reads in environment-box"],
418 ["reads", supervised, { environmentId: here }, "here"],
419 ["reads", supervised, {}, "here"],
420
421 // The caller is checked here before anything goes.
422 ["writes", readOnlyClient, { environmentId: box }, "capability_denied"],
423 ["writes", ended, { environmentId: box }, "parent_not_active"],
424 ["writes", supervised, { environmentId: box }, "writes in environment-box"],
425 ["writes_with_capability", readOnlyClient, { environmentId: box }, "capability_denied"],
426 [
427 "starts_threads",
428 plan,
429 { environmentId: box, interactionMode: "default" },
430 "interaction_mode_escalation_denied",
431 ],
432 ["starts_threads", plan, { environmentId: box }, "starts_threads in environment-box"],
433 ["writes_environment", supervised, { environmentId: box }, "capability_denied"],
434 [
435 "writes_environment",
436 fullAccess,
437 { environmentId: box },
438 "writes_environment in environment-box",
439 ],
440 ["writes_environment", fullAccess, { environmentId: here }, "here"],
441
442 // A thread id names a thread where the call runs, and is checked there.
443 [
444 "writes_threads",
445 supervised,
446 { environmentId: box, threadId: fullAccessThreadId },
447 "writes_threads in environment-box",
448 ],
449 [
450 "writes_threads",
451 supervised,
452 { environmentId: here, threadId: fullAccessThreadId },
453 "runtime_mode_escalation_denied",
454 ],
455 ] as const)("a linked %s from %o with %o: %s", ([tool, scope, args, expected]) =>
456 call(tool, scope, args).pipe(
457 Effect.map((outcome) => expect(outcome).toBe(expected)),
458 Effect.provide(linkedProbeServer),
459 ),
460 );
461
462 it.effect("refuses a linked environment to a tool that acts as its calling thread", () =>
463 Effect.gen(function* () {
464 const CallerToolkit = Toolkit.make(
465 Tool.make("acts_as_caller", linkedProbe).annotate(
466 McpSchema.EnabledWhen,
467 McpInvocationContext.hiddenFromOutsideClients,
468 ),
469 );
470 const built = yield* Layer.build(
471 McpToolAccess.HandlersLayer.layer(
472 McpToolAccess.toLayer(CallerToolkit, {
473 acts_as_caller: McpToolAccess.actsAsCaller(ranHere),
474 }),
475 ),
476 ).pipe(Effect.scoped, Effect.exit);
477 expect(Exit.isFailure(built) && Cause.hasDies(built.cause)).toBe(true);
478 }),
479 );
480
481 // Discovery hides these tools. The handler must refuse on its own if that ever changes.
482 it.effect.each(["reads_as_caller", "acts_as_caller"] as const)(
483 "%s refuses an outside client behind discovery",
484 (tool) =>
485 Effect.gen(function* () {
486 const built = yield* ProbeToolkit;
487 const { result } = yield* built
488 .handle(tool, {})
489 .pipe(Stream.unwrap, Stream.run(Sink.last()), Effect.flatMap(Effect.fromOption));
490 expect(result).toMatchObject({ code: "thread_credential_required" });
491 }).pipe(
492 Effect.provide(McpToolAccess.HandlersLayer.layer(layerProbeHandlers)),
493 Effect.provideService(McpInvocationContext.McpInvocationContext, fullAccessClient),
494 Effect.provide(Layer.mock(ThreadManagement.ThreadManagementService)({})),
495 ),
496 );
497
498 it.effect("refuses to build a thread-bound tool that outside clients would be offered", () =>
499 Effect.gen(function* () {
500 const CallerToolkit = Toolkit.make(Tool.make("reads_as_caller", probe));
501 const built = yield* Layer.build(
502 McpToolAccess.HandlersLayer.layer(
503 McpToolAccess.toLayer(CallerToolkit, {
504 reads_as_caller: McpToolAccess.readsAsCaller(() => ran),
505 }),
506 ),
507 ).pipe(Effect.scoped, Effect.exit);
508 expect(Exit.isFailure(built) && Cause.pretty(built.cause)).toContain(
509 "reads_as_caller acts as its calling thread",
510 );
511 }),
512 );