@zenera/cli 1.1.23 → 1.1.25

package/dist/batch.js

@@ -0,0 +1,413 @@
+import { addUsage, lockHolder, MANIFEST_FILE as MEMORY_MANIFEST, memoryDir, MemoryStore, mergeModelUsage, readProjectConfig, SANDBOX_GROUP, selectTools, usageByModel, zeroUsage, } from '@zenera/neo';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import * as Engine from "./engine.js";
+import { stamp } from "./ids.js";
+import { duration } from "./narrate.js";
+import { BatchProgress } from "./progress.js";
+import { assertLocks } from "./podman.js";
+import { project as resolveProject, target } from "./resolve.js";
+import { display } from "./session.js";
+import { CliError, count, cyan, dim, EXIT, invalidError, json, jsonText, note, usageError, write, } from "./term.js";
+import { appendUsage } from "./usage.js";
+import { availableTools } from "./validate.js";
+/** Past this, the limit is the provider's rate limit and the failures are 429s. */
+const MAX_CONCURRENCY = 32;
+export async function runBatch(opts) {
+    const project = await resolveProject({ cwd: opts.cwd, project: opts.project });
+    const items = opts.request.items;
+    // Every item at once holds its own containers, so a short engine fails
+    // here once instead of once per item.
+    const boxes = containersPerItem(project.dir);
+    if (boxes > 0) {
+        await assertLocks(boxes * Math.min(opts.concurrency, items.length));
+    }
+    const dir = opts.dir ? resolve(opts.cwd, opts.dir) : join(project.dir, 'batches', stamp());
+    // Two batches in one directory would interleave their item folders and the
+    // second would overwrite the first's index while the first still points at
+    // it. Cheaper to refuse than to explain.
+    if (existsSync(join(dir, 'batch.json'))) {
+        throw invalidError(`${dir} already holds a batch`, 'name an empty directory with --batch-dir, or leave it out for a fresh one');
+    }
+    await mkdir(dir, { recursive: true });
+    const source = memorySource(project.dir, opts.memory);
+    const mode = source ? (opts.memoryReadOnly ? 'read-only' : 'copied') : 'none';
+    // A project declares its memory directory; it is the first run that makes
+    // one. So a batch may legitimately be pointed at a graph that is not there
+    // yet - which is the whole of warming a cold project.
+    const seeded = source !== undefined && existsSync(source);
+    if (opts.memoryReadOnly && !source) {
+        throw usageError('--memory-read-only, but this project has no memory', 'give one with --memory, or drop the flag');
+    }
+    if (source && seeded) {
+        // A graph is three files that only mean anything together. Reading one
+        // mid-commit is a wrong answer and copying one is a wrong archive, so
+        // both modes wait rather than race.
+        const held = lockHolder(source);
+        if (held) {
+            throw invalidError(`that memory is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or point --memory at another directory');
+        }
+    }
+    // Serially, and before anything runs: sixteen recursive copies of the same
+    // tree at once is the one moment a batch is disk-bound, and it would be
+    // spent racing itself.
+    const prepared = await prepareMemories(items, { dir, mode, source, seeded });
+    // Opened once, here, so a path that is not a memory is one error rather
+    // than one per item — and so the read-only refusal lands before any cost.
+    if (mode === 'read-only' && source) {
+        await MemoryStore.open(source, { readOnly: true });
+    }
+    // Ctrl-C asks every run to stop rather than killing the process: each one
+    // still lands its turn, and each finished item keeps the answer it already
+    // wrote.
+    const stopping = new AbortController();
+    const onInterrupt = () => stopping.abort();
+    process.once('SIGINT', onInterrupt);
+    if (!opts.json) {
+        note(`${cyan(project.name)} ${dim(`${count(items.length, 'item')}, ${opts.concurrency} at a time`)}`);
+        note(dim(`memory: ${source ? `${mode}${seeded ? '' : ' (new)'}, ${display(source, opts.cwd)}` : 'none'}`));
+        note(dim(`batch:  ${display(dir, opts.cwd)}`));
+        note(dim(`watch:  ${display(join(dir, 'README.md'), opts.cwd)}`));
+        note('');
+    }
+    // The dashboard, from here until the last item lands.
+    const progress = new BatchProgress({
+        dir,
+        project: project.name,
+        projectDir: project.dir,
+        input: opts.input,
+        concurrency: opts.concurrency,
+        memory: source ? `${mode}${seeded ? '' : ' (new)'} — \`${source}\`` : 'none',
+        items,
+    });
+    progress.begin();
+    const startedAt = new Date();
+    let done = 0;
+    // What each item spent, per model. Collected here rather than read back
+    // out of the dashboard, which is deliberately not load-bearing.
+    const spent = [];
+    const results = await pool(items, opts.concurrency, async (item) => {
+        const result = await runItem(item, {
+            opts,
+            projectDir: project.dir,
+            dir,
+            memory: prepared.get(item.id),
+            memoryReadOnly: mode === 'read-only',
+            signal: stopping.signal,
+            progress,
+            spent,
+        });
+        done += 1;
+        if (!opts.json) {
+            note(`${dim(`[${done}/${items.length}]`)} ` +
+                `${result.ok ? cyan('ok') : 'failed'} ${item.id}` +
+                `${result.error ? dim(` — ${result.error.message}`) : ''}`);
+        }
+        return result;
+    });
+    process.off('SIGINT', onInterrupt);
+    await progress.close();
+    // An item that was given an empty graph and found nothing worth keeping
+    // leaves a directory that is not a memory, and `merge` rightly refuses
+    // one. Nothing was learned there, so there is nothing to leave behind.
+    const written = mode === 'copied' ? await keepWritten(prepared) : 0;
+    const finishedAt = new Date();
+    const failed = results.filter((r) => !r.ok).length;
+    const models = mergeModelUsage(...spent);
+    const body = {
+        batch: {
+            dir,
+            readme: join(dir, 'README.md'),
+            input: opts.input,
+            project: project.dir,
+            items: items.length,
+            ok: results.length - failed,
+            failed,
+            concurrency: opts.concurrency,
+            memory: { source: source ?? null, mode },
+            usage: models.reduce((sum, m) => addUsage(sum, m.usage), zeroUsage()),
+            models,
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+        },
+        batch_results: results,
+    };
+    const text = jsonText(body);
+    await writeFile(join(dir, 'batch.json'), text, 'utf8');
+    appendUsage(project.dir, {
+        kind: 'batch',
+        ts: finishedAt.toISOString(),
+        batchDir: dir,
+        input: opts.input,
+        items: items.length,
+        ok: results.length - failed,
+        failed,
+        concurrency: opts.concurrency,
+        memory: mode,
+        startedAt: startedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        models,
+    });
+    if (opts.out) {
+        await writeFile(resolve(opts.cwd, opts.out), text, 'utf8');
+    }
+    if (opts.json) {
+        json(body);
+    }
+    else {
+        note('');
+        note(`${count(results.length - failed, 'run')} ok, ${failed} failed  ` +
+            dim(duration(finishedAt.getTime() - startedAt.getTime())));
+        if (mode === 'copied' && written > 0) {
+            note(dim(`fold what they learned back in: zen memory merge ${dir}/*/memory`));
+        }
+        // The batch directory is the answer, and it is the whole answer: every
+        // path in the index is under it.
+        write(dir);
+    }
+    // After everything is written. A batch that ends in a non-zero exit still
+    // has to leave behind the answers it did get.
+    if (failed > 0) {
+        throw new CliError(`${count(failed, 'item')} failed`, EXIT.failed, `what each one said: ${join(dir, 'batch.json')}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// One item
+// ---------------------------------------------------------------------------
+/**
+ * The most containers one item can start: one shared by the agents on the
+ * project's sandbox block, one more for each agent with a block of its own.
+ * A project that does not load is each item's to report, so it counts none.
+ */
+export function containersPerItem(dir) {
+    let read;
+    try {
+        read = readProjectConfig(dir);
+    }
+    catch {
+        return 0;
+    }
+    const tools = availableTools(read.root, read.config);
+    const shells = read.config.agents.filter((a) => {
+        try {
+            return selectTools(tools, [...(a.tools ?? [])], { where: a.name }).some((t) => t.group === SANDBOX_GROUP);
+        }
+        catch {
+            return false;
+        }
+    });
+    const own = shells.filter((a) => a.sandbox).length;
+    return own + (shells.length > own ? 1 : 0);
+}
+/**
+ * A failure is data. One item that asks something the model cannot answer must
+ * not cost the other ninety-nine their answers, so everything is caught and
+ * written down, and the exit code is decided once at the end.
+ */
+async function runItem(item, ctx) {
+    const at = join(ctx.dir, item.id);
+    const output = join(at, 'output.json');
+    const watch = ctx.progress.watch(item.id);
+    try {
+        const where = await target({
+            cwd: ctx.opts.cwd,
+            project: ctx.projectDir,
+            // Every item is its own conversation. There is no session to
+            // resume and nobody to ask which one.
+            fresh: true,
+            workspace: item.workspace ?? join(at, 'workspace'),
+            yes: true,
+        });
+        const engine = await Engine.open({
+            project: where.project,
+            session: where.session,
+            readOnly: ctx.opts.readOnly,
+            model: ctx.opts.model,
+            image: ctx.opts.image,
+            memoryDir: ctx.memory,
+            memoryReadOnly: ctx.memoryReadOnly,
+            keys: ctx.opts.keys,
+            yes: true,
+            // The project's own problems are the batch's, not each item's.
+            quiet: true,
+            // A fresh session nobody resumes: a stopped container per item
+            // is how a few fine-tuning rounds used up every engine lock.
+            disposable: true,
+        });
+        try {
+            // Nothing is narrated to the terminal — a hundred interleaved
+            // streams there is not progress, it is noise. The events go to the
+            // dashboard instead, where each item has a line of its own.
+            const outcome = await Engine.run(engine, item.input, watch, ctx.signal);
+            // Written the moment it is known, not at the end — a batch killed
+            // halfway still has every answer it managed to get.
+            await writeFile(output, jsonText(Engine.envelope(engine, outcome)), 'utf8');
+            const models = usageByModel(outcome.result.state.trajectory);
+            ctx.spent.push(models);
+            appendUsage(ctx.projectDir, {
+                kind: 'run',
+                ts: new Date().toISOString(),
+                runDir: outcome.run.dir,
+                session: engine.session.id,
+                batchDir: ctx.dir,
+                item: item.id,
+                ok: true,
+                stopReason: outcome.result.stopReason,
+                durationMs: outcome.durationMs,
+                models,
+            });
+            ctx.progress.finish(item.id, { ok: true, usage: outcome.result.usage, models });
+            return { index: item.index, id: item.id, ok: true, input: index(item.input), output };
+        }
+        finally {
+            await engine.close();
+        }
+    }
+    catch (err) {
+        const error = {
+            message: err instanceof Error ? err.message : String(err),
+            ...(err instanceof CliError && err.hint ? { hint: err.hint } : {}),
+        };
+        await writeFile(output, jsonText({ ok: false, id: item.id, error }), 'utf8');
+        appendUsage(ctx.projectDir, {
+            kind: 'run',
+            ts: new Date().toISOString(),
+            batchDir: ctx.dir,
+            item: item.id,
+            ok: false,
+            error: error.message,
+            models: [],
+        });
+        ctx.progress.finish(item.id, { ok: false, error: error.message });
+        return {
+            index: item.index,
+            id: item.id,
+            ok: false,
+            input: index(item.input),
+            output,
+            error,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Parts
+// ---------------------------------------------------------------------------
+/**
+ * A bounded map that keeps its order. Workers pull from one cursor rather than
+ * taking a slice each, so a batch of one slow item and fifty fast ones finishes
+ * in the time of the slow one instead of the time of the slowest slice.
+ *
+ * `worker` is expected not to throw; `runItem` is the only caller and catches.
+ */
+export async function pool(items, limit, worker) {
+    const out = new Array(items.length);
+    let next = 0;
+    const runner = async () => {
+        for (;;) {
+            const i = next;
+            next += 1;
+            if (i >= items.length) {
+                return;
+            }
+            out[i] = await worker(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runner));
+    return out;
+}
+/** `--concurrency`, or the default. */
+export function concurrency(value) {
+    if (value === undefined) {
+        return 16;
+    }
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw usageError(`--concurrency ${value}: expected a whole number, 1 or more`);
+    }
+    if (n > MAX_CONCURRENCY) {
+        throw usageError(`--concurrency ${n} is more than this runs at once`, `${MAX_CONCURRENCY} is the most; past that the limit is the provider's, not ours`);
+    }
+    return n;
+}
+/**
+ * Each item's memory, made before any of them runs.
+ *
+ * In the copying mode every item gets its own graph to write into, so that
+ * sixteen runs at once are sixteen private histories rather than one contended
+ * lock. A source that is not there yet is not an error: a project declares its
+ * memory directory and the first run makes it, so warming a cold project means
+ * copying from nothing, and nothing is what each item starts with.
+ */
+export async function prepareMemories(items, at) {
+    const prepared = new Map();
+    for (const item of items) {
+        await mkdir(join(at.dir, item.id), { recursive: true });
+        if (at.mode === 'copied' && at.source) {
+            const mine = join(at.dir, item.id, 'memory');
+            if (at.seeded) {
+                await cp(at.source, mine, { recursive: true, filter: notLock });
+            }
+            prepared.set(item.id, mine);
+        }
+        else if (at.mode === 'read-only' && at.source) {
+            prepared.set(item.id, at.source);
+        }
+    }
+    return prepared;
+}
+/**
+ * Drops the memories nothing was committed to, and counts the ones left.
+ *
+ * A memory is its manifest and the two files beside it; a directory without
+ * one is not a memory and `merge` refuses it by name. Leaving those behind
+ * would mean the `merge` line this command prints is advice that fails, so an
+ * item that learned nothing leaves nothing.
+ */
+export async function keepWritten(prepared) {
+    let kept = 0;
+    for (const at of prepared.values()) {
+        if (existsSync(join(at, MEMORY_MANIFEST))) {
+            kept += 1;
+        }
+        else {
+            await rm(at, { recursive: true, force: true });
+        }
+    }
+    return kept;
+}
+/** Where the batch reads memory from: `--memory`, else what the project says. */
+function memorySource(projectDir, override) {
+    try {
+        return memoryDir(projectDir, readProjectConfig(projectDir).config, override);
+    }
+    catch {
+        // An unloadable project is about to fail properly, with its own error.
+        return override;
+    }
+}
+/** The lock belongs to the run that took it, never to a copy of its memory. */
+const notLock = (src) => basename(src) !== '.lock';
+/**
+ * The question, for the index — text whole, media named rather than repeated.
+ * Every byte is already in the item's own run input file, and a combined file
+ * carrying forty inlined screenshots is not an index of anything.
+ */
+function index(input) {
+    if (typeof input === 'string') {
+        return input;
+    }
+    const parts = Array.isArray(input) ? input : [input];
+    return parts.map((part) => summarise(part));
+}
+function summarise(part) {
+    if (part.type === 'text') {
+        return part;
+    }
+    if (part.url.startsWith('data:')) {
+        return { type: part.type, mimeType: part.mimeType, bytes: part.url.length, inlined: true };
+    }
+    return part;
+}
+//# sourceMappingURL=batch.js.map

package/dist/catalog.d.ts

@@ -36,6 +36,8 @@ export interface CatalogEntry {
     };
     /** ISO date the model was published, when known */
     created?: string;
+    /** vertex only: who makes it - `google`, or the partner Vertex resells */
+    publisher?: string;
     source: 'live' | 'curated';
 }
 /** A provider's listing, and an honest account of where it came from. */
@@ -72,6 +74,7 @@ export declare const PREFERRED: Record<Provider, {
     chat: readonly string[];
     embedding: readonly string[];
 }>;
+export declare function fromVertexPartners(): Promise<CatalogEntry[]>;
 /**
  * Asks one provider what it serves. Throws whatever the SDK throws.
  *
@@ -79,8 +82,9 @@ export declare const PREFERRED: Record<Provider, {
  * to break when a vendor reshapes a payload, and they are untestable if the
  * only way to reach them is a credential and a network. It mirrors
  * `ProviderSpec.client`, which exists in the library for the same reason.
+ * `partners` is the same seam for Vertex's second listing.
  */
-export declare function fetchCatalog(provider: Provider, client?: unknown): Promise<CatalogEntry[]>;
+export declare function fetchCatalog(provider: Provider, client?: unknown, partners?: () => Promise<CatalogEntry[]>): Promise<CatalogEntry[]>;
 /** The key one provider's listing is filed under, version and all. */
 export declare const catalogKey: (provider: Provider) => string;
 export interface CatalogOptions {
@@ -111,4 +115,10 @@ export interface Filters {
 export declare function matches(row: CatalogEntry, query: string, filters?: Filters): boolean;
 /** The providers a search covers when none was named. */
 export declare const catalogProviders: () => readonly Provider[];
+/** Resold on Vertex rather than made by Google. */
+export declare const isPartner: (e: CatalogEntry) => boolean;
+/** Provider, then Google's own models, then each partner's together. */
+export declare function byGroup(a: CatalogEntry, b: CatalogEntry): number;
+/** The heading a row is listed under, when its provider resells other makers' models. */
+export declare function groupOf(e: CatalogEntry): string | undefined;
 //# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -16,7 +16,7 @@
 // `source` for exactly that reason: a curated guess must never be mistaken for
 // the vendor's own word.
 // ---------------------------------------------------------------------------
-import { ModelRegistry } from '@zenera/neo';
+import { ModelRegistry, vertexEndpoint } from '@zenera/neo';
 import { Cache, cacheKey } from "./cache.js";
 import { PROVIDERS } from "./keys.js";
 import { classify } from "./liveness.js";
@@ -24,7 +24,7 @@ import { classify } from "./liveness.js";
 export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
 export const CATALOG_KIND = 'catalog';
 /** Bumped when the stored shape changes, which makes every old entry a miss. */
-const CATALOG_VERSION = 1;
+const CATALOG_VERSION = 2;
 // ---------------------------------------------------------------------------
 // The fallback table
 // ---------------------------------------------------------------------------
@@ -53,9 +53,17 @@ export const CURATED = {
         { id: 'gemini-embedding-2', roles: ['embedding'] },
     ],
     vertex: [
-        { id: 'gemini-3.5-flash-lite', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-3.8-flash', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-embedding-2', roles: ['embedding'] },
+        {
+            id: 'gemini-3.5-flash-lite',
+            roles: ['chat'],
+            contextLength: 1_048_576,
+            publisher: 'google',
+        },
+        { id: 'gemini-3.8-flash', roles: ['chat'], contextLength: 1_048_576, publisher: 'google' },
+        { id: 'gemini-embedding-2', roles: ['embedding'], publisher: 'google' },
+        // Open-weight models are served but not listed by Model Garden, so these are the only record.
+        { id: 'qwen/qwen3-235b-a22b-instruct-2507-maas', roles: ['chat'], publisher: 'qwen' },
+        { id: 'openai/gpt-oss-120b-maas', roles: ['chat'], publisher: 'openai' },
     ],
     openrouter: [
         { id: 'openai/gpt-5.6-luna', roles: ['chat'], contextLength: 1_050_000 },
@@ -227,6 +235,7 @@ async function fromGenAI(client, provider) {
             description: model.description,
             contextLength: model.inputTokenLimit,
             maxOutputTokens: model.outputTokenLimit,
+            publisher: provider === 'vertex' ? 'google' : undefined,
         }));
     }
     return rows;
@@ -296,6 +305,38 @@ async function fromRouter(client, provider) {
     }
     return rows;
 }
+/**
+ * Partner models on Vertex. The GenAI listing holds Google's alone, so each
+ * partner's Model Garden listing is asked as well - only for publishers whose
+ * models the runtime can call: Claude at `rawPredict`, the rest at the
+ * OpenAI-compatible endpoint as `publisher/model`.
+ */
+const VERTEX_PARTNERS = ['anthropic', 'xai'];
+export async function fromVertexPartners() {
+    const at = vertexEndpoint();
+    const token = await at.token();
+    const lists = await Promise.all(VERTEX_PARTNERS.map(async (publisher) => {
+        const res = await fetch(`https://aiplatform.googleapis.com/v1beta1/publishers/${publisher}/models?pageSize=200`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'x-goog-user-project': at.project,
+            },
+        });
+        if (!res.ok) {
+            return [];
+        }
+        const body = (await res.json());
+        return (body.publisherModels ?? [])
+            .map((m) => bareId(m.name ?? ''))
+            .filter((id) => id && !/embed|ocr/.test(id))
+            .map((id) => entry('vertex', {
+            id: publisher === 'anthropic' ? id : `${publisher}/${id}`,
+            roles: ['chat'],
+            publisher,
+        }));
+    }));
+    return lists.flat();
+}
 /**
  * Asks one provider what it serves. Throws whatever the SDK throws.
  *
@@ -303,16 +344,27 @@ async function fromRouter(client, provider) {
  * to break when a vendor reshapes a payload, and they are untestable if the
  * only way to reach them is a credential and a network. It mirrors
  * `ProviderSpec.client`, which exists in the library for the same reason.
+ * `partners` is the same seam for Vertex's second listing.
  */
-export async function fetchCatalog(provider, client = new ModelRegistry().client(provider)) {
+export async function fetchCatalog(provider, client = new ModelRegistry().client(provider), partners = fromVertexPartners) {
     switch (provider) {
         case 'openai':
             return enrich(provider, await fromOpenAI(client, provider));
         case 'anthropic':
             return enrich(provider, await fromAnthropic(client, provider));
         case 'google':
-        case 'vertex':
             return enrich(provider, await fromGenAI(client, provider));
+        case 'vertex': {
+            // A partner listing that fails must not cost the Gemini one.
+            const [google, others] = await Promise.all([
+                fromGenAI(client, provider),
+                partners().catch(() => []),
+            ]);
+            const live = [...google, ...others];
+            const seen = new Set(live.map((r) => r.id));
+            const unlisted = curated(provider).filter((r) => r.publisher !== 'google' && !seen.has(r.id));
+            return enrich(provider, [...live, ...unlisted]);
+        }
         case 'openrouter':
             return enrich(provider, await fromRouter(client, provider));
     }
@@ -459,4 +511,25 @@ export function matches(row, query, filters = {}) {
 }
 /** The providers a search covers when none was named. */
 export const catalogProviders = () => PROVIDERS;
+// ---------------------------------------------------------------------------
+// Grouping
+// ---------------------------------------------------------------------------
+/** Resold on Vertex rather than made by Google. */
+export const isPartner = (e) => e.publisher !== undefined && e.publisher !== 'google';
+/** Provider, then Google's own models, then each partner's together. */
+export function byGroup(a, b) {
+    return (a.provider.localeCompare(b.provider) ||
+        Number(isPartner(a)) - Number(isPartner(b)) ||
+        (a.publisher ?? '').localeCompare(b.publisher ?? '') ||
+        a.id.localeCompare(b.id));
+}
+/** The heading a row is listed under, when its provider resells other makers' models. */
+export function groupOf(e) {
+    if (!e.publisher) {
+        return undefined;
+    }
+    return isPartner(e)
+        ? `${e.provider} · partner · ${e.publisher}`
+        : `${e.provider} · Google (Gemini, Gemma, Imagen, Veo)`;
+}
 //# sourceMappingURL=catalog.js.map

package/dist/command.d.ts

@@ -12,6 +12,12 @@ export interface Command {
     readonly details?: readonly string[];
     /** printed instead of the `zen` banner, so the sub-brand shows through */
     readonly banner?: BannerText;
+    /**
+     * True when this invocation's stdout is the answer rather than a report on
+     * it. The banner is then held back rather than dropped: if the run turns
+     * out to need a prompt, someone is there to see it, and it appears.
+     */
+    readonly quiet?: (args: readonly string[]) => boolean;
     /**
      * Answers `--help` itself, for a command whose arguments select a page the
      * frame cannot see. Without it the frame prints this command's own page.

package/dist/commands/inspect.d.ts

@@ -1,3 +1,60 @@
 import type { Command } from '../command.ts';
+import { type RunPaths, type SessionPaths } from '../session.ts';
+import { type NodeDetail, type Trace, type TraceEntry } from '../trace.ts';
+interface Flags {
+    project?: string;
+    session?: string;
+    run?: string;
+    dir?: string;
+    memory?: string;
+    model?: string;
+    part?: string[];
+    'question-file'?: string;
+    full?: boolean;
+    open?: boolean;
+    rebuild?: boolean;
+    'no-timing'?: boolean;
+    'no-style'?: boolean;
+}
 export declare const inspect: Command;
+/**
+ * Which parts print in full: everything `--part` names, or everything but
+ * `request`. A prefix matches, so `--part call` catches `call run_command (…)`.
+ */
+export declare function wholeParts(found: readonly NodeDetail[], values: {
+    part?: string[];
+    full?: boolean;
+}): (name: string) => boolean;
+/**
+ * One recorded call, put back to a model with a question on the end.
+ *
+ * `node` shows what the model was given; this asks the model what it made of
+ * it. Everything it sees is what it saw at the time, so an answer naming the
+ * skill that steered it is checkable against the same node.
+ */
+export declare function replayableCalls(trace: Trace): {
+    entry: TraceEntry;
+    node: import("@zenera/neo").LlmCallNode;
+}[];
+export declare function renderAskExchange(question: string, answer: string, columns?: number): string[];
+export declare function repeatQuestions(initial: string, next: () => Promise<string>, answer: (question: string) => Promise<void>): Promise<void>;
+/** The question: the words on the line, or the whole of `--question-file` (`-` is stdin). */
+export declare function readQuestion(words: readonly string[], file: string | undefined, cwd: string): Promise<string>;
+/** One node, framed so a payload cannot be mistaken for the next node. */
+export declare function renderNode(node: NodeDetail, whole?: (name: string) => boolean): string;
+export interface Located {
+    project: string;
+    session: SessionPaths;
+    run: RunPaths;
+}
+/**
+ * Which run, by whichever handle the caller has.
+ *
+ * A directory is the handle a *program* holds: `zen run --json` reports one,
+ * and asking it to be taken apart into a project, a session and a run before
+ * it can be used again would be work for nothing. A person holds an id, or
+ * nothing at all and gets asked.
+ */
+export declare function locate(cwd: string, values: Pick<Flags, 'project' | 'session' | 'run' | 'dir'>, positional: string | undefined, asking: boolean): Promise<Located>;
+export {};
 //# sourceMappingURL=inspect.d.ts.map