@turri-dev/cli 0.1.27-next.763d091 → 0.1.28-next.d5f2680

package/README.md

@@ -151,14 +151,14 @@ Then say what you want:
 
 > A small API where people can register and sign in, in Python.
 
-In a new project **turri** starts it itself, without asking how: it chooses the stack - the one you name, else a standard library stack this machine can build - writes the module and its unit testing script (and the conformance tests' when you ask for them), regenerates the smallest thing that runs at once, then the main thing you described, and says what it chose and what it would write next. Every change after is yours to ask for: **turri** writes it as \*\*\*plain and regenerates it. While it works:
+In a new project **turri** starts it itself, without asking how: it chooses the stack - the one you name, else a standard library stack this machine can build - writes the module and its unit testing script (and the conformance tests' when you ask for them, or the [test advisor](docs/test-advisor.md) finds a functional spec that needs them), regenerates the smallest thing that runs at once, then the main thing you described, and says what it chose and what it would write next. Every change after is yours to ask for: **turri** writes it as \*\*\*plain and regenerates it. While it works:
 
 - the **panel** above the input shows every build - its stage, what its agents are doing, its model and cost - and the queue behind it;
 - ask to try it at any time - "let me try it" - and **`release`** puts what is built so far in `dist/<module>` and **`activate`** starts it, installing what it needs - nothing to approve;
 - the **side panel** (`ctrl+h`) takes the screen and opens on **regen** - \*\*\*plain, every item marked planned, working, regenerated, validating, conform or needs you - and `p` turns it to the **pulses** (`/pulses`) - every pulse, running, queued and finished, and what each regenerates; what its agents did is in each pulse's log in `.turri/jobs/`, kept with `--debug` (`debug: true`);
 - **`/halt`** halts a pulse, **`/lineage`** shows every generation of a module, and the **`drift`** tool says what is left to regenerate;
 - **`/btw <question>`** asks turri something on the side - answered at once, even while a question waits for you (typed as the answer, under "Something else…"), and left out of the conversation;
-- **`/turri-config`** changes any setting of the project's `config.turri.yaml` - the models, review, conformance tests, how many pulses at once - and says when it takes effect: now, at your next message, or at the next pulse. No restart: `/turri-config review false`, or `/turri-config` alone to pick from the list;
+- **`/turri-config`** changes any setting of the project's `config.turri.yaml` - the models, review, the test advisor, how many pulses at once - and says when it takes effect: now, at your next message, or at the next pulse. No restart: `/turri-config review false`, or `/turri-config` alone to pick from the list;
 - **`/sentinel`** says whether the sentinel checks every pulse that finishes: `ask` (you are asked before it first opens), `on` or `off`;
 - **`/stack`** chooses the stack to build with, in a project whose backend and frontend each have their own testing scripts in `config.turri.<stack>.yaml` - `/stack backend`, `/stack none` - for the session (`--stack <name>` on the command line). The chat's model builds each part with its own stack by itself, pinned to that module's pulses.
 
@@ -175,10 +175,10 @@ The last one holds for the rest of the session; the model can be chosen separate
 Without a conversation, the same work is on the command line:
 
 ```bash
-turri validate app.plain    # validate ***plain - no model, no API key
+turri parse app.plain    # parse ***plain, its syntax and structure - no model, no API key
 turri drift app.plain       # what is left to regenerate - starts nothing
 turri regenerate app.plain      # regenerate the code from ***plain: planned into jobs, run until it is done
-turri regenerate app.plain 3    # regenerate functionality 3, changed or not
+turri regenerate app.plain app:add-task    # regenerate one functional spec again, changed or not
 ```
 
 More: [using **turri**](docs/using.md); to regenerate \*\*\*plain overnight, see [running unattended](docs/headless.md).
@@ -190,7 +190,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | | |
 | --- | --- |
 | [Installation](docs/installation.md) | doctor, what turri needs of this machine, **turri** and `pi`, environment variables |
-| [Examples](examples/README.md) | projects to build with turri step by step: guestbook - a backend and a frontend in minutes - a CLI, and a backend service with conformance tests |
+| [Examples](examples/README.md) | projects to build with turri step by step: guestbook - a backend and a frontend in minutes - a CLI, and a backend service tested where it matters |
 | [Using **turri**](docs/using.md) | the conversation, skills, tools, pulses and regen, choosing models, the command line |
 | [The project config](docs/config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](docs/deploy.md) | trying what is built: the last commit in `dist/<module>`, started on your machine, nothing installed without asking |
@@ -199,7 +199,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | [Regenerating](docs/regenerating.md) | what each build does and in which order: functionalities, modules, regeneration, changes to \*\*\*plain, conformance and acceptance tests, working notes, what the code is built from |
 | [The sandbox](docs/sandbox.md) | what agents can reach, the walls every command passes, time limits, the web tools |
 | [Skills and gates](docs/skills-and-gates.md) | the gate syntax, what the harness enforces, judges, rules |
-| [The \*\*\*plain parser](docs/parser.md) | the TypeScript port, `turri validate`, fidelity to the reference parser |
+| [The \*\*\*plain parser](docs/parser.md) | the TypeScript port, `turri parse`, fidelity to the reference parser |
 | [Theming](docs/theming.md) | the two brand themes |
 | [Development](docs/development.md) | tests, layout, known edges |
 

package/dist/advisor-chat.d.ts

@@ -0,0 +1,63 @@
+import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ChatLink } from "./chats.ts";
+import type { AdvisorVerdict, TestAdvisor } from "./regenerate/advisor-runs.ts";
+import type { WorkLoop } from "./regenerate/loop.ts";
+/** The line a no is drawn as: the functional spec, and the classifier's reading in a few words - a no has no evidence. */
+export declare function noLine(verdict: AdvisorVerdict): string;
+/** The line the chat is to tell the person a yes in. */
+export declare function yesLine(verdict: AdvisorVerdict): string;
+/** A yes's report, as the chat's agent is given it: the questions that were a yes with their evidence, and the inputs. */
+export declare function describeReport(verdict: AdvisorVerdict): string[];
+/** The turn a batch of yeses starts: each one's report, and what the chat is to do with them - asking the person nothing. */
+export declare function yesTask(verdicts: AdvisorVerdict[]): string;
+/** How long a verdict waits before the chat is looked at again, while the person types or it cannot be told yet. */
+export declare const ADVISOR_RECHECK_MS = 2000;
+/**
+ * A chat's verdicts: held until the chat is idle - its agent done, and nothing typed in its editor - then delivered
+ * together: one turn for every yes, one line for each no. A verdict no longer about its functional spec as it is - its
+ * text changed, or it was given scenarios meanwhile - is let go.
+ */
+export declare function verdictDelivery(pi: ExtensionAPI, link: ChatLink, context: () => ExtensionContext | undefined): {
+    put(verdict: AdvisorVerdict): void;
+};
+/**
+ * The test advisor and the chat, in its system prompt while the session has the advisor and the project wants it: the
+ * two ways an evaluation starts, what to say while it runs, what to do with its verdict, and when to ask for one.
+ */
+export declare const TEST_ADVISOR_BLOCK: string;
+/** The test advisor of the session a work loop is in. */
+export declare function bindAdvisor(loop: WorkLoop, advisor: () => TestAdvisor | undefined): void;
+/**
+ * What a change's tool result tells the chat's agent of the test advisor: the functional specs it has taken up, so the
+ * agent tells the person they are being evaluated - nothing when it has taken up none.
+ */
+export declare function advisingNote(loop: WorkLoop, plainFile: string): string;
+/** What an evaluation asked for came to, by functional spec - each named `module:func-id`, a missing one with why. */
+export interface EvaluateOutcome {
+    /** Being evaluated now: the verdict comes to the chat the person looks at. */
+    started: string[];
+    /** Being evaluated already. */
+    already: string[];
+    /** With scenarios already: not evaluated. */
+    scenarios: string[];
+    /** Not found, with why. */
+    missing: string[];
+}
+/**
+ * The test advisor asked to evaluate functional specs - `module:func-id`s, or func-ids of `plainFile`'s module (else the
+ * one the project's config names) - even a text it judged already, and whatever `test-advisor` says: `evaluate_tests`'s
+ * and a host's `evaluateTests`. It returns at once.
+ */
+export declare function evaluateTests(cwd: string, advisor: TestAdvisor | undefined, funcIds: string[], options?: {
+    plainFile?: string;
+    reason?: string;
+}): EvaluateOutcome;
+/**
+ * evaluate_tests: the chat's own way to the test advisor - a functional spec evaluated in the background, whatever
+ * `test-advisor` says, and even when its text was judged already. It returns at once; the verdict comes back to the chat
+ * as the advisor's verdicts do. In the chat and a host only: the session has an advisor.
+ */
+export declare function evaluateTestsTool(options: {
+    cwd: string;
+    advisor: () => TestAdvisor | undefined;
+}): ToolDefinition;

package/dist/advisor-chat.js

@@ -0,0 +1,290 @@
+import { existsSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { chatBusy } from "./chat-idle.js";
+import { conformanceTestsOnIn } from "./conformance-switch.js";
+import { readProjectConfig } from "./config.js";
+import { modulePlainFile } from "./plain/parser.js";
+import { projectDirOf, resolveTemplateDirs } from "./regenerate/paths.js";
+import { resolveRequiresChain } from "./regenerate/requires.js";
+import { refuseTestPlainFile } from "./test-plain-files.js";
+/**
+ * The test advisor in the chat (docs/test-advisor.md). The advisor decides; the chat is the only writer of the ***plain.
+ * A finished verdict reaches the chat the person looks at once it is idle - never interrupting it: a yes is a message
+ * that starts a turn, in which the chat tells the person and writes the scenarios with change_plain, asking nothing; a
+ * no is one line drawn by turri, starting no turn. What else the chat is told of the advisor - in its system prompt, in a
+ * change's result - is here too, and its own way to it, evaluate_tests.
+ */
+/** Why, in a few words, by the first question of a yes. */
+const WHY = {
+    "silent-failure": "a wrong implementation could look right",
+    divergence: "it can be read two ways",
+    cost: "a bug in it would be costly",
+};
+const specOf = (verdict) => `${verdict.module}:${verdict.funcId}`;
+/** The line a no is drawn as: the functional spec, and the classifier's reading in a few words - a no has no evidence. */
+export function noLine(verdict) {
+    const only = verdict.report.questions.map((answered) => answered.question);
+    const reading = only.length > 0 && only.every((question) => question === "revisited") ? "its unit tests cover it as it is built on" : "nothing silent to get wrong";
+    return `${specOf(verdict)} doesn't need testing scenarios - ${reading}.`;
+}
+/** The line the chat is to tell the person a yes in. */
+export function yesLine(verdict) {
+    const why = verdict.report.questions.map((answered) => WHY[answered.question]).find((reason) => reason !== undefined);
+    return `${specOf(verdict)} needs testing scenarios${why !== undefined ? ` - ${why}` : ""}. Writing them now.`;
+}
+/** A yes's report, as the chat's agent is given it: the questions that were a yes with their evidence, and the inputs. */
+export function describeReport(verdict) {
+    return [
+        "Why it needs testing:",
+        ...verdict.report.questions.map((answered) => `- ${answered.question}: ${answered.evidence}`),
+        "Inputs to cover:",
+        ...(verdict.report.inputs.length === 0
+            ? ["- none picked: cover its expected use, as the rules on test plain files say"]
+            : verdict.report.inputs.map((input, index) => "agreed" in input
+                ? `${index + 1}. input: ${input.input} - agreed output: ${input.agreed}`
+                : `${index + 1}. input: ${input.input} - split: ${input.readings.map((reading, at) => `(${at + 1}) ${reading}`).join("; ")}`)),
+    ];
+}
+/** The turn a batch of yeses starts: each one's report, and what the chat is to do with them - asking the person nothing. */
+export function yesTask(verdicts) {
+    const where = (path, project) => relative(project, path) || path;
+    return [
+        `My test advisor judged that ${verdicts.length === 1 ? "this functional spec needs" : "these functional specs need"} explicit testing scenarios. You write them now.`,
+        "",
+        ...verdicts.flatMap((verdict) => [
+            `<functional_spec name="${specOf(verdict)}" plain_file="${where(verdict.plainFile, verdict.project)}" tested_in="${where(verdict.tip, verdict.project)}" test_plain_file="${verdict.testFile}">`,
+            ...describeReport(verdict),
+            "</functional_spec>",
+            "",
+        ]),
+        "What to do, in this turn, asking the person nothing:",
+        `1. Tell the person in a line for each, e.g. "${yesLine(verdicts[0])}"`,
+        "2. With change_plain, write whatever the step-7 guard would refuse, in this order, only what is missing: the ***test reqs*** of the module",
+        "   it is tested in - the stack's conformance template, stdlib/<kind>/conformance/<stack>, imported, or the module's own - then the",
+        "   conformance testing script for its stack, with implement-conformance-testing-script - cultivate, plainFile the module it is tested in,",
+        "   which returns at once: go straight on - then the scenarios in its test plain file.",
+        "3. Cover each input of the report that is this functional spec's: an agreed one with the readers' output, never a placeholder such as",
+        "   <name> where a value belongs; a split one settled by the reading most consistent with the functional spec and its module - say which",
+        "   reading you took. Leave out an input that exercises another functional spec, or nothing this one says.",
+        "4. Ask the person nothing: the change is visible, and turri tests the scenarios once the code is built.",
+    ].join("\n");
+}
+/** The line a no is drawn as, in the transcript and in no model's context. */
+const ADVISOR_ENTRY = "turri_advisor";
+/** How long a verdict waits before the chat is looked at again, while the person types or it cannot be told yet. */
+export const ADVISOR_RECHECK_MS = 2000;
+/**
+ * A chat's verdicts: held until the chat is idle - its agent done, and nothing typed in its editor - then delivered
+ * together: one turn for every yes, one line for each no. A verdict no longer about its functional spec as it is - its
+ * text changed, or it was given scenarios meanwhile - is let go.
+ */
+export function verdictDelivery(pi, link, context) {
+    const waiting = [];
+    let timer;
+    pi.registerEntryRenderer(ADVISOR_ENTRY, (entry, _options, theme) => {
+        const data = entry.data;
+        if (data === undefined)
+            return undefined;
+        const box = new Box(1, 0);
+        box.addChild(new Text(theme.fg("muted", data.text), 0, 0));
+        return box;
+    });
+    const busy = () => chatBusy(link, context);
+    const later = (ms) => {
+        if (timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            deliver();
+        }, ms);
+        timer.unref?.();
+    };
+    const deliver = () => {
+        if (waiting.length === 0)
+            return;
+        if (busy()) {
+            // Its agent ending says so (agent_settled); the person's typing does not, so it is looked at again.
+            later(ADVISOR_RECHECK_MS);
+            return;
+        }
+        const now = waiting.splice(0).filter((verdict) => {
+            try {
+                return verdict.current();
+            }
+            catch {
+                return false;
+            }
+        });
+        const yes = now.filter((verdict) => verdict.report.verdict === "yes");
+        try {
+            for (const verdict of now.filter((verdict) => verdict.report.verdict === "no"))
+                pi.appendEntry(ADVISOR_ENTRY, { text: noLine(verdict) });
+            if (yes.length > 0) {
+                // A follow-up, never a steer: should a turn start in between, this waits for it to end.
+                void pi.sendMessage({ customType: "turri_advisor_verdict", content: yesTask(yes), display: false, details: { specs: yes.map(specOf) } }, { triggerTurn: true, deliverAs: "followUp" });
+            }
+        }
+        catch {
+            // Not bound to its session yet: kept, and tried again.
+            waiting.unshift(...now);
+            later(ADVISOR_RECHECK_MS);
+            return;
+        }
+        for (const verdict of now)
+            verdict.delivered();
+    };
+    pi.on("agent_settled", () => deliver());
+    pi.on("session_start", () => later(0));
+    return {
+        put(verdict) {
+            // A newer verdict on the same functional spec replaces the one waiting.
+            const at = waiting.findIndex((known) => known.project === verdict.project && specOf(known) === specOf(verdict));
+            if (at !== -1)
+                waiting.splice(at, 1);
+            waiting.push(verdict);
+            // The rest of what arrives at once comes with it.
+            later(0);
+        },
+    };
+}
+/**
+ * The test advisor and the chat, in its system prompt while the session has the advisor and the project wants it: the
+ * two ways an evaluation starts, what to say while it runs, what to do with its verdict, and when to ask for one.
+ */
+export const TEST_ADVISOR_BLOCK = [
+    "<test advisor>",
+    "My test advisor decides whether a functional spec needs explicit testing scenarios - whether it could fail silently, be read two ways, or",
+    "cost a lot when wrong - in the background. You are the only writer of the ***plain: it writes nothing, and you write what its yes calls for.",
+    "An evaluation starts two ways:",
+    "- By itself, for each new or changed functional spec that has no scenarios. A change's result names the ones it took up.",
+    "- When you call evaluate_tests - even for a text it judged already. Call it when the person asks whether a functional spec needs tests,",
+    "  and on your own, as another way of saying what one means: when pulses keep failing on a complicated functional spec, scenarios may pin",
+    "  down what it should do - say why in its reason. A functional spec with scenarios is not evaluated.",
+    "When a change's result or evaluate_tests says a functional spec is being evaluated, tell the person so in a line, and go on: nothing waits",
+    "for it. Its verdict comes back to this chat once you are idle:",
+    "- A yes is a message with its report: tell the person in a line, then write with change_plain what testing it needs - the test reqs, the",
+    "  conformance testing script and its scenarios, in that order and only what is missing - as the message says, asking the person nothing.",
+    "- A no is a line turri draws itself: there is nothing for you to do.",
+    "When the person asks you for scenarios (\"write conformance scenarios for core:add-task\"), decide and write them yourself, with change_plain,",
+    "as a ***plain change they see, as the rules say - whatever test-advisor says.",
+    "</test advisor>",
+].join("\n");
+/** Each work loop's session's test advisor - the chat's and a host's loops have one. */
+const advisorsOfLoops = new WeakMap();
+/** The test advisor of the session a work loop is in. */
+export function bindAdvisor(loop, advisor) {
+    advisorsOfLoops.set(loop, advisor);
+}
+/**
+ * What a change's tool result tells the chat's agent of the test advisor: the functional specs it has taken up, so the
+ * agent tells the person they are being evaluated - nothing when it has taken up none.
+ */
+export function advisingNote(loop, plainFile) {
+    const taking = advisorsOfLoops.get(loop)?.()?.taking(projectDirOf(resolve(plainFile))) ?? [];
+    if (taking.length === 0)
+        return "";
+    return [
+        `My test advisor is evaluating ${taking.join(", ")} in the background, to see whether ${taking.length === 1 ? "it needs" : "they need"} explicit testing scenarios.`,
+        "Tell the person, in a line, that testing scenarios are being evaluated for them, and go on - there is nothing to wait for: the verdict",
+        "comes back to this chat.",
+    ].join("\n");
+}
+/** The functional specs evaluate_tests is given, each as the advisor is asked for it - or, not found, why. */
+function namedSpecs(cwd, names, plainFile) {
+    const named = plainFile ?? readProjectConfig(cwd).module;
+    const base = named !== undefined ? resolve(cwd, named) : undefined;
+    if (base !== undefined)
+        refuseTestPlainFile(base);
+    if (base !== undefined && !existsSync(base))
+        throw new Error(`There is no .plain file at ${base}.`);
+    const chain = (() => {
+        try {
+            return base !== undefined ? resolveRequiresChain(base, [], undefined, { allowNoFunctionalities: true }) : [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    return names.map((given) => {
+        const name = given.trim();
+        const at = name.lastIndexOf(":");
+        if (at === -1 && base === undefined)
+            return { name, missing: `name it as module:func-id - there is no plain_file, and no module: in the project's config` };
+        const module = at === -1 ? basename(base, ".plain") : name.slice(0, at);
+        const funcId = at === -1 ? name : name.slice(at + 1);
+        const own = chain.find((link) => link.moduleName === module)?.plainFile ?? modulePlainFile(module, resolveTemplateDirs(base ?? join(cwd, `${module}.plain`)));
+        if (own === null || own === undefined || !existsSync(own))
+            return { name: `${module}:${funcId}`, missing: `there is no module ${module} here` };
+        // A module below the one named: its scenarios are tested in the one named, at the top of the chain.
+        const tip = base !== undefined && chain.some((link) => link.moduleName === module) && resolve(own) !== resolve(base) ? { tip: base } : {};
+        return { name: `${module}:${funcId}`, asked: { module, funcId, plainFile: resolve(own), ...tip } };
+    });
+}
+/**
+ * The test advisor asked to evaluate functional specs - `module:func-id`s, or func-ids of `plainFile`'s module (else the
+ * one the project's config names) - even a text it judged already, and whatever `test-advisor` says: `evaluate_tests`'s
+ * and a host's `evaluateTests`. It returns at once.
+ */
+export function evaluateTests(cwd, advisor, funcIds, options = {}) {
+    if (advisor === undefined)
+        throw new Error("This session has no test advisor: it runs in the chat and a host only.");
+    if (!conformanceTestsOnIn(cwd)) {
+        throw new Error("Conformance tests are off for this project (conformance-tests: false, or unset), and the test advisor with them. They are turned on in the chat - by asking for them - or with conformance-tests: true in config.turri.yaml.");
+    }
+    if (funcIds.length === 0)
+        throw new Error("Name the functional specs to evaluate, each as module:func-id.");
+    const said = { started: [], already: [], scenarios: [], missing: [] };
+    for (const spec of namedSpecs(cwd, funcIds, options.plainFile)) {
+        if (spec.asked === undefined) {
+            said.missing.push(`${spec.name}: ${spec.missing}`);
+            continue;
+        }
+        const outcome = advisor.evaluate({ ...spec.asked, ...(options.reason !== undefined ? { reason: options.reason } : {}) });
+        if (outcome === "missing")
+            said.missing.push(`${spec.name}: its module has no such functional spec`);
+        else
+            said[outcome].push(spec.name);
+    }
+    return said;
+}
+/**
+ * evaluate_tests: the chat's own way to the test advisor - a functional spec evaluated in the background, whatever
+ * `test-advisor` says, and even when its text was judged already. It returns at once; the verdict comes back to the chat
+ * as the advisor's verdicts do. In the chat and a host only: the session has an advisor.
+ */
+export function evaluateTestsTool(options) {
+    return defineTool({
+        name: "evaluate_tests",
+        label: "Evaluate tests",
+        description: "Have turri's test advisor evaluate, in the background, whether functional specs need explicit testing scenarios - even one it judged " +
+            "already, and whatever test-advisor says. It returns at once; the verdict comes back to this chat: a yes as a message to write the " +
+            "scenarios on, a no as a line. A functional spec that has scenarios is not evaluated.",
+        promptSnippet: "evaluate_tests: have the test advisor judge whether functional specs need testing scenarios, in the background",
+        promptGuidelines: [
+            "Call evaluate_tests when the person asks whether a functional spec needs tests (\"does add-task need tests?\"), rather than judging it yourself.",
+            "Call it on your own too, as another way of saying what a functional spec means: when pulses keep failing on a complicated functional spec, scenarios may pin down what it should do - say so in reason.",
+            "It returns at once: tell the person testing scenarios are being evaluated, and go on. On a yes, write the scenarios as the verdict's message says.",
+        ],
+        parameters: Type.Object({
+            funcIds: Type.Array(Type.String(), { description: "The functional specs, each as module:func-id (core:add-task) - or a func-id alone, of plain_file's module" }),
+            plain_file: Type.Optional(Type.String({ description: "The .plain file a func-id alone is of, and whose chain the scenarios are tested in. Omitted: the module the project's config.turri.yaml names" })),
+            reason: Type.Optional(Type.String({ description: "Why you ask, for the advisor to weigh: \"the coding agent failed three times to implement it\"" })),
+        }),
+        async execute(_id, params) {
+            const said = evaluateTests(options.cwd, options.advisor(), params.funcIds, { ...(params.plain_file !== undefined ? { plainFile: params.plain_file } : {}), ...(params.reason !== undefined ? { reason: params.reason } : {}) });
+            const list = (names) => names.join(", ");
+            const one = (names, single, many) => (names.length === 1 ? single : many);
+            const text = [
+                ...(said.started.length > 0 ? [`Testing scenarios for ${list(said.started)} are being evaluated in the background; the verdict comes back to this chat.`] : []),
+                ...(said.already.length > 0 ? [`${list(said.already)} ${one(said.already, "is", "are")} being evaluated already; the verdict comes back to this chat.`] : []),
+                ...(said.scenarios.length > 0 ? [`${list(said.scenarios)} ${one(said.scenarios, "has", "have")} scenarios already, so ${one(said.scenarios, "it is", "they are")} not evaluated: tested as the scenarios say.`] : []),
+                ...(said.missing.length > 0 ? [`Not evaluated - ${said.missing.join("; ")}.`] : []),
+                ...(said.started.length + said.already.length > 0 ? ["Tell the person so in a line, and go on: there is nothing to wait for."] : []),
+            ].join("\n");
+            return { content: [{ type: "text", text }], details: said };
+        },
+    });
+}

package/dist/background-skills.d.ts

@@ -0,0 +1,53 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ChatLink } from "./chats.ts";
+import type { ScriptKind } from "./regenerate/test-scripts.ts";
+/**
+ * A skill that runs in the background (`metadata.background: true`, docs/skills-and-gates.md): in the chat, cultivate
+ * starts it and returns at once, nothing shows while it runs, and nobody is asked anything. Its end comes back to the
+ * chat it was started from once that chat is idle - never interrupting it: one line drawn by turri when it did its work,
+ * a message that starts a turn when it did not, for the chat to tell the person and decide what next.
+ */
+/** How a background run ended, for the chat it was started from. */
+export interface SkillRunEnd {
+    skill: string;
+    /** It did its work: a line, starting no turn. */
+    ok: boolean;
+    /** The line it is drawn as. */
+    line: string;
+    /** When it did not do its work: what the chat's agent is told, in a turn of its own. */
+    task?: string;
+    /** The testing script it writes, when it writes one. */
+    kind?: ScriptKind;
+    /** The module it is for, relative to the project, when it was given one. */
+    plainFile?: string;
+}
+/**
+ * What a host is told of a background run, besides its skill: the testing script it writes and the module it is for,
+ * each when there is one - in cultivate's result as it starts, and in the message a run that did not do its work sends.
+ */
+export declare function runDetails(kind: ScriptKind | undefined, plainFile: string | undefined): {
+    kind?: ScriptKind;
+    plainFile?: string;
+};
+/** What the agent of a background run is told, besides what the chat passed on. */
+export declare const BACKGROUND_NOTE: string;
+/** What cultivate says as it starts a background run. */
+export declare function startedText(skill: string, options: {
+    model?: string;
+    plainFile?: string;
+    kind?: ScriptKind;
+}): string;
+/**
+ * What a background run changed of the files that changed in the project while it ran: the chat goes on meanwhile, and
+ * what it writes - its ***plain, its test plain files - is not the run's. A run that writes a testing script changes
+ * the script, a prepare script beside a conformance one, and a config file naming them; any other run, all of them.
+ */
+export declare function ownChanges(changed: string[], kind?: ScriptKind): string[];
+/** The line a background run that did its work is drawn as. */
+export declare function doneLine(skill: string, changed: string[], kind?: ScriptKind): string;
+/** What the chat's agent is told when a background run did not do its work: why, and what is left to it. */
+export declare function failedTask(skill: string, why: string, output: string | undefined, kind?: ScriptKind): string;
+/** A chat's background runs' ends: held until it is idle - its agent done, nothing typed - then told together. */
+export declare function skillRunDelivery(pi: ExtensionAPI, link: ChatLink, context: () => ExtensionContext | undefined): {
+    put(end: SkillRunEnd): void;
+};

package/dist/background-skills.js

@@ -0,0 +1,121 @@
+import { Box, Text } from "@earendil-works/pi-tui";
+import { chatBusy } from "./chat-idle.js";
+/**
+ * What a host is told of a background run, besides its skill: the testing script it writes and the module it is for,
+ * each when there is one - in cultivate's result as it starts, and in the message a run that did not do its work sends.
+ */
+export function runDetails(kind, plainFile) {
+    return { ...(kind !== undefined ? { kind } : {}), ...(plainFile !== undefined ? { plainFile } : {}) };
+}
+/** What the agent of a background run is told, besides what the chat passed on. */
+export const BACKGROUND_NOTE = "You run in the background: nobody can be asked anything, and nobody watches. Where the module's stack, its ***plain and the project " +
+    "leave something open, decide it - the reading most consistent with them - and say what you decided in your result. If what you are " +
+    "to make cannot be told at all - no language, no test framework to go by - write nothing, and say why.";
+const WHAT = { unit: "unit testing script", conformance: "conformance testing script" };
+/** What cultivate says as it starts a background run. */
+export function startedText(skill, options) {
+    const what = options.kind !== undefined ? `the ${WHAT[options.kind]}${options.plainFile !== undefined ? ` for ${options.plainFile}` : ""}` : "its work";
+    return [
+        `${skill} is writing ${what} in the background${options.model !== undefined ? `, on ${options.model}` : ""}. What it did comes back to this chat when it ends.`,
+        "Do not wait for it, and do not tell the person to: go on with the turn.",
+        ...(options.kind !== undefined
+            ? [
+                options.kind === "unit"
+                    ? "Regenerate now if there is more to do: a module's pulses wait for its unit testing script while it is written, and start once it is."
+                    : "Write the scenarios now if they are next: the module's conformance tests wait for the script while it is written, and are written once it is.",
+            ]
+            : []),
+    ].join("\n");
+}
+/**
+ * What a background run changed of the files that changed in the project while it ran: the chat goes on meanwhile, and
+ * what it writes - its ***plain, its test plain files - is not the run's. A run that writes a testing script changes
+ * the script, a prepare script beside a conformance one, and a config file naming them; any other run, all of them.
+ */
+export function ownChanges(changed, kind) {
+    if (kind === undefined)
+        return changed;
+    const scripts = kind === "unit" ? ["run_unittests"] : ["run_conformance_tests", "prepare_environment"];
+    const name = (path) => path.split("/").at(-1) ?? path;
+    return changed.filter((path) => scripts.some((script) => name(path).startsWith(script)) || /^config(\.turri)?(\.[^.]+)?\.yaml$/.test(name(path)));
+}
+/** The line a background run that did its work is drawn as. */
+export function doneLine(skill, changed, kind) {
+    const files = changed.join(", ");
+    if (kind === undefined)
+        return `${skill} finished in the background: ${files}.`;
+    const what = WHAT[kind];
+    return `${what.charAt(0).toUpperCase()}${what.slice(1)} written: ${files}.`;
+}
+/** What the chat's agent is told when a background run did not do its work: why, and what is left to it. */
+export function failedTask(skill, why, output, kind) {
+    return [
+        `${skill}, which you started in the background, ${why}.`,
+        "",
+        ...(output !== undefined && output.trim() !== "" ? ["<artifact>", output.trim(), "</artifact>", ""] : []),
+        "Tell the person in a line or two what went wrong" +
+            (kind === undefined
+                ? "."
+                : kind === "unit"
+                    ? ", and that the module's pulses cannot be built until it has a unit testing script."
+                    : ", and that the module's conformance tests cannot be written until it has a conformance testing script."),
+        "Start it again with cultivate only when you can change what went wrong - the context you pass it, the module it is for; otherwise say what the person can do. Ask the person nothing.",
+    ].join("\n");
+}
+/** The line drawn for a background run, in the transcript and in no model's context. */
+const SKILL_RUN_ENTRY = "turri_skill_run";
+/** How long an end waits before the chat is looked at again, while the person types or it cannot be told yet. */
+const RECHECK_MS = 2000;
+/** A chat's background runs' ends: held until it is idle - its agent done, nothing typed - then told together. */
+export function skillRunDelivery(pi, link, context) {
+    const waiting = [];
+    let timer;
+    pi.registerEntryRenderer(SKILL_RUN_ENTRY, (entry, _options, theme) => {
+        const data = entry.data;
+        if (data === undefined)
+            return undefined;
+        const box = new Box(1, 0);
+        box.addChild(new Text(theme.fg("muted", data.text), 0, 0));
+        return box;
+    });
+    const later = (ms) => {
+        if (timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            deliver();
+        }, ms);
+        timer.unref?.();
+    };
+    const deliver = () => {
+        if (waiting.length === 0)
+            return;
+        if (chatBusy(link, context)) {
+            later(RECHECK_MS);
+            return;
+        }
+        const now = waiting.splice(0);
+        const failed = now.filter((end) => !end.ok && end.task !== undefined);
+        try {
+            for (const end of now.filter((end) => end.ok))
+                pi.appendEntry(SKILL_RUN_ENTRY, { text: end.line });
+            if (failed.length > 0) {
+                // A follow-up, never a steer: should a turn start in between, this waits for it to end.
+                void pi.sendMessage({ customType: SKILL_RUN_ENTRY, content: failed.map((end) => end.task).join("\n\n---\n\n"), display: false, details: { skills: failed.map((end) => end.skill), runs: failed.map((end) => ({ skill: end.skill, ...runDetails(end.kind, end.plainFile) })) } }, { triggerTurn: true, deliverAs: "followUp" });
+            }
+        }
+        catch {
+            // Not bound to its session yet: kept, and tried again.
+            waiting.unshift(...now);
+            later(RECHECK_MS);
+        }
+    };
+    pi.on("agent_settled", () => deliver());
+    pi.on("session_start", () => later(0));
+    return {
+        put(end) {
+            waiting.push(end);
+            later(0);
+        },
+    };
+}

package/dist/bedrock-region.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The AWS region turri's Bedrock models are called in. pi calls Bedrock in AWS_REGION, else AWS_DEFAULT_REGION, else -
+ * with an AWS_PROFILE - the profile's region, else the region of the model's endpoint in its catalogue, us-east-1
+ * (pi-ai's bedrock-converse-stream.js). A model served in a geography that needs a region of its own - eu, jp, au, apac,
+ * in, ca, us-gov - answers only when it is called in a region of that geography, so turri sets AWS_REGION itself, in
+ * its own process, before any model is called: the terminal's chat, every command and a host's session alike. A region
+ * the person set is never touched. The environment is the lever: pi's per-call `region` is not reachable from the
+ * sessions pi makes itself - the chat's - so one region serves every model, and models that need two are said, not
+ * guessed between.
+ */
+/** Where the region pi calls Bedrock in comes from. */
+export type BedrockRegionSource = 
+/** AWS_REGION or AWS_DEFAULT_REGION, set by the person. */
+"set"
+/** AWS_REGION, set by turri for the geography the models need. */
+ | "turri"
+/** The region of the AWS_PROFILE's profile. */
+ | "profile"
+/** Nothing names one: pi's default, us-east-1. */
+ | "default";
+/** What turri does about the AWS region a project's Bedrock models are called in. */
+export interface BedrockRegion {
+    /** The region pi calls Bedrock in - undefined when the models need two regions and nothing names one, or the project uses no Bedrock model. */
+    region?: string;
+    source: BedrockRegionSource;
+    /** The Bedrock models the project uses, each once. */
+    models: string[];
+    /** The region the models need, and its geography - when they need one, and one only. */
+    needs?: {
+        region: string;
+        geography: string;
+    };
+    /**
+     * The models need more than one region: one AWS_REGION serves every model, so turri sets none, and says which model
+     * needs which.
+     */
+    conflict?: Array<{
+        region: string;
+        geography: string;
+        models: string[];
+    }>;
+}
+/** The variable turri marks its own AWS_REGION with, so the pi it starts - and a reload - tells it from the person's. */
+export declare const TURRI_AWS_REGION = "TURRI_AWS_REGION";
+/** Whether a region is in a geography: one of the regions Bedrock serves that geography's inference profiles from. */
+export declare function regionInGeography(region: string, geography: string): boolean;
+/** The region an AWS profile names, from AWS_CONFIG_FILE or ~/.aws/config - undefined when it names none, or the file cannot be read. */
+export declare function profileRegion(profile: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * What turri does about the AWS region for a project, from the environment as it is - reading it, setting nothing.
+ * `also`: models used besides the config's - named on the command line, chosen in this session.
+ */
+export declare function bedrockRegionFor(projectDir: string, options?: {
+    also?: string[];
+    env?: NodeJS.ProcessEnv;
+}): BedrockRegion;
+/**
+ * Set AWS_REGION for a project's Bedrock models, as `bedrockRegionFor` says: when they need a region and the person
+ * set none. Done again when the models change, it moves or takes back what turri set before, never the person's.
+ */
+export declare function applyBedrockRegion(projectDir: string, options?: {
+    also?: string[];
+    env?: NodeJS.ProcessEnv;
+}): BedrockRegion;
+/** A line on the region, for a model check: what turri set and how to override it - or the conflict it would not guess. */
+export declare function describeBedrockRegion(decided: BedrockRegion): string | undefined;