@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/conversation-writes.js

@@ -0,0 +1,100 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/**
+ * What the conversation itself writes in the project, for the audit to leave alone.
+ *
+ * The audit puts back what changes in the project's own files while an agent's command runs, taking every change then
+ * for the command's. But the conversation goes on beside the pulses: the person's model edits a spec, writes a spec
+ * diff or runs a command of its own, and a change of its that lands while an agent's `ls` runs would be put back as the
+ * agent's - the person's edit undone, silently. So the conversation's file tools, its shell and the spec diffs it applies
+ * say here what they write and when, and the audit leaves a change the conversation made while the command ran.
+ *
+ * Only the conversation reaches this: the agents of a pulse are started without extensions, so its hooks never see
+ * their tools, and their own writes are fenced to their folders.
+ */
+/** Anything still marked as in progress after this long is taken to have ended: a hook that never heard its end. */
+const STALE_MS = 15 * 60 * 1000;
+/** Paths being written now, with each write in progress. */
+const writing = new Map();
+/** Paths written, with when the last write ended. */
+const wrote = new Map();
+/** The conversation's commands running now - what they write cannot be known. */
+const commands = new Set();
+let lastCommandEnd = 0;
+/** A path as the audit walks it: absolute, with its symlinks resolved where it exists. */
+function canonical(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        try {
+            return join(realpathSync(dirname(absolute)), basename(absolute));
+        }
+        catch {
+            return absolute;
+        }
+    }
+}
+/** The conversation is about to write these files: call what it returns once it has. */
+export function conversationWriting(paths) {
+    const write = { started: Date.now() };
+    const marked = paths.map(canonical);
+    for (const path of marked)
+        writing.set(path, (writing.get(path) ?? new Set()).add(write));
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        const now = Date.now();
+        for (const path of marked) {
+            const left = writing.get(path);
+            left?.delete(write);
+            if (left?.size === 0)
+                writing.delete(path);
+            wrote.set(path, now);
+        }
+    };
+}
+/** The conversation starts a command of its own: call what it returns once it has ended. */
+export function conversationCommand() {
+    const command = { started: Date.now() };
+    commands.add(command);
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        commands.delete(command);
+        lastCommandEnd = Date.now();
+    };
+}
+/** The conversation's turn is over: nothing of its is in progress any more. */
+export function conversationSettled() {
+    const now = Date.now();
+    for (const path of writing.keys())
+        wrote.set(path, now);
+    writing.clear();
+    if (commands.size > 0)
+        lastCommandEnd = now;
+    commands.clear();
+}
+/** Whether the conversation may have written this file after `since` - a write of its to it, or a command of its own. */
+export function writtenByConversation(path, since) {
+    const now = Date.now();
+    const live = (running) => now - running.started < STALE_MS;
+    if ([...commands].some(live) || lastCommandEnd > since)
+        return true;
+    const key = canonical(path);
+    if ([...(writing.get(key) ?? [])].some(live))
+        return true;
+    return (wrote.get(key) ?? 0) > since;
+}
+/** For tests: forget everything. */
+export function resetConversationWrites() {
+    writing.clear();
+    wrote.clear();
+    commands.clear();
+    lastCommandEnd = 0;
+}

package/dist/regenerate/credentials.js

@@ -0,0 +1,88 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+/**
+ * Credentials are the person's: no agent writes them. A run that needs one and does not have it is told
+ * so - by its judge, to the person - rather than given one an agent made up, which every later run then
+ * fails on without anyone seeing why.
+ *
+ * A credential file is a `.env` or one of its variants (`.env.local`, `.env.test`); a template of one -
+ * `.env.example`, `.env.sample`, `.env.template`, `.env.dist` - holds no secret and is not one.
+ */
+export function isCredentialFile(path) {
+    const name = basename(path);
+    if (name === ".env")
+        return true;
+    const variant = /^\.env\.(.+)$/.exec(name)?.[1];
+    return variant !== undefined && !["example", "sample", "template", "dist"].includes(variant.toLowerCase());
+}
+/** What an agent is told when it tries to write one. */
+export function credentialRefusal(path) {
+    return (`${basename(path)} holds credentials, and they are the person's to provide - never an agent's to write, ` +
+        "not even a placeholder: a made-up one makes every later run fail without anyone seeing why. If the software or its " +
+        "tests need a credential that is missing or rejected, say so - in submit_work - and name the variable.");
+}
+/** Folders a credential file is never looked for in: dependencies, caches, histories. */
+const SKIPPED = new Set(["node_modules", ".venv", "venv", ".git", ".plaingit", "cache", "logs", "__pycache__", ".pytest_cache", "target", "build", "dist", ".gradle", ".m2"]);
+const DEPTH = 5;
+/** The credential files under `roots`, with what each holds: what an agent's command is checked against. */
+export function credentialFiles(roots) {
+    const found = new Map();
+    const visit = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const path = join(dir, name);
+            let isDir;
+            try {
+                isDir = statSync(path).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                if (depth < DEPTH && !SKIPPED.has(name))
+                    visit(path, depth + 1);
+            }
+            else if (isCredentialFile(path)) {
+                try {
+                    found.set(path, readFileSync(path, "utf8"));
+                }
+                catch {
+                    /* unreadable: nothing to put back */
+                }
+            }
+        }
+    };
+    for (const root of roots)
+        visit(root, 0);
+    return found;
+}
+/**
+ * Undo what a command did to the credential files under `roots`, from what they held before it: one it made is
+ * removed, one it changed or removed is put back. Says which it put back.
+ */
+export function restoreCredentialFiles(before, roots) {
+    const after = credentialFiles(roots);
+    const restored = [];
+    for (const [path, text] of after) {
+        if (before.get(path) === text)
+            continue;
+        if (before.has(path))
+            writeFileSync(path, before.get(path));
+        else
+            rmSync(path, { force: true });
+        restored.push(path);
+    }
+    for (const [path, text] of before) {
+        if (after.has(path) || existsSync(path))
+            continue;
+        writeFileSync(path, text);
+        restored.push(path);
+    }
+    return restored;
+}

package/dist/regenerate/debug-log.js

@@ -0,0 +1,228 @@
+import { appendFileSync, existsSync } from "node:fs";
+import { maskSecrets } from "./masking.js";
+import { dirname, join, resolve, sep } from "node:path";
+import { currentJob, reportActivity, reportTranscript } from "./activity.js";
+import { ensureInScratch, MODULES_DIR, projectRootOf, scratchDir } from "./paths.js";
+/**
+ * Every render agent's whole conversation, streamed to a file of its own as it happens - always.
+ *
+ * A job's transcript keeps a tool call's arguments to 600 characters and its result to 2000, and only while pi is
+ * running. When an agent goes wrong, what it was actually
+ * given and what actually came back is what there is to go on. So each agent a render starts -
+ * coding, conformance, repair, the spec-steps planner - writes everything to `.turri/debug/`
+ * in the project: the system prompt, every prompt, its replies and thinking as they stream, every
+ * tool call with its arguments and its whole result, each response's stop reason and usage, and the
+ * provider's retries and errors.
+ *
+ * Each event is on disk the moment it arrives, so a crashed or killed run leaves its log up to
+ * the moment it stopped, and `tail -f` follows an agent live. The folder is in the project, not in
+ * `plain_modules`, so no agent can read another's log. A log that cannot be written is given up
+ * on, never allowed to fail the render.
+ */
+/** `.turri/debug` in the project: beside `plain_modules`, never inside it. */
+export function debugDir(project) {
+    return join(scratchDir(join(project, MODULES_DIR)), "debug");
+}
+/**
+ * Where the log of an agent working in `cwd` goes: always outside what that agent can reach. In
+ * `plain_modules`, or in the project that holds it, that is the project's; an explicit build
+ * folder elsewhere is its own fence (see `modulesRootOf`), so its logs go beside it, not in it.
+ */
+export function debugDirFor(cwd) {
+    const dir = resolve(cwd);
+    if (dir.split(sep).includes(MODULES_DIR))
+        return debugDir(projectRootOf(dir));
+    if (existsSync(join(dir, MODULES_DIR)))
+        return debugDir(dir);
+    return join(dirname(dir), ".turri", "debug");
+}
+const logs = new WeakMap();
+/** The debug log a session is streaming to, if it has one. */
+export function debugLogOf(session) {
+    return logs.get(session);
+}
+/**
+ * Start streaming a session to a log of its own. `label` says what the agent is - `app 3 coding
+ * agent` - and names the file.
+ */
+export function startDebugLog(session, options) {
+    let file;
+    try {
+        const dir = debugDirFor(options.cwd);
+        ensureInScratch(dirname(dir), dir);
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const name = options.label.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "agent";
+        file = join(dir, `${stamp}-${name}.log`);
+        for (let n = 2; existsSync(file); n += 1)
+            file = join(dir, `${stamp}-${name}-${n}.log`);
+        appendFileSync(file, maskSecrets(header(session, options)), { flag: "wx" });
+    }
+    catch (error) {
+        reportActivity(`debug log not started: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    let broken = false;
+    const write = (text) => {
+        if (broken)
+            return;
+        try {
+            appendFileSync(file, maskSecrets(text));
+        }
+        catch (error) {
+            // Given up on, not retried: a disk that is full or a folder that went is not going to
+            // come back mid-turn, and the render matters more than its log.
+            broken = true;
+            reportActivity(`debug log stopped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    let prompts = 0;
+    /** Each call's number and start, by its id: calls in one response run at once and end in any order. */
+    const toolStarted = new Map();
+    let calls = 0;
+    /** How much of the reply or thinking block in progress has streamed. */
+    let streamed = 0;
+    const record = (event) => {
+        switch (event.type) {
+            case "message_update": {
+                const update = event.assistantMessageEvent;
+                if (update.type === "text_start" || update.type === "thinking_start") {
+                    streamed = 0;
+                    write(`\n${stamp()} ${update.type === "text_start" ? "reply" : "thinking"}\n`);
+                }
+                else if (update.type === "text_delta" || update.type === "thinking_delta") {
+                    streamed += update.delta.length;
+                    write(update.delta);
+                }
+                else if (update.type === "text_end" || update.type === "thinking_end") {
+                    // A block can arrive whole, with no deltas - redacted thinking does: then its end has it.
+                    write(streamed === 0 && update.content ? `${update.content}\n` : "\n");
+                }
+                break;
+            }
+            case "tool_execution_start":
+                calls += 1;
+                toolStarted.set(event.toolCallId, { n: calls, at: Date.now() });
+                write(`\n${stamp()} → #${calls} ${event.toolName}\n${formatArgs(event.args)}`);
+                break;
+            case "tool_execution_end": {
+                const started = toolStarted.get(event.toolCallId);
+                toolStarted.delete(event.toolCallId);
+                const which = started !== undefined ? `#${started.n} ` : "";
+                const took = started !== undefined ? ` · ${duration(Date.now() - started.at)}` : "";
+                write(`\n${stamp()} ← ${which}${event.toolName} ${event.isError ? "failed" : "done"}${took}\n${indent(resultText(event.result))}`);
+                break;
+            }
+            case "message_end": {
+                const message = event.message;
+                if (message.role !== "assistant")
+                    break;
+                const parts = [`stop: ${message.stopReason ?? "unknown"}`];
+                if (message.usage !== undefined) {
+                    const { input, output, cacheRead, cacheWrite, cost } = message.usage;
+                    parts.push(`tokens: ${input} in, ${output} out, ${cacheRead} cache read, ${cacheWrite} cache write`);
+                    if (typeof cost?.total === "number")
+                        parts.push(`$${cost.total.toFixed(4)}`);
+                }
+                write(`\n${stamp()} end of response · ${parts.join(" · ")}\n`);
+                if (message.errorMessage !== undefined)
+                    write(`${stamp()} error: ${message.errorMessage}\n`);
+                // A response cut off runs none of its tool calls, so they never reach the lines above.
+                if (message.stopReason === "error" || message.stopReason === "aborted" || message.stopReason === "length") {
+                    for (const block of message.content ?? []) {
+                        if (block.type === "toolCall")
+                            write(`${stamp()} (cut off, not run) → ${block.name ?? "a tool"}\n${formatArgs(block.arguments ?? {})}`);
+                    }
+                }
+                break;
+            }
+            case "auto_retry_start":
+                write(`\n${stamp()} provider retry ${event.attempt} of ${event.maxAttempts} in ${duration(event.delayMs)}: ${event.errorMessage}\n`);
+                break;
+            case "auto_retry_end":
+                write(`${stamp()} provider retry ${event.success ? "succeeded" : `gave up${event.finalError ? `: ${event.finalError}` : ""}`}\n`);
+                break;
+            case "compaction_start":
+                write(`\n${stamp()} compacting the context (${event.reason})\n`);
+                break;
+            case "compaction_end":
+                write(`${stamp()} compaction ${event.aborted ? "aborted" : event.errorMessage ? `failed: ${event.errorMessage}` : "done"}\n`);
+                break;
+        }
+    };
+    // pi calls this from inside the agent's turn: nothing in it may throw back into that.
+    session.subscribe((event) => {
+        try {
+            record(event);
+        }
+        catch (error) {
+            write(`\n${stamp()} (an event could not be logged: ${error instanceof Error ? error.message : String(error)})\n`);
+        }
+    });
+    const log = {
+        file,
+        prompt(text) {
+            prompts += 1;
+            write(`\n\n${"=".repeat(24)} prompt ${prompts} · ${stamp()} ${"=".repeat(24)}\n${text}\n`);
+        },
+        note(line) {
+            write(`\n${stamp()} ${line}\n`);
+        },
+    };
+    logs.set(session, log);
+    // In the transcript, not the activity: where to look, not something an agent did.
+    reportTranscript({ kind: "stage", text: `debug log: ${file}` });
+    return log;
+}
+function header(session, options) {
+    const job = currentJob();
+    const model = session.model?.id !== undefined ? `${session.model.provider ?? "?"}/${session.model.id}` : "pi's default";
+    const lines = [
+        `turri debug log · ${options.label}`,
+        `started   ${new Date().toISOString()}`,
+        `job       ${job !== undefined ? `${job.id} · ${job.kind} · ${job.summary}` : "none - run from the command line, or waited on"}`,
+        `model     ${model}${session.thinkingLevel !== undefined ? ` · thinking ${session.thinkingLevel}` : ""}`,
+        `cwd       ${options.cwd}`,
+        `session   ${session.sessionFile ?? "not saved"}`,
+        ...(options.tools !== undefined ? [`tools     ${options.tools.join(", ")}`] : []),
+    ];
+    const system = session.systemPrompt;
+    return `${lines.join("\n")}\n${system ? `\n${"=".repeat(24)} system prompt ${"=".repeat(24)}\n${system}\n` : ""}`;
+}
+/** Local time of day to the millisecond: when each thing happened, and how long between them. */
+function stamp() {
+    const now = new Date();
+    const pad = (n, width = 2) => String(n).padStart(width, "0");
+    return `[${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}]`;
+}
+function duration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = ms / 1000;
+    return s < 60 ? `${s.toFixed(1)}s` : `${Math.floor(s / 60)}m ${Math.round(s % 60)}s`;
+}
+/** Every line indented, so a tool's output stands apart from the lines around it. */
+function indent(text) {
+    let end = text.length;
+    while (end > 0 && text.charCodeAt(end - 1) === 10)
+        end -= 1;
+    if (end === 0)
+        return "";
+    return `${text.slice(0, end).split("\n").map((line) => `    ${line}`).join("\n")}\n`;
+}
+/** A tool call's arguments, one per line, whole: a file's content is shown as the file, not as JSON. */
+function formatArgs(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return indent(JSON.stringify(args) ?? "");
+    return Object.entries(args)
+        .map(([key, value]) => typeof value === "string" && value.includes("\n")
+        ? `  ${key}:\n${indent(value)}`
+        : `  ${key}: ${typeof value === "string" ? value : JSON.stringify(value)}\n`)
+        .join("");
+}
+/** A tool result's text, whole; anything else in it is named rather than dropped silently. */
+function resultText(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return result === undefined ? "" : (JSON.stringify(result) ?? "");
+    return content.map((part) => (part.type === "text" && typeof part.text === "string" ? part.text : `[${part.type ?? "unknown"} content]`)).join("\n");
+}

package/dist/regenerate/debugger.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { ask, BEGIN, createExecutor } from "../pi.js";
+import { confinedTools } from "./confine.js";
+import { createWebTools, WEB_TOOLS } from "./web.js";
+/**
+ * A fresh look at a failure the coding agent keeps hitting.
+ *
+ * The coding agent's session fills with its own attempts, and an agent stuck on a failure tends to keep circling the
+ * same few changes - moving files about, reordering a fixture - when the cause is one it has not thought of: an
+ * in-memory database every connection opens anew, a test runner that does not put the project on the path. When the
+ * unit tests fail the same way round after round, or the agent goes round in circles in its own runs, the harness starts
+ * this agent: a session of its own - on the `debugger` role's model, else a stronger one than the coding agent's, the
+ * judge model or the harness model - that reads the code, the tests, the build files and the
+ * failing run - and the web - and says what the cause is and what change fixes it. It changes nothing; the coding
+ * agent is given what it found, and goes on.
+ */
+/** How many tool calls the debugger has before it must hand over what it found. */
+const DEBUGGER_CALLS = 40;
+/** The debugger's account, as the coding agent is given it. */
+export function diagnosisText(diagnosis) {
+    return [`<root cause>\n${diagnosis.rootCause.trim()}\n</root cause>`, `<fix>\n${diagnosis.fix.trim()}\n</fix>`].join("\n\n");
+}
+function debugPrompt(input) {
+    const script = input.script !== undefined && existsSync(input.script) ? readFileSync(input.script, "utf8") : undefined;
+    return [
+        `The unit tests of the codebase in ${input.buildDir} have failed the same way ${input.times} times in a row. The coding agent`,
+        "keeps changing things and the failure does not move: it has not seen the cause. You look at it with fresh eyes.",
+        "",
+        "Find the root cause - the one thing that makes this failure happen - and the change that fixes it. Read the failing",
+        "run below, the tests it names, the code they exercise, the build files (pyproject.toml, package.json, go.mod, pom.xml,",
+        "...) and the testing script below: it decides pass or fail, and how and where it runs the tests is often the cause.",
+        "Look the error up on the web when it is one a library or tool is known for. Think about what the coding agent may have",
+        "missed rather than what it has already tried: a test runner that does not put the code on its import path, an",
+        "in-memory database that every connection opens empty, a name that shadows another, a configuration a tool needs.",
+        "",
+        "You change nothing - you only read. When you know, call submit_diagnosis: the root cause, with the evidence for it,",
+        "and the fix - which files, and exactly what to change in them.",
+        "",
+        "<what the change is meant to do>",
+        input.task.trim(),
+        "</what the change is meant to do>",
+        ...(script !== undefined ? ["", `<testing script path="${input.script}">`, script.trimEnd(), "</testing script>"] : []),
+        "",
+        "<failing run>",
+        input.failure.trimEnd().slice(-8000),
+        "</failing run>",
+    ].join("\n");
+}
+/** Have a fresh agent find why the unit tests keep failing the same way: its root cause and fix, or undefined when it found none. */
+export async function debugFailure(input) {
+    let found;
+    const submit = defineTool({
+        name: "submit_diagnosis",
+        label: "Submit the diagnosis",
+        description: "Hand over the root cause of the failure and the change that fixes it. The coding agent gets only this.",
+        parameters: Type.Object({
+            root_cause: Type.String({ description: "The one thing that makes the failure happen, and the evidence for it: the lines of the run, the code, the docs" }),
+            fix: Type.String({ description: "The change that fixes it: which files, and exactly what to change in them" }),
+        }),
+        async execute(_id, params) {
+            const given = params;
+            found = { rootCause: given.root_cause, fix: given.fix };
+            return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
+        },
+    });
+    // It reads the code and the web, and changes nothing: the file tools, no shell.
+    const fence = confinedTools({ workdir: input.buildDir, read: [input.buildDir], write: [], noBash: true });
+    const session = await createExecutor({
+        cwd: input.buildDir,
+        customTools: [submit, ...createWebTools(), ...fence.tools],
+        tools: [...fence.names, ...WEB_TOOLS, "submit_diagnosis"],
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        label: `${input.label} debugger`,
+        role: "debugger",
+        system: fence.note,
+        task: debugPrompt(input),
+        budget: { calls: DEBUGGER_CALLS, finish: ["submit_diagnosis"] },
+    });
+    try {
+        await ask(session, BEGIN, input.onDelta);
+        if (found === undefined)
+            await ask(session, "Call submit_diagnosis now with what you found: the most likely root cause, and the fix.", input.onDelta);
+    }
+    finally {
+        session.dispose();
+    }
+    return found;
+}

package/dist/regenerate/delivery.js

@@ -0,0 +1,19 @@
+import { relative } from "node:path";
+/**
+ * How a job that lands code ends: the person can try what is built, by asking - `deploy` sets it up
+ * from what is built.
+ */
+function shortPath(buildDir) {
+    const fromHere = relative(process.cwd(), buildDir);
+    return fromHere === "" || fromHere.startsWith("..") ? buildDir : fromHere;
+}
+/** What every job that lands code ends with: the person can try it now, by asking. */
+export const TRY_IT_LINE = "Want to try it? Just ask me - I'll set it up from what's built so far.";
+/** The same for a command-line run, which has no one to ask: the command that does it. */
+export function tryItCommand(plainFile) {
+    return `To try it: turri release ${shortPath(plainFile)}`;
+}
+/** A job's report, ending with how to try what it built when it landed. */
+export function withTryItLine(report, landed) {
+    return landed ? `${report}\n\n${TRY_IT_LINE}` : report;
+}

package/dist/regenerate/diagnose-job.js

@@ -0,0 +1,40 @@
+import { describeJob } from "./jobs.js";
+/**
+ * Why a job did not land, from its transcript: how it ended, the last failing run of a testing script, the review that
+ * sent the work back last, the stages that went wrong and the tool calls that failed - what someone reading the whole
+ * log would look for first, so the conversation does not have to guess from the report.
+ */
+const LAST_RUN_CHARS = 6_000;
+const LAST_REVIEW_CHARS = 4_000;
+const SHOWN_ERRORS = 5;
+const SHOWN_STAGES = 12;
+const textOf = (entry) => entry.full ?? entry.text;
+/** A testing script's run that failed, as the harness or an agent's run_unit_tests / run_conformance_tests saw it. */
+const FAILED_RUN = /\bexited ([1-9]\d*)\b|had not finished after \d+ seconds/;
+/** A stage that says something went wrong. */
+const WRONG = /not passing|did not|failing|failed|✗|undoing|stopped|halt|wrong|missing/i;
+export function whyFailed(job) {
+    const ended = describeJob(job);
+    if (job.status === "running" || job.status === "queued")
+        return `${ended}\n\nIt has not ended yet: pulses says how it is going.`;
+    const transcript = job.transcript;
+    // An agent's run is a tool result; the harness's own reaches the agent as the prompt that sends it back.
+    const lastRun = [...transcript].reverse().find((entry) => (entry.kind === "result" || entry.kind === "prompt") && FAILED_RUN.test(textOf(entry)));
+    const lastReview = [...transcript].reverse().find((entry) => entry.kind === "prompt" && /A review of the work found|review found/i.test(textOf(entry)));
+    const stages = transcript.filter((entry) => entry.kind === "stage" && WRONG.test(entry.text)).slice(-SHOWN_STAGES);
+    const errors = transcript.filter((entry) => entry.kind === "result" && entry.error === true).slice(-SHOWN_ERRORS);
+    const tail = (text, chars) => (text.length > chars ? `… ${text.slice(-chars)}` : text);
+    return [
+        ended,
+        ...(job.diagnosis !== undefined ? ["", "<diagnosis>", job.diagnosis.trim(), "</diagnosis>"] : []),
+        ...(stages.length > 0 ? ["", "<what went wrong, as it happened>", ...stages.map((entry) => `- ${entry.text.trim()}`), "</what went wrong, as it happened>"] : []),
+        ...(lastRun !== undefined
+            ? ["", `<last failing test run${lastRun.agent !== undefined ? ` by="${lastRun.agent.label}"` : ""}>`, tail(textOf(lastRun).trim(), LAST_RUN_CHARS), "</last failing test run>"]
+            : []),
+        ...(lastReview !== undefined ? ["", "<last review that sent the work back>", tail(textOf(lastReview).trim(), LAST_REVIEW_CHARS), "</last review that sent the work back>"] : []),
+        ...(errors.length > 0
+            ? ["", "<tool calls that failed, last ones>", ...errors.map((entry) => `- ${entry.agent?.label ?? "an agent"}: ${textOf(entry).trim().slice(0, 400)}`), "</tool calls that failed, last ones>"]
+            : []),
+        ...(job.logFile !== undefined ? ["", `The whole transcript: ${job.logFile}`] : []),
+    ].join("\n");
+}

package/dist/regenerate/diagnose.js

@@ -0,0 +1,81 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { ask, BEGIN, createExecutor } from "../pi.js";
+import { confinedTools } from "./confine.js";
+/** How many tool calls the diagnosis may make before it is told to decide. */
+export const DIAGNOSIS_CALLS = 40;
+export function describeDiagnosis(diagnosis) {
+    const whose = { spec: "the spec", environment: "the environment", code: "the code", harness: "turri itself" }[diagnosis.whose];
+    return [
+        `What happened: ${diagnosis.whatHappened.trim()}`,
+        `Why: ${diagnosis.cause.trim()}`,
+        `To fix - in ${whose}:`,
+        ...diagnosis.todo.map((step, index) => `  ${index + 1}. ${step.trim()}`),
+    ].join("\n");
+}
+export async function diagnoseFailure(options) {
+    let diagnosis;
+    const submit = defineTool({
+        name: "submit_diagnosis",
+        label: "Submit the diagnosis",
+        description: "Hand over what happened, why, whose it is to fix and exactly what to do. Call this once.",
+        parameters: Type.Object({
+            what_happened: Type.String({ description: "What the job did and where it failed, both times - in a few sentences" }),
+            cause: Type.String({ description: "The root cause, as the logs, the code, the tests or turri's source show it - quote what shows it" }),
+            whose: Type.Union([Type.Literal("spec"), Type.Literal("environment"), Type.Literal("code"), Type.Literal("harness")], {
+                description: "Where the fix belongs: the spec, the environment (a service, a credential, a toolchain), the code, or turri itself",
+            }),
+            todo: Type.Array(Type.String(), { description: "Exactly what to do, step by step - the file and the change, the command, the setting" }),
+        }),
+        async execute(_id, params) {
+            const given = params;
+            diagnosis = { whatHappened: given.what_happened, cause: given.cause, whose: given.whose, todo: given.todo };
+            return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
+        },
+    });
+    const fence = confinedTools({ workdir: options.projectDir, read: [options.projectDir, options.harnessDir], write: [], noBash: true });
+    const session = await createExecutor({
+        cwd: options.projectDir,
+        customTools: [submit, ...fence.tools],
+        tools: [...fence.names, "submit_diagnosis"],
+        model: options.model,
+        label: `${options.job.summary} diagnosis`, role: "diagnosis",
+        system: fence.note,
+        task: diagnosisPrompt(options),
+        budget: { calls: DIAGNOSIS_CALLS, finish: ["submit_diagnosis"] },
+    });
+    try {
+        await ask(session, BEGIN);
+        if (diagnosis === undefined)
+            await ask(session, "You have not called submit_diagnosis. Call it now, with what you know.");
+    }
+    catch {
+        // Without a diagnosis the person still gets both failures, as they were.
+    }
+    finally {
+        session.dispose();
+    }
+    return diagnosis;
+}
+export function diagnosisPrompt(options) {
+    return [
+        `A turri job failed twice: ${options.job.kind} - ${options.job.summary} (job ${options.job.id}). It was tried a`,
+        "second time and failed again, so it has stopped, and every job queued behind it has failed without running. Work",
+        "out why, and what has to be done so it passes - the person is told exactly what you say.",
+        "",
+        "You can read, and change nothing:",
+        `- the project, in ${options.projectDir}: its .plain specs and templates, config.turri.yaml, the testing scripts, and`,
+        "  plain_modules - each module's code and conformance tests, the notes (.turri-notes.md in the code), the full",
+        "  outputs of the test runs (plain_modules/.turri/logs), and every agent's own log",
+        `  (${options.projectDir}/.turri/debug) - newest last;`,
+        ...(options.jobLog !== undefined ? [`- this job's own log: ${options.jobLog};`] : []),
+        `- turri itself, in ${options.harnessDir}: its source (src/), its skills (genome/skills/), the ***plain authoring rules`,
+        "  (genome/rules/) and its docs (docs/) - so a failure that comes from the harness can be named as that.",
+        "",
+        "Find the root cause, not the last symptom: read the failing run's output and the agents' logs around where it",
+        "failed, and follow it to the spec line, the code, the test, the environment or the harness it comes from. Then",
+        "call submit_diagnosis: what happened, why, whose it is to fix, and exactly what to do.",
+        "",
+        ...options.failures.flatMap((failure, index) => [`<attempt ${index + 1}>`, failure.trim().slice(-12_000), `</attempt ${index + 1}>`, ""]),
+    ].join("\n");
+}