@turri-dev/cli 0.1.8-next.e553476 → 0.1.8

package/README.md

@@ -1,7 +1,5 @@
 <p align="center"><img src="docs/images/turri-banner.gif" alt="turri, beside its mark - the first coding agent with the power of regenerative software: npm install -g @turri-dev/cli - and a pixel jellyfish regenerating, from a polyp on the sea floor"></p>
 
-<h1 align="center">turri<br>the first coding agent with the power of<br>regenerative software<br>&nbsp;</h1>
-
 <p align="center">
   <a href="https://www.npmjs.com/package/@turri-dev/cli"><img src="https://img.shields.io/npm/v/@turri-dev/cli?label=npm" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/@turri-dev/cli" alt="MIT licence"></a>
@@ -154,7 +152,7 @@ It asks you about the problem, the stack and the product, writes \*\*\*plain, an
 
 - 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/`;
+- 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 in the middle of a skill's interview (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;

package/dist/cli.js

@@ -81,6 +81,7 @@ const COMMANDS = {
     "spec-diff": { module: "./spec-diff-cli.ts", blurb: "apply a change to the specs, given as a git diff, and regenerate it" },
     validate: { module: "./validate-cli.ts", blurb: "validate a ***plain spec, regenerating nothing" },
     lineage: { module: "./lineage-cli.ts", blurb: "a module's lineage: what was regenerated into it, and when" },
+    ledger: { module: "./ledger-cli.ts", blurb: "what turri did here: the last runs and their pulses, or one pulse, from the ledger" },
     release: { module: "./release-cli.ts", blurb: "release what is regenerated to dist/<module> and activate it on this machine" },
     cultivate: { module: "./cultivate-cli.ts", blurb: "run a gated skill" },
 };
@@ -96,6 +97,7 @@ const USAGE = [
     "",
     `  ${"options".padEnd(12)} --harness-model <m>  the model you chat with   --coding-model <m>  the model renders run on`,
     `  ${"".padEnd(12)} --stack <name>  build with config.turri.<name>.yaml over config.turri.yaml - here and in every command`,
+    `  ${"".padEnd(12)} --debug  keep what turri writes for debugging it - agents' logs and sessions - as debug: true does`,
     `  ${"".padEnd(12)} --use-theme <t>  another theme than turri-dark - and every option of pi's own`,
     "",
     ...Object.entries(COMMANDS).map(([name, { blurb }]) => `  ${name.padEnd(12)} ${blurb}`),
@@ -109,7 +111,7 @@ const USAGE = [
 ].join("\n");
 dropNoise();
 // --stack <name>, for any command and for the conversation: the stack everything is built with (stacks.ts), taken out
-// before the rest is read - a command never sees it.
+// before the rest is read - a command never sees it. --debug too: TURRI_DEBUG for this run, and the pi it starts.
 const argv = await withoutStack(process.argv.slice(2));
 const [command, ...rest] = argv;
 async function withoutStack(args) {
@@ -121,6 +123,8 @@ async function withoutStack(args) {
             stack = args[++at] ?? "";
         else if (arg.startsWith("--stack="))
             stack = arg.slice("--stack=".length);
+        else if (arg === "--debug")
+            process.env.TURRI_DEBUG = "1";
         else
             kept.push(arg);
     }
@@ -173,7 +177,7 @@ process.argv = [
 // A headless run is stopped by a signal - SIGTERM, SIGHUP, Ctrl-C - whatever else listens for it: it exits, and what
 // its agents left running goes with it (shell.ts kills every process group on exit). Left to the libraries' own
 // handlers, one ran on for minutes after it was told to stop, building in the same codebase as the run after it.
-if (!["validate", "check", "drift", "lineage"].includes(command)) {
+if (!["validate", "check", "drift", "lineage", "ledger"].includes(command)) {
     for (const [signal, code] of [["SIGTERM", 143], ["SIGHUP", 129], ["SIGINT", 130]]) {
         process.on(signal, () => {
             console.error(`\nstopped (${signal})`);

package/dist/config-edit.d.ts

@@ -5,7 +5,7 @@
  * kept; `models:` and `agent-env:`, which nest, are written again whole, their own comments lost.
  */
 /** When a change takes effect. Nothing turri reads needs a restart: what is fixed at its start is changed live. */
-export type Effect = "now" | "next-message" | "next-pulse" | "next-plan" | "next-test-run" | "next-landing" | "next-regenerate";
+export type Effect = "now" | "next-message" | "next-pulse" | "next-plan" | "next-test-run" | "next-landing" | "next-regenerate" | "next-start";
 export type SettingKind = "boolean" | "choice" | "number" | "model" | "list" | "path" | "budget";
 export interface Setting {
     /** As written in the file - a nested one by its path: `models.coding`, `models.coding.turn-limit`, `agent-env.files`. */

package/dist/config-edit.js

@@ -11,6 +11,7 @@ export const EFFECT_TEXT = {
     "next-test-run": "in effect from the next test run - the running pulse's too",
     "next-landing": "in effect from the next pulse that lands - the running one too",
     "next-regenerate": "in effect for the next regeneration that names no .plain file",
+    "next-start": "in effect the next time turri starts here",
 };
 const SECONDS = ["0", "60", "120", "180", "300"];
 /** A role's line: which agents it is, for the list. */
@@ -75,6 +76,9 @@ export function settings(rules = []) {
         { key: "agent-env.files", about: "dotenv files whose variables the agents' commands get", kind: "list", unset: "none", effect: "next-pulse", projectOnly: true },
         { key: "agent-env.vars", about: "variables from turri's environment the agents' commands get, by name", kind: "list", unset: "none", effect: "next-pulse", projectOnly: true },
         { key: "toolchains", about: "folders of this machine an agent's commands may read beside the usual ones", kind: "list", unset: "none", effect: "next-pulse", projectOnly: true },
+        { key: "debug", about: "whether turri keeps what it writes for debugging it - agents' logs and sessions, pulse logs, outputs", kind: "boolean", unset: "false", effect: "next-pulse", projectOnly: true },
+        { key: "cache-keep", about: "megabytes of package caches the project keeps; 0 keeps none", kind: "number", options: ["0", "1024", "4096", "16384"], min: 0, unset: "4096", effect: "next-start", projectOnly: true },
+        { key: "ledger-keep", about: "megabytes of the ledger - what turri did, as facts - the project keeps; 0 keeps none", kind: "number", options: ["0", "50", "100", "500"], min: 0, unset: "100", effect: "next-start", projectOnly: true },
         ...roles,
     ];
 }

package/dist/config.d.ts

@@ -260,6 +260,23 @@ export interface ProjectConfig {
      * toolchain installed somewhere unusual. A module's own are added to the project's.
      */
     toolchains?: string[];
+    /**
+     * Megabytes of the ledger - what turri did, as facts, in .turri/ledger - the project keeps: past it, the oldest runs'
+     * are pruned when a run first writes. 0 keeps none, and writes none. The project's alone. Unset: 100.
+     */
+    ledgerKeep?: number;
+    /**
+     * Whether turri keeps what it writes for a person debugging it: every agent's whole log and saved session, each
+     * pulse's log, the testing scripts' and services' outputs, the agents' temporary files, and the dependencies installed
+     * in the modules a chain has left behind. Off, only what turri reads to work is kept. The project's alone. Unset: false.
+     */
+    debug?: boolean;
+    /**
+     * Megabytes of package caches - plain_modules/.turri/cache, and the caches in the agents' home folders - the project
+     * keeps: past it, the least recently written are removed when a run first starts an agent's command. 0 keeps none.
+     * The project's alone. Unset: 4096.
+     */
+    cacheKeep?: number;
     /** Each agent role's own model, thinking and turn limit; `default` for every role not named. */
     models?: Partial<Record<AgentRole | "default", RoleChoice>>;
     /** Seconds each turn of an agent a render starts has, for every role without its own. Unset: 120. 0: none. */
@@ -288,6 +305,9 @@ export declare const CONFIG_KEYS: {
     readonly maxLinesPerPulse: "max-lines-per-pulse";
     readonly agentEnv: "agent-env";
     readonly toolchains: "toolchains";
+    readonly ledgerKeep: "ledger-keep";
+    readonly debug: "debug";
+    readonly cacheKeep: "cache-keep";
     readonly models: "models";
     readonly turnLimit: "turn-limit";
 };
@@ -310,6 +330,13 @@ export declare function readProjectConfig(root: string, stack?: string): Project
  * edited. Never set in the conversation.
  */
 type RunOverrides = Partial<Pick<ProjectConfig, "harnessModel" | "codingModel" | "judgeModel" | "conformanceTests" | "review" | "mutationTesting">>;
+/** Megabytes of package caches a project keeps when `cache-keep:` does not say. */
+export declare const DEFAULT_CACHE_KEEP_MB = 4096;
+/**
+ * Whether turri keeps what it writes for a person debugging it, in this project: TURRI_DEBUG - `--debug` sets it, and
+ * `0` or `false` turns it off - else the project's `debug:`. Off by default.
+ */
+export declare function debugMode(project: string): boolean;
 /** Read a command's options as the config's keys for the rest of this process. */
 export declare function overrideConfig(overrides: RunOverrides): void;
 /** `--conformance-tests <value>`: the config's own values - all (or true), chosen, module, false. Undefined for anything else. */

package/dist/config.js

@@ -379,6 +379,9 @@ export const CONFIG_KEYS = {
     maxLinesPerPulse: "max-lines-per-pulse",
     agentEnv: "agent-env",
     toolchains: "toolchains",
+    ledgerKeep: "ledger-keep",
+    debug: "debug",
+    cacheKeep: "cache-keep",
     models: "models",
     turnLimit: "turn-limit",
 };
@@ -431,7 +434,7 @@ function readStackedConfig(root, stack) {
     // The project's alone: one conversation, one module built when none is named.
     const merged = { ...project };
     for (const key of Object.keys(CONFIG_KEYS)) {
-        if (key === "module" || key === "harnessModel" || key === "parallelJobs" || key === "rulesOff" || key === "compactAt" || key === "toolchains" || key === "agentEnv" || own[key] === undefined)
+        if (key === "module" || key === "harnessModel" || key === "parallelJobs" || key === "rulesOff" || key === "compactAt" || key === "ledgerKeep" || key === "debug" || key === "cacheKeep" || key === "toolchains" || key === "agentEnv" || own[key] === undefined)
             continue;
         merged[key] = own[key];
     }
@@ -443,6 +446,23 @@ function readStackedConfig(root, stack) {
     return withoutUndefined(merged);
 }
 let runOverrides = {};
+/** Megabytes of package caches a project keeps when `cache-keep:` does not say. */
+export const DEFAULT_CACHE_KEEP_MB = 4096;
+/**
+ * Whether turri keeps what it writes for a person debugging it, in this project: TURRI_DEBUG - `--debug` sets it, and
+ * `0` or `false` turns it off - else the project's `debug:`. Off by default.
+ */
+export function debugMode(project) {
+    const said = process.env.TURRI_DEBUG?.trim().toLowerCase();
+    if (said !== undefined && said !== "")
+        return said !== "0" && said !== "false";
+    try {
+        return readProjectConfig(project).debug === true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Read a command's options as the config's keys for the rest of this process. */
 export function overrideConfig(overrides) {
     runOverrides = { ...overrides };
@@ -542,6 +562,13 @@ function readConfigFile(path) {
             : undefined,
         maxSpecsPerPulse: positiveInteger(raw[CONFIG_KEYS.maxSpecsPerPulse]),
         maxLinesPerPulse: positiveInteger(raw[CONFIG_KEYS.maxLinesPerPulse]),
+        ledgerKeep: typeof raw[CONFIG_KEYS.ledgerKeep] === "number" && Number.isInteger(raw[CONFIG_KEYS.ledgerKeep]) && raw[CONFIG_KEYS.ledgerKeep] >= 0
+            ? raw[CONFIG_KEYS.ledgerKeep]
+            : undefined,
+        debug: typeof raw[CONFIG_KEYS.debug] === "boolean" ? raw[CONFIG_KEYS.debug] : undefined,
+        cacheKeep: typeof raw[CONFIG_KEYS.cacheKeep] === "number" && Number.isInteger(raw[CONFIG_KEYS.cacheKeep]) && raw[CONFIG_KEYS.cacheKeep] >= 0
+            ? raw[CONFIG_KEYS.cacheKeep]
+            : undefined,
         models: modelsSetting(raw[CONFIG_KEYS.models]),
         turnLimit: turnLimitSetting(raw[CONFIG_KEYS.turnLimit]),
     };

package/dist/extension.js

@@ -44,6 +44,9 @@ import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
 import { HISTORY_DIR, historyLog, historyShow } from "./regenerate/lineage.js";
 import { defaultBuildDir } from "./regenerate/paths.js";
 import { describeTurnIncident, describeUsage, onModelEvent } from "./regenerate/activity.js";
+import { ledgerWanted, startLedger } from "./regenerate/ledger.js";
+import { describePastPulse, describeRuns, earlierPulses, ledgerProjects } from "./regenerate/ledger-view.js";
+import { ledgerTool } from "./ledger-tools.js";
 import { describeSpecConflict } from "./regenerate/stop-report.js";
 import { inheritProviders, inheritThinkingLevel } from "./pi.js";
 import { beginCapture, captureConsole, describeCaptured, dropNoise } from "./quiet.js";
@@ -379,6 +382,24 @@ function turriExtension(pi, host) {
                 ctx.ui.notify(event.job !== undefined ? `${event.job}: ${line}` : line, "warning");
         });
     });
+    // What this session does, as facts, in the project's .turri/ledger - a pulse's own in its project. Said once, in the
+    // chat, when it cannot be written.
+    const ledgerTrouble = [];
+    let tellLedgerTrouble;
+    if (ledgerWanted()) {
+        startLedger({
+            mode: Object.keys(host).length > 0 ? "host" : "chat",
+            project: cwd,
+            warn: (message) => (tellLedgerTrouble !== undefined ? tellLedgerTrouble(message) : ledgerTrouble.push(message)),
+        });
+    }
+    pi.on("session_start", (_event, ctx) => {
+        if (!ctx.hasUI)
+            return;
+        tellLedgerTrouble = (message) => ctx.ui.notify(message, "warning");
+        for (const message of ledgerTrouble.splice(0))
+            tellLedgerTrouble(message);
+    });
     // What a turri that was killed left running - its commands' process groups - stopped as this one starts.
     const orphans = sweepOrphanedGroups();
     let orphansSaid = orphans === 0;
@@ -1448,28 +1469,40 @@ async function deliver(jobs, input) {
 const panelOpeners = new WeakMap();
 /** By registry: the last pulse that failed, stopped or did not pass, not yet looked at - ctrl+h opens on it. */
 const needsLooking = new WeakMap();
+/** What heads a pulse told from the ledger: it is not this session's, and the facts are all there is of it. */
+const pastPulseNote = "A pulse of an earlier session, as the ledger recorded it - facts, not its transcript. Its whole log is the file it names, " +
+    "for the read tool.";
 function registerJobTools(pi, jobs, cwd) {
     pi.registerTool({
         name: "diagnose",
         label: "Diagnose a pulse",
         description: "Why a pulse did not land, from its whole transcript: how it ended and its diagnosis, the stages that went wrong, the " +
             "last failing test run with its output, the last review that sent the work back, and the tool calls that failed - " +
-            "and where the whole log is.",
+            "and where the whole log is. A pulse of an earlier session is told from the ledger - what it recorded of it, as facts.",
         promptSnippet: "diagnose: why a pulse did not land, from its transcript",
         promptGuidelines: ["When a pulse failed or did not land, call diagnose before you explain it or change the spec: go by what happened, not by the report alone."],
         parameters: Type.Object({ job_id: Type.String({ description: "The pulse's id" }) }),
         async execute(_id, params) {
             const job = jobs.get(params.job_id);
-            if (job === undefined)
-                return { content: [{ type: "text", text: `No pulse ${params.job_id} has run in this session.` }], details: { status: "unknown" } };
-            return { content: [{ type: "text", text: whyFailed(job) }], details: { status: job.status } };
+            if (job === undefined) {
+                const past = describePastPulse(ledgerProjects(cwd), params.job_id);
+                if (past !== undefined)
+                    return { content: [{ type: "text", text: `${pastPulseNote}\n\n${past}` }], details: { status: "earlier" } };
+                return { content: [{ type: "text", text: `No pulse ${params.job_id} has run in this session, and the ledger has none by that id.` }], details: { status: "unknown" } };
+            }
+            // What the ledger recorded of it besides: its rounds, test runs, healers and commits, as facts.
+            const facts = describePastPulse(ledgerProjects(cwd), job.id);
+            const text = facts !== undefined ? `${whyFailed(job)}\n\nWhat the ledger recorded of it:\n${facts}` : whyFailed(job);
+            return { content: [{ type: "text", text }], details: { status: job.status } };
         },
     });
+    pi.registerTool(ledgerTool({ cwd }));
     pi.registerTool({
         name: "pulses",
         label: "Pulses",
         description: "What is regenerating: with no pulse, every pulse of this session - running, planned and finished - and what deploy started; " +
-            "with a pulse's id, that pulse - whether it is still running, its latest output, and its report once it has finished.",
+            "with a pulse's id, that pulse - whether it is still running, its latest output, and its report once it has finished. " +
+            "A pulse of an earlier session is told from the ledger.",
         promptSnippet: "pulses: every pulse, or one - what is regenerating and how it is going",
         parameters: Type.Object({
             job_id: Type.Optional(Type.String({ description: "The id returned when the pulse started. Omitted: every pulse" })),
@@ -1477,7 +1510,7 @@ function registerJobTools(pi, jobs, cwd) {
         }),
         async execute(_id, params) {
             if (params.job_id === undefined) {
-                return { content: [{ type: "text", text: listJobs(jobs) }], details: { status: "all" } };
+                return { content: [{ type: "text", text: listJobs(jobs, cwd) }], details: { status: "all" } };
             }
             const existing = jobs.get(params.job_id);
             const planned = shownJobs(jobs).find((job) => job.id === params.job_id && jobs.get(job.id) === undefined);
@@ -1488,6 +1521,9 @@ function registerJobTools(pi, jobs, cwd) {
                 };
             }
             if (existing === undefined) {
+                const past = describePastPulse(ledgerProjects(cwd), params.job_id);
+                if (past !== undefined)
+                    return { content: [{ type: "text", text: `${pastPulseNote}\n\n${past}` }], details: { status: "earlier" } };
                 const known = shownJobs(jobs).map((job) => job.id);
                 return {
                     content: [
@@ -1601,6 +1637,21 @@ function registerJobTools(pi, jobs, cwd) {
     const panelBeside = () => (panelDocked && panelTerminal !== undefined ? dockedWidth(paddedColumns(panelTerminal.columns)) : 0);
     // What is open in the pulse list and the map, and where their cursors are: the conversation's, as left each time it opens.
     const jobsTree = createJobsTreeState();
+    // Earlier sessions' pulses, from the ledger: read as the panel first shows them - they do not change while this one runs.
+    let earlier;
+    const earlierJobs = () => {
+        if (earlier !== undefined)
+            return earlier;
+        try {
+            const found = earlierPulses(ledgerProjects(cwd), new Set(jobs.list().map((job) => job.id)));
+            earlier = found.jobs;
+            jobsTree.earlierMore = found.more;
+        }
+        catch {
+            earlier = [];
+        }
+        return earlier;
+    };
     const mapState = createSpecMapState();
     // The map from the files - the .plain files asked for, else the project's - with the work loop's plan laid over them.
     const specMap = createSpecMapSource({
@@ -1694,6 +1745,7 @@ function registerJobTools(pi, jobs, cwd) {
             specMap.refresh();
             const view = createSidePanel({
                 jobs: () => shownJobs(jobs),
+                earlier: earlierJobs,
                 tree: jobsTree,
                 map: () => specMap.read(),
                 mapState,
@@ -1967,13 +2019,27 @@ function deployedLabel(name, what) {
 function shownJobs(jobs) {
     return [...(workLoops.get(jobs)?.loop.planned() ?? []), ...jobs.list()];
 }
-function listJobs(jobs) {
+function listJobs(jobs, cwd) {
     const all = [...shownJobs(jobs)].reverse().filter((job) => job.replacedBy === undefined);
     const deployed = runningDeployed().map((item) => `deploy ${item.name}  running  ${item.moduleName}: ${item.url ?? item.command}  (pid ${item.pid}, output in ${relative(process.cwd(), item.log) || item.log})`);
     const listed = deployed.length > 0 ? `\n\nActivated from dist - /halt activated <name> halts one:\n${deployed.join("\n")}` : "";
+    const before = earlierRuns(jobs, cwd);
     if (all.length === 0)
-        return `No pulses have been started.${listed}`;
-    return `${jobLines(all)}${listed}`;
+        return `No pulses have been started in this session.${listed}${before}`;
+    return `${jobLines(all)}${listed}${before}`;
+}
+/** Earlier sessions' last runs and their pulses, from the ledger - nothing when it has none. */
+function earlierRuns(jobs, cwd) {
+    try {
+        const found = earlierPulses(ledgerProjects(cwd), new Set(jobs.list().map((job) => job.id)));
+        if (found.runs.length === 0)
+            return "";
+        const more = found.more > 0 ? `\n\n${found.more} earlier run${found.more === 1 ? "" : "s"} beyond these are in the ledger.` : "";
+        return `\n\nEarlier sessions, from the ledger - pulses or diagnose with a pulse's id tells one:\n${describeRuns(found.runs)}${more}`;
+    }
+    catch {
+        return "";
+    }
 }
 function jobLines(all) {
     return all

package/dist/genome.js

@@ -136,6 +136,8 @@ export async function runSkill(opts) {
         rules: true,
         system: toolchainsBlock(),
         resumeFrom: resumed?.sessionFile,
+        // Its run picks it back up (resume) and the side questions read it (btw): saved whatever the mode.
+        saveSession: true,
     });
     const manifest = resumed ?? {
         skill: skill.name,

package/dist/host.d.ts

@@ -8,7 +8,7 @@ export { createTurriExtension, type TurriHost } from "./extension.ts";
 export type { AskUserIO } from "./ask.ts";
 /** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
-export { configForSpec, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf, type ProjectConfig } from "./config.ts";
+export { configForSpec, debugMode, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf, type ProjectConfig } from "./config.ts";
 export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.ts";
 export { BEDROCK_DEFAULT, BEDROCK_REGIONS, bedrockModels, initConfig, VENDORS, type BedrockChoice, type Vendor } from "./init-config.ts";
 export { checkPlainFile, type CheckResult } from "./plain/check.ts";
@@ -19,3 +19,5 @@ export { createWorkLoop, describeModules, functionalityCompletion, promptOf, typ
 export { createJobRegistry, defaultParallelJobs, type Job, type JobRegistry } from "./regenerate/jobs.ts";
 export { describeTurnIncident, onModelEvent, type TranscriptEntry } from "./regenerate/activity.ts";
 export { sweepOrphanedGroups } from "./regenerate/shell.ts";
+export { ledgerDir, onLedgerEvent, readLedger, type AgentRef, type LedgerEntry, type LedgerEvent, type LedgerKind, type LedgerQuery } from "./regenerate/ledger.ts";
+export { asJob, describePulseView, describeRuns, earlierPulses, ledgerProjects, pulseView, runViews, type PulseView, type RunView } from "./regenerate/ledger-view.ts";

package/dist/host.js

@@ -9,7 +9,7 @@ export { createTurriExtension } from "./extension.js";
 /** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
 // The project and its settings.
-export { configForSpec, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf } from "./config.js";
+export { configForSpec, debugMode, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf } from "./config.js";
 export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.js";
 // A project's first config.turri.yaml, as `turri init-config` writes it - the vendor whose models it takes chosen by the host.
 export { BEDROCK_DEFAULT, BEDROCK_REGIONS, bedrockModels, initConfig, VENDORS } from "./init-config.js";
@@ -23,3 +23,6 @@ export { createWorkLoop, describeModules, functionalityCompletion, promptOf } fr
 export { createJobRegistry, defaultParallelJobs } from "./regenerate/jobs.js";
 export { describeTurnIncident, onModelEvent } from "./regenerate/activity.js";
 export { sweepOrphanedGroups } from "./regenerate/shell.js";
+// What turri did, as facts: the ledger, heard live and read back - this session's pulses and every earlier one's.
+export { ledgerDir, onLedgerEvent, readLedger } from "./regenerate/ledger.js";
+export { asJob, describePulseView, describeRuns, earlierPulses, ledgerProjects, pulseView, runViews } from "./regenerate/ledger-view.js";

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/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;
     /**