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
});