@devries-cameron20 / t3code-1 / commits / e49d058439
Fork 0

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

fix(server): thread_not_found points agents at linked environments (#31946)

Julius Marminge committed Nov 14, 2026 at 19:06 UTC e49d05843960cb846612ea37a10e34d0b552a63a
8 files changed +115 -19
apps/server/src/mcp/OrchestratorMcpService.test.ts
+1
@@ -4290,6 +4290,7 @@ describe("OrchestratorMcpService thread lookup", () => {
4290 client: { sessionId: "thread-lookup", label: "Claude Code", access: "full-access" },
4291 capabilities: new Set(["orchestration"]),
4292 issuedAt: 1,
4293 + linkedEnvironments: false,
4294 };
4295 const service = (
4296 shells: ReadonlyArray<OrchestrationV2ThreadShell>,
apps/server/src/mcp/OrchestratorMcpService.ts
+9 -2
@@ -1321,13 +1321,19 @@ const make = Effect.gen(function* () {
1321 : Effect.fail(failure("target_required", missingMessage));
1322
1323 const loadTargetThread = Effect.fn("OrchestratorMcpService.loadTargetThread")(function* (
1324 + scope: McpInvocationScope,
1325 threadId: ThreadId,
1326 ) {
1327 const shell = yield* threadManagement
1328 .getThreadShell(threadId)
1329 .pipe(Effect.mapError(threadManagementFailure));
1330 if (shell === null || shell.deletedAt !== null) {
1330 - return yield* threadNotFound(threadManagement, threadId, `Thread ${threadId} was not found.`);
1331 + return yield* threadNotFound(
1332 + threadManagement,
1333 + scope,
1334 + threadId,
1335 + `Thread ${threadId} was not found.`,
1336 + );
1337 }
1338 // Keeps legacy import and project validation; callers read only the thread row.
1339 return yield* threadManagement
@@ -1343,7 +1349,7 @@ const make = Effect.gen(function* () {
1349 const target: Pick<OrchestrationV2ThreadProjection, "thread"> =
1350 caller.parent !== undefined && threadId === caller.parent.thread.id
1351 ? caller.parent
1346 - : yield* loadTargetThread(threadId);
1352 + : yield* loadTargetThread(scope, threadId);
1353 return { ...caller, target } as const;
1354 });
1355
@@ -1404,6 +1410,7 @@ const make = Effect.gen(function* () {
1410 if (shell === null || shell.deletedAt !== null) {
1411 return yield* threadNotFound(
1412 threadManagement,
1413 + scope,
1414 threadId,
1415 `Thread ${threadId} is no longer available.`,
1416 );
apps/server/src/mcp/ThreadMetadataMcpService.ts
+6 -1
@@ -142,7 +142,12 @@ const make = Effect.gen(function* () {
142 ),
143 );
144 if (shell === null || shell.deletedAt !== null) {
145 - return yield* threadNotFound(threadManagement, threadId, `Thread ${threadId} was not found.`);
145 + return yield* threadNotFound(
146 + threadManagement,
147 + scope,
148 + threadId,
149 + `Thread ${threadId} was not found.`,
150 + );
151 }
152 const requestKey =
153 input.clientRequestId === undefined ? yield* random.uuidV4() : input.clientRequestId;
apps/server/src/mcp/linkOrigin.ts
+1 -1
@@ -29,7 +29,7 @@ export const callerLinkOrigin = (
29 : undefined);
30
31 /** The link that fences a caller, if any: one paired below full access. */
32 -const fencingLinkOrigin = (caller: Pick<Caller, "scope" | "caller">) => {
32 +export const fencingLinkOrigin = (caller: Pick<Caller, "scope" | "caller">) => {
33 const origin = callerLinkOrigin(caller);
34 return origin !== undefined && linkOriginIsFenced(origin) ? origin : undefined;
35 };
apps/server/src/mcp/threadAccess.test.ts
+70 -7
@@ -1,5 +1,10 @@
1 import { expect, it } from "@effect/vitest";
2 -import { EnvironmentId, ThreadId } from "@t3tools/contracts";
2 +import {
3 + EnvironmentId,
4 + type OrchestrationV2ThreadShell,
5 + ProviderInstanceId,
6 + ThreadId,
7 +} from "@t3tools/contracts";
8 import * as Effect from "effect/Effect";
9 import * as Layer from "effect/Layer";
10
@@ -9,32 +14,90 @@ import { liveThreadShell } from "./McpToolAccess.testkit.ts";
14 import { readThread } from "./threadAccess.ts";
15
16 const bareId = ThreadId.make("5d0b4a3e-8c1f-4a52-9d37-2f6c7e1b9a04");
17 +const claudeCode: McpInvocationContext.McpClientCaller = {
18 + sessionId: "thread-access",
19 + label: "Claude Code",
20 + access: "full-access",
21 +};
22 const client: McpInvocationContext.McpInvocationScope = {
23 environmentId: EnvironmentId.make("environment:thread-access"),
24 requestNamespace: "client:thread-access",
25 thread: undefined,
16 - client: { sessionId: "thread-access", label: "Claude Code", access: "full-access" },
26 + client: claudeCode,
27 capabilities: new Set(["orchestration"]),
28 issuedAt: 1,
29 };
30
21 -const readBare = (existing: ReadonlyArray<ThreadId>) =>
22 - readThread(bareId).pipe(
31 +const linksHint =
32 + "Thread ids belong to one environment: for a thread on a linked one, find it with `t3_environment_links` and pass its `environmentId` to a tool that takes one.";
33 +
34 +const readBare = (
35 + existing: ReadonlyArray<OrchestrationV2ThreadShell | ThreadId>,
36 + scope: McpInvocationContext.McpInvocationScope = client,
37 +) => {
38 + const shells = existing.map((shell) =>
39 + typeof shell === "string" ? liveThreadShell(shell) : shell,
40 + );
41 + return readThread(bareId).pipe(
42 Effect.flip,
24 - Effect.provideService(McpInvocationContext.McpInvocationContext, client),
43 + Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
44 Effect.provide(
45 Layer.mock(ThreadManagement.ThreadManagementService)({
46 getThreadShell: (threadId) =>
28 - Effect.succeed(existing.includes(threadId) ? liveThreadShell(threadId) : null),
47 + Effect.succeed(shells.find((shell) => shell.id === threadId) ?? null),
48 }),
49 ),
50 );
51 +};
52
53 it.effect("points a bare uuid at the mcp: thread it belongs to", () =>
54 Effect.gen(function* () {
55 const error = yield* readBare([ThreadId.make(`mcp:${bareId}`)]);
56
57 expect(error.code).toBe("thread_not_found");
38 - expect(error.message).toBe(`The thread was not found. Did you mean \`mcp:${bareId}\`?`);
58 + expect(error.message).toBe(
59 + `The thread was not found. Did you mean \`mcp:${bareId}\`? ${linksHint}`,
60 + );
61 + }),
62 +);
63 +
64 +it.effect("tells a caller with linked environments that the thread may be on one of them", () =>
65 + Effect.gen(function* () {
66 + const error = yield* readBare([], { ...client, linkedEnvironments: true });
67 +
68 + expect(error.code).toBe("thread_not_found");
69 + expect(error.message).toContain("t3_environment_links");
70 + expect(error.message).toContain("environmentId");
71 +
72 + const linksOff = yield* readBare([], { ...client, linkedEnvironments: false });
73 + expect(linksOff.message).toBe("The thread was not found.");
74 + const peerLink = yield* readBare([], {
75 + ...client,
76 + linkedEnvironments: true,
77 + client: { ...claudeCode, linked: true },
78 + });
79 + expect(peerLink.message).toBe("The thread was not found.");
80 +
81 + // A thread a fenced link started may not use this environment's links.
82 + const fencedThread = ThreadId.make("thread:started-by-fenced-link");
83 + const fenced = yield* readBare(
84 + [
85 + {
86 + ...liveThreadShell(fencedThread),
87 + linkOrigin: { sessionId: "peer-session", label: "Laptop", access: "auto" },
88 + },
89 + ],
90 + {
91 + ...client,
92 + linkedEnvironments: true,
93 + client: undefined,
94 + thread: {
95 + threadId: fencedThread,
96 + providerSessionId: "provider-session",
97 + providerInstanceId: ProviderInstanceId.make("codex"),
98 + },
99 + },
100 + );
101 + expect(fenced.message).toBe("The thread was not found.");
102 }),
103 );
apps/server/src/mcp/threadAccess.ts
+23 -5
@@ -18,26 +18,39 @@ import * as Effect from "effect/Effect";
18 import type { OrchestratorV2Error } from "../orchestration-v2/Orchestrator.ts";
19 import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
20 import { resolveInteractionMode, resolveRuntimeMode } from "./delegatedTaskModes.ts";
21 +import { fencingLinkOrigin } from "./linkOrigin.ts";
22 import * as McpInvocationContext from "./McpInvocationContext.ts";
23
24 /**
25 * Threads an agent starts over MCP are `mcp:<uuid>`, and agents often paste the
26 * bare uuid. The id is never rewritten, so permission checks keyed on it still
27 * hold; the miss only names a live thread the caller could read by its full id.
28 + * Ids from another machine miss here too. The link hint is static: listing links probes peers.
29 */
30 export const threadNotFound = Effect.fn("OrchestratorMcpService.threadNotFound")(function* (
31 threads: Pick<ThreadManagement.ThreadManagementService["Service"], "getThreadShell">,
32 + scope: McpInvocationContext.McpInvocationScope,
33 threadId: ThreadId,
34 message: string,
35 ) {
36 const prefixed = ThreadId.make(`mcp:${threadId}`);
37 const shell = yield* threads.getThreadShell(prefixed).pipe(Effect.orElseSucceed(() => null));
38 + const mcpHint =
39 + shell === null || shell.deletedAt !== null ? "" : ` Did you mean \`${prefixed}\`?`;
40 + const caller =
41 + scope.thread === undefined
42 + ? null
43 + : yield* threads.getThreadShell(scope.thread.threadId).pipe(Effect.orElseSucceed(() => null));
44 + // A peer link's caller would be pointed at this machine's links, and a fenced one may not use them.
45 + const linksHint =
46 + scope.linkedEnvironments === false ||
47 + scope.client?.linked === true ||
48 + fencingLinkOrigin({ scope, caller: caller ?? undefined }) !== undefined
49 + ? ""
50 + : " Thread ids belong to one environment: for a thread on a linked one, find it with `t3_environment_links` and pass its `environmentId` to a tool that takes one.";
51 return yield* new OrchestratorMcpFailure({
52 code: "thread_not_found",
37 - message:
38 - shell === null || shell.deletedAt !== null
39 - ? message
40 - : `${message} Did you mean \`${prefixed}\`?`,
53 + message: `${message}${mcpHint}${linksHint}`,
54 });
55 });
56
@@ -190,7 +203,12 @@ export const readThread = Effect.fn("mcp.readThread")(function* <
203 const targetId = yield* resolveThreadId(context, threadId);
204 const shell = yield* context.threads.getThreadShell(targetId).pipe(Effect.mapError(unavailable));
205 if (shell === null || shell.deletedAt !== null) {
193 - return yield* threadNotFound(context.threads, targetId, "The thread was not found.");
206 + return yield* threadNotFound(
207 + context.threads,
208 + context.scope,
209 + targetId,
210 + "The thread was not found.",
211 + );
212 }
213 const projection = yield* context.threads
214 .getProjectThreadRecords({ projectId: shell.projectId, threadId: targetId }, fields, {
apps/server/src/mcp/toolkits/pullRequests/handlers.test.ts
+3 -1
@@ -248,7 +248,9 @@ describe("pull request toolkit handlers", () => {
248 const error = yield* harness
249 .call("link_pull_request", { threadId: bareId, number: 123 })
250 .pipe(Effect.flip);
251 - expect(error.message).toBe(`Thread ${bareId} was not found. Did you mean \`mcp:${bareId}\`?`);
251 + expect(error.message).toBe(
252 + `Thread ${bareId} was not found. Did you mean \`mcp:${bareId}\`? Thread ids belong to one environment: for a thread on a linked one, find it with \`t3_environment_links\` and pass its \`environmentId\` to a tool that takes one.`,
253 + );
254 expect(error).toMatchObject({ _tag: "OrchestratorMcpFailure", code: "thread_not_found" });
255 expect(yield* Ref.get(harness.commands)).toEqual([]);
256 }),
apps/server/src/mcp/toolkits/pullRequests/handlers.ts
+2 -2
@@ -174,7 +174,7 @@ const make = Effect.gen(function* () {
174 Effect.mapError((cause) => new Failure({ cause })),
175 );
176 if (Option.isNone(thread) || thread.value.deletedAt !== null) {
177 - return yield* threadNotFound(engine, threadId, `Thread ${threadId} was not found.`);
177 + return yield* threadNotFound(engine, scope, threadId, `Thread ${threadId} was not found.`);
178 }
179 return thread.value;
180 });
@@ -208,7 +208,7 @@ const make = Effect.gen(function* () {
208 return yield* watches.setWatching({ threadId, target: input, watching }).pipe(
209 Effect.catchTags({
210 PullRequestWatchThreadNotFoundError: (error) =>
211 - threadNotFound(engine, error.threadId, error.message),
211 + threadNotFound(engine, scope, error.threadId, error.message),
212 }),
213 );
214 });