openchamber/packages/web/server/lib/walkthrough/DOCUMENTATION.md

Walkthrough

Generates a guided, ordered reading path through a diff: the small model groups related hunks into stops and chapters and explains each group, and the UI renders those stops interleaved with the code they describe.

Generation is always user-initiated. Nothing here runs on a timer, on a file change, or as a side effect of opening a panel — it spends tokens, so a person has to ask for it.

Files

• hunks.js — parses a unified diff into files and hunks and assigns each hunk a stable id.
• generated.js — recognises tool-produced files that are kept out of the model's input.
• sources.js — turns a source descriptor into diff sections.
• digest.js — builds the model-facing digest and the alias↔id mapping.
• prompt.js — system prompt, size guidance, previous-walkthrough section, and PROMPT_VERSION.
• schema.js — response schema, response normalization, tolerant JSON parsing.
• store.js — content-addressed cache entries plus mutable pointers.
• pull-request.js — PR diffs via the shared GitHub octokit helper.
• model-settings.js — the feature's own model override.
• index.js — orchestration.
• routes.js — /api/walkthrough*.

Hunk identity

hunks.js is the only place that decides what a hunk is or what its id is. The client never recomputes ids; it receives the current hunk index (id → patch) alongside the walkthrough and matches ids to ids. Two implementations of the same hash would have to agree byte-for-byte forever, and the first one to drift would silently mis-anchor every stop.

An id is <scope>:<path>:<sha1(header + body)[:8]>, with a -2, -3, … suffix for byte-identical hunks repeated inside one file.

Two consequences fall out of hashing the content:

• Editing a hunk changes its id, so an anchor that no longer resolves is proof the code it described changed. Staleness needs no heuristics.
• Editing one hunk does not disturb its neighbours, so a small edit invalidates only the stops that actually covered it.

scope keeps staged and unstaged versions of the same lines apart, so a stop written against staged code never silently re-anchors onto an unstaged edit.

Sources

Kind	Sections	Notes
working-tree (all | staged | working)	staged, working	Untracked files are fetched individually because git diff omits them
branch	branch	getRangeDiff uses three-dot base...head, so work merged in from the base branch is excluded
pr	pr:<number>	GitHub returns the merge-base diff, matching the branch semantics

The panel offers the current branch's pull request on its own: it registers with the shared GitHub PR status store (useGitHubPrStatusStore) rather than waiting for the pull request panel to have been visited. That store already dedupes concurrent requests by signature and throttles by TTL, so several panels asking the same question produce one call to GitHub.

No truncation

Within what it covers, the digest is complete. When it does not fit the resolved model's context, generation is refused (409, code: 'context-too-small') so the user can pick a roomier model. A walkthrough written against a silently clipped diff is confidently wrong in a way no reader can detect, which is worse than no walkthrough.

Generated files

generated.js excludes tool-produced files — lockfiles, minified bundles, codegen, snapshots — from the digest by name, never by size. A lockfile can be larger than the entire change around it and carries no intent, so sending it wastes context that real code needs.

They are excluded, not hidden: they carry no hunk aliases (so nothing can anchor to them), but they are still parsed, still returned to the client, and still appear in the uncovered tail. The matcher is deliberately conservative — src/lock.ts and src/generator.ts are authored code — because a false positive silently drops real code from a review, which is the exact failure this feature exists to prevent.

When a change consists only of generated files, generation is refused with code: 'only-generated' rather than the misleading "nothing changed".

Model selection

The walkthrough has its own model setting (Settings → Sessions → Changes Walkthrough Model), read by model-settings.js:

walkthroughModelOverride (provider/model) is the whole contract: set, that model is used for this feature and nothing else; unset or empty, generation falls back to whatever the small-model chain resolves to. Choosing a model is the opt-out, so there is no separate toggle to disagree with the picker — the settings picker simply shows "Small model will be used" until a choice is made, and clearing it restores the fallback.

The separation exists because the two roles pull in opposite directions: the small model is chosen to be cheap and fast for recaps and commit messages, while this one needs schema-shaped output and enough context for a whole diff. Forcing one setting to serve both means degrading one feature to fix the other.

A review can also override the model for itself: GET/POST accept a model (provider/model) that outranks both the setting and the small-model chain. That choice is panel state, not a settings edit — picking a roomier model for one risky change should not silently redefine the default for every future one. It needs no storage: the model that produced a walkthrough is already recorded in its cache entry, so reopening a panel resolves the picker as explicit choice → model that generated what is on screen → settings. Because the model is part of the cache key, switching models and back returns the earlier review for free.

The picker hides models the catalog reports as structured_output: false — offering them would move the same refusal one click later — and, like the small model picker, only shows providers with a usable login. The in-panel picker on a blocked walkthrough writes this setting too, so recovering from a refusal never silently changes the model behind commit messages.

Structured output, and what happens when it is refused

structured_output: false in the catalog blocks generation up front. A missing capability field does not block — the catalog omits it for roughly half of all models, and treating unknown as unsupported would hide models that work.

Providers that do not declare the capability sometimes reject the schema at request time (a plain 400, or Alibaba/Qwen's "'messages' must contain the word 'json'"). A rejected request shape is not a dead end, so a 4xx on a schema request triggers exactly one retry with the schema moved into the prompt and the tolerant parser handling the result. Only if that fails to yield usable JSON is structured-output-unsupported reported — at which point it is a real capability problem the user can fix by switching model.

The refusal is then remembered per provider/model and the fallback goes first from then on. Without that, every generation on such a provider pays for a call whose failure is already known. The memory is process-lifetime only on purpose: a provider that gains structured-output support should not need a settings change to be tried again, and one wasted first attempt after a restart is cheap.

The system prompt states "respond with a single JSON object" explicitly, which also satisfies the providers that scan the request for the word json before honouring response_format. That keeps them on the fast path instead of paying for a wasted first call.

Output budget

Generation asks for 24k output tokens (capped per model by the catalog), and the input budget reserves exactly that much. A walkthrough itself is only a few thousand tokens of JSON — the headroom exists because reasoning models spend the same budget thinking first and return nothing when it runs out. When that still happens, code: 'output-exhausted' reports it as what it is: this model cannot finish this job, so pick another or review a narrower scope.

Caching and staleness

Cache entries (entries/<sha256>.json) are immutable and content-addressed. The key covers walkthrough version, prompt version, repo root, source, provider, model, and every file's path/status/hunk-ids. The key is computed from the current diff, so a hit means the walkthrough was written about exactly this code; there is no freshness question to ask of an entry, because staleness is a miss. Returning the working tree to an earlier state therefore costs nothing.

Pointers (pointers/<sha256(repoRoot + source)>.json) are mutable and hold { cacheKey, generatedAt, repoRoot, sourceKey }. They answer what the cache cannot: which walkthrough was last shown here, and has the code moved since. A pointer whose entry has been evicted reads as "no walkthrough" — truthful, and the next generation overwrites it.

Regeneration is manual and re-authors rather than merges: the previous walkthrough goes into the prompt as prose so the model can keep what is still true, with its anchors deliberately stripped so everything is re-anchored against the current digest. Splicing partially-regenerated chapters into an old narrative was considered and rejected — the seams produce stops that contradict each other, and the failure is invisible.

Hygiene

• Entries are bounded by count and total size (200 / 50 MB) and evicted least-recently-used after a write that crosses a limit. Nothing is dropped for being merely old: an entry costs kilobytes and stays reachable if the working tree ever returns to that state.
• Writes are tmp+rename; reads enforce a size limit and validate the version, so a corrupt file is a miss rather than a crash.
• Pointers are never evicted by size. They are pruned only when their repository is provably gone, deferred off the request path, fully asynchronous, and capped.

That last point is deliberate rather than incidental. The desktop app hosts this server inside the Electron main process, so a synchronous loop here would stall IPC and the window rather than a single request — and the paths being checked are user repositories, where a worktree on an unplugged drive or an unreachable share can make one existence check hang for seconds. Only ENOENT deletes a pointer: unreachable is not the same as gone, and a dead share must not cost the user their walkthroughs.

Coverage

The model is told it may leave mechanical changes out. Whatever it does not anchor is computed as uncoveredHunkIds and rendered as a collapsed tail, so the reader can always answer "have I seen everything that changed". No hunk disappears from the view.

Cost of reading

Opening the panel is a GET that runs the whole git pipeline, so it is kept as cheap as the data allows:

• Untracked files come from listUntrackedPaths (a plain ls-files) rather than getStatus, which also computes ahead/behind, diff stats, and merge state — roughly 180ms of work for an answer this module discards.
• Their diffs go through getUntrackedDiffs, which resolves the repository once for the whole batch and bounds concurrency, instead of one getDiff per file each re-resolving the repository.
• Readiness is computed from the same diff as the walkthrough itself. It used to be its own endpoint that the client called in parallel, which meant every panel open ran the entire pipeline twice.

On a working tree of 80 files and 138 hunks this took a panel open from ~800ms to ~340ms. Parsing and digest building are ~3ms of that; everything else is git.

Generation outlives its request

A dropped connection and a deliberate cancel are indistinguishable at the socket, so tying generation to the request lifetime meant an accidental refresh threw away a minute of paid-for work. Instead:

• Jobs live in a module-level map keyed by repository + source. A second generate for the same source attaches to the running job rather than starting a rival one — pressing the button again after a refresh costs nothing extra.
• Leaving the page detaches the client; the job finishes and writes its cache entry, so coming back finds the result waiting.
• GET /api/walkthrough reports generating, letting a returning client show progress instead of an empty panel, and the client re-attaches so the result lands somewhere.
• Stopping is an explicit POST /api/walkthrough/cancel. That is the only thing that aborts the model call.

The cost of this is that a job everyone abandoned keeps spending until it finishes; the generation timeout bounds it.

That timeout is a hang guard, not a pace-setter, and it scales with the diff: 120s plus 1s per hunk, capped at 15 minutes. A fixed number made a three-hunk edit and a 500-hunk pull request wait the same, which guarded nothing in the small case and risked killing the big one just short of the finish line. It errs long on purpose — losing a nearly-complete generation costs real money, while an over-long deadline only holds a job slot. Note that the schema fallback can use the deadline twice, once per attempt.

Progress

A running job records a coarse stage: collecting (reading the diff, which for a pull request is seconds of network), asking, retrying when a provider rejects the schema and the prompt-side fallback runs, and assembling.

Only phases a person can wait on are named. Building the digest and reading the cache take single-digit milliseconds; giving them rows would imply progress that is not happening.

retrying exists for diagnostics but is not shown: from outside it is the same wait on the same model, and naming our fallback only raises the question of what it is. The client folds it into asking.

The client also paces the display, holding each step for a floor before revealing the next and keeping the list on screen briefly after the work ends. Assembling takes milliseconds, so without that the result replaces the list before the final step is ever seen finishing — naming a step the user never observes is worse than not naming it. The cost is well under a second at the end of a wait measured in minutes.

GET /api/walkthrough/progress reads the job registry and nothing else — no git, no network — so the client can poll it once a second. The full read must never be used for this: it re-runs the whole git pipeline.

Routes

• GET /api/walkthrough?directory&source — last walkthrough, the current hunk index, staleness, and readiness. Never generates.
• POST /api/walkthrough/generate — { directory, source, force }. Survives client disconnects; a concurrent call for the same source joins the running job.
• GET /api/walkthrough/progress?directory&source — the current stage, or null. Memory-only and safe to poll.
• POST /api/walkthrough/cancel — { directory, source }; aborts a running generation.

There is deliberately no delete route: regeneration covers the need, and an endpoint nothing calls is a maintenance surface that rots untested.

Registered lazily from feature-routes-runtime.js. /api/walkthrough is in the JSON body-parser allowlist in core-routes.js.

Runtime availability

Web, desktop, and hosted mobile reach these routes normally. VS Code serves Git through its own bridge rather than the OpenChamber Git routes, so the feature is not offered there; the surface is also gated to tablet width and above.