feat(orchestration): API keys, API profiles and agent-to-agent delegation

[BIackFIame]

Goal

Let agents delegate to other agents (including other vendors) through CanvasTTY, and give API-key based agents a safe place for keys and backend settings.

Behavior

• Provider API keys are stored in the main process, encrypted with Electron safeStorage, in one atomically written file with size quotas. It fails closed when OS encryption is unavailable. The renderer only sees which keys exist.
• API profiles name a model backend: protocol, HTTPS base URL, key reference and default model, with built-in presets. They are not agents and never appear in launchers.
• Session hierarchy: sessions carry role and parentSessionId, and restore drops orphaned subagents. This also fixes assertCreateRequest rejecting the four new providers over IPC.
• Capability descriptors state what CanvasTTY can really do with each agent, and a missing provider fails to compile.
• Agent control (spawn, send, observe, result, cancel, children) works over ordinary terminal sessions.
• Orchestration MCP reuses the agent-bridge design: an authenticated user-local socket, one-use bootstrap capabilities, rotated reconnect tokens, and scoping to the caller's own session subtree. MCP config is injected for Claude, Codex, OpenCode, Kimi and Hermes. Only orchestrator sessions receive it, and ordinary launches are unchanged.

Orchestration contract (maintainer's #32 review)

The maintainer's review of #32 lists requirements for an orchestration feature. This stack meets them as follows.

• Role: the launch dialog has an explicit Orchestrator option (added in feat(routing): launch routing, reasoning effort, server preparation and sign-in #69) and keeps the provider fixed. Cards show Orchestrator or Subagent. The option is separate from normal/YOLO permissions and keeps the selected profile.
• Ownership: an orchestrator sees and controls only its own subtree. Stale sessions are rejected, and an unrelated manual session is never owned by it.

Agent	Orchestrator	Subagent (worker)	Lifecycle source	Result / approvals
Claude, Codex, Qwen	Yes (PTY + MCP)	Yes	Hooks	Terminal
OpenCode	Yes (PTY + MCP)	Yes	Structured events	Terminal
Kimi	Yes (PTY + MCP, ACP)	Yes	Hooks / ACP	Terminal / ACP
Hermes	Yes (PTY + MCP)	Yes	Hooks	Terminal
Cursor, MiniMax Code	Yes over ACP; no PTY adapter	Yes	Process / ACP	Terminal / ACP
Grok, OMP, Pi	No (no verified MCP adapter)	Yes	Hooks (Grok) / process	Terminal
Devin, Antigravity	No	Yes	Process	Terminal

What is missing is stated plainly: Grok, OMP, Pi, Devin and Antigravity cannot be orchestrators yet, and a child's result is its terminal tail rather than a structured final answer.

Documentation

ADR: docs/adr/ADR-20260921-orchestration-mcp-rides-agent-bridge.md.

Verification

• npm run typecheck passed. Full suite: 723/723; Even G2 companion tests (npm run test:even): 47/47.
• Orchestration is covered by socket-level tests with fake agent processes.
• Live, with real models, on the final state of the series (macOS, OpenCode on the Z.AI plan):
  • an orchestrator called spawn_agent; the child started as a Subagent, wrote sub.txt, and the orchestrator waited and recorded the child's id;
  • with two children, one finished its file task and the orchestrator stopped the other with cancel_agent ({"canceled":true}, gone from list_agents).
• Not shown live: mixed-vendor delegation (only OpenCode is signed in on the test machine), approval prompts inside a child, and Linux or Windows desktops.

Series

Each part is one commit on top of the previous one. Please merge them in order. Until #63 is merged, GitHub also shows the earlier parts here; review only the top commit 9d4cb0b (Commits tab → last commit).

Part	PR	Scope	Lines
1	#63	Providers: Cursor, MiniMax Code, Devin, Antigravity	+579/−90
2	#64	API keys, API profiles, agent delegation (MCP)	+4275/−63
3	#65	Remote servers, placement, privacy tiers, accounts	+6620/−40
4	#66	Isolation: capsules, worktrees, containers	+5508/−839
5	#67	ACP, connection settings, remote containers	+6827/−563
6	#68	Project context and learning	+6148/−370
7	#69	Routing, reasoning effort, server preparation, sign-in	+3122/−467
8	#70	Open issues and safe fixes from open PRs	+306/−58

Compatibility with open upstream PRs

integration/stack-with-open-prs is this whole stack with #54–#62 merged on top and every conflict resolved. On that branch both TypeScript checks, 1492/1492 tests, npm run test:even (47/47) and electron-vite build pass.

• fix(even-g2): isolate transport keys per paired device #54, fix(even-g2): align local-network Settings card layout #56, fix(canvas): honor region bounds when snapping resize #57, fix(canvas): let sticky note editors scroll their own text #59, fix(plugins): prevent stale version writes during updates #60 merge cleanly.
• fix(settings): keep rejected writes out of live settings #58: conflicts in SettingsStore.ts. Keep this stack's store: it already serializes every write and publishes a value only after the disk write succeeds. fix(settings): keep rejected writes out of live settings #58's new tests pass against it unchanged.
• fix(window): restore state events after macOS Dock reopen #61: mechanical. registerIpc returns the window observer; keep both sides. This stack's IPC tests stub both window-state helpers, so they pass in either merge order.
• fix(even-g2): require explicit grant for answer capture #55:
  • TerminalManager.ts: keep this stack's launch structure. The answer-capture grant must also reach the prepared and measured-grid first start, because every real agent launch goes through that path.
  • hook-helper.mjs: keep this stack's 512 KiB input read and safe cut, and gate the answer on fix(even-g2): require explicit grant for answer capture #55's grant.
  • Fix and tests: 64ef294 (grant through prepared starts, feat(updates): add GitHub release updates across platforms #62 follow-ups) and c2dd726 (hook test under the grant).
• feat(updates): add GitHub release updates across platforms #62: whichever of this stack and feat(updates): add GitHub release updates across platforms #62 lands second needs the same commit:
  • The restore step in shutdownForUpdate must clear shuttingDown. Otherwise no session can start after a failed update; feat(updates): add GitHub release updates across platforms #62's own test fails without this.
  • Restore only live sessions, using the orphan-subagent rule.
  • Refuse to install while a server is being prepared or a capsule test runs.
  • Open About through SettingsLocation.

I will rebase this stack onto whichever of these lands first.

🤖 Generated with Claude Code

[howdeploy]

Integrated into main via #73. Your authored orchestration commit and @claude co-author trailer are preserved in the merge history. Thank you, @BIackFIame.