@turri-dev/cli 0.1.8-next.e553476 → 0.1.9-next.73bfddf

package/dist/pi.js

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

package/dist/regenerate/activity.d.ts

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

package/dist/regenerate/activity.js

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

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

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

package/dist/regenerate/agent-env.js

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

package/dist/regenerate/agent-shell.js

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

package/dist/regenerate/chunk-plan.d.ts

@@ -79,6 +79,14 @@ export declare function stepsOf(input: PlanInput, draft: DraftJob[]): Array<Draf
     step: SpecStep;
 }>;
 export declare const MAX_SPECS_PER_JOB = 3;
+/** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
+export declare const TITLE_WORDS = 10;
+export declare const TITLE_CHARS = 70;
+/**
+ * A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. Text
+ * cut already is cut again without stacking a second: several first lines joined, each cut, end on one ellipsis.
+ */
+export declare function shortTitle(text: string, chars?: number, words?: number): string;
 export declare const MAX_LINES_PER_JOB = 120;
 /**
  * A functional spec to build, for the grouping: the number the agent answers with, its text, and whether it is built
@@ -135,28 +143,39 @@ export interface PlaceAnswer {
     /** What of the person's wishes it did not follow, and why. */
     notes?: string;
 }
+/** A group to title: the number the agent answers with, and its functional specs' text. */
+export interface TitleGroup {
+    number: number;
+    specs: string[];
+}
+export interface TitleAnswer {
+    titles: Array<{
+        group: number;
+        title: string;
+    }>;
+}
 /**
- * The two judgements, each asked again with what was wrong with its answer - the last answer given, whether it holds
- * or not: the plan checks it again. Injectable, so the plan is testable without a model.
+ * The judgements, each asked again with what was wrong with its answer - the last answer given, whether it holds
+ * or not: the plan checks it again. Injectable, so the plan is testable without a model. `title` titles the groups no
+ * agent titled - the conformance tests', and a grouping that fell back - for what each pulse does, rather than its
+ * first functional spec's first line; without it, they keep that.
  */
 export interface ChunkAgents {
     group(specs: NewSpec[], check: (answer: GroupAnswer) => string[], steering?: Steering[], maxSpecs?: number): Promise<GroupAnswer | undefined>;
     place(input: PlaceInput, check: (answer: PlaceAnswer) => string[]): Promise<PlaceAnswer | undefined>;
+    title?(groups: TitleGroup[], check: (answer: TitleAnswer) => string[], track: "code" | "conformance"): Promise<TitleAnswer | undefined>;
 }
 /** What is wrong with a grouping: every new functional spec once, in order, next to each other, none too big. */
 export declare function groupProblems(specs: NewSpec[], answer: GroupAnswer, maxSpecs?: number): string[];
+/** What is wrong with a titling: every group titled once, by its number, none empty, none too long. */
+export declare function titleProblems(groups: TitleGroup[], answer: TitleAnswer): string[];
 /** What is wrong with a placement: every new req once, each where there is such a job. */
 export declare function placeProblems(input: PlaceInput, answer: PlaceAnswer): string[];
-/**
- * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
- * the work loop runs: checked (checkDraft), or, when nothing holds, the whole work as one job. `notes` is given what
- * the plan did not do as asked - the person's wishes an agent did not follow and why, an answer that did not hold, a
- * group split for its size - for the conversation to say, rather than guess.
- */
 export declare function planChunks(input: PlanInput, agents?: ChunkAgents, notes?: string[]): Promise<DraftJob[]>;
 export declare function groupPrompt(specs: NewSpec[], steering?: Steering[], maxSpecs?: number): string;
 export declare function placePrompt(input: PlaceInput): string;
-/** The chunking's two agents, on a model - fresh for every plan. */
+export declare function titlePrompt(groups: TitleGroup[], track: "code" | "conformance"): string;
+/** The chunking's agents, on a model - fresh for every plan. */
 export declare function llmChunkAgents(options: {
     cwd: string;
     model?: string;