feat(walkthrough): guided AI walkthrough for diffs, branches, and PRs (#2572)

A diff is ordered by file path, which is almost never the order in which a
change makes sense. This adds a Walkthrough surface that reorders it: the model
groups related hunks into stops, explains what each group changes about
behavior, and orders the stops so each builds on the last. It explains and
orders; judging code stays with the existing Review action.

Reviews uncommitted work (all, staged, unstaged), a branch against its base, or
a pull request. Generation is always user-initiated — nothing runs on a timer,
on a file change, or as a side effect of opening a panel.

Invariants worth preserving:

- Hunk identity is derived on the server and only there. Ids are content
  hashes, so an anchor that no longer resolves is proof the code it described
  changed, and staleness needs no heuristics. The client matches ids to ids and
  never recomputes them; two implementations would have to agree forever.
- The digest is never truncated. A diff that does not fit the model's context
  is refused with an actionable reason, because a walkthrough written against
  half a diff reads as confident and is wrong.
- Nothing disappears. Lockfiles and other generated output are excluded from
  the model's input by name — never by size — and everything no stop covers is
  listed at the end, so "have I seen all of it" stays answerable.
- Cost is explicit. Results are content-addressed, so returning the working
  tree to an earlier state costs nothing; generation outlives its request, so a
  refresh detaches the client rather than discarding paid-for work, and only an
  explicit cancel stops it.

Supporting changes to shared modules:

- git: expose the existing getRangeDiff as GET /api/git
  listUntrackedPaths and getUntrackedDiffs. The latter resolve the repository
  once for a batch instead of per file, taking a panel
  ~340ms on an 80-file working tree.
- small-model: structured output across four wire forma
  and abort signal, and an onOverflow policy so an oversized prompt fails
  loudly instead of being silently clipped. A provider
  remembered so the prompt-side fallback goes first next time.
- models.dev metadata: surface structured_output as tri
  false blocks a model, a missing field does not, because the catalog omits it
  for roughly half of all models.

Desktop and tablet only: VS Code serves Git through its
these routes, and the mobile shell does not consume the surface registry.

Docs: packages/docs walkthrough page in English and all eight locales.
This commit is contained in:
Bohdan Triapitsyn
2026-08-02 16:22:55 +03:00
committed by GitHub
parent b1ec34162e
commit 34d0ff7383
99 changed files with 7316 additions and 53 deletions
@@ -31,10 +31,43 @@ other runtime API.
and as a final utility fallback.
4. Last resort: the session's own model (`preferredModelID`) when no small
model resolves anywhere — costlier, but always valid.
- Input clamp: the prompt is truncated to the resolved model's catalog
- Input clamp: the prompt is measured against the resolved model's catalog
`limit.context` (minus an output reserve, ~4 chars/token estimate;
conservative default when the model is not in the catalog). Truncation is
reported as `inputTruncated: true` in the response.
conservative default when the model is not in the catalog). `onOverflow`
decides what an oversized prompt means:
- `truncate` (default) clips the tail and reports `inputTruncated: true`.
Correct for callers that degrade gracefully (summaries, commit messages).
- `error` throws a `413` with `code: 'context-too-small'` plus
`requiredChars`/`availableChars`. Correct for callers whose output would be
quietly wrong on a clipped input, so they can ask the user for a roomier
model instead of returning confident nonsense.
- Structured output: pass `responseSchema` (a JSON Schema) to get
schema-shaped JSON back as `text`. Wire support differs per format —
`response_format: {type: 'json_schema'}` for OpenAI-compatible chat,
`text.format` for the Responses API, a forced single tool call for the
Anthropic messages API, and `generationConfig.responseSchema` for Google
(whose OpenAPI-flavored dialect drops unknown JSON Schema keywords). The
ChatGPT-plan codex backend has no equivalent and rejects a schema request
with `code: 'structured-output-unsupported'` rather than silently returning
prose.
- Output budget: `maxOutputTokens` is capped at the catalog's `limit.output` for
the model, and the **same number** is reserved from the input allowance. The
two must not drift — a caller that asks for a large answer while the reserve
stays at the default overruns the context, and the failure looks like a
truncation bug rather than a budgeting one. `describeSmallModel` takes
`outputReserveTokens` so readiness checks agree with what generation will do.
- Reasoning models can spend the entire output budget thinking and return
nothing. That case (empty content with `finish_reason: 'length'`, or content
empty while `reasoning_content` is populated) throws with
`code: 'output-exhausted'` so callers can offer a different model instead of
showing a transport error.
- `timeoutMs` overrides the 60s default per call; `signal` lets a caller abort
a request that is no longer wanted. Both apply to every wire format.
- `describeSmallModel()` additionally reports `inputCharBudget`,
`contextTokens`, `contextKnown`, and `structuredOutput`. The last is
tri-state: `true`/`false` from the catalog, `null` when the catalog omits the
field — which it does for roughly half of all models, aggregators and proxies
especially. Callers must treat `null` as "try it", not "unsupported".
- `call.js` — wire formats and per-provider auth, replicating OpenCode's
plugin auth loaders:
- **GitHub Copilot**: fetches the requested model's authenticated `/models`