@turri-dev/cli 0.1.7 → 0.1.8-next.91b957c

package/dist/identity.js

@@ -1,5 +1,31 @@
-/** Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. */
-export const TURRI_IDENTITY = [
+/** In the terminal: regen, where the person watches the work - the side panel, its key, and the pulses behind it. */
+const REGEN = [
+    "- regen is the side panel (ctrl+h): the spec with each functionality and item marked built, regenerating,",
+    "  planned or waiting - and behind it the pulses (/pulses), every pulse regenerating, planned and finished. Say regen,",
+    "  lowercase. It was the regeneration, the job queue, or the job panel.",
+];
+/** In a host: where the person watches the work is the host's to say - its surface, below. */
+const HOST_SURFACE = [
+    "- What the person sees of your work - where they watch it, and what they press - is the app's you run in, and",
+    "  <surface> below says it in its own words. Say only what it says, and speak of no key, panel or view it does not",
+    "  name.",
+];
+/**
+ * Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. Where
+ * the person watches the work is the terminal's regen; given a host's surface, that is said in its place.
+ */
+export function conversationIdentity(surface) {
+    const text = surface?.trim() ?? "";
+    const hosted = text !== "";
+    return [
+        ...IDENTITY_BEFORE,
+        ...(hosted ? HOST_SURFACE : REGEN),
+        ...IDENTITY_AFTER,
+        ...(hosted ? ["", "<surface>", text, "</surface>"] : []),
+        "</turri>",
+    ].join("\n");
+}
+const IDENTITY_BEFORE = [
     "<turri>",
     "You are turri - always lowercase - a coding agent with the power of regenerative software. The software is its",
     "***plain; the code is regenerated from it. You help the person write ***plain, and you regenerate the code from it a",
@@ -25,11 +51,11 @@ export const TURRI_IDENTITY = [
     "- A pulse is one unit of work regenerating the code - a spec diff regenerated in a codebase, or its conformance",
     "  tests. It was called a job, and still is in places: the job_id a tool takes is a pulse's id, and parallel-jobs and",
     "  allow-to-stop-jobs in config.turri.yaml are about pulses. \"Job\" in what you read is a pulse; say pulse.",
-    "- regen is the side panel (ctrl+h): the spec with each functionality and item marked built, regenerating,",
-    "  planned or waiting - and behind it the pulses (/pulses), every pulse regenerating, planned and finished. Say regen,",
-    "  lowercase. It was the regeneration, the job queue, or the job panel.",
+];
+const IDENTITY_AFTER = [
     "- mutate, in a skill's activity, is write_spec_diff: a spec change written and regenerated in one step.",
     "- Regenerate is the word for what you do to the code: never grow, grew or grown - older text, a tool's description",
     "  or a report may still say it, and means regenerate.",
-    "</turri>",
-].join("\n");
+];
+/** turri as the terminal runs it. */
+export const TURRI_IDENTITY = conversationIdentity();

package/dist/init-config.d.ts

@@ -66,6 +66,9 @@ export declare const DEFAULTS: {
     readonly compactAt: 100000;
     readonly maxSpecsPerPulse: 3;
     readonly maxLinesPerPulse: 120;
+    readonly ledgerKeep: 100;
+    readonly debug: false;
+    readonly cacheKeep: 4096;
 };
 /** How many pulses run at once without a setting: half this machine's cores, one to four - as regenerate/jobs.ts has it. */
 export declare function defaultParallel(cores?: number): number;

package/dist/init-config.js

@@ -118,6 +118,9 @@ export const DEFAULTS = {
     compactAt: 100000,
     maxSpecsPerPulse: 3,
     maxLinesPerPulse: 120,
+    ledgerKeep: 100,
+    debug: false,
+    cacheKeep: 4096,
 };
 /** How many pulses run at once without a setting: half this machine's cores, one to four - as regenerate/jobs.ts has it. */
 export function defaultParallel(cores = availableParallelism()) {
@@ -183,6 +186,18 @@ export function quickStartConfig(vendor = "other", bedrock) {
         "# Folders of this machine an agent's commands may read beside the usual ones - a toolchain somewhere unusual: [/srv/zig].",
         "toolchains: []",
         "",
+        "# Megabytes of the ledger - what turri did, as facts, in .turri/ledger, never committed - the project keeps; past it,",
+        "# the oldest runs' are pruned. 0 keeps none.",
+        `ledger-keep: ${DEFAULTS.ledgerKeep}`,
+        "",
+        "# Megabytes of package caches - npm's, pip's, Maven's... in plain_modules/.turri/cache - the project keeps; past it,",
+        "# the least recently written are removed. 0 keeps none.",
+        `cache-keep: ${DEFAULTS.cacheKeep}`,
+        "",
+        "# Whether turri keeps what it writes for debugging it: every agent's whole log and session, each pulse's log, the",
+        "# test runs' outputs, the agents' temporary files. Off, only what turri reads to work is kept. TURRI_DEBUG=1 for one run.",
+        `debug: ${DEFAULTS.debug}`,
+        "",
         "# The testing scripts, by path from the project root - written here by the skill that writes them. One not named is",
         "# looked for at the root, then in test_scripts/. Each runs the static checks of what it tests - the formatter, the",
         "# linter, the type checker - with the tests, exiting 80 when the tests pass and only the checks do not. The prepare",

package/dist/ledger-cli.d.ts

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

package/dist/ledger-cli.js

@@ -0,0 +1,50 @@
+import { resolve } from "node:path";
+import { readLedger } from "./regenerate/ledger.js";
+import { describePastPulse, describeRuns, ledgerProjects, runViews } from "./regenerate/ledger-view.js";
+const USAGE = `usage: turri ledger [pulse] [--runs <n>] [--json]
+
+What turri did here, from the project's ledger (.turri/ledger): the last runs, a line a pulse - how each ended, how
+long it took and what it cost. With a pulse's id, or the start of it, that pulse: its rounds, test runs, verdicts,
+healers, what turri refused and what its history recorded. --json prints the events themselves, a JSON line each.
+
+  --runs <n>   how many runs to show, the most recent first (default 5)
+  --json       the events, as the ledger has them - the pulse's alone with a pulse`;
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const runsAt = args.indexOf("--runs");
+const runs = runsAt >= 0 ? Number(args[runsAt + 1]) : 5;
+if (runsAt >= 0 && (!Number.isInteger(runs) || runs < 1)) {
+    console.error(`--runs takes a number of runs, at least 1\n\n${USAGE}`);
+    process.exit(1);
+}
+const [pulse] = args.filter((arg, at) => !arg.startsWith("-") && (runsAt < 0 || at !== runsAt + 1));
+const projects = ledgerProjects(process.cwd());
+if (projects.length === 0) {
+    console.log("No ledger here: turri has not run in this folder, or in a project under it, since the ledger began.");
+    process.exit(0);
+}
+if (args.includes("--json")) {
+    for (const project of projects)
+        for (const entry of readLedger(project, pulse !== undefined ? { job: pulse } : {}))
+            console.log(JSON.stringify(entry));
+    process.exit(0);
+}
+if (pulse !== undefined) {
+    const described = describePastPulse(projects, pulse);
+    if (described === undefined) {
+        console.error(`The ledger has no pulse ${pulse}.`);
+        process.exit(1);
+    }
+    console.log(described);
+    process.exit(0);
+}
+for (const project of projects) {
+    if (projects.length > 1)
+        console.log(`── ${resolve(project)}\n`);
+    console.log(describeRuns(runViews(project).slice(0, runs)));
+    if (projects.length > 1)
+        console.log("");
+}

package/dist/ledger-tools.d.ts

@@ -0,0 +1,10 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+type AnyTool = ToolDefinition<any, any, any>;
+/**
+ * ledger: what turri did, as the ledger recorded it - in this session and every one before it. One pulse, by its id,
+ * as facts; the last runs, a line a pulse; or the events of some kinds, counted and listed. Reads only.
+ */
+export declare function ledgerTool(options: {
+    cwd: string;
+}): AnyTool;
+export {};

package/dist/ledger-tools.js

@@ -0,0 +1,64 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { describeEvents, describePastPulse, describeRuns, ledgerProjects, runViews, sinceOf } from "./regenerate/ledger-view.js";
+/** How many runs `ledger` lists when it is asked for none. */
+const RUNS_SHOWN = 3;
+/**
+ * ledger: what turri did, as the ledger recorded it - in this session and every one before it. One pulse, by its id,
+ * as facts; the last runs, a line a pulse; or the events of some kinds, counted and listed. Reads only.
+ */
+export function ledgerTool(options) {
+    return defineTool({
+        name: "ledger",
+        label: "Ledger",
+        description: "What turri did here, as its ledger recorded it - facts, not transcripts - in this session and every earlier one. " +
+            "With pulse: that pulse, this session's or an earlier one's - how it ended, its rounds and test runs (how many failed " +
+            "the same way), the judge's and the reviews' verdicts, the healers (the debugger, the diagnosis) and whether they " +
+            "failed, the model provider's trouble, what turri refused and stopped, what it committed or rolled back, its last " +
+            "stages and its log. With kinds (and module, since): how many events of those kinds there were, and the most recent, " +
+            "a line each - healer.failed, provider.error, script.run, gate.round, judge.verdict, guard.refused, history.failed, " +
+            "job.finished, ...; a group by its first part, healer for every healer event. Otherwise: the last runs, a line a pulse - " +
+            "how each ended, how long, what it cost. Starts nothing and calls no model.",
+        promptSnippet: "ledger: what turri did - a pulse as facts, the last runs, or events counted by kind - this session and earlier ones",
+        promptGuidelines: [
+            "Use ledger for what turri recorded of the work - a pulse's rounds, test runs, verdicts, healers and commits, this session's or an earlier one's; how often something happened; what earlier runs did and cost - rather than reading .turri/ledger with the shell. pulses is what is running and planned now; a pulse's whole transcript is its log, which ledger names when it is kept (debug mode).",
+        ],
+        parameters: Type.Object({
+            pulse: Type.Optional(Type.String({ description: "A pulse's id, or the start of it: that pulse, as the ledger has it" })),
+            kinds: Type.Optional(Type.Array(Type.String(), { description: "Event kinds to count and list - healer.failed, or healer for the whole group" })),
+            module: Type.Optional(Type.String({ description: "With kinds: only the events of this module" })),
+            since: Type.Optional(Type.String({ description: "With kinds: only events since then - 24h, 7d, 30m, or a date and time" })),
+            runs: Type.Optional(Type.Number({ description: `Without pulse or kinds: how many of the last runs to list (default ${RUNS_SHOWN})` })),
+            limit: Type.Optional(Type.Number({ description: "With kinds: how many of the most recent events to list (default 20)" })),
+        }),
+        async execute(_id, params) {
+            const text = (body, details = {}) => ({ content: [{ type: "text", text: body }], details });
+            const projects = ledgerProjects(options.cwd);
+            if (projects.length === 0)
+                return text("The ledger is empty here: nothing has run in this folder, or in a project under it, since it began.", { found: false });
+            if (params.pulse !== undefined) {
+                const described = describePastPulse(projects, params.pulse.trim());
+                return described !== undefined ? text(described, { found: true }) : text(`The ledger has no pulse ${params.pulse}.`, { found: false });
+            }
+            if (params.kinds !== undefined && params.kinds.length > 0) {
+                let since;
+                if (params.since !== undefined) {
+                    since = sinceOf(params.since);
+                    if (since === undefined)
+                        return text(`since takes 24h, 7d, 30m or a date and time, not ${JSON.stringify(params.since)}.`, { found: false });
+                }
+                return text(describeEvents(projects, {
+                    kinds: params.kinds,
+                    ...(params.module !== undefined ? { module: params.module } : {}),
+                    ...(since !== undefined ? { since } : {}),
+                    ...(params.limit !== undefined ? { limit: params.limit } : {}),
+                }), { found: true });
+            }
+            const count = params.runs !== undefined && Number.isFinite(params.runs) ? Math.max(1, Math.floor(params.runs)) : RUNS_SHOWN;
+            const runs = projects.flatMap((project) => runViews(project)).sort((a, b) => (b.started?.ts ?? "").localeCompare(a.started?.ts ?? ""));
+            const shown = runs.slice(0, count);
+            const more = runs.length - shown.length;
+            return text(`${describeRuns(shown)}${more > 0 ? `\n\n${more} earlier run${more === 1 ? "" : "s"} beyond these: ask with runs for more.` : ""}`, { found: true, runs: shown.length });
+        },
+    });
+}

package/dist/loop-cli.js

@@ -5,6 +5,7 @@ import { configForSpec, inheritModel, modelOnly, modelSpec, projectModels, readP
 import { PACKAGE_ROOT } from "./environment.js";
 import { c } from "./module-report.js";
 import { describeTurnIncident, onModelEvent } from "./regenerate/activity.js";
+import { ledgerWanted, startLedger } from "./regenerate/ledger.js";
 import { tryItCommand } from "./regenerate/delivery.js";
 import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
 import { createJobRegistry, pulseName } from "./regenerate/jobs.js";
@@ -32,6 +33,9 @@ export async function runLoop(options) {
     // 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);
+    // What the run does, as facts, in the project's .turri/ledger.
+    if (ledgerWanted() && options.dryRun !== true)
+        startLedger({ mode: options.command?.[0] ?? "headless", project: projectDir, warn: (message) => console.error(message) });
     const buildDir = options.buildDir !== undefined && options.dryRun !== true ? resolve(options.buildDir) : undefined;
     if (buildDir !== undefined)
         refuseBuildDir(buildDir, projectDir);

package/dist/loop-tools.js

@@ -9,6 +9,7 @@ import { pulseName } from "./regenerate/jobs.js";
 import { stopDeployed } from "./regenerate/release.js";
 import { projectDirOf } from "./regenerate/paths.js";
 import { findTestScripts } from "./regenerate/test-scripts.js";
+import { surfaceOf } from "./surface.js";
 /** How the queue is to be planned, for the work this call queues - see regenerate/steer.ts. */
 export const GUIDANCE_PARAM = Type.Optional(Type.String({
     description: "How to plan the queue for this work, in a sentence or two - which functional specs go together, what first - as " +
@@ -114,8 +115,9 @@ export function stopJob(jobs, named, reason, loop) {
     if (module !== undefined)
         return module;
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
+    // /pulses is the terminal's: in a host, the pulses tool lists them.
     if (matches.length === 0)
-        return `No pulse ${named}. /pulses shows them.`;
+        return `No pulse ${named}. ${surfaceOf(jobs) !== undefined ? "The pulses tool lists them." : "/pulses shows them."}`;
     if (matches.length > 1)
         return `'${named}' matches ${matches.map((job) => job.id).join(", ")}. Give more of the id.`;
     const target = matches[0];

package/dist/pi.d.ts

@@ -184,6 +184,8 @@ export declare function createExecutor(opts: {
     rules?: boolean;
     /** Continue the session saved in this file, instead of starting a new one. */
     resumeFrom?: string;
+    /** Save its session to disk, debug mode or not: it is picked back up later (a skill's run, resumed). */
+    saveSession?: boolean;
     /** Added to its system prompt: its sandbox, above all - what it can reach (see confine.ts sandboxNote). */
     system?: string;
     /**

package/dist/pi.js

@@ -2,13 +2,14 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, ModelRegistry, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { loadRules, renderRulesBlock } from "./rules.js";
-import { inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, roleTurnLimitMs, splitModelSpec } from "./config.js";
+import { debugMode, inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, roleTurnLimitMs, splitModelSpec } from "./config.js";
 import { maskToolResults } from "./regenerate/masking.js";
 import { withListArguments } from "./regenerate/list-arguments.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, reportModelEvent, reportUsage, } from "./regenerate/activity.js";
 import { debugLogOf, startDebugLog } from "./regenerate/debug-log.js";
+import { firstLine, record } from "./regenerate/ledger.js";
 let thinkingSource;
 /**
  * Where sub-agents take their thinking level from: the conversation that started them.
@@ -280,6 +281,8 @@ async function askOnce(session, text, onDelta) {
     // Calls to one tool failing one after another - arguments it refuses, or errors - with nothing going through.
     let failing = 0;
     let failingTool;
+    /** When each tool call under way started, by its id: how long it took is recorded as it ends. */
+    const toolStarted = new Map();
     harnessStops.delete(session);
     reportNow("waiting for the model");
     // Every entry says which agent it is from, and what it runs on - for reading one agent at a time.
@@ -348,6 +351,7 @@ async function askOnce(session, text, onDelta) {
             }
         }
         if (event.type === "tool_execution_start") {
+            toolStarted.set(event.toolCallId, Date.now());
             const args = JSON.stringify(event.args ?? {});
             transcript({ kind: "tool", text: `${shownName(event.toolName)} ${clipText(args, MAX_TOOL_ARGS)}`, full: `${shownName(event.toolName)} ${args}` });
             const took = Date.now() - stepStarted;
@@ -369,6 +373,9 @@ async function askOnce(session, text, onDelta) {
                 stopTurn(session, `${failing} ${shownName(event.toolName)} calls failed in a row`);
             }
             const output = resultText(event.result);
+            const started = toolStarted.get(event.toolCallId);
+            toolStarted.delete(event.toolCallId);
+            record({ kind: "tool.call", tool: event.toolName, ms: started !== undefined ? Date.now() - started : 0, ok: !event.isError, resultChars: output.length }, { agent: modelEventOf(session) });
             transcript({ kind: "result", text: clipText(output, MAX_TOOL_RESULT), error: event.isError, full: output });
             const line = describeToolResult(event.toolName, event.result, event.isError);
             if (line !== undefined)
@@ -483,6 +490,7 @@ async function askOnce(session, text, onDelta) {
     // A turn turri ended is ended, whatever the provider was doing then: what comes back of the abort is not the provider failing.
     if (providerError !== undefined && stoppedFor === undefined) {
         debug?.note(`turn ended with a provider error after ${seconds(Date.now() - turnStarted)}: ${providerError}`);
+        record({ kind: "provider.error", error: firstLine(providerError, 300), transient: TRANSIENT_PROVIDER_ERROR.test(providerError) }, { agent: modelEventOf(session) });
         throw new ProviderError(`${session.model?.id ?? "model"}: ${providerError}`);
     }
     debug?.note(`turn finished after ${seconds(Date.now() - turnStarted)}`);
@@ -659,6 +667,11 @@ export function guardRepeats(tools, session, budget) {
     // Calls refused in the restricted turn under way, and which turn's set that was.
     let refused = 0;
     let refusedIn;
+    /** The agent a refusal is of, for the ledger. */
+    const guardPlace = () => {
+        const current = session();
+        return current !== undefined ? { agent: modelEventOf(current) } : {};
+    };
     return tools.map((tool) => ({
         ...tool,
         execute: async (...args) => {
@@ -669,6 +682,7 @@ export function guardRepeats(tools, session, budget) {
                 if (refusedIn !== only)
                     (refused = 0), (refusedIn = only);
                 refused += 1;
+                record({ kind: "guard.refused", rule: "restricted", tool: tool.name, times: refused }, guardPlace());
                 if (refused > REFUSED_BEFORE_STOP) {
                     reportActivity(`  stopped the agent's turn: ${refused} calls to tools this turn does not have`);
                     stopTurn(current, `${refused} calls to tools this turn does not have`);
@@ -679,6 +693,7 @@ export function guardRepeats(tools, session, budget) {
             }
             calls += 1;
             if (budget !== undefined && !budget.finish.includes(tool.name) && calls > budget.calls) {
+                record({ kind: "guard.refused", rule: "budget", tool: tool.name, times: calls - budget.calls }, guardPlace());
                 if (calls > budget.calls * 2) {
                     reportActivity(`  stopped the agent's turn: ${calls} tool calls, past its budget of ${budget.calls}`);
                     stopTurn(session(), `${calls} tool calls, past its budget of ${budget.calls}`);
@@ -707,6 +722,8 @@ export function guardRepeats(tools, session, budget) {
                 // Anything else may have changed what a look would find.
                 looks.clear();
             }
+            if (repeats > REPEATS_ALLOWED)
+                record({ kind: "guard.refused", rule: "repeat", tool: tool.name, times: repeats }, guardPlace());
             if (repeats > REPEATS_BEFORE_STOP) {
                 reportActivity(`  stopped the agent's turn: it made the same ${tool.name} call ${repeats} times with nothing changed`);
                 stopTurn(session(), `the same ${tool.name} call ${repeats} times with nothing changed`);
@@ -736,11 +753,14 @@ export function guardRepeats(tools, session, budget) {
  * start that has forgotten what it just wrote.
  */
 export async function createExecutor(opts) {
-    // Saved to disk, in the project: an agent's session is the record of what it did, and the
-    // only way to pick a long run back up after the process that ran it is gone.
+    // Saved to disk, in the project, for an agent picked back up after the process that ran it is gone - a skill's run -
+    // and in debug mode, as the record of what each did. Nothing else reads one back: the rest are kept in memory.
+    const project = projectRootOf(opts.cwd);
     const sessionManager = opts.resumeFrom !== undefined
         ? SessionManager.open(opts.resumeFrom)
-        : SessionManager.create(opts.cwd, sessionsDir(projectRootOf(opts.cwd)));
+        : opts.saveSession === true || debugMode(project)
+            ? SessionManager.create(opts.cwd, sessionsDir(project))
+            : SessionManager.inMemory(opts.cwd);
     // An agent that writes and runs code - given the harness's run its reports are checked against - can say the machine
     // lacks what the work needs: its turn ends, and the pulse stops with it. Observers, explorers and judges cannot.
     const hasShell = opts.customTools.some((tool) => tool.name === "bash") && opts.checkEnvironment !== undefined;

package/dist/regenerate/activity.d.ts

@@ -36,6 +36,9 @@ export interface ActivitySink {
         kind: string;
         summary: string;
     };
+    /** The project the job works in, and its module: where what it does is recorded (ledger.ts). */
+    project?: string;
+    module?: string;
     /** The spec was found to contradict itself - for the person to decide. */
     specConflict?(conflict: SpecConflict): void;
     /** The functional spec being built now, or nothing when none is. */
@@ -89,6 +92,12 @@ export declare function currentJob(): {
     kind: string;
     summary: string;
 } | undefined;
+/** Where this code runs: the job it runs for, its project and its module - each when it runs for one. */
+export declare function currentPlace(): {
+    job?: string;
+    project?: string;
+    module?: string;
+};
 /**
  * The conversation an agent is having, as it happens: what it was asked, what it wrote and
  * thought, what it called and what came back. Text and thinking arrive as deltas and are

package/dist/regenerate/activity.js

@@ -22,6 +22,17 @@ export function currentStopSignal() {
 export function currentJob() {
     return store.getStore()?.job;
 }
+/** Where this code runs: the job it runs for, its project and its module - each when it runs for one. */
+export function currentPlace() {
+    const sink = store.getStore();
+    if (sink === undefined)
+        return {};
+    return {
+        ...(sink.job !== undefined ? { job: sink.job.id } : {}),
+        ...(sink.project !== undefined ? { project: sink.project } : {}),
+        ...(sink.module !== undefined ? { module: sink.module } : {}),
+    };
+}
 export function reportTranscript(entry) {
     store.getStore()?.transcript(entry);
 }

package/dist/regenerate/agent-env.d.ts

@@ -28,6 +28,13 @@ export declare function agentEnvironment(moduleDir: string, options?: {
     hostEnv?: NodeJS.ProcessEnv;
     home?: string;
 }): AgentEnvironment;
+/**
+ * Hold the package caches of a scratch area to `keepMb` megabytes: past it, the caches least recently written go whole -
+ * a package manager's folder in `cache`, or a tool's in an agent's home - until it is under. A cache is as recent as the
+ * newest thing written anywhere in it: a package manager writes deep inside its folder, never beside it. What goes is
+ * downloaded again when it is wanted. Never a reason for the work to fail.
+ */
+export declare function tidyCaches(scratch: string, keepMb: number): void;
 /**
  * On macOS, what a program asks the system for as the per-user temporary folder - not TMPDIR - is that folder with this
  * suffix added: a folder of the module's own inside it. The JVM keeps its attach sockets there (`.java_pid<pid>`), which

package/dist/regenerate/agent-env.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import { readProjectConfig, stackOf } from "../config.js";
+import { DEFAULT_CACHE_KEEP_MB, readProjectConfig, stackOf } from "../config.js";
 import { registerSecrets } from "./masking.js";
 import { projectRootOf, modulesScratchDir } from "./paths.js";
 /**
@@ -12,9 +12,9 @@ import { projectRootOf, modulesScratchDir } from "./paths.js";
  * agent, and an agent's command - or the code it runs - could read any of them. So only an allow-list passes: the path,
  * the locale, the terminal, the user, and the variables that locate the host's toolchains. Then turri's own: a HOME of
  * the module's own, kept between pulses, so a tool's settings and an agent's dotfiles never land in the person's; a
- * TMPDIR; the package caches in the project, so a dependency downloads once; and git stopped at the module, so a
- * project that is itself a repository is not found from the code. Last, what the project passes on purpose -
- * `agent-env:` in its config - which never replaces turri's own.
+ * TMPDIR; the package caches in the project, so a dependency downloads once - held to `cache-keep:`; and git stopped
+ * at the module, so a project that is itself a repository is not found from the code. Last, what the project passes on
+ * purpose - `agent-env:` in its config - which never replaces turri's own.
  */
 /** Passed from the host as they are. */
 const ALLOWED = ["PATH", "LANG", "TERM", "TZ", "USER", "LOGNAME", "COLORTERM"];
@@ -62,11 +62,18 @@ export function cacheEnv(cache) {
         GRADLE_USER_HOME: join(cache, "gradle"),
         CARGO_HOME: join(cache, "cargo"),
         npm_config_cache: join(cache, "npm"),
+        // node-gyp's headers, which it keeps in the home folder - a copy each module's - once for the project.
+        npm_config_devdir: join(cache, "node-gyp"),
         YARN_CACHE_FOLDER: join(cache, "yarn"),
         PIP_CACHE_DIR: join(cache, "pip"),
         UV_CACHE_DIR: join(cache, "uv"),
         GOCACHE: join(cache, "go-build"),
         GOMODCACHE: join(cache, "go-mod"),
+        // The browsers the end-to-end test tools download - hundreds of megabytes each, kept in the home folder: once for
+        // the project, not once a module.
+        PLAYWRIGHT_BROWSERS_PATH: join(cache, "ms-playwright"),
+        PUPPETEER_CACHE_DIR: join(cache, "puppeteer"),
+        CYPRESS_CACHE_FOLDER: join(cache, "Cypress"),
     };
 }
 /** The git identity an agent's commits in a scratch repository get - never the person's. */
@@ -101,9 +108,123 @@ export function agentEnvironment(moduleDir, options = {}) {
     Object.assign(env, turrisOwn(module, name));
     return { env, passed: Object.keys(values).sort(), values, missing };
 }
+/** The scratch areas whose caches this process has held to `cache-keep:`: once a run, before its first command. */
+const tidied = new Set();
+/** Where in an agent's home folder its tools keep caches of their own. */
+const HOME_CACHES = [join("Library", "Caches"), ".cache"];
+/**
+ * Hold the package caches of a scratch area to `keepMb` megabytes: past it, the caches least recently written go whole -
+ * a package manager's folder in `cache`, or a tool's in an agent's home - until it is under. A cache is as recent as the
+ * newest thing written anywhere in it: a package manager writes deep inside its folder, never beside it. What goes is
+ * downloaded again when it is wanted. Never a reason for the work to fail.
+ */
+export function tidyCaches(scratch, keepMb) {
+    const caches = [];
+    const folders = [join(scratch, "cache")];
+    for (const home of entries(join(scratch, "home")))
+        for (const inHome of HOME_CACHES)
+            folders.push(join(scratch, "home", home, inHome));
+    for (const folder of folders) {
+        for (const name of entries(folder)) {
+            const path = join(folder, name);
+            try {
+                caches.push({ path, ...measure(path) });
+            }
+            catch {
+                /* gone meanwhile */
+            }
+        }
+    }
+    let total = caches.reduce((sum, cache) => sum + cache.bytes, 0);
+    for (const cache of caches.sort((a, b) => a.written - b.written)) {
+        if (total <= keepMb * 1024 * 1024)
+            break;
+        total -= cache.bytes;
+        // What could not be removed still counts: a cache half gone is not the room it took.
+        if (existsSync(cache.path))
+            total += remove(cache.path);
+    }
+}
+function entries(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** A file's or folder's bytes and when anything in it was last written, its links not followed. */
+function measure(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory())
+        return { bytes: stat.size, written: stat.mtimeMs };
+    let bytes = 0;
+    let written = stat.mtimeMs;
+    for (const name of entries(path)) {
+        try {
+            const inside = measure(join(path, name));
+            bytes += inside.bytes;
+            written = Math.max(written, inside.written);
+        }
+        catch {
+            /* gone meanwhile */
+        }
+    }
+    return { bytes, written };
+}
+/**
+ * Remove a cache whole, and say how many of its bytes are left. Some tools make what they cache read-only - Go's module
+ * cache, so it is never edited in place - and a folder that cannot be written cannot be emptied: each is made writable
+ * first, as `go clean -modcache` does.
+ */
+function remove(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        writable(path);
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch {
+            /* what cannot be removed stays */
+        }
+    }
+    try {
+        return existsSync(path) ? measure(path).bytes : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Every folder under `path` made writable by its owner, links not followed. */
+function writable(path) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isDirectory())
+            return;
+        chmodSync(path, stat.mode | 0o700);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries(path))
+        writable(join(path, name));
+}
 /** HOME, TMPDIR, the caches and git's ceiling: what no setting of the project's replaces. */
 function turrisOwn(module, name) {
     const scratch = modulesScratchDir(module);
+    if (!tidied.has(scratch)) {
+        tidied.add(scratch);
+        let keep = DEFAULT_CACHE_KEEP_MB;
+        try {
+            keep = readProjectConfig(projectRootOf(module)).cacheKeep ?? DEFAULT_CACHE_KEEP_MB;
+        }
+        catch {
+            /* a config that does not parse is said elsewhere: the default holds */
+        }
+        tidyCaches(scratch, keep);
+    }
     const fakeHome = join(scratch, "home", name);
     mkdirSync(fakeHome, { recursive: true });
     const gitconfig = join(fakeHome, ".gitconfig");

package/dist/regenerate/agent-shell.js

@@ -1,6 +1,7 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { readProjectConfig, stackOf } from "../config.js";
 import { reportNote } from "./activity.js";
+import { record } from "./ledger.js";
 import { agentEnvironment, DARWIN_TEMP_SUFFIX, packageCacheDir, TOOLCHAIN_VARIABLES } from "./agent-env.js";
 import { afterCommand, auditMessage, beforeCommand } from "./audit.js";
 import { checkCommand, machineReadable } from "./command-check.js";
@@ -67,6 +68,9 @@ export function agentShell(role, options = {}) {
             throw error;
         }
         const result = afterCommand(before);
+        if (result.putBack.length + result.left.length + result.lost.length + result.conversation.length > 0) {
+            record({ kind: "audit.putBack", putBack: result.putBack.length, left: result.left.length, lost: result.lost.length, conversation: result.conversation.length });
+        }
         if (result.putBack.length > 0)
             reportNote(`  an agent's command changed ${result.putBack.join(", ")} - put back`);
         if (result.left.length > 0)
@@ -90,6 +94,7 @@ export function agentShell(role, options = {}) {
         async run(command, runOptions = {}) {
             const checked = checkCommand(command, commandFence);
             if (!checked.ok) {
+                record({ kind: "command.refused", rule: checked.rule });
                 reportNote(`  refused an agent's command (${checked.rule}): ${command.length > 120 ? `${command.slice(0, 120)}...` : command}`);
                 const output = `Not run: ${checked.reason}`;
                 runOptions.onData?.(Buffer.from(output));

package/dist/regenerate/cases.js

@@ -64,6 +64,9 @@ export function conformanceCasesBlock(cases) {
     if (cases.patch.length > 0) {
         lines.push(`- Changed - its text, its acceptance tests, or a concept it uses: ${named(cases.patch)}.`, "  Its conformance tests exist: rewrite them to what it says now. The tests of everything else stay as they are.");
     }
+    if (cases.again.length > 0) {
+        lines.push(`- Regenerated again - its code was built anew, and its conformance tests were written against the code it replaced: ${named(cases.again)}.`, "  Its text did not change, but the code did. Run its tests against the new code. What they check that the", "  specification says stays checked: rewrite such a test only as the new code needs it reached. What they check", "  that the specification leaves open - a path, a field, a message, a format the old code chose and the", "  specification never names - is the new code's choice now: rewrite those checks to what the new code does,", "  or take them out. No test may hold the new code to what only the old code did. The tests of everything else", "  stay as they are.");
+    }
     if (cases.delete.length > 0)
         lines.push(`- Taken out - remove its conformance tests: ${named(cases.delete)}.`);
     if (cases.mechanical) {