@turri-dev/cli 0.1.2-next.48dacfc → 0.1.3-next.17f0f7f

package/dist/chat-skills.js

@@ -11,7 +11,7 @@
  * message, a deploy - is offered as pi offers it.
  */
 /** What a skill says it is about, that turri covers: ***plain specs and their testing scripts. */
-const ABOUT_PLAIN = /\*\*\*plain|\\\*\\\*\\\*plain|\.plain\b|\bcodeplain\b|functional specs?\b|testing scripts?\b|run_unittests|run_conformance_tests/i;
+const ABOUT_PLAIN = /\*\*\*plain|\\\*\\\*\\\*plain|\.plain\b|functional specs?\b|testing scripts?\b|run_unittests|run_conformance_tests/i;
 /** Whether turri has what a pi skill offers: it runs a skill of that name itself, or the skill is about ***plain. */
 export function supersededByTurri(skill, turriRuns) {
     return turriRuns.has(skill.name) || ABOUT_PLAIN.test(`${skill.name} ${skill.description}`);

package/dist/config.js

@@ -49,7 +49,7 @@ import { projectDirOf } from "./regenerate/paths.js";
  * as `coding-model`, which it was before there were two.
  *
  * Keys are written with dashes; underscores are read the same (`conformance_tests`). Keys it
- * does not know - a codeplain `config.yaml`, read while it is the old file, carries several - are ignored, and so is a value of
+ * does not know - another tool's `config.yaml`, read while it is the old file, may carry several - are ignored, and so is a value of
  * the wrong type. Everything is optional, and what is given on the command line wins.
  *
  * A project whose parts do not share a stack - a Python backend and a React frontend beside each other - keeps a
@@ -385,6 +385,9 @@ function text(value) {
  * not parse.
  */
 export function readProjectConfig(root, stack) {
+    return withRunOverrides(readStackedConfig(root, stack));
+}
+function readStackedConfig(root, stack) {
     const project = readConfigFile(join(root, projectConfigFile(root)));
     if (stack === undefined)
         return project;
@@ -403,6 +406,25 @@ export function readProjectConfig(root, stack) {
     merged.models = joinModels(project.models, own.models);
     return withoutUndefined(merged);
 }
+let runOverrides = {};
+/** Read a command's options as the config's keys for the rest of this process. */
+export function overrideConfig(overrides) {
+    runOverrides = { ...overrides };
+}
+/** `--conformance-tests <value>`: the config's own values - all (or true), chosen, module, false. Undefined for anything else. */
+export function conformanceOption(value) {
+    return conformanceSetting(value);
+}
+/** `--review <value>`: the config's own, true or false. Undefined for anything else. */
+export function reviewOption(value) {
+    const word = value.trim().toLowerCase();
+    return word === "true" ? true : word === "false" ? false : undefined;
+}
+/** The config with the command's options in place of the keys they name. */
+function withRunOverrides(config) {
+    const given = Object.entries(runOverrides).filter(([, value]) => value !== undefined);
+    return given.length === 0 ? config : { ...config, ...Object.fromEntries(given) };
+}
 /** A module's `models:` over the project's, role by role - each entry taking what it leaves out from the project's; the chat's the project's alone. */
 function joinModels(project, own) {
     if (own === undefined)

package/dist/conform-cli.js

@@ -1,4 +1,4 @@
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { headlessOptions, parseArgs, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri conform <file.plain> [frid ...] [options]
 
 Writes and runs the black-box conformance tests of a module's functional specs - those named, or
@@ -8,8 +8,14 @@ module inherits, a failure fixed in the test or the code, whichever is wrong. Ev
 tested goes in one pulse, as far as the size guardrail lets.
 
   --one-by-one             a pulse a functional spec instead
-  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--one-by-one"], USAGE);
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --coding-model <p/id>    its coding-model, --model too: the agents that build
+  --judge-model <p/id>     its judge-model: the judge and the test review
+  --review <true|false>    its review: whether the code and its tests are reviewed once they pass
+  --build-dir <dir>        as the run ends, export the code there (see turri regenerate --help)
+  --report <file.json>     write a report of the run there (see turri regenerate --help)`;
+const { positional, options } = parseArgs(process.argv.slice(2), ["--one-by-one"], USAGE, ["--build-dir", "--report", "--harness-model", "--judge-model", "--review"]);
+const { report, buildDir } = headlessOptions(options, false);
 const [plainFile, ...frids] = positional;
 if (plainFile === undefined) {
     console.error(USAGE);
@@ -17,10 +23,11 @@ if (plainFile === undefined) {
 }
 runLoop({
     plainFile,
-    ...(options.model !== undefined ? { model: options.model } : {}),
+    ...(buildDir !== undefined ? { buildDir } : {}),
+    ...(report !== undefined ? { report } : {}),
+    command: ["conform", ...process.argv.slice(2)],
     ask: (loop) => loop.conformance(plainFile, {
         ...(frids.length > 0 ? { frids } : {}),
-        ...(options.model !== undefined ? { model: options.model } : {}),
         ...(options["one-by-one"] !== undefined ? { separately: true } : {}),
     }),
 }).catch((error) => {

package/dist/init-config.js

@@ -292,7 +292,7 @@ function whose(vendor, bedrock) {
     return `${VENDORS[choice.maker].label}'s on Amazon Bedrock (${choice.region})`;
 }
 /**
- * What a config.yaml in `folder` says that turri reads too - codeplain's testing scripts, say - by turri's names
+ * What a config.yaml in `folder` says that turri reads too - another tool's testing scripts, say - by turri's names
  * (`template_dir` read as `template-dir`), in the file's order; and the keys it leaves, turri reading none of them. The
  * two models are the vendor's, so they are not taken.
  */
@@ -338,7 +338,7 @@ export function initConfig(dir, options = {}) {
     const existing = existsSync(path) && options.force !== true;
     const { harness, coding } = modelsOf(vendor, options.bedrock);
     const lines = modelLines(harness, coding);
-    // A new file takes what a config.yaml beside it - codeplain's - says that turri reads too: its testing scripts, say.
+    // A new file takes what a config.yaml beside it - another tool's, say - says that turri reads too: its testing scripts, say.
     const shared = existing ? { carried: [], left: [] } : sharedWithLegacy(folder);
     const config = existing
         ? withModels(readFileSync(path, "utf8"), lines)
@@ -384,7 +384,7 @@ const USAGE = [
     "a mix of Anthropic and Google, the starting point for any provider pi supports. On amazon-bedrock, --maker and",
     "--region say whose models and where (anthropic: global, us, eu, jp, au; openai: global, us) - asked when not given.",
     "A config.turri.yaml already there keeps everything but its two models; --force writes the whole of it again. A new",
-    "one takes from a config.yaml beside it - codeplain's - the keys turri reads too, its testing scripts say, and leaves",
+    "one takes from a config.yaml beside it - another tool's, say - the keys turri reads too, its testing scripts say, and leaves",
     "config.yaml as it is.",
 ].join("\n");
 /** Ask until the answer is one `read` takes. */

package/dist/loop-cli.js

@@ -1,20 +1,23 @@
 import { sweepOrphanedGroups } from "./regenerate/shell.js";
 import { createInterface } from "node:readline/promises";
-import { resolve } from "node:path";
-import { configForSpec, modelSpec, projectModels, readProjectConfig } from "./config.js";
+import { resolve, sep } from "node:path";
+import { configForSpec, conformanceOption, reviewOption, inheritModel, modelOnly, modelSpec, overrideConfig, projectModels, readProjectConfig, roleModel, ROLE_THINKING, splitModelSpec, } from "./config.js";
 import { PACKAGE_ROOT } from "./environment.js";
 import { c } from "./module-report.js";
 import { tryItCommand } from "./regenerate/delivery.js";
 import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
 import { createJobRegistry, pulseName } from "./regenerate/jobs.js";
 import { conformanceChooser } from "./regenerate/choose-conformance.js";
-import { createWorkLoop, describeModules, promptOf } from "./regenerate/loop.js";
-import { projectDirOf } from "./regenerate/paths.js";
+import { createWorkLoop, describeModules, functionalityCompletion, promptOf } from "./regenerate/loop.js";
+import { MODULES_DIR, projectDirOf } from "./regenerate/paths.js";
+import { exportModule } from "./regenerate/release.js";
+import { listFiles } from "./regenerate/testing.js";
+import { startRunReport } from "./run-report.js";
 /**
  * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
  * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
  * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
- * and exit 1 when any failed. With `dryRun`, the work is planned and the prompt of the first job each codebase would
+ * and exit 1 when any failed or a module is not complete. With `dryRun`, the work is planned and the prompt of the first job each codebase would
  * start printed, and nothing runs.
  */
 export async function runLoop(options) {
@@ -24,8 +27,42 @@ export async function runLoop(options) {
     if (orphans > 0)
         console.log(`Stopped ${orphans} process group${orphans === 1 ? "" : "s"} a turri that was killed left running.`);
     const project = { ...readProjectConfig(process.cwd()), ...Object.fromEntries(Object.entries(configForSpec(plainFile)).filter(([, value]) => value !== undefined)) };
-    const model = options.model ?? modelSpec(projectModels(project).coding);
+    // The models as the config has them - with a command's own options read as its keys (headlessOptions), as the chat reads them.
+    const model = modelSpec(projectModels(project).coding);
     const projectDir = projectDirOf(plainFile);
+    const buildDir = options.buildDir !== undefined && options.dryRun !== true ? resolve(options.buildDir) : undefined;
+    if (buildDir !== undefined)
+        refuseBuildDir(buildDir, projectDir);
+    // The code, exported into --build-dir as the process exits - however it exits - before the report's last write.
+    let exported;
+    if (buildDir !== undefined) {
+        process.once("exit", () => {
+            exported = exportCode(plainFile, buildDir);
+            console.error(exported.exported === true ? `The code is in ${buildDir} (${String(exported.module)} at ${String(exported.commit)}).` : `Nothing exported to ${buildDir}: ${String(exported.why)}`);
+        });
+    }
+    const report = options.report !== undefined && options.dryRun !== true
+        ? startRunReport({
+            file: options.report,
+            command: options.command ?? process.argv.slice(2),
+            specFile: plainFile,
+            projectDir,
+            ...(buildDir !== undefined ? { buildDir } : {}),
+            conformanceTests: conformanceLabel(project.conformanceTests),
+            review: project.review === true,
+            models: reportModels(project, model),
+        })
+        : undefined;
+    try {
+        return await runLoopReporting({ ...options, plainFile, project, model, projectDir, reporter: report, exported: () => exported });
+    }
+    catch (error) {
+        report?.crashed(error);
+        throw error;
+    }
+}
+async function runLoopReporting(options) {
+    const { plainFile, project, model, projectDir, reporter: report } = options;
     // Each job as it starts and as it ends - the transcript of each is in .turri/jobs/.
     const seen = new Map();
     const registry = createJobRegistry({
@@ -47,18 +84,28 @@ export async function runLoop(options) {
             console.log(`${mark} ${job.id} ${pulseName(job)} - ${job.status}`);
             if (job.status !== "succeeded")
                 console.log(c.dim((job.announce ?? job.report ?? job.error ?? "").trim()));
+            report?.write();
         },
     });
     const planner = modelSpec(projectModels(project).harness);
     const loop = createWorkLoop({
         registry,
         cwd: process.cwd(),
-        ...(options.buildDir !== undefined ? { buildDir: resolve(options.buildDir) } : {}),
         ...(model !== undefined ? { modelFor: () => model } : {}),
         ...(planner !== undefined ? { plannerModel: planner } : {}),
         ...(options.dryRun === true ? { dryRun: true } : {}),
-        // Under conformance-tests: chosen or module, the chooser decides as a pulse ends, as in the chat.
-        onChoose: conformanceChooser({ model: () => planner, ...(options.dryRun === true ? { dryRun: true } : {}) }),
+        // Under conformance-tests: chosen or module, the chooser decides as a pulse ends, as in the chat - on the harness
+        // model, else the coding model: never pi's own default, which may be one this account cannot reach.
+        onChoose: conformanceChooser({ model: () => planner ?? model, ...(options.dryRun === true ? { dryRun: true } : {}) }),
+    });
+    report?.attach({
+        jobs: () => registry.list(),
+        modules: () => moduleStates(loop.drift(plainFile)),
+        completion: () => functionalityCompletion(plainFile),
+        atExit: () => {
+            const exported = options.exported();
+            return exported !== undefined ? { build_dir_export: exported } : undefined;
+        },
     });
     let planned = await options.ask(loop);
     console.log(describeModules(planned, { for: "command line" }));
@@ -68,6 +115,13 @@ export async function runLoop(options) {
         const why = toStartOver
             .map(({ startOver }) => `${startOver.codebases.join(", ")} was built without ${startOver.requires.join(", ")}, which it now requires: no change to its code can bring it in.`)
             .join("\n");
+        // No terminal and no --start-over: no one to ask, so the run stops here rather than build nothing and say it is done.
+        if (options.startOver !== true && process.stdin.isTTY !== true) {
+            const message = `${why}\nThere is no terminal to ask whether to start over: run it again with --start-over to start over without asking.`;
+            console.error(c.red(message));
+            report?.end("incomplete", message);
+            process.exit(1);
+        }
         const agreed = options.startOver === true ||
             (await askAtTerminal("Start over?", `${why}\nStarting over takes its code and conformance tests out - they stay in its history - and builds it again from the bottom of the chain.`));
         if (agreed === true) {
@@ -91,27 +145,168 @@ export async function runLoop(options) {
     console.log(`\n${describeModules(loop.status(), { for: "command line" })}`);
     const ended = registry.list();
     const failed = ended.filter((job) => job.status === "failed");
-    console.log(`\n${failed.length === 0 ? c.green(c.bold("all jobs done")) : c.red(c.bold(`${failed.length} job${failed.length === 1 ? "" : "s"} failed`))}`);
+    // Complete: every codebase regenerated from the spec as it is, its conformance tests too - nothing halted, nothing
+    // waiting for a start over, nothing the planner left out.
+    const unfinished = moduleStates(loop.drift(plainFile)).filter((module) => module.state !== "complete");
+    const verdict = failed.length > 0
+        ? c.red(c.bold(`${failed.length} job${failed.length === 1 ? "" : "s"} failed`))
+        : unfinished.length > 0
+            ? c.red(c.bold(`not complete: ${unfinished.map((module) => `${module.module}${module.why !== undefined ? ` - ${module.why}` : ""}`).join("; ")}`))
+            : c.green(c.bold("all jobs done"));
+    console.log(`\n${verdict}`);
     for (const job of [...ended].reverse())
         console.log(`  ${job.id} ${pulseName(job)}: ${job.status}`);
     if (ended.some((job) => job.status === "succeeded"))
         console.log(`\n${tryItCommand(plainFile)}`);
-    process.exit(failed.length === 0 ? 0 : 1);
+    report?.end(failed.length > 0 ? "failed" : unfinished.length > 0 ? "incomplete" : "completed");
+    process.exit(failed.length === 0 && unfinished.length === 0 ? 0 : 1);
+}
+/** How each codebase stands, from what is left to regenerate there. */
+export function moduleStates(reports) {
+    return reports.map((report) => {
+        const state = report.running !== undefined
+            ? "running"
+            : report.startOver !== undefined
+                ? "start_over_needed"
+                : report.why !== undefined
+                    ? "halted"
+                    : report.code === null && (report.conformance === null || report.conformance === undefined) && report.scheduled.length === 0
+                        ? "complete"
+                        : "incomplete";
+        const why = state === "start_over_needed"
+            ? `built without ${report.startOver.requires.join(", ")}, which it now requires: run with --start-over`
+            : state === "incomplete"
+                ? report.code !== null && report.code !== undefined
+                    ? "its code is not regenerated from the spec as it is"
+                    : "its conformance tests are not written for what is built"
+                : report.why;
+        return { module: report.module, state, ...(why !== undefined ? { why } : {}) };
+    });
+}
+/**
+ * A --build-dir the export would wipe something in: the project, a folder holding it, or one inside plain_modules.
+ * Anything else is the export's own, its contents replaced as the run ends.
+ */
+function refuseBuildDir(buildDir, projectDir) {
+    const within = (dir, of) => dir === of || dir.startsWith(`${of}${sep}`);
+    const why = within(projectDir, buildDir)
+        ? "it holds the project, and the export replaces what is in it"
+        : within(buildDir, resolve(projectDir, MODULES_DIR))
+            ? `it is inside ${MODULES_DIR}, which turri regenerates in`
+            : undefined;
+    if (why === undefined)
+        return;
+    console.error(`--build-dir ${buildDir} cannot be used: ${why}. Name a folder of its own - the code is exported there as the run ends.`);
+    process.exit(1);
+}
+/** The furthest-built codebase's last commit, exported into `dir` - or why nothing was. */
+function exportCode(plainFile, dir) {
+    try {
+        const deployment = exportModule(plainFile, undefined, dir);
+        const files = listFiles(dir).length;
+        // Its history began, and nothing landed in it yet: only the harness's own files, which are left out.
+        if (files === 0)
+            return { exported: false, dir, why: `nothing has landed in ${deployment.moduleName} yet: its codebase holds no code` };
+        return { exported: true, dir, module: deployment.moduleName, commit: deployment.commit, files };
+    }
+    catch (error) {
+        return { exported: false, dir, why: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** `conformance-tests:` as the report says it - not set is false. */
+function conformanceLabel(setting) {
+    return setting === true ? "all" : setting === "chosen" || setting === "module" ? setting : "false";
+}
+/** The models of the three roles as this run uses them: the coding model given, the others as they fall back - each with the level it thinks at. */
+function reportModels(project, model) {
+    const coding = splitModelSpec(model);
+    const harness = projectModels(project).harness ?? modelOnly(model);
+    // As the judge's agent finds it: its models: entry over judge-model over models.default, else the coding model's.
+    const judge = inheritModel(roleModel(project, "judge"), modelOnly(model)) ?? {};
+    const choice = (given, fallback) => ({
+        ...(given.model !== undefined ? { model: given.model } : {}),
+        ...((given.thinking ?? fallback) !== undefined ? { thinking: given.thinking ?? fallback } : {}),
+    });
+    return {
+        harness: choice(harness, ROLE_THINKING.planner),
+        coding: choice(coding, ROLE_THINKING.coding),
+        judge: choice(judge, ROLE_THINKING.judge),
+    };
 }
-/** A command's arguments: the positional ones, and `--name value` / `--flag` options - `--coding-model` is `--model`. */
-export function parseArgs(argv, flags, usage) {
+/**
+ * The options every command that regenerates takes for a headless run: `--report` and `--build-dir`, and the config's
+ * own keys - `--harness-model`, `--coding-model` (`--model`), `--judge-model`, `--review` and, where `conformance` is
+ * true, `--conformance-tests` - read as if config.turri.yaml had them, the config's order of them kept (overrideConfig).
+ * Exits on a value it cannot read.
+ */
+export function headlessOptions(options, conformance) {
+    const given = (name) => {
+        const value = options[name];
+        if (name in options && (value === undefined || value.trim() === ""))
+            failOption(`--${name} needs a value`);
+        return value;
+    };
+    const tests = conformance ? given("conformance-tests") : undefined;
+    const setting = tests !== undefined ? conformanceOption(tests) : undefined;
+    if (tests !== undefined && setting === undefined)
+        failOption(`--conformance-tests takes all, chosen, module or false, not ${tests}`);
+    const reviewed = given("review");
+    const review = reviewed !== undefined ? reviewOption(reviewed) : undefined;
+    if (reviewed !== undefined && review === undefined)
+        failOption(`--review takes true or false, not ${reviewed}`);
+    const model = (name) => {
+        const spec = given(name);
+        return spec !== undefined ? { [name === "model" ? "codingModel" : name === "harness-model" ? "harnessModel" : "judgeModel"]: splitModelSpec(spec) } : {};
+    };
+    overrideConfig({
+        ...model("harness-model"),
+        ...model("model"),
+        ...model("judge-model"),
+        ...(setting !== undefined ? { conformanceTests: setting } : {}),
+        ...(review !== undefined ? { review } : {}),
+    });
+    const report = given("report");
+    const buildDir = given("build-dir");
+    return { ...(report !== undefined ? { report } : {}), ...(buildDir !== undefined ? { buildDir } : {}) };
+}
+function failOption(message) {
+    console.error(message);
+    process.exit(1);
+}
+/**
+ * A command's arguments: the positional ones, `--flag`s and `--name value` options (`--name=value` too) -
+ * `--coding-model` is `--model`. An option it does not take is refused, rather than taking the word after it, and so is an
+ * option with no value - the end of the words, or another option where its value should be.
+ */
+export function parseArgs(argv, flags, usage, valued = []) {
     const positional = [];
     const options = {};
+    const takes = new Set(["--model", ...valued]);
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
+        const [name, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+        const option = name === "--coding-model" ? "--model" : name;
         if (arg === "-h" || arg === "--help") {
             console.log(usage);
             process.exit(0);
         }
-        else if (flags.includes(arg))
-            options[arg.slice(2)] = "yes";
-        else if (arg.startsWith("--"))
-            options[arg === "--coding-model" ? "model" : arg.slice(2)] = argv[++i];
+        else if (flags.includes(option) && inline === undefined)
+            options[option.slice(2)] = "yes";
+        else if (takes.has(option)) {
+            // Its value is the next word - never another option, which would be taken as the value and lost.
+            const value = inline ?? argv[i + 1];
+            if (value === undefined || (inline === undefined && value.startsWith("--"))) {
+                console.error(`${usage}\n\n${name} needs a value${value !== undefined ? `, not the option ${value}` : ""} - ${name}=<value> gives one that starts with --.`);
+                process.exit(1);
+            }
+            if (inline === undefined)
+                i += 1;
+            options[option.slice(2)] = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`${usage}\n\nNo such option: ${name}.`);
+            process.exit(1);
+        }
         else
             positional.push(arg);
     }

package/dist/pi.js

@@ -6,7 +6,7 @@ import { inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, rol
 import { maskToolResults } from "./regenerate/masking.js";
 import { checkAgainstScript, ENVIRONMENT_ERROR_TOOL, EnvironmentError, environmentErrorTool, sandboxGapOf } from "./regenerate/environment-error.js";
 import { MODULES_DIR, projectRootOf, sessionsDir } from "./regenerate/paths.js";
-import { currentStopSignal, describeToolCall, describeToolResult, JobStoppedError, shownName, reportActivity, reportNow, reportAgent, reportTranscript, reportUsage, } from "./regenerate/activity.js";
+import { currentStopSignal, describeToolCall, describeToolResult, JobStoppedError, shownName, reportActivity, reportNow, reportAgent, reportTranscript, reportModelEvent, reportUsage, } from "./regenerate/activity.js";
 import { debugLogOf, startDebugLog } from "./regenerate/debug-log.js";
 let thinkingSource;
 /**
@@ -262,6 +262,7 @@ async function askOnce(session, text, onDelta) {
     transcript({ kind: "prompt", text: task !== undefined ? `${task}\n\n${text}` : text });
     if (agent !== undefined)
         reportAgent({ label: agent.label, ...(agent.model !== undefined ? { model: agent.model } : {}), turns: 1 });
+    reportModelEvent({ kind: "turn", ...modelEventOf(session) });
     const unsubscribe = session.subscribe((event) => {
         if (event.type === "message_update") {
             const update = event.assistantMessageEvent;
@@ -332,6 +333,7 @@ async function askOnce(session, text, onDelta) {
                 reportUsage(spent);
                 if (agent !== undefined)
                     reportAgent({ label: agent.label, usage: spent });
+                reportModelEvent({ kind: "call", ...modelEventOf(session), usage: spent, ms: Date.now() - stepStarted });
             }
             // A provider error counts only if the turn ends on it: a later message that ends well - pi's own retry, the
             // stream picked up again - means it recovered, and the turn's work stands.
@@ -514,6 +516,7 @@ export async function compactIfDue(session) {
     const who = agent?.label ?? "the agent";
     reportActivity(`  compacting ${who}'s work: ${thousands(conversation)} tokens of it, past ${thousands(settings.atTokens)}`);
     try {
+        const compactStarted = Date.now();
         const result = await session.compact(settings.instructions);
         const usage = result.usage;
         if (usage !== undefined) {
@@ -521,7 +524,9 @@ export async function compactIfDue(session) {
             reportUsage(spent);
             if (agent !== undefined)
                 reportAgent({ label: agent.label, usage: spent });
+            reportModelEvent({ kind: "call", ...modelEventOf(session), usage: spent, ms: Date.now() - compactStarted });
         }
+        reportModelEvent({ kind: "compaction", ...modelEventOf(session) });
         if (agent !== undefined)
             reportAgent({ label: agent.label, compactions: 1 });
         reportActivity(`  compacted ${who}'s work${result.estimatedTokensAfter !== undefined ? ` to about ${thousands(result.estimatedTokensAfter)} tokens` : ""}`);
@@ -542,6 +547,13 @@ const agentRoles = new WeakMap();
 function agentOf(session) {
     return agentLabels.get(session);
 }
+/** Who a model event is from: the agent's model as it runs now, its role and its label - an agent with no label too. */
+function modelEventOf(session) {
+    const agent = agentOf(session);
+    const role = agentRoles.get(session);
+    const model = session.model !== undefined ? `${session.model.provider}/${session.model.id}${session.thinkingLevel ? `:${session.thinkingLevel}` : ""}` : agent?.model;
+    return { ...(model !== undefined ? { model } : {}), ...(role !== undefined ? { role } : {}), ...(agent !== undefined ? { label: agent.label } : {}) };
+}
 /**
  * Have this session's turns timed, as an agent a render starts has: `limitMs` each - its role's in the config - or
  * the default.
@@ -700,7 +712,7 @@ export async function createExecutor(opts) {
     if (chosen.model !== undefined) {
         const model = findModel(session, chosen.model);
         if (model === undefined) {
-            throw new Error(`Model '${chosen.model}' is not configured. Check the provider's API key.`);
+            throw new Error(`Model '${chosen.model}' is not a model pi knows: no such id for that provider. \`turri --list-models <search>\` lists the ones it does; one of your own goes in ~/.pi/agent/models.json.`);
         }
         await session.setModel(model);
     }

package/dist/plain/errors.js

@@ -1,4 +1,4 @@
-/** Ports of the exception classes in plain2code_exceptions.py that this parser raises. */
+/** Ports of the exception classes of the Python reference implementation that this parser raises. */
 export class PlainSyntaxError extends Error {
     constructor(message) {
         super(message);

package/dist/plain/files.js

@@ -1,7 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { createEnvironment } from "./liquid.js";
-/** Ports of the file_utils.py and plain2code_utils.py helpers this parser needs. */
+/** Ports of the Python reference implementation's file helpers this parser needs. */
 export function openFrom(dirs, fileName) {
     for (const dir of dirs) {
         const fullPath = join(dir, fileName);

package/dist/plain/liquid.js

@@ -7,7 +7,7 @@ function currentScope() {
 }
 /**
  * Leading indentation of the line the tag sits on, and whether that line is a
- * comment. Ported from Plain2CodeIncludeNode.render_to_output, which walks
+ * comment. Ported from the reference implementation's include node, which walks
  * backwards from the tag to the start of its line.
  */
 function scanLine(source, start) {
@@ -70,7 +70,7 @@ export function createEnvironment(options) {
                     "    2. The directory specified by --template-dir (if provided)\n" +
                     "    3. The built-in 'standard_template_library' directory\n");
             }
-            // Plain2CodeLoaderMixin.load: rstrip, then re-indent every line to match the
+            // The reference implementation's loader: rstrip, then re-indent every line to match the
             // include site. The rstrip is what stops a block-level include from ending
             // the surrounding list.
             const indented = templateSource.replace(/\s+$/, "").split("\n").join("\n" + " ".repeat(whitespaces));

package/dist/regenerate/activity.js

@@ -84,6 +84,25 @@ export function describeUsage(usage) {
     return usage.cost > 0 ? `${size} tok · $${usage.cost.toFixed(2)}` : `${size} tok`;
 }
 const store = new AsyncLocalStorage();
+const modelListeners = new Set();
+/** Hear of every model call, turn and compaction from now on. Returns what stops it. */
+export function onModelEvent(listener) {
+    modelListeners.add(listener);
+    return () => modelListeners.delete(listener);
+}
+export function reportModelEvent(event) {
+    if (modelListeners.size === 0)
+        return;
+    const job = store.getStore()?.job?.id;
+    for (const listener of modelListeners) {
+        try {
+            listener(job !== undefined ? { ...event, job } : event);
+        }
+        catch {
+            /* a listener that fails does not take the agent down */
+        }
+    }
+}
 export function withActivity(sink, run) {
     return store.run(sink, run);
 }

package/dist/regenerate/loop.js

@@ -89,6 +89,61 @@ function chainsFor(plainFile) {
 function ownBuilt(entry) {
     return (readRecord(entry.buildDir)?.[FUNCTIONAL_REQUIREMENTS] ?? []).length;
 }
+/**
+ * The functional specs of a spec's whole requires chain, completed or not, in the codebase each chain delivers: its
+ * furthest-built module's code - which holds the code of every module below it. A functional spec is completed when that
+ * codebase's code record, as last committed, holds it as the spec has it now - the same text, the linked files it uses
+ * holding the same, no definition it uses changed, not marked to regenerate again. A record moves only when a pulse
+ * lands, its unit tests passing (and its conformance tests, when they are on), so completed is landed and passing.
+ * The modules above the delivered codebase have nothing completed. One entry per chain; planning nothing, calling no model.
+ */
+export function functionalityCompletion(plainFile) {
+    return withParseCache(() => chainsFor(resolve(plainFile)).map((chain) => {
+        let delivered = -1;
+        chain.forEach((entry, index) => {
+            if (readRecord(entry.buildDir) !== null)
+                delivered = index;
+        });
+        const counts = chain.map((entry) => ({ module: entry.moduleName, specified: entry.frids.length, completed: 0, conformanceTested: 0, incomplete: [...entry.frids] }));
+        if (delivered === -1)
+            return { codebase: tipOf(chain).buildDir, modules: counts };
+        const codebase = chain.slice(0, delivered + 1);
+        const tip = tipOf(codebase);
+        const spec = chainSpec(codebase).tree;
+        const record = readRecord(tip.buildDir);
+        const changes = codeWork(record, spec);
+        // Its own: what the work loop would regenerate - new, changed, a concept it uses changed, or marked again.
+        const cases = casesOf(codeTree(record ?? {}), changes, { module: tip.moduleName });
+        const touched = new Set([...cases.add, ...cases.patch, ...cases.again].map((spec) => `${spec.module ?? tip.moduleName}:${spec.frid}`));
+        // The modules' below it: an item the record does not have as the spec has it.
+        for (const change of changes) {
+            if (change.section !== REQUIRED_FUNCTIONAL_SPECS || change.after === undefined)
+                continue;
+            try {
+                const item = JSON.parse(change.after);
+                if (item.module !== undefined && item.frid !== undefined)
+                    touched.add(`${item.module}:${item.frid}`);
+            }
+            catch {
+                /* not an item */
+            }
+        }
+        const specText = (module, frid) => {
+            const own = module === tip.moduleName;
+            const items = spec[own ? FUNCTIONAL_REQUIREMENTS : REQUIRED_FUNCTIONAL_SPECS] ?? [];
+            return (own ? items[Number(frid) - 1] : items.find((item) => item.module === module && item.frid === frid))?.markdown.trim();
+        };
+        codebase.forEach((entry, index) => {
+            const count = counts[index];
+            const completed = entry.frids.filter((frid) => !touched.has(`${entry.moduleName}:${frid}`));
+            const tested = (readRecord(conformanceDirFor(entry.moduleName, modulesRoot(projectDirOf(entry.plainFile))))?.[FUNCTIONAL_REQUIREMENTS] ?? []).filter((item) => item.frid !== undefined && item.markdown.trim() === specText(entry.moduleName, item.frid));
+            count.completed = completed.length;
+            count.conformanceTested = completed.filter((frid) => tested.some((item) => item.frid === frid)).length;
+            count.incomplete = entry.frids.filter((frid) => !completed.includes(frid));
+        });
+        return { codebase: tip.buildDir, modules: counts };
+    }));
+}
 /** The modules of a chain to build: its furthest-built one, and those above it - or, none built, all of it. */
 function toBuild(chain) {
     let from = 0;
@@ -434,7 +489,7 @@ export function createWorkLoop(options) {
             title: planned.title,
             diff: shown.diff,
             ...(state.model !== undefined ? { model: state.model } : {}),
-            lanes: [...moduleLanes(tip.plainFile, options.buildDir)],
+            lanes: [...moduleLanes(tip.plainFile)],
             rerun: `turri regenerate ${relative(options.cwd, tip.plainFile) || basename(tip.plainFile)}`,
             run: async (onDelta) => {
                 // The guardrail: a conformance job tests only code that is built - the code record, read as the job starts, has every functional spec it tests as it tests it.
@@ -1313,7 +1368,6 @@ export async function previewJobs(options) {
         registry: createJobRegistry(),
         cwd: options.cwd,
         dryRun: true,
-        ...(options.buildDir !== undefined ? { buildDir: options.buildDir } : {}),
         ...(options.model !== undefined ? { modelFor: () => options.model } : {}),
         ...(options.plannerModel !== undefined ? { plannerModel: options.plannerModel } : {}),
         ...(options.steering !== undefined ? { steering: options.steering } : {}),

package/dist/regenerate/prompt.js

@@ -24,7 +24,7 @@ function alreadyImplemented(moduleName, own, required) {
  * one another, the current module marked - and each tagged with its module and its id there. A codebase holds the
  * functionalities of every module it is built on, and each module numbers its own from 1, so
  * "functionality 1" alone is ambiguous: the first listed may be base's 1 and the next top's 3.
- * (plain2code's _get_implemented_functional_requirements_prompt_section, as tags.)
+ * (the reference implementation's implemented functional requirements prompt section, as tags.)
  */
 export function functionalitiesByModule(entries, currentModule, status) {
     // In the order given: the bottom of the chain first. A regeneration in a later module's