@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/environment-error.js

@@ -0,0 +1,220 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, isAbsolute, sep } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { passedCredentials } from "./agent-env.js";
+import { missingToolchain } from "./test-scripts.js";
+import { MODULES_DIR } from "./paths.js";
+import { reportActivity } from "./activity.js";
+import { LINUX_MACHINE, MACOS_MACHINE } from "./os-sandbox.js";
+/**
+ * When the machine lacks what the work needs - a toolchain, a system library, a credential - no agent can fix it, and
+ * none tries: the pulse stops and is rolled back, the module's later pulses wait, and the person is told what is
+ * missing, how to fix it, and how to run it again. Raised two ways: an agent calls `report_environment_error`, which
+ * ends its turn - its reason goes to the person as it is; or the harness finds it itself - a testing script that cannot
+ * find its toolchain, a credential `agent-env:` names that is not there - and works out at once what to do about it.
+ */
+export class EnvironmentError extends Error {
+    // Declared fields, not parameter properties: node's own type stripping cannot run those.
+    /** The module whose pulse stopped. */
+    moduleName;
+    /** What the environment lacks. */
+    missing;
+    /** What needs it. */
+    neededBy;
+    /** What showed it: the command, the output. */
+    shownBy;
+    /** How to fix it, when it is known. */
+    fix;
+    /** Who found it: an agent, or the harness. */
+    source;
+    /**
+     * Nothing is missing: what the agent could not reach is on this machine, and turri's own sandbox kept it from it - the
+     * files it named, and the toolchain folder that holds them, for `toolchains:` to let the agents read.
+     */
+    sandbox;
+    constructor(details) {
+        super(details.sandbox !== undefined
+            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.paths[0]}, which is on this machine.`
+            : `${details.moduleName} stopped: the environment lacks ${details.missing}.`);
+        this.name = "EnvironmentError";
+        this.moduleName = details.moduleName;
+        this.missing = details.missing;
+        this.neededBy = details.neededBy;
+        if (details.shownBy !== undefined)
+            this.shownBy = details.shownBy;
+        if (details.fix !== undefined)
+            this.fix = details.fix;
+        this.source = details.source;
+        if (details.sandbox !== undefined)
+            this.sandbox = details.sandbox;
+    }
+}
+/** A folder named for a version - `24.16.0`, `v22.3.0`, `3.12.4` - the root of a version manager's install. */
+const VERSION = /^v?\d+\.\d+/;
+/** The parts of an install below its root, where the root ends: `…/24.16.0/lib/node_modules/…` ends before `lib`. */
+const INSIDE_INSTALL = new Set(["bin", "lib", "lib64", "libexec", "share", "include", "node_modules"]);
+/** The toolchain folder a file is part of: its version manager's install, else the folder above its bin or lib, else its own. */
+function toolchainFolder(path) {
+    const parts = path.split(sep);
+    for (let at = parts.length - 2; at > 0; at -= 1)
+        if (VERSION.test(parts[at]))
+            return parts.slice(0, at + 1).join(sep);
+    const inside = parts.findIndex((part, at) => at > 1 && INSIDE_INSTALL.has(part));
+    return inside > 1 ? parts.slice(0, inside).join(sep) : dirname(path);
+}
+/**
+ * What an agent reported the machine lacks, read for what it says of turri's own sandbox: a file it names that is on
+ * this machine - outside the project and the system's folders, which the sandbox already lets it read - is not missing,
+ * the sandbox hid it. A version manager's Node under ~/.local/share/mise, say, whose npm the agent could not open. Then
+ * the stop is the sandbox's, and the fix is a line of config - `toolchains:` - not an install.
+ */
+export function sandboxGapOf(text, options = {}) {
+    const exists = options.exists ?? existsSync;
+    const system = (options.platform ?? process.platform) === "darwin" ? MACOS_MACHINE : LINUX_MACHINE;
+    const within = (path, root) => path === root || path.startsWith(`${root}/`);
+    const named = [...text.matchAll(/(?:^|[\s'"`(=:])(\/[^\s'"`()<>,;]+)/g)].map((match) => match[1].replace(/[.:]+$/, ""));
+    const paths = [...new Set(named)].filter((path) => path.split("/").length > 3 && exists(path) && !system.some((root) => within(path, root)) && (options.project === undefined || !within(path, options.project)));
+    return paths.length > 0 ? { paths, folder: toolchainFolder(paths[0]) } : undefined;
+}
+/**
+ * What the person is told, in the chat, at the end of `turri regenerate`, and in the job's log. `rerun`: the command that runs
+ * the work again, as the pulse knows it - the spec the person ran; without it, the module's own spec by its name.
+ */
+export function describeEnvironmentError(error, rerun) {
+    if (error.sandbox !== undefined) {
+        return [
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${error.sandbox.paths[0]}\` - it is on this machine; nothing is missing.**`,
+            `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
+            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.yaml, keeping what is there: \`toolchains: [${error.sandbox.folder}]\`. Nothing needs installing.`,
+            `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+        ].join("\n");
+    }
+    return [
+        `**${error.moduleName} stopped: the environment lacks ${error.missing}.**`,
+        `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
+        `To fix: ${error.fix ?? "provide it on this machine, then run it again."}`,
+        `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+    ].join("\n");
+}
+/** The name agents know the tool by - their wall text names it. */
+export const ENVIRONMENT_ERROR_TOOL = "report_environment_error";
+/** How much of the harness's run a report that does not stand is shown, at most. */
+const RUN_SHOWN_CHARS = 4000;
+/**
+ * An agent's report checked against the harness's own run of the testing script - on this machine, outside the agent's
+ * sandbox, the run that decides whether the work is done. Its shell runs behind walls the script does not: what fails
+ * there may run here. The script passing, the machine has what the work needs: the report does not stand, and the agent
+ * goes on. The script not finding its toolchain, it stands. Failing otherwise, the agent is shown the run once - a
+ * report made again after it stands.
+ */
+export function checkAgainstScript(run, script) {
+    let shown = false;
+    return async () => {
+        const result = await run();
+        const name = basename(script);
+        if (result.exitCode === 0) {
+            return {
+                stands: false,
+                reply: `Not recorded: the harness ran the project's testing script, ${name}, on this machine itself, and it passed - ` +
+                    "the machine has what the work needs. What failed was your shell: your commands run behind a sandbox the " +
+                    "testing scripts do not. Do not work around it, and do not report it again: carry on with the work, and " +
+                    "check it with the tool that runs the testing script as the harness does.",
+            };
+        }
+        if (missingToolchain(result) !== undefined || shown)
+            return { stands: true };
+        shown = true;
+        const output = result.output.length > RUN_SHOWN_CHARS ? `...\n${result.output.slice(-RUN_SHOWN_CHARS)}` : result.output;
+        return {
+            stands: false,
+            reply: `Not recorded yet: the harness ran the project's testing script, ${name}, on this machine itself - outside your ` +
+                `sandbox - and it exited ${result.exitCode}, but not for want of a toolchain. Read its output below. A failure ` +
+                "of the code or the tests is yours to fix; if it shows the machine lacks what you reported, call " +
+                `${ENVIRONMENT_ERROR_TOOL} again and it stands.\n\n${output}`,
+        };
+    };
+}
+/**
+ * `report_environment_error`: an agent that finds the machine lacking what the work needs says so, and its turn ends.
+ * `record` is told what it reported; whoever asked the turn stops the pulse with it. With `check`, the report is checked
+ * first: one that does not stand is not recorded, and the agent is told why and goes on.
+ */
+export function environmentErrorTool(record, check) {
+    return defineTool({
+        name: ENVIRONMENT_ERROR_TOOL,
+        label: "Report an environment error",
+        description: "Say that this machine lacks something the work needs - a toolchain, a system library, a driver, a service, a " +
+            "credential - which you cannot and may not install or make up. It ends your turn: the pulse stops, and the person " +
+            "is told exactly what you write here - unless the harness's own run of the testing script, outside your sandbox, " +
+            "shows the machine has it: then you are told so, and go on. Use it only for what is missing from the machine, never " +
+            "for a problem in the code or the tests.",
+        promptSnippet: `${ENVIRONMENT_ERROR_TOOL}: the machine lacks something the work needs - ends your turn`,
+        parameters: Type.Object({
+            missing: Type.String({ description: "What is missing - e.g. `JDK 21`, `the CUDA toolkit (nvcc)`, `the D365_CLIENT_SECRET credential`" }),
+            needed_by: Type.String({ description: "What needs it - the build, a test, a library - e.g. `mvn test`, `torch's GPU build`" }),
+            shown_by: Type.Optional(Type.String({ description: "The command that showed it, and what it said" })),
+        }),
+        async execute(_id, params) {
+            const { missing, needed_by: neededBy, shown_by: shownBy } = params;
+            const report = { missing, neededBy, ...(shownBy !== undefined ? { shownBy } : {}) };
+            if (check !== undefined) {
+                reportActivity(`  the agent reports the environment lacks ${missing} - checking it with the harness's own run of the testing script`);
+                const verdict = await check(report);
+                if (!verdict.stands) {
+                    reportActivity("  it does not stand: the agent goes on");
+                    return { content: [{ type: "text", text: verdict.reply }], details: {} };
+                }
+            }
+            record(report);
+            return { content: [{ type: "text", text: "Recorded. Your turn ends here; the person is told." }], details: {}, terminate: true };
+        },
+    });
+}
+/**
+ * A testing script that cannot find its toolchain: the machine lacks it, and no change to the code or the tests would
+ * pass the script - so it is the environment's, found by the harness. `missing` is what the run's output named.
+ */
+export function toolchainError(missing, details) {
+    const what = `${details.kind} testing script`;
+    const needs = missing.command !== undefined ? `\`${missing.command}\`` : `a toolchain the ${what} needs`;
+    return new EnvironmentError({
+        moduleName: details.moduleName,
+        missing: needs,
+        neededBy: `the ${what}, \`${basename(details.script)}\``,
+        shownBy: missing.command !== undefined ? `it could not find \`${missing.command}\`` : "it exited saying a toolchain is missing",
+        fix: `install ${missing.command ?? "it"} on this machine, so the testing script finds it on its PATH.`,
+        source: "harness",
+    });
+}
+/** The harness's run of a testing script, when it could not find its toolchain: the error that stops the pulse. */
+export function missingToolchainError(run, details) {
+    const missing = missingToolchain(run);
+    return missing !== undefined ? toolchainError(missing, details) : undefined;
+}
+/** The module a folder is part of, by name: `plain_modules/<module>/...`. */
+function moduleNameOf(moduleDir) {
+    return basename(moduleDir);
+}
+/**
+ * Before a pulse in `moduleDir` starts any agent: a credential `agent-env:` names that is not there stops it - every
+ * command that needs it would fail, and no agent may make one up. Nothing when all are there, or the folder is no
+ * module's.
+ */
+export function missingCredentials(moduleDir) {
+    if (!isAbsolute(moduleDir) || basename(dirname(moduleDir)) !== MODULES_DIR)
+        return undefined;
+    // Only read: nothing of the module's environment - its home, its TMPDIR - is made for a check.
+    const { missing } = passedCredentials(moduleDir, process.env);
+    if (missing.length === 0)
+        return undefined;
+    const names = missing.map((item) => item.name);
+    return new EnvironmentError({
+        moduleName: moduleNameOf(moduleDir),
+        missing: `${names.length === 1 ? "the credential" : "the credentials"} ${names.map((name) => `\`${name}\``).join(", ")}`,
+        neededBy: "`agent-env:` in the project's config, which passes them to the agents",
+        shownBy: missing.map((item) => `${item.name}: ${item.why}`).join("; "),
+        fix: "provide them where `agent-env:` reads them - the dotenv file it names, or the environment turri is started in - or take them out of `agent-env:`.",
+        source: "harness",
+    });
+}

package/dist/regenerate/job-log.js

@@ -0,0 +1,102 @@
+import { appendFileSync, existsSync } from "node:fs";
+import { maskSecrets } from "./masking.js";
+import { dirname, isAbsolute, join, sep } from "node:path";
+import { ensureInScratch, MODULES_DIR, projectRootOf, scratchDir } from "./paths.js";
+/** The folder a job's log goes in: the project of the first module it writes, from its lanes. */
+export function jobLogDir(lanes) {
+    const lane = lanes.find((candidate) => isAbsolute(candidate) && candidate.split(sep).includes(MODULES_DIR));
+    if (lane === undefined)
+        return undefined;
+    return join(scratchDir(join(projectRootOf(lane), MODULES_DIR)), "jobs");
+}
+export function startJobLog(job, lanes) {
+    const dir = jobLogDir(lanes);
+    if (dir === undefined)
+        return undefined;
+    let file;
+    try {
+        ensureInScratch(dirname(dir), dir);
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        file = join(dir, `${stamp}-${job.id}-${job.kind}.log`);
+        for (let n = 2; existsSync(file); n += 1)
+            file = join(dir, `${stamp}-${job.id}-${job.kind}-${n}.log`);
+        appendFileSync(file, maskSecrets([
+            `turri job ${job.id} · ${job.kind} · ${job.summary}`,
+            `started   ${new Date().toISOString()}`,
+            ...(job.model !== undefined ? [`model     ${job.model}`] : []),
+            ...(job.diff !== undefined ? ["", "── the spec change", job.diff.trimEnd()] : []),
+            "",
+        ].join("\n")), { flag: "wx" });
+    }
+    catch {
+        return undefined;
+    }
+    let broken = false;
+    const write = (text) => {
+        if (broken)
+            return;
+        try {
+            appendFileSync(file, maskSecrets(text));
+        }
+        catch {
+            broken = true;
+        }
+    };
+    /** The kind of the entry written last: deltas of a reply join it, as they do on screen. */
+    let last;
+    return {
+        file,
+        entry(entry) {
+            const text = entry.full ?? entry.text;
+            if ((entry.kind === "text" || entry.kind === "thinking") && last === entry.kind) {
+                write(text);
+                return;
+            }
+            last = entry.kind;
+            const at = stamp();
+            switch (entry.kind) {
+                case "stage":
+                    write(`\n\n${at} ── ${text}\n`);
+                    break;
+                case "spec": {
+                    const [label, ...rest] = text.split("\n");
+                    write(`\n\n${at} ── building ${label}\n${rest.map((line) => `  │ ${line}`).join("\n")}\n`);
+                    break;
+                }
+                case "diff":
+                    write(`\n\n${at} ── the spec change\n${text.trimEnd()}\n`);
+                    break;
+                case "prompt":
+                    write(`\n\n${at} harness ▸\n${text.trimEnd()}\n`);
+                    break;
+                case "text":
+                    write(`\n\n${at} agent ▸\n${text}`);
+                    break;
+                case "thinking":
+                    write(`\n\n${at} thinking ▸\n${text}`);
+                    break;
+                case "tool":
+                    write(`\n\n${at} ⚙ ${text}\n`);
+                    break;
+                case "result":
+                    write(`${at} ${entry.error ? "✗" : "↳"}\n${text === "" ? "    (no output)" : text.replace(/\n+$/, "").split("\n").map((line) => `    ${line}`).join("\n")}\n`);
+                    break;
+            }
+        },
+        note(line) {
+            last = undefined;
+            write(`\n\n${stamp()} · ${line.trim()}\n`);
+        },
+        end(status, report, agents = []) {
+            last = undefined;
+            write(`\n\n${stamp()} ── ${status}\n${(report ?? "").trimEnd()}\n`);
+            if (agents.length > 0)
+                write(`\n── its agents\n${agents.map((line) => `  ${line}`).join("\n")}\n`);
+        },
+    };
+}
+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)}]`;
+}

package/dist/regenerate/job-panel.js

@@ -0,0 +1,336 @@
+import { foregroundAnsi, mixColors, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { formatDuration, formatElapsed, pulseName } from "./jobs.js";
+/**
+ * The live panel above the editor while background work runs.
+ *
+ * One block per running job: what it is and how long it has been going, the stage it is
+ * at, what is happening this second, and the last things its agents did. What waits is not
+ * in it - the side panel lists the queue. It disappears when nothing is running - the finished
+ * job announces itself in the transcript instead.
+ *
+ * It is drawn as a component rather than handed over as lines, because pi cuts a list of
+ * lines off at ten. Instead it sizes itself: compact by default, and the agents' trace in full
+ * while tool output is expanded - pi's own ctrl+o, which the person already uses to see more of
+ * what the agent did. What finished stays counted either way: the side panel lists it.
+ */
+export const JOB_PANEL_KEY = "turri-jobs";
+/**
+ * The key that opens the side panel on its jobs, and goes back to it. Not ctrl+j: a terminal without the Kitty keyboard
+ * protocol sends ctrl+j as a line feed - what it sends for shift+enter too, and what a dialog reads as enter - so it
+ * would answer a question, and take a new line from the editor. ctrl+h is the byte old terminals sent for backspace;
+ * every terminal now sends backspace as DEL, which pi never takes for ctrl+h, so it is free - in pi, and in a dialog.
+ */
+export const PANEL_KEY = "ctrl+h";
+const TICK_MS = 1000;
+/**
+ * Each key in the line under the panel - ctrl+o, ctrl+h - breathes until it is first pressed: fully there, a little
+ * faint, and back, so it reads as something to press, not as text. Once every BREATH_MS, redrawn every BREATH_TICK_MS
+ * while the panel shows and a key still breathes, at most BREATH_FADE of the way from the text's colour to the dim one.
+ * Pressed once, it stays still for the rest of the process; the other breathes on.
+ */
+export const BREATH_MS = 2400;
+const BREATH_TICK_MS = 100;
+const BREATH_FADE = 0.6;
+const pressed = new Set();
+/** A key of the line was pressed - ctrl+o, or the side panel opened: it stops breathing. */
+export function keyPressed(key) {
+    pressed.add(key);
+}
+export function breathes(key) {
+    return !pressed.has(key);
+}
+/** For tests: every key breathing again. */
+export function resetKeysForTests() {
+    pressed.clear();
+}
+/** How faint a breathing key is at `now`: 0, fully there, at the start of each breath, BREATH_FADE halfway through. */
+export function breath(now) {
+    const phase = (now % BREATH_MS) / BREATH_MS;
+    return BREATH_FADE * (0.5 - 0.5 * Math.cos(2 * Math.PI * phase));
+}
+/** Tool-call progress arrives many times a second; the screen does not need to. */
+const REDRAW_MS = 100;
+/** Activity lines per running job while compact. */
+const COMPACT_ACTIVITY = 2;
+/**
+ * A spinner rather than a disclosure arrow: a `▸` promises something opens when you pick
+ * it. The frame follows the clock, so it moves on every redraw, including the tick.
+ */
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export function spinner(now) {
+    return SPINNER[Math.floor(now / 1000) % SPINNER.length];
+}
+/** A finished pulse in its module's line: its mark, number and kind - `✓ 3 regenerate`. What it regenerated is in the side panel. */
+function finishedItem(job, marks) {
+    if (job.module === undefined || job.pulse === undefined)
+        return `${finishedMark(job, marks)} ${pulseName(job)}`;
+    return `${finishedMark(job, marks)} ${job.pulse} ${job.kind}`;
+}
+/**
+ * What finished, a line a module - its name, then its pulses oldest first - fitted to `width` from the left: the
+ * newest that fit, the rest counted as earlier. The side panel lists every one.
+ */
+export function finishedLines(finished, width, marks = PLAIN_MARKS) {
+    const byModule = new Map();
+    for (const job of [...finished].sort((a, b) => a.sequence - b.sequence)) {
+        const key = job.module ?? job.kind;
+        byModule.set(key, [...(byModule.get(key) ?? []), job]);
+    }
+    const pad = Math.max(...[...byModule.keys()].map((name) => visibleWidth(name)));
+    return [...byModule].map(([name, jobs]) => {
+        const head = `  ${name}${" ".repeat(pad - visibleWidth(name))}  `;
+        const items = jobs.map((job) => finishedItem(job, marks));
+        const lineOf = (from) => `${head}${from > 0 ? `… ${from} earlier · ` : ""}${items.slice(from).join(" · ")}`;
+        let from = 0;
+        while (width !== undefined && from < items.length - 1 && visibleWidth(lineOf(from)) > width)
+            from += 1;
+        return lineOf(from);
+    });
+}
+/** A pulse that ran to its end and whose build did not pass - stopped at a gate - is not a success. */
+export function didNotPass(job) {
+    return job.status === "succeeded" && job.details?.passed === false;
+}
+const PLAIN_MARKS = { success: (text) => text, error: (text) => text, warning: (text) => text };
+/** A finished pulse's mark, in the colour of how it ended. */
+export function finishedMark(job, paint = PLAIN_MARKS) {
+    if (didNotPass(job) || job.status === "failed")
+        return paint.error("✗");
+    if (job.status === "stopped")
+        return paint.warning("■");
+    return paint.success("✓");
+}
+/** What a pulse cost, as its line says it: " · $0.12", or nothing when the price is not known. */
+export function pulseCost(job) {
+    return job.usage.cost > 0 ? ` · $${job.usage.cost.toFixed(2)}` : "";
+}
+/**
+ * Jobs whose tool draws its own progress widget, which already shows the functional spec being
+ * built: the panel leaves it out, so it is not written twice.
+ */
+const SPEC_SHOWN_BY_WIDGET = new Set(["regenerate"]);
+/** Spec lines shown per running job while expanded. */
+const EXPANDED_SPEC_LINES = 30;
+const PLAIN_DIFF = { added: (text) => text, removed: (text) => text };
+export function summarizeDiff(diff, style = PLAIN_DIFF) {
+    const files = new Set();
+    let added = 0;
+    let removed = 0;
+    let first;
+    let firstRemoved;
+    for (const line of diff.split("\n")) {
+        const file = /^\+\+\+ (?:b\/)?(.+)$/.exec(line);
+        if (file) {
+            if (file[1] !== "/dev/null")
+                files.add(file[1].split("/").pop());
+            continue;
+        }
+        if (line.startsWith("---") || line.startsWith("diff --git") || line.startsWith("index "))
+            continue;
+        if (line.startsWith("+")) {
+            added += 1;
+            const text = line.slice(1).replace(/^- /, "").trim();
+            if (first === undefined && text !== "" && !/^\*\*\*.*\*\*\*$/.test(text))
+                first = text;
+        }
+        else if (line.startsWith("-")) {
+            removed += 1;
+            const text = line.slice(1).replace(/^- /, "").trim();
+            if (firstRemoved === undefined && text !== "" && !/^\*\*\*.*\*\*\*$/.test(text))
+                firstRemoved = text;
+        }
+    }
+    // What it adds, when it adds anything; what it takes out, when that is all it does.
+    const what = first !== undefined ? ` · ${first}` : firstRemoved !== undefined ? ` · removes: ${firstRemoved}` : "";
+    return `${[...files].join(", ")} ${style.added(`+${added}`)} ${style.removed(`−${removed}`)}${what}`;
+}
+/** The lines of a diff worth reading in a panel: the hunks, not the headers. */
+/**
+ * A line of the panel wrapped to its width, its continuations under its text: indented as far as it is,
+ * and past the rule of a diff box when it is in one.
+ */
+export function wrapKeepingIndent(line, width) {
+    if (visibleWidth(line) <= width)
+        return [line];
+    const plain = line.replace(/\x1b\[[0-9;]*m/g, "");
+    const indent = /^(\s*(?:│ )?)/.exec(plain)?.[1] ?? "";
+    // Inside a diff box its rule goes on down the continuations; elsewhere, blanks.
+    const lead = indent;
+    const inner = Math.max(10, width - indent.length);
+    const [first = "", ...rest] = wrapTextWithAnsi(line, width);
+    return [first, ...rest.flatMap((part) => wrapTextWithAnsi(part, inner)).map((part) => `${lead}${part}`)];
+}
+export function jobPanelLines(jobs, options = {}) {
+    const now = options.now ?? Date.now();
+    const expanded = options.expanded === true;
+    const inOrder = [...jobs].sort((a, b) => a.sequence - b.sequence);
+    const running = inOrder.filter((job) => job.status === "running");
+    // A module whose work is being planned: the planner is an agent, and takes a while - shown at once, as work going on.
+    const planning = inOrder.filter((job) => job.status === "queued" && job.planning !== undefined);
+    // Nothing running or being planned: no panel - what waits and what finished are in the side panel.
+    if (running.length === 0 && planning.length === 0)
+        return [];
+    const finished = inOrder.filter((job) => (job.status === "succeeded" || job.status === "failed" || job.status === "stopped") && job.replacedBy === undefined);
+    const lines = [];
+    // What finished, on top - a line a module, oldest first - and a rule under it: what runs now is below, by the input.
+    if (finished.length > 0) {
+        lines.push(...finishedLines(finished, options.width, options.marks ?? PLAIN_MARKS));
+        lines.push(`  ${"─".repeat(Math.max(10, (options.width ?? 80) - 4))}`);
+    }
+    for (const [index, job] of running.entries()) {
+        if (index > 0)
+            lines.push("");
+        // Its module, how long and what it has cost: what it is doing follows.
+        lines.push(`${spinner(now)} ${pulseName(job)} · ${formatDuration(job)}${pulseCost(job)}`);
+        // What it is on now, and for how long - beside the job's own time, which is the whole of it.
+        const onIt = job.building?.since !== undefined ? ` · ${formatElapsed(now - job.building.since)}` : "";
+        if (job.building !== undefined && SPEC_SHOWN_BY_WIDGET.has(job.kind)) {
+            // The module widget shows its text; the panel, how long it has taken so far.
+            lines.push(`    ${job.building.label}${onIt}`);
+        }
+        else if (job.building !== undefined) {
+            const text = job.building.text.split("\n").filter((line) => line.trim() !== "");
+            if (!expanded) {
+                const more = text.length > 1 ? `  (+${text.length - 1} line${text.length === 2 ? "" : "s"} · ctrl+o)` : "";
+                lines.push(`    ${job.building.label}${onIt}: ${(text[0] ?? "").trim()}${more}`);
+            }
+            else {
+                lines.push(`    ${job.building.label}${onIt}:`);
+                for (const line of text.slice(0, EXPANDED_SPEC_LINES))
+                    lines.push(`      │ ${line}`);
+                if (text.length > EXPANDED_SPEC_LINES)
+                    lines.push(`      │ … ${text.length - EXPANDED_SPEC_LINES} more lines - ${PANEL_KEY} shows it all`);
+            }
+        }
+        const activity = expanded ? job.activity : job.activity.slice(-COMPACT_ACTIVITY);
+        for (const line of activity)
+            lines.push(`      ${line}`);
+        if (job.now !== undefined) {
+            const seconds = Math.max(0, Math.round((now - job.now.since) / 1000));
+            lines.push(`      … ${job.now.label} · ${seconds}s`);
+        }
+    }
+    for (const job of planning) {
+        if (lines.length > 0 && running.length > 0)
+            lines.push("");
+        lines.push(`${spinner(now)} ${job.module ?? job.summary} · planning the pulses · ${formatElapsed(now - job.planning.since)}`);
+        lines.push("    the planner is cutting the work into pulses - the first starts once it is done");
+    }
+    // Always a line of help: how to see more here, and how to inspect the jobs in the side panel.
+    if (options.hints === false) {
+        // The side panel shows it all already, and says its own keys.
+    }
+    else {
+        // Set apart from the trace above it.
+        lines.push("");
+        const key = options.keys ?? ((_key, text) => text);
+        lines.push(`  ${key("trace", `ctrl+o to ${expanded ? "collapse" : "expand"} the trace`)} · ${key("peek", `${PANEL_KEY} to peek at regen`)}`);
+    }
+    return lines;
+}
+/**
+ * The keys of the line, painted at `now`'s breath: one not pressed yet in the text's colour mixed toward the dim one, one
+ * pressed as it is. Plain where the theme has no colours to mix.
+ */
+export function breathing(theme, now) {
+    const text = theme.colors?.text;
+    const dim = theme.colors?.dim ?? theme.colors?.muted;
+    const mode = theme.getColorMode?.();
+    if (text === undefined || dim === undefined || (mode !== "truecolor" && mode !== "256color"))
+        return (_key, line) => line;
+    const ansi = foregroundAnsi(mixColors(text, dim, breath(now)), mode);
+    return (key, line) => (breathes(key) ? `${ansi}${line}\x1b[39m` : line);
+}
+export function createJobPanel(list) {
+    let ui;
+    let tui;
+    let mounted = false;
+    let timer;
+    /** The keys breathing: a redraw a tick of it, while the panel shows and a key still breathes. */
+    let breathTimer;
+    /** Whether the trace was open when the panel was first drawn. */
+    let firstExpanded;
+    let pending;
+    const active = () => list().some((job) => job.status === "running" || job.status === "queued");
+    const draw = () => {
+        if (ui === undefined)
+            return;
+        const target = ui;
+        try {
+            if (active() && !mounted) {
+                mounted = true;
+                target.setWidget(JOB_PANEL_KEY, (next, theme) => {
+                    tui = next;
+                    return {
+                        // Laid out on every render, so ctrl+o takes effect on the very next frame.
+                        render: (width) => {
+                            const expanded = target.getToolsExpanded();
+                            // ctrl+o turns the trace open or closed: once it is not as it first was, ctrl+o was pressed.
+                            if (firstExpanded === undefined)
+                                firstExpanded = expanded;
+                            else if (expanded !== firstExpanded)
+                                keyPressed("trace");
+                            const marks = { success: (text) => theme.fg("success", text), error: (text) => theme.fg("error", text), warning: (text) => theme.fg("warning", text) };
+                            const lines = jobPanelLines(list(), { expanded, width, marks, keys: breathing(theme, Date.now()) });
+                            // Opened, nothing is cut off: every line wraps. Closed, a line each - the panel stays short.
+                            return expanded ? lines.flatMap((line) => wrapKeepingIndent(line, width)) : lines.map((line) => truncateToWidth(line, width));
+                        },
+                        invalidate() { },
+                    };
+                }, { placement: "aboveEditor" });
+            }
+            else if (!active() && mounted) {
+                mounted = false;
+                tui = undefined;
+                target.setWidget(JOB_PANEL_KEY, undefined);
+            }
+            else {
+                tui?.requestRender();
+            }
+        }
+        catch {
+            // The panel is a convenience; losing it must not fail the work it shows.
+        }
+        // The elapsed time moves even when the agents are quiet - a long model call is exactly
+        // when someone looks to see whether anything is happening.
+        if (mounted && timer === undefined) {
+            timer = setInterval(draw, TICK_MS);
+            timer.unref?.();
+            breathTimer = setInterval(() => {
+                // Both pressed: nothing breathes, and the panel is drawn as often as before.
+                if (!breathes("trace") && !breathes("peek")) {
+                    clearInterval(breathTimer);
+                    breathTimer = undefined;
+                    return;
+                }
+                tui?.requestRender();
+            }, BREATH_TICK_MS);
+            breathTimer.unref?.();
+        }
+        else if (!mounted && timer !== undefined) {
+            clearInterval(timer);
+            timer = undefined;
+            if (breathTimer !== undefined)
+                clearInterval(breathTimer);
+            breathTimer = undefined;
+        }
+    };
+    return {
+        attach(next) {
+            // A new session starts with pi's widgets cleared, so whatever was mounted is gone.
+            ui = next;
+            mounted = false;
+            tui = undefined;
+            draw();
+        },
+        refresh() {
+            if (pending !== undefined)
+                return;
+            pending = setTimeout(() => {
+                pending = undefined;
+                draw();
+            }, REDRAW_MS);
+            pending.unref?.();
+        },
+    };
+}