@zenera/cli 1.1.22 → 1.1.24

package/dist/commands/run.js

@@ -1,29 +1,37 @@
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { parse } from "../args.js";
+import { concurrency, runBatch } from "../batch.js";
 import * as Engine from "../engine.js";
 import { duration, Narrator, stopMark, summary } from "../narrate.js";
 import * as Projects from "../projects.js";
+import { readBatch, readRequest } from "../request.js";
 import { target } from "../resolve.js";
 import { display } from "../session.js";
-import { bold, cyan, dim, json, note, readStdin, usageError, write } from "../term.js";
+import { bold, cyan, dim, json, jsonText, note, readStdin, usageError, write } from "../term.js";
 import { parseChoice } from "../tui/theme.js";
 const USAGE = 'zen run [project] [prompt] [options]';
 export const run = {
     summary: 'Run the project — the TUI on a terminal, one shot otherwise.',
     usage: USAGE,
     banner: { head: 'Zenera', accent: 'Neo', subtitle: 'Agentic Runtime', hue: 'orange' },
+    // A batch prints the path of its directory, and a banner above a path is a
+    // banner inside `$(zen run batch ...)`. True whether or not --json is on.
+    quiet: (args) => args[0] === 'batch',
     details: [
         'Arguments:',
         '  [project]   Name of a project. Default: the one you are in.',
         '  [prompt]    Your question, in quotes. Without one, the TUI opens.',
+        '  batch       Run a file full of questions at once. See below.',
         '',
         'Options:',
         '  --project <name|dir>   Which project to run. Default: the one you are in.',
         '  --session <id>         Continue this session.',
         '  --new                  Start a new session without asking which one.',
+        '  --input <file>         Read the whole request from JSON. `-` is stdin.',
         '  --workspace <dir>      Directory the agent can read and write.',
         '  --memory <dir>         Directory the agents remember into.',
+        '  --memory-read-only     Recall from it, write nothing back.',
         '  --model <ref>          Use this model instead of the default.',
         '  --image <ref>          Use this container image to run commands in.',
         '  --read-only            Take away every tool that can write.',
@@ -31,9 +39,14 @@ export const run = {
         '  --plain                Never open the TUI. Needs a prompt.',
         '  --theme <dark|light>   Colours for the TUI. Default: auto.',
         '  --out <file>           Put the answer in this file instead of on screen.',
+        '                         With --json, the file gets the whole JSON envelope.',
         '  --yes                  Answer yes to every question.',
         '  --json                 Print machine-readable JSON (session, run, mounts, output, etc...).',
         '',
+        'Batch options:',
+        '  --batch-dir <dir>      Where the runs live. Default: <project>/batches/<stamp>.',
+        '  --concurrency <n>      How many at a time. Default: 16, most: 32.',
+        '',
         'The first word is the project when it names one, otherwise the prompt.',
         'The answer goes to stdout and the progress to stderr, so `> out.md` keeps',
         'the answer alone and `2>/dev/null` hides the progress.',
@@ -41,6 +54,39 @@ export const run = {
         'A prompt always starts a new session, so --new is for the TUI, where the',
         'alternative is being asked which session to continue.',
         '',
+        '--input names a file holding the whole request - project, input, workspace,',
+        'memory - and what it says wins over the same flag on the line. Its paths are',
+        'relative to the file, so a case travels with the images beside it. It is the',
+        'way to ask about a picture, and it never opens the TUI:',
+        '',
+        '  { "input": [{ "text": "what is this?" }, { "image": "./shot.png" }] }',
+        '',
+        '`zen run batch --input cases.json` asks a whole file of them at once. The',
+        'file is the same shape, pluralised, and nothing else is allowed in it:',
+        '',
+        '  { "batch": [{ "id": "vat", "input": "what is VAT?" }, { "input": "..." }] }',
+        '',
+        'Every item is its own session, in its own directory under the batch dir:',
+        '',
+        '  <batch-dir>/<id>/workspace/     what that item could read and write',
+        '  <batch-dir>/<id>/memory/        its own copy, in the copying mode',
+        '  <batch-dir>/<id>/output.json    exactly what `zen run --json` prints',
+        '  <batch-dir>/batch.json          the index: every item, ok, and its file',
+        '  <batch-dir>/README.md           a dashboard, rewritten every second',
+        '',
+        'Memory comes in two modes, because a memory is a locked directory and',
+        'sixteen runs cannot hold one lock. With --memory-read-only they all recall',
+        'from the one graph and write nothing. Without it, each gets a copy, and the',
+        "project's own memory is never touched - fold them back in afterwards with",
+        '`zen memory merge <batch-dir>/*/memory`. An item that committed nothing',
+        'leaves no memory behind, and a --memory that does not exist yet starts every',
+        'item from an empty graph - which is how a cold project is warmed.',
+        '',
+        'A batch prints the path of its directory and nothing else; --json prints',
+        'the index there instead. An item that fails is written down like any other',
+        'and the exit code says how many did, so one bad question costs one answer.',
+        'For a project or a prompt actually called "batch", say --project batch.',
+        '',
         'Examples:',
         '  zen run                               open the TUI in this project',
         '  zen run acme                          open the TUI in the acme project',
@@ -49,17 +95,24 @@ export const run = {
         '  zen run "what changed?" > out.md      redirect the answer into a file',
         '  zen run --out out.md "what changed?"  write the answer to out.md only',
         '  zen run --json "what changed?"        output JSON with workspace, run paths, state, etc...',
+        '  zen run --input case.json --json      run a request from a file, answer as JSON',
+        '  zen run --input case.json --json --out result.json    ... into a file',
         '  zen run --read-only "what changed?"   let it read but not write',
         '  zen run --memory ./mem                remember into ./mem, not the project',
         '  zen run --new                         open the TUI in a new session',
+        '  zen run batch --input cases.json      ask them all, 16 at a time',
+        '  zen run batch --input cases.json --memory-read-only    ... sharing one memory',
+        '  zen run batch --input cases.json --json | jq .batch_results',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
             session: { type: 'string' },
             new: { type: 'boolean' },
+            input: { type: 'string' },
             workspace: { type: 'string' },
             memory: { type: 'string' },
+            'memory-read-only': { type: 'boolean' },
             model: { type: 'string' },
             image: { type: 'string' },
             'no-keys': { type: 'boolean' },
@@ -68,8 +121,16 @@ export const run = {
             plain: { type: 'boolean' },
             theme: { type: 'string' },
             out: { type: 'string' },
+            'batch-dir': { type: 'string' },
+            concurrency: { type: 'string' },
         }, USAGE);
         const piped = await readStdin();
+        // Before the first positional is read as a project name, because in a
+        // batch it is not one and `batch` is not a prompt either.
+        if (positionals[0] === 'batch') {
+            await batch(ctx, values, positionals.slice(1), piped);
+            return;
+        }
         // `zen run acme` is what everyone types before finding --project, and a
         // project name is a bare word where a prompt is a sentence. So the
         // first positional is read as a project when it names one and as the
@@ -78,23 +139,31 @@ export const run = {
         // there for the day a project is called "why".
         const [head, ...rest] = positionals;
         const named = !values.project && head ? await Projects.find(head) : undefined;
-        const prompt = (named ? rest : positionals).join(' ').trim() || piped;
+        const typed = (named ? rest : positionals).join(' ').trim();
+        if (values.input && typed) {
+            throw usageError('a prompt and --input both say what to ask', 'put the prompt in the file, or drop --input');
+        }
         if (values.theme !== undefined && !parseChoice(values.theme)) {
             throw usageError(`unknown theme: ${values.theme}`, 'dark, light or auto');
         }
+        // With `--input -` the pipe carries the request, not the prompt, so it
+        // is read here and never looked at again below.
+        const request = values.input ? await readRequest(values.input, ctx.cwd, piped) : undefined;
+        const prompt = typed || (request ? '' : (piped ?? ''));
         // A prompt on the command line is a request for an answer, not a
         // conversation to pick up. So it answers the three questions itself:
         // a fresh session, the directory it was typed in as the workspace,
         // and no confirmation for it — `zen run acme "what changed?"` should
         // read the code that is right there. Every flag still wins, and the
         // TUI, where there is someone to ask, still asks.
-        const shot = Boolean(prompt);
+        const input = request ? request.input : prompt;
+        const shot = Boolean(prompt) || Boolean(request);
         const where = await target({
             cwd: ctx.cwd,
-            project: values.project ?? (named ? head : undefined),
+            project: request?.project ?? values.project ?? (named ? head : undefined),
             session: values.session,
             fresh: values.new || (shot && !values.session),
-            workspace: values.workspace ?? (shot ? ctx.cwd : undefined),
+            workspace: request?.workspace ?? values.workspace ?? (shot ? ctx.cwd : undefined),
             yes: values.yes || shot,
         });
         const engine = await Engine.open({
@@ -104,8 +173,10 @@ export const run = {
             model: values.model,
             image: values.image,
             // Relative to where it was typed, like every other path on the line
-            // — the project root is not the cwd.
-            memoryDir: values.memory ? resolve(ctx.cwd, values.memory) : undefined,
+            // — the project root is not the cwd. A request's paths are already
+            // absolute, resolved against the file rather than against this.
+            memoryDir: request?.memory ?? (values.memory ? resolve(ctx.cwd, values.memory) : undefined),
+            memoryReadOnly: values['memory-read-only'],
             keys: values['no-keys'] ? false : undefined,
             yes: values.yes || ctx.json,
         });
@@ -114,7 +185,7 @@ export const run = {
             // terminal, with nothing to say yet. A prompt on the command line
             // is a request for an answer, and drawing a full-screen interface
             // over it would be worse than not drawing one.
-            const drawing = !prompt &&
+            const drawing = !shot &&
                 !values.plain &&
                 !ctx.json &&
                 Boolean(process.stdout.isTTY && process.stdin.isTTY);
@@ -127,10 +198,10 @@ export const run = {
                 });
                 return;
             }
-            if (!prompt) {
+            if (!shot) {
                 throw usageError('nothing to ask', 'give a prompt, or pipe one in');
             }
-            await once(engine, prompt, values, ctx.json, ctx.cwd, where);
+            await once(engine, input, values, ctx.json, ctx.cwd, where);
         }
         finally {
             await engine.close();
@@ -138,9 +209,54 @@ export const run = {
     },
 };
 // ---------------------------------------------------------------------------
+// Many shots
+// ---------------------------------------------------------------------------
+/**
+ * Flags that mean something to one run and nothing to a hundred. Refused by
+ * name rather than ignored: a `--workspace` that was quietly dropped is a batch
+ * whose answers came from somewhere else.
+ */
+const NOT_IN_A_BATCH = [
+    ['session', 'every item is a new session of its own'],
+    ['new', 'every item is new already'],
+    ['workspace', 'they cannot share one; each item gets its own, or names one in the file'],
+    ['plain', 'a batch never draws the TUI'],
+    ['theme', 'a batch never draws the TUI'],
+];
+async function batch(ctx, values, rest, piped) {
+    if (rest.length > 0) {
+        throw usageError(`zen run batch: nothing goes after "batch" (got "${rest[0]}")`, 'the questions live in the file named by --input');
+    }
+    for (const [flag, why] of NOT_IN_A_BATCH) {
+        if (values[flag] !== undefined && values[flag] !== false) {
+            throw usageError(`--${flag} means nothing in a batch`, why);
+        }
+    }
+    if (!values.input) {
+        throw usageError('zen run batch needs --input <file>', 'a JSON file holding the batch');
+    }
+    await runBatch({
+        request: await readBatch(values.input, ctx.cwd, piped),
+        input: values.input === '-' ? '<stdin>' : resolve(ctx.cwd, values.input),
+        dir: values['batch-dir'],
+        cwd: ctx.cwd,
+        project: values.project,
+        memory: values.memory ? resolve(ctx.cwd, values.memory) : undefined,
+        memoryReadOnly: values['memory-read-only'],
+        concurrency: concurrency(values.concurrency),
+        model: values.model,
+        image: values.image,
+        readOnly: values['read-only'],
+        keys: values['no-keys'] ? false : undefined,
+        yes: values.yes,
+        out: values.out,
+        json: ctx.json,
+    });
+}
+// ---------------------------------------------------------------------------
 // One shot
 // ---------------------------------------------------------------------------
-async function once(engine, prompt, values, asJson, cwd, where) {
+async function once(engine, input, values, asJson, cwd, where) {
     const narrator = new Narrator({
         quiet: asJson,
         live: Boolean(process.stderr.isTTY),
@@ -162,39 +278,28 @@ async function once(engine, prompt, values, asJson, cwd, where) {
     }
     let outcome;
     try {
-        outcome = await Engine.run(engine, prompt, narrator.handle, stopping.signal);
+        outcome = await Engine.run(engine, input, narrator.handle, stopping.signal);
     }
     finally {
         narrator.done();
         process.off('SIGINT', onInterrupt);
     }
-    if (values.out) {
-        await writeFile(values.out, `${outcome.text}\n`, 'utf8');
-    }
     if (asJson) {
-        json({
-            session: { id: engine.session.id, dir: engine.session.dir },
-            run: {
-                id: outcome.run.id,
-                dir: outcome.run.dir,
-                input: outcome.run.input,
-                output: outcome.run.output,
-                state: outcome.run.state,
-                meta: outcome.run.meta,
-                ...(outcome.report ? { report: outcome.report } : {}),
-            },
-            mounts: Engine.mounts(engine),
-            agent: outcome.result.agent,
-            stopReason: outcome.result.stopReason,
-            durationMs: outcome.durationMs,
-            usage: outcome.result.usage,
-            output: outcome.text,
-        });
+        // --out is a destination, not a copy, and with --json the answer *is*
+        // the envelope — so that is what lands in the file, not the prose.
+        const body = Engine.envelope(engine, outcome);
+        if (values.out) {
+            await writeFile(values.out, jsonText(body), 'utf8');
+        }
+        else {
+            json(body);
+        }
         return;
     }
-    // --out is a destination, not a copy: the answer goes there instead of to
+    // The same rule for prose: the answer goes to the file instead of to
     // stdout, so a redirect and a file cannot both end up holding it.
     if (values.out) {
+        await writeFile(values.out, `${outcome.text}\n`, 'utf8');
         note(dim(`answer: ${cyan(values.out)}`));
     }
     else {

package/dist/commands/sandbox.js

@@ -1,4 +1,4 @@
-import { readProjectConfig } from '@zenera/neo';
+import { readProjectConfig, sandboxLimits, } from '@zenera/neo';
 import { parse } from "../args.js";
 import { resolveBuild } from "../image.js";
 import { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "../podman.js";
@@ -9,6 +9,8 @@ const USAGE = 'zen sandbox [status|up|pull|clean|disk] [options]';
 const LISTED = 6;
 /** Under the labels, which is where the eye already is. */
 const INDENT = ' '.repeat(11);
+/** `agents.yaml` states memory in MiB; `bytes` prints bytes. */
+const MIB = 1024 * 1024;
 // ---------------------------------------------------------------------------
 // The container engine, on its own
 //
@@ -97,6 +99,7 @@ async function projectSandbox(cwd, values) {
             name: found.name,
             image: build?.tag ?? config.sandbox?.image,
             build,
+            limits: widest(config),
         };
     }
     catch {
@@ -118,6 +121,8 @@ async function status(project, image, asJson) {
             ...found,
             project: project?.name ?? null,
             dockerfile: build?.dockerfile ?? null,
+            limits: project?.limits ?? null,
+            fits: fits(found.capacity?.memory, project?.limits?.memory) ?? null,
             containers,
         });
         return;
@@ -128,7 +133,17 @@ async function status(project, image, asJson) {
         const state = found.machine.starting ? yellow('starting') : mark(found.machine.running);
         write(`${bold('machine')}    ${found.machine.name} ${state}`);
     }
+    if (found.connection) {
+        // A concurrency limit wearing a connection string: `ssh://` opens one
+        // connection per call and sshd refuses them past ten, which stays
+        // invisible until a batch is wide enough to lose tasks at random.
+        const how = found.connection.shared
+            ? dim('· one shared connection, no limit on parallel calls')
+            : yellow('· a new ssh connection per call — about 10 at a time');
+        write(`${bold('connection')} ${dim(found.connection.uri)} ${how}`);
+    }
     write(`${bold('responds')}   ${mark(found.ready)}`);
+    writeAll(limitLines(found, project?.limits));
     if (project) {
         write(`${bold('project')}    ${project.name} ${dim(project.dir)}`);
     }
@@ -144,6 +159,62 @@ async function status(project, image, asJson) {
         note(dim('run `zen sandbox up` to fix what can be fixed.'));
     }
 }
+/**
+ * The hungriest container this project can start. An agent may override the
+ * project's `sandbox:` block, and it is the largest of them that decides
+ * whether a batch fits — reporting the project's own figure would understate
+ * the machine by however much an agent asked for on top.
+ *
+ * The overrides are merged onto the project's block rather than read alone,
+ * because that is what `SandboxPool.for` does when it builds the container: an
+ * agent that names only `memory:` still runs with the project's `cpus:`.
+ */
+function widest(config) {
+    const base = config.sandbox ?? {};
+    return config.agents
+        .map((a) => sandboxLimits(a.sandbox ? { ...base, ...a.sandbox } : base))
+        .reduce((most, one) => (one.memory > most.memory ? one : most), sandboxLimits(base));
+}
+/**
+ * How many containers of this size the engine could hold at once.
+ *
+ * Nothing enforces it — `--memory` caps one container and the kernel kills
+ * whatever overruns the sum, so this is what the machine can honour, not a
+ * gate anything checks. It is worth printing because neither figure gives it
+ * alone: off Linux the memory is the *machine's*, which has nothing to do with
+ * the host, so a few containers at the 4096 MiB default can be past it while
+ * the laptop sits nearly empty.
+ */
+function fits(capacity, container) {
+    if (!capacity || !container) {
+        return undefined;
+    }
+    return Math.max(0, Math.floor(capacity / container));
+}
+/**
+ * Two ceilings, in the order they bite: what the engine has, and what one
+ * container is permitted to take of it.
+ */
+function limitLines(found, limits) {
+    const lines = [];
+    const where = found.machine ? 'machine' : 'host';
+    if (found.capacity) {
+        const { memory, swap, cpus } = found.capacity;
+        const swapped = swap > 0 ? `${bytes(swap * MIB)} swap` : 'no swap';
+        lines.push(`${bold('capacity')}   ${bytes(memory * MIB)} ${dim(`· ${swapped} · ${cpus} cpus · the ${where}'s, not the host's`)}`);
+    }
+    if (limits) {
+        const room = fits(found.capacity?.memory, limits.memory);
+        const how = limits.declared ? limits.hardening : `${limits.hardening} defaults`;
+        const tail = room === undefined
+            ? how
+            : room > 0
+                ? `· ${how} · the ${where} has room for ${room}`
+                : `· ${how} · more than the ${where} has`;
+        lines.push(`${bold('container')}  ${bytes(limits.memory * MIB)} ${dim(`· ${limits.cpus} cpus ${tail}`)}`);
+    }
+    return lines;
+}
 /**
  * The containers this project's sessions made. A container carries the session
  * id that made it in a label, and a session id is a directory name under the

package/dist/engine.d.ts

@@ -12,10 +12,18 @@ export interface EngineOptions {
     image?: string;
     /** another directory to remember into — `--memory` */
     memoryDir?: string;
+    /** recall only: nothing is written and several runs may share one graph */
+    memoryReadOnly?: boolean;
     /** whether credentials reach the sandbox — `--no-keys` sets this false */
     keys?: boolean;
     /** answer the sandbox's install question without asking — `--yes` */
     yes?: boolean;
+    /**
+     * Hold back the warnings about the project rather than the run. A batch
+     * opens one project a hundred times, and a hundred copies of the same
+     * complaint is a worse report than one.
+     */
+    quiet?: boolean;
 }
 export interface Engine {
     project: AgentProject;
@@ -27,6 +35,8 @@ export interface Engine {
     /** whether the agent was denied every writing tool */
     readOnly: boolean;
     session: SessionPaths;
+    /** the graph this session remembers into, when any agent has one */
+    memory?: string;
     /** the session's accumulated state, when it has one */
     state?: AgentState;
     /** the containers this session may start; present whether or not it does */
@@ -56,7 +66,16 @@ export interface RunOutcome {
     durationMs: number;
     /** where the report landed, when one could be rendered */
     report?: string;
+    /** where the Mermaid graph landed, when one could be emitted */
+    graph?: string;
 }
+/**
+ * What one finished run looks like to a program: `zen run --json` prints it,
+ * and a batch writes one beside every item. The same function on purpose — a
+ * batch whose items were shaped differently would make every consumer of a
+ * single run a special case.
+ */
+export declare function envelope(engine: Engine, outcome: RunOutcome): Record<string, unknown>;
 /**
  * One turn. The session's state decides whether this starts a run or continues
  * one — which is the whole of what `resume` used to be, and why it is not a

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
+import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, fileTools, lastText, loadProject, memoryDir, readProjectConfig, renderReportHtml, sandboxTools, turns, } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -8,8 +8,9 @@ import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
 import { projectMounts } from "./projects.js";
 import { buildSandbox, preflight, teardown, usesSandbox } from "./sandbox.js";
-import { acquire, createRun, readSessionMeta, writeSessionMeta, } from "./session.js";
+import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
 import { CliError, EXIT, invalidError, warn } from "./term.js";
+import { traceMermaid } from "./trace.js";
 /**
  * Wires the library to a session directory. Every store is file-backed and
  * rooted inside `.data/`, so a session is self-contained: copy the directory
@@ -27,7 +28,9 @@ export async function open(opts) {
     // build: one SDK's words about one model, when the useful answer is which
     // of the project's models are reachable and which are not.
     for (const issue of auditModels(opts.project.dir, keys)) {
-        warn(describeIssue(issue));
+        if (!opts.quiet) {
+            warn(describeIssue(issue));
+        }
     }
     const meta = await readSessionMeta(opts.session);
     const workspace = resolve(meta.workspace);
@@ -40,13 +43,15 @@ export async function open(opts) {
     let sandbox;
     let project;
     let files;
+    let memory;
     try {
         const { root, config } = readProjectConfig(opts.project.dir);
         // Naming a directory declares the graph, but it cannot bind anyone to
         // it — so say when the run is pointed at a memory no agent will touch.
-        if (opts.memoryDir && !config.agents.some((a) => a.memory)) {
+        if (opts.memoryDir && !opts.quiet && !config.agents.some((a) => a.memory)) {
             warn('--memory names a directory no agent uses — none has `memory: true`');
         }
+        memory = memoryDir(root, config, opts.memoryDir);
         // Assets and the skill catalog are mounted for both, under one name.
         const mounts = projectMounts(root, config, opts.memoryDir);
         sandbox = buildSandbox({
@@ -74,7 +79,7 @@ export async function open(opts) {
                 // Both groups are pointed at one directory, so both are told the
                 // one name for it: whatever `run_command` prints a path as,
                 // `read_file` accepts.
-                ...workspaceTools(workspaceOptions),
+                ...fileTools(workspaceOptions),
                 ...sandboxTools(sandbox.pool),
                 // Registered whether or not a key exists: the credential is
                 // read when a tool is called, so a project that names `exa:*`
@@ -84,6 +89,7 @@ export async function open(opts) {
             ],
             skillsAt: SKILLS_MOUNT,
             memoryDir: opts.memoryDir,
+            memoryReadOnly: opts.memoryReadOnly,
             payloads,
             resolveFile: (path) => files.within(path),
         });
@@ -118,6 +124,7 @@ export async function open(opts) {
         workspaceMount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
         readOnly: Boolean(opts.readOnly),
         session: opts.session,
+        memory,
         state,
         sandbox,
         lock,
@@ -151,6 +158,33 @@ export function mounts(engine) {
         })),
     ];
 }
+/**
+ * What one finished run looks like to a program: `zen run --json` prints it,
+ * and a batch writes one beside every item. The same function on purpose — a
+ * batch whose items were shaped differently would make every consumer of a
+ * single run a special case.
+ */
+export function envelope(engine, outcome) {
+    return {
+        session: { id: engine.session.id, dir: engine.session.dir },
+        run: {
+            id: outcome.run.id,
+            dir: outcome.run.dir,
+            input: outcome.run.input,
+            output: outcome.run.output,
+            state: outcome.run.state,
+            meta: outcome.run.meta,
+            ...(outcome.report ? { report: outcome.report } : {}),
+            ...(outcome.graph ? { graph: outcome.graph } : {}),
+        },
+        mounts: mounts(engine),
+        agent: outcome.result.agent,
+        stopReason: outcome.result.stopReason,
+        durationMs: outcome.durationMs,
+        usage: outcome.result.usage,
+        output: outcome.text,
+    };
+}
 /**
  * One turn. The session's state decides whether this starts a run or continues
  * one — which is the whole of what `resume` used to be, and why it is not a
@@ -205,7 +239,24 @@ async function record(engine, input, result, startedAt, durationMs) {
     catch {
         // A report is a convenience. Losing it must not lose the run.
     }
-    writeJson(run.meta, {
+    // The same trajectory for the other reader. `report.html` is for a person;
+    // this is what `zen inspect graph` prints, written down while the state is
+    // already in hand — a batch of a hundred items is otherwise a hundred more
+    // commands to run before anything can be read.
+    let graph;
+    try {
+        await writeFile(run.graph, traceMermaid(result.state, {
+            runId: run.id,
+            dir: run.dir,
+            workspace: engine.workspace,
+            memory: engine.memory,
+        }), 'utf8');
+        graph = run.graph;
+    }
+    catch {
+        // Same rule as the report: a view of the run is not the run.
+    }
+    writeRunMeta(run, {
         version: 1,
         id: run.id,
         session: session.id,
@@ -217,9 +268,10 @@ async function record(engine, input, result, startedAt, durationMs) {
         turns: turns(result.state),
         usage: result.usage,
         workspace: engine.workspace,
+        memory: engine.memory,
         error: result.state.error,
-    }, 0o644);
-    return { run, result, text, durationMs, report };
+    });
+    return { run, result, text, durationMs, report, graph };
 }
 function asText(input) {
     if (typeof input === 'string') {

package/dist/liveness.js

@@ -1,4 +1,4 @@
-import { EXA_BASE_URL, ModelRegistry, text, } from '@zenera/neo';
+import { EXA_BASE_URL, isUnfunded, ModelRegistry, text, } from '@zenera/neo';
 import { envOf, SHAPES, } from "./keys.js";
 // ---------------------------------------------------------------------------
 // Liveness
@@ -89,8 +89,11 @@ export function classify(err) {
         };
     }
     // A 429 is this minute's rate limit, not an empty account, and the two
-    // share vocabulary — so a status that says "slow down" wins.
-    if (status !== 429 && UNFUNDED.some((needle) => haystack.includes(needle))) {
+    // share vocabulary — so a status that says "slow down" wins. Unless the
+    // vendor named the refusal itself: `credit_balance_exhausted` is a 429 too,
+    // and it is the account.
+    if (isUnfunded(err) ||
+        (status !== 429 && UNFUNDED.some((needle) => haystack.includes(needle)))) {
         return {
             state: 'blocked',
             at,

package/dist/main.js

@@ -6,7 +6,7 @@ import { NEO_BANNER, printBanner } from "./banner.js";
 import { ALIASES, COMMANDS, EXTERNAL } from "./commands/index.js";
 import { cliManifest, versionOf } from "./commands/version.js";
 import { hasExternal, loadExternal } from "./external.js";
-import { CliError, EXIT, bold, cyan, dim, fail, note, pad, title, write } from "./term.js";
+import { CliError, EXIT, bold, cyan, deferBanner, dim, fail, note, pad, title, write, } from "./term.js";
 /** What the user typed: `zen`, `zn` or `zenera` all arrive here. */
 const NAME = invokedAs('zen');
 /** Usage lines are written against `zen`. Say them back in the reader's word. */
@@ -66,9 +66,12 @@ async function main(argv) {
     // actually there — a banner over "not installed" is a claim about nothing.
     const ragSearch = name === 'rag' && ['docs', 'schema'].includes(rest[0]) && rest[1] === 'search';
     const interactive = rest.includes('--interactive');
+    const answers = command?.quiet?.(rest) === true;
     if (!json && (!ragSearch || interactive)) {
         const brand = external && hasExternal(external) ? external.banner : command?.banner;
-        printBanner(brand ?? NEO_BANNER, { full: ragSearch && interactive });
+        const show = () => printBanner(brand ?? NEO_BANNER, { full: ragSearch && interactive });
+        // A command that answers holds its banner back until it has to ask.
+        answers ? deferBanner(show) : show();
     }
     if (parts.name === 'help') {
         await usage(rest[0]);