@zenera/cli 1.1.22 → 1.1.24

package/dist/podman.d.ts

@@ -28,12 +28,28 @@ export interface PodmanStatus {
         running: boolean;
         starting: boolean;
     };
+    /** how this client reaches the engine, and whether one connection carries every call */
+    connection?: {
+        uri: string;
+        shared: boolean;
+    };
     /** whether `podman info` answered */
     ready: boolean;
+    /** what the engine has to hand out: the machine's on macOS and Windows, the host's on Linux */
+    capacity?: {
+        memory: number;
+        swap: number;
+        cpus: number;
+    };
     image?: string;
     imagePresent?: boolean;
 }
 export declare function ensurePodmanReady(opts?: PodmanOptions): Promise<void>;
+/**
+ * The machine's forwarded endpoint as a URI this client accepts, or nothing
+ * when there is no machine to ask.
+ */
+export declare function sharedEndpoint(engine?: string, exec?: import("@zenera/neo").Runner): Promise<string | undefined>;
 /**
  * A build that ran and failed, rather than a host that could not be asked.
  *

package/dist/podman.js

@@ -56,11 +56,19 @@ async function preflight(opts) {
     //    containers natively and has no machine to list, so asking would fail
     //    with a message about an unknown command rather than about anything
     //    true.
+    let shared;
     if (platform() !== 'linux') {
         await machine(engine, call, opts, run);
+        shared = await shareConnection(engine, run);
     }
     // 3. The socket. Everything above can be true while the engine is wedged.
-    const info = await call(['info'], 60_000);
+    let info = await call(['info'], 60_000);
+    if (info.code !== 0 && shared && process.env.CONTAINER_HOST === shared) {
+        // The shared endpoint is an optimisation, so it never gets to be the
+        // reason a run fails: put the default connection back and ask again.
+        delete process.env.CONTAINER_HOST;
+        info = await call(['info'], 60_000);
+    }
     if (info.code !== 0) {
         throw sandboxError(`${engine} is installed but not responding`, first(info) || `try: ${engine} machine start`);
     }
@@ -226,6 +234,93 @@ function parseMachines(stdout) {
         throw sandboxError('could not read `podman machine list --format json`');
     }
 }
+/**
+ * The machine's forwarded endpoint as a URI this client accepts, or nothing
+ * when there is no machine to ask.
+ */
+export async function sharedEndpoint(engine = 'podman', exec = runProcess) {
+    if (platform() === 'linux') {
+        return undefined;
+    }
+    const res = await exec(engine, ['machine', 'inspect'], { timeoutMs: 30_000 }).catch(() => undefined);
+    if (!res || res.code !== 0) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(res.stdout.trim() || '[]');
+    }
+    catch {
+        return undefined;
+    }
+    const one = (Array.isArray(raw) ? raw : [])[0];
+    // Windows first: a named pipe is the only endpoint there, and `\\.\pipe\x`
+    // is spelled `//./pipe/x` in a URI.
+    const pipe = one?.ConnectionInfo?.PodmanPipe?.Path;
+    if (pipe) {
+        return `npipe://${pipe.replaceAll('\\', '/')}`;
+    }
+    const socket = one?.ConnectionInfo?.PodmanSocket?.Path;
+    return socket ? `unix://${socket}` : undefined;
+}
+/**
+ * Points this process at the shared endpoint, and returns what it set so the
+ * caller can take it back if the engine then fails to answer.
+ *
+ * An explicit `CONTAINER_HOST` or `CONTAINER_CONNECTION` is the user's choice
+ * about which engine to talk to, which is not ours to overrule for a
+ * throughput win.
+ */
+async function shareConnection(engine, exec) {
+    if (process.env.CONTAINER_HOST || process.env.CONTAINER_CONNECTION) {
+        return undefined;
+    }
+    const uri = await sharedEndpoint(engine, exec);
+    if (uri) {
+        process.env.CONTAINER_HOST = uri;
+    }
+    return uri;
+}
+/**
+ * The connection a run will use, which is what a report about concurrency has
+ * to name — not the one that is configured today.
+ *
+ * `status` deliberately changes nothing, so it does not set `CONTAINER_HOST`
+ * the way `ensurePodmanReady` does; it asks the same question in the same
+ * order instead, and so answers for the run that has not happened yet. The
+ * `ssh://` fallback is therefore the machine where the shared endpoint could
+ * not be found, which is exactly the one worth saying so about.
+ */
+async function connectionOf(engine, exec) {
+    const held = process.env.CONTAINER_HOST;
+    if (held) {
+        return { uri: held, shared: !held.startsWith('ssh://') };
+    }
+    const shared = process.env.CONTAINER_CONNECTION
+        ? undefined
+        : await sharedEndpoint(engine, exec);
+    if (shared) {
+        return { uri: shared, shared: true };
+    }
+    const res = await exec(engine, ['system', 'connection', 'list', '--format', 'json'], {
+        timeoutMs: 30_000,
+    }).catch(() => undefined);
+    if (!res || res.code !== 0) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(res.stdout.trim() || '[]');
+    }
+    catch {
+        return undefined;
+    }
+    const all = Array.isArray(raw) ? raw : [];
+    const named = process.env.CONTAINER_CONNECTION;
+    const uri = (named ? all.find((c) => c.Name === named) : undefined)?.URI ??
+        (all.find((c) => c.Default) ?? all[0])?.URI;
+    return uri ? { uri, shared: !uri.startsWith('ssh://') } : undefined;
+}
 // ---------------------------------------------------------------------------
 // The image
 // ---------------------------------------------------------------------------
@@ -294,9 +389,27 @@ export async function podmanStatus(opts = {}) {
                 starting: Boolean(chosen.Starting),
             };
         }
+        status.connection = await connectionOf(engine, run);
     }
-    const info = await call(['info']);
+    // The same `info` answers both questions, and the memory is the one worth
+    // printing: off Linux it is the machine's, which is neither the host's nor
+    // anything the container limits in agents.yaml were written against.
+    const info = await call([
+        'info',
+        '--format',
+        '{{.Host.MemTotal}} {{.Host.SwapTotal}} {{.Host.CPUs}}',
+    ]);
     status.ready = info?.code === 0;
+    if (info?.code === 0) {
+        const [memory, swap, cpus] = info.stdout.trim().split(/\s+/).map(Number);
+        if (Number.isFinite(memory) && memory > 0) {
+            status.capacity = {
+                memory: Math.round(memory / 1048576),
+                swap: Number.isFinite(swap) ? Math.round(swap / 1048576) : 0,
+                cpus: Number.isFinite(cpus) ? cpus : 0,
+            };
+        }
+    }
     if (opts.image) {
         status.image = opts.image;
         const exists = status.ready ? await call(['image', 'exists', opts.image]) : undefined;

package/dist/progress.d.ts

@@ -0,0 +1,33 @@
+import { type AgentEvent, type ModelUsage, type TokenUsage } from '@zenera/neo';
+import type { BatchItem } from './request.ts';
+export type ItemStatus = 'queued' | 'running' | 'ok' | 'failed';
+export interface ProgressOptions {
+    dir: string;
+    project: string;
+    projectDir: string;
+    /** the batch file this came from */
+    input: string;
+    concurrency: number;
+    memory: string;
+    items: readonly BatchItem[];
+}
+export declare class BatchProgress {
+    #private;
+    constructor(opts: ProgressOptions);
+    get file(): string;
+    /** Starts the ticking. Unref'd: the dashboard never holds the process open. */
+    begin(): void;
+    /** The event sink for one item, ready to hand to `Engine.run`. */
+    watch(id: string): (event: AgentEvent) => void;
+    finish(id: string, outcome: {
+        ok: boolean;
+        error?: string;
+        usage?: TokenUsage;
+        models?: readonly ModelUsage[];
+    }): void;
+    /** Stops the clock and leaves the file as the record of the finished batch. */
+    close(): Promise<void>;
+    /** Exported for the tests: the whole file, from the state in hand. */
+    render(): string;
+}
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.js

@@ -0,0 +1,402 @@
+import { addUsage, isCheckpoint, mergeModelUsage, zeroUsage, } from '@zenera/neo';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { duration, format } from "./narrate.js";
+/**
+ * What a batch looks like while it is still running.
+ *
+ * A hundred interleaved event streams on one terminal is not progress, it is
+ * noise — but the same events, folded per item and written to one file, are a
+ * dashboard. So the batch directory keeps a `README.md` that is rewritten once
+ * a second: open it in any editor with a preview and it is a live view of
+ * every run, and when the batch ends the last write leaves the same file as
+ * the report of what happened.
+ *
+ * Nothing here is load-bearing. Every number is derived from events that are
+ * also recorded properly elsewhere, and a failed write is swallowed: a batch
+ * must not die because its dashboard could not be refreshed.
+ */
+const TICK_MS = 1000;
+/** How much of the model's last words to keep. Enough to recognise, not to read. */
+const TAIL = 220;
+const BAR_WIDTH = 28;
+/** A line no wider than this is one line in the panel, on any screen. */
+const PANEL_WIDTH = 116;
+export class BatchProgress {
+    #opts;
+    #items;
+    #startedAt = Date.now();
+    #timer;
+    #writing;
+    #again = false;
+    #finishedAt;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#items = opts.items.map((item) => ({
+            id: item.id,
+            index: item.index,
+            question: question(item.input),
+            status: 'queued',
+            stage: 'queued',
+            turns: 0,
+            tools: 0,
+            usage: zeroUsage(),
+            models: [],
+        }));
+    }
+    get file() {
+        return join(this.#opts.dir, 'README.md');
+    }
+    /** Starts the ticking. Unref'd: the dashboard never holds the process open. */
+    begin() {
+        this.#timer ??= setInterval(() => void this.#flush(), TICK_MS);
+        this.#timer.unref?.();
+        void this.#flush();
+    }
+    /** The event sink for one item, ready to hand to `Engine.run`. */
+    watch(id) {
+        const item = this.#find(id);
+        item.status = 'running';
+        item.stage = 'starting';
+        item.startedAt = Date.now();
+        return (event) => this.#on(item, event);
+    }
+    finish(id, outcome) {
+        const item = this.#find(id);
+        item.status = outcome.ok ? 'ok' : 'failed';
+        item.stage = outcome.ok ? 'done' : 'failed';
+        item.finishedAt = Date.now();
+        item.error = outcome.error;
+        // The result's own accounting is the authority; the running total is
+        // only what the events happened to carry.
+        if (outcome.usage) {
+            item.usage = outcome.usage;
+        }
+        if (outcome.models) {
+            item.models = outcome.models;
+        }
+    }
+    /** Stops the clock and leaves the file as the record of the finished batch. */
+    async close() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = undefined;
+        }
+        this.#finishedAt = Date.now();
+        for (const item of this.#items) {
+            if (item.status === 'running') {
+                item.status = 'failed';
+                item.stage = 'interrupted';
+                item.error = 'interrupted before it finished';
+                item.finishedAt = this.#finishedAt;
+            }
+        }
+        await this.#flush();
+    }
+    #find(id) {
+        const item = this.#items.find((i) => i.id === id);
+        if (!item) {
+            throw new Error(`no such batch item: ${id}`);
+        }
+        return item;
+    }
+    #on(item, event) {
+        item.branch = event.branch?.name;
+        if (!isCheckpoint(event)) {
+            switch (event.type) {
+                case 'thinking_delta':
+                    item.stage = 'thinking';
+                    item.thinking = tail(item.thinking, event.delta);
+                    break;
+                case 'text_delta':
+                    item.stage = 'writing';
+                    item.text = tail(item.text, event.delta);
+                    break;
+                case 'tool_call_detected':
+                    item.stage = `calling ${event.name}`;
+                    break;
+                default:
+                    break;
+            }
+            return;
+        }
+        switch (event.type) {
+            case 'run_created':
+                item.agent = event.agent;
+                item.stage = 'starting';
+                break;
+            case 'before_llm_call':
+                item.agent = event.agent;
+                item.stage = 'waiting on the model';
+                // A new turn's reasoning is not the last turn's.
+                item.thinking = undefined;
+                item.text = undefined;
+                break;
+            case 'after_llm_call':
+                item.turns += 1;
+                item.usage = addUsage(item.usage, event.node.usage);
+                item.models = mergeModelUsage(item.models, [
+                    { model: event.node.model, calls: 1, usage: event.node.usage },
+                ]);
+                break;
+            case 'before_tool_call':
+                item.tools += 1;
+                item.lastTool = event.call.name;
+                item.lastToolFailed = undefined;
+                item.stage = `running ${event.call.name}`;
+                break;
+            case 'after_tool_call':
+                item.lastTool = event.node.name;
+                item.lastToolFailed = event.node.isError;
+                item.stage = 'working';
+                break;
+            case 'handoff':
+                item.agent = event.to;
+                item.stage = `handed to ${event.to}`;
+                break;
+            case 'before_fork':
+                item.stage = `forked into ${event.node.branches.map((b) => b.name).join(', ')}`;
+                break;
+            case 'branch_finished':
+                item.stage = `branch ${event.child.name} ${event.status}`;
+                break;
+            case 'run_finished':
+                if (!event.branch) {
+                    item.stage = 'finishing';
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    /**
+     * One write at a time, and never a stale last write: a tick that lands
+     * mid-write is remembered and repeated afterwards, so the file always ends
+     * up holding the newest render rather than whichever call returned last.
+     */
+    #flush() {
+        if (this.#writing) {
+            this.#again = true;
+            return this.#writing;
+        }
+        this.#writing = (async () => {
+            try {
+                await writeFile(this.file, this.render(), 'utf8');
+            }
+            catch {
+                // A dashboard nobody can write is not a reason to lose a batch.
+            }
+            this.#writing = undefined;
+            if (this.#again) {
+                this.#again = false;
+                await this.#flush();
+            }
+        })();
+        return this.#writing;
+    }
+    /** Exported for the tests: the whole file, from the state in hand. */
+    render() {
+        const now = this.#finishedAt ?? Date.now();
+        const done = this.#items.filter((i) => i.status === 'ok' || i.status === 'failed');
+        const failed = done.filter((i) => i.status === 'failed');
+        const running = this.#items.filter((i) => i.status === 'running');
+        const queued = this.#items.filter((i) => i.status === 'queued');
+        const total = this.#items.reduce((sum, i) => addUsage(sum, i.usage), zeroUsage());
+        const out = [];
+        out.push(`# ${this.#opts.project} — batch`);
+        out.push('');
+        out.push(this.#finishedAt
+            ? `**Finished** ${stampOf(now)} · ${duration(now - this.#startedAt)}`
+            : `**Running** · updated ${stampOf(now)} · ${duration(now - this.#startedAt)} elapsed`);
+        out.push('');
+        out.push(`\`${bar(done.length, this.#items.length)}\` **${done.length}/${this.#items.length}**` +
+            ` · ${done.length - failed.length} ok · ${failed.length} failed` +
+            ` · ${running.length} running · ${queued.length} queued`);
+        out.push('');
+        out.push(...this.#facts(total, done, now));
+        const slots = Math.min(this.#opts.concurrency, running.length + queued.length);
+        if (slots > 0) {
+            out.push('', '## Running now', '');
+            out.push(...panel(running, slots, now));
+        }
+        const models = mergeModelUsage(...this.#items.map((i) => i.models));
+        if (models.length > 0) {
+            // Below the panel on purpose: this table gains a row whenever a new
+            // model is first used, and anything above the panel that grows
+            // moves the panel down between ticks.
+            out.push('', '## Tokens by model', '');
+            out.push(...byModel(models));
+        }
+        if (done.length > 0) {
+            out.push('', '## Finished', '');
+            out.push(...table(done));
+        }
+        if (failed.length > 0) {
+            out.push('', '## What went wrong', '');
+            for (const item of failed) {
+                out.push(`- **${item.id}** — ${oneLine(item.error ?? 'failed')}`);
+            }
+        }
+        if (queued.length > 0) {
+            out.push('', '## Waiting', '');
+            out.push(queued.map((i) => `\`${i.id}\``).join(' · '));
+        }
+        out.push('', '---', '');
+        out.push(this.#finishedAt
+            ? `Every answer is in \`batch.json\`, and each item's own \`output.json\`.`
+            : `This file is rewritten every second while the batch runs.`);
+        out.push('');
+        return out.join('\n');
+    }
+    #facts(total, done, now) {
+        const spent = done
+            .map((i) => (i.finishedAt ?? now) - (i.startedAt ?? now))
+            .reduce((a, b) => a + b, 0);
+        const rows = [
+            ['Batch', `\`${this.#opts.dir}\``],
+            ['Project', `\`${this.#opts.projectDir}\``],
+            ['Input', `\`${this.#opts.input}\``],
+            ['Memory', this.#opts.memory],
+            ['Concurrency', `${this.#opts.concurrency} at a time`],
+            ['Tokens', tokens(total)],
+            // Always present, even before the first item lands: a row that
+            // appears later pushes everything below it down a line.
+            ['Average run', done.length === 0 ? '—' : duration(Math.round(spent / done.length))],
+        ];
+        return [
+            '| | |',
+            '| :-- | :-- |',
+            ...rows.map(([name, value]) => `| **${name}** | ${value} |`),
+        ];
+    }
+}
+// ---------------------------------------------------------------------------
+// Drawing
+// ---------------------------------------------------------------------------
+/**
+ * The live part of the dashboard, and the only part that is redrawn rather
+ * than appended to — so it is drawn at a **fixed height**. A preformatted
+ * block never wraps, every item gets the same four lines whether or not it has
+ * anything to say, and a free slot is drawn as a free slot rather than left
+ * out. What is being read therefore stays where it was a second ago.
+ */
+function panel(running, slots, now) {
+    const out = ['```text'];
+    for (let slot = 0; slot < slots; slot += 1) {
+        if (slot > 0) {
+            out.push('');
+        }
+        const item = running[slot];
+        out.push(...(item ? lines(item, now) : IDLE));
+    }
+    out.push('```');
+    return out;
+}
+const IDLE = ['· idle', '  waiting for a free slot', '  —', '  ↳ —'];
+function lines(item, now) {
+    const words = item.text ?? item.thinking;
+    const doing = words
+        ? oneLine(words)
+        : item.lastTool
+            ? `${item.lastTool}${item.lastToolFailed === true ? ' (failed)' : ''}`
+            : '—';
+    return [
+        `▶ #${item.index} ${item.id}`,
+        `  ${oneLine(item.question)}`,
+        `  ${[
+            item.agent,
+            item.branch ? `${item.stage} ⑂ ${item.branch}` : item.stage,
+            `${duration(now - (item.startedAt ?? now))} in`,
+            `turn ${item.turns + 1}`,
+            `${item.tools} ${item.tools === 1 ? 'tool' : 'tools'}`,
+            tokens(item.usage),
+        ]
+            .filter(Boolean)
+            .join(' · ')}`,
+        `  ↳ ${doing}`,
+    ].map((line) => clip(line, PANEL_WIDTH));
+}
+/**
+ * Which model spent what. A batch can route agents — and forks — to different
+ * models, so one total belongs to none of them; these rows add back up to the
+ * `Tokens` fact above.
+ */
+function byModel(models) {
+    return [
+        '| model | calls | in | cached | out | thinking |',
+        '| :-- | --: | --: | --: | --: | --: |',
+        ...models.map((m) => `| ${[
+            `\`${m.model}\``,
+            String(m.calls),
+            format(m.usage.inputTokens),
+            format(m.usage.cachedInputTokens),
+            format(m.usage.outputTokens),
+            format(m.usage.reasoningTokens),
+        ].join(' | ')} |`),
+    ];
+}
+function table(done) {
+    const rows = [...done].sort((a, b) => a.index - b.index);
+    return [
+        '| # | item | status | took | turns | tools | tokens | question |',
+        '| --: | :-- | :-- | --: | --: | --: | :-- | :-- |',
+        ...rows.map((i) => `| ${[
+            String(i.index),
+            `\`${i.id}\``,
+            i.status === 'ok' ? '✓ ok' : '✗ failed',
+            duration((i.finishedAt ?? 0) - (i.startedAt ?? i.finishedAt ?? 0)),
+            String(i.turns),
+            String(i.tools),
+            tokens(i.usage),
+            clip(oneLine(i.question), 60),
+        ].join(' | ')} |`),
+    ];
+}
+function bar(done, total) {
+    const filled = total === 0 ? 0 : Math.round((done / total) * BAR_WIDTH);
+    return '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+}
+function tokens(usage) {
+    if (usage.inputTokens === 0 && usage.outputTokens === 0) {
+        return '—';
+    }
+    const thinking = usage.reasoningTokens ? ` (${format(usage.reasoningTokens)} thinking)` : '';
+    return `${format(usage.inputTokens)} in · ${format(usage.outputTokens)} out${thinking}`;
+}
+/** The question, as one line of a table cell rather than a document. */
+function question(input) {
+    if (typeof input === 'string') {
+        return input;
+    }
+    return input.map(part).join(' ');
+}
+/** Media is named, not repeated: the whole point is one readable line. */
+function part(one) {
+    if (typeof one === 'string') {
+        return one;
+    }
+    if ('text' in one) {
+        return one.text;
+    }
+    for (const kind of ['image', 'audio', 'video', 'file']) {
+        if (kind in one) {
+            return `[${kind}]`;
+        }
+    }
+    return '[media]';
+}
+/** Markdown tables and blockquotes are line-oriented; the text is not. */
+function oneLine(text) {
+    return clip(text.replace(/\s+/g, ' ').trim().replace(/\|/g, '\\|'), 400);
+}
+function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function tail(had, delta) {
+    const next = (had ?? '') + delta;
+    return next.length > TAIL ? `…${next.slice(next.length - TAIL)}` : next;
+}
+function stampOf(ms) {
+    return new Date(ms).toTimeString().slice(0, 8);
+}
+//# sourceMappingURL=progress.js.map

package/dist/request.d.ts

@@ -0,0 +1,45 @@
+import { type Input } from '@zenera/neo';
+export interface RunRequest {
+    /** a registered name, or a directory — paths resolved against the file */
+    project?: string;
+    input: Input;
+    /** absolute */
+    workspace?: string;
+    /** absolute */
+    memory?: string;
+}
+export interface BatchItem {
+    /** names this item's directory under the batch dir; defaults to its index */
+    id: string;
+    index: number;
+    input: Input;
+    /** absolute; without one the item gets a directory of its own */
+    workspace?: string;
+}
+export interface BatchRequest {
+    items: BatchItem[];
+}
+/**
+ * `-` is stdin, and then there is no file to resolve paths against, so the cwd
+ * answers instead — the only place a piped request could have meant.
+ */
+export declare function readRequest(file: string, cwd: string, piped?: string): Promise<RunRequest>;
+/**
+ * `base` is the directory every relative path in the request is resolved
+ * against — the file's own, so a case travels with the images beside it.
+ */
+export declare function parseRequest(body: string, base: string, where: string): RunRequest;
+/** The batch file. `-` is stdin, and then the cwd is what paths mean. */
+export declare function readBatch(file: string, cwd: string, piped?: string): Promise<BatchRequest>;
+/**
+ * Everything refusable is refused here, before a single model is called: a
+ * batch that fails on item 80 has already spent seventy-nine runs finding out
+ * something its file could have been read for.
+ */
+export declare function parseBatch(body: string, base: string, where: string): BatchRequest;
+/**
+ * Canonical `ContentPart[]` out, whatever went in: the shorthands exist for
+ * whoever writes the file, and stop existing the moment it is read.
+ */
+export declare function toInput(raw: unknown, base: string, where: string): Input;
+//# sourceMappingURL=request.d.ts.map