Skip to content

Commit d2bcefc

Browse files
t3dotggclaude
andcommitted
feat(server): thread tools return a ready t3-thread link
Agents often write bare ids or URL-encoded ids instead of [title](t3-thread://v1/<threadId>). Thread-returning MCP tools now include a `link` field built with formatThreadLink, and the long link rule in tool descriptions shrinks to "Mention a thread with its `link`." Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 15702a9 commit d2bcefc

11 files changed

Lines changed: 47 additions & 14 deletions

File tree

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ describe("OrchestratorMcpService", () => {
8989
],
9090
} as unknown as OrchestrationV2ThreadProjection;
9191
const childProjection = {
92-
thread: { id: childThreadId },
92+
thread: { id: childThreadId, title: "Child" },
9393
runs: [
9494
{
9595
id: childRunId,
@@ -223,7 +223,7 @@ describe("OrchestratorMcpService", () => {
223223
],
224224
} as unknown as OrchestrationV2ThreadProjection;
225225
const childProjection = {
226-
thread: { id: childThreadId },
226+
thread: { id: childThreadId, title: "Child" },
227227
runs: [
228228
{
229229
id: RunId.make("run:mcp-restart-child"),
@@ -316,7 +316,7 @@ describe("OrchestratorMcpService", () => {
316316
],
317317
} as unknown as OrchestrationV2ThreadProjection;
318318
const childProjection = {
319-
thread: { id: childThreadId },
319+
thread: { id: childThreadId, title: "Child" },
320320
runs: [],
321321
contextTransfers: [],
322322
messages: [],
@@ -400,7 +400,7 @@ describe("OrchestratorMcpService", () => {
400400
}) as unknown as OrchestrationV2ThreadProjection;
401401
// A finished run whose binding to the follow-up was lost.
402402
const childProjection = {
403-
thread: { id: childThreadId },
403+
thread: { id: childThreadId, title: "Child" },
404404
runs:
405405
childState === "no runs"
406406
? []
@@ -503,7 +503,7 @@ describe("OrchestratorMcpService", () => {
503503
],
504504
} as unknown as OrchestrationV2ThreadProjection;
505505
const childProjection = {
506-
thread: { id: childThreadId },
506+
thread: { id: childThreadId, title: "Child" },
507507
runs: [{ id: childRunId, status: "running" }],
508508
contextTransfers: [],
509509
messages: [],
@@ -583,7 +583,7 @@ describe("OrchestratorMcpService", () => {
583583
],
584584
} as unknown as OrchestrationV2ThreadProjection;
585585
const childProjection = {
586-
thread: { id: childThreadId },
586+
thread: { id: childThreadId, title: "Child" },
587587
runs: [{ id: childRunId, status: "running" }],
588588
contextTransfers: [],
589589
messages: [],
@@ -669,7 +669,7 @@ describe("OrchestratorMcpService", () => {
669669
],
670670
} as unknown as OrchestrationV2ThreadProjection;
671671
const childProjection = {
672-
thread: { id: childThreadId },
672+
thread: { id: childThreadId, title: "Child" },
673673
runs: [{ id: childRunId, status: "running" }],
674674
contextTransfers: [],
675675
messages: [],
@@ -764,7 +764,7 @@ describe("OrchestratorMcpService", () => {
764764
[
765765
childThreadId,
766766
{
767-
thread: { id: childThreadId },
767+
thread: { id: childThreadId, title: "Child" },
768768
runs: [{ id: RunId.make("run:mcp-cancel-grandchild-child"), status: "running" }],
769769
contextTransfers: [],
770770
messages: [],
@@ -992,7 +992,7 @@ describe("OrchestratorMcpService provider resolution", () => {
992992
}) as unknown as OrchestrationV2ThreadProjection;
993993

994994
const childProjection = {
995-
thread: { id: childThreadId },
995+
thread: { id: childThreadId, title: "Child" },
996996
runs: [],
997997
contextTransfers: [],
998998
messages: [],

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ import {
6767
} from "@t3tools/contracts";
6868
import { getProviderOptionCurrentValue } from "@t3tools/shared/model";
6969
import { runRanAfter } from "@t3tools/shared/orchestrationV2ThreadError";
70+
import { formatThreadLink } from "@t3tools/shared/threadLinks";
7071
import {
7172
normalizeThreadPullRequestKey,
7273
visibleThreadPullRequests,
@@ -855,6 +856,7 @@ function listItemFromShell(
855856
return {
856857
threadId: shell.id,
857858
title: shell.title,
859+
link: formatThreadLink(shell.id, shell.title),
858860
createdBy: shell.createdBy,
859861
creationSource: shell.creationSource,
860862
status: shell.activityRunStatus ?? shell.status,
@@ -887,6 +889,7 @@ function threadDetail(
887889
threadId: projection.thread.id,
888890
projectId: projection.thread.projectId,
889891
title: projection.thread.title,
892+
link: formatThreadLink(projection.thread.id, projection.thread.title),
890893
createdBy: projection.thread.createdBy,
891894
creationSource: projection.thread.creationSource,
892895
status: active?.status ?? latest?.status ?? "idle",
@@ -1597,6 +1600,7 @@ const make = Effect.gen(function* () {
15971600
const response = {
15981601
taskId: task.id,
15991602
childThreadId: task.childThreadId,
1603+
link: formatThreadLink(task.childThreadId, childControls.thread.title),
16001604
childRunId: childRun?.id ?? null,
16011605
childNodeId: task.id,
16021606
status,
@@ -2648,6 +2652,7 @@ const make = Effect.gen(function* () {
26482652
);
26492653
return {
26502654
threadId,
2655+
link: formatThreadLink(threadId, projection.thread.title),
26512656
runId: run?.id ?? null,
26522657
status: run?.status ?? "idle",
26532658
title: projection.thread.title,
@@ -2839,6 +2844,7 @@ const make = Effect.gen(function* () {
28392844
);
28402845
return {
28412846
threadId: input.threadId,
2847+
link: formatThreadLink(input.threadId, target.thread.title),
28422848
messageId,
28432849
runId: result.run.id,
28442850
...(result.run.delegatedTaskId === undefined ? {} : { taskId: result.run.delegatedTaskId }),

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ const CreateThreadsTool = Tool.make("create_threads", {
214214

215215
const ThreadListTool = Tool.make("t3_thread_list", {
216216
description:
217-
"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 only when it asks for something or fails after snoozing; completed runs and background wakes keep it snoozed. pullRequests lists every pull request linked to each thread; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. To link a thread for the user, write `[title](t3-thread://v1/<threadId>)` with the threadId exactly as returned, not URL-encoded; T3 Code shows the thread's current title.",
217+
"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 only when it asks for something or fails after snoozing; completed runs and background wakes keep it snoozed. pullRequests lists every pull request linked to each thread; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. Mention a thread with its `link`.",
218218
parameters: OrchestratorMcpThreadListInput,
219219
success: OrchestratorMcpThreadListResult,
220220
failure: OrchestratorMcpFailure,
@@ -228,7 +228,7 @@ const ThreadListTool = Tool.make("t3_thread_list", {
228228

229229
const ThreadReadTool = Tool.make("t3_thread_read", {
230230
description:
231-
"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 also reports its snooze state and, in pullRequests, every linked pull request; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. To link a thread for the user, write `[title](t3-thread://v1/<threadId>)` with the threadId exactly as returned, not URL-encoded; T3 Code shows the thread's current title.",
231+
"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 also reports its snooze state and, in pullRequests, every linked pull request; linkedPullRequest is a legacy single link and can be null while pullRequests still has entries. Mention a thread with its `link`.",
232232
parameters: OrchestratorMcpThreadReadInput,
233233
success: OrchestratorMcpThreadReadResult,
234234
failure: OrchestratorMcpFailure,

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ const clientLaunchHarness = (input: {
8181
thread: {
8282
id: launch.threadId,
8383
projectId: launch.projectId,
84+
title: launch.title,
8485
modelSelection: launch.modelSelection,
8586
},
8687
runs: [],
@@ -159,6 +160,7 @@ it.effect(
159160
expect(belowCeiling.result).toMatchObject({
160161
projectId: belowCeiling.projectId,
161162
modelSelection: belowCeiling.modelSelection,
163+
link: `[Fix](t3-thread://v1/${belowCeiling.launched[0]?.threadId})`,
162164
});
163165
expect(belowCeiling.launched[0]?.runtimeMode).toBe("approval-required");
164166
expect(belowCeiling.launched[0]?.initialMessage?.senderThreadId).toBeUndefined();

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import * as Repositories from "../../../sourceControl/SourceControlRepositorySer
1111
import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
1212
import * as ServerSettings from "../../../serverSettings.ts";
1313
import { resolveProjectSettings } from "@t3tools/shared/projectSettings";
14+
import { formatThreadLink } from "@t3tools/shared/threadLinks";
1415
import { resolveRuntimeMode } from "../../OrchestratorMcpService.ts";
1516
import * as McpToolAccess from "../../McpToolAccess.ts";
1617
import { newCommandId, readCaller, resolveProjectId, unavailable } from "../../threadAccess.ts";
@@ -197,6 +198,7 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
197198
const run = result.projection.runs.find((run) => run.userMessageId === messageId);
198199
return {
199200
threadId: thread.id,
201+
link: formatThreadLink(thread.id, thread.title),
200202
projectId: thread.projectId,
201203
modelSelection: thread.modelSelection,
202204
runId: run?.id ?? null,

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", {
104104
const ThreadLaunchTool = Tool.make("t3_thread_launch", {
105105
...shared,
106106
description:
107-
'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. To fetch and start from the base branch\'s remote, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings from the calling thread; a caller outside a T3 thread must pass projectId and gets the project\'s default model. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. To link a thread for the user, write `[title](t3-thread://v1/<threadId>)` with the threadId exactly as returned, not URL-encoded; T3 Code shows the thread\'s current title. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. The new thread may not run with broader runtime or interaction modes than the caller: the calling T3 thread\'s own modes, or the permission mode an outside agent was approved with.',
107+
'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. To fetch and start from the base branch\'s remote, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings from the calling thread; a caller outside a T3 thread must pass projectId and gets the project\'s default model. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. Mention a thread with its `link`. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. The new thread may not run with broader runtime or interaction modes than the caller: the calling T3 thread\'s own modes, or the permission mode an outside agent was approved with.',
108108
parameters: Schema.Struct({
109109
projectId: Schema.optional(ProjectId),
110110
scratch: Schema.optional(
@@ -133,6 +133,7 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {
133133
}),
134134
success: Schema.Struct({
135135
threadId: ThreadId,
136+
link: Schema.optional(Schema.String),
136137
projectId: ProjectId,
137138
modelSelection: ModelSelection,
138139
runId: Schema.NullOr(RunId),

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
} from "@t3tools/contracts";
1010
import * as Effect from "effect/Effect";
1111
import { modelSelectionCommandType } from "@t3tools/shared/model";
12+
import { formatThreadLink } from "@t3tools/shared/threadLinks";
1213

1314
import * as McpToolAccess from "../../McpToolAccess.ts";
1415
import {
@@ -105,9 +106,15 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, {
105106
Effect.gen(function* () {
106107
const { caller } = yield* readCaller();
107108
const threadSearch = yield* ThreadSearch.ThreadSearch;
108-
return yield* threadSearch
109+
const { matches } = yield* threadSearch
109110
.searchThreads({ ...input, projectId: input.projectId ?? caller?.projectId })
110111
.pipe(Effect.mapError(unavailable));
112+
return {
113+
matches: matches.map((match) => ({
114+
...match,
115+
link: formatThreadLink(match.threadId, match.title),
116+
})),
117+
};
111118
}),
112119
),
113120
t3_thread_fork: writesThread((input) =>

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,7 @@ const ThreadSearchTool = Tool.make("t3_thread_search", {
254254
threadId: OrchestrationThreadSearchMatch.fields.threadId,
255255
projectId: OrchestrationThreadSearchMatch.fields.projectId,
256256
title: Schema.String,
257+
link: Schema.optional(Schema.String),
257258
source: Schema.Literals(["title", "user", "assistant"]),
258259
snippet: Schema.optional(OrchestrationThreadSearchMatch.fields.snippet),
259260
messageCreatedAt: Schema.optional(OrchestrationThreadSearchMatch.fields.messageCreatedAt),

‎docs/orchestration-v2/orchestrator-mcp-server.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -391,7 +391,8 @@ and `creationSource: "mcp"`; provider output uses `creationSource: "provider"`.
391391
Actor and ingress are separate so agent-authored user-role messages remain
392392
distinguishable from human-authored messages.
393393

394-
Agents mention another thread as `[title](t3-thread://v1/<threadId>)`. The
394+
Agents mention another thread as `[title](t3-thread://v1/<threadId>)`. Thread
395+
results carry this ready-made as `link`, so agents never format the id. The
395396
link carries only the id. Clients first resolve it in the message's environment,
396397
then use a unique match in another enabled environment. Ambiguous matches stay
397398
unresolved. Web and desktop show the resolved thread’s current title. Mobile

‎packages/contracts/src/orchestratorMcp.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,7 @@ export type OrchestratorMcpDelegateTaskInput = typeof OrchestratorMcpDelegateTas
190190
export const OrchestratorMcpDelegateTaskResult = Schema.Struct({
191191
taskId: NodeId,
192192
childThreadId: ThreadId,
193+
link: Schema.optional(Schema.String),
193194
childRunId: Schema.NullOr(RunId),
194195
childNodeId: NodeId,
195196
status: OrchestratorMcpDelegatedTaskStatus,
@@ -273,6 +274,7 @@ export type OrchestratorMcpCreatedThreadStatus = typeof OrchestratorMcpCreatedTh
273274

274275
export const OrchestratorMcpCreatedThread = Schema.Struct({
275276
threadId: ThreadId,
277+
link: Schema.optional(Schema.String),
276278
runId: Schema.NullOr(RunId),
277279
status: OrchestratorMcpCreatedThreadStatus,
278280
title: Schema.String,
@@ -327,6 +329,7 @@ export type OrchestratorMcpThreadPullRequest = typeof OrchestratorMcpThreadPullR
327329
export const OrchestratorMcpThreadListItem = Schema.Struct({
328330
threadId: ThreadId,
329331
title: Schema.String,
332+
link: Schema.optional(Schema.String),
330333
createdBy: OrchestrationV2Actor,
331334
creationSource: OrchestrationV2CreationSource,
332335
status: OrchestratorMcpThreadStatus,
@@ -394,6 +397,7 @@ export const OrchestratorMcpThreadDetail = Schema.Struct({
394397
threadId: ThreadId,
395398
projectId: ProjectId,
396399
title: Schema.String,
400+
link: Schema.optional(Schema.String),
397401
createdBy: OrchestrationV2Actor,
398402
creationSource: OrchestrationV2CreationSource,
399403
status: OrchestratorMcpThreadStatus,
@@ -475,6 +479,7 @@ export type OrchestratorMcpThreadSendInput = typeof OrchestratorMcpThreadSendInp
475479

476480
export const OrchestratorMcpThreadSendResult = Schema.Struct({
477481
threadId: ThreadId,
482+
link: Schema.optional(Schema.String),
478483
messageId: MessageId,
479484
runId: RunId,
480485
taskId: Schema.optional(NodeId),

0 commit comments

Comments
 (0)