Spike: spawn and show Model Router sessions from T3 through an MCP threads toolkit

[lukemaj]

Outcome

Evidence to decide whether T3 Code becomes the surface that spawns and shows Model Router's sessions (planner, dispatcher, workers, and "send this to Astra" work), integrated as additions rather than edits to upstream code. This is a spike: answers and a throwaway draft PR, not a product change.

Idea (user, 2026-09-24)

Instead of making T3 discover agents launched elsewhere (#1), let T3 spawn them. Agents in a T3 thread start child threads on a chosen harness and model through a new T3 MCP toolkit; children show in the Agents panel; AgentsMD plugins such as Model Router extend T3 instead of competing with it. Model Router keeps policy, capacity and the durable job ledger; T3 executes and displays. Depending on T3 is acceptable.

Questions to answer, each with evidence

1. Spawn: can a new MCP toolkit (next to device, preview, pullRequests in apps/server/src/mcp/toolkits) let an agent in thread A create thread B on a chosen provider, model and effort, give it a task, and return B's result to A? Per provider: Claude, Codex, OpenCode, Grok.

2. Message a live thread: can A (or an outside process) send B a message while B is working and while B is idle; is it steering or a queued follow-up; does the reply reach A? This is the delivery path Report terminal job state back to the planner: ready to merge or blocked model-router#94 needs.

3. Show as subagent: can B appear as a child of A in the Agents panel (AgentsPanel.tsx, subagentRuntime.ts)? What is the smallest parent/child link, and which existing upstream files must change (count files and lines)?

4. Router kits: can T3 launch a provider session with Model Router's role configuration (CODEX_HOME, CLAUDE_CONFIG_DIR, OpenCode config directory, GROK_HOME, permission set)? See ProviderInstanceEnvironment, ClaudeHome, CodexHomeLayout.

5. Durability: does a T3-spawned session keep running when the desktop window closes or the server restarts? Can the server run headless (npx t3 / apps/server) as the executor overnight?

6. Router as client: what API would the Model Router runner call to have T3 spawn and message threads (HTTP, WebSocket orchestration, MCP), keeping the router's ledger authoritative? Model Router may depend on T3 (user, 2026-09-24: the user is its only user); a direct CLI fallback is not required, so also say which existing runner machinery T3 would make unnecessary.

7. Upstream cost: for each existing file the spike had to touch, how often did it change upstream in the last 90 days (git log --since=90.days upstream/main -- <file>)?

8. Agents panel (user request, 2026-09-24): make the small bounded change to the spawning logic so threads spawned for Model Router (child threads of a parent thread) appear in the parent thread's right-side Agents panel, which today shows "No agents yet" for them. Implement it in the spike and prove it live.

9. Sidebar Subagents section (user request, 2026-09-24): child threads do not appear in the main sidebar thread list by default. They are grouped in a new collapsible Subagents section next to Snoozed and Settled, so the main list keeps only threads the user interacts with. Implement it in the spike, reusing the Snoozed/Settled section mechanism, and report which existing upstream files it touches.

Deliverables

• One findings comment on this Issue answering 1 to 9, each marked verified (with the command or live run), inference, or unknown.
• A draft PR on a spike branch with the minimal toolkit and any panel link, not merged, with its diff split into new files versus edited upstream files.
• A recommendation: go, go with changes, or no-go, with the smallest surviving design.

Constraints

• Never touch the user's running T3 instance (MCP at 127.0.0.1:3773, ~/.t3/userdata) or its dev servers. Use an isolated T3 home and a different port.
• Prefer new files over edits to upstream code.
• No provider credentials copied into the repo; no releases or installs.

Non-goals

Production quality, mobile support, Project Direction changes in either repo (the user decides after the findings).

Blockers

None.

Objective contribution

Directly serves this fork's Objective (one control surface for agents across harnesses) and may replace #1's discovery approach; also decides the delivery path for toolboxmd/model-router#94.

[lukemaj]

Spike findings (draft PR #4)

Recommendation: go with changes. T3 can spawn, message and show Model Router sessions on all four providers with 2 edited upstream files (+54 / -3 lines). Everything else is new files. Two blockers to production use: running turns do not survive a T3 server restart, and T3 can wake only planners that are T3 threads. Both are below.

Setup. Isolated dev instance: T3 home under /tmp, server port 14791, web port 7056, scratch git repo as the project. Parent thread on claudeAgent / claude-haiku-4-5. The user's instance on port 3773 and ~/.t3/userdata were not touched. Provider CLIs used their normal logins, and nothing was copied into the repo. Screenshots are in the PR body.

1. Spawn: verified on Claude, Codex, OpenCode and Grok

• Spawn. The new threads toolkit (spawn_thread, message_thread, read_thread, list_child_threads) sits next to device, preview and pullRequests. spawn_thread dispatches ordinary thread.create and thread.turn.start commands with an instanceId, model, effort and runtimeMode. Effort maps to Claude effort, Codex/Grok reasoningEffort and OpenCode variant.
• Live run (verified). The Claude parent spawned one child per provider. Each child replied correctly and its reply came back to the parent:
  • codex / gpt-6-luna / effort low: MANGO
  • grok / grok-build: KIWI
  • opencode / opencode/nemotron-3.5-lightning-free: PINEAPPLE
  • claude-router (a second Claude instance) / Haiku: see item 4
• Getting the result back.
  • Push (verified on all four): with reportBack: true, each finished child turn is sent to the parent as a message, for example [Subagent Codex child (thread …) finished a turn] MANGO. The parent then acts on it.
  • Pull (verified once): read_thread, called from inside one of Claude's native subagents, reported the child's status and error.
  • The tools return immediately, so the Codex MCP tool timeout does not apply.
• Parents on other providers (inference). Only a Claude parent was tested live. McpSessionRegistry issues the t3-code credential to every adapter (Claude, Codex, OpenCode, Grok, Cursor and Antigravity all read readMcpProviderSession), so the toolkit should reach agents on any provider.
• Capacity failures (verified). Muse free (opencode/muse-spark-1.3-contributor-free) hit free_tier_limit. OpenCode kept retrying and the child stayed running. The failure appeared only as a runtime.warning activity, so a router must watch for it.

2. Message a live thread: verified. Running threads get a steer, not a queued follow-up

• Idle child (verified). message_thread starts a new turn. Codex replied PAPAYA and the reply reached the parent.
• Working child, Codex (verified). message_thread from the parent returned statusBefore: running. The provider log shows a single turn/started / turn/completed pair. The message was folded into the running turn: the child answered only FOLLOWUP-DONE and dropped its original BUSY-DONE reply.
• Working child, Claude, from an outside process (verified). The message went through POST /api/orchestration/dispatch and was merged into the running turn. The reply was SLOW-DONE STEERED OUTSIDE.
• OpenCode and Grok (inference). By code reading, both adapters treat a mid-turn send as a steer (OpenCodeAdapter.ts:3164, GrokAdapter.ts:1535). Not tested live mid-turn.
• No server-side queue. The "queue" behavior users see is composer-side only.
• Bug found (verified). A message sent while a Claude child was still starting created a second turn and left the thread running forever. The spike now refuses message_thread until the child is running or idle.
• What this means for model-router#94. Waking the planner becomes one thread.turn.start into the planner's T3 thread. A busy planner is steered, not queued, so the "retry until idle" logic goes away, but the report lands mid-turn.
  • Limit: this works only when the planner is a T3 thread. A planner in a plain terminal harness outside T3 still needs today's per-harness callback path. That touches the Objective's "planner in any harness" and is the user's call.

3. Show as a subagent: verified, with no edits to AgentsPanel.tsx or subagentRuntime.ts

• Smallest parent/child link. The child's id carries the parent: sub.<parentThreadId>.<suffix>. It needs no contract, projector or migration change and survives restarts.
• How the rows get there. A bridge in the toolkit layer subscribes to domain events. It mirrors each child's thread.created and thread.session-set into the parent's activities as task.started / task.updated / task.progress rows with agentKind: "agent", which the existing fold already renders.
• Verified. Rows appeared for MCP-spawned children and for children created by an outside process over HTTP. They showed model, effort, instance, running/idle/failed/stopped status and the last reply.
• Upstream files for the panel: 0. The toolkit registration is 1 file (McpHttpServer.ts, +7).
• Limits.
  • Panel rows are not clickable (AgentRow is non-interactive). Opening the child from its row would mean editing AgentsPanel.tsx.
  • When the parent's own session is disconnected, the fold marks live rows as interrupted even if the child is still running (inference from ChatView.tsx:2923).

4. Router kits: verified for per-instance environment; inference for the specific variables

• Environment (verified). A claude-router instance in settings.json with environment: [{name: "MR_ROLE", value: "worker-kit-proof"}] ran a child whose echo MR_ROLE=$MR_ROLE printed MR_ROLE=worker-kit-proof.
• Home directories (code). Every instance's ProviderInstanceConfig.environment is passed to the provider process (ProviderInstanceEnvironment.ts). On top of that:
  • Claude homePath becomes CLAUDE_CONFIG_DIR (ClaudeHome.ts).
  • Codex homePath becomes its home, with an optional authOverlay that shares auth.json (CodexHomeLayout.ts).
• Inference. CODEX_HOME, CLAUDE_CONFIG_DIR, OPENCODE_CONFIG_DIR and GROK_HOME are plain environment variables, so each role kit can be one provider instance. Not verified per variable.
• Permissions. Per thread through runtimeMode (approval-required, auto-accept-edits, auto, full-access), which spawn_thread accepts.
• Gap. Instances are static settings entries. Model Router's per-launch generated kit directories would become stable per-role directories, or need a settings write per kit.

5. Durability

• Headless executor (verified). All children were spawned and finished with no browser attached; the first browser connected after they were done. npx t3 / apps/server works as a headless executor.
• Server restart (verified). A running Codex turn ended with "Provider session did not survive a server restart. Send a new message to continue." The next message resumed the same provider conversation: the child still knew its first answer, MANGO.
  • Provider processes are server children. None were left after I stopped the server; I checked for processes whose working directory was in my sandbox.
  • So an overnight executor loses in-flight turns on any T3 restart or update, and the router ledger must re-send.
  • The spike's reportBack flag is in memory and was lost across the restart (verified: the post-restart reply was not reported to the parent).
• Closing the desktop window (inference, not tested). The window only hosts a client. Quitting the desktop app stops its bundled server and behaves like the restart above.
• Idle sessions (inference from logs). The session reaper (inactivityThresholdMs: 1800000) stops idle sessions after 30 minutes. They resume on the next message.

6. Router as client

• API (verified). Bearer token from t3 auth session issue (scopes orchestration:read / orchestration:operate), then:
  • POST /api/orchestration/dispatch with thread.create, thread.turn.start or thread.turn.interrupt
  • GET /api/orchestration/threads/:id for messages and activities
  • GET /api/orchestration/shell for status
  • All test traffic went through these endpoints. A job created from outside with id sub.<plannerThreadId>.router-job-1 appeared in the planner's Agents panel and in the Subagents shelf, with no MCP involved.
• Push instead of polling (inference, not exercised). The WebSocket RPC orchestration.subscribeThread / subscribeShell.
• Keeping the ledger authoritative. The router keeps job to thread id (the id can embed the job id) and treats T3 as the executor. Command ids are deduplicated by the engine (code).
• Runner machinery T3 would make unnecessary:
  • the harness launch and resume paths in runner/harnesses.py (CodexCLI, ClaudeCLI, OpenCodeServer, GrokBuildCLI)
  • most of runner/adapters.py
  • the four planner callback kinds (the Scope DiffPanel patch cache keys by theme pingdotgg/t3code#94 path collapses into one call)
  • transcript display
• What stays: policy.py routing, rate-limit probes, kits.py (as instance definitions), the store/ledger and controller, and stall and capacity detection. supervisor.py's "survives controller death" guarantee is not replaced, because T3 does not keep a turn alive through its own restart.

7. Upstream cost

Commits on upstream/main in the last 90 days (git log --since=90.days upstream/main -- <file>):

File	Edited	Commits in 90 days
apps/server/src/mcp/McpHttpServer.ts	+7	8
apps/web/src/components/Sidebar.tsx	+47 / -3	142

For comparison, the files I avoided: AgentsPanel.tsx 6, subagentRuntime.ts 6, Sidebar.logic.ts 40, Sidebar.drag.ts 6, packages/contracts/src/orchestration.ts 58. The branch merges cleanly with upstream/main at f3cb2a1 (git merge-tree). Sidebar.tsx at about 1.6 commits a day is the real carrying cost.

8. Agents panel: implemented and verified live

Children spawned for a parent show in the parent's right-side Agents panel. See item 3 and the PR #4 screenshots. The last one shows 10 child-thread rows across 5 provider instances, plus one of Claude's native subagents.

9. Sidebar Subagents shelf: implemented and verified live

• Behavior. Child threads leave the main list and sit in a collapsible Subagents (n) shelf after Snoozed and Settled. It is collapsed by default and remembered in localStorage like the other shelves (screenshots 1 and 3).
• Upstream files touched: 1 (Sidebar.tsx, +47 / -3), plus new sidebar/SidebarSubagentsShelf.tsx and subagentThreads.ts.
• Why the shelf sits outside the sortable list. It reuses the shelf pattern (localStorage flag, slim rows through renderThreadRowInner) but not the sortable Snoozed/Settled markers. Joining that list would also mean editing Sidebar.logic.ts and Sidebar.drag.ts.
• Rough edges. Shelf rows are not draggable, are not part of the jump-key or shift-select order, and show the settled row's un-settle hover action. Mobile is not covered.

Smallest surviving design

1. Keep: the threads toolkit as new files with a one-line registration, the id-embedded parent link, and the bridge into task.* rows. The Agents panel needs no upstream edits.
2. Fix before real use:
   • drive the bridge from turn events, not session status (steer and dangling-turn cases)
   • persist reportBack (for example, in the parent's task.started payload, rebuilt on start)
   • fail spawn_thread fast on a disabled instance (already done in the spike)
   • surface runtime.warning capacity failures as failed on the parent's row
3. Model Router:
   • drive T3 over HTTP dispatch with a bearer, and keep the ledger authoritative
   • re-send after a T3 restart
   • map each role kit to a provider instance with environment / homePath
   • deliver Scope DiffPanel patch cache keys by theme pingdotgg/t3code#94 reports as thread.turn.start into the planner's T3 thread
   • keep the CLI callback path only if planners outside T3 must stay supported (user decision)
4. Sidebar: keep the 1-file hook for now. Propose a real parentThreadId plus the "hide child threads" behavior upstream (Ideas discussion), because carrying a Sidebar.tsx edit against 142 commits in 90 days is the main cost.

No Project Direction was changed. Deciding direction (T3 as the surface, planners limited to T3 threads) is yours.

[lukemaj]

Follow-up: restart continuation (A) and the simpler sidebar (B)

Same isolated setup as before: T3 home under /tmp, ports 14791 / 7056. The user's instance was not touched. Branch head 8638154, PR #4 body updated.

A. Restart continuation with continueThreadsAfterServerUpdate: true

Setup.

• Parent spike3-parent-2 (Claude Haiku), plus four children created the router way: POST /api/orchestration/dispatch thread.create with ids sub.spike3-parent-2.{claude,codex,opencode,grok}. The OpenCode child ran on Muse free (opencode/muse-spark-1.3-contributor-free).
• Each thread was given a roughly 90 s foreground shell command. Once the commands were running, I triggered a graceful server restart (the dev watcher's SIGTERM path, the same stop path that marks continuations).
• Claude refused a bare sleep 90 because of a hook in the user's Claude config, so Claude was retested with a 90 s Python loop.

Provider	Continues automatically?	Keeps id, parent link, panel row?	What is lost
Codex	Yes, verified. New turn id; the model said "The interruption ended the original process… I'm rerunning the same foreground command", then CODEX-DONE.	Yes, verified	The running shell process. The command was rerun from the start.
OpenCode (Muse)	Yes, verified. "Retrying the 90s foreground sleep", then OPENCODE-DONE.	Yes, verified	The running shell process (rerun)
Claude (parent and child)	Yes, verified. Both saw "continue where I left off"; the Python process died with exit code 137, both reran it, then SPIKE3-PARENT-2-DONE2 / CLAUDE-DONE2.	Yes, verified	The running process (rerun)
Grok	No, verified twice. The thread went to error: "Provider session did not survive a server restart. Send a new message to continue."	Yes, verified. The row went to "failed", then back to idle after a new message.	The in-flight turn. The conversation survives: the next message resumed it, and Grok still knew GROK-DONE.

Notes:

• Grok cause: unknown. Its session binding after the stop had no continueAfterServerUpdate marker (status stopped, activeTurnId null), so reconcileProviderSessions treated it as orphaned. Codex and OpenCode bindings kept the marker. I did not trace why the Grok adapter's session misses the marker.
• How the continuation is sent (code). Codex uses the promptless continuation (promptlessTurnContinuation: true). Claude, OpenCode and Grok get the input "Continue where you left off." (serverRuntimeStartup.ts:348). No extra user message appeared in the T3 thread.
• Side effects (inference). Continuation reruns the interrupted tool call from scratch. Non-idempotent commands can run twice.
• Spike bridge. Panel rows are driven by persisted events and the ids carry the parent, so rows and links survived (verified). The in-memory reportBack flag is still lost across a restart (verified earlier). Router-created children do not use reportBack anyway.
• Correction to the earlier finding. "A restart kills a running turn" was with the setting off. With it on, Codex, OpenCode and Claude continue by themselves. Grok still needs the router to re-send.

B. Children hidden from the sidebar, opened from the Agents panel

Replaces the Subagents shelf.

• Sidebar. Child threads (sub.<parent>.<suffix>) are filtered out of the visible list: 1 line of logic in Sidebar.tsx, 3 lines in total. No new section.
• Agents panel. Direct-spawn rows whose id is a child thread are wrapped in a new AgentThreadLink (a router Link to /$environmentId/$threadId). Native provider subagent rows stay plain.
• Live proof (verified):
  • The sidebar showed only the parent threads.
  • Clicking the "Restart opencode" row navigated to /<env>/sub.spike3-parent-2.opencode.
  • I typed "Reply with exactly the word CLICKED-THROUGH and nothing else." in the normal composer and sent it; the child replied CLICKED-THROUGH.
  • Screenshots 5 to 7 are in the PR body.
• Gap. There is no way back from the child to its parent (no sidebar row, no parent breadcrumb). Adding one is another small ChatView or header edit.

Upstream edit count.

Version	Edited upstream files	Lines	New files
Shelf (previous)	2: McpHttpServer.ts +7, Sidebar.tsx +47 / -3	+54 / -3	6
Hide + click-through (now)	3: McpHttpServer.ts +7, Sidebar.tsx +3, AgentsPanel.tsx +4 / -1	+14 / -1	6 (AgentThreadLink.tsx replaces SidebarSubagentsShelf.tsx)

The new version touches one more file but has a quarter of the edited lines. Its Sidebar.tsx hunk (142 upstream commits in 90 days) shrinks from 50 lines to 3, and AgentsPanel.tsx changes rarely (6 commits in 90 days). The branch still merges cleanly with upstream/main f3cb2a1.

Updated recommendation. Still go with changes, now with this design, and with continueThreadsAfterServerUpdate enabled on the executor. Model Router must still handle Grok re-sends and rerun side effects.

[lukemaj]

Superseded by #8, delivered in #10 (merged as dbc38af). The spike's findings shipped in production form.