@zenera/cli 1.1.24 → 1.1.25

package/dist/meta/finetune/tuning.d.ts

@@ -0,0 +1,167 @@
+import { type ChildProcess } from 'node:child_process';
+import type { Case } from './dataset/types.ts';
+import type { Phase } from './feedback.ts';
+import { Improvements } from './improvements.ts';
+import { Journal } from './journal.ts';
+import type { Snapshot } from './live.ts';
+import { Memories } from './memories.ts';
+import { SystemVersions } from './system.ts';
+import type { ByStage } from './usage.ts';
+export declare const FINETUNE_DIR = "finetune";
+/** Where a tuning was kept before it moved to {@link FINETUNE_DIR}. */
+export declare const LEGACY_FINETUNE_DIR = ".finetune";
+export interface Config {
+    workers: number;
+    /** apply once this many requests are waiting */
+    applyAt: number;
+    tries: number;
+    memTries: number;
+    /** merge the submitted memories after this many more arrive */
+    mergeEvery: number;
+    seed: number;
+    classes?: string[];
+    ids?: string[];
+    rubric?: boolean;
+    limit?: number;
+}
+export declare const DEFAULTS: Config;
+export type Step = 'idle' | 'run' | 'analyze' | 'parked';
+export interface Worker {
+    slot: number;
+    case?: Case;
+    phase?: Phase;
+    attempt?: number;
+    step: Step;
+    since: number;
+}
+/** A case in flight. It holds a worker only while it runs or is analyzed; parked, it holds none. */
+export interface Seat {
+    case: Case;
+    worker?: Worker;
+    phase?: Phase;
+}
+/** Runs `zen <args>` in the project, stderr into `log`; stdout is returned. */
+export type Zen = (args: string[], log: string) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+export declare class Stopped extends Error {
+    constructor();
+}
+export interface Event {
+    at: string;
+    what: string;
+    worker?: number;
+    case?: string;
+    rev?: number;
+    phase?: Phase;
+    attempt?: number;
+    detail?: string;
+    /** a step that ended: what it came to, how long it took, what it spent */
+    result?: string;
+    took?: number;
+    tokens?: number;
+}
+/** Failed cases in a row, with nothing going through between, that stop the loop. */
+export declare const FAILURES_IN_A_ROW = 3;
+export interface StepFailure {
+    at: string;
+    /** `merge-20 · no memory try 1`, `apply 004`, `memory m03` */
+    where: string;
+    message: string;
+    log?: string;
+}
+export declare class Tuning {
+    readonly root: string;
+    readonly dir: string;
+    readonly config: Config;
+    readonly zen: Zen;
+    readonly tickMs: number;
+    readonly workers: Worker[];
+    readonly claimed: Set<string>;
+    readonly startedAt: number;
+    readonly recent: Event[];
+    readonly system: SystemVersions;
+    readonly journal: Journal;
+    readonly improvements: Improvements;
+    readonly memories: Memories;
+    stopping: boolean;
+    finished: boolean;
+    fatal: Error | undefined;
+    /** woken cases waiting for a worker: they go before any new case */
+    resuming: number;
+    /** every case of the selection has been started */
+    drained: boolean;
+    /** cases started by this process: a failed one is not taken twice in one start */
+    readonly tried: Set<string>;
+    /** cases failed since the last step that went through */
+    failures: number;
+    /** what the last status page counted */
+    progress: {
+        counts: Record<string, number>;
+        total: number;
+        spent: ByStage;
+    } | undefined;
+    /** called with every live snapshot */
+    readonly watchers: Set<(s: Snapshot) => void>;
+    /** the latest step failures, newest first */
+    readonly errors: StepFailure[];
+    constructor(root: string, config: Config, zen: Zen, tickMs?: number);
+    get stopFile(): string;
+    tick(): Promise<void>;
+    stop(why: string): void;
+    /** Between steps: a stop takes effect here, never in the middle of one. */
+    checkStopping(): void;
+    caseDir(c: {
+        id: string;
+        rev: number;
+    }): string;
+    /** Where `retry` puts a case's earlier rounds: `r<rev>.<round>`. */
+    roundsDir(c: {
+        id: string;
+    }): string;
+    /** 1 for a case never retried at this revision. */
+    round(c: {
+        id: string;
+        rev: number;
+    }): number;
+    /** A step went through: the sandbox and the providers are up. */
+    succeeded(): void;
+    /** A case failed for a reason outside the prose. Enough in a row means nothing will go through. */
+    failed(why: string): void;
+    /** No run goes through without the container engine: stop at the first sign, not the third. */
+    sandboxDown(why: string): void;
+    attemptDir(c: {
+        id: string;
+        rev: number;
+    }, phase: Phase, attempt: number): string;
+    /** What the loop knows of a try, which a feedback file is never trusted for. */
+    known(c: {
+        id: string;
+        rev: number;
+    }, phase: Phase, attempt: number): {
+        phase: Phase;
+        attempt: number;
+        round?: number | undefined;
+        case: string;
+        caseRev: number;
+    };
+    freeWorker(): Worker | undefined;
+    busy(): number;
+    /** Puts a case on a free worker, waiting for one; a woken case goes before a new one. */
+    seat(s: Seat, woken: boolean): Promise<void>;
+    /** Gives the case's worker back, for another case to use. */
+    unseat(s: Seat): void;
+    /** A case moved to another step on its worker. */
+    at(s: Seat, phase: Phase, attempt: number, step: Step): void;
+    /** A step ended: the worker is between steps until the next `at`, and the event says how it went. */
+    ended(s: Seat, e: Omit<Event, 'at' | 'worker' | 'case' | 'rev'>): void;
+    /** A step failed: kept for the live view, and in events.jsonl with its log. */
+    error(where: string, message: string, log?: string): void;
+    event(e: Omit<Event, 'at'>): void;
+    report(): void;
+}
+/** The real `zen`: this same binary, in its own process group so Ctrl-C reaches only us. */
+export declare function spawnZen(root: string, children: Set<ChildProcess>): Zen;
+export declare function readJson<T>(file: string): T | undefined;
+//# sourceMappingURL=tuning.d.ts.map

package/dist/meta/finetune/tuning.js

@@ -0,0 +1,289 @@
+import { spawn } from 'node:child_process';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CliError, EXIT } from "../host.js";
+import { forget, remember } from "./children.js";
+import { Improvements } from "./improvements.js";
+import { Journal } from "./journal.js";
+import { Memories } from "./memories.js";
+import { writeStatus } from "./report.js";
+import { SystemVersions } from "./system.js";
+// ---------------------------------------------------------------------------
+// One tuning, in progress
+//
+// Everything the workers and the applier share: where things go, the settings,
+// how `zen` is run, and what each worker is doing right now. Each case's own
+// progress is not held here - it is on disk, one folder per attempt.
+// ---------------------------------------------------------------------------
+export const FINETUNE_DIR = 'finetune';
+/** Where a tuning was kept before it moved to {@link FINETUNE_DIR}. */
+export const LEGACY_FINETUNE_DIR = '.finetune';
+export const DEFAULTS = {
+    workers: 4,
+    applyAt: 4,
+    tries: 4,
+    memTries: 3,
+    mergeEvery: 3,
+    seed: 1,
+};
+export class Stopped extends Error {
+    constructor() {
+        super('stopped');
+    }
+}
+const pad = (n) => String(n).padStart(2, '0');
+/** Failed cases in a row, with nothing going through between, that stop the loop. */
+export const FAILURES_IN_A_ROW = 3;
+export class Tuning {
+    root;
+    dir;
+    config;
+    zen;
+    tickMs;
+    workers;
+    claimed = new Set();
+    startedAt = Date.now();
+    recent = [];
+    system;
+    journal;
+    improvements;
+    memories;
+    stopping = false;
+    finished = false;
+    fatal;
+    /** woken cases waiting for a worker: they go before any new case */
+    resuming = 0;
+    /** every case of the selection has been started */
+    drained = false;
+    /** cases started by this process: a failed one is not taken twice in one start */
+    tried = new Set();
+    /** cases failed since the last step that went through */
+    failures = 0;
+    /** what the last status page counted */
+    progress;
+    /** called with every live snapshot */
+    watchers = new Set();
+    /** the latest step failures, newest first */
+    errors = [];
+    constructor(root, config, zen, tickMs = 1000) {
+        this.root = root;
+        this.dir = join(root, FINETUNE_DIR);
+        this.config = config;
+        this.zen = zen;
+        this.tickMs = tickMs;
+        this.workers = Array.from({ length: config.workers }, (_, slot) => ({
+            slot: slot + 1,
+            step: 'idle',
+            since: Date.now(),
+        }));
+        this.system = new SystemVersions(root, join(this.dir, 'systems'));
+        this.journal = new Journal(join(this.dir, 'journal.jsonl'));
+        this.improvements = new Improvements(this);
+        this.memories = new Memories(this);
+    }
+    get stopFile() {
+        return join(this.dir, 'stop');
+    }
+    async tick() {
+        await sleep(this.tickMs);
+        if (!this.stopping && existsSync(this.stopFile)) {
+            this.stop('stop requested');
+        }
+    }
+    stop(why) {
+        if (!this.stopping) {
+            this.stopping = true;
+            this.event({ what: 'stopping', detail: why });
+        }
+    }
+    /** Between steps: a stop takes effect here, never in the middle of one. */
+    checkStopping() {
+        if (this.stopping) {
+            throw new Stopped();
+        }
+    }
+    caseDir(c) {
+        return join(this.dir, 'cases', c.id, `r${c.rev}`);
+    }
+    /** Where `retry` puts a case's earlier rounds: `r<rev>.<round>`. */
+    roundsDir(c) {
+        return join(this.dir, 'cases', c.id, 'rounds');
+    }
+    /** 1 for a case never retried at this revision. */
+    round(c) {
+        try {
+            return (readdirSync(this.roundsDir(c)).filter((n) => n.startsWith(`r${c.rev}.`)).length + 1);
+        }
+        catch {
+            return 1;
+        }
+    }
+    /** A step went through: the sandbox and the providers are up. */
+    succeeded() {
+        this.failures = 0;
+    }
+    /** A case failed for a reason outside the prose. Enough in a row means nothing will go through. */
+    failed(why) {
+        this.failures++;
+        if (this.failures >= FAILURES_IN_A_ROW && !this.stopping) {
+            this.fatal = new CliError(`${this.failures} cases failed in a row - the last: ${why}`, EXIT.failed, 'fix what broke (the sandbox, a provider, a key), then start again: failed cases carry on where they stopped');
+            this.stop(`${this.failures} cases failed in a row`);
+        }
+    }
+    /** No run goes through without the container engine: stop at the first sign, not the third. */
+    sandboxDown(why) {
+        this.fatal ??= new CliError(`the sandbox failed: ${why}`, EXIT.sandbox, 'see what the engine says: zen sandbox status - fix it, then start again: failed cases carry on where they stopped');
+        this.stop('the sandbox failed');
+    }
+    attemptDir(c, phase, attempt) {
+        return join(this.caseDir(c), `${pad(attempt)}-${phase}`);
+    }
+    /** What the loop knows of a try, which a feedback file is never trusted for. */
+    known(c, phase, attempt) {
+        const round = this.round(c);
+        return { case: c.id, caseRev: c.rev, ...(round > 1 ? { round } : {}), phase, attempt };
+    }
+    freeWorker() {
+        return this.workers.find((w) => !w.case);
+    }
+    busy() {
+        return this.workers.filter((w) => w.case).length;
+    }
+    /** Puts a case on a free worker, waiting for one; a woken case goes before a new one. */
+    async seat(s, woken) {
+        if (woken) {
+            this.resuming++;
+        }
+        try {
+            for (;;) {
+                const w = this.freeWorker();
+                if (w && (woken || this.resuming === 0)) {
+                    Object.assign(w, {
+                        case: s.case,
+                        phase: undefined,
+                        attempt: undefined,
+                        step: 'idle',
+                        since: Date.now(),
+                    });
+                    s.worker = w;
+                    return;
+                }
+                this.checkStopping();
+                await this.tick();
+            }
+        }
+        finally {
+            if (woken) {
+                this.resuming--;
+            }
+        }
+    }
+    /** Gives the case's worker back, for another case to use. */
+    unseat(s) {
+        if (!s.worker) {
+            return;
+        }
+        Object.assign(s.worker, {
+            case: undefined,
+            phase: undefined,
+            attempt: undefined,
+            step: 'idle',
+            since: Date.now(),
+        });
+        s.worker = undefined;
+    }
+    /** A case moved to another step on its worker. */
+    at(s, phase, attempt, step) {
+        const w = s.worker;
+        s.phase = phase;
+        Object.assign(w, { case: s.case, phase, attempt, step, since: Date.now() });
+        this.event({
+            what: step,
+            worker: w.slot,
+            case: s.case.id,
+            rev: s.case.rev,
+            phase,
+            attempt,
+        });
+    }
+    /** A step ended: the worker is between steps until the next `at`, and the event says how it went. */
+    ended(s, e) {
+        if (s.worker) {
+            Object.assign(s.worker, { step: 'idle', since: Date.now() });
+        }
+        this.event({ worker: s.worker?.slot, case: s.case.id, rev: s.case.rev, ...e });
+    }
+    /** A step failed: kept for the live view, and in events.jsonl with its log. */
+    error(where, message, log) {
+        this.errors.unshift({
+            at: new Date().toISOString(),
+            where,
+            message,
+            ...(log ? { log } : {}),
+        });
+        this.errors.length = Math.min(this.errors.length, 20);
+        this.event({ what: 'error', detail: `${where}: ${message}${log ? ` - see ${log}` : ''}` });
+    }
+    event(e) {
+        const row = { at: new Date().toISOString(), ...e };
+        mkdirSync(this.dir, { recursive: true });
+        appendFileSync(join(this.dir, 'events.jsonl'), `${JSON.stringify(row)}\n`);
+        this.recent.unshift(row);
+        this.recent.length = Math.min(this.recent.length, 50);
+        this.report();
+    }
+    report() {
+        try {
+            writeStatus(this);
+        }
+        catch {
+            // A status page that failed to render must not stop the tuning.
+        }
+    }
+}
+/** The real `zen`: this same binary, in its own process group so Ctrl-C reaches only us. */
+export function spawnZen(root, children) {
+    return (args, log) => new Promise((resolve) => {
+        mkdirSync(dirname(log), { recursive: true });
+        const fd = openSync(log, 'a');
+        const child = spawn(process.execPath, [process.argv[1], ...args], {
+            cwd: root,
+            stdio: ['ignore', 'pipe', fd],
+            detached: true,
+        });
+        children.add(child);
+        const dir = join(root, FINETUNE_DIR);
+        if (child.pid !== undefined) {
+            remember(dir, child.pid, process.argv[1]);
+        }
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        let finished = false;
+        const done = (code) => {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            children.delete(child);
+            if (child.pid !== undefined) {
+                forget(dir, child.pid);
+            }
+            closeSync(fd);
+            resolve({ code, stdout });
+        };
+        child.on('error', () => done(1));
+        child.on('close', (code) => done(code ?? 1));
+    });
+}
+export function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=tuning.js.map

package/dist/meta/finetune/usage.d.ts

@@ -0,0 +1,62 @@
+export interface Tokens {
+    calls: number;
+    input: number;
+    cached: number;
+    output: number;
+    reasoning: number;
+}
+export type ByModel = Record<string, Tokens>;
+export type Stage = 'run' | 'analyze' | 'apply';
+export declare const STAGES: Stage[];
+export type ByStage = Partial<Record<Stage, ByModel>>;
+export declare function mergeModels(...all: (ByModel | undefined)[]): ByModel;
+export declare function mergeStages(...all: (ByStage | undefined)[]): ByStage;
+export declare function total(by: ByModel | undefined): Tokens;
+/** Input plus output, the input counting cached tokens. */
+export declare function spent(by: ByModel | undefined): number;
+/** `vertex/gemini-3.8-flash` and `gemini-3.8-flash` are one model in a table. */
+export declare const modelName: (m: string | undefined) => string;
+export interface ModelMetrics extends Tokens {
+    /** the largest input of a single call */
+    peak: number;
+    /** time spent waiting on this model */
+    ms: number;
+}
+export interface RunMetrics {
+    models: Record<string, ModelMetrics>;
+    /** summed over every lane, so parallel branches can exceed the wall clock */
+    llmMs: number;
+    toolMs: number;
+    toolCalls: number;
+    toolErrors: number;
+    memory: {
+        recall: number;
+        load: number;
+        grep: number;
+        commit: number;
+        forget: number;
+    };
+    forks: number;
+    branches: number;
+    compactions: number;
+    handoffs: number;
+    /** the first error a sandbox tool got from the container engine, not from a command */
+    sandbox?: string;
+}
+/**
+ * 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 declare function runMetrics(runDir: string): RunMetrics | undefined;
+/** The token part of a run's metrics, per model. */
+export declare function tokensOf(m: RunMetrics): ByModel;
+export declare function runTokens(runDir: string): ByModel | undefined;
+/** One `zen meta run --json` envelope: `{ model, tokens: { calls, inputTokens, … } }`. */
+export declare function envelopeTokens(file: string): ByModel | undefined;
+/** Every envelope in `dir` named `<stem>.json` or `<stem>-<n>.json` - retries keep their own. */
+export declare function envelopesIn(dir: string, stem: string): ByModel | undefined;
+/** 1234 → 1.2k, 2184341 → 2.2M. */
+export declare function short(n: number): string;
+//# sourceMappingURL=usage.d.ts.map