# Runnable Steps — Design

How this repo turns the tutorial into a **from-scratch build you can run at every
chapter**. This document is the blueprint; it was reviewed by an independent
model (Codex, Gate 0) and incorporates that review.

## 1. Goal & principles

A reader should feel they are *building* a coding agent, one runnable step at a
time — not reading a finished codebase. Concretely:

1. **No-key first run.** The first command in every chapter runs against a local
   mock model — `npm install` is the only setup. Feeling the thing work must not
   require an API key. Real models are an optional `--live` smoke, never the main
   path. (nanoGPT's "feel the magic" quick start.)
2. **Diff-first narrative.** A chapter reads: *run the previous step and watch it
   fail or fall short → here is the small diff this chapter adds → run this step
   and watch the new behavior.* The full snapshot is an entrypoint at the end,
   not the opening. The "I built this" feeling comes from the diff + observed
   change, which single-source slicing alone does **not** produce.
3. **One source, everything generated.** `steps/canonical/` is the only hand-
   written code. Per-chapter snapshots, the code blocks in the docs, and the
   example transcripts are all generated from it. Change canonical → regenerate →
   CI `git diff --exit-code` blocks any drift.
4. **Every step runs, proven by CI with no key.** Each step, in both languages,
   compiles/imports and passes a scripted scenario against the mock — asserting
   machine-observable events (tool calls, side-effect files, control flow), never
   the model's natural language.
5. **Seams, not rewrites.** New capabilities enter at a small set of named
   integration points (§3). A chapter that needs a seam introduces it as that
   chapter's explicit refactor — we do not pre-stub empty hooks, and we do not
   pretend the loop never changes.
6. **Small enough to read; mirrored in two languages.** Each step's core files
   are tens of lines, single-backend (Anthropic only). TS and Python are kept
   behaviorally identical, enforced by a parity check on a normalized event log.

Production `src/` and `python/mini_claude/` stay untouched as the *fuller*
reference; ch13 compares three tiers: your final step → this repo's production
version → real Claude Code.

## 2. Layout

```
steps/
  canonical/{ts,py}/     # ONLY hand-written source. #step (slice) + #region (doc) markers.
  scenarios/*.json       # shared scripted model behavior — used by test, run --demo, @transcript
  build.mjs              # canonical --slice--> dist/<step>/{ts,py}  (self-contained snapshots)
  run.mjs                # run a step: --demo (default, no key) | --live | --diff | --list | --py | -- <prompt>
  mock-anthropic.mjs     # local server speaking the real Anthropic /v1/messages (+SSE) protocol
  mock-anthropic.selftest.mjs  # proves the real TS & Python SDKs work against the mock
  docs-sync.mjs          # inject @snippet / @diff / @transcript into docs/ & en/docs/ ; lint ; normalize
  test.mjs               # every step × {ts,py} × scenario: compile/import + assert + parity
  lint-markers.mjs       # validate #step / #region / @snippet integrity
  DESIGN.md              # this file
  dist/                  # generated, gitignored
```

## 3. Seam matrix (the named integration points)

The agent is written so capabilities attach at these seams. A chapter's diff is
"introduce/extend seam X". This keeps the loop legible and bounds the marker
churn. Seams are added at the chapter that first needs them (not upfront):

| Seam | First chapter | What plugs in later |
|------|---------------|---------------------|
| `callModel(req)` | 1 (inline) | ch5 turns it into the streaming call; it is the single model-call site |
| `toolRegistry` | 2 | ch9 skill / ch11 agent / ch12 mcp add tools |
| `executeToolCall(name,input)` | 2 | ch6 wraps it with `permissionGate` |
| `buildRequest()` (system+tools+messages) | 3 | ch3 system prompt; ch8 memory injection |
| `history` / message array | 1 | ch7 compaction rewrites it; ch4 save/resume serializes it |
| `runCli(argv)` / `slashCommand(input)` | 4 | ch7 `/compact`, ch9 `/skill`, ch10 `/plan`, ch15 `/goal` `/loop` |
| `sessionStore` | 4 | save/resume |
| `permissionGate(call)` | 6 | ch10 plan-mode read-only, ch15 auto classifier |
| `beforeTurn()` / `afterAssistant()` | 7 | ch7 compaction at turn boundary; ch8 memory prefetch |
| `auxModelCall(kind, system, messages)` | 7 | one-shot side calls: ch7 compact summary, ch15 goal evaluator, ch15 auto classifier (distinct from the main loop's `callModel`) |
| `eventSink` / trace | 3 | `--trace-request` (ch3 system), `--trace-stream` (ch5 chunks); the observable substrate for demos/tests |
| `clock` / scheduler | 15 | ch15 `/loop` — injectable so CI never really sleeps 60s |

Gate 0/1 correction: "loop only changes at ch5/ch6" was wrong. Context
(turn-boundary tool_use/tool_result pairing), memory (inject around the model
call), tool routing (mcp/subagent/skill), plan mode, and the aux one-shot calls
(compact/goal/classifier) all touch the core. `callModel` is inline in ch1 and
becomes the streaming call in ch5 — it is NOT abstracted early (no empty hooks);
each seam is introduced at the chapter that first needs it. `auxModelCall` is a
*separate* model-call site from `callModel` so the mock can tell a compaction /
evaluator / classifier request apart from a main-loop request (see scenarios).

## 4. Chapter → step map

13 code steps (ch1-12 + ch15); ch13/14 are doc-only.

| Ch | Step | New (prefer a new file) | No-key demo asserts (observable event) |
|----|------|-------------------------|----------------------------------------|
| 1 | 1 | `agent.ts`(**non-streaming** loop)+`tools.ts`(read_file)+`cli.ts` | reads a file → `read_file` call in event log |
| 2 | 2 | `tools.ts` grows to 6 tools | writes a file → file exists on disk |
| 3 | 3 | +`prompt.ts`; `buildRequest` uses it | `--trace-request` shows the system prompt block |
| 4 | 4 | `cli.ts`: arg parse + `sessionStore` + `/clear` etc | resume a saved session → prior message reloaded |
| 5 | 5 | `callModel`: `create`→`stream` (only change) | `--trace-stream` shows >1 text chunk over time |
| 6 | 6 | +`permissions.ts`; `permissionGate` wraps executeToolCall | `rm -rf` is denied → deny event, no side effect |
| 7 | 7 | +`context.ts`; `beforeTurn` compaction; `/compact` | mock forces high usage → message count drops / summary event |
| 8 | 8 | +`memory.ts`; deterministic top-k recall injected in `buildRequest` | new session → memory file read + injection event (no extra model call) |
| 9 | 9 | +`skills.ts`; `/name` → registry | `/commit` → skill prompt injected event |
| 10 | 10 | +`plan.ts`; `--plan`/`/plan` via permissionGate | plan mode → write tool denied event |
| 11 | 11 | +`subagent.ts`; `agent` tool | `agent(explore)` → sub-agent event + isolated tools |
| 12 | 12 | +`mcp.ts` (stdio JSON-RPC, version-negotiated) | event log shows `initialize` / `tools/list` / `tools/call` |
| 13 | — | doc-only | three-tier comparison |
| 14 | — | doc-only | walks through steps/test.mjs (same harness that tests the book) |
| 15 | 13 | +`autonomy.ts`; `sideQuery`; `/goal` `/loop` `--auto` | goal: evaluator verdict + 2nd-turn reinjection in event log |

Decisions locked by Gate 0:
- **ch1-4 are non-streaming** (`messages.create`). ch5 is the "swap the call shape"
  chapter. (The pilot currently streams from ch1 — Phase A fixes this.) Dual
  backend is *not* in the teaching trunk; it stays a production-only feature.
- **ch8 recall is deterministic** (keyword/index top-k, no model call). `sideQuery`
  is introduced later, at ch15, and reused by the auto classifier.
- **ch12 MCP** teaches stdio only; the mock MCP server negotiates protocol
  version; docs do not hardcode a dated version as "current".

## 5. Markers + linter

- **Slice** `#step`: `//#step >=N | ==N | <=N | <N | >N` (TS), `#step …` (Py),
  closed by `//#endstep` / `#endstep`. Consecutive `#step` before an end = if/elif
  (first matching branch wins). Implemented in `build.mjs`.
- **Doc region** `#region NAME` … `#endregion`: names a span for the docs. The
  region is extracted from the **sliced** file for a given step, so a doc snippet
  always equals code that really exists in that chapter's snapshot.
- **`lint-markers.mjs`** fails the build on: unbalanced markers, unknown region
  referenced by a `@snippet`, empty region, duplicate region name in one file,
  a `@snippet`/`@diff`/`@transcript` whose target step/region doesn't exist.

## 6. Scenarios + mock + event log

- **`steps/scenarios/*.json`** is the single source of scripted model behavior.
  A turn is `{tools:[{name,input}], text?}` (tool_use) or `{text}` (final).
  `steps/scenarios/_map.json` maps each step to its scenario **and** its
  expectations (what the chapter must prove: `toolCalls`, `toolResultsContain`,
  `systemContains`, `files`, `finalStopReason`). `test.mjs`, `run --demo`, and
  `@transcript` read the same scenario — no third copy to drift. (Gate 0 P2.)
  - *Single-loop vs multi-track (Gate 1 P0):* ch1-6 have one model-call loop, so
    a flat `turns` list keyed by assistant-message count is enough. From **ch7**
    the agent makes *aux* one-shot calls (compact summary; ch11 sub-agents; ch15
    goal evaluator / auto classifier) that are NOT the main loop — a sub-agent's
    first request also has assistantCount 0. So at ch7 the scenario gains
    `tracks: { main: [...], "compact": [...], "subagent:explore": [...], "auto:stage1": [...], "goal": [...] }`
    and the mock **routes each request to a track by its shape** (system prompt /
    tools / first user message), logging the `track`; tests assert every track is
    consumed. `turns` stays as sugar for `{ main: turns }`. This is implemented
    when ch7 lands (not stubbed early); Gate 3 re-checks it. MCP (ch12) is a
    stdio subprocess with its own mock server + JSONL log, separate from the
    model mock.
- **Mock is in-process, per language.** `mock-anthropic.mjs` (Node) and
  `mock_anthropic.py` (Python) both implement the real Anthropic `POST
  /v1/messages` — `create` and SSE `stream`, `tool_use` blocks, `usage`, errors —
  and both read the SAME `scenarios/*.json`. A test/demo starts the mock **in the
  same process/runtime as the step it drives** (Node mock ↔ TS steps; Python mock
  ↔ Python steps) and drives the step by importing its `Agent` class with
  `ANTHROPIC_BASE_URL` pointed at the in-process mock. There is still no `if
  (test)` branch in the teaching code — only an env var and an imported class.
  - *Why in-process, per language:* on the dev host, mihomo intercepts
    cross-process loopback, so a subprocess step cannot reach a mock server in
    another process (verified). Same-process loopback works everywhere (dev host,
    CI, reader machines), so the in-process design is strictly more robust. It
    also gives cleaner assertions (drive `Agent.chat()` directly). The two small
    mocks mirror each other and share the scenario JSON, so they cannot drift
    behaviorally.
- On queue exhaustion the mock returns an error and the run **fails** (never a
  false green). It emits an **event log** (JSONL): every request (system, tools,
  messages), every tool_use it issued, and usage — the machine-observable
  substrate for assertions and transcripts.
- **Conformance selftests** prove protocol fidelity before any step depends on
  it: `mock-anthropic.selftest.mjs` drives the **Node** mock with the real TS SDK
  (create, stream, tool_use); `mock_anthropic.selftest.py` drives the **Python**
  mock with the real Python SDK (create, stream text chunks, stream tool input,
  usage, exhaustion→error). Each is same-process (the only loopback shape that
  works on the dev host). `test.mjs` then exercises both mocks end-to-end.

## 7. test.mjs

For each step × {ts, py}, run the scenario against the in-process mock and assert
**behaviorally** (Gate 1 — the earlier "did the mock emit a tool name" check was
false-green and is gone):
1. compile (tsc) / import (py) — must pass, **no skips** (a missing Python env
   fails, it does not pass vacuously).
2. **every scripted turn consumed** (one model call per turn) and the **final
   turn reached** (`stop_reason == end_turn`) — catches an agent that stops
   feeding tool results back.
3. **each tool really ran**: its real output appears in the `tool_result` the
   agent sent back (`toolResultsContain`) — catches a broken/stubbed tool.
4. **the system prompt carries what the chapter added** (`systemContains`) —
   catches a broken prompt.
5. **file side effects** happened; natural language only via `contains`.
6. **parity**: TS and Python produce the same normalized event log (requests,
   tool_result contents, responses).

`test.selfcheck.mjs` is the meta-test: it applies three mutations (garbage
`read_file`, agent never feeds results back, broken system prompt) to canonical,
regenerates, and asserts `test.mjs` goes **red** for each — so the harness is
proven to catch broken code, not just pass. Deterministic, no API key → CI.

## 8. docs-sync.mjs

Markdown carries HTML-comment placeholders; the script fills between them,
idempotently, and CI runs `git diff --exit-code` to catch drift.

- `@snippet lang=ts file=agent.ts region=loop step=2` → the region, sliced at that
  step.
- `@diff step=N file=agent.ts` → the unified diff of file between step N-1 and N
  (the chapter's change, in the main narrative — Gate 0 P0).
- `@transcript scenario=read-a-file step=1 lang=ts` → the **real** stdout of
  running that step against the mock, captured in a **fixed temp workspace**
  (normalized paths, no real dates, ANSI stripped — Gate 0 P1) so it is stable.
- Hardening: empty snippet fails, duplicate/unknown region fails, unsynced doc
  fails, path/time/ANSI normalization.

## 9. run.mjs

- `node steps/run.mjs <N>` → **default `--demo`**: starts the mock, sets a dummy
  key, isolates a temp cwd/HOME, runs the step's demo scenario. No key needed.
- `--live` → real API via `.env` (proxy stripped); optional smoke.
- `--diff` → what this chapter added vs the previous (also available as `@diff` in
  docs).
- `--list` → steps + one-line capabilities. `--py` → Python. `-- "<prompt>"` →
  one-shot (live) or drive the demo.

## 10. Execution: per-step closed loop (Gate 0 P1)

After the ch1-3 template is set, **each chapter is a full vertical loop** before
moving on (codecrafters "one stage at a time"): canonical slice (both langs) →
mock test green → doc `@snippet`+`@diff`+`@transcript` (zh+en) → `--diff` self-
check → read the chapter through. Not "all code, then all docs".

## 11. Phases & Codex gates

- **Gate 0 (plan)** — done; this doc incorporates it.
- **Phase A — foundations**: seam matrix; `lint-markers.mjs`; `mock-anthropic.mjs`
  + selftest (real TS+Py SDK); `scenarios/`; `test.mjs`; `run.mjs` `--demo`
  default + `--diff`/`--list`; revise pilot ch1-3 to **non-streaming** + add
  `#region` + demo scenarios; ch1-3 mock-test green + representative `--live`
  smoke. → **Gate 1** (foundations architecture, mock fidelity, no test-hooks in
  teaching code, seam matrix).
- **Phase B — doc/code loop on ch1-3**: `docs-sync.mjs`; wire ch1-3 zh+en docs
  (@snippet/@diff/@transcript + ▶run); drift check green; read all four. →
  **Gate 2** (doc-code sync + ch1-3 as the whole-book template: readability &
  usefulness).
- **Phase C/D merged — per-chapter closed loop** for ch4→ch12→ch15, each: code +
  mock test + docs + transcript + diff + read-through, batched commits. →
  **Gate 3** (mid: code-step quality, parity, demos observable) and **Gate 4**
  (full-book doc consistency, from-scratch feel, facts).
- **Phase E — final**: full mock test suite green (both langs); representative
  `--live` smoke; docs-sync drift check; readable-writing blockers=0 all zh;
  read every zh+en chapter end-to-end; → **Gate 5 (final)** → push.

Each gate: `/cross-review` or `ask-codex.sh` (gpt-5.5 xhigh, web), triage P0/P1,
record in progress notes.

## 12. Goal DoD (revised per Gate 0)

1. canonical covers ch1-12 + ch15 in TS+Python; build/run (`--demo` default,
   `--live`, `--diff`, `--list`, `--py`, one-shot) work.
2. `mock-anthropic` + `test.mjs`: every step × both languages green with **no API
   key** (assert event log + parity, no skips). `--live` smoke on a
   representative 3-4 steps recorded (date/model), **non-blocking**.
3. every code chapter's docs/ + en/docs/ code blocks generated from canonical
   (no hand-copied), with `@diff` in the narrative, a ▶run entry, and a captured
   `@transcript`; `git diff --exit-code` drift check green.
4. all zh chapters readable-writing blockers=0; every chapter zh+en read end-to-
   end for readability/usefulness, issues fixed.
5. 5 Codex gates passed, P0/P1 resolved.
6. committed in phases; pushed to GitHub.

## 13. Risks

- **Canonical marker churn** → seam matrix + `lint-markers` + mock-test each step
  immediately; favor new files.
- **Mock false-green / SDK mismatch** → selftest with real SDKs first; queue
  exhaustion fails; no skips.
- **Doc migration volume** → per-chapter closed loop, templated on ch1-3; prose
  (already reframed) untouched, only code blocks swapped for placeholders.
- **Runway** → durable commit per chapter; ch1-3 vertical slice done first is a
  complete, usable deliverable; if incomplete, report done-vs-remaining and push
  what's verified.
- **Live key** → inferera key works now; CI never depends on it.