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

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>
@@ -49,7 +47,7 @@ turri init-config --vendor anthropic
 
 It then tells you which API key to set - or to type `/login` once **turri** is running instead. **turri** loads the `config.turri.yaml` in the folder you start it from. Below the two models, the file sets every other setting to its default - change any of them in the file, or from the chat with `/turri-config`. Any other model works too: [models](#models).
 
-Once `turri` is running, say: *Let's start a new project: a small API where people can register and sign in.*
+Once `turri` is running, type: `/spawn a small API where people can register and sign in` - or `/brood` for an interview that settles each feature with you first.
 
 No project of your own yet? Build one of [**the examples**](examples/README.md) with turri, step by step.
 
@@ -146,11 +144,11 @@ cd ~/my-project
 turri
 ```
 
-Then talk to it:
+Then start the interview:
 
-> Let's start a new project: a small API where people can register and sign in.
+> /brood a small API where people can register and sign in
 
-It runs the interview skill, asks you about the problem, the stack and the product, writes \*\*\*plain, and builds each functionality as it is written. While it works:
+It asks you about the problem, the stack and the product, writes \*\*\*plain, and builds each functionality as it is written. While it works:
 
 - the **panel** above the input shows every build - its stage, what its agents are doing, its model and cost - and the queue behind it;
 - ask to try it at any time - "let me try it" - and **`release`** puts what is built so far in `dist/<module>` and **`activate`** starts it, installing what it needs - nothing to approve;
@@ -188,7 +186,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | | |
 | --- | --- |
 | [Installation](docs/installation.md) | doctor, what turri needs of this machine, **turri** and `pi`, environment variables |
-| [Examples](examples/README.md) | projects to build with turri step by step: cognio from an empty folder, guestbook - a backend and a frontend in minutes - a CLI, a backend service with conformance tests, a REST API integration |
+| [Examples](examples/README.md) | projects to build with turri step by step: guestbook - a backend and a frontend in minutes - a CLI, and a backend service with conformance tests |
 | [Using **turri**](docs/using.md) | the conversation, skills, tools, pulses and regen, choosing models, the command line |
 | [The project config](docs/config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](docs/deploy.md) | trying what is built: the last commit in `dist/<module>`, started on your machine, nothing installed without asking |

package/dist/btw.d.ts

@@ -53,6 +53,8 @@ export interface SideQuestion {
     projectDir: string;
     /** turri's own folder: its source, skills, rules and docs. */
     harnessDir: string;
+    /** A host's surface, in its own words (TurriHost.surface): where the person watches the work instead of the terminal. */
+    surface?: string;
 }
 export declare function sideQuestionPrompt(side: SideQuestion): string;
 /** Answers a side question with an agent of its own, read only, on `model`. */

package/dist/btw.js

@@ -12,7 +12,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { confinedTools } from "./regenerate/confine.js";
-import { TURRI_IDENTITY } from "./identity.js";
+import { conversationIdentity } from "./identity.js";
 import { ask, BEGIN, createExecutor } from "./pi.js";
 /** How many tool calls the side agent may make before it is told to answer. */
 export const SIDE_CALLS = 20;
@@ -85,7 +85,7 @@ export function skillSessionText(runDir, maxChars = SKILL_SESSION_CHARS) {
 }
 export function sideQuestionPrompt(side) {
     return [
-        TURRI_IDENTITY,
+        conversationIdentity(side.surface),
         "",
         "The person is in the middle of something with you - a skill, a pulse - and has asked you a question on the side",
         "with /btw. Answer it as turri: in the first person, to them, in whole sentences - briefly and plainly, from what is",

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" },
 };
@@ -173,7 +174,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,7 @@ 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: "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,11 @@ 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;
     /** 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 +293,7 @@ export declare const CONFIG_KEYS: {
     readonly maxLinesPerPulse: "max-lines-per-pulse";
     readonly agentEnv: "agent-env";
     readonly toolchains: "toolchains";
+    readonly ledgerKeep: "ledger-keep";
     readonly models: "models";
     readonly turnLimit: "turn-limit";
 };

package/dist/config.js

@@ -379,6 +379,7 @@ export const CONFIG_KEYS = {
     maxLinesPerPulse: "max-lines-per-pulse",
     agentEnv: "agent-env",
     toolchains: "toolchains",
+    ledgerKeep: "ledger-keep",
     models: "models",
     turnLimit: "turn-limit",
 };
@@ -431,7 +432,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 === "toolchains" || key === "agentEnv" || own[key] === undefined)
             continue;
         merged[key] = own[key];
     }
@@ -542,6 +543,9 @@ 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,
         models: modelsSetting(raw[CONFIG_KEYS.models]),
         turnLimit: turnLimitSetting(raw[CONFIG_KEYS.turnLimit]),
     };

package/dist/extension.d.ts

@@ -41,6 +41,17 @@ export interface TurriHost {
     onPlanChange?(): void;
     /** The dialogs ask_user puts its questions in - the conversation's and a skill's interview - instead of the terminal's. */
     dialogs?: AskUserIO;
+    /**
+     * The host's own UI, in its own words: the views it has in place of the terminal's, what its marks and buttons mean,
+     * where questions appear. Given, turri tells the model none of the terminal's - its keys, the side panel, regen,
+     * /pulses - and gives it this instead, as a `<surface>` block in turri's identity. Absent, the terminal is the surface.
+     */
+    surface?: string;
+    /**
+     * The last word on the whole system prompt, as turri has built it for this turn - after its own before_agent_start
+     * work: what it returns is what is sent. For a host that needs to change anything else.
+     */
+    systemPrompt?(prompt: string): string;
 }
 /** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
 export declare function createTurriExtension(host?: TurriHost): (pi: ExtensionAPI) => void;

package/dist/extension.js

@@ -44,6 +44,8 @@ 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 { describeSpecConflict } from "./regenerate/stop-report.js";
 import { inheritProviders, inheritThinkingLevel } from "./pi.js";
 import { beginCapture, captureConsole, describeCaptured, dropNoise } from "./quiet.js";
@@ -53,13 +55,14 @@ import { describeStdlib } from "./stdlib.js";
 import { peekKeyListener, runAsk } from "./ask.js";
 import { QuestionDialog } from "./question-dialog.js";
 import { registerStacks } from "./stacks.js";
-import { catalogueLine, discoverSkills, leftOutNote } from "./skills.js";
+import { catalogueLine, createCommandGate, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
-import { TURRI_IDENTITY } from "./identity.js";
+import { conversationIdentity } from "./identity.js";
+import { setSurface, surfaceOf } from "./surface.js";
 import { turriIdentity } from "./environment.js";
 import { conformanceChooser } from "./regenerate/choose-conformance.js";
 import { answerSideQuestion, askWithAsides, BTW_HOW, runningSkill, skillRunStarted, skillSessionText, transcriptOf } from "./btw.js";
-import { createJobRegistry, defaultParallelJobs, describeJob, formatDuration, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
+import { createJobRegistry, defaultParallelJobs, describeJob, firstRegeneration, formatDuration, formatElapsed, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
 /**
  * Makes gated skills reachable from a conversation.
  *
@@ -180,6 +183,14 @@ export function chatAskUserTool(dialogs) {
         },
     };
 }
+/**
+ * The conversation's system prompt for a turn: pi's, turri's identity - with the host's surface in place of the
+ * terminal's, when it has one - and turri's blocks; then the host's last word on it.
+ */
+function conversationSystemPrompt(base, host, blocks) {
+    const prompt = [base, conversationIdentity(host.surface), ...blocks].filter((part) => part !== "").join("\n\n");
+    return host.systemPrompt !== undefined ? host.systemPrompt(prompt) : prompt;
+}
 /** The host each conversation's jobs report to, for the work loop made for them later. */
 const hosts = new WeakMap();
 /** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
@@ -260,6 +271,8 @@ function turriExtension(pi, host) {
         },
     });
     hosts.set(jobs, host);
+    // What the model is told of where the person watches the work, deep in the tools too: the host's surface, or the terminal.
+    setSurface(jobs, host.surface);
     host.onJobs?.(jobs);
     // The ***plain rules go into the system prompt in full, every turn. The block is
     // identical each time, so it sits inside the cached prefix rather than invalidating it.
@@ -298,7 +311,7 @@ function turriExtension(pi, host) {
             }
         }
         return {
-            systemPrompt: [event.systemPrompt, TURRI_IDENTITY, TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()].filter((part) => part !== "").join("\n\n"),
+            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
         };
     });
     // The conversation's agent does not run turri again through its shell, unless the person
@@ -314,7 +327,7 @@ function turriExtension(pi, host) {
         if (event.toolName === "bash" && typeof command === "string") {
             const what = selfInvocation(command);
             if (what !== undefined && !askedForCommandLine(lastUserMessage))
-                return { block: true, reason: refusal(what) };
+                return { block: true, reason: refusal(what, surfaceOf(jobs)) };
         }
         markConversationWrite(event.toolCallId, event.toolName, event.input);
         return undefined;
@@ -368,6 +381,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;
@@ -416,6 +447,19 @@ function turriExtension(pi, host) {
         return;
     const catalogue = skills.map(catalogueLine).join("\n");
     const pendingNote = leftOutNote(discoveredSkills);
+    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
+    // once its command is typed. The command puts what was typed in the chat, as the person's message, for the model to
+    // run it with what follows as its context.
+    const gate = createCommandGate();
+    for (const skill of skills.filter((s) => s.commandOnly)) {
+        pi.registerCommand(skill.name, {
+            description: `Start ${skill.name}${skill.steps.length > 1 ? ` - ${skill.steps.map((step) => step.name).join(" → ")}` : ""}: /${skill.name} [what you want]`,
+            handler: async (args) => {
+                gate.typed(skill.name);
+                pi.sendUserMessage(`/${skill.name}${args.trim() !== "" ? ` ${args.trim()}` : ""}`, { deliverAs: "followUp" });
+            },
+        });
+    }
     pi.registerTool({
         name: "cultivate",
         label: "Cultivate",
@@ -426,6 +470,7 @@ function turriExtension(pi, host) {
         promptSnippet: "cultivate: run a gated skill - its steps and review gates enforced by turri",
         promptGuidelines: [
             "When a request matches a skill listed in cultivate's description, call cultivate instead of doing the work yourself. Doing it by hand skips the review gates.",
+            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, so call cultivate for it at once, with what follows the command as context. Never call cultivate for one otherwise; tell them to type its command.",
             // pi lists .agents/skills among its own skills too: read and followed by hand, a skill's gates would be skipped.
             "A skill cultivate lists may also be among your own skills, from the project's .agents/skills: run it with cultivate all the same, never by reading its SKILL.md and following it.",
             "cultivate returns the reviewed artifact and a trace of every gate decision. Report the artifact to the user; do not rewrite it.",
@@ -458,6 +503,8 @@ function turriExtension(pi, host) {
                     details: {},
                 };
             }
+            if (!gate.mayStart(skill))
+                return { content: [{ type: "text", text: startedByCommandOnly(skill.name) }], details: { notStarted: true } };
             // A new run clears the run folder. An interrupted one is not thrown away by accident:
             // whether to pick it up or start over is the user's call.
             const runDir = skillRunDir(cwd, skill.name);
@@ -475,6 +522,8 @@ function turriExtension(pi, host) {
                     details: { interrupted },
                 };
             }
+            // Its command is used up: started again later, it is typed again.
+            gate.started(skill.name);
             const trace = [`skill: ${skill.name}`, ...describeGates(skill).map((l) => `  ${l}`)];
             // While it runs, what its agent is doing leads: pi shows a running tool's first lines, and the trace's first
             // lines are the gates, which say nothing about now. The result keeps the trace alone.
@@ -560,6 +609,8 @@ function turriExtension(pi, host) {
             const filesBefore = projectFiles(cwd);
             // A side question asked while it runs is told what it has done so far.
             const ended = skillRunStarted({ skill: skill.name, dir: skill.dir, step: () => live.step, trace: () => [...trace], runDir });
+            // From here the time to first regeneration is counted, for a skill that writes spec diffs: its first pulse started.
+            const began = Date.now();
             const { result, output: captured } = await captureConsole(() => runSkill({
                 skillDir: skill.dir,
                 cwd,
@@ -620,11 +671,17 @@ function turriExtension(pi, host) {
                 ? `${specsChanged.join(", ")} changed, and nothing is regenerated from that yet: call regenerate for it, and the code is brought up to the spec.`
                 : "";
             const gated = skill.steps.some((step) => step.gate !== undefined);
+            const first = skill.allowedTools.includes("write_spec_diff") ? firstRegeneration(jobs.list(), began) : {};
+            const ttfr = first.started === undefined
+                ? ""
+                : `Time to first regeneration: ${formatElapsed(first.started)} - its first pulse started that long after ${skill.name} began` +
+                    (first.landed !== undefined ? `, and landed after ${formatElapsed(first.landed)}.` : ".");
             const text = result.ok
                 ? [
                     gated ? `${skill.name}: passed all gates.` : `${skill.name}: finished. It has no review gates, so nothing checked its work: read what it changed before you report it.`,
                     changed,
                     ...(unrendered !== "" ? [unrendered] : []),
+                    ...(ttfr !== "" ? [ttfr] : []),
                     "",
                     "<artifact>",
                     result.output,
@@ -1411,20 +1468,27 @@ 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" } };
+            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" } };
+            }
             return { content: [{ type: "text", text: whyFailed(job) }], details: { status: job.status } };
         },
     });
@@ -1432,7 +1496,8 @@ function registerJobTools(pi, jobs, cwd) {
         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" })),
@@ -1440,7 +1505,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);
@@ -1451,6 +1516,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: [
@@ -1564,6 +1632,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({
@@ -1657,6 +1740,7 @@ function registerJobTools(pi, jobs, cwd) {
             specMap.refresh();
             const view = createSidePanel({
                 jobs: () => shownJobs(jobs),
+                earlier: earlierJobs,
                 tree: jobsTree,
                 map: () => specMap.read(),
                 mapState,
@@ -1930,13 +2014,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
@@ -2083,6 +2181,7 @@ async function askOnTheSide(pi, ctx, cwd, jobs, question) {
         pulses: jobs.list().map((job) => `${job.id} ${job.status}: ${pulseName(job)}`),
         projectDir: cwd,
         harnessDir: PACKAGE_ROOT,
+        ...(surfaceOf(jobs) !== undefined ? { surface: surfaceOf(jobs) } : {}),
     }, chatModelOf(ctx));
     try {
         pi.appendEntry(SIDE_ENTRY, { question, answer });

package/dist/host.d.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

@@ -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/identity.d.ts

@@ -1,2 +1,7 @@
-/** Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. */
+/**
+ * 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 declare function conversationIdentity(surface?: string): string;
+/** turri as the terminal runs it. */
 export declare const TURRI_IDENTITY: string;

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,7 @@ export declare const DEFAULTS: {
     readonly compactAt: 100000;
     readonly maxSpecsPerPulse: 3;
     readonly maxLinesPerPulse: 120;
+    readonly ledgerKeep: 100;
 };
 /** 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,7 @@ export const DEFAULTS = {
     compactAt: 100000,
     maxSpecsPerPulse: 3,
     maxLinesPerPulse: 120,
+    ledgerKeep: 100,
 };
 /** 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 +184,10 @@ 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}`,
+        "",
         "# 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 {};