@turri-dev/cli 0.1.8-next.b03162b → 0.1.8-next.bfcb24e

package/dist/extension.js

@@ -46,6 +46,7 @@ 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";
@@ -1489,9 +1490,13 @@ function registerJobTools(pi, jobs, cwd) {
                     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" } };
             }
-            return { content: [{ type: "text", text: whyFailed(job) }], details: { status: job.status } };
+            // 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",

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.",
+        ],
+        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/regenerate/ledger-view.d.ts

@@ -70,4 +70,23 @@ export declare function earlierPulses(projects: string[], known: Set<string>, ru
 };
 /** A pulse of the ledger's, as the lists show a job: finished as it ended, its time and cost - and nothing to run. */
 export declare function asJob(view: PulseView): Job;
+/** What to count in the ledger: kinds - whole, or a group by what comes before the dot - a module, since when. */
+export interface EventQuery {
+    /** `healer.failed`, or `healer` for every healer event. */
+    kinds?: string[];
+    module?: string;
+    /** Only events at or after this time. */
+    since?: Date;
+    /** How many of the most recent to list, a line each. */
+    limit?: number;
+}
+/** One event in a line: when, its pulse and module, its kind, its own fields - the agent's role when it has one. */
+export declare function eventLine(entry: LedgerEntry): string;
+/**
+ * The events of these projects' ledgers that `query` asks for: how many of each kind, and the most recent, a line each -
+ * or, when no kind asked for is in the ledger, the kinds it has.
+ */
+export declare function describeEvents(projects: string[], query?: EventQuery): string;
+/** `24h`, `7d`, `30m`, or a date and time: the moment it means, or undefined when it means none. */
+export declare function sinceOf(text: string, now?: number): Date | undefined;
 export {};

package/dist/regenerate/ledger-view.js

@@ -148,18 +148,25 @@ export function describePulseView(view) {
         lines.push(`  tried again (${retry.attempt} of ${retry.of}) after: ${retry.failure}`);
     if (view.rounds.size > 0)
         lines.push(`  rounds: ${[...view.rounds].map(([gate, { round, of }]) => `${gate} ${round} of ${of}`).join("; ")}`);
-    if (view.scripts.length > 0) {
-        const failing = view.scripts.filter((run) => run.exit !== 0);
+    // can_it_fail's runs, on code changed to break it, apart: one failing is a test that caught the bug.
+    const mutations = view.scripts.filter((run) => run.mutated === true);
+    const tests = view.scripts.filter((run) => run.mutated !== true);
+    if (tests.length > 0) {
+        const failing = tests.filter((run) => run.exit !== 0);
         const signatures = new Map();
         for (const run of failing)
             if (run.signature !== undefined)
                 signatures.set(run.signature, (signatures.get(run.signature) ?? 0) + 1);
         const most = Math.max(0, ...signatures.values());
-        const timedOut = view.scripts.filter((run) => run.timedOut).length;
-        lines.push(`  test runs: ${view.scripts.length}, ${failing.length} failing` +
+        const timedOut = tests.filter((run) => run.timedOut).length;
+        lines.push(`  test runs: ${tests.length}, ${failing.length} failing` +
             (most > 1 ? ` - ${most} of them the same way` : "") +
             (timedOut > 0 ? `, ${timedOut} stopped at the time limit` : ""));
     }
+    if (mutations.length > 0) {
+        const caught = mutations.filter((run) => run.exit !== 0 && !run.timedOut).length;
+        lines.push(`  can_it_fail: ${mutations.length} run${mutations.length === 1 ? "" : "s"} on code broken on purpose, ${caught} caught by the tests`);
+    }
     if (view.judge.size > 0)
         lines.push(`  the judge blamed: ${[...view.judge].map(([culprit, times]) => `${culprit} ${times}x`).join(", ")}`);
     if (view.reviews.length > 0)
@@ -284,3 +291,55 @@ export function asJob(view) {
         earlier: { run: view.run, ...(view.runMode !== undefined ? { runMode: view.runMode } : {}), lines: describePulseView(view).split("\n").slice(1).map((line) => line.replace(/^  /, "")) },
     };
 }
+/** The envelope's fields, said apart from an event's own. */
+const ENVELOPE = new Set(["v", "ts", "seq", "run", "job", "module", "agent", "kind"]);
+/** One event in a line: when, its pulse and module, its kind, its own fields - the agent's role when it has one. */
+export function eventLine(entry) {
+    const fields = Object.entries(entry)
+        .filter(([key]) => !ENVELOPE.has(key))
+        .map(([key, value]) => {
+        const text = typeof value === "string" ? JSON.stringify(value.length > 160 ? `${value.slice(0, 159)}…` : value) : JSON.stringify(value);
+        return `${key}=${text}`;
+    });
+    const where = [entry.job, entry.module, entry.agent?.role ?? entry.agent?.label].filter((part) => part !== undefined);
+    return [entry.ts.slice(0, 19).replace("T", " "), ...where, entry.kind, ...fields].join(" · ");
+}
+/**
+ * The events of these projects' ledgers that `query` asks for: how many of each kind, and the most recent, a line each -
+ * or, when no kind asked for is in the ledger, the kinds it has.
+ */
+export function describeEvents(projects, query = {}) {
+    const all = projects.flatMap((project) => readLedger(project, query.since !== undefined ? { since: query.since } : {}));
+    const inModule = query.module !== undefined ? all.filter((entry) => entry.module === query.module) : all;
+    const wanted = query.kinds?.map((kind) => kind.trim()).filter((kind) => kind !== "");
+    const matches = (kind) => wanted === undefined || wanted.length === 0 || wanted.some((asked) => kind === asked || kind.startsWith(`${asked}.`));
+    const found = inModule.filter((entry) => matches(entry.kind));
+    const scope = [query.module !== undefined ? `in ${query.module}` : "", query.since !== undefined ? `since ${query.since.toISOString().slice(0, 16).replace("T", " ")}` : ""].filter(Boolean).join(", ");
+    if (found.length === 0) {
+        const kinds = [...new Set(inModule.map((entry) => entry.kind))].sort();
+        return `No ${wanted !== undefined && wanted.length > 0 ? wanted.join(", ") : ""} events${scope !== "" ? ` ${scope}` : ""} in the ledger.${kinds.length > 0 ? ` It has: ${kinds.join(", ")}.` : ""}`;
+    }
+    const counts = new Map();
+    for (const entry of found)
+        counts.set(entry.kind, (counts.get(entry.kind) ?? 0) + 1);
+    const pulses = new Set(found.map((entry) => entry.job).filter((job) => job !== undefined)).size;
+    const runs = new Set(found.map((entry) => entry.run)).size;
+    const limit = Math.max(1, query.limit ?? 20);
+    const recent = found.slice(-limit);
+    return [
+        `${found.length} event${found.length === 1 ? "" : "s"}${scope !== "" ? ` ${scope}` : ""}, in ${runs} run${runs === 1 ? "" : "s"} and ${pulses} pulse${pulses === 1 ? "" : "s"}: ${[...counts].sort((a, b) => b[1] - a[1]).map(([kind, times]) => `${kind} ${times}`).join(", ")}`,
+        "",
+        recent.length === found.length ? "Each, oldest first:" : `The last ${recent.length}, oldest first:`,
+        ...recent.map(eventLine),
+    ].join("\n");
+}
+/** `24h`, `7d`, `30m`, or a date and time: the moment it means, or undefined when it means none. */
+export function sinceOf(text, now = Date.now()) {
+    const relative = /^(\d+)\s*([mhd])$/i.exec(text.trim());
+    if (relative !== null) {
+        const unit = { m: 60_000, h: 3_600_000, d: 86_400_000 }[relative[2].toLowerCase()];
+        return new Date(now - Number(relative[1]) * unit);
+    }
+    const date = new Date(text.trim());
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}

package/dist/regenerate/ledger.d.ts

@@ -131,6 +131,7 @@ export type LedgerEvent = {
     ms: number;
     timedOut: boolean;
     inPlace: boolean;
+    mutated?: boolean;
     signature?: string;
 } | {
     kind: "gate.round";

package/dist/regenerate/test-scripts.js

@@ -378,6 +378,8 @@ async function runScript(cwd, script, args, logDir, options = {}) {
         ms: run.elapsedMs,
         timedOut: run.timedOut === true,
         inPlace: options.named === undefined,
+        // On code changed for the run - can_it_fail's bug: failing is what it is for.
+        ...(options.mutated === true ? { mutated: true } : {}),
         ...(run.exitCode !== 0 ? { signature: signatureHash(failureSignature(run)) } : {}),
     });
     return run;
@@ -417,10 +419,10 @@ function quote(path) {
     return `'${path.replace(/'/g, "'\\''")}'`;
 }
 /** A testing script run on a fresh copy of the code: the project's script copied fresh into the staging folder, beside it. */
-async function runOnCopy(stagingRoot, script, args, logDir, limitMs) {
+async function runOnCopy(stagingRoot, script, args, logDir, limitMs, mutated) {
     const copy = join(stagingRoot, basename(script));
     writeFileSync(copy, readFileSync(script));
-    return runScript(stagingRoot, script, args, logDir, { named: copy, ...(limitMs !== undefined ? { limitMs } : {}) });
+    return runScript(stagingRoot, script, args, logDir, { named: copy, ...(limitMs !== undefined ? { limitMs } : {}), ...(mutated === true ? { mutated } : {}) });
 }
 /**
  * The harness's run of the unit testing script on the code as it is now - and run_unit_tests'.
@@ -486,7 +488,7 @@ limitMs) {
         return run;
     };
     if (project.inPlace) {
-        const inPlace = () => runScript(project.root, script, [resolve(buildDir)], buildDir, limitMs !== undefined ? { limitMs } : {});
+        const inPlace = () => runScript(project.root, script, [resolve(buildDir)], buildDir, { ...(limitMs !== undefined ? { limitMs } : {}), ...(change !== undefined ? { mutated: true } : {}) });
         const started = Date.now();
         if (change === undefined)
             return passed(await inPlace(), started);
@@ -501,7 +503,7 @@ limitMs) {
         if (change !== undefined)
             writeFileSync(join(staging.build, change.file), change.text);
         const started = Date.now();
-        return passed(await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs), started);
+        return passed(await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs, change !== undefined), started);
     }
     finally {
         rmSync(staging.root, { recursive: true, force: true });

package/docs/development.md

@@ -57,7 +57,7 @@ The workflow signs in to npm with npm's trusted publishing (OIDC), not a token:
 | `src/screen-padding.ts` | the blank row above and below the whole screen and the two columns either side, in both of pi's ways of drawing it |
 | `src/regenerate/spec-map.ts`, `src/regenerate/spec-map-view.ts` | regen: each item's mark, from the records, the `.plain` files and the work loop's plan (`mapPlan`), and the map drawn |
 | `src/regenerate/debug-log.ts` | each render agent's whole conversation, always streamed to `.turri/debug/` |
-| `src/regenerate/ledger.ts`, `src/regenerate/ledger-view.ts`, `src/ledger-cli.ts` | the ledger: what turri did, as typed facts, in `.turri/ledger/` - `record()`, read back for `pulses`, `diagnose` and `turri ledger` - see [the ledger](using.md#the-ledger) |
+| `src/regenerate/ledger.ts`, `src/regenerate/ledger-view.ts`, `src/ledger-tools.ts`, `src/ledger-cli.ts` | the ledger: what turri did, as typed facts, in `.turri/ledger/` - `record()`, read back for the `ledger` tool, `pulses`, `diagnose` and `turri ledger` - see [the ledger](using.md#the-ledger) |
 | `genome/` | what turri knows and can do: `genome/skills/`, the skill library, and `genome/rules/`, the \*\*\*plain authoring rules |
 
 ## Known edges

package/docs/using.md

@@ -36,7 +36,8 @@ While a skill runs, a line above the input shows its phases, every one by name -
 | `engine` | show or choose the model the code is regenerated on - see [below](#choosing-a-model) |
 | `pulses` | the pulses - running, planned and finished - or one of them |
 | `halt` | halt a pulse, a module's planned pulses, or what `activate` started |
-| `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed |
+| `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed - and what the [ledger](#the-ledger) recorded of it |
+| `ledger` | what turri did, from the [ledger](#the-ledger), this session's and every earlier one's: a pulse as facts, by its id - its rounds, test runs, verdicts, healers, refusals and commits; events of some kinds counted and listed, for a module or since a time - `healer.failed`, or `healer` for the group; or the last runs, a line a pulse |
 | `lineage` | a module's lineage: what each regeneration and conformance run changed in it, and what it was regenerated from |
 | `cultivate` | run a gated skill, its steps and review gates enforced |
 | `release`, `activate` | try what is regenerated: release it to `dist/<module>` and activate it on this machine, installing what it needs - see [deploy](deploy.md) |
@@ -182,7 +183,7 @@ It is in `.turri/ledger/` in the project, a JSON line an event, one file a run -
 | pulses | `job.queued`, `job.started`, every `job.stage`, `job.retried`, `job.finished` - its status, whether it landed, how long it ran, what it cost, how it ended |
 | the work loop | `loop.halted`, `loop.stopped` (a pulse the spec moved on from), `planner.failed`, `planner.fellBack` |
 | the model | `model.call` (time and tokens), `model.turn`, `model.compaction`, `provider.retry`, `provider.stall`, `provider.error`, `turn.stopped` (a turn turri ended itself, and why) |
-| tools and tests | `tool.call` (the tool, how long, whether it failed - never its arguments or result), `script.run` (the testing script, its exit, how long, whether the time limit stopped it, the failure's fingerprint) |
+| tools and tests | `tool.call` (the tool, how long, whether it failed - never its arguments or result), `script.run` (the testing script, its exit, how long, whether the time limit stopped it, the failure's fingerprint, and `mutated` for a `can_it_fail` run on code broken on purpose) |
 | the gates | `gate.round`, `review.verdict`, `arbiter.ruling`, `judge.verdict` |
 | what turri refused | `guard.refused` (a repeated call, a call past its budget, a tool the turn does not have), `command.refused`, `audit.putBack` |
 | the healers | `healer.started`, `healer.ended` with what it found, `healer.failed` and why - the debugger, the diagnosis of a failed pulse |
@@ -191,7 +192,7 @@ It is in `.turri/ledger/` in the project, a JSON line an event, one file a run -
 
 Never in it: prompts, replies, thinking, tool arguments and results, file contents. What an event does carry - a stage, an error's first line - is masked as the logs are.
 
-`turri ledger` prints the last runs, a line a pulse; `turri ledger <pulse>` one pulse - its rounds, its test runs and how many failed the same way, the verdicts, the healers, what turri refused, what its history recorded, its log; `--json` the events themselves, for `jq`. In the chat, `pulses` lists the last three earlier runs under this session's pulses, and `pulses` and `diagnose` tell one of them by its id; the side panel's pulses list has them as **earlier sessions** (see [the side panel](#in-a-conversation)).
+`turri ledger` prints the last runs, a line a pulse; `turri ledger <pulse>` one pulse - its rounds, its test runs and how many failed the same way, the verdicts, the healers, what turri refused, what its history recorded, its log; `--json` the events themselves, for `jq`. In the chat, `ledger` is the way in - a pulse of this session or an earlier one, the events of some kinds counted (how often the debugger failed this week: `kinds: [healer.failed], since: 7d`), the last runs - and `pulses` lists the last three earlier runs under this session's pulses, `pulses` and `diagnose` tell one of them by its id, and `diagnose` adds the ledger's facts to a pulse of this session; the side panel's pulses list has them as **earlier sessions** (see [the side panel](#in-a-conversation)).
 
 It is for looking up, never for deciding: what to build comes from the records alone (see [what the code is built from](regenerating.md#what-the-code-is-built-from)), so deleting `.turri/ledger/` loses nothing but what can be looked up. When a run first writes to the project, the files of runs that have ended are gzipped and the oldest pruned past `ledger-keep:` megabytes - 100 unset, `0` for none at all; a run still going is never touched. `.turri` ignores itself, so the ledger is never committed, and nothing of it is sent anywhere. A ledger that cannot be written is said once and given up on, never failing the work.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.8-next.b03162b",
+  "version": "0.1.8-next.bfcb24e",
   "license": "MIT",
   "type": "module",
   "repository": {