@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/diff-view.js

@@ -0,0 +1,240 @@
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { highlightLine, roleOf } from "../plain/highlight.js";
+import { RESOURCE_MARKER } from "../plain/markdown.js";
+/** Painted with nothing: the text as it is, for where there are no colours. */
+export const PLAIN_PAINT = {
+    syntax: (_colour, text) => text,
+    added: (text) => text,
+    removed: (text) => text,
+    addedBand: (text) => text,
+    removedBand: (text) => text,
+    muted: (text) => text,
+};
+/** A section's header: `***functional specs***`. */
+const SECTION = /^\*\*\*[^*].*\*\*\*$/;
+/** A line of a .plain file as the spec reads it: its links as the parser renders them (markdown.ts). */
+function asRead(line) {
+    return line.replace(/\[([^\]]*)\]\([^)]*\)/g, (_, text) => `\`${RESOURCE_MARKER}${text}\``);
+}
+/**
+ * Place a spec diff's lines in the .plain files they come from - `files`, the module's and every one it
+ * reads, named as they are to be shown. A spec diff is of the spec as read, the files it imports laid into
+ * it, so its own line numbers are not the file's: each line is found where it is written, the file a line
+ * before it was found in first, from there on, and each place once.
+ */
+export function locateDiffLines(diff, files) {
+    const where = {};
+    // Each line as the parser renders it: a link `[text](path)` is the span `` `[resource]text` `` in the spec as read.
+    const texts = files.map((file) => ({ name: file.name, lines: file.text.split("\n").map((line) => asRead(line.trimEnd())) }));
+    // The section each line of a file is in: the nearest `***...***` header above it, or on it.
+    const sections = texts.map((file) => {
+        let current;
+        return file.lines.map((line) => (SECTION.test(line.trim()) ? (current = line.trim()) : current));
+    });
+    const used = new Set();
+    let last;
+    const take = (file, line, index) => {
+        used.add(`${file}:${line}`);
+        const section = sections[file][line];
+        where[index] = { file: texts[file].name, line: line + 1, ...(section !== undefined ? { section } : {}) };
+        last = { file, line };
+    };
+    diff
+        .replace(/\n+$/, "")
+        .split("\n")
+        .forEach((line, index) => {
+        if (HEADER.test(line) || line.startsWith("+++ ") || line.startsWith("@@") || line.startsWith("\\"))
+            return;
+        if (line.startsWith("-")) {
+            // A removed line still written in a file - taken out of what is compared, not out of the spec - is that file's.
+            const removed = asRead(line.slice(1).trimEnd());
+            if (removed.trim() === "" || SECTION.test(removed.trim()))
+                return;
+            const file = texts.findIndex((candidate) => candidate.lines.includes(removed));
+            if (file !== -1) {
+                const at = texts[file].lines.indexOf(removed);
+                const section = sections[file][at];
+                where[index] = { file: texts[file].name, line: at + 1, ...(section !== undefined ? { section } : {}) };
+            }
+            return;
+        }
+        const text = (line.startsWith("+") || line.startsWith(" ") ? line.slice(1) : line).trimEnd();
+        if (text === "") {
+            // A blank line: the one right after the line before it, when that is blank.
+            if (last !== undefined && texts[last.file].lines[last.line + 1] === "" && !used.has(`${last.file}:${last.line + 1}`))
+                take(last.file, last.line + 1, index);
+            return;
+        }
+        const order = last === undefined ? texts.map((_, file) => file) : [last.file, ...texts.map((_, file) => file).filter((file) => file !== last.file)];
+        for (const file of order) {
+            const lines = texts[file].lines;
+            const from = last !== undefined && file === last.file ? last.line + 1 : 0;
+            const found = [...lines.keys()].slice(from).concat([...lines.keys()].slice(0, from)).find((at) => lines[at] === text && !used.has(`${file}:${at}`));
+            if (found !== undefined)
+                return take(file, found, index);
+        }
+    });
+    return where;
+}
+const HEADER = /^(diff --git |index |--- |new file mode |deleted file mode )/;
+/**
+ * A spec diff, file by file: each file's lines together, however the diff has them - a spec diff is of the
+ * spec as read, so what one file holds can come in more than one place - the file being rendered first,
+ * the rest by name. Each line is in the file it is placed in (`where`); a line placed nowhere - a removed
+ * one, or one written other than it reads - goes with the line placed before it, else the one after it,
+ * else the file the diff's own header names. The file being rendered is the one the diff's header names.
+ */
+export function diffFiles(diff, width, paint = PLAIN_PAINT, where) {
+    const inner = Math.max(10, width);
+    const lines = diff.replace(/\n+$/, "").split("\n");
+    // The gutter: as wide as the largest line number there is. None known, there is no gutter.
+    const digits = where === undefined || Object.keys(where).length === 0 ? 0 : String(Math.max(...Object.values(where).map((at) => at.line))).length;
+    // Every line highlighted in the diff's order, so front matter one opens is carried to the lines after it on its side.
+    let before = [];
+    let after = [];
+    let headerFile;
+    let removedFrom;
+    let rendered;
+    // The section the diff is in on each side, from the headers it shows: for lines placed nowhere.
+    let sectionBefore;
+    let sectionAfter;
+    const read = [];
+    for (const [index, line] of lines.entries()) {
+        if (line.startsWith("--- "))
+            removedFrom = line.slice(4).replace(/^a\//, "");
+        if (line.startsWith("+++ ")) {
+            // The file, by the name it has after the change - or had, when the change removes it.
+            const named = line.slice(4).replace(/^b\//, "");
+            headerFile = named === "/dev/null" ? (removedFrom ?? named) : named;
+            rendered ??= headerFile;
+            before = [];
+            after = [];
+            continue;
+        }
+        if (HEADER.test(line) || line.startsWith("@@") || line.startsWith("\\"))
+            continue;
+        const sign = line[0] === "+" || line[0] === "-" ? line[0] : " ";
+        const text = sign === " " && !line.startsWith(" ") ? line : line.slice(1);
+        let tokens;
+        if (sign === "-")
+            ({ tokens, state: before } = highlightLine(text, before));
+        else if (sign === "+")
+            ({ tokens, state: after } = highlightLine(text, after));
+        else {
+            // On both sides: each carries what it has open on.
+            ({ tokens, state: before } = highlightLine(text, before));
+            after = highlightLine(text, after).state;
+        }
+        const coloured = tokens
+            .map((token) => {
+            const role = roleOf(token.scopes);
+            return role === undefined ? token.text : paint.syntax(role, token.text);
+        })
+            .join("");
+        const header = SECTION.test(text.trim());
+        if (header && sign !== "+")
+            sectionBefore = text.trim();
+        if (header && sign !== "-")
+            sectionAfter = text.trim();
+        const at = where?.[index];
+        const section = at?.section ?? (sign === "-" ? sectionBefore : sectionAfter);
+        read.push({ index, sign, coloured, file: at?.file ?? headerFile ?? "", header, ...(headerFile !== undefined ? { under: headerFile } : {}), ...(at !== undefined ? { at } : {}), ...(section !== undefined ? { section } : {}) });
+    }
+    // A line placed nowhere is never put in a file on a guess. A removed one - in no file now - is in the file of the
+    // change it is part of: the lines placed in its own run of removed and added lines, or else the line right beside
+    // it. Any other goes with the lines found in no file, named as such.
+    // With nothing placed at all - a diff of the files themselves - its own headers say which file each line is in.
+    for (const [at, line] of read.entries()) {
+        if (line.at !== undefined || where === undefined)
+            continue;
+        // Under a header of another file than the one rendered - a linked resource whose content changed - it is that file's.
+        if (line.under !== undefined && line.under !== rendered) {
+            line.file = line.under;
+            continue;
+        }
+        line.file = NOT_FOUND;
+        // A blank line says nothing of where it is: it goes with the line before it in the diff, or else the one after it.
+        // Never a line of its own under "not found": beside nothing placed, it goes with the file being rendered.
+        if (visibleWidth(line.coloured.trim()) === 0) {
+            const candidates = [read[at - 1]?.file, read[at + 1]?.at?.file, headerFile];
+            line.file = candidates.find((file) => file !== undefined && file !== NOT_FOUND) ?? line.file;
+            continue;
+        }
+        if (line.sign !== "-")
+            continue;
+        const run = [];
+        for (let i = at; i >= 0 && read[i].sign !== " " && (i === at || read[i + 1].index - read[i].index === 1); i -= 1)
+            run.unshift(read[i]);
+        for (let i = at + 1; i < read.length && read[i].sign !== " " && read[i].index - read[i - 1].index === 1; i += 1)
+            run.push(read[i]);
+        const placed = run.find((other) => other.sign === "+" && other.at !== undefined) ?? run.find((other) => other.at !== undefined);
+        // A section's header beside it says nothing of its file: every spec has one.
+        const beside = [read[at - 1], read[at + run.length - run.indexOf(line)]].find((other) => other !== undefined && other.at !== undefined && !other.header && Math.abs(other.index - line.index) <= run.length);
+        // Beside nothing placed, it left the spec being shown.
+        const file = placed?.at?.file ?? beside?.at?.file ?? rendered;
+        if (file !== undefined)
+            line.file = file;
+    }
+    // The file being rendered first - the diff names it by its path from where it was written - then the rest by name.
+    const names = [...new Set(read.map((line) => line.file))];
+    const isRendered = (name) => rendered !== undefined && (name === rendered || rendered.endsWith(`/${name}`) || name.endsWith(`/${rendered}`));
+    // The lines found in no file last.
+    const rank = (name) => (name === NOT_FOUND ? 2 : isRendered(name) ? 0 : 1);
+    names.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+    // Only the files the diff changes: one whose lines are all context around a change elsewhere is not shown, and nor is
+    // one whose only change is a blank line - spacing, not the spec.
+    const changed = names.filter((file) => read.some((line) => line.file === file && line.sign !== " " && visibleWidth(line.coloured.trim()) > 0));
+    return changed.map((file) => {
+        const own = read.filter((line) => line.file === file);
+        const rows = [];
+        let previous;
+        // Lines of the file not in the diff, as GitHub marks them: above the first block, and between two.
+        // Its section beside it, as GitHub names a hunk's function - once: not when the block starts with the section's
+        // header itself, nor when the lines above it are in that section already, its name shown there.
+        const hidden = (arrow, count, next, above) => {
+            const lines = paint.muted(`${" ".repeat(digits)}${digits > 0 ? " " : ""}${arrow}${count !== undefined && count > 0 ? ` ${count} line${count === 1 ? "" : "s"}` : ""}`);
+            const named = next?.section !== undefined && !next.header && above?.section !== next.section;
+            return named ? `${lines}${paint.muted(" · ")}${paint.syntax("section", next.section)}` : lines;
+        };
+        const firstAt = own.find((line) => line.at !== undefined)?.at?.line;
+        if (own[0] !== undefined) {
+            // Above the first block: how many lines are hidden there, when that is known - and its section, unless it starts with it.
+            const count = own[0].at !== undefined && firstAt !== undefined ? firstAt - 1 : undefined;
+            if ((count !== undefined && count > 0) || (own[0].section !== undefined && !own[0].header))
+                rows.push(hidden("↑", count, own[0]));
+        }
+        for (const line of own) {
+            // Where its lines do not follow on from each other - another hunk, or another place in the file - the lines between are hidden.
+            if (previous !== undefined) {
+                const gap = line.at !== undefined && previous.at !== undefined ? line.at.line - previous.at.line - 1 : undefined;
+                const follows = gap !== undefined ? gap <= 0 : line.index - previous.index <= 1;
+                if (!follows)
+                    rows.push(hidden("↕", gap, line, previous));
+            }
+            previous = line;
+            const mark = line.sign === "+" ? paint.added("+") : line.sign === "-" ? paint.removed("-") : " ";
+            const gutter = line.at !== undefined ? paint.muted(String(line.at.line).padStart(digits)) : " ".repeat(digits);
+            const lead = digits > 0 ? `${gutter} ` : "";
+            const blank = " ".repeat(digits > 0 ? digits + 1 : 0);
+            const [first = "", ...rest] = line.coloured === "" ? [""] : wrapTextWithAnsi(line.coloured, inner - 2 - blank.length);
+            // Continuations under the text, not the number or the sign: those columns stay clear.
+            for (const row of [`${lead}${mark} ${first}`, ...rest.map((part) => `${blank}  ${part}`)]) {
+                const padded = `${row}${" ".repeat(Math.max(0, inner - visibleWidth(row)))}`;
+                rows.push(line.sign === "+" ? paint.addedBand(padded) : line.sign === "-" ? paint.removedBand(padded) : row);
+            }
+        }
+        return { file, added: own.filter((line) => line.sign === "+").length, removed: own.filter((line) => line.sign === "-").length, rows };
+    });
+}
+/** A file's header: its name, and what it adds and takes out. `open`, with the mark of a group that opens and closes. */
+export function fileHeader(file, paint, open) {
+    const mark = open === undefined ? "" : open ? "▾ " : "▸ ";
+    const counts = [file.added > 0 ? paint.added(`+${file.added}`) : "", file.removed > 0 ? paint.removed(`−${file.removed}`) : ""].filter(Boolean).join(" ");
+    return `${paint.muted(`${mark}${file.file === "" ? "(the spec)" : file.file}`)}${counts !== "" ? `  ${counts}` : ""}`;
+}
+/** Where a spec diff's lines go that are in none of the spec's files as they are written. */
+export const NOT_FOUND = "not found in the spec's files";
+/** The diff's lines, at most `width` wide: every file, each under its header - for a view that opens none and closes none. */
+export function diffView(diff, width, paint = PLAIN_PAINT, where) {
+    return diffFiles(diff, width, paint, where).flatMap((file) => [fileHeader(file, paint), ...file.rows]);
+}

package/dist/regenerate/drift.js

@@ -0,0 +1,194 @@
+import { DEFAULT_CONCEPTS, extractConceptsFromDefinition, extractConceptsFromSpecText } from "../plain/concepts.js";
+import { DEFINITIONS, FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS } from "../plain/spec.js";
+import { codeTree, conformanceTarget, marksRegenerateAgain } from "./records.js";
+import { applyChanges, changesBetween, parseTree, resourcesChanged, serializeTree } from "./spec-steps.js";
+/**
+ * The work, derived from the records - see docs/regenerating.md. Nothing here is stored: what is left
+ * to build is the difference between what a record says is built and what the spec says now, worked
+ * out again whenever either changes.
+ *
+ * - Code work: from the code record to the spec as the code sees it.
+ * - Conformance work: from the tests record to what the conformance tests are to be written for now -
+ *   the chosen functional specs the code is built from.
+ *
+ * A job is a set of those changes. What it tells its agents follows from the functional specs it
+ * touches - its cases - and a running job is stopped once the spec no longer wants what it makes.
+ */
+/** Everything left to build in the code: from what the code record says it is built from, to the spec now. */
+export function codeWork(record, spec) {
+    return changesBetween(serializeTree(codeTree(record ?? {})), serializeTree(codeTree(spec)));
+}
+/** Everything left to do in the conformance tests: from what the tests record says they are written for, to what they are to be now. */
+export function conformanceWork(tests, code, spec, chosen) {
+    return changesBetween(serializeTree(tests ?? {}), serializeTree(conformanceTarget(code, tests, spec, chosen)));
+}
+const functionalSpecs = (tree) => tree[FUNCTIONAL_REQUIREMENTS] ?? [];
+const firstLine = (markdown) => markdown.trim().split("\n")[0].replace(/^-\s*/, "").trim();
+/** An item of a serialized tree, read back. */
+const itemOfLine = (line) => {
+    if (line === undefined)
+        return undefined;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The concept a definition defines, from its text. */
+const definedBy = (markdown) => extractConceptsFromDefinition(markdown)[0];
+/** The concepts a text names, the predefined ones left out. */
+const namedIn = (text) => extractConceptsFromSpecText(text).filter((concept) => !DEFAULT_CONCEPTS.has(concept));
+/**
+ * Every concept a functional spec uses: those its text names, and those their definitions name in
+ * turn, as far as it goes.
+ */
+export function conceptsUsed(markdown, definitions) {
+    const byConcept = new Map();
+    for (const definition of definitions)
+        for (const concept of definedBy(definition.markdown))
+            byConcept.set(concept, definition.markdown);
+    const used = new Set();
+    const visit = (text) => {
+        for (const concept of namedIn(text)) {
+            if (used.has(concept))
+                continue;
+            used.add(concept);
+            const definition = byConcept.get(concept);
+            if (definition !== undefined)
+                visit(definition);
+        }
+    };
+    visit(markdown);
+    return used;
+}
+/**
+ * The cases of a job: `before` is the tree it starts from - the record, or what the jobs ahead of it
+ * leave - and `changes` the changes it makes, found from `before`. `fresh`: the module requires none
+ * and nothing is built.
+ *
+ * A functional spec is patched when its item changed, or when a concept it uses - as the spec after
+ * the job defines it, or as it was defined before - is defined anew, changed or taken out by the job.
+ * `module`: the module whose codebase it is - its own functional specs are that module's.
+ */
+export function casesOf(before, changes, options = {}) {
+    const beforeText = serializeTree(before);
+    const after = parseTree(applyChanges(beforeText, changes));
+    const numberIn = (tree, item, position) => {
+        if (item?.frid !== undefined)
+            return item.frid;
+        const specs = functionalSpecs(tree);
+        const at = item === undefined ? -1 : specs.findIndex((spec) => spec.markdown === item.markdown);
+        return String(at === -1 ? position : at + 1);
+    };
+    const own = options.module !== undefined ? { module: options.module } : {};
+    const add = [];
+    const patch = [];
+    const again = [];
+    const removed = [];
+    for (const change of changes) {
+        const was = itemOfLine(change.before);
+        const is = itemOfLine(change.after);
+        // Marked to regenerate again: regenerated again, whatever else changed in its text - its own or, required, another module's.
+        if (change.kind === "change" && is !== undefined && marksRegenerateAgain(was)) {
+            const required = change.section === REQUIRED_FUNCTIONAL_SPECS ? is : undefined;
+            if (change.section === FUNCTIONAL_REQUIREMENTS)
+                again.push({ frid: numberIn(after, is, change.position), text: firstLine(is.markdown), ...own });
+            else if (required !== undefined)
+                again.push({ frid: `${required.frid ?? change.position}`, text: firstLine(is.markdown), ...(required.module !== undefined ? { module: required.module } : {}) });
+            continue;
+        }
+        if (change.section !== FUNCTIONAL_REQUIREMENTS)
+            continue;
+        if (change.kind === "add" && is !== undefined)
+            add.push({ frid: numberIn(after, is, change.position), text: firstLine(is.markdown), ...own });
+        else if (change.kind === "remove" && was !== undefined)
+            removed.push({ frid: numberIn(before, was, change.position), text: firstLine(was.markdown), ...own });
+        else if (change.kind === "change" && is !== undefined)
+            patch.push({ frid: numberIn(after, is, change.position), text: firstLine(is.markdown), ...own });
+    }
+    // The concepts the job defines anew, changes or takes out.
+    const redefined = new Set();
+    for (const change of changes) {
+        if (change.section !== DEFINITIONS)
+            continue;
+        for (const line of [change.before, change.after]) {
+            const item = itemOfLine(line);
+            if (item !== undefined)
+                for (const concept of definedBy(item.markdown))
+                    redefined.add(concept);
+        }
+    }
+    if (redefined.size > 0) {
+        const touched = new Set([...add, ...patch, ...again].filter((spec) => spec.module === options.module).map((spec) => spec.frid));
+        const definitionsAfter = after[DEFINITIONS] ?? [];
+        const definitionsBefore = before[DEFINITIONS] ?? [];
+        functionalSpecs(after).forEach((item, index) => {
+            const frid = item.frid ?? String(index + 1);
+            if (touched.has(frid))
+                return;
+            const uses = new Set([...conceptsUsed(item.markdown, definitionsAfter), ...conceptsUsed(item.markdown, definitionsBefore)]);
+            if ([...redefined].some((concept) => uses.has(concept)))
+                patch.push({ frid, text: firstLine(item.markdown), ...own });
+        });
+        patch.sort((a, b) => Number(a.frid) - Number(b.frid));
+    }
+    return {
+        fresh: options.fresh === true,
+        add,
+        patch,
+        again,
+        delete: removed,
+        mechanical: add.length === 0 && patch.length === 0 && again.length === 0 && removed.length === 0,
+    };
+}
+/** Two changes are the same change when they do the same to the same item. */
+function sameChange(a, b) {
+    return a.section === b.section && a.kind === b.kind && (a.before ?? "") === (b.before ?? "") && (a.after ?? "") === (b.after ?? "");
+}
+/**
+ * Whether a running job may finish: every change it makes is still part of the work as it is now -
+ * both measured from the same record, which nothing changes while the job runs. When one is not, the
+ * job is making something the spec no longer wants, and it is stopped and rolled back.
+ */
+/**
+ * Why a running job is no longer wanted, in a line: the files it links that hold something else now - the commonest
+ * cause, a resource edited while the job regenerated from it - else the items whose text changed under it, by section
+ * and place.
+ */
+export function whyNotWanted(running, work) {
+    const taken = new Set();
+    const gone = running.filter((mine) => {
+        const at = work.findIndex((change, index) => !taken.has(index) && sameChange(mine, change));
+        if (at === -1)
+            return true;
+        taken.add(at);
+        return false;
+    });
+    const files = new Set();
+    const items = [];
+    for (const mine of gone) {
+        // The same item as the spec has it now: by section and place.
+        const now = work.find((change) => change.section === mine.section && change.position === mine.position);
+        const changedFiles = now !== undefined ? resourcesChanged(mine.after, now.after).map((resource) => resource.target) : [];
+        if (changedFiles.length > 0)
+            changedFiles.forEach((file) => files.add(file));
+        else
+            items.push(`${mine.section} ${mine.position}`);
+    }
+    const parts = [
+        ...(files.size > 0 ? [`${[...files].join(", ")} ${files.size === 1 ? "holds" : "hold"} something else now`] : []),
+        ...(items.length > 0 ? [`${items.join(", ")} ${items.length === 1 ? "reads" : "read"} otherwise now`] : []),
+    ];
+    return parts.length > 0 ? parts.join("; ") : "the spec it was building from changed";
+}
+export function stillWanted(running, work) {
+    const taken = new Set();
+    return running.every((mine) => {
+        const at = work.findIndex((change, index) => !taken.has(index) && sameChange(mine, change));
+        if (at === -1)
+            return false;
+        taken.add(at);
+        return true;
+    });
+}

package/dist/regenerate/engine.js

@@ -0,0 +1,118 @@
+/**
+ * Which model the agents of a job run on.
+ *
+ * By default, whatever the conversation is using. The person can say otherwise - "render spec
+ * changes with Gemini Flash" - for one kind of work or for all of it, and that holds for the
+ * rest of the session, for jobs started from a tool call and for jobs a skill queues alike. A
+ * single tool call can also name a model for itself alone.
+ *
+ * A name is resolved strictly. pi's own pattern matching picks its best guess and says nothing
+ * - "gpt-5" becomes a Bedrock model with no credentials, "flash" a GLM one - and a job on a
+ * guessed model is worse than a question. So an exact id is taken as it is, a looser name is
+ * taken only when it fits exactly one model that has credentials, and anything else comes back
+ * as a short list to ask the person about.
+ */
+const MAX_CANDIDATES = 8;
+function label(model) {
+    return `${model.provider}/${model.id}`;
+}
+function describe(model, catalog) {
+    const name = model.name && model.name !== model.id ? ` (${model.name})` : "";
+    return `${label(model)}${name}${catalog.hasConfiguredAuth(model) ? "" : " - no credentials"}`;
+}
+/** The words of a model name, lowercased: "Gemini Flash 3.1" and "gemini-3.1-flash" alike. */
+function words(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s/_:-]+|(?<=[a-z])(?=\d)|(?<=\d)(?=[a-z])/)
+        .filter(Boolean);
+}
+function noCredentials(model) {
+    return {
+        ok: false,
+        message: `${label(model)} is known, but ${model.provider} has no credentials here. ` +
+            "Log in with /login, or set the provider's API key, and try again.",
+        candidates: [],
+    };
+}
+function found(model) {
+    return { ok: true, model: label(model), name: model.name ?? model.id };
+}
+/** Resolve what the person called a model to one this machine can run, or say why not. */
+export function resolveModel(query, catalog) {
+    const wanted = query.trim();
+    const all = catalog.getAll();
+    const usable = (model) => catalog.hasConfiguredAuth(model);
+    // An exact reference: provider/id, or a bare id.
+    const exact = all.filter((model) => label(model).toLowerCase() === wanted.toLowerCase());
+    if (exact.length > 0)
+        return usable(exact[0]) ? found(exact[0]) : noCredentials(exact[0]);
+    const byId = all.filter((model) => model.id.toLowerCase() === wanted.toLowerCase());
+    const byIdUsable = byId.filter(usable);
+    if (byIdUsable.length === 1)
+        return found(byIdUsable[0]);
+    if (byId.length === 1)
+        return noCredentials(byId[0]);
+    // A looser name: every word of it has to be in the model's provider, id or name.
+    const asked = words(wanted);
+    const matches = (byId.length > 1 ? byId : all).filter((model) => {
+        const have = new Set(words(`${model.provider} ${model.id} ${model.name ?? ""}`));
+        return asked.length > 0 && asked.every((word) => have.has(word));
+    });
+    const matchesUsable = matches.filter(usable);
+    if (matchesUsable.length === 1)
+        return found(matchesUsable[0]);
+    // Several fit, but one is exactly what was said - "gpt 5.5" is gpt-5.5, not gpt-5.5-pro.
+    const same = (model) => {
+        const id = words(model.id).filter((word) => !words(model.provider).includes(word));
+        const said = asked.filter((word) => !words(model.provider).includes(word));
+        return id.length === said.length && said.every((word) => id.includes(word));
+    };
+    const exactly = matchesUsable.filter(same);
+    if (exactly.length === 1)
+        return found(exactly[0]);
+    const shown = [...matchesUsable, ...matches.filter((model) => !usable(model))].slice(0, MAX_CANDIDATES);
+    if (shown.length === 0) {
+        return {
+            ok: false,
+            message: `No model matches '${wanted}'. Give its provider/id - pi's /model lists the ones configured here.`,
+            candidates: [],
+        };
+    }
+    const more = matches.length > shown.length ? ` (and ${matches.length - shown.length} more)` : "";
+    return {
+        ok: false,
+        message: matchesUsable.length === 0
+            ? `'${wanted}' matches no model that has credentials here. The closest${more}:`
+            : `'${wanted}' fits more than one model. Ask which one is meant${more}:`,
+        candidates: shown.map((model) => describe(model, catalog)),
+    };
+}
+/** The resolution as text for the agent: the model, or why not and what to ask. */
+export function describeResolution(resolution) {
+    if (resolution.ok)
+        return `${resolution.model} (${resolution.name})`;
+    return [resolution.message, ...resolution.candidates.map((candidate) => `- ${candidate}`)].join("\n");
+}
+export const WORK_LABEL = {
+    spec_changes: "spec changes",
+    functionalities: "functionalities",
+    all: "everything",
+};
+/** The model a job of this kind runs on: chosen for it, chosen for everything, or the chat's. */
+export function modelFor(choices, work, chat) {
+    return choices[work] ?? choices.all ?? chat;
+}
+/**
+ * Where each kind of work runs now, in a line each: chosen in this session, or the default coding
+ * model - from `--coding-model` or config.turri.yaml, said which - or the conversation's.
+ */
+export function describeChoices(choices, chat, project) {
+    const fallback = project !== undefined ? `${project.model} (${project.from})` : `${chat ?? "pi's default model"} (the chat's model)`;
+    return ["spec_changes", "functionalities"]
+        .map((work) => {
+        const chosen = choices[work] ?? choices.all;
+        return `- ${WORK_LABEL[work]}: ${chosen ?? fallback}`;
+    })
+        .join("\n");
+}