clover's git

the-knife

1	# Orchestrator MCP Server
2
3	## Purpose
4
5	T3 exposes V2 orchestration through its app-owned MCP endpoint. A provider
6	agent can use this endpoint to:
7
8	- create an app-owned sub-agent on any supported provider instance;
9	- wait for or poll the sub-agent's durable result;
10	- cancel an active delegated task; and
11	- create one or more ordinary top-level T3 threads;
12	- list a project's threads and incrementally read any thread;
13	- rename threads, regenerate titles, and link or unlink pull requests;
14	- send or steer follow-up messages; and
15	- wait for or interrupt ordinary thread runs.
16
17	These are T3 orchestration operations, not provider-native sub-agent APIs.
18	Delegated tasks always create a T3 child thread and run. The child receives
19	only the supplied task prompt, plus an optional role instruction supplied in
20	the same tool call. Parent conversation history is not copied into the child.
21
22	`ThreadManagementService` is the shared server application boundary for V2
23	WebSocket commands and MCP. It owns thread lookup, listing, send-mode
24	selection, durable send postconditions, wait polling, and interrupt selection;
25	`OrchestratorV2` remains the lower-level command/event processor. Transport
26	adapters only authenticate, resolve transport-specific inputs, and shape
27	responses.
28
29	## Transport And Authentication
30
31	The orchestration tools share the existing authenticated HTTP MCP endpoint:
32
33	```text
34	http://127.0.0.1:<server-port>/mcp
35	```
36
37	The provider-visible server key is `t3-code`. The endpoint registers both the
38	preview toolkit and the orchestration toolkit.
39
40	Before `ProviderSessionManager` opens a new V2 provider session, it asks
41	`McpSessionRegistry` for a credential scoped to:
42
43	- the T3 environment;
44	- the parent T3 thread;
45	- the concrete provider instance; and
46	- the provider session.
47
48	The credential grants `preview` and `orchestration` capabilities. Credentials
49	expire after a maximum lifetime, expire when idle, and are revoked when the
50	provider session is released. The raw token is not persisted in orchestration
51	state.
52
53	The MCP HTTP server resolves the bearer token and supplies the resulting
54	`McpInvocationScope` to tool handlers. Orchestration handlers additionally
55	check the `orchestration` capability before reading or mutating state.
56
57	## Provider Injection
58
59	### Codex V2
60
61	Codex app-server receives the remote MCP server through command-line config
62	overrides:
63
64	```text
65	-c mcp_servers.t3-code.url=http://127.0.0.1:<port>/mcp
66	-c mcp_servers.t3-code.bearer_token_env_var="T3_MCP_BEARER_TOKEN"
67	```
68
69	The provider-session token is placed in `T3_MCP_BEARER_TOKEN`. Both the
70	production Codex launcher and the injectable test launcher use the same
71	projection helper.
72
73	### Claude Agent SDK V2
74
75	Claude receives an HTTP MCP server in its query options:
76
77	```ts
78	{
79	mcpServers: {
80	"t3-code": {
81	type: "http",
82	url: "http://127.0.0.1:<port>/mcp",
83	headers: {
84	Authorization: "Bearer <provider-session-token>",
85	},
86	},
87	},
88	allowedTools: [
89	// existing allowed tools
90	"mcp__t3-code__*",
91	],
92	}
93	```
94
95	The adapter logs only whether MCP configuration exists; it does not log the
96	server headers or token.
97
98	### Cursor Agent SDK V2
99
100	Cursor receives the same authenticated HTTP MCP endpoint through the SDK's
101	`mcpServers` agent and send options. The adapter passes the authorization header
102	to the SDK but projects only redacted option metadata into protocol diagnostics.
103
104	### Grok ACP V2
105
106	Grok receives the authenticated HTTP MCP endpoint through the ACP
107	`session/new`, `session/load`, and `session/fork` `mcpServers` field. The shared
108	ACP adapter owns standard protocol behavior; the Grok flavor adds xAI extension
109	requests such as structured user questions.
110
111	ACP does not define native subagents or active steering. Grok therefore uses
112	orchestrator-owned child threads and implements steering through
113	cancel-and-restart. Its current driver also lacks `session/fork`, so app forks
114	use portable context transfer. These are orchestrator policies, not
115	provider-specific MCP tools.
116
117	### ACP Registry V2
118
119	The `acpRegistry` driver is the generic flavor of the same shared ACP adapter.
120	Each provider instance names an agent from the official ACP Registry. Settings
121	searches the registry through the connected server, then prepares a compatible
122	distribution before persisting the provider instance. Binary distributions use
123	a managed, versioned cache; declared checksums are verified when present.
124	Version-pinned `npx` packages install globally through `npm`; `uvx` packages use
125	`uv tool install`. ACP launches the resulting global command directly, so the
126	same command is available for terminal authentication. A local executable may
127	override the installed command without changing the registry-declared arguments
128	or environment.
129
130	Search, preparation, provider status, and session startup share one
131	server-scoped catalog service. This keeps platform selection and registry
132	validation identical across settings and runtime use. Catalog inspection never
133	starts an ACP process, probes models, or performs authentication. The managed
134	provider snapshot creates a disposable `session/new` through the normal provider
135	refresh lifecycle, using success as the authentication-readiness proof and
136	projecting advertised models into the snapshot. Terminal-only login remains a
137	manual operation on the connected server.
138
139	Capabilities such as session loading, session forking, models, modes, and MCP
140	transport are enabled only when the selected agent advertises them. Missing
141	features degrade through V2 policy: steering uses interrupt-and-restart,
142	forking uses portable context when native `session/fork` is unavailable, and
143	subagents use orchestrator-owned child threads. Registry agents do not receive
144	provider-specific extensions; those remain in flavors such as Grok.
145
146	### Pi V2
147
148	T3 keeps a provider-session HTTP bridge even when Pi supports native MCP.
149	`mcp.json` entries override native registrations, and native MCP's default
150	60-second request timeout can interrupt long-running T3 tools. The bridge owns
151	the injected endpoint and credential and forwards Pi's cancellation signal.
152
153	When a provider session credential exists, the adapter writes a T3-owned
154	extension into the server cache and spawns
155	`pi --mode rpc --extension <cache>/pi-t3-mcp-extension.ts` with:
156
157	```text
158	T3_MCP_URL=http://127.0.0.1:<port>/mcp
159	T3_MCP_BEARER_TOKEN=<provider-session-token>
160	```
161
162	The extension preserves public names under `mcp__t3-code__` for saved loadouts
163	and tool selectors. Modern Pi also receives hidden `mcp__t3_code__` aliases,
164	which reserve the normalized namespace against configured MCP servers without
165	adding declarations or search results. On Pi 0.99+,
166	`orchestrator_capabilities`, `delegate_task`, and `task_status` remain directly
167	available; optional tools are discovered through Pi's builtin `tool_search`.
168	On older Pi or without builtin search, all tools remain directly available.
169	The bridge calls the original MCP tool name over HTTP. Follow-up requests send
170	`mcp-protocol-version: 2025-06-18`; Effect's MCP transport returns 400
171	without it. The first turn of a session also receives the shared T3
172	orchestration instructions.
173
174	Pi keeps ownership of native extension discovery. T3 does not replace Pi's
175	`subagent` tool or reproduce Pi's package and project-trust loader. Durable
176	delegation goes through the namespaced T3 MCP `delegate_task` tool and the
177	shared orchestration child-thread lifecycle. When Pi's example `subagent`
178	extension is installed, the adapter observes its documented `details.results`
179	shape and projects task cards with no child thread id. Unknown result shapes
180	remain ordinary dynamic tool output.
181
182	### Provider Support
183
184	A provider instance can run child tasks when its live `ProviderInstance`
185	exposes a V2 `orchestrationAdapter` — the same registration the orchestrator
186	resolves when a `delegated_task.request` executes. That covers Codex, Claude
187	Agent SDK, Cursor Agent SDK, Grok, generic registry agents over ACP, OpenCode,
188	OpenCode 2, Pi, Antigravity, and any future driver that builds an adapter.
189	Capability discovery still reports other registered provider instances, but
190	marks them unavailable for orchestration when no adapter resolves. This keeps
191	provider selection model-visible without allowing a request that cannot run.
192
193	## Tool Surface
194
195	The server exposes eleven orchestration tools.
196
197	### `orchestrator_capabilities`
198
199	Returns:
200
201	- the inherited provider instance and model;
202	- the parent runtime and interaction modes;
203	- registered provider instances and advertised models;
204	- whether each provider can run a child task; and
205	- feature flags for polling, cancellation, and batch thread creation.
206
207	Unavailable providers include model-visible constraints such as missing V2
208	adapter support, disabled state, missing executable, or missing authentication.
209
210	### `delegate_task`
211
212	Creates a T3-owned child thread and immediately dispatches the supplied task
213	prompt.
214
215	```ts
216	type DelegateTaskInput = {
217	task: string;
218	target?: {
219	providerInstanceId?: string;
220	driverKind?: string;
221	model?: string;
222	};
223	title?: string;
224	role?: "implementation" | "research" | "review" | "design" | "test" | "general";
225	mode?: "async" | "wait";
226	timeoutMs?: number;
227	clientRequestId?: string;
228	runtimeMode?: "inherit" | "approval-required" | "auto-accept-edits" | "full-access";
229	interactionMode?: "inherit" | "plan" | "default";
230	};
231	```
232
233	Provider, model, runtime mode, and interaction mode inherit from the parent
234	when omitted. A driver-only target inherits the parent's provider instance
235	when it can run child tasks, and otherwise selects an available instance of
236	that driver; an explicit `providerInstanceId` is honored exactly and fails
237	when unavailable. Selecting a different provider without a model uses that
238	provider's first advertised model.
239
240	A provider runs a runtime mode it does not offer as `approval-required`, so a
241	child would ask for approval on every command. `orchestrator_capabilities`
242	lists `runtimeModes` only for a provider that offers some of the modes, and
243	omits it for a provider that offers all of them. When the target lists
244	`runtimeModes`, an explicit `runtimeMode` outside that list is refused, and an
245	inherited mode steps down to the broadest mode the target offers.
246
247	Each delegated review round uses a new `delegate_task` call with the original brief,
248	prior findings, responses, and unresolved objections. Track each round by its own `taskId` and use
249	a distinct `clientRequestId` per round, stable across retries of that round.
250	`childThreadId` is backing storage, not a target for another review round through
251	`t3_thread_send`. Ordinary thread messaging remains available for user-requested
252	conversations; it does not reopen a completed task. There is no task-level follow-up
253	API for preserving the same reviewer session.
254
255	Delegation requires an active parent run owned by the MCP credential's
256	provider session. The request becomes the V2 command
257	`delegated_task.request`.
258
259	`mode: "async"` returns the current durable state immediately.
260	`mode: "wait"` waits for the task result, including nested work and completion follow-ups, or until
261	the timeout expires. A wait timeout does not cancel the child; the result sets
262	`waitTimedOut: true`, and the caller can continue with `task_status`. A pending blocking
263	question also ends the wait with `hasPendingQuestion: true` and `waitTimedOut: false`.
264	If `hasPendingQuestion`, pass `threadId=childThreadId` to `t3_pending_request_list`,
265	`t3_pending_request_read` (with `requestId`) and `t3_pending_request_respond`, or ask
266	the user; the task's completion still wakes this thread. Async questions and approvals
267	do not end the wait.
268
269	```ts
270	type DelegateTaskResult = {
271	taskId: string;
272	childThreadId: string;
273	childRunId: string | null;
274	childNodeId: string;
275	status: "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "interrupted";
276	workState: "working" | "waiting_for_children" | "result_available";
277	hasPendingChildRuns: boolean;
278	providerInstanceId: string;
279	model: string | null;
280	summary: string | null;
281	resultContextTransferId: string | null;
282	latestTerminalRunId: string | null;
283	latestTerminalStatus: "completed" | "failed" | "cancelled" | "interrupted" | null;
284	latestTerminalSummary: string | null;
285	latestTerminalResultContextTransferId: string | null;
286	hasPendingQuestion: boolean;
287	waitTimedOut: boolean;
288	};
289	```
290
291	### `task_status`
292
293	Reads a delegated task from the parent thread's durable projection. A task ID
294	from another parent thread is rejected. `childRunId` identifies the original
295	run. `workState` distinguishes active work, a finished turn waiting for children,
296	and an available result. The task remains nonterminal until its known work
297	finishes. Its published `summary` and result transfer then remain stable across
298	later follow-ups. `hasPendingChildRuns` reports later queued or executing turns;
299	`latestTerminal*` exposes later executed, non-monitor results without replacing
300	the published task result.
301
302	### `task_cancel`
303
304	Stops the child thread with the internal `thread.stop` command, then stops every
305	task the child delegated, and disposes automatic parent delivery. Like a user Stop,
306	`thread.stop` interrupts the running turn, holds queued turns, and ends pull request
307	watches. A nonterminal task with no interruptible run is rejected. A terminal task
308	returns its existing status, and its child thread still stops, including later
309	runs and watch wakes. Published task results remain available. It accepts an
310	optional cancellation reason.
311
312	### `create_threads`
313
314	Creates between one and twenty ordinary top-level T3 threads:
315
316	```ts
317	type CreateThreadsInput = {
318	threads: Array<{
319	prompt?: string;
320	title?: string;
321	target?: {
322	providerInstanceId?: string;
323	driverKind?: string;
324	model?: string;
325	};
326	runtimeMode?: "inherit" | "approval-required" | "auto-accept-edits" | "full-access";
327	interactionMode?: "inherit" | "plan" | "default";
328	}>;
329	clientRequestId?: string;
330	};
331	```
332
333	Each entry independently resolves provider, model, and modes. The new threads
334	inherit the parent's project, branch, and worktree path, but they have no
335	sub-agent lineage. Entries with a prompt immediately dispatch a run; entries
336	without a prompt remain idle.
337
338	### `t3_thread_launch`
339
340	Launches one ordinary top-level thread through the app's launch service. Use an
341	explicit `workspaceStrategy` to create a new worktree (`worktree` with `baseRef`),
342	attach an existing checkout (`existing_worktree` with `worktreePath`), or use the
343	project root (`root`, also the default). The thread is bound to that workspace
344	before the agent starts. Creating a worktree in the task prompt does not update
345	this binding.
346
347	Pass the task in `message`. Project, model, and modes inherit when omitted;
348	workspace does not. `scratch: true` launches without a project, in a folder of
349	its own under the environment's Scratch project. For stacked PRs, use the parent branch as `baseRef` with
350	`startFromOrigin: false`. The new thread may not run with broader runtime or
351	interaction modes than the caller. Launch has no retry key, so inspect existing threads after a failed or lost response before
352	launching again. `create_threads` remains the batch option for a shared checkout.
353
354	### `t3_thread_list`
355
356	Lists durable thread shells in one project, newest first: `projectId` when
357	given, else the calling thread's project. Callers can filter by title, run
358	status, and whether app-owned sub-agent threads are included. Results are
359	bounded and offset-paginated. Deleted threads are never listed.
360
361	### `t3_thread_read`
362
363	Reads the durable state, recent runs, and visible timeline of any thread in
364	the environment by thread ID. A deleted thread returns `thread_not_found`. The
365	default `messages` view returns user messages, assistant
366	messages, and proposed plans. The `activity` view also returns summarized tool,
367	reasoning, checkpoint, handoff, and runtime-request items. Large item text is
368	bounded and reports whether it was truncated. `afterPosition` and
369	`nextPosition` support incremental reads.
370
371	Thread and message results include required `createdBy` and `creationSource`
372	provenance. MCP-created threads and user-role messages use `createdBy: "agent"`
373	and `creationSource: "mcp"`; provider output uses `creationSource: "provider"`.
374	Actor and ingress are separate so agent-authored user-role messages remain
375	distinguishable from human-authored messages.
376
377	Agents mention another thread as `[title](t3-thread://v1/<threadId>)`. The
378	link carries only the id, which resolves in the environment of the message that
379	holds it. Clients show the thread's current title rather than the label, so a
380	rename never leaves a stale link.
381
382	List and read results report `snoozed` and `snoozedUntil`, and
383	`t3_thread_list` filters on `snoozed`. The server's `isSnoozed` follows the
384	client's `effectiveSnoozed`, so agents and the sidebar agree: a snoozed thread
385	wakes early when it has a pending request, fails, or completes after the snooze.
386
387	### `t3_thread_update`
388
389	Updates metadata for the calling thread or any other thread in the environment.
390	The typed actions are `rename`, `regenerate_title`, `link_pull_request`, and
391	`unlink_pull_request`. A link input supplies the repository, number, and URL;
392	the server records the target thread's project ID. Branch and workspace changes
393	are outside this tool.
394
395	The result includes the command ID and durable event sequence together with the
396	resultant title, title-regeneration marker, and linked pull request. Reusing a
397	`clientRequestId` for the same action and thread replays the same command
398	receipt. Thread list and read results expose the linked pull request, and thread
399	detail also exposes an in-flight title regeneration.
400
401	### `t3_thread_send`
402
403	Sends a message to any ordinary or delegated thread in the environment:
404
405	- `auto` starts an idle thread, steers a fully active turn, or queues behind a
406	turn that is not yet steerable;
407	- `queue` creates a separate follow-up run after active work;
408	- `steer` requires a steerable active provider turn; and
409	- `restart` requires an active provider turn and uses the orchestrator's
410	interrupt-and-restart path.
411
412	The target runtime and interaction modes may not be broader than the caller's.
413	Stable command and message IDs are derived from `clientRequestId` for
414	idempotent retries.
415
416	### `t3_thread_wait`
417
418	Waits for a selected run to become `completed`, `failed`, `cancelled`,
419	`interrupted`, or `rolled_back`. Without `runId`, it pins the latest run at call
420	time; an idle thread returns immediately. A timeout reports the latest durable
421	status and does not cancel work.
422
423	### `t3_thread_interrupt`
424
425	Interrupts a selected active run through the normal V2 `run.interrupt` command.
426	Without `runId`, it selects the newest interruptible run. A terminal run is
427	returned unchanged, and a thread with no active provider turn returns
428	`no_active_run`.
429
430	## Delegated Task Lifecycle
431
432	The MCP server is a command ingress into V2. It does not call provider adapters
433	directly.
434
435	```text
436	provider model
437	-> MCP tools/call delegate_task
438	-> authenticated OrchestratorMcpService
439	-> shared ThreadManagementService
440	-> V2 delegated_task.request command
441	-> child thread + child run
442	-> parent app_owned subagent projection
443	-> parent/child execution nodes
444	-> consumed subagent_spawn context transfer
445	-> normal provider effect and runtime ingestion
446	-> child run reaches a terminal state
447	-> parent subagent/node/turn item finalized
448	-> consumed subagent_result context transfer
449	-> wait result or later task_status result
450	```
451
452	The child thread has lineage relationship `subagent` and points back to the
453	parent node. The parent gets an `app_owned` sub-agent projection and a
454	sub-agent turn item so the existing debug UI can render progress.
455
456	Terminal provider events trigger finalization. The event stream first replays
457	persisted events and then follows live events, so finalization also runs after
458	a server restart. An existing `subagent_result` transfer makes finalization
459	idempotent.
460
461	Users rarely watch child threads, so a child question would otherwise go
462	unanswered. When a child opens a pending `user_input` request, the parent gets
463	a notification message telling it to answer with the pending request tools or
464	ask the user. The message says whether the child is blocked or, for a Codex
465	async question, still working. If the question is answered or dismissed before
466	the notification starts a turn, that queued turn is cancelled. Approvals are not
467	routed, because those tools cannot answer them.
468	A parent still blocked in a `delegate_task` wait gets the blocking question
469	through that wait instead.
470	If the provider cuts that wait short, a still-pending live question wakes the
471	parent when its launching run completes, fails, or waits for post-turn work.
472	Stopping or interrupting the parent prevents this catch-up.
473
474	A failed run exposes its provider error before any progress text. Successful
475	results use the latest assistant content from the final work turn.
476
477	## Policy And Idempotency
478
479	- A child runtime mode may stay equal to or become narrower than the parent
480	mode. It may not escalate privileges.
481	- A child interaction mode may stay equal to or narrow from `default` to
482	`plan`. It may not escalate from `plan` to `default`.
483	- Thread tools take any thread in the environment as a target. For a thread
484	caller, list and search cover one project: its own unless `projectId` is given.
485	- A tool that changes another thread needs the calling thread's live run, and
486	the target's runtime and interaction modes may not be broader than the
487	caller's. This is the same privilege ceiling as child creation.
488	- Provider instances must be enabled, installed, available, authenticated, and
489	backed by a V2 adapter.
490	- A requested model must be advertised by the selected provider when the
491	provider publishes a model list.
492	- `clientRequestId` derives stable command, thread, and message IDs within the
493	provider session. Retrying the same call returns the same durable work.
494	- Calls without `clientRequestId` receive a generated request key and create
495	new work.
496
497	Expected denials use the typed `OrchestratorMcpFailure` result:
498
499	```text
500	capability_denied
501	parent_not_active
502	provider_unavailable
503	model_unavailable
504	runtime_mode_escalation_denied
505	interaction_mode_escalation_denied
506	task_not_found
507	task_not_cancellable
508	thread_not_found
509	run_not_found
510	thread_not_sendable
511	thread_not_interruptible
512	invalid_request
513	orchestration_error
514	```
515
516	## Code Ownership
517
518	- Shared schemas: `packages/contracts/src/orchestratorMcp.ts` and
519	`packages/contracts/src/threadMetadataMcp.ts`
520	- MCP services: `apps/server/src/mcp/OrchestratorMcpService.ts` and the focused
521	`apps/server/src/mcp/ThreadMetadataMcpService.ts`
522	- Tool definitions and handlers:
523	`apps/server/src/mcp/toolkits/orchestrator/`
524	- HTTP registration and authentication:
525	`apps/server/src/mcp/McpHttpServer.ts`
526	- Credential lifecycle: `apps/server/src/mcp/McpSessionRegistry.ts`
527	- Provider injection:
528	`apps/server/src/orchestration-v2/ProviderSessionManager.ts` and V2 adapters
529	- Durable delegated-task command and finalization:
530	`apps/server/src/orchestration-v2/Orchestrator.ts`
531
532	## Verification
533
534	The integration test uses the real MCP toolkit registration, V2 orchestrator,
535	SQL persistence, event ingestion, projections, and checkpoints. Only the
536	external provider adapters are deterministic test implementations.
537
538	Coverage includes:
539
540	- capability discovery;
541	- cross-provider delegated completion;
542	- prompt-only child context;
543	- parent and child lineage projections;
544	- spawn and result context transfers;
545	- async status polling;
546	- cancellation;
547	- batch ordinary-thread creation;
548	- thread listing and timeline reads, including another project's threads;
549	- ordinary-thread send, wait, steering, and interruption;
550	- inheritance and per-thread provider overrides; and
551	- idempotent retries.
552
553	Provider adapter tests separately verify Codex, Claude, Cursor, Grok, and ACP
554	Registry behavior and MCP injection. The provider-session manager test verifies
555	that credentials exist before an adapter opens and are revoked when it closes.