v2-refactor-temp/docs/ai/README.md
The AI domain is the largest single surface in the v2 refactor. The
renderer's src/renderer/src/aiCore/ tree (~80 files) is deleted in
full; its logic ports into src/main/ai/ (~150 files). The transport
becomes IPC + a Main-owned active-stream registry. This directory
breaks the change into clusters reviewable in parallel — one cluster
per agent.
Each cluster doc:
| Cluster | What it covers | Doc |
|---|---|---|
| Stream Manager | AiStreamManager, listeners, persistence backends, lifecycle, dispatcher, context providers | stream-manager-cluster.md |
| Agent Loop | Agent class, hooks composition, single-pass stream, observers, tool-execution events | agent-cluster.md |
| Params Pipeline | buildAgentParams, RequestFeature set, capability resolution, system-prompt assembly | params-cluster.md |
| Tool Registry | Registry, built-in tools, MCP sync, meta-tools, defer exposition, tool-call repair | tool-cluster.md |
| Provider Resolution | provider/config.ts, endpoint.ts, extensions, custom providers (aihubmix, newapi), Claude Code runtime helpers | provider-cluster.md |
| Messages & Observability | UI part conversion, file processor, OTel span adapter | messages-observability-cluster.md |
| AiService & IPC | AiService lifecycle wiring, IPC handlers, request-type schemas | ai-service-cluster.md |
| Renderer Transport | IpcChatTransport, dispatch coordinator, topic-level subscription, awaiting-approval bridge | renderer-transport-cluster.md |
| Renderer V2 Chat UI | Parts-based rendering, approval cards, branch navigation, execution overlay | renderer-ui-cluster.md |
| Composer Tool Surface | + menu, / panel, active chips, assistant/agent tool discoverability and disabled-state rules | composer-tool-surface-design.md |
| Package Changes | packages/aiCore, packages/provider-registry, shared types | packages-cluster.md |
| Data Layer | Agent / session / workspace schema rewrite, MessageService, migrators, DataApi handlers, shared types/schemas | data-cluster.md |
| Agents Core Carve | Renderer agent-session stack onto main (types/agent.ts enriched shape + hooks/agents + pages/agents + v2 utils/export); the history page rides this — measured not an independent page split | agents-core-carve.md |
Three smaller, self-contained sub-features have their own design docs that pre-date this index — these stay where they are and the cluster docs above reference them:
adapter-family.md — endpoint → @ai-sdk/*
routing. (Covered also at Provider Resolution.)translate-on-main.md — translate flow,
why it's not chat-shape.branch-navigation.md — UX for branched
DAG history; UX-side, not on the AiService critical path.token-estimator-p0.md — backend token
estimation behind the input-bar badge.large-file-upload-port.md — outstanding
port from renderer for Gemini/OpenAI File APIs.tool-approval-defer-fix.md — fix design
for the defer-exposition approval-gate bypass (review #1).tool-approval-state-consolidation.md —
diagnosis + target design + phased refactor plan for the approval split-brain
(stream / DB / renderer state can't be simultaneously consistent); single-authority
(DB parts) model, collapsing the main-side multi-write into one authoritative write
(Phase 1 = CR-002, done).steer-state-machine-consolidation.md —
steer-queue state machine (#15935 fresh-eyes review): delete the lastTerminalKind
shadow, drive chaining / enqueue / approve-gate off the single authority
(stream.status on the in-grace stream). Blockers 1–3 implemented on
codex/main-3 (+ S5 removed for free); blocker 4 (renderer executionId reuse)
handed off to the renderer slice.channel-ingress-security.md — security
model + gaps for externally-triggered (inbound IM) agent runs (review D1).stream-ipc-validation.md — scheme to validate
the untrusted-renderer AI stream IPC payloads (review D2).declarative-tool-registry.md — one
declarative registry for Claude Code agent tools (policy + catalog UI +
chat rendering): exposure/category/pairGroup, opt-out disabledTools,
SDK 0.3.168 upgrade, 7-PR sequence.The clusters are not strictly independent — but the listed order roughly matches dependency depth (later clusters consume earlier ones). For solo review, take them in order. For agent-parallel review, assign the first six clusters in any order; renderer clusters last since they consume the Main contract.