Skip to content

Commit b860fe8

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 d935071 commit b860fe8

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
@@ -595,6 +595,22 @@ describe("orchestrator MCP toolkit", () => {
595595
branch: "feature/mcp-branch",
596596
worktreePath: cwd,
597597
});
598+
// A thread in the project root has neither a branch nor a worktree of its own.
599+
const rootThreadId = ThreadId.make("thread:mcp-project-root");
600+
yield* orchestrator.dispatch({
601+
type: "thread.create",
602+
createdBy: "user",
603+
creationSource: "web",
604+
commandId: CommandId.make("command:mcp-project-root:create"),
605+
threadId: rootThreadId,
606+
projectId,
607+
title: "Thread in the project root",
608+
modelSelection: codexSelection,
609+
runtimeMode: "full-access",
610+
interactionMode: "default",
611+
branch: null,
612+
worktreePath: null,
613+
});
598614
const listCall = yield* invoke("t3_thread_list", {
599615
includeSubagents: false,
600616
limit: 100,
@@ -603,14 +619,18 @@ describe("orchestrator MCP toolkit", () => {
603619
Effect.orDie,
604620
);
605621
expect(listed.threads.map((thread) => thread.threadId)).toEqual(
606-
expect.arrayContaining([parentThreadId, branchThreadId]),
622+
expect.arrayContaining([parentThreadId, branchThreadId, rootThreadId]),
607623
);
608624
expect(listed.threads.find((thread) => thread.threadId === branchThreadId)).toMatchObject(
609625
{
610626
branch: "feature/mcp-branch",
611627
worktreePath: cwd,
612628
},
613629
);
630+
expect(listed.threads.find((thread) => thread.threadId === rootThreadId)).toMatchObject({
631+
branch: null,
632+
worktreePath: null,
633+
});
614634
expect(listed.threads.find((thread) => thread.threadId === parentThreadId)).toMatchObject(
615635
{ branch: null, worktreePath: cwd },
616636
);

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

Lines changed: 1 addition & 1 deletion
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 threads in a project, newest first. Omit `projectId` for yours. Filter by status, title, settled, or snoozed. `branch`, `worktreePath`: its checkout. Page with the cursor.",
217+
"List threads in a project, newest first. Omit `projectId` for yours. Filter by status, title, settled, or snoozed. `branch`, `worktreePath`: its own; null `worktreePath` means the project root. Page with the cursor.",
218218
parameters: OrchestratorMcpThreadListInput,
219219
success: OrchestratorMcpThreadListResult,
220220
failure: OrchestratorMcpFailure,

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

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

380382
### `t3_thread_read`
381383

0 commit comments

Comments
 (0)