1. Process and permission boundary
The Electron main process owns workspace files, PTY, Git and operating-system capabilities. A context-isolated bridge exposes only allowed IPC to the renderer. React renders the shell, panels and agent activity, while Monaco owns text models, selections and decorations. Web content never receives direct Node authority.
2. Provider normalization
Claude, OpenAI and local adapters normalize different streams into text, reasoning, plan, tool-call, edit, usage and error events. The renderer consumes shared events rather than vendor payloads, and a provider registry gives the Orchestrator model capability and credential state.
3. Agent execution loop
The Orchestrator opens a conversation turn and budget, then records model events in order. Tool calls pass permission and schema checks before entering the Workspace Tools queue; results return to the next model context. Cancellation, timeout and tool errors become terminal events so visible activity and internal state converge.
4. Reviewable edit transactions
File proposals are not saved immediately. They become pending transactions containing base revision, range, replacement and rationale. Monaco renders inline diffs and multi-file status for accept or reject. A changed base revision creates a conflict instead of a blind write, while turn checkpoints support grouped undo.
Workspace Tools wrap files, search, terminal, Git, LSP/DAP and MCP behind common contracts. Provider-tool separation allows model changes without editor-core changes and keeps an MCP failure from disabling basic editing. Sensitive operations require explicit approval and observable activity; partial failures leave transactions unapplied.
6. Process and state ownership
The renderer owns tab, editor and review UI state; Electron main owns filesystem, process permissions and IPC; the agent runtime owns provider sessions and the tool loop. Checkpoints preserve a separate pre-change recovery point so an AI response and a disk write are never one implicit state.
Large diffs, Monaco model count, agent streaming and terminal output can pressure the renderer. Batched activity events, bounded logs, file locks and checkpoint restore require validation; provider or MCP failure must not propagate into basic editing.
8. Security, observability and debt
The preload IPC allowlist, tool approval and workspace-path validation establish permission boundaries. Crash policy and activity logs support local diagnosis, while remote telemetry and SLOs are missing. Generating typed contracts between .cjs main modules and the TypeScript renderer remains debt.
