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
committed by
GitHub
GitHub
parent
b1ec34162e
commit
34d0ff7383
@@ -36,14 +36,46 @@ const readSmallModelSettingsOverride = () => {
|
||||
const DEFAULT_CONTEXT_TOKENS = 64_000;
|
||||
const OUTPUT_RESERVE_TOKENS = 4_000;
|
||||
|
||||
const clampPromptToModelLimit = ({ prompt, catalog, providerID, modelID }) => {
|
||||
/**
|
||||
* Input budget in characters, given how much of the context the caller intends
|
||||
* to leave for the answer. The reserve must match the output budget the caller
|
||||
* will actually request, or the two disagree and the model overruns its context.
|
||||
*/
|
||||
export const getModelInputCharBudget = ({ catalog, providerID, modelID, outputReserveTokens }) => {
|
||||
const limit = catalog?.[providerID]?.models?.[modelID]?.limit;
|
||||
const contextTokens = Number(limit?.context) > 0 ? Number(limit.context) : DEFAULT_CONTEXT_TOKENS;
|
||||
const inputBudgetTokens = Math.max(1_000, contextTokens - OUTPUT_RESERVE_TOKENS);
|
||||
const maxChars = inputBudgetTokens * 4;
|
||||
const known = Number(limit?.context) > 0;
|
||||
const contextTokens = known ? Number(limit.context) : DEFAULT_CONTEXT_TOKENS;
|
||||
const reserve = Number(outputReserveTokens) > 0 ? Number(outputReserveTokens) : OUTPUT_RESERVE_TOKENS;
|
||||
const inputBudgetTokens = Math.max(1_000, contextTokens - reserve);
|
||||
return { maxChars: inputBudgetTokens * 4, contextTokens, contextKnown: known };
|
||||
};
|
||||
|
||||
/**
|
||||
* The output budget to actually request: what the caller asked for, capped by
|
||||
* what the model admits it can emit. Asking for more than `limit.output` is
|
||||
* rejected outright by some providers and silently ignored by others.
|
||||
*/
|
||||
const resolveOutputTokens = ({ catalog, providerID, modelID, maxOutputTokens }) => {
|
||||
const requested = Number(maxOutputTokens) > 0 ? Number(maxOutputTokens) : 0;
|
||||
if (!requested) return undefined;
|
||||
const limit = Number(catalog?.[providerID]?.models?.[modelID]?.limit?.output);
|
||||
return limit > 0 ? Math.min(requested, limit) : requested;
|
||||
};
|
||||
|
||||
// `truncate` keeps the historical behavior for callers whose prompt losing its
|
||||
// tail is survivable (summaries, commit messages). `error` is for callers whose
|
||||
// output would be quietly wrong on a clipped input — they need the failure.
|
||||
const clampPromptToModelLimit = ({ prompt, catalog, providerID, modelID, onOverflow, outputReserveTokens }) => {
|
||||
const { maxChars } = getModelInputCharBudget({ catalog, providerID, modelID, outputReserveTokens });
|
||||
if (prompt.length <= maxChars) {
|
||||
return { prompt, truncated: false };
|
||||
}
|
||||
if (onOverflow === 'error') {
|
||||
throw Object.assign(
|
||||
new Error(`Input is too large for ${providerID}/${modelID}: ${prompt.length} characters exceeds the ${maxChars} the model's context allows`),
|
||||
{ statusCode: 413, code: 'context-too-small', providerID, modelID, requiredChars: prompt.length, availableChars: maxChars },
|
||||
);
|
||||
}
|
||||
return { prompt: `${prompt.slice(0, maxChars)}…`, truncated: true };
|
||||
};
|
||||
|
||||
@@ -61,7 +93,7 @@ const readConfiguredSmallModel = (workingDirectory) => {
|
||||
* Generates text with the user's small model, resolved and authenticated
|
||||
* entirely server-side from the OpenCode config and auth store.
|
||||
*/
|
||||
export async function generateSmallModelText({ prompt, system, maxOutputTokens, model, directory, preferredProviderID, preferredModelID, restrictToPreferredProvider = false }) {
|
||||
export async function generateSmallModelText({ prompt, system, maxOutputTokens, model, directory, preferredProviderID, preferredModelID, restrictToPreferredProvider = false, responseSchema, timeoutMs, signal, onOverflow = 'truncate' }) {
|
||||
if (typeof prompt !== 'string' || !prompt.trim()) {
|
||||
throw Object.assign(new Error('prompt is required'), { statusCode: 400 });
|
||||
}
|
||||
@@ -101,11 +133,20 @@ export async function generateSmallModelText({ prompt, system, maxOutputTokens,
|
||||
);
|
||||
}
|
||||
|
||||
const outputTokens = resolveOutputTokens({
|
||||
catalog,
|
||||
providerID: resolved.providerID,
|
||||
modelID: resolved.modelID,
|
||||
maxOutputTokens,
|
||||
});
|
||||
|
||||
const clamped = clampPromptToModelLimit({
|
||||
prompt: prompt.trim(),
|
||||
catalog,
|
||||
providerID: resolved.providerID,
|
||||
modelID: resolved.modelID,
|
||||
onOverflow,
|
||||
outputReserveTokens: outputTokens,
|
||||
});
|
||||
|
||||
const text = await callSmallModel({
|
||||
@@ -116,7 +157,10 @@ export async function generateSmallModelText({ prompt, system, maxOutputTokens,
|
||||
modelID: resolved.modelID,
|
||||
prompt: clamped.prompt,
|
||||
system: typeof system === 'string' && system.trim() ? system.trim() : undefined,
|
||||
maxOutputTokens,
|
||||
maxOutputTokens: outputTokens,
|
||||
responseSchema,
|
||||
timeoutMs,
|
||||
signal,
|
||||
});
|
||||
|
||||
return {
|
||||
@@ -152,17 +196,47 @@ export function listAuthenticatedProviders() {
|
||||
|
||||
/**
|
||||
* Reports which model would be used, without calling it.
|
||||
*
|
||||
* `inputCharBudget` and `structuredOutput` let callers refuse work before
|
||||
* spending a request: the walkthrough needs both a big enough context and
|
||||
* schema-shaped output, and would rather tell the user to pick another model
|
||||
* than send a doomed prompt. `structuredOutput` is deliberately tri-state —
|
||||
* the catalog omits the field for roughly half of all models (aggregators and
|
||||
* proxies especially), and treating "unknown" as "unsupported" would hide
|
||||
* models that work fine.
|
||||
*/
|
||||
export async function describeSmallModel({ directory, preferredProviderID, preferredModelID } = {}) {
|
||||
export async function describeSmallModel({ directory, preferredProviderID, preferredModelID, outputReserveTokens, overrideModel } = {}) {
|
||||
const auth = readAuthFile();
|
||||
const catalog = await getModelCatalog().catch(() => ({}));
|
||||
const resolved = resolveSmallModel({
|
||||
auth,
|
||||
// A caller with its own model setting (the diff walkthrough) outranks the
|
||||
// small-model chain entirely — it asked for this model on purpose.
|
||||
const explicit = parseModelRef(overrideModel);
|
||||
const resolved = explicit
|
||||
? { ...explicit, source: 'request' }
|
||||
: resolveSmallModel({
|
||||
auth,
|
||||
catalog,
|
||||
settingsSmallModel: readSmallModelSettingsOverride(),
|
||||
configSmallModel: readConfiguredSmallModel(directory),
|
||||
preferredProviderID,
|
||||
preferredModelID,
|
||||
});
|
||||
if (!resolved) return resolved;
|
||||
|
||||
const entry = catalog?.[resolved.providerID]?.models?.[resolved.modelID];
|
||||
const { maxChars, contextTokens, contextKnown } = getModelInputCharBudget({
|
||||
catalog,
|
||||
settingsSmallModel: readSmallModelSettingsOverride(),
|
||||
configSmallModel: readConfiguredSmallModel(directory),
|
||||
preferredProviderID,
|
||||
preferredModelID,
|
||||
providerID: resolved.providerID,
|
||||
modelID: resolved.modelID,
|
||||
outputReserveTokens,
|
||||
});
|
||||
return resolved;
|
||||
|
||||
return {
|
||||
...resolved,
|
||||
inputCharBudget: maxChars,
|
||||
contextTokens,
|
||||
contextKnown,
|
||||
structuredOutput: typeof entry?.structured_output === 'boolean' ? entry.structured_output : null,
|
||||
outputTokenLimit: Number(entry?.limit?.output) > 0 ? Number(entry.limit.output) : null,
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user