@zenera/cli 1.1.22 → 1.1.24

package/dist/request.js

@@ -0,0 +1,300 @@
+import { media, text } from '@zenera/neo';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, extname, isAbsolute, resolve } from 'node:path';
+import { readStdin, usageError, warn } from "./term.js";
+/**
+ * Local media is read and inlined, so the state a run is resumed from carries
+ * the picture rather than a path that meant something on another machine. That
+ * also puts the bytes in `state.json`, rewritten at every checkpoint of every
+ * later turn — hence a ceiling, and a word of warning well before it.
+ */
+const MAX_MEDIA_BYTES = 20 * 1024 * 1024;
+const WARN_MEDIA_BYTES = 2 * 1024 * 1024;
+/** Enough to name what people actually attach; anything else says `mimeType`. */
+const MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.svg': 'image/svg+xml',
+    '.heic': 'image/heic',
+    '.avif': 'image/avif',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.m4a': 'audio/mp4',
+    '.flac': 'audio/flac',
+    '.aac': 'audio/aac',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.mkv': 'video/x-matroska',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.html': 'text/html',
+    '.yaml': 'application/yaml',
+    '.yml': 'application/yaml',
+};
+const MEDIA_KEYS = ['image', 'audio', 'video', 'file'];
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+/**
+ * `-` 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 async function readRequest(file, cwd, piped) {
+    if (file === '-') {
+        const body = piped ?? (await readStdin());
+        if (body === undefined) {
+            throw usageError('--input - expects the request on stdin', 'pipe a JSON object in');
+        }
+        return parseRequest(body, cwd, '<stdin>');
+    }
+    const at = resolve(cwd, file);
+    let body;
+    try {
+        body = readFileSync(at, 'utf8');
+    }
+    catch {
+        throw usageError(`cannot read ${at}`);
+    }
+    return parseRequest(body, dirname(at), at);
+}
+/**
+ * `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 function parseRequest(body, base, where) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch (err) {
+        throw usageError(`${where}: ${err.message}`, 'the request must be JSON');
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw usageError(`${where}: expected a JSON object`, 'see: zen run --help');
+    }
+    if (raw.input === undefined) {
+        throw usageError(`${where}: no "input"`, 'a request has to say what to ask');
+    }
+    return {
+        project: project(raw.project, base, where),
+        input: toInput(raw.input, base, where),
+        workspace: path(raw.workspace, base, where, 'workspace'),
+        memory: path(raw.memory, base, where, 'memory'),
+    };
+}
+/** The batch file. `-` is stdin, and then the cwd is what paths mean. */
+export async function readBatch(file, cwd, piped) {
+    if (file === '-') {
+        const body = piped ?? (await readStdin());
+        if (body === undefined) {
+            throw usageError('--input - expects the batch on stdin', 'pipe a JSON object in');
+        }
+        return parseBatch(body, cwd, '<stdin>');
+    }
+    const at = resolve(cwd, file);
+    let body;
+    try {
+        body = readFileSync(at, 'utf8');
+    }
+    catch {
+        throw usageError(`cannot read ${at}`);
+    }
+    return parseBatch(body, dirname(at), at);
+}
+/**
+ * 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 function parseBatch(body, base, where) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch (err) {
+        throw usageError(`${where}: ${err.message}`, 'the batch must be JSON');
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw usageError(`${where}: expected a JSON object`, 'see: zen run batch --help');
+    }
+    for (const key of ['memory', 'workspace', 'project']) {
+        if (raw[key] !== undefined) {
+            throw usageError(`${where}: "${key}" is not part of a batch file`, `it applies to every item, so it is a flag: --${key}`);
+        }
+    }
+    if (!Array.isArray(raw.batch)) {
+        throw usageError(`${where}: no "batch" array`, 'a batch is a list of requests');
+    }
+    if (raw.batch.length === 0) {
+        throw usageError(`${where}: "batch" is empty`, 'there is nothing to run');
+    }
+    const items = raw.batch.map((item, index) => toItem(item, index, base, `${where}: batch`));
+    unique(items.map((i) => i.id), 'id', where);
+    unique(items.flatMap((i) => (i.workspace ? [i.workspace] : [])), 'workspace', where);
+    return { items };
+}
+function toItem(raw, index, base, where) {
+    const at = `${where}[${index}]`;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw usageError(`${at}: expected an object`, 'see: zen run batch --help');
+    }
+    const obj = raw;
+    for (const key of ['memory', 'project']) {
+        if (obj[key] !== undefined) {
+            throw usageError(`${at}: "${key}" is not part of a batch item`, `every item shares one, so it is a flag: --${key}`);
+        }
+    }
+    if (obj.input === undefined) {
+        throw usageError(`${at}: no "input"`, 'an item has to say what to ask');
+    }
+    return {
+        id: id(obj.id, index, at),
+        index,
+        input: toInput(obj.input, base, at),
+        workspace: path(obj.workspace, base, at, 'workspace'),
+    };
+}
+/** An id names a directory, so it has to be one path segment and nothing else. */
+function id(value, index, at) {
+    if (value === undefined) {
+        return String(index);
+    }
+    if (typeof value !== 'string' || !value) {
+        throw usageError(`${at}: "id" must be a non-empty string`);
+    }
+    if (!/^[\w.-]+$/.test(value) || value === '.' || value === '..') {
+        throw usageError(`${at}: "${value}" cannot be an id`, 'it names a directory: letters, digits, dot, dash and underscore');
+    }
+    return value;
+}
+function unique(values, what, where) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            throw usageError(`${where}: two items share the ${what} "${value}"`, 'every item runs at the same time as the others; give each its own');
+        }
+        seen.add(value);
+    }
+}
+/**
+ * A registered name is not a path and must not be resolved into one; a name
+ * that looks like a path is one. `Projects.open` takes either.
+ */
+function project(value, base, where) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || !value) {
+        throw usageError(`${where}: "project" must be a name or a directory`);
+    }
+    return value.startsWith('.') || isAbsolute(value) ? resolve(base, value) : value;
+}
+function path(value, base, where, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || !value) {
+        throw usageError(`${where}: "${field}" must be a directory`);
+    }
+    return resolve(base, value);
+}
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+/**
+ * Canonical `ContentPart[]` out, whatever went in: the shorthands exist for
+ * whoever writes the file, and stop existing the moment it is read.
+ */
+export function toInput(raw, base, where) {
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (!Array.isArray(raw)) {
+        throw usageError(`${where}: "input" must be a string or an array of parts`);
+    }
+    return raw.map((part, i) => toPart(part, base, `${where}: input[${i}]`));
+}
+function toPart(part, base, at) {
+    if (typeof part === 'string') {
+        return text(part);
+    }
+    if (part === null || typeof part !== 'object' || Array.isArray(part)) {
+        throw usageError(`${at}: expected a string or an object`);
+    }
+    const obj = part;
+    const mimeType = mime(obj.mimeType, at);
+    if (typeof obj.type === 'string') {
+        if (obj.type === 'text') {
+            return text(str(obj.text, at, 'text'));
+        }
+        if (MEDIA_KEYS.includes(obj.type)) {
+            const kind = obj.type;
+            return url(kind, str(obj.url, at, 'url'), mimeType, base, at);
+        }
+        throw usageError(`${at}: unknown part type "${obj.type}"`, `text, ${MEDIA_KEYS.join(', ')}`);
+    }
+    if (typeof obj.text === 'string') {
+        return text(obj.text);
+    }
+    for (const kind of MEDIA_KEYS) {
+        if (obj[kind] !== undefined) {
+            return url(kind, str(obj[kind], at, kind), mimeType, base, at);
+        }
+    }
+    throw usageError(`${at}: no text, ${MEDIA_KEYS.join(', ')} or type`, 'see: zen run --help');
+}
+/**
+ * A url the model can already fetch is left exactly as it is; anything else is
+ * a path on this machine, and a path is only a url once it carries its bytes.
+ */
+function url(kind, value, mimeType, base, at) {
+    if (/^(https?|data):/.test(value)) {
+        return media(kind, value, mimeType);
+    }
+    const file = resolve(base, value);
+    const type = mimeType ?? MIME[extname(file).toLowerCase()];
+    if (!type) {
+        throw usageError(`${at}: nothing known about "${extname(file) || value}"`, 'name the type with "mimeType"');
+    }
+    let size;
+    try {
+        size = statSync(file).size;
+    }
+    catch {
+        throw usageError(`${at}: cannot read ${file}`);
+    }
+    if (size > MAX_MEDIA_BYTES) {
+        throw usageError(`${at}: ${file} is ${Math.round(size / 1024 / 1024)} MB`, `inlined media lives in the run state — the limit is ${MAX_MEDIA_BYTES / 1024 / 1024} MB`);
+    }
+    if (size > WARN_MEDIA_BYTES) {
+        warn(`${file} is large; it is written into the session state on every later turn`);
+    }
+    const bytes = readFileSync(file);
+    return media(kind, `data:${type};base64,${bytes.toString('base64')}`, type);
+}
+function str(value, at, field) {
+    if (typeof value !== 'string' || !value) {
+        throw usageError(`${at}: "${field}" must be a non-empty string`);
+    }
+    return value;
+}
+function mime(value, at) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || !value) {
+        throw usageError(`${at}: "mimeType" must be a string`);
+    }
+    return value;
+}
+//# sourceMappingURL=request.js.map

package/dist/sandbox.js

@@ -178,6 +178,12 @@ function toSpec(config, extra, secrets) {
 export function usesSandbox(project) {
     return project.agents.some((a) => a.tools.some((t) => t.group === SANDBOX_GROUP));
 }
+/**
+ * Images this process has already settled. A batch opens the same project
+ * dozens of times at once, and without this each one shells out to podman and
+ * the concurrent copies race each other to pull the very same image.
+ */
+const READY = new Set();
 /**
  * Asked before the first turn rather than at the first tool call, so a missing
  * container engine costs nothing instead of costing a round trip and half a
@@ -185,6 +191,9 @@ export function usesSandbox(project) {
  */
 export async function preflight(setup, yes) {
     mkdirSync(setup.home, { recursive: true });
+    if (READY.has(setup.image)) {
+        return;
+    }
     await ensurePodmanReady({
         image: setup.image,
         build: setup.build,
@@ -192,6 +201,7 @@ export async function preflight(setup, yes) {
         memory: setup.spec.memory,
         yes,
     });
+    READY.add(setup.image);
 }
 /** Best-effort teardown: losing a container must never lose a run. */
 export async function teardown(pool) {

package/dist/scaffold.d.ts

@@ -11,6 +11,14 @@
  * own beside them.
  */
 export declare const SHARED_RULES: readonly string[];
+/**
+ * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
+ * The publishable packages move in lockstep, so one number covers them all.
+ *
+ * Exported so the check that reports a drifted pin reads the same number the
+ * scaffold wrote, rather than a second definition of "this version".
+ */
+export declare function ownVersion(): string;
 /**
  * Writes the editor's files under `dir`, replacing what is there. They are
  * ours: they say how the editor is to treat a directory the agents write into,

package/dist/scaffold.js

@@ -59,8 +59,11 @@ const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', '
 /**
  * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
  * The publishable packages move in lockstep, so one number covers them all.
+ *
+ * Exported so the check that reports a drifted pin reads the same number the
+ * scaffold wrote, rather than a second definition of "this version".
  */
-function ownVersion() {
+export function ownVersion() {
     const manifest = fileURLToPath(new URL('../package.json', import.meta.url));
     return JSON.parse(readFileSync(manifest, 'utf8')).version;
 }

package/dist/session.d.ts

@@ -6,7 +6,6 @@ export interface SessionPaths {
     data: string;
     /** the live, resumable state — rewritten after every run */
     state: string;
-    memory: string;
     blobs: string;
     runs: string;
     lock: string;
@@ -52,10 +51,30 @@ export interface RunPaths {
     output: string;
     state: string;
     report: string;
+    /** the same run as one Mermaid flowchart, for a model to read */
+    graph: string;
     meta: string;
 }
 export declare function runPaths(session: SessionPaths, id: string): RunPaths;
 export declare function createRun(session: SessionPaths): RunPaths;
+/**
+ * The same paths, reached from a directory instead of from a pair of ids.
+ *
+ * `zen run --json` hands back a run directory, and a caller holding one has no
+ * reason to take it apart again to ask a second question about the same run.
+ * The layout is fixed, so the ids can be read back out of the path — and both
+ * still go through `isStamp`, so a path from anywhere cannot name a directory
+ * this layout would never have produced.
+ *
+ * The session comes back too, not only the run: blobs are stored per session,
+ * so anything that resolves a payload needs both halves — and the project, so
+ * a command reached this way can still read the project's config.
+ */
+export declare function runPathsAt(dir: string): {
+    project: string;
+    session: SessionPaths;
+    run: RunPaths;
+};
 export interface RunMeta {
     version: 1;
     id: string;
@@ -68,9 +87,15 @@ export interface RunMeta {
     turns: number;
     usage: unknown;
     workspace: string;
+    memory?: string;
     error?: string;
 }
 export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;
+/**
+ * Partial, because a run killed before it recorded anything still has a
+ * directory, and every field here is worth having on its own.
+ */
+export declare function readRunMeta(p: RunPaths): Promise<Partial<RunMeta>>;
 export interface RunSummary {
     id: string;
     startedAt?: string;

package/dist/session.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
-import { join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
 import { isStamp, stamp, stampInstant } from "./ids.js";
 import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
@@ -17,7 +17,6 @@ export function sessionPaths(projectDir, id) {
         workspace: join(dir, 'workspace'),
         data,
         state: join(data, 'state.json'),
-        memory: join(data, 'memory'),
         blobs: join(data, 'blobs'),
         runs: join(dir, 'runs'),
         lock: join(dir, '.lock'),
@@ -134,6 +133,7 @@ export function runPaths(session, id) {
         output: join(dir, 'output.md'),
         state: join(dir, 'state.json'),
         report: join(dir, 'report.html'),
+        graph: join(dir, 'graph.mmd'),
         meta: join(dir, 'meta.json'),
     };
 }
@@ -142,16 +142,55 @@ export function createRun(session) {
     mkdirSync(p.dir, { recursive: true });
     return p;
 }
+/**
+ * The same paths, reached from a directory instead of from a pair of ids.
+ *
+ * `zen run --json` hands back a run directory, and a caller holding one has no
+ * reason to take it apart again to ask a second question about the same run.
+ * The layout is fixed, so the ids can be read back out of the path — and both
+ * still go through `isStamp`, so a path from anywhere cannot name a directory
+ * this layout would never have produced.
+ *
+ * The session comes back too, not only the run: blobs are stored per session,
+ * so anything that resolves a payload needs both halves — and the project, so
+ * a command reached this way can still read the project's config.
+ */
+export function runPathsAt(dir) {
+    const full = resolve(dir);
+    const runId = basename(full);
+    const sessionDir = dirname(dirname(full));
+    const wrong = () => usageError(`${display(full)} is not a run directory`, 'runs live at <project>/sessions/<session>/runs/<run>');
+    if (!isStamp(runId) || !isStamp(basename(sessionDir)) || basename(dirname(full)) !== 'runs') {
+        throw wrong();
+    }
+    const project = dirname(dirname(sessionDir));
+    const session = sessionPaths(project, basename(sessionDir));
+    const run = runPaths(session, runId);
+    if (resolve(run.dir) !== full) {
+        throw wrong();
+    }
+    if (!existsSync(run.state)) {
+        throw invalidError(`run ${runId} has no state.json`, 'only a run that got far enough to save state can be inspected');
+    }
+    return { project, session, run };
+}
 export function writeRunMeta(p, meta) {
     writeJson(p.meta, meta, 0o644);
 }
+/**
+ * Partial, because a run killed before it recorded anything still has a
+ * directory, and every field here is worth having on its own.
+ */
+export async function readRunMeta(p) {
+    return await readJson(p.meta, {});
+}
 /** Newest first — the order a picker wants. */
 export async function listRuns(session) {
     const out = [];
     for (const id of runIds(session.dir).reverse()) {
         // A run killed before it recorded anything still has an id, and the id
         // says when it started, so it is listable without its meta.
-        const meta = await readJson(runPaths(session, id).meta, {});
+        const meta = await readRunMeta(runPaths(session, id));
         out.push({
             id,
             startedAt: meta.startedAt ?? stampInstant(id),

package/dist/term.d.ts

@@ -56,6 +56,8 @@ export declare function write(line?: string): void;
 export declare function writeAll(lines: readonly string[]): void;
 /** Machine-readable output. Pretty-printed: it is read by people too. */
 export declare function json(value: unknown): void;
+/** The same bytes, for a caller sending them somewhere other than stdout. */
+export declare function jsonText(value: unknown): string;
 export declare function note(line?: string): void;
 /**
  * One line of narration that rewrites itself while work is in flight, so a
@@ -72,6 +74,7 @@ export declare function warn(message: string): void;
 export declare function title(text: string): void;
 export declare function fail(message: string, hint?: string): void;
 export declare function isInteractive(): boolean;
+export declare function deferBanner(print: () => void): void;
 export declare function ask(question: string, fallback?: string): Promise<string>;
 /**
  * Reads without echoing. `readline` writes what you type through its `output`

package/dist/term.js

@@ -154,7 +154,11 @@ export function writeAll(lines) {
 }
 /** Machine-readable output. Pretty-printed: it is read by people too. */
 export function json(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    process.stdout.write(jsonText(value));
+}
+/** The same bytes, for a caller sending them somewhere other than stdout. */
+export function jsonText(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
 }
 export function note(line = '') {
     process.stderr.write(`${line}\n`);
@@ -229,10 +233,22 @@ export function fail(message, hint) {
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY);
 }
+// A banner is for whoever is sitting there, and the only proof that anyone is
+// sitting there is that we are about to ask them something. Commands whose
+// stdout is the answer hand theirs over here instead of printing it, and it
+// appears if — and only if — the run turns out to need a person. Held as a
+// thunk so this module stays below the banner, which is drawn with its colours.
+let pending;
+export function deferBanner(print) {
+    pending = print;
+}
 function requireTty(what, flag) {
     if (!isInteractive()) {
         throw usageError(`cannot ask for ${what} without a terminal`, `pass ${flag} instead`);
     }
+    const banner = pending;
+    pending = undefined;
+    banner?.();
 }
 export async function ask(question, fallback) {
     requireTty(question, '--yes or the matching flag');

package/dist/trace.d.ts

@@ -0,0 +1,84 @@
+import { type AgentState, type PayloadResolver, type TrajectoryNode } from '@zenera/neo';
+export interface TraceEntry {
+    /** diagram id — `n1`, `n2`, …, in the order the run appended nodes */
+    key: string;
+    node: TrajectoryNode;
+    depth: number;
+    /** the branch this ran in, or null on the trunk */
+    branch: string | null;
+    /** hidden from the model's context by a later compaction */
+    covered: boolean;
+    /** the id of the compaction that hid it, when it is on the same level */
+    coveredBy?: string;
+    children: TraceBranch[];
+    turnStart: number | null;
+    startMs: number | null;
+    endMs: number | null;
+}
+export interface TraceBranch {
+    name: string;
+    agent: string;
+    status: string;
+    entries: TraceEntry[];
+    startMs: number | null;
+    endMs: number | null;
+    turnStart: number | null;
+    /** the one branch the join actually waited for */
+    slowest: boolean;
+}
+export interface Trace {
+    root: TraceEntry[];
+    /** every entry, branches included, in key order */
+    entries: TraceEntry[];
+    byKey: Map<string, TraceEntry>;
+}
+export declare function traceOf(state: AgentState): Trace;
+export declare function safe(text: string, max?: number): string;
+export interface TraceOptions {
+    /** the run id to name in the header, when it differs from `state.runId` */
+    runId?: string;
+    /** the run directory, so the header can spell the command that opens a node */
+    dir?: string;
+    /** the files the run worked on */
+    workspace?: string;
+    /** the memory graph the run read, when it had one */
+    memory?: string;
+    timing?: boolean;
+    usage?: boolean;
+    /** false drops the palette: a model reads the labels, not the colours */
+    style?: boolean;
+}
+export declare function traceMermaid(state: AgentState, opts?: TraceOptions): string;
+/** The node list on its own, for `--json`. */
+export declare function traceIndex(trace: Trace): {
+    id: string;
+    nodeId: string;
+    kind: string;
+    agent: string;
+    branch: string | null;
+    ts: string;
+    label: string;
+}[];
+export interface NodePart {
+    name: string;
+    text: string;
+}
+export interface NodeDetail {
+    id: string;
+    nodeId: string;
+    kind: string;
+    agent: string;
+    branch: string | null;
+    ts: string;
+    label: string;
+    parts: NodePart[];
+    /** fields worth reading that are not payloads */
+    facts: Record<string, string>;
+}
+/**
+ * `n5`, or `n5..n9`. A range is how a reader asks about a stretch, which is
+ * the shape of the question the diagram provokes ("what are n14 to n38 doing").
+ */
+export declare function parseNodeIds(words: readonly string[], known: Map<string, unknown>): string[];
+export declare function nodeDetail(trace: Trace, ids: readonly string[], payloads: PayloadResolver): Promise<NodeDetail[]>;
+//# sourceMappingURL=trace.d.ts.map