Skip to content

Commit 4b5adce

Browse files
committed
docs(server): a thread in the project root has no worktree of its own
The list description and the server doc said both fields are null when a thread has no checkout of its own. `worktreePath` is the thread's own worktree: a thread in the project root has a null `worktreePath` and works in the project root instead, which the two fields do not express the same way. Say that a null `worktreePath` means the thread works in the project root, and cover it in the list test.
1 parent 2558459 commit 4b5adce

3 files changed

Lines changed: 25 additions & 3 deletions

File tree

‎apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -587,6 +587,22 @@ describe("orchestrator MCP toolkit", () => {
587587
branch: "feature/mcp-branch",
588588
worktreePath: cwd,
589589
});
590+
// A thread in the project root has neither a branch nor a worktree of its own.
591+
const rootThreadId = ThreadId.make("thread:mcp-project-root");
592+
yield* orchestrator.dispatch({
593+
type: "thread.create",
594+
createdBy: "user",
595+
creationSource: "web",
596+
commandId: CommandId.make("command:mcp-project-root:create"),
597+
threadId: rootThreadId,
598+
projectId,
599+
title: "Thread in the project root",
600+
modelSelection: codexSelection,
601+
runtimeMode: "full-access",
602+
interactionMode: "default",
603+
branch: null,
604+
worktreePath: null,
605+
});
590606
const listCall = yield* invoke("t3_thread_list", {
591607
includeSubagents: false,
592608
limit: 100,
@@ -595,14 +611,18 @@ describe("orchestrator MCP toolkit", () => {
595611
Effect.orDie,
596612
);
597613
expect(listed.threads.map((thread) => thread.threadId)).toEqual(
598-
expect.arrayContaining([parentThreadId, branchThreadId]),
614+
expect.arrayContaining([parentThreadId, branchThreadId, rootThreadId]),
599615
);
600616
expect(listed.threads.find((thread) => thread.threadId === branchThreadId)).toMatchObject(
601617
{
602618
branch: "feature/mcp-branch",
603619
worktreePath: cwd,
604620
},
605621
);
622+
expect(listed.threads.find((thread) => thread.threadId === rootThreadId)).toMatchObject({
623+
branch: null,
624+
worktreePath: null,
625+
});
606626
expect(listed.threads.find((thread) => thread.threadId === parentThreadId)).toMatchObject(
607627
{ branch: null, worktreePath: cwd },
608628
);

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,7 @@ const CreateThreadsTool = Tool.make("create_threads", {
194194

195195
const ThreadListTool = Tool.make("t3_thread_list", {
196196
description:
197-
"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. branch and worktreePath report the checkout each thread works in, and are null when the thread has none. 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.",
197+
"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. branch and worktreePath report the thread's own branch and worktree; a null worktreePath means the thread works in the project root. 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.",
198198
parameters: OrchestratorMcpThreadListInput,
199199
success: OrchestratorMcpThreadListResult,
200200
failure: OrchestratorMcpFailure,

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,9 @@ given, else the calling thread's project. Callers can filter by title, run
374374
status, and whether app-owned sub-agent threads are included. Results are
375375
bounded and offset-paginated. Deleted threads are never listed. Each listed
376376
thread reports the `branch` and `worktreePath` it works in, as the read tool
377-
does; both are null when the thread has no checkout of its own.
377+
does. `worktreePath` is the thread's own worktree, and is null when the
378+
thread works in the project root instead; `branch` is null when the thread
379+
has no branch of its own.
378380

379381
### `t3_thread_read`
380382

0 commit comments

Comments
 (0)