Repository navigation
Description
The architecture reference does not explain the part of Agent Code that makes the product possible: reconstructing one conversation from several independent observations of a native provider runtime.
Agent Code does not drive providers through an SDK or an OAuth-backed API client. It runs the native CLI (Claude Code, Codex, OpenCode's TUI) or OpenCode's native service, and reconstructs what should be on screen from channels that disagree in timing, identity and trust: the emulated terminal screen, intercepted or proxied model streams, committed JSONL/rollout transcripts, screen- or structure-derived conditions, process state and subagent transcripts. Section 8.3 of ARCHITECTURE.md currently summarizes the ownership ledger in a few paragraphs with one small example diagram, and section 5.2/5.3 lists the headless packages as table rows without showing their internal structure.
A maintainer reading the reference cannot currently answer:
- Why the application emulates a terminal instead of calling a provider API, and what that costs.
- What each headless package (
claude-code-headless,codex-headless,opencode-headless,opencode-terminal-headless,agent-transcript-parser) contains, which channels it produces, and where the package/application boundary sits. - Which channel is trusted for which fact (assistant text never comes from the screen; committed transcripts outrank live streams; ghosts only fill a stalled committed tail).
- How main forwards channels without losing boundaries, how the renderer folds them into
SessionRuntime, how collectors turn runtime slices into candidates, and how the ledger produces{ rows, decisions, unknowns }. - Every owner kind, rejection reason and ordering rule, and the example that motivates each.
- How that sanitized object becomes painted rows: the view bridge, provider operation dispatch, the shape recorder (sightings), the per-provider
shapes.tscatalogs, and the audit/coverage gates. - How real recordings and debug bundles become fixtures, and which replay invariants hold at every tick.
Acceptance criteria:
- Add a dedicated, source-grounded chapter for the observation → sanitized conversation → rendering pipeline, with enough diagrams to follow a prompt from PTY bytes to painted rows.
- Document each headless package's structure, public entry points, produced channels and sanitization responsibilities, with a structure diagram per package family.
- Document the ownership model exhaustively: owners, source planes, content kinds, candidate identities, every
RenderReason, provider suppression policy, the ghost predicate, the ordering law, unknowns and identity stability. - Document the A→B→C→D method as architecture: sanitized object, shape recorder, shape catalog, one-shape-at-a-time rendering, and why fixtures come from real captures rather than hand-invented expectations.
- Keep diagrams consistent with the reference's current diagram conventions (question, scope, takeaway, committed SVG preview).
- Every claim links to the implementation or package source at the inspected revision.
Activity
docs(architecture): record combining the diagram and pipeline PRs