@zenera/cli 1.1.23 → 1.1.25

package/dist/meta/finetune/usage.js

@@ -0,0 +1,225 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export const STAGES = ['run', 'analyze', 'apply'];
+const zero = () => ({ calls: 0, input: 0, cached: 0, output: 0, reasoning: 0 });
+function addTo(into, model, t) {
+    const m = (into[model] ??= zero());
+    m.calls += t.calls;
+    m.input += t.input;
+    m.cached += t.cached;
+    m.output += t.output;
+    m.reasoning += t.reasoning;
+}
+export function mergeModels(...all) {
+    const out = {};
+    for (const by of all) {
+        for (const [model, t] of Object.entries(by ?? {})) {
+            addTo(out, model, t);
+        }
+    }
+    return out;
+}
+export function mergeStages(...all) {
+    const out = {};
+    for (const stage of STAGES) {
+        const parts = all.map((s) => s?.[stage]).filter((p) => !!p);
+        if (parts.length > 0) {
+            out[stage] = mergeModels(...parts);
+        }
+    }
+    return out;
+}
+export function total(by) {
+    const sum = {};
+    for (const t of Object.values(by ?? {})) {
+        addTo(sum, 'all', t);
+    }
+    return sum.all ?? zero();
+}
+/** Input plus output, the input counting cached tokens. */
+export function spent(by) {
+    const s = total(by);
+    return s.input + s.output;
+}
+const fromUsage = (u, calls) => ({
+    calls,
+    input: u.inputTokens ?? 0,
+    cached: u.cachedInputTokens ?? 0,
+    output: u.outputTokens ?? 0,
+    reasoning: u.reasoningTokens ?? 0,
+});
+/** `vertex/gemini-3.8-flash` and `gemini-3.8-flash` are one model in a table. */
+export const modelName = (m) => m ? m.replace(/^[^/:]+[/:]/, '') : '?';
+/** `SandboxError`s the engine causes; a path outside the workspace is the model's own doing. */
+const SANDBOX_DOWN = /could not (create|start) container|the sandbox container \S+ stopped|could not (write|start) the job|is not installed, or not on PATH|exceeded num_locks|cannot connect to podman/i;
+const cache = new Map();
+/**
+ * One walk of a run's `state.json`, branches included. Nested records repeat a
+ * node, so nodes are counted by id. A node is stamped when the work behind it
+ * finished, so the gap to the node before it in the same lane is that work -
+ * the same timing as the Stats tab of report.html.
+ */
+export function runMetrics(runDir) {
+    const file = join(runDir, 'state.json');
+    if (!existsSync(file)) {
+        return undefined;
+    }
+    const st = statSync(file);
+    const key = `${st.mtimeMs}:${st.size}`;
+    const hit = cache.get(file);
+    if (hit?.key === key) {
+        return hit.metrics;
+    }
+    let root;
+    try {
+        root = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const m = {
+        models: {},
+        llmMs: 0,
+        toolMs: 0,
+        toolCalls: 0,
+        toolErrors: 0,
+        memory: { recall: 0, load: 0, grep: 0, commit: 0, forget: 0 },
+        forks: 0,
+        branches: 0,
+        compactions: 0,
+        handoffs: 0,
+    };
+    const seen = new Set();
+    const count = (o, ms) => {
+        switch (o.type) {
+            case 'llm_call':
+            case 'compaction': {
+                if (!o.usage) {
+                    return;
+                }
+                const model = o.type === 'compaction' ? 'summarizer' : modelName(o.model);
+                const t = fromUsage(o.usage, 1);
+                const into = (m.models[model] ??= { ...zero(), peak: 0, ms: 0 });
+                into.calls += 1;
+                into.input += t.input;
+                into.cached += t.cached;
+                into.output += t.output;
+                into.reasoning += t.reasoning;
+                into.peak = Math.max(into.peak, t.input);
+                into.ms += ms;
+                m.llmMs += ms;
+                if (o.type === 'compaction') {
+                    m.compactions++;
+                }
+                return;
+            }
+            case 'tool_result': {
+                m.toolCalls++;
+                m.toolErrors += o.isError ? 1 : 0;
+                m.toolMs += typeof o.durationMs === 'number' ? o.durationMs : ms;
+                const said = o.result?.preview;
+                if (!m.sandbox && typeof said === 'string' && SANDBOX_DOWN.test(said)) {
+                    m.sandbox = /"error":\s*"([^"]+)/.exec(said)?.[1] ?? said;
+                }
+                return;
+            }
+            case 'memory_recall':
+                m.memory.recall++;
+                return;
+            case 'memory_op': {
+                const op = o.op;
+                if (op in m.memory) {
+                    m.memory[op]++;
+                }
+                return;
+            }
+            case 'fork':
+                m.forks++;
+                m.branches += Array.isArray(o.branches) ? o.branches.length : 0;
+                return;
+            case 'handoff':
+                m.handoffs++;
+                return;
+        }
+    };
+    // A branch lane starts where its parent lane was when the fork began.
+    const walk = (v, lanePrev) => {
+        if (Array.isArray(v)) {
+            let prev = lanePrev;
+            for (const item of v) {
+                const o = item;
+                const ts = o && typeof o.ts === 'string' ? Date.parse(o.ts) : NaN;
+                if (o &&
+                    typeof o.type === 'string' &&
+                    typeof o.id === 'string' &&
+                    !seen.has(o.id)) {
+                    seen.add(o.id);
+                    count(o, prev !== undefined && !Number.isNaN(ts) ? Math.max(0, ts - prev) : 0);
+                }
+                walk(item, prev);
+                if (!Number.isNaN(ts)) {
+                    prev = ts;
+                }
+            }
+        }
+        else if (v && typeof v === 'object') {
+            for (const x of Object.values(v)) {
+                walk(x, lanePrev);
+            }
+        }
+    };
+    walk(root, undefined);
+    cache.set(file, { key, metrics: m });
+    return m;
+}
+/** The token part of a run's metrics, per model. */
+export function tokensOf(m) {
+    return Object.fromEntries(Object.entries(m.models).map(([model, { calls, input, cached, output, reasoning }]) => [
+        model,
+        { calls, input, cached, output, reasoning },
+    ]));
+}
+export function runTokens(runDir) {
+    const m = runMetrics(runDir);
+    return m ? tokensOf(m) : undefined;
+}
+/** One `zen meta run --json` envelope: `{ model, tokens: { calls, inputTokens, … } }`. */
+export function envelopeTokens(file) {
+    if (!existsSync(file)) {
+        return undefined;
+    }
+    let env;
+    try {
+        env = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!env.tokens) {
+        return undefined;
+    }
+    return { [modelName(env.model)]: fromUsage(env.tokens, env.tokens.calls ?? 0) };
+}
+/** Every envelope in `dir` named `<stem>.json` or `<stem>-<n>.json` - retries keep their own. */
+export function envelopesIn(dir, stem) {
+    let names = [];
+    try {
+        names = readdirSync(dir).filter((n) => new RegExp(`^${stem}(-\\d+)?\\.json$`).test(n));
+    }
+    catch {
+        return undefined;
+    }
+    const parts = names.map((n) => envelopeTokens(join(dir, n))).filter((p) => !!p);
+    return parts.length > 0 ? mergeModels(...parts) : undefined;
+}
+/** 1234 → 1.2k, 2184341 → 2.2M. */
+export function short(n) {
+    if (n >= 1_000_000) {
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    }
+    if (n >= 1000) {
+        return `${Math.round(n / 1000)}k`;
+    }
+    return String(n);
+}
+//# sourceMappingURL=usage.js.map

package/dist/meta/host.d.ts

@@ -0,0 +1,14 @@
+export { invokedAs, parse } from '../args.ts';
+export type { EventLine } from '../eventlog.ts';
+export { paths, readJson, writeJson } from '../home.ts';
+export { envOf, type KeyEntry, type KeyStore, type Provider } from '../keys.ts';
+export { PROVIDER_NAMES, splitRef } from '../modelref.ts';
+export { duration } from '../narrate.ts';
+export { copyTree, MEMORY_RULES, TEMPLATES } from '../scaffold.ts';
+export { bold, CliError, confirm, credentialError, cut, cyan, dim, EXIT, green, invalidError, json, note, pad, plain, red, styled, table, usageError, write, writeAll, yellow, } from '../term.ts';
+export { safe } from '../trace.ts';
+export { formatInline, formatMarkdown } from '../tui/markdown.ts';
+export { resolveTheme, type Theme } from '../tui/theme.ts';
+export { boxWidth } from '../tui/wrap.ts';
+export { META_PROMPT_ENV, META_SESSION_ENV } from '../usage.ts';
+//# sourceMappingURL=host.d.ts.map

package/dist/meta/host.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// The meta layer's one door into the rest of the CLI
+//
+// Everything under `src/meta/` imports the runtime through this file and no
+// other, so the layer can leave for a package of its own by turning this into
+// a dependency. `test/meta-boundary.test.ts` holds the line.
+// ---------------------------------------------------------------------------
+export { invokedAs, parse } from "../args.js";
+export { paths, readJson, writeJson } from "../home.js";
+export { envOf } from "../keys.js";
+export { PROVIDER_NAMES, splitRef } from "../modelref.js";
+export { duration } from "../narrate.js";
+export { copyTree, MEMORY_RULES, TEMPLATES } from "../scaffold.js";
+export { bold, CliError, confirm, credentialError, cut, cyan, dim, EXIT, green, invalidError, json, note, pad, plain, red, styled, table, usageError, write, writeAll, yellow, } from "../term.js";
+export { safe } from "../trace.js";
+export { formatInline, formatMarkdown } from "../tui/markdown.js";
+export { resolveTheme } from "../tui/theme.js";
+export { boxWidth } from "../tui/wrap.js";
+export { META_PROMPT_ENV, META_SESSION_ENV } from "../usage.js";
+//# sourceMappingURL=host.js.map

package/dist/meta/index.d.ts

@@ -0,0 +1,11 @@
+export * from './editor.ts';
+export * from './finetune/dataset/index.ts';
+export * from './finetune/index.ts';
+export * from './launch.ts';
+export * from './model.ts';
+export * from './prompts.ts';
+export * from './relay.ts';
+export * from './tokens.ts';
+export * from './window.ts';
+export * from './wire.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/meta/index.js

@@ -0,0 +1,11 @@
+export * from "./editor.js";
+export * from "./finetune/dataset/index.js";
+export * from "./finetune/index.js";
+export * from "./launch.js";
+export * from "./model.js";
+export * from "./prompts.js";
+export * from "./relay.js";
+export * from "./tokens.js";
+export * from "./window.js";
+export * from "./wire.js";
+//# sourceMappingURL=index.js.map

package/dist/meta/launch.d.ts

@@ -0,0 +1,81 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type Sink } from './window.ts';
+export interface Binary {
+    command: string;
+    args: string[];
+    from: 'path' | 'npx';
+}
+/**
+ * A `copilot` already installed is used as it is; otherwise `npx` fetches one.
+ * Note that finding the name on `PATH` is not the same as finding the CLI —
+ * an editor may have put a shim there that installs it on first run — so this
+ * only decides how to launch, never whether it will work.
+ */
+export declare function locate(has?: (cmd: string) => boolean): Binary;
+interface Event {
+    type: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface Outcome {
+    /** the last thing the agent said that was not a preamble to a tool call */
+    answer: string;
+    exitCode: number;
+    sessionId?: string;
+    usage?: Record<string, unknown>;
+    events: Event[];
+}
+export interface Log {
+    readonly path: string;
+    /** Where the answer alone goes, beside the log and openable on its own. */
+    readonly answerPath: string;
+    line(text: string): void;
+    saveAnswer(text: string): void;
+    close(): void;
+}
+/**
+ * `<project>/.tmp/logs/meta.<when>[-<session>].log`, opened for append. The
+ * session keeps runs started in the same second - a tuning loop's - apart.
+ */
+export declare function openLog(dir: string, now?: Date, session?: string): Log;
+export declare function recordSession(dir: string, id: string): void;
+export declare function lastSession(dir: string): string | undefined;
+/**
+ * Folds one event into the outcome and says what, if anything, to show for it.
+ *
+ * `assistant.message` carries both the running commentary and the final word;
+ * what separates them is `toolRequests`, so the last message that asked for no
+ * tool is the answer and the rest are narration.
+ */
+export declare function absorb(event: Event, out: Outcome, sink: Sink, width: number): void;
+export interface Launch {
+    binary: Binary;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    sink?: Sink;
+    log?: Log;
+    width?: number;
+    /** said after the elapsed time on the status row, e.g. the tokens so far */
+    status?: () => string;
+    /** every event copilot prints, before it is folded */
+    onEvent?: (event: Event) => void;
+    /** injected by the tests, which have no copilot and want none */
+    spawn?: typeof nodeSpawn;
+}
+export declare function launch(opts: Launch): Promise<Outcome>;
+/** Resumes after copilot's own retries run out; `--retries` overrides. */
+export declare const DEFAULT_RESUMES = 5;
+/** What the resumed session is told, since `-p` has to say something. */
+export declare const RESUME_PROMPT = "The previous model call failed. Continue the task from where you stopped.";
+export declare function resumeDelayMs(attempt: number): number;
+/**
+ * Why the run is worth resuming, or undefined when waiting cannot help.
+ *
+ * Only a refusal that time can cure counts: a rate limit, the provider's own
+ * failure, a connection that timed out. A 400 or a bad key fails the same way
+ * however often it is sent - except the one below.
+ */
+export declare function transient(out: Outcome): string | undefined;
+export {};
+//# sourceMappingURL=launch.d.ts.map

package/dist/meta/launch.js

@@ -0,0 +1,286 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { cut, dim, duration, formatInline, plain } from "./host.js";
+import { FRAME_MS, windowSink } from "./window.js";
+/**
+ * A `copilot` already installed is used as it is; otherwise `npx` fetches one.
+ * Note that finding the name on `PATH` is not the same as finding the CLI —
+ * an editor may have put a shim there that installs it on first run — so this
+ * only decides how to launch, never whether it will work.
+ */
+export function locate(has = (cmd) => onPath(cmd)) {
+    return has('copilot')
+        ? { command: 'copilot', args: [], from: 'path' }
+        : { command: 'npx', args: ['--yes', '@github/copilot'], from: 'npx' };
+}
+function onPath(cmd) {
+    const dirs = (process.env.PATH ?? '').split(':').filter(Boolean);
+    return dirs.some((d) => existsSync(`${d}/${cmd}`));
+}
+/**
+ * `<project>/.tmp/logs/meta.<when>[-<session>].log`, opened for append. The
+ * session keeps runs started in the same second - a tuning loop's - apart.
+ */
+export function openLog(dir, now = new Date(), session) {
+    const two = (n) => String(n).padStart(2, '0');
+    const stamp = `${now.getFullYear()}${two(now.getMonth() + 1)}${two(now.getDate())}` +
+        `${two(now.getHours())}${two(now.getMinutes())}${two(now.getSeconds())}` +
+        (session ? `-${session.slice(0, 8)}` : '');
+    const folder = `${dir}/.tmp/logs`;
+    mkdirSync(folder, { recursive: true });
+    const path = `${folder}/meta.${stamp}.log`;
+    const answerPath = `${folder}/meta.${stamp}.md`;
+    const file = createWriteStream(path, { flags: 'a' });
+    return {
+        path,
+        answerPath,
+        line: (text) => {
+            file.write(`${plain(text)}\n`);
+        },
+        saveAnswer: (text) => {
+            writeFileSync(answerPath, text.endsWith('\n') ? text : `${text}\n`);
+        },
+        close: () => {
+            file.end();
+        },
+    };
+}
+/** The project's last meta session, so `zen meta resume` needs no id. */
+function sessionFile(dir) {
+    return `${dir}/.tmp/logs/meta.session`;
+}
+export function recordSession(dir, id) {
+    mkdirSync(`${dir}/.tmp/logs`, { recursive: true });
+    writeFileSync(sessionFile(dir), `${id}\n`);
+}
+export function lastSession(dir) {
+    try {
+        return readFileSync(sessionFile(dir), 'utf8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Everything the sink is told, kept by the log too — and the detail only there. */
+function tee(sink, log) {
+    return {
+        answer: (text) => sink.answer(text),
+        narrate: (line) => {
+            log.line(line);
+            sink.narrate(line);
+        },
+        detail: (line) => log.line(line),
+        warn: (line) => {
+            log.line(line);
+            sink.warn(line);
+        },
+        status: (line) => sink.status?.(line),
+        close: () => sink.close?.(),
+    };
+}
+/**
+ * Folds one event into the outcome and says what, if anything, to show for it.
+ *
+ * `assistant.message` carries both the running commentary and the final word;
+ * what separates them is `toolRequests`, so the last message that asked for no
+ * tool is the answer and the rest are narration.
+ */
+export function absorb(event, out, sink, width) {
+    const data = (event.data ?? {});
+    switch (event.type) {
+        case 'assistant.message': {
+            const content = String(data.content ?? '').trim();
+            const requests = Array.isArray(data.toolRequests) ? data.toolRequests : [];
+            if (requests.length === 0) {
+                out.answer = content;
+            }
+            else if (content) {
+                sink.narrate(cut(formatInline(content.replace(/\s+/g, ' ')), width));
+            }
+            break;
+        }
+        case 'tool.execution_start': {
+            const args = (data.arguments ?? {});
+            const what = String(args.command ?? args.description ?? data.toolName ?? '').trim();
+            // Step-by-step belongs in the log: on screen it is a wall of `$`
+            // saying less than the one line of commentary above it.
+            sink.detail?.(`$ ${what.replace(/\s+/g, ' ')}`);
+            break;
+        }
+        case 'tool.execution_complete': {
+            if (data.success === false) {
+                sink.detail?.(`  ${String(data.toolName ?? 'the tool')} failed`);
+            }
+            break;
+        }
+        case 'session.tools_updated': {
+            if (data.model) {
+                sink.detail?.(`model ${String(data.model)}`);
+            }
+            break;
+        }
+        case 'session.error': {
+            sink.warn(String(data.message ?? 'the session failed'));
+            break;
+        }
+        case 'model.call_failure': {
+            const status = data.statusCode ? ` (${String(data.statusCode)})` : '';
+            sink.warn(`${cut(String(data.errorMessage ?? 'the model call failed'), width)}${status}`);
+            break;
+        }
+        case 'result': {
+            out.exitCode = Number(event.exitCode ?? 0);
+            out.sessionId = event.sessionId;
+            out.usage = event.usage;
+            break;
+        }
+        default:
+            break;
+    }
+    out.events.push(event);
+}
+export async function launch(opts) {
+    const shown = opts.sink ?? windowSink();
+    const sink = opts.log ? tee(shown, opts.log) : shown;
+    const width = opts.width ?? Math.max(40, (process.stderr.columns ?? 100) - 4);
+    const start = opts.spawn ?? nodeSpawn;
+    const out = { answer: '', exitCode: 0, events: [] };
+    const child = start(opts.binary.command, [...opts.binary.args, ...opts.args], {
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: false,
+    });
+    const stop = (signal) => () => {
+        child.kill(signal);
+    };
+    const onInt = stop('SIGINT');
+    const onTerm = stop('SIGTERM');
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    // The first model call says nothing for as long as it takes, and silence
+    // after the model line is indistinguishable from a hang.
+    const began = Date.now();
+    const beat = setInterval(() => {
+        const extra = opts.status?.();
+        sink.status?.(`working: ${duration(Date.now() - began)}${extra ? ` · ${extra}` : ''}`);
+    }, FRAME_MS);
+    beat.unref();
+    child.stderr?.on('data', (chunk) => {
+        const text = chunk.toString().trimEnd();
+        if (text) {
+            sink.narrate(dim(text));
+        }
+    });
+    try {
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        for await (const line of lines) {
+            if (!line.trim()) {
+                continue;
+            }
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                // Not ours to interpret, but losing it is worse than showing it.
+                sink.narrate(line);
+                continue;
+            }
+            opts.onEvent?.(event);
+            absorb(event, out, sink, width);
+        }
+        const code = await new Promise((resolve) => {
+            child.on('close', (value, signal) => resolve(value ?? (signal ? 1 : 0)));
+        });
+        if (out.exitCode === 0 && code !== 0) {
+            out.exitCode = code;
+        }
+    }
+    finally {
+        clearInterval(beat);
+        process.off('SIGINT', onInt);
+        process.off('SIGTERM', onTerm);
+        // The answer is written by the caller, so the window has to be gone first.
+        sink.close?.();
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Resuming
+//
+// Copilot retries a failed model call itself, five times over about a minute,
+// and has no setting to change that. A run that outlasts it is still a session
+// on disk, so the retry happens one level up: wait, then resume that session.
+// ---------------------------------------------------------------------------
+/** Resumes after copilot's own retries run out; `--retries` overrides. */
+export const DEFAULT_RESUMES = 5;
+/** The first wait; it doubles per resume, up to `RESUME_MAX_MS`. */
+const RESUME_INITIAL_MS = 30_000;
+const RESUME_MAX_MS = 300_000;
+/** What the resumed session is told, since `-p` has to say something. */
+export const RESUME_PROMPT = 'The previous model call failed. Continue the task from where you stopped.';
+export function resumeDelayMs(attempt) {
+    return Math.min(RESUME_INITIAL_MS * 2 ** attempt, RESUME_MAX_MS);
+}
+/**
+ * Why the run is worth resuming, or undefined when waiting cannot help.
+ *
+ * Only a refusal that time can cure counts: a rate limit, the provider's own
+ * failure, a connection that timed out. A 400 or a bad key fails the same way
+ * however often it is sent - except the one below.
+ */
+export function transient(out) {
+    if (out.exitCode === 0 || !out.sessionId) {
+        return undefined;
+    }
+    const at = out.events.findLastIndex((e) => e.type === 'session.error');
+    const data = out.events[at]?.data;
+    if (!data) {
+        return undefined;
+    }
+    const status = Number(data.statusCode ?? 0);
+    if (data.errorType === 'rate_limit' || status === 429) {
+        return 'rate-limited (429)';
+    }
+    if (status === 408 || status >= 500) {
+        return `the provider failed (${status})`;
+    }
+    if (/timed out|ECONNRESET|socket hang up/i.test(String(data.message ?? ''))) {
+        return 'the connection failed';
+    }
+    if (status === 400 && injected(out.events.slice(0, at))) {
+        return 'refused a tool call copilot made itself (400)';
+    }
+    return undefined;
+}
+/**
+ * Whether the turn that failed began with a tool call copilot wrote, not the
+ * model. When a background command finishes, copilot adds a `read_bash` of its
+ * own; Gemini 3 rejects any tool call in the current turn that lacks its thought
+ * signature, so that request is a 400 every time. A new user message - the
+ * resume - starts a turn that no longer holds it.
+ */
+function injected(before) {
+    for (let i = before.length - 1; i >= 0; i--) {
+        const event = before[i];
+        if (event.type === 'system.notification') {
+            return true;
+        }
+        if (event.type === 'user.message') {
+            return false;
+        }
+        if (event.type === 'assistant.message') {
+            if (event.data?.model) {
+                return false;
+            }
+            const requests = event.data?.toolRequests;
+            if (Array.isArray(requests) && requests.length > 0) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=launch.js.map