@zenera/cli 1.1.23 → 1.1.25

package/dist/commands/models.js

@@ -11,14 +11,14 @@
 // instead", and prints a ref on stdout that can be pasted straight back into
 // agents.yaml — or read by an agent doing the pasting.
 // ---------------------------------------------------------------------------
-import { createEmbedder, createModel, ModelRegistry } from '@zenera/neo';
+import { createEmbedder, ModelRegistry } from '@zenera/neo';
 import { parse } from "../args.js";
-import { loadCatalog, loadCatalogs, matches, PREFERRED, } from "../catalog.js";
+import { byGroup, groupOf, isPartner, loadCatalog, loadCatalogs, matches, PREFERRED, } from "../catalog.js";
 import { ensureHome } from "../home.js";
 import { envNames, form, isProvider, KeyStore, PROVIDERS } from "../keys.js";
-import { probeModel } from "../liveness.js";
-import { ago, bold, credentialError, cyan, dim, green, json, note, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen models <providers|ls|search|show|test|pick> [ref] [options]';
+import { probeChat, probeModel } from "../liveness.js";
+import { ago, bold, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen models <providers|ls|search|show|test|pick|browse> [ref] [options]';
 /**
  * The keyring is materialised here, and only here.
  *
@@ -112,15 +112,32 @@ function freshness(cat) {
     return cat.origin === 'live' ? green('fetched now') : dim(`cached ${ago(cat.fetchedAt)}`);
 }
 const roleMark = (row) => row.roles.join('+');
+const maker = (row) => !row.publisher ? '' : isPartner(row) ? yellow(row.publisher) : green(row.publisher);
 function row(entry) {
     return [
         cyan(entry.ref),
+        maker(entry),
         dim(roleMark(entry)),
         dim(tokens(entry.contextLength)),
         dim(entry.pricing?.free ? 'free' : ''),
         dim(entry.name ?? ''),
     ];
 }
+/** The table, with a heading wherever a reseller's rows change maker. */
+function grouped(entries) {
+    const lines = table(entries.map(row));
+    const out = [];
+    let last;
+    entries.forEach((e, i) => {
+        const group = groupOf(e);
+        if (group && group !== last) {
+            out.push(...(out.length > 0 ? [''] : []), bold(group));
+        }
+        last = group;
+        out.push(lines[i]);
+    });
+    return out;
+}
 /**
  * Says how a listing was obtained whenever it was not the vendor's own word —
  * on stderr, because it is narration about the answer rather than the answer.
@@ -175,6 +192,7 @@ const providers = async (ctx, args) => {
     })));
     note('');
     note(dim('zen models ls <provider>   what one of them serves'));
+    note(dim('zen models browse          walk them with the arrow keys'));
     note(dim('zen models pick --chat     the first one that answers'));
 };
 // ---------------------------------------------------------------------------
@@ -198,7 +216,7 @@ const ls = async (ctx, args) => {
     const all = cats
         .flatMap((c) => c.entries)
         .filter((e) => matches(e, '', { roles }))
-        .sort((a, b) => a.ref.localeCompare(b.ref));
+        .sort(byGroup);
     if (ctx.json) {
         json({
             models: all,
@@ -215,10 +233,13 @@ const ls = async (ctx, args) => {
         note(dim('nothing matched — try: zen models ls --refresh'));
         return;
     }
-    writeAll(table(all.slice(0, limit).map(row)));
+    writeAll(grouped(all.slice(0, limit)));
     if (all.length > limit) {
         note(dim(`${all.length - limit} more — narrow with \`zen models search\`, or pass --all`));
     }
+    if (all.some(isPartner)) {
+        note(dim('partner models are billed through Vertex and must be enabled in Model Garden first: https://console.cloud.google.com/vertex-ai/model-garden'));
+    }
 };
 // ---------------------------------------------------------------------------
 // search
@@ -255,7 +276,7 @@ const search = async (ctx, args) => {
         // Cheapest first when price is known: search is usually the step before
         // picking one, and the free ones are what most people are looking for.
         .sort((a, b) => Number(b.pricing?.free ?? false) - Number(a.pricing?.free ?? false) ||
-        a.ref.localeCompare(b.ref));
+        byGroup(a, b));
     if (ctx.json) {
         json({ query, matched: hits.length, models: hits.slice(0, limit) });
         return;
@@ -377,9 +398,7 @@ function target(ref, provider, id, role) {
     if (role !== 'chat') {
         throw usageError(`${ref} is ${role}-only, and there is no way to ask it a question from here`, 'zen models test only exercises chat and embedding models');
     }
-    // 16 tokens is enough for "ok" and not enough to matter. Anthropic requires
-    // a cap at all, so this is not merely thrift.
-    return { ref, kind: 'model', model: createModel({ provider, model: id, maxTokens: 16 }) };
+    return { ref, kind: 'model', model: probeChat(provider, id) };
 }
 function verdict(probe) {
     switch (probe.check.state) {
@@ -393,6 +412,18 @@ function verdict(probe) {
             return dim('no answer');
     }
 }
+/**
+ * What the provider said, in the verdict's own colour. Grey is for the half of
+ * the output nobody needs to read, and the one line explaining a refusal is not
+ * in that half.
+ */
+function reason(probe) {
+    const detail = probe.check.detail ?? '';
+    if (detail === '' || probe.check.state === 'live') {
+        return dim(detail);
+    }
+    return probe.check.state === 'dead' ? red(detail) : yellow(detail);
+}
 /**
  * Which project and region a Vertex call was actually made in. A publisher
  * model is only missing *somewhere*, and the somewhere is the part nobody
@@ -429,11 +460,11 @@ const test = async (ctx, args) => {
             cyan(p.ref),
             verdict(p),
             dim(p.dimensions ? `${p.dimensions} dims` : ''),
-            dim(p.check.detail ?? ''),
+            reason(p),
         ])));
         for (const p of probes) {
             if (p.check.fix) {
-                note(dim(`${p.ref}: ${p.check.fix}`));
+                note(`${yellow('fix')} ${bold(p.ref)} ${p.check.fix}`);
             }
         }
         // A Vertex refusal is about a model *in a project*, and the project is
@@ -524,6 +555,67 @@ const pick = async (ctx, args) => {
     throw credentialError(`no ${role} model answered on this machine`, 'add a credential: zen key add openai');
 };
 // ---------------------------------------------------------------------------
+// browse
+// ---------------------------------------------------------------------------
+/**
+ * The same catalog, walked with the arrow keys: providers, what one serves,
+ * one model in full, with a key to ask it a question and a key to take it.
+ *
+ * The interface is drawn on stderr, so a pick reaches stdout alone and
+ * `$(zen models browse)` is the ref, the same contract `pick` keeps.
+ */
+const browse = async (ctx, args) => {
+    const { values, positionals } = parse(args, { refresh: { type: 'boolean' }, theme: { type: 'string' } }, 'zen models browse [provider] [--refresh] [--theme dark|light|auto]');
+    const initial = positionals[0];
+    if (initial !== undefined && !isProvider(initial)) {
+        throw usageError(`unknown provider "${initial}"`, `known: ${PROVIDERS.join(', ')}`);
+    }
+    if (ctx.json || !isInteractive()) {
+        throw usageError('browsing needs a person at a terminal', 'from a script: zen models ls --json, or zen models pick --chat');
+    }
+    const where = await credentials();
+    // Offline, like `providers`: the overview should not cost five listings.
+    // A provider is fetched when it is opened.
+    const cats = await loadCatalogs(PROVIDERS, { offline: true });
+    const { browse: draw } = await import("../tui/models.js");
+    const chosen = await draw({
+        providers: cats.map((c) => ({
+            provider: c.provider,
+            credential: source(where, c.provider),
+            models: c.entries.length,
+            origin: c.origin,
+            fetchedAt: c.fetchedAt,
+        })),
+        initial,
+        theme: values.theme,
+        load: (provider, refresh) => loadCatalog(provider, { refresh: refresh || values.refresh }),
+        test: async (entry) => {
+            const role = entry.roles.includes('chat')
+                ? 'chat'
+                : entry.roles.includes('embedding')
+                    ? 'embedding'
+                    : (entry.roles[0] ?? 'chat');
+            const probe = await probeModel(target(entry.ref, entry.provider, entry.id, role));
+            return {
+                state: probe.check.state,
+                ms: probe.ms,
+                detail: probe.check.detail,
+                fix: probe.check.fix,
+                dimensions: probe.dimensions,
+            };
+        },
+    });
+    if (!chosen) {
+        // Leaving is a fine way to end a browse, but not an answer to a
+        // substitution that was waiting for one.
+        if (!process.stdout.isTTY) {
+            throw new CliError('nothing picked', EXIT.failed);
+        }
+        return;
+    }
+    write(chosen.ref);
+};
+// ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
 const SUBS = {
@@ -536,6 +628,8 @@ const SUBS = {
     test,
     check: test,
     pick,
+    browse,
+    ui: browse,
 };
 export const models = {
     summary: 'What this machine can use: list, search, test and pick models.',
@@ -558,6 +652,8 @@ export const models = {
         '  zen models show <ref>            One model, in full.',
         '  zen models test <ref> …          Ask it one real question.',
         '  zen models pick --embedding      The first ref that answers, on stdout.',
+        '  zen models browse [provider]     Walk providers and models with the',
+        '                                   arrow keys; t asks one, p prints its ref.',
     ],
     run: async (ctx) => {
         const [name, ...rest] = ctx.args;
@@ -576,7 +672,7 @@ export const models = {
             await ls(ctx, ctx.args);
             return;
         }
-        throw usageError(`unknown: zen models ${name}`, `try: ${cyan('providers, ls, search, show, test, pick')} — or a provider: ${dim(PROVIDERS.join(', '))}`);
+        throw usageError(`unknown: zen models ${name}`, `try: ${cyan('providers, ls, search, show, test, pick, browse')} — or a provider: ${dim(PROVIDERS.join(', '))}`);
     },
 };
 //# sourceMappingURL=models.js.map

package/dist/commands/open.js

@@ -3,9 +3,9 @@ import { accessSync, constants, existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join, resolve, sep } from 'node:path';
 import { one, parse } from "../args.js";
+import { editorFiles } from "../meta/editor.js";
 import { project as resolveProject } from "../resolve.js";
-import { editorFiles } from "../scaffold.js";
-import { CliError, cyan, dim, EXIT, json, note, usageError } from "../term.js";
+import { CliError, cyan, dim, EXIT, isInteractive, json, note, usageError } from "../term.js";
 const USAGE = 'zen open [project] [--editor <cmd>] [--wait]';
 /**
  * A project is resolved by name or from the cwd, and the path is handed to an
@@ -247,8 +247,8 @@ function verify(editor) {
             ? 'name one with --editor, or set $ZENERA_EDITOR'
             : `${editor.from} names a command that is not on PATH`);
     }
-    if ((editor.from === '$VISUAL' || editor.from === '$EDITOR') && !process.stdin.isTTY) {
-        throw usageError(`${editor.from} names a terminal editor and there is no terminal here`, 'name a windowed one with --editor, or set $ZENERA_EDITOR');
+    if ((editor.from === '$VISUAL' || editor.from === '$EDITOR') && !isInteractive()) {
+        throw usageError(`${editor.from} names a terminal editor and there is no one at a terminal here`, 'name a windowed one with --editor, or set $ZENERA_EDITOR');
     }
 }
 async function launch(editor, dir) {

package/dist/commands/run.js

@@ -1,29 +1,40 @@
+import { usageByModel } from '@zenera/neo';
 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 { agentEventLog } from "../eventlog.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, drivenByAgent, json, jsonText, note, readStdin, usageError, write, } from "../term.js";
 import { parseChoice } from "../tui/theme.js";
+import { appendUsage } from "../usage.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 +42,18 @@ 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.',
+        '  --events <file>        Append what the agent does to this file as it does it:',
+        '                         one JSON line per model call, tool call and message.',
+        '  --disposable           Remove its containers when it ends, whatever `persist:`',
+        '                         says: for a session that will never be continued.',
         '  --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 +61,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 +102,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 +128,18 @@ export const run = {
             plain: { type: 'boolean' },
             theme: { type: 'string' },
             out: { type: 'string' },
+            events: { type: 'string' },
+            disposable: { type: 'boolean' },
+            '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 +148,34 @@ 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);
+        if (values.events && !shot) {
+            throw usageError('--events records a one-shot run', 'give a prompt or --input');
+        }
         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,20 +185,24 @@ 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,
+            disposable: values.disposable,
         });
         try {
             // The TUI is for the case it is actually good at: a person at a
             // 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);
+                Boolean(process.stdout.isTTY && process.stdin.isTTY) &&
+                !drivenByAgent();
             if (drawing) {
                 const { start } = await import("../tui/app.js");
                 await start(engine, {
@@ -127,10 +212,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,18 +223,72 @@ 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'],
+    ['events', 'each item already has its own output.json'],
+    ['disposable', 'a batch removes its containers already'],
+];
+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),
     });
+    const record = values.events ? agentEventLog(resolve(cwd, values.events)) : undefined;
+    const onEvent = (event) => {
+        narrator.handle(event);
+        record?.(event);
+    };
     // Ctrl-C asks the run to stop rather than killing the process, so the turn
-    // still lands on disk and the session stays resumable.
+    // still lands on disk and the session stays resumable. SIGTERM too: it is
+    // how a tuning stops a run it left behind, and its containers go with it.
     const stopping = new AbortController();
     const onInterrupt = () => stopping.abort();
     process.once('SIGINT', onInterrupt);
+    process.once('SIGTERM', onInterrupt);
     if (!asJson) {
         // Two questions were just answered, possibly without being asked. Say
         // which way they went: a run that quietly resumed the wrong session, or
@@ -162,39 +301,39 @@ 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, onEvent, stopping.signal);
     }
     finally {
         narrator.done();
         process.off('SIGINT', onInterrupt);
+        process.off('SIGTERM', onInterrupt);
     }
-    if (values.out) {
-        await writeFile(values.out, `${outcome.text}\n`, 'utf8');
-    }
+    appendUsage(where.project.dir, {
+        kind: 'run',
+        ts: new Date().toISOString(),
+        runDir: outcome.run.dir,
+        session: engine.session.id,
+        ok: true,
+        stopReason: outcome.result.stopReason,
+        durationMs: outcome.durationMs,
+        models: usageByModel(outcome.result.state.trajectory),
+    });
     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 {