AirCoding/AirPlan/docs/architecture/decisions-round-1.md

# Architecture Decisions — Round 1

Date: 2026-05-25
Source: idea.md discussion, questions 1–18

## D-001: Bun as JS Runtime

- **Decision**: Bun.
- **Why**: Both OpenCode and Claude Code use Bun; built-in SQLite removes native addon dependency; native TSX support simplifies build config; C++ modules communicate via subprocess, not native addons.
- **Distribution**: Bundle Bun runtime with AirCoding.

## D-002: @opentui/solid as TUI Framework

- **Decision**: `@opentui/solid` (MIT licensed, standalone project, not coupled to OpenCode).
- **Why**: OpenTUI is an independent library consumed by OpenCode as a regular npm dependency. The TUI rendering layer is cleanly separated from OpenCode's business logic. Reference OpenCode's TUI component patterns for interaction design.
- **Reuse strategy**: Direct npm dependency on `@opentui/solid @opentui/core @opentui/keymap`. AirCoding TUI components reference OpenCode patterns but are independently implemented.

## D-003: Bun Monorepo

- **Decision**: Monorepo with Bun workspaces + Turborepo.
- **MVP packages**:
  - `packages/tui` — AirCoding TUI components on top of `@opentui/solid`
  - `packages/runtime` — Agent Loop, Session, Scheduler, Tool Registry, EventBus
  - `packages/llm` — Provider/Model abstraction (reference `@opencode-ai/llm`, but may fork/adapt)
  - `packages/toolchain` — C++ BuildTool, DiagnosticParser, TestRunner
  - `packages/cli` — Entry point, assembles all packages
- **Later**: Plugin SDK, debug knowledge, Python worker bridge.

## D-004: Python as Subprocess-Only Tooling

- **Decision**: Python workers are called via `Bun.spawn` with JSON-over-stdio. No long-lived Python server. No bundled Python environment.
- **Scope**: Python only wraps existing C++ toolchain scripts and Python-specific libraries. Experience mining, context assembly, and memory management stay in TS runtime.
- **Re-evaluated from idea.md**: idea.md assigned Python for Hermes-style learning and AirContext compression, but these are LLM + text + SQLite operations that Bun/TS handles natively. Keeping them in TS avoids unnecessary language bridging.

## D-005: Event-Driven Agent Architecture

- **Decision**: Event-driven. Main Agent subscribes to EventBus for agent/task/tool events and renders progress to TUI/HUD.
- **Main Agent state machine** (see `AirPlan/docs/architecture/main-agent-state-machine.md`):
  - IDLE → CLASSIFYING → DELEGATING → CONFIRMING → EXECUTING → SUMMARIZING → IDLE
  - INTERRUPTING for mid-execution user requirement changes (classified via LLM)
  - Error handling: Main Agent handles what it can, escalates to user only when necessary
- **Key constraint**: Main Agent must remain idle-ready for user intervention. Background tasks (ExperienceMiner, DebugKnowledge indexing) are dispatched to sub-agents.

## D-006: Sub-Agent Loops Are Independent

- **Decision**: Executor, Reviewer, and Debugger each have their own agent loop implementation. Not a shared generic loop engine.
- **Executor loop**: LOADING → THINKING → ACTING → OBSERVING → (loop with debugging sub-loop on failure) → FINALIZING
- **Reviewer loop**: LOADING → REVIEWING → DECIDING (approved / changes_requested / blocked)
- **Debugger loop**: GATHERING → ANALYZING → FIXING → (RECORDING or ESCALATING)
- **Sub-agent execution quality**: Claude Code is the behavioral benchmark (read-first, small edits, verify before return, follow Project Rules).

## D-007: Independent Processes for Sub-Agents

- **Decision**: Each Executor/Reviewer/Debugger is an independent Bun process spawned by Scheduler. IPC via stdio + JSON (same mechanism as Python workers).
- **Why**: Crash isolation, context isolation, natural worktree support. Single-process approach excluded due to context explosion and lack of fault isolation.
- **Communication**: Scheduler passes TaskSpec (worktree path, tool set, permission level) on spawn; sub-agent returns structured WorkerResult JSON on completion.

## D-008: Push Heartbeat + Soft/Hard Timeout

- **Decision**: Sub-agents push `AgentHeartbeat` events (status, turn count, tokens) every N seconds. Scheduler subscribes and detects stalls.
- **Heartbeat**: Push model. Sub-agent proactively reports state.
- **Timeout**: Hybrid. Hard timeout kills on expiration. Soft timeout warns and allows extension requests (sub-agent can justify need for more time). Scheduler decides per-task.
- **Loop detection**: Same error signature appearing N+ times triggers escalation to Main Agent (not auto-kill).

## D-009: Per-Session SQLite with Anthropic-Native Storage

- **Decision**: 
  - `~/.air/sessions/<session-id>/session.db` per session
  - `~/.air/projects/<project-id>/debug-records.db` cross-session
  - `~/.air/projects/<project-id>/learned-memory.db` cross-session
- **Message format**: Anthropic-native content blocks (TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock), following Claude Code's approach.
- **Provider switching**: Same-provider switching (e.g., Opus → Sonnet) is zero-cost. Cross-provider switching converts at API boundary (Anthropic format → target provider format → response → back to Anthropic format for storage).
- **Event persistence**: 
  - High-frequency events (TokenDelta, StdoutChunk) → EventBus only, not persisted
  - Durable events (TaskCompleted, ToolRunCompleted) → SQLite, synchronous write on main thread
  - WAL mode for concurrent read/write

## D-010: Full Context Dump on Session Exit

- **Decision**: On session exit, dump complete context to session storage. On resume, load from full dump, not reconstruct from summaries.
- **Recovery**:
  - Compaction is internal projection optimization, not data removal
  - Structured summaries serve as index for fast historical lookup
  - Scheduler rebuilds task queue from AgentTask table; running tasks judged by heartbeat timestamp
  - User sees full conversation history transparently

## D-011: Build System Auto-Detection

- **Priority**: CMake (built-in) > Meson/Bazel/XMake (capability plugin) > Makefile/.sln
- **Conflict handling**: When multiple build system files exist (e.g., CMakeLists.txt + meson.build), ask user to choose.
- **Generator**: Ninja first, fall back to Make if Ninja fails.
- **Config failure**: BuildTool built-in logic attempts fix first (install missing deps, adjust CMake args); if unresolved, hand off to Debugger.

## D-012: compile_commands.json — On-Demand Generation, No Caching

- **Decision**: Detect and generate `compile_commands.json` on demand via `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`. No persistence/caching between sessions.

## D-013: clangd CLI Mode for MVP

- **Decision**: CLI mode (`clangd --check=<file>` or equivalent) for MVP. Spawn on tool call, exit on completion. LSP daemon mode deferred to later phase if CLI latency proves unacceptable.

## D-014: LLM-Based Diagnostic Parsing

- **Decision**: All compiler/linker output parsed via LLM (not regex). LLM extracts structured `Diagnostic` records and generates semantic error signatures.
- **Error signature**: LLM computes semantic signature that normalizes across GCC/Clang/MSVC wording differences (e.g., "use of undeclared identifier" and "was not declared in this scope" map to same signature).
- **Linker errors**: Separately categorized from compiler diagnostics.

## D-015: LLM-Driven Project Initialization — Loose Acceptance

- **Decision**: Scanner collects facts → LLM infers `ProjectProfile` → loose schema acceptance (missing fields marked as `unknown`, not rejected) → user confirms/corrects → incremental field update with "may affect related inferences" hint.
- **No LLM retry loop** on schema mismatch. User correction is single-pass.

## D-016: Classification by LLM

- **Decision**: Main Agent uses LLM to classify user messages (chat, direct-mode, simple-task, needs-planning).

## D-017: Confirmation Gating

- **Decision**: Implementation-level changes that don't affect interfaces or architecture → silently proceed to EXECUTING. Architecture-level changes → Arc assessment required. Low permission: user confirms. High permission: auto-proceed with results displayed to user for immediate intervention.

## D-018: Interruption via LLM Intent Detection

- **Decision**: User interruption during execution detected via LLM intent classification, not Ctrl+C (ineffective with multi-process architecture).

## D-019: Scheduler — Full Dependency Handling

- **Decision**: Scheduler handles both hard dependencies (topological sort) and soft dependencies (optimization hints). Write-area conflict detection: different areas → parallel; same area but different code blocks → git worktree parallel then merge; same area, same code block → serial.
- **Concurrency**: Dynamic, API-rate-limit-aware, machine-resource-aware.
- **Failure**: Retry 3-5 times. Solvable failures block hard dependents only. Unsolvable failures (e.g., kernel limitation) go back to Architecture Designer. Repeated failures after max retries → Main Agent evaluates (silent resolution vs. user escalation).
- **Model selection**: Scheduler decides whether to force a specific model per task or let Executor choose.

## D-020: Memory System — Claude Code Style

- **Decision**: Claude Code's persistent memory system (MEMORY.md + frontmatter + typed layers) is the primary reference for memory design, alongside Hermes-style experience mining as a candidate layer.