Skip to content

Commit f20267f

Browse files
committed
fix(mcp): point a bare thread uuid at its mcp: thread in thread_not_found
Threads started over MCP get ids like mcp:<uuid>, but agents often pass the bare uuid, and thread_not_found gave no hint about the prefix. When an id matches nothing, the error now says "Did you mean `mcp:<id>`?" if that thread exists and is not deleted. The id is never rewritten, so lookups, mode limits and write checks behave exactly as before.
1 parent 05696c6 commit f20267f

5 files changed

Lines changed: 158 additions & 7 deletions

File tree

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2204,3 +2204,79 @@ describe("OrchestratorMcpService provider resolution", () => {
22042204
);
22052205
});
22062206
});
2207+
2208+
describe("OrchestratorMcpService thread lookup", () => {
2209+
const bareId = ThreadId.make("5d0b4a3e-8c1f-4a52-9d37-2f6c7e1b9a04");
2210+
const launched = liveThreadShell(ThreadId.make(`mcp:${bareId}`));
2211+
const deletedLaunched = { ...launched, deletedAt: DateTime.makeUnsafe("2026-10-05T00:00:00Z") };
2212+
const client: McpInvocationScope = {
2213+
environmentId: EnvironmentId.make("environment:thread-lookup"),
2214+
requestNamespace: "client:thread-lookup",
2215+
thread: undefined,
2216+
client: { sessionId: "thread-lookup", label: "Claude Code", access: "full-access" },
2217+
capabilities: new Set(["orchestration"]),
2218+
issuedAt: 1,
2219+
};
2220+
const service = (shells: ReadonlyArray<OrchestrationV2ThreadShell>, sent: Ref.Ref<number>) =>
2221+
layerOrchestratorService.pipe(
2222+
Layer.provide(
2223+
Layer.mergeAll(
2224+
NodeServices.layer,
2225+
Layer.mock(ThreadManagementService.ThreadManagementService)({
2226+
getThreadShell: (threadId) =>
2227+
Effect.succeed(shells.find((shell) => shell.id === threadId) ?? null),
2228+
sendToThread: () => Ref.update(sent, (count) => count + 1).pipe(Effect.as({} as never)),
2229+
}),
2230+
ServerSettings.layerTest(),
2231+
Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
2232+
Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
2233+
list: () => Effect.succeed([]),
2234+
}),
2235+
Layer.mock(ProjectService.ProjectService)({}),
2236+
Layer.mock(SecretRequests.SecretRequests)({}),
2237+
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2238+
),
2239+
),
2240+
);
2241+
const failuresFor = (shells: ReadonlyArray<OrchestrationV2ThreadShell>) =>
2242+
Effect.gen(function* () {
2243+
const sent = yield* Ref.make(0);
2244+
return yield* Effect.gen(function* () {
2245+
const mcp = yield* OrchestratorMcpService.OrchestratorMcpService;
2246+
const read = yield* mcp.readThread(client, { threadId: bareId }).pipe(Effect.flip);
2247+
const send = yield* mcp
2248+
.sendToThread(client, { threadId: bareId, message: "hello" })
2249+
.pipe(Effect.flip);
2250+
return { read, send, sends: yield* Ref.get(sent) };
2251+
}).pipe(Effect.provide(service(shells, sent)));
2252+
});
2253+
2254+
it.effect("points a bare uuid at the mcp: thread it belongs to", () =>
2255+
Effect.gen(function* () {
2256+
const { read, send, sends } = yield* failuresFor([launched]);
2257+
for (const error of [read, send]) {
2258+
assert.equal(error.code, "thread_not_found");
2259+
assert.include(error.message, `mcp:${bareId}`);
2260+
}
2261+
assert.equal(sends, 0);
2262+
}),
2263+
);
2264+
2265+
it.effect("keeps the plain message for an id that matches nothing", () =>
2266+
Effect.gen(function* () {
2267+
const { read, send } = yield* failuresFor([]);
2268+
assert.equal(read.code, "thread_not_found");
2269+
assert.equal(read.message, `Thread ${bareId} is no longer available.`);
2270+
assert.equal(send.code, "thread_not_found");
2271+
assert.equal(send.message, `Thread ${bareId} was not found.`);
2272+
}),
2273+
);
2274+
2275+
it.effect("does not name an mcp: thread that was deleted", () =>
2276+
Effect.gen(function* () {
2277+
const { read, send } = yield* failuresFor([deletedLaunched]);
2278+
assert.equal(read.message, `Thread ${bareId} is no longer available.`);
2279+
assert.equal(send.message, `Thread ${bareId} was not found.`);
2280+
}),
2281+
);
2282+
});

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

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,26 @@ export const isLiveCallerShell = (
231231
) ??
232232
false));
233233

234+
/**
235+
* Threads an agent starts over MCP are `mcp:<uuid>`, and agents often paste the
236+
* bare uuid. The id is never rewritten, so permission checks keyed on it still
237+
* hold; the miss only names a live thread the caller could read by its full id.
238+
*/
239+
export const threadNotFound = Effect.fn("OrchestratorMcpService.threadNotFound")(function* (
240+
threads: Pick<ThreadManagementService.ThreadManagementService["Service"], "getThreadShell">,
241+
threadId: ThreadId,
242+
message: string,
243+
) {
244+
const prefixed = ThreadId.make(`mcp:${threadId}`);
245+
const shell = yield* threads.getThreadShell(prefixed).pipe(Effect.orElseSucceed(() => null));
246+
return yield* failure(
247+
"thread_not_found",
248+
shell === null || shell.deletedAt !== null
249+
? message
250+
: `${message} Did you mean \`${prefixed}\`?`,
251+
);
252+
});
253+
234254
function threadManagementFailure(error: unknown): OrchestratorMcpFailure {
235255
if (!isThreadManagementError(error)) return failure("orchestration_error", errorMessage(error));
236256
switch (error._tag) {
@@ -1123,7 +1143,7 @@ const make = Effect.gen(function* () {
11231143
.getThreadShell(threadId)
11241144
.pipe(Effect.mapError(threadManagementFailure));
11251145
if (shell === null || shell.deletedAt !== null) {
1126-
return yield* failure("thread_not_found", `Thread ${threadId} was not found.`);
1146+
return yield* threadNotFound(threadManagement, threadId, `Thread ${threadId} was not found.`);
11271147
}
11281148
return yield* loadProjectThread(shell.projectId, threadId);
11291149
});
@@ -1198,7 +1218,11 @@ const make = Effect.gen(function* () {
11981218
.getThreadShell(threadId)
11991219
.pipe(Effect.mapError(threadManagementFailure));
12001220
if (shell === null || shell.deletedAt !== null) {
1201-
return yield* failure("thread_not_found", `Thread ${threadId} is no longer available.`);
1221+
return yield* threadNotFound(
1222+
threadManagement,
1223+
threadId,
1224+
`Thread ${threadId} is no longer available.`,
1225+
);
12021226
}
12031227
const target = yield* threadManagement
12041228
.getProjectThreadRecords({ projectId: shell.projectId, threadId }, [

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import * as Layer from "effect/Layer";
1616

1717
import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
1818
import type { McpInvocationScope } from "./McpInvocationContext.ts";
19+
import { threadNotFound } from "./OrchestratorMcpService.ts";
1920

2021
export class ThreadMetadataMcpService extends Context.Service<
2122
ThreadMetadataMcpService,
@@ -167,7 +168,7 @@ const make = Effect.gen(function* () {
167168
),
168169
);
169170
if (shell === null || shell.deletedAt !== null) {
170-
return yield* failure("thread_not_found", `Thread ${threadId} was not found.`);
171+
return yield* threadNotFound(threadManagement, threadId, `Thread ${threadId} was not found.`);
171172
}
172173
const target = yield* threadManagement
173174
.getProjectThreadRecords({ projectId: shell.projectId, threadId }, [])
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import { expect, it } from "@effect/vitest";
2+
import { EnvironmentId, ThreadId } from "@t3tools/contracts";
3+
import * as Effect from "effect/Effect";
4+
import * as Layer from "effect/Layer";
5+
6+
import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
7+
import * as McpInvocationContext from "./McpInvocationContext.ts";
8+
import { liveThreadShell } from "./McpToolAccess.testkit.ts";
9+
import { readThread } from "./threadAccess.ts";
10+
11+
const bareId = ThreadId.make("5d0b4a3e-8c1f-4a52-9d37-2f6c7e1b9a04");
12+
const client: McpInvocationContext.McpInvocationScope = {
13+
environmentId: EnvironmentId.make("environment:thread-access"),
14+
requestNamespace: "client:thread-access",
15+
thread: undefined,
16+
client: { sessionId: "thread-access", label: "Claude Code", access: "full-access" },
17+
capabilities: new Set(["orchestration"]),
18+
issuedAt: 1,
19+
};
20+
21+
const readBare = (existing: ReadonlyArray<ThreadId>) =>
22+
readThread(bareId).pipe(
23+
Effect.flip,
24+
Effect.provideService(McpInvocationContext.McpInvocationContext, client),
25+
Effect.provide(
26+
Layer.mock(ThreadManagement.ThreadManagementService)({
27+
getThreadShell: (threadId) =>
28+
Effect.succeed(existing.includes(threadId) ? liveThreadShell(threadId) : null),
29+
}),
30+
),
31+
);
32+
33+
it.effect("points a bare uuid at the mcp: thread it belongs to", () =>
34+
Effect.gen(function* () {
35+
const error = yield* readBare([ThreadId.make(`mcp:${bareId}`)]);
36+
37+
expect(error.code).toBe("thread_not_found");
38+
expect(error.message).toBe(`The thread was not found. Did you mean \`mcp:${bareId}\`?`);
39+
}),
40+
);
41+
42+
it.effect("keeps the plain message for an id that matches nothing", () =>
43+
Effect.gen(function* () {
44+
const error = yield* readBare([]);
45+
46+
expect(error.code).toBe("thread_not_found");
47+
expect(error.message).toBe("The thread was not found.");
48+
}),
49+
);

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -156,10 +156,11 @@ export const readThread = Effect.fn("mcp.readThread")(function* <
156156
const targetId = yield* resolveThreadId(context, threadId);
157157
const shell = yield* context.threads.getThreadShell(targetId).pipe(Effect.mapError(unavailable));
158158
if (shell === null || shell.deletedAt !== null) {
159-
return yield* new OrchestratorMcpFailure({
160-
code: "thread_not_found",
161-
message: "The thread was not found.",
162-
});
159+
return yield* OrchestrationMcp.threadNotFound(
160+
context.threads,
161+
targetId,
162+
"The thread was not found.",
163+
);
163164
}
164165
const projection = yield* context.threads
165166
.getProjectThreadRecords({ projectId: shell.projectId, threadId: targetId }, fields, {

0 commit comments

Comments
 (0)