@turri-dev/cli 0.1.6 → 0.1.7-next.8f13f3a

package/dist/regenerate/test-scripts.d.ts

@@ -0,0 +1,221 @@
+import { Type } from "typebox";
+import { type TestRun } from "./testing.ts";
+/**
+ * The project's testing scripts, and the harness's runs of them.
+ *
+ * An agent runs whatever it likes while it works. Whether the work is done is decided by the
+ * project's own scripts - the ones the `implement-unit-testing-script` and
+ * `implement-conformance-testing-script` skills write into `test_scripts/` and link from the spec -
+ * run by the harness, never by the agent. The same script, the same way, every time: done is a
+ * decision the project made, not one an agent makes about its own work.
+ *
+ * The scripts live beside the specs, outside `plain_modules`, so no agent can reach them. The harness's runs and the
+ * agents' run_unit_tests and run_conformance_tests are the only ways they are ever run. They are the person's: they run
+ * on this machine as the person would run them - unfenced, in the person's own environment (turri's model provider
+ * keys left out) - through the host runner (shell.ts), which gives them a time limit and a stop. What they run on is the
+ * project's choice (`testing-scripts-run-on:` in its config):
+ *
+ * - `in-place`, the default: the project's own script at its own path, from the project, on the real build and tests
+ *   folders - so a script that finds things from its own path (a host codebase it merges the code into) finds them.
+ * - `copy`: a fresh copy of the code, staged in the project's scratch with the script copied beside it - build output
+ *   stays out of the code, two modules testing at once never share a folder, and nothing a test writes reaches the
+ *   code.
+ *
+ * A copy is named for its module and the run: the scripts work in `/tmp/<lang>_<basename of the build>`, and every
+ * module's build is called `code`.
+ */
+export type ScriptKind = "unit" | "conformance";
+export interface TestScripts {
+    /** `run_unittests_<lang>.sh <build>` */
+    unit?: string;
+    /** `run_conformance_tests_<lang>.sh <build> <conformance tests>` - the whole suite, at once. */
+    conformance?: string;
+    /**
+     * `prepare_environment_<lang>.sh <build>` - optional: run on the build before every run of the
+     * conformance testing script, which runs only once it passes. turri never writes one.
+     */
+    prepare?: string;
+    /** Why a script was not found where one was looked for: a name in config.turri.yaml, two in a folder. */
+    notes?: Partial<Record<ScriptKind | "prepare", string>>;
+    /** Conformance was turned off: the conformance testing script is not run, found or not. */
+    conformanceOff?: boolean;
+    /** What the config has them run on: the code in place (the default, unset), or a fresh copy of the code. */
+    runOn?: "copy" | "in-place";
+}
+/**
+ * The scripts, with the conformance testing script set aside because conformance was turned
+ * off: no conformance tests are written or run - not even those already in the codebase - and
+ * no agent is shown it.
+ */
+export declare function withoutConformance(scripts: TestScripts): TestScripts;
+export declare function scriptKind(name: string): ScriptKind | undefined;
+export declare const SCRIPTS_DIR = "test_scripts";
+/**
+ * The project a build belongs to: the folder that holds its plain_modules. A build folder
+ * elsewhere belongs to the folder of its spec.
+ */
+export declare function projectRootFor(plainFile: string, buildDir: string): string;
+/**
+ * The project's testing scripts, looked for in this order:
+ *
+ * 1. `config.turri.yaml` at the project root, with the chosen stack's `config.turri.<stack>.yaml` over it -
+ *    `unittests-script:` and `conformance-tests-script:`, paths from the root;
+ * 2. the project root itself - the one `run_unittests*.sh` / `run_conformance_tests*.sh` there;
+ * 3. `test_scripts/` - the one of each there.
+ *
+ * The prepare script - `prepare-environment-script:`, else the one `prepare_environment*.sh` - is looked for the same
+ * way, and is optional: without one, the conformance testing script runs alone.
+ *
+ * A folder holding two of a kind does not say which is meant: it is skipped, and noted, so the
+ * error that stops the build can say to name one in config.turri.yaml.
+ */
+export declare function findTestScripts(root: string, plainFile?: string, buildDir?: string): TestScripts;
+/**
+ * The exit code a testing script ends with when the tests passed and only its static checks - the formatter in check
+ * mode, the linter, the type checker - did not. Every other failure is the script's own exit code. The harness tells the
+ * two apart: a unit run says it was the static checks, and a conformance run sends its tests' findings straight to the
+ * conformance agent, with no judge asked whether the code or the tests are wrong.
+ */
+export declare const STATIC_CHECKS_FAILED = 80;
+/** Whether a failed run of a testing script failed on its static checks alone: the tests passed. */
+export declare function staticChecksOnly(run: {
+    exitCode: number;
+    timedOut?: boolean;
+}): boolean;
+/** Raised before a build starts when the script that would decide it is done is missing. */
+export declare class MissingTestScriptError extends Error {
+    readonly moduleName: string;
+    readonly kind: ScriptKind;
+    constructor(moduleName: string, kind: ScriptKind, note?: string);
+}
+/** The scripts a build needs, or the error that stops it before it starts. */
+export declare function requireTestScripts(moduleName: string, scripts: TestScripts, needs: {
+    conformance: boolean;
+}): asserts scripts is TestScripts & {
+    unit: string;
+};
+/**
+ * The scripts that decide an agent's work, in its prompt - only those that will be run on it: a
+ * conformance testing script an agent's work is never judged by is left out. The whole script,
+ * read from the project as it is now.
+ */
+export declare function withTestingScripts(prompt: string, scripts: TestScripts, kinds: ScriptKind[], root: string): string;
+export interface ScriptRun {
+    /** How the run is shown: the script's name, as the project calls it. */
+    command: string;
+    exitCode: number;
+    output: string;
+    /** Stopped by the time limit: counted as failed. */
+    timedOut?: boolean;
+    /** The time limit it ran under. */
+    timeoutMs: number;
+    /** How long it ran, from start to end - or to the limit that stopped it. */
+    elapsedMs?: number;
+    /** Where the whole output is, when it was too long to be shown whole. */
+    log?: string;
+}
+/** For tests: a shorter limit than two minutes. */
+export declare function setScriptTimeoutForTests(ms: number | undefined): void;
+/**
+ * The project a build belongs to - the folder above its `plain_modules`, where the testing scripts'
+ * own paths start - and whether they run on the code in place (the default), rather than on a fresh copy
+ * (`testing-scripts-run-on: copy`).
+ */
+/** Whether the testing scripts run on the code in `buildDir` itself, not on a copy of it. */
+export declare function scriptsRunInPlace(buildDir: string): boolean;
+/**
+ * The harness's run of the unit testing script on the code as it is now - and run_unit_tests'.
+ *
+ * On this machine, on the code in place, or - `testing-scripts-run-on: copy` - on a fresh copy of the code
+ * (see the top of this file). This and runConformanceScript are the only ways the testing
+ * scripts are ever run.
+ */
+export declare function runUnitScript(buildDir: string, script: string): Promise<ScriptRun>;
+/** How long the last passing run of `script` on the code in `buildDir` took, in this process - undefined before one has. */
+export declare function lastPassingMs(buildDir: string, script: string): number | undefined;
+/** A change to one code file for a run: the file, relative to the code folder, and the text it holds for the run. */
+export interface CodeChange {
+    file: string;
+    text: string;
+}
+/**
+ * A script that takes the code folder - the unit testing script - run where the testing scripts run. `change`: one file
+ * as it is for this run - made to the fresh copy, or, in place, to the code itself and undone once the run ends.
+ */
+export declare function runOnCode(buildDir: string, script: string, what: string, change?: CodeChange, 
+/** A time limit of its own, in place of a test run's. */
+limitMs?: number): Promise<ScriptRun>;
+/**
+ * The harness's run of the conformance testing script - and run_conformance_tests': the code, and
+ * the codebase's whole conformance suite - every functionality's tests, and those carried up from
+ * the modules below - in one folder, run at once. As runUnitScript runs: on a copy of the code staged beside the tests,
+ * or in place.
+ */
+export declare function runConformanceScript(buildDir: string, testsDirs: string[], scripts: TestScripts): Promise<ScriptRun>;
+/**
+ * `run_unit_tests` / `run_conformance_tests`: the agent's final check before it finishes - the
+ * project's testing script, run exactly as the harness will run it to decide whether the work is
+ * done. It takes no command. Everything else - one test, one file, another configuration, while
+ * the agent works - is what bash is for.
+ */
+export declare function createScriptTool(options: {
+    kind: ScriptKind;
+    script: string | undefined;
+    run: () => Promise<ScriptRun>;
+    runs: TestRun[];
+    onRun?: (command: string, exitCode: number) => void;
+    /** Watches the agent's runs for a loop: told once, then its turn is ended. */
+    watch?: LoopWatch;
+}): import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{}>, {
+    loop?: "warn" | "stop" | undefined;
+    command: string;
+    exitCode: number;
+}, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;
+/** How many of the agent's own runs failing the same way, one after another, are a loop. */
+export declare const LOOP_RUNS = 6;
+/**
+ * The agent's own test runs, watched for a loop: an agent stuck on a failure tends to try the same few changes in turn -
+ * three signatures of a stand-in function, say - running the tests after each, dozens of times in one turn, and never
+ * reads what would tell it the cause. Two things say it is circling: the code folder back exactly as it was at an
+ * earlier failing run (its notes aside), or LOOP_RUNS failing runs in a row the same way. The first time, it is told
+ * so with the run; the second, its turn is ended, and `stuck` says so until the harness has dealt with it. A passing
+ * run clears it all.
+ */
+export interface LoopWatch {
+    /** A run of the agent's: undefined, or "warn" the first time it is circling, "stop" the second. */
+    see(run: ScriptRun): "warn" | "stop" | undefined;
+    /** It was stopped for going round in circles, and the harness has not dealt with it yet. */
+    readonly stuck: boolean;
+    /** How many failing runs since its last passing one. */
+    readonly failing: number;
+    /** Dealt with: it starts counting again - the states it has failed in still remembered. */
+    reset(): void;
+}
+export declare function createLoopWatch(dir: string): LoopWatch;
+/**
+ * How long a run took against its time limit, in a line: for whoever judges it or works out its cause - so a run that
+ * ended on its own is never taken for one the limit stopped, nor the other way.
+ */
+export declare function runTiming(run: Pick<ScriptRun, "exitCode" | "timedOut" | "timeoutMs" | "elapsedMs">): string;
+/**
+ * What a failed run says is not installed where it ran - the command, when its output names it - or undefined when
+ * the run failed for another reason. A missing command is the cause only on evidence that it ended the run: exit 69,
+ * the testing scripts' own way to say a toolchain is missing, or 127, what a shell or `timeout` gives for a command it
+ * could not find - else a command not found on the last line the run printed, nothing having run after it. Earlier in
+ * the output it is a warning, not the failure: a shell profile's, an optional tool probed for, a fallback taken - and a
+ * run that failed for its own reasons is the agent's to fix, not a stop for the person.
+ */
+export declare function missingToolchain(run: Pick<ScriptRun, "exitCode" | "output">): {
+    command?: string;
+} | undefined;
+/** Where `command` is on this machine's PATH, or undefined when it is not there. */
+export declare function onThisMachine(command: string): string | undefined;
+/** What a failed script run means, for the agent that has to fix it. */
+export declare function scriptFailure(run: ScriptRun, what: string): string;
+/** How many rounds running the same failure, taken the same way, is nothing changing. */
+export declare const STUCK_ROUNDS = 3;
+/**
+ * A failing run, as a fingerprint: the lines that say what went wrong, without what changes from run
+ * to run - numbers, times, paths, ids. Two runs failing the same way have the same one.
+ */
+export declare function failureSignature(run: ScriptRun): string;

package/dist/regenerate/testing.d.ts

@@ -0,0 +1,141 @@
+import { Type } from "typebox";
+import { type ScriptRun } from "./test-scripts.ts";
+/** Shared test-running and test-preservation machinery for both render tools. */
+export interface TestRun {
+    command: string;
+    exitCode: number;
+}
+/** A test run has the same time limit as any command: see COMMAND_TIMEOUT_MS. */
+export declare const RUN_TIMEOUT_MS: number;
+/**
+ * Output as an agent is shown it: whole when it fits, otherwise its last MAX_OUTPUT_CHARS - where a
+ * test run says what failed and why. With `log` the whole output is kept in that file too, and the
+ * cut says how to read it: through read_output, by the file's name - never by a path, which would
+ * point the agent outside its walls.
+ */
+export declare function truncateOutput(text: string, log?: string): string;
+/**
+ * A test run's output as an agent is shown it: whole when it is short; otherwise its failures with the trace after each,
+ * its counts and its end - DEBUG and TRACE logging left out - with the whole kept and one read_output away. Most of what
+ * agents carried in their context was a failing run's logging; what they act on is which test failed, where, and why.
+ */
+export declare function shownTestOutput(text: string, log?: string): string;
+/** Where the whole outputs are kept: the project's scratch area, read only through read_output. */
+export declare function outputsDir(dir: string): string;
+/** Keep `output` whole, whatever its length, in the outputs folder. Returns the file, or nothing when it could not be written. */
+export declare function keepOutput(dir: string, label: string, output: string | Buffer): string | undefined;
+/**
+ * Keep a run's whole output where an agent can read it, when it is too long to be shown whole:
+ * in the project's scratch area, inside plain_modules. Returns the file, or nothing when the
+ * output fits.
+ */
+export declare function keepFullOutput(dir: string, label: string, output: string): string | undefined;
+/** Keep a test run's whole output for read_output when it is too long to be shown whole - past TEST_OUTPUT_WHOLE. */
+export declare function keepTestOutput(dir: string, label: string, output: string): string | undefined;
+/**
+ * A shell's output as the agent is shown it: when pi cut it and kept the whole in a temporary file of its own, the file
+ * is taken into the outputs folder, and the agent pointed at read_output instead of at the file.
+ */
+export declare function keptShellOutput(dir: string, text: string): string;
+/**
+ * `read_output`: the whole of an output that was cut - a test run's, a command's - read by the id the cut gave, a range
+ * of lines or the lines matching a pattern. It reads the kept outputs and nothing else.
+ */
+export declare function readOutputTool(dir: string): import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+    id: Type.TString;
+    offset: Type.TOptional<Type.TNumber>;
+    limit: Type.TOptional<Type.TNumber>;
+    pattern: Type.TOptional<Type.TString>;
+}>, {
+    id: string;
+}, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;
+/** Output as an agent is shown it, with the whole of it kept in a file when it had to be cut. */
+export declare function shownOutput(dir: string, label: string, output: string): string;
+/**
+ * Never part of the codebase: version control, installed dependencies, tool caches, and the
+ * harness's own bookkeeping. Installed dependencies alone can be tens of thousands of files.
+ */
+export declare const NOT_CODE: Set<string>;
+export declare function listFiles(root: string): string[];
+/** A tool that runs the tests and lets the harness see the result, rather than taking the agent's word. */
+export declare const TEST_FILE_PATTERN: RegExp;
+/**
+ * Which files look like tests, and roughly how many cases each holds.
+ *
+ * The count is a heuristic over common test idioms across languages. It is not a parser -
+ * it exists to notice that tests went missing between one turn and the next, which is a
+ * question worth asking even when the estimate is a case or two off.
+ */
+export declare function inventoryTests(root: string): Map<string, number>;
+export interface TestRemoval {
+    file: string;
+    before: number;
+    after: number;
+    deleted: boolean;
+}
+/** Test files that disappeared, or lost cases, between two inventories. */
+export declare function findTestRemovals(before: Map<string, number>, after: Map<string, number>): TestRemoval[];
+export declare function describeRemovals(removals: TestRemoval[]): string;
+/**
+ * A deleted test is a silent way to make a suite pass. The rule is narrow on purpose:
+ * a test may go only when it asserts nothing meaningful, never because it is failing.
+ */
+export declare function removalChallengePrompt(removals: TestRemoval[], subject: string): string;
+/**
+ * How many times a coding agent that ended its turn having written nothing is asked for a draft: once. Thinking a
+ * problem through and ending the turn with nothing written leaves nothing to test or review; a best guess does. A
+ * change that only rewords or describes may need no code, and the agent says so.
+ */
+export declare const DRAFT_ASKS = 1;
+/** For a coding agent that has written nothing yet: write a best-guess draft now, or say why no code is needed. */
+export declare function draftPrompt(): string;
+export type UnitVerdict = {
+    ok: true;
+    command: string;
+} | {
+    ok: false;
+    command?: string;
+    prompt: string;
+    missing?: MissingToolchain;
+    run?: ScriptRun;
+};
+/** A toolchain the testing script needs and does not find on this machine: no change to the code can pass it. */
+export interface MissingToolchain {
+    command?: string;
+}
+/**
+ * The harness's own run of the unit tests, which is what "the tests pass" rests on.
+ *
+ * The agent runs whatever commands it likes while it works. Whether the code is done is the
+ * project's unit testing script, run by the harness on the code as it now is - the same script,
+ * the same way, every time (see test-scripts.ts).
+ */
+export declare function verifyUnitSuite(buildDir: string, runs: TestRun[], script: string): Promise<UnitVerdict>;
+/** Every file of the test code under `dirs`, by path, as it is now. */
+export declare function snapshotFiles(dirs: string[]): Map<string, Buffer>;
+/** The files under `dirs` that differ from the snapshot: changed, added or deleted. */
+export declare function changedSince(snapshot: Map<string, Buffer>, dirs: string[]): string[];
+/** Put the files under `dirs` back to the snapshot: its files restored, any others removed. */
+export declare function restoreSnapshot(snapshot: Map<string, Buffer>, dirs: string[]): void;
+/**
+ * Run an agent that fixes code with the conformance tests out of its reach - by the harness,
+ * not by its file access, which covers the whole of `plain_modules`.
+ *
+ * The tests say what the specification requires; an agent told to make them pass could
+ * otherwise do it by changing a test. So they are photographed before it starts and compared
+ * when it finishes. Anything it changed is put back, and it is sent to fix the code instead,
+ * until it leaves the tests alone or the rounds run out - after which the tests are put back
+ * all the same. Returns the agent's last report and every test file it had to have restored.
+ */
+export declare function keepingTestsUnchanged(input: {
+    dirs: string[];
+    /** The agent's first turn. */
+    start: () => Promise<string>;
+    /** Another turn, with this prompt. */
+    again: (prompt: string) => Promise<string>;
+    /** For the activity line: whose code is being fixed. */
+    label: string;
+}): Promise<{
+    report: string;
+    restored: string[];
+}>;

package/dist/regenerate/transcript-view.d.ts

@@ -0,0 +1,21 @@
+import type { DiffPaint } from "./diff-view.ts";
+import type { DiffStyle } from "./job-panel.ts";
+/**
+ * How the side panel colours things. Plain text when there is no theme, as in tests.
+ *
+ * The panel no longer shows a job's agents at work - every prompt, reply, thought and tool call: that is in each
+ * pulse's log (job-log.ts), streamed as it happens.
+ */
+export interface TranscriptStyle extends DiffStyle {
+    heading(text: string): string;
+    muted(text: string): string;
+    accent(text: string): string;
+    error(text: string): string;
+    /** A pulse that passed, and one stopped: not given, the added colour and the accent. */
+    success?(text: string): string;
+    warning?(text: string): string;
+    /** How a spec diff is painted - ***plain highlighted, added and removed lines filled (`plain-palette.ts`). Not given: the +/- coloured alone. */
+    diff?: DiffPaint;
+    /** A functional spec its conformance tests pass for - regen's ◆: neon. */
+    conforms?: (text: string) => string;
+}

package/dist/regenerate/unit-gate.d.ts

@@ -0,0 +1,27 @@
+import type { MissingToolchain, TestRun } from "./testing.ts";
+import { type ScriptRun } from "./test-scripts.ts";
+/**
+ * The coding agent's unit tests: the project's unit testing script, run by the harness. The script is the whole of it -
+ * its static checks, when it runs any, included - and its exit code says which failed: `STATIC_CHECKS_FAILED` is the
+ * tests passing and only the checks not.
+ */
+export type WorkVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    /** What the agent is sent back with. */
+    prompt: string;
+    /** The run that failed, for the fingerprint and the debugger. */
+    run: ScriptRun;
+    /** The script that run was of. */
+    script: string;
+    /** Only the script's static checks failed: the tests passed. */
+    staticOnly: boolean;
+    /** A toolchain the script needs and this machine lacks. */
+    missing?: MissingToolchain;
+};
+export interface UnitGate {
+    /** The unit testing script on the code, recorded in `runs`: passing, or what to send the agent back with. */
+    verify(runs: TestRun[]): Promise<WorkVerdict>;
+}
+export declare function createUnitGate(buildDir: string, unit: string): UnitGate;

package/dist/regenerate/unit-review.d.ts

@@ -0,0 +1,152 @@
+import { type WorkLedger } from "./submit-work.ts";
+import type { JobCases } from "./drift.ts";
+/** How many times the reviewer runs can_it_fail in a review session: each is a run of the unit testing script. */
+export declare const REVIEWER_CAN_IT_FAIL_RUNS = 3;
+/**
+ * The review of the work: once its unit tests pass, does the code do what the spec says, and do the tests test it?
+ *
+ * A passing unit suite proves only what its tests check, and a coding agent is quick to write tests
+ * that check next to nothing - that a function exists, that it returns something, that a status is
+ * 200 - and pass whatever the code does, or none at all. So once the unit testing script passes, a
+ * reviewer reads what the work wrote - the code and the unit tests, as a diff - beside the spec, and says
+ * where the code does not do what the spec says, and which tests are missing or weak. It changes nothing. Its problems go back to the coding agent, the unit testing script
+ * runs again, and the review looks again. It optimises the tests, it is not a gate: a problem that
+ * leaves a behaviour of the spec untested is worked on first, the rest - ways to make tests that
+ * already test it better - are let go after UNIT_REVIEW_ROUNDS reviews, and after UNIT_REVIEW_LIMIT
+ * whatever is left is let go too, kept in the notes, and the work goes on.
+ */
+/** What the review found wrong with the code or its unit tests. */
+export interface UnitReviewProblem {
+    file: string;
+    test?: string;
+    /** "wrong": the code does not do what the spec says. "missing", "bad": a unit test not there, or weak. */
+    kind: "missing" | "bad" | "wrong";
+    what: string;
+    /**
+     * A behaviour the spec states is not implemented, or implemented wrong, or not yet tested: no test for it, or
+     * one that cannot fail - it only checks that something exists, asserts nothing, mocks the unit it tests, is skipped.
+     */
+    blocking?: boolean;
+}
+/**
+ * How many reviews may send the unit tests back before the arbiter weighs them: from this one on, every review that
+ * sends them back goes to the arbiter first, and only what it upholds reaches the coding agent.
+ */
+export declare const UNIT_REVIEW_ROUNDS = 1;
+/**
+ * How many reviews at most. The review optimises the tests; it does not decide whether the work is done - the
+ * unit testing script does. Past this many, whatever it still finds, blocking or not, is let go, kept in the notes,
+ * and the work goes on.
+ */
+export declare const UNIT_REVIEW_LIMIT = 2;
+/** The unit test files that differ from what they were when the work started: added or changed. */
+export declare function changedUnitTests(buildDir: string, atStart: Map<string, string>): string[];
+/**
+ * The reviewer's task, for its instructions: what it reviews, against which specification, and how. It stays word for
+ * word through every review of the loop; what each review is shown comes as a message (`unitReviewRequest`).
+ */
+export declare function unitReviewTask(options: {
+    buildDir: string;
+    /** What the work built: "functionality 3 of module `m`", "the spec change to module `m`". */
+    what: string;
+    /** The specification it built, as the coding agent had it, what is new in this work apart (`reviewedSpec`). */
+    spec: string;
+    /** The work is a spec change, not a functionality. */
+    forChange?: boolean;
+    /** What the work does to each functional spec (work.ts): each part held to its own case. */
+    cases?: JobCases;
+    /** It has can_it_fail, to check that a test it doubts can fail. */
+    canItFail?: boolean;
+    /** The unit testing script, word for word: how the unit tests are run, and so which of them run at all. */
+    testingScript?: {
+        path: string;
+        content: string;
+    };
+}): string;
+/** What one review is shown: the whole work the first time; after that, what changed since the last, and the problems it raised. */
+export declare function unitReviewRequest(options: {
+    /** First review: the whole work (`workDiff`). After it: the diff since the last review (`diffSinceSnapshot`). */
+    diff: string;
+    changed: string[];
+    /** The coding agent's account of its work since the last review (`describeAccounts`). */
+    account: string;
+    /** The problems the last review raised that went to the coding agent - given, this is a review after it. */
+    earlier?: UnitReviewProblem[];
+    /** What the arbiter let go of the last review: not to be raised again. */
+    letGo?: UnitReviewProblem[];
+}): string;
+export interface UnitReviewer {
+    /** One review: what it is shown (`unitReviewRequest`), and its verdict. No verdict is no pass. */
+    review(request: string): Promise<{
+        pass: boolean;
+        problems: UnitReviewProblem[];
+    }>;
+    dispose(): void;
+}
+/**
+ * The reviewer: a read-only agent, on the judge model, that says pass or every problem - one session for the whole
+ * loop, so a review after the first starts from what it already read and raised, not from nothing. Its task is its
+ * instructions; its work is compacted as it gets longer.
+ */
+export declare function createUnitReviewer(options: {
+    /** What the work does to each functional spec (work.ts): the reviewer holds each part to its own case. */
+    cases?: JobCases;
+    buildDir: string;
+    what: string;
+    spec: string;
+    forChange?: boolean;
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+    /** The unit testing script: the reviewer checks with can_it_fail that a test it doubts can fail. */
+    unitScript?: string;
+    /** The unit testing script, word for word, in its task. */
+    testingScript?: {
+        path: string;
+        content: string;
+    };
+}): Promise<UnitReviewer>;
+/** The review's problems, for the coding agent. */
+export declare function unitReviewFeedbackPrompt(problems: UnitReviewProblem[]): string;
+/**
+ * Review the code and its unit tests until they pass it: each time it finds problems, they go to the coding agent
+ * and the unit tests must pass again before the next review. Past UNIT_REVIEW_ROUNDS reviews with
+ * nothing blocking, what it still suggests is let go and kept in the notes; past UNIT_REVIEW_LIMIT,
+ * whatever is left is let go the same way - the review optimises the tests, it never stops the work.
+ * Only unit tests that no longer pass after a round of fixes do.
+ */
+export declare function untilUnitTestsReviewed(options: {
+    /** What the work does to each functional spec (work.ts): the reviewer holds each part to its own case. */
+    cases?: JobCases;
+    buildDir: string;
+    /** The code folder's files when the work started, to see which unit tests it added or changed. */
+    atStart: Map<string, string>;
+    what: string;
+    /** The specification it built, what is new in this work apart (`reviewedSpec`). */
+    spec: string;
+    forChange?: boolean;
+    label: string;
+    model?: string;
+    /** Send the coding agent a prompt. */
+    send: (prompt: string) => Promise<void>;
+    /** Run the unit tests with the coding agent until they pass: false when they do not. */
+    untilPassing: () => Promise<boolean>;
+    stage: (label: string) => void;
+    onDelta?: (delta: string) => void;
+    /** What the coding agent handed over through submit_work: its account, beside the diff, for the reviewer. */
+    work?: WorkLedger;
+    /** Send the coding agent back once for problems its account left unanswered. Default true when `work` is given. */
+    askForAnswers?: boolean;
+    /** The unit testing script: the reviewer checks with can_it_fail that a test it doubts can fail. */
+    unitScript?: string;
+    /** The unit testing script, word for word, for the reviewer to read. */
+    testingScript?: {
+        path: string;
+        content: string;
+    };
+}): Promise<{
+    passed: boolean;
+    waived?: UnitReviewProblem[];
+    problems?: UnitReviewProblem[];
+    reviews: number;
+}>;

package/dist/regenerate/web.d.ts

@@ -0,0 +1,61 @@
+import { Type } from "typebox";
+/**
+ * The web, for the agents that build: search it, and read a page.
+ *
+ * An agent building on a library it half-remembers, or stuck on an error it has not seen, does
+ * better reading the documentation or the answer than guessing again. So every rendering agent
+ * has two tools: `web_search`, which asks DuckDuckGo and returns the results, and `web_fetch`,
+ * which reads one page and returns it as text.
+ *
+ * Both run here, in turri itself. What reaches the web through them is a request the agent made
+ * through a tool, and what comes back is text it reads.
+ *
+ * Only the public web: `web_fetch` refuses an address on this machine or its network - localhost,
+ * the private ranges, the cloud metadata address - so it cannot be used to reach the cloud's
+ * credentials or a service inside the person's network by way of turri.
+ */
+export declare const WEB_TOOLS: string[];
+/** How much of a page one call returns; the rest is had with `offset`. */
+export declare const PAGE_CHARS = 20000;
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export declare function decodeEntities(text: string): string;
+/** The results on a page of DuckDuckGo Lite: each a link, then its snippet. Ads are left out. */
+export declare function parseSearchResults(html: string): SearchResult[];
+export declare function webSearch(query: string, limit?: number): Promise<SearchResult[]>;
+/** Whether an IP address is on this machine or its network, rather than the public internet. */
+export declare function isPrivateAddress(address: string): boolean;
+type Lookup = (host: string) => Promise<string[]>;
+/** Refuse a URL that is not http(s) on the public internet; its parsed form when it is. */
+export declare function checkPublicUrl(raw: string, resolve?: Lookup): Promise<URL>;
+/** A page as readable text: what a person would read, without the markup, scripts and styles. */
+export declare function htmlToText(html: string): string;
+export interface FetchedPage {
+    url: string;
+    status: number;
+    contentType: string;
+    text: string;
+}
+/** Fetch a public page, following redirects - each checked - and return it as text. */
+export declare function webFetch(raw: string, opts?: {
+    resolve?: Lookup;
+    fetchImpl?: typeof fetch;
+}): Promise<FetchedPage>;
+/** One window of a long page, and how to read on. */
+export declare function pageWindow(text: string, offset: number): string;
+export declare function createWebTools(): ((import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+    query: Type.TString;
+    limit: Type.TOptional<Type.TInteger>;
+}>, {
+    results: number;
+}, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>) | (import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+    url: Type.TString;
+    offset: Type.TOptional<Type.TInteger>;
+}>, {
+    characters: number;
+    status: number;
+}, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>))[];
+export {};

package/dist/regenerate/workspace.d.ts

@@ -0,0 +1,12 @@
+export interface WorkspaceInput {
+    /** The agent's folder. */
+    dir: string;
+    /** Whether the agent has my_diff, which shows its work. */
+    hasMyDiff: boolean;
+    /** The module's implementation reqs, which name its stack; read from its spec when not given. */
+    implementationReqs?: string[];
+    /** For tests: a command's version, in place of asking this machine. */
+    probe?: (command: string) => string | undefined;
+}
+/** The block, for the agent's system prompt beside its walls. */
+export declare function workspaceBlock(input: WorkspaceInput): string;

package/dist/regenerate-cli.d.ts

@@ -0,0 +1 @@
+export {};