The best way to control Claude Code, Codex and more from any computer or phone
| 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; |
| 15 | - wait for or interrupt ordinary thread runs; and |
| 16 | - schedule recurring work that runs without an active turn. |
| 17 | |
| 18 | These are T3 orchestration operations, not provider-native sub-agent APIs. |
| 19 | Delegated tasks always create a T3 child thread and run. The child receives |
| 20 | only the supplied task prompt, plus an optional role instruction supplied in |
| 21 | the same tool call. Parent conversation history is not copied into the child. |
| 22 | |
| 23 | `ThreadManagementService` is the shared server application boundary for V2 |
| 24 | WebSocket commands and MCP. It owns thread lookup, listing, send-mode |
| 25 | selection, durable send postconditions, wait polling, and interrupt selection; |
| 26 | `OrchestratorV2` remains the lower-level command/event processor. Transport |
| 27 | adapters only authenticate, resolve transport-specific inputs, and shape |
| 28 | responses. |
| 29 | |
| 30 | ## Transport And Authentication |
| 31 | |
| 32 | The orchestration tools share the existing authenticated HTTP MCP endpoint: |
| 33 | |
| 34 | ```text |
| 35 | http://127.0.0.1:<server-port>/mcp |
| 36 | ``` |
| 37 | |
| 38 | The provider-visible server key is `t3-code`. The endpoint registers both the |
| 39 | preview toolkit and the orchestration toolkit. |
| 40 | |
| 41 | Before `ProviderSessionManager` opens a new V2 provider session, it asks |
| 42 | `McpSessionRegistry` for a credential scoped to: |
| 43 | |
| 44 | - the T3 environment; |
| 45 | - the parent T3 thread; |
| 46 | - the concrete provider instance; and |
| 47 | - the provider session. |
| 48 | |
| 49 | The credential grants `preview` and `orchestration` capabilities. Credentials |
| 50 | expire after a maximum lifetime, expire when idle, and are revoked when the |
| 51 | provider session is released. The raw token is not persisted in orchestration |
| 52 | state. |
| 53 | |
| 54 | The MCP HTTP server resolves the bearer token and supplies the resulting |
| 55 | `McpInvocationScope` to tool handlers. Orchestration handlers additionally |
| 56 | check the `orchestration` capability before reading or mutating state. |
| 57 | |
| 58 | ## Provider Injection |
| 59 | |
| 60 | ### Codex V2 |
| 61 | |
| 62 | Codex gets T3's MCP server in each thread's `thread/start`, `thread/resume`, |
| 63 | and `thread/fork` config, with the provider-session token in an |
| 64 | `Authorization` header. The same server is registered twice: |
| 65 | |
| 66 | - `t3-code`: every tool except `t3_thread_wait` and `delegate_task`. |
| 67 | - `t3-code-direct`: only `t3_thread_wait` and `delegate_task`, with |
| 68 | `omit_tools_from = ["code_mode", "deferred"]`. |
| 69 | |
| 70 | Code Mode yields a script after about 30 seconds, so the model polls a blocking |
| 71 | `t3_thread_wait` or `delegate_task` with `mode: "wait"`, resending its context |
| 72 | on each poll. The second entry makes both direct tool calls, like Codex's own |
| 73 | wait tools. Codex reports calls as `<server>.<tool>`, so |
| 74 | `packages/shared/src/t3McpToolPresentation.ts` must resolve both server names. |
| 75 | Tool display and pending-work detection depend on it. |
| 76 | |
| 77 | ### Claude Agent SDK V2 |
| 78 | |
| 79 | Claude receives an HTTP MCP server in its query options: |
| 80 | |
| 81 | ```ts |
| 82 | { |
| 83 | mcpServers: { |
| 84 | "t3-code": { |
| 85 | type: "http", |
| 86 | url: "http://127.0.0.1:<port>/mcp", |
| 87 | headers: { |
| 88 | Authorization: "Bearer <provider-session-token>", |
| 89 | }, |
| 90 | }, |
| 91 | }, |
| 92 | allowedTools: [ |
| 93 | // existing allowed tools |
| 94 | "mcp__t3-code__*", |
| 95 | ], |
| 96 | } |
| 97 | ``` |
| 98 | |
| 99 | The adapter logs only whether MCP configuration exists; it does not log the |
| 100 | server headers or token. |
| 101 | |
| 102 | ### Cursor Agent SDK V2 |
| 103 | |
| 104 | Cursor receives the same authenticated HTTP MCP endpoint through the SDK's |
| 105 | `mcpServers` on `Agent.create` / `Agent.resume` and each `send`. With |
| 106 | `@cursor/sdk` 1.0.39+, send-level servers replace only the create-time inline |
| 107 | set; ambient servers from `settingSources` (`project`, `user`, `team`, `mdm`, |
| 108 | `plugins`) stay available. The adapter passes the authorization header to the |
| 109 | SDK but projects only redacted option metadata into protocol diagnostics. |
| 110 | |
| 111 | ### Grok ACP V2 |
| 112 | |
| 113 | Grok receives the authenticated HTTP MCP endpoint through the ACP |
| 114 | `session/new`, `session/load`, and `session/fork` `mcpServers` field. The shared |
| 115 | ACP adapter owns standard protocol behavior; the Grok flavor adds xAI extension |
| 116 | requests such as structured user questions. |
| 117 | |
| 118 | ACP does not define native subagents or active steering. Grok therefore uses |
| 119 | orchestrator-owned child threads and implements steering through |
| 120 | cancel-and-restart. Its current driver also lacks `session/fork`, so app forks |
| 121 | use portable context transfer. These are orchestrator policies, not |
| 122 | provider-specific MCP tools. |
| 123 | |
| 124 | ### ACP Registry V2 |
| 125 | |
| 126 | The `acpRegistry` driver is the generic flavor of the same shared ACP adapter. |
| 127 | Each provider instance names an agent from the official ACP Registry. Settings |
| 128 | searches the registry through the connected server, then prepares a compatible |
| 129 | distribution before persisting the provider instance. Binary distributions use |
| 130 | a managed, versioned cache; declared checksums are verified when present. |
| 131 | Version-pinned `npx` packages install globally through `npm`; `uvx` packages use |
| 132 | `uv tool install`. ACP launches the resulting global command directly, so the |
| 133 | same command is available for terminal authentication. A local executable may |
| 134 | override the installed command without changing the registry-declared arguments |
| 135 | or environment. |
| 136 | |
| 137 | Search, preparation, provider status, and session startup share one |
| 138 | server-scoped catalog service. This keeps platform selection and registry |
| 139 | validation identical across settings and runtime use. Catalog inspection never |
| 140 | starts an ACP process, probes models, or performs authentication. The managed |
| 141 | provider snapshot creates a disposable `session/new` through the normal provider |
| 142 | refresh lifecycle, using success as the authentication-readiness proof and |
| 143 | projecting advertised models into the snapshot. Terminal-only login remains a |
| 144 | manual operation on the connected server. |
| 145 | |
| 146 | Capabilities such as session loading, session forking, models, modes, and MCP |
| 147 | transport are enabled only when the selected agent advertises them. Missing |
| 148 | features degrade through V2 policy: steering uses interrupt-and-restart, |
| 149 | forking uses portable context when native `session/fork` is unavailable, and |
| 150 | subagents use orchestrator-owned child threads. Registry agents do not receive |
| 151 | provider-specific extensions; those remain in flavors such as Grok. |
| 152 | |
| 153 | ### Pi V2 |
| 154 | |
| 155 | T3 keeps a provider-session HTTP bridge even when Pi supports native MCP. |
| 156 | `mcp.json` entries override native registrations, and native MCP's default |
| 157 | 60-second request timeout can interrupt long-running T3 tools. The bridge owns |
| 158 | the injected endpoint and credential and forwards Pi's cancellation signal. |
| 159 | |
| 160 | When a provider session credential exists, the adapter writes a T3-owned |
| 161 | extension into the server cache and spawns |
| 162 | `pi --mode rpc --extension <cache>/pi-t3-mcp-extension.ts` with: |
| 163 | |
| 164 | ```text |
| 165 | T3_MCP_URL=http://127.0.0.1:<port>/mcp |
| 166 | T3_MCP_BEARER_TOKEN=<provider-session-token> |
| 167 | ``` |
| 168 | |
| 169 | The extension preserves public names under `mcp__t3-code__` for saved loadouts |
| 170 | and tool selectors. Modern Pi also receives `mcp__t3_code__` aliases, Pi's own |
| 171 | name for the server, which reserve it against configured MCP servers. They are |
| 172 | `model-only` and hide their own declarations, so the model can call them without |
| 173 | added declarations, search results, or codemode entries. An alias follows its |
| 174 | public tool: dropped when that tool is excluded, and off while a direct one is |
| 175 | off. Pi's `hidden` exposure would make them unreachable. On Pi 0.99+, |
| 176 | `orchestrator_capabilities`, `delegate_task`, and `task_status` remain directly |
| 177 | available; optional tools are discovered through Pi's builtin `tool_search`. |
| 178 | On older Pi or without builtin search, all tools remain directly available. |
| 179 | The bridge calls the original MCP tool name over HTTP. Follow-up requests send |
| 180 | `mcp-protocol-version: 2025-06-18`; Effect's MCP transport returns 400 |
| 181 | without it. The first turn of a session also receives the shared T3 |
| 182 | orchestration instructions. |
| 183 | |
| 184 | Pi keeps ownership of native extension discovery. T3 does not replace Pi's |
| 185 | `subagent` tool or reproduce Pi's package and project-trust loader. Durable |
| 186 | delegation goes through the namespaced T3 MCP `delegate_task` tool and the |
| 187 | shared orchestration child-thread lifecycle. When Pi's example `subagent` |
| 188 | extension is installed, the adapter observes its documented `details.results` |
| 189 | shape and projects task cards with no child thread id. Unknown result shapes |
| 190 | remain ordinary dynamic tool output. |
| 191 | |
| 192 | ### Provider Support |
| 193 | |
| 194 | A provider instance can run child tasks when its live `ProviderInstance` |
| 195 | exposes a V2 `orchestrationAdapter` — the same registration the orchestrator |
| 196 | resolves when a `delegated_task.request` executes. That covers Codex, Claude |
| 197 | Agent SDK, Cursor Agent SDK, Grok, generic registry agents over ACP, OpenCode, |
| 198 | OpenCode 2, Pi, Antigravity, and any future driver that builds an adapter. |
| 199 | Capability discovery still reports other registered provider instances, but |
| 200 | marks them unavailable for orchestration when no adapter resolves. This keeps |
| 201 | provider selection model-visible without allowing a request that cannot run. |
| 202 | |
| 203 | ## Tool Surface |
| 204 | |
| 205 | `OrchestratorToolkit` in |
| 206 | [`toolkits/orchestrator/tools.ts`](../../apps/server/src/mcp/toolkits/orchestrator/tools.ts) |
| 207 | is the authoritative list of orchestration tools. The sections below cover |
| 208 | delegation and thread tools. `t3_thread_launch` is documented with them but |
| 209 | registered by the project toolkit in |
| 210 | [`toolkits/project/tools.ts`](../../apps/server/src/mcp/toolkits/project/tools.ts). |
| 211 | |
| 212 | ### `orchestrator_capabilities` |
| 213 | |
| 214 | Returns: |
| 215 | |
| 216 | - the inherited provider instance and model; |
| 217 | - the parent runtime and interaction modes; |
| 218 | - registered provider instances and advertised models; |
| 219 | - whether each provider can run a child task; and |
| 220 | - feature flags for polling, cancellation, and batch thread creation. |
| 221 | |
| 222 | Unavailable providers include model-visible constraints such as missing V2 |
| 223 | adapter support, disabled state, missing executable, or missing authentication. |
| 224 | |
| 225 | The model list is short on purpose: catalogs such as OpenCode can hold hundreds |
| 226 | of models, and every call lands in the agent's context. Each provider lists |
| 227 | custom, favorite, and the caller's own models, plus all current (non-legacy) |
| 228 | models for Codex, Claude, Muse, and Grok, or the first 8 current models in the |
| 229 | user's model order for other providers. `omittedModels` counts the rest, and the |
| 230 | `search` input finds them, legacy models included. `delegate_task` still accepts |
| 231 | any catalog model. |
| 232 | |
| 233 | ### `delegate_task` |
| 234 | |
| 235 | Creates a T3-owned child thread and immediately dispatches the supplied task |
| 236 | prompt. |
| 237 | |
| 238 | The [shared contract](../../packages/contracts/src/orchestratorMcp.ts) is authoritative for |
| 239 | inputs and results, including target options and linked-environment fields. |
| 240 | |
| 241 | ```ts |
| 242 | import type { |
| 243 | OrchestratorMcpDelegateTaskInput as DelegateTaskInput, |
| 244 | OrchestratorMcpDelegateTaskResult as DelegateTaskResult, |
| 245 | } from "@t3tools/contracts"; |
| 246 | ``` |
| 247 | |
| 248 | For local delegation, provider, model, runtime mode, and interaction mode inherit |
| 249 | from the parent when omitted. A driver-only target inherits the parent's provider instance |
| 250 | when it can run child tasks, and otherwise selects an available instance of |
| 251 | that driver; an explicit `providerInstanceId` is honored exactly and fails |
| 252 | when unavailable. Selecting a different provider without a model uses that |
| 253 | provider's first advertised model. |
| 254 | |
| 255 | Set `target.options` using the options returned by `orchestrator_capabilities`, such as |
| 256 | `{effort: "max"}`. Supplied values override inherited selections; `{}` or `[]` clears them. |
| 257 | For local delegation, use `isolation: "worktree"` for a separate prepared checkout from |
| 258 | the parent's commit; the default `"shared"` uses the parent's checkout. Uncommitted parent |
| 259 | edits are not copied. A linked-environment target (`target.environmentId`) runs in the remote |
| 260 | project's checkout and rejects worktree isolation. To launch an isolated thread there, use |
| 261 | `t3_thread_launch` with `environmentId` and a worktree `workspaceStrategy`. |
| 262 | |
| 263 | A provider runs a runtime mode it does not offer as `approval-required`, so a |
| 264 | child would ask for approval on every command. `orchestrator_capabilities` |
| 265 | lists `runtimeModes` only for a provider that offers some of the modes, and |
| 266 | omits it for a provider that offers all of them. When the target lists |
| 267 | `runtimeModes`, an explicit `runtimeMode` outside that list is refused, and an |
| 268 | inherited mode steps down to the broadest mode the target offers. |
| 269 | |
| 270 | Each independent delegated review round uses a new `delegate_task` call with the |
| 271 | original brief, prior findings, responses, and unresolved objections. Track each |
| 272 | round by its own `taskId` and use a distinct `clientRequestId` per round, stable |
| 273 | across retries of that round. |
| 274 | A follow-up that needs the same child's conversation goes through `t3_thread_send` |
| 275 | on its `childThreadId`. After the original task completes, that follow-up runs as a |
| 276 | fresh task in the child thread; it does not reopen the completed task or change its |
| 277 | published result. |
| 278 | |
| 279 | Delegation requires an active parent run owned by the MCP credential's |
| 280 | provider session. The request becomes the V2 command |
| 281 | `delegated_task.request`. |
| 282 | |
| 283 | `mode: "async"` returns the current durable state immediately. |
| 284 | `mode: "wait"` waits for the task result, including nested work and completion follow-ups, or until |
| 285 | the timeout expires. A wait timeout does not cancel the child; the result sets |
| 286 | `waitTimedOut: true`. When the result includes `next`, completion wakes the parent: |
| 287 | do not wait on the task or poll it; continue other work, and end the turn when none is |
| 288 | left. A pending blocking question also ends the wait with `hasPendingQuestion: true` and |
| 289 | `waitTimedOut: false`. |
| 290 | If `hasPendingQuestion`, pass `threadId=childThreadId` to `t3_pending_request` with |
| 291 | action `list`, `read` (with `requestId`), or `respond`, or ask the user; the task's completion still wakes this thread. A pending live approval for the |
| 292 | task's own unfinished work also ends the wait. Its identity appears in `pendingApproval`; |
| 293 | it grants no approval authority. Read the fresh full request in the child thread before |
| 294 | responding, since the durable record can outlive its provider callback. Async questions |
| 295 | do not end the wait. |
| 296 | |
| 297 | ### `task_status` |
| 298 | |
| 299 | Reads a delegated task from the parent thread's durable projection. A task ID |
| 300 | from another parent thread is rejected. `childRunId` identifies the original |
| 301 | run. `status: "starting"` means the child's provider has not started its turn |
| 302 | yet, so a task that stays there has not begun work. A task in a linked |
| 303 | environment reads its run's status there for this. `workState` distinguishes |
| 304 | active work, a finished turn waiting for children, and an available result. The |
| 305 | task remains nonterminal until its known work finishes. Its published `summary` |
| 306 | and result transfer then remain stable across later follow-ups. |
| 307 | `hasPendingChildRuns` reports later queued or executing turns; `latestTerminal*` |
| 308 | exposes later executed, non-monitor results without replacing the published task |
| 309 | result. |
| 310 | |
| 311 | ### `task_cancel` |
| 312 | |
| 313 | Stops every task the child delegated, then the child thread with the internal |
| 314 | `thread.stop` command, cancels the task's own queued turn, and disposes automatic |
| 315 | parent delivery. Like a user Stop, `thread.stop` interrupts the running turn, holds |
| 316 | queued turns, and ends pull request watches. The task's own queued turn is cancelled |
| 317 | even if Stop already held it, so a task that is only queued can be cancelled; other |
| 318 | queued turns in the child stay held for Resume. A nonterminal task is rejected when |
| 319 | it has no interruptible run, no queued turn of its own, and its finished turn no |
| 320 | longer waits on background work or delegated tasks. Once a cancelled task's turn |
| 321 | ends, a completed result settles as `interrupted` and a failed one stays `failed`. A |
| 322 | terminal task returns its existing status, and its child thread still stops, |
| 323 | including later runs and watch wakes. In both cases, a follow-up that lost its child |
| 324 | run but still shows as running on the parent is cancelled there and reported as |
| 325 | `cancelled`. Published task results remain available. It accepts an |
| 326 | optional cancellation reason. |
| 327 | |
| 328 | ### `create_threads` |
| 329 | |
| 330 | Creates between one and twenty ordinary top-level T3 threads: |
| 331 | |
| 332 | ```ts |
| 333 | import type { OrchestratorMcpCreateThreadsInput as CreateThreadsInput } from "@t3tools/contracts"; |
| 334 | ``` |
| 335 | |
| 336 | Each entry independently resolves provider, model, and modes. The new threads |
| 337 | inherit the parent's project, branch, and worktree path, but they have no |
| 338 | sub-agent lineage. Entries with a prompt immediately dispatch a run; entries |
| 339 | without a prompt remain idle. `create_threads` is local-only: `target.environmentId` and |
| 340 | `target.projectId` are ignored even though the shared target contract accepts them. Use |
| 341 | `t3_thread_launch` with `environmentId` and `projectId` to select another environment or project. |
| 342 | |
| 343 | ### `t3_thread_launch` |
| 344 | |
| 345 | Launches one ordinary top-level thread through the app's launch service. Use an |
| 346 | explicit `workspaceStrategy` to create a new worktree (`worktree` with `baseRef`), |
| 347 | attach an existing checkout (`existing_worktree` with `worktreePath`), or use the |
| 348 | project root (`root`, also the default). The thread is bound to that workspace |
| 349 | before the agent starts. Creating a worktree in the task prompt does not update |
| 350 | this binding. |
| 351 | |
| 352 | Pass the task in `message`. Project, model, and modes inherit when omitted; |
| 353 | workspace does not. `scratch: true` launches without a project, in a folder of |
| 354 | its own under the environment's Scratch project. A new worktree with `startFromOrigin` omitted follows the new-worktree setting. For stacked PRs, use the parent branch as `baseRef` with |
| 355 | `startFromOrigin: false`. The new thread may not run with broader runtime or |
| 356 | interaction modes than the caller. As for `delegate_task`, a runtime mode the |
| 357 | provider does not offer is refused, and an inherited or default one steps down |
| 358 | to the broadest mode it offers. `create_threads` remains the batch option for a |
| 359 | shared checkout. |
| 360 | |
| 361 | Set `clientRequestId` on the initial launch to make it retryable. After an error |
| 362 | or a lost reply, resend the same request with the same key from the same |
| 363 | provider session. This reuses any thread already created by that request. If the |
| 364 | initial request had no key, check for the thread before launching again. |
| 365 | |
| 366 | ### `t3_thread_list` |
| 367 | |
| 368 | Lists durable thread shells in one project, newest first: `projectId` when |
| 369 | given, else the calling thread's project. Callers can filter by title, run |
| 370 | status, and whether app-owned sub-agent threads are included. Results are |
| 371 | bounded and offset-paginated. Deleted threads are never listed. |
| 372 | |
| 373 | ### `t3_thread_read` |
| 374 | |
| 375 | Reads the durable state, recent runs, and visible timeline of any thread in |
| 376 | the environment by thread ID. A deleted thread returns `thread_not_found`. The |
| 377 | default `messages` view returns user messages, assistant |
| 378 | messages, and proposed plans. The `activity` view also returns summarized tool, |
| 379 | reasoning, checkpoint, handoff, and runtime-request items. Large item text is |
| 380 | bounded and reports whether it was truncated. An agent in a T3 thread that |
| 381 | reads without a cursor gets the newest items, and `beforePosition=earlierPosition` |
| 382 | reads older ones. Client callers (the CLI, linked environments, outside MCP |
| 383 | clients) start at the oldest item instead, because the CLI and linked |
| 384 | environments on older versions read that way and follow only `hasMore`. |
| 385 | `afterPosition=-1` starts any read at the oldest item, and |
| 386 | `afterPosition=nextPosition` reads newer items. The server stops adding items once the result reaches about 30,000 characters and |
| 387 | reports the rest through `earlierPosition` or `hasMore`. Claude Code saves MCP |
| 388 | results over its token limit to a file instead of showing them, so a read has |
| 389 | to fit whatever `limit` an agent asks for. |
| 390 | |
| 391 | Thread and message results include required `createdBy` and `creationSource` |
| 392 | provenance. MCP-created threads and user-role messages use `createdBy: "agent"` |
| 393 | and `creationSource: "mcp"`; provider output uses `creationSource: "provider"`. |
| 394 | Actor and ingress are separate so agent-authored user-role messages remain |
| 395 | distinguishable from human-authored messages. |
| 396 | |
| 397 | Agents mention another thread by the `link` its result carries, |
| 398 | `<t3-thread://v2/<environmentId>/<threadId>>`, so they never format an id or |
| 399 | write a title, which goes stale when the user renames the thread. The |
| 400 | environment that owns the thread builds the link, so forwarded results and tasks |
| 401 | delegated to a linked environment name that environment. Clients open only that |
| 402 | environment's thread and show its current title; a link to a thread they do not |
| 403 | know renders as a label that opens nothing. Older `t3-thread://v1/<threadId>` |
| 404 | links name no environment: clients resolve them in the message's environment, |
| 405 | then by a unique match in another enabled environment. An outside OAuth client, |
| 406 | one that is not a linked environment, cannot render `t3-thread://` links, so it |
| 407 | gets the link Copy thread copies, `https://app.t3.codes/threads/<environmentId>/<threadId>` |
| 408 | on the server's `T3CODE_HOSTED_APP_URL`, for threads in this environment. The |
| 409 | hosted app offers the desktop app, the mobile app, or itself. |
| 410 | |
| 411 | List and read results report `snoozed`, `snoozedUntil`, and `pinned`, and |
| 412 | `t3_thread_list` filters on `snoozed`. The server's `isSnoozed` follows the |
| 413 | client's `effectiveSnoozed`, so agents and the sidebar agree: a snoozed thread |
| 414 | wakes early only when it has a pending request or fails after snoozing. Completed |
| 415 | runs, background wakes, and delegated completions keep it snoozed. |
| 416 | |
| 417 | They also report `blockedOnThreadWait` and `pendingBackgroundTasks`, the shell |
| 418 | fields behind the sidebar's Waiting label, so an agent can see what a thread |
| 419 | still waits on after its run completed. A subagent or `background_task` holds |
| 420 | the thread. A command or monitor holds it only with `awaited: true`, since agents |
| 421 | often leave a dev server running. |
| 422 | |
| 423 | ### `t3_thread_update` |
| 424 | |
| 425 | Updates metadata for the calling thread or any other thread in the environment. |
| 426 | The typed actions are `rename`, which requires `title`, and `regenerate_title`, |
| 427 | which rejects one. Pull request links go through the separate |
| 428 | `link_pull_request` and `unlink_pull_request` tools. Branch and workspace |
| 429 | changes are outside this tool. |
| 430 | |
| 431 | The result includes the command ID and durable event sequence together with the |
| 432 | resultant title, title-regeneration marker, and linked pull request. Reusing a |
| 433 | `clientRequestId` for the same action and thread replays the same command |
| 434 | receipt. Thread list and read results expose the linked pull request, and thread |
| 435 | detail also exposes an in-flight title regeneration. |
| 436 | |
| 437 | ### `t3_thread_send` |
| 438 | |
| 439 | Sends a message to any ordinary or delegated thread in the environment: |
| 440 | |
| 441 | - `auto` starts an idle thread, steers a fully active turn, or queues behind a |
| 442 | turn that is not yet steerable; |
| 443 | - `queue` creates a separate follow-up run after active work; |
| 444 | - `steer` requires a steerable active provider turn; and |
| 445 | - `restart` requires an active provider turn and uses the orchestrator's |
| 446 | interrupt-and-restart path. On a provider that can stop a turn and queue |
| 447 | messages but not restart a turn with new input, it stops the turn and queues |
| 448 | the message ahead of other queued messages; an unheld delegated-task result |
| 449 | that survives the stop still runs first. It is rejected when neither path |
| 450 | applies: the provider cannot stop a turn, Stop has already reached the turn, |
| 451 | or the turn or the new message is `/compact` or `/logout`. |
| 452 | |
| 453 | The target runtime and interaction modes may not be broader than the caller's. |
| 454 | Stable command and message IDs are derived from `clientRequestId` for |
| 455 | idempotent retries. |
| 456 | |
| 457 | `outputSchema` (also on `t3_thread_launch`) asks the run for a result as data. |
| 458 | The run stores the schema, the turn's prompt ends with how to hand the result |
| 459 | back, and the agent calls `t3_submit_output`. The server checks the value |
| 460 | against the schema before storing it, so the caller never parses a reply. A send |
| 461 | that asks for a result is queued instead of steered: the result belongs to one |
| 462 | whole turn. A turn can end without submitting; the caller sees a finished run |
| 463 | with no `output`. |
| 464 | |
| 465 | ### `t3_submit_output` |
| 466 | |
| 467 | Stores the calling thread's result on its running turn, once it fits the schema |
| 468 | that turn was sent with. A turn that was asked for nothing answers for the |
| 469 | newest turn that was asked and has not answered yet, which is how an agent that |
| 470 | ended its turn to wait gives its result after it is woken. A rejection names what did not fit, so the agent can |
| 471 | correct it and call again; a later accepted submission replaces an earlier one. |
| 472 | |
| 473 | ### `t3_thread_wait` |
| 474 | |
| 475 | Waits for a selected run to become `completed`, `failed`, `cancelled`, |
| 476 | `interrupted`, or `rolled_back`. Without `runId`, it pins the latest run at call |
| 477 | time; an idle thread returns immediately. A timeout reports the latest durable |
| 478 | status and does not cancel work. `output` carries what the run submitted |
| 479 | against its `outputSchema`; with `untilOutput`, a completed run that has not |
| 480 | submitted yet is waited on until it has. |
| 481 | |
| 482 | ### `t3_thread_interrupt` |
| 483 | |
| 484 | Interrupts a selected active run through the normal V2 `run.interrupt` command. |
| 485 | Without `runId`, it selects the newest interruptible run. A terminal run is |
| 486 | returned unchanged, and a thread with no active provider turn returns |
| 487 | `no_active_run`. |
| 488 | |
| 489 | ### Scheduled tasks |
| 490 | |
| 491 | `schedule_task`, `list_scheduled_tasks`, and `delete_scheduled_task` manage |
| 492 | recurring work in the app scheduler; `schedule_task` with a `scheduledTaskId` |
| 493 | updates an existing task. A schedule |
| 494 | runs its prompt on an interval, at a fixed time in the server's local time |
| 495 | zone, or on each qualifying webhook request, even when no turn is active. |
| 496 | Without a signature, anyone with the webhook URL can trigger a run. |
| 497 | Signature checks, filters, and dedupe can skip a webhook request. |
| 498 | `bindToCurrentThread` defaults to `true` only when the caller has a thread in |
| 499 | the task's project; otherwise it defaults to `false`. Bound runs post into |
| 500 | that thread; unbound runs each launch a fresh thread in the task's project. |
| 501 | Explicit `bindToCurrentThread: true` without a caller thread in that project |
| 502 | is rejected. Pausing uses `schedule_task` with `scheduledTaskId` and `enabled: false`; |
| 503 | deletion is permanent. |
| 504 | |
| 505 | ## Delegated Task Lifecycle |
| 506 | |
| 507 | The MCP server is a command ingress into V2. It does not call provider adapters |
| 508 | directly. |
| 509 | |
| 510 | ```text |
| 511 | provider model |
| 512 | -> MCP tools/call delegate_task |
| 513 | -> authenticated OrchestratorMcpService |
| 514 | -> shared ThreadManagementService |
| 515 | -> V2 delegated_task.request command |
| 516 | -> child thread + child run |
| 517 | -> parent app_owned subagent projection |
| 518 | -> parent/child execution nodes |
| 519 | -> consumed subagent_spawn context transfer |
| 520 | -> normal provider effect and runtime ingestion |
| 521 | -> child run reaches a terminal state |
| 522 | -> parent subagent/node/turn item finalized |
| 523 | -> consumed subagent_result context transfer |
| 524 | -> wait result or later task_status result |
| 525 | ``` |
| 526 | |
| 527 | The child thread has lineage relationship `subagent` and points back to the |
| 528 | parent node. The parent gets an `app_owned` sub-agent projection and a |
| 529 | sub-agent turn item so the existing debug UI can render progress. |
| 530 | |
| 531 | Terminal provider events trigger finalization. The event stream first replays |
| 532 | persisted events and then follows live events, so finalization also runs after |
| 533 | a server restart. An existing `subagent_result` transfer makes finalization |
| 534 | idempotent. |
| 535 | |
| 536 | Users rarely watch child threads, so a child question would otherwise go |
| 537 | unanswered. When a child opens a pending `user_input` request, the parent gets |
| 538 | a notification message telling it to answer with the pending request tools or |
| 539 | ask the user. The message says whether the child is blocked or, for a Codex |
| 540 | async question, still working. If the parent's turn is running and its provider |
| 541 | can steer without interrupting tools, the notification steers into that turn, |
| 542 | like a background task's completion. A queued notice would wait behind a |
| 543 | long-running orchestrator turn that may never end. Otherwise it queues. If the |
| 544 | question is answered or dismissed before a queued notification starts a turn, |
| 545 | that queued turn is cancelled. Approvals are not |
| 546 | routed, because those tools cannot answer them. |
| 547 | A parent still blocked in a `delegate_task` wait gets the blocking question |
| 548 | through that wait instead. |
| 549 | If the provider cuts that wait short, a still-pending live question wakes the |
| 550 | parent when its launching run completes, fails, or waits for post-turn work. |
| 551 | Stopping or interrupting the parent prevents this catch-up. |
| 552 | |
| 553 | A failed run exposes its provider error before any progress text. Successful |
| 554 | results use the latest assistant content from the final work turn. |
| 555 | |
| 556 | ## Policy And Idempotency |
| 557 | |
| 558 | - A child runtime mode may stay equal to or become narrower than the parent |
| 559 | mode. It may not escalate privileges. |
| 560 | - A child interaction mode may stay equal to or narrow from `default` to |
| 561 | `plan`. It may not escalate from `plan` to `default`. |
| 562 | - Thread tools take any thread in the environment as a target. For a thread |
| 563 | caller, list and search cover one project: its own unless `projectId` is given. |
| 564 | - A tool that changes another thread needs the calling thread's live run, and |
| 565 | the target's runtime and interaction modes may not be broader than the |
| 566 | caller's. This is the same privilege ceiling as child creation. |
| 567 | - Provider instances must be enabled, installed, available, authenticated, and |
| 568 | backed by a V2 adapter. |
| 569 | - A requested model must be advertised by the selected provider when the |
| 570 | provider publishes a model list. |
| 571 | - `clientRequestId` derives stable command, thread, and message IDs within the |
| 572 | provider session. Retrying the same call returns the same durable work. |
| 573 | - Calls without `clientRequestId` receive a generated request key and create |
| 574 | new work. |
| 575 | |
| 576 | Expected denials use the typed `OrchestratorMcpFailure` result: |
| 577 | |
| 578 | ```text |
| 579 | capability_denied |
| 580 | parent_not_active |
| 581 | provider_unavailable |
| 582 | model_unavailable |
| 583 | runtime_mode_escalation_denied |
| 584 | interaction_mode_escalation_denied |
| 585 | task_not_found |
| 586 | task_not_cancellable |
| 587 | thread_not_found |
| 588 | run_not_found |
| 589 | thread_not_sendable |
| 590 | thread_not_interruptible |
| 591 | invalid_request |
| 592 | orchestration_error |
| 593 | ``` |
| 594 | |
| 595 | ## Code Ownership |
| 596 | |
| 597 | - Shared schemas: `packages/contracts/src/orchestratorMcp.ts` and |
| 598 | `packages/contracts/src/threadMetadataMcp.ts` |
| 599 | - MCP services: `apps/server/src/mcp/OrchestratorMcpService.ts` and the focused |
| 600 | `apps/server/src/mcp/ThreadMetadataMcpService.ts` |
| 601 | - Tool definitions and handlers: |
| 602 | `apps/server/src/mcp/toolkits/orchestrator/` |
| 603 | - HTTP registration and authentication: |
| 604 | `apps/server/src/mcp/McpHttpServer.ts` |
| 605 | - Credential lifecycle: `apps/server/src/mcp/McpSessionRegistry.ts` |
| 606 | - Provider injection: |
| 607 | `apps/server/src/orchestration-v2/ProviderSessionManager.ts` and V2 adapters |
| 608 | - Durable delegated-task command and finalization: |
| 609 | `apps/server/src/orchestration-v2/Orchestrator.ts` |
| 610 | |
| 611 | ## Verification |
| 612 | |
| 613 | The integration test uses the real MCP toolkit registration, V2 orchestrator, |
| 614 | SQL persistence, event ingestion, projections, and checkpoints. Only the |
| 615 | external provider adapters are deterministic test implementations. |
| 616 | |
| 617 | Coverage includes: |
| 618 | |
| 619 | - capability discovery; |
| 620 | - cross-provider delegated completion; |
| 621 | - prompt-only child context; |
| 622 | - parent and child lineage projections; |
| 623 | - spawn and result context transfers; |
| 624 | - async status polling; |
| 625 | - cancellation; |
| 626 | - batch ordinary-thread creation; |
| 627 | - thread listing and timeline reads, including another project's threads; |
| 628 | - ordinary-thread send, wait, steering, and interruption; |
| 629 | - inheritance and per-thread provider overrides; and |
| 630 | - idempotent retries. |
| 631 | |
| 632 | Provider adapter tests separately verify Codex, Claude, Cursor, Grok, and ACP |
| 633 | Registry behavior and MCP injection. The provider-session manager test verifies |
| 634 | that credentials exist before an adapter opens and are revoked when it closes. |