@zenera/cli 1.1.24 → 1.1.26

package/dist/commands/view.js

@@ -0,0 +1,114 @@
+import { existsSync, statSync } from 'node:fs';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { parse } from "../args.js";
+import { dim, json, note, usageError, write } from "../term.js";
+// ---------------------------------------------------------------------------
+// zen view - a folder in the browser, redrawn as its files change
+// ---------------------------------------------------------------------------
+const USAGE = 'zen view [path] [--port <n>] [--throttle <ms>] [--open] [--hidden]';
+const OPTIONS = {
+    port: { type: 'string' },
+    throttle: { type: 'string' },
+    open: { type: 'boolean' },
+    hidden: { type: 'boolean' },
+};
+/** Resolves when one of the signals arrives, and stops listening for them. */
+function until(signals) {
+    return new Promise((settle) => {
+        const done = () => {
+            for (const s of signals) {
+                process.off(s, done);
+            }
+            settle();
+        };
+        for (const s of signals) {
+            process.once(s, done);
+        }
+    });
+}
+/** A file inside the cwd is served from the cwd, so its links up the tree still resolve. */
+export function placeOf(cwd, target) {
+    if (statSync(target).isDirectory()) {
+        return { root: target, start: '/' };
+    }
+    const rel = relative(cwd, target);
+    const parts = rel.split(sep);
+    // A dot-folder on the way would be refused as hidden, so serve from the file's own folder.
+    const within = rel !== '' &&
+        rel !== '..' &&
+        !rel.startsWith(`..${sep}`) &&
+        !parts.slice(0, -1).some((p) => p.startsWith('.'));
+    const root = within ? cwd : dirname(target);
+    const path = within ? parts : [basename(target)];
+    return { root, start: `/${path.join('/')}` };
+}
+export const view = {
+    summary: 'Show a folder in the browser: markdown, diagrams and code, redrawn as files change.',
+    usage: USAGE,
+    details: [
+        'Serves [path] (default: here) on 127.0.0.1 until Ctrl-C and prints its address.',
+        'Markdown is drawn with its tables and mermaid diagrams; json, jsonl, python and',
+        'other code is highlighted; a directory is a listing. An open page follows its',
+        'file: when the file changes, only what changed is redrawn. Images, html and pdf',
+        'are handed to the browser as they are. Dotfiles are not served without --hidden,',
+        'and .env and .git never are.',
+        '',
+        'Options:',
+        '  --port <n>     This port. Default: one derived from the folder, so a page left',
+        '                 open reconnects after a restart; any free one if it is taken.',
+        '  --throttle <ms> Least time between two redraws of one page. Default 1000.',
+        '  --open         Open the page in the browser.',
+        '  --hidden       Serve dotfiles too.',
+        '',
+        'Examples:',
+        '  zen view',
+        '  zen view finetune/STATUS.md --open',
+    ],
+    banner: { head: 'Zenera', accent: 'View', subtitle: 'Live File Viewer', hue: 'pink' },
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, OPTIONS, USAGE);
+        if (positionals.length > 1) {
+            throw usageError('zen view takes one path', USAGE);
+        }
+        const target = resolve(ctx.cwd, positionals[0] ?? '.');
+        if (!existsSync(target)) {
+            throw usageError(`no such file or directory: ${target}`);
+        }
+        let port;
+        if (values.port !== undefined) {
+            port = Number(values.port);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                throw usageError('--port takes a port number', `got "${values.port}"`);
+            }
+        }
+        let throttleMs;
+        if (values.throttle !== undefined) {
+            throttleMs = Number(values.throttle);
+            if (!Number.isInteger(throttleMs) || throttleMs < 0) {
+                throw usageError('--throttle takes milliseconds', `got "${values.throttle}"`);
+            }
+        }
+        const { root, start } = placeOf(ctx.cwd, target);
+        const { openBrowser, serveView } = await import('@zenera/view');
+        const server = await serveView({
+            root,
+            start,
+            hidden: values.hidden ?? false,
+            ...(port !== undefined ? { port } : {}),
+            ...(throttleMs !== undefined ? { throttleMs } : {}),
+        });
+        if (ctx.json) {
+            json({ url: server.url, root: server.root, port: server.port });
+        }
+        else {
+            write(server.url);
+            note(dim(`serving ${server.root} · Ctrl-C stops it`));
+        }
+        if (values.open) {
+            openBrowser(server.url);
+        }
+        await until(['SIGINT', 'SIGTERM']);
+        await server.close();
+    },
+};
+//# sourceMappingURL=view.js.map

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import { AgentRunner, type AgentEvent, type AgentProject, type AgentState, type Input, type RunResult } from '@zenera/neo';
+import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type RunResult } from '@zenera/neo';
 import { type Project } from './projects.ts';
 import { type SandboxSetup } from './sandbox.ts';
 import { type Held, type RunPaths, type SessionPaths } from './session.ts';
@@ -24,6 +24,11 @@ export interface EngineOptions {
      * complaint is a worse report than one.
      */
     quiet?: boolean;
+    /**
+     * The session will never be resumed, so its containers are removed on close
+     * whatever `persist:` says. A stopped one would only hold an engine lock.
+     */
+    disposable?: boolean;
 }
 export interface Engine {
     project: AgentProject;
@@ -32,6 +37,8 @@ export interface Engine {
     workspace: string;
     /** where the workspace appears inside the container */
     workspaceMount: string;
+    /** every tree the file tools reach, and the names they reach them by */
+    files: Workspace;
     /** whether the agent was denied every writing tool */
     readOnly: boolean;
     session: SessionPaths;

package/dist/engine.js

@@ -2,6 +2,7 @@ import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace,
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { auditModels, describeIssue } from "./audit.js";
 import { loadProjectEnv } from "./env.js";
 import { readJson, writeJson } from "./home.js";
@@ -64,6 +65,7 @@ export async function open(opts) {
             keys: opts.keys,
             env: env?.names,
             mounts,
+            ...(opts.disposable ? { persist: false } : {}),
         });
         const workspaceOptions = {
             root: workspace,
@@ -122,6 +124,7 @@ export async function open(opts) {
         name: opts.project.name,
         workspace,
         workspaceMount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+        files,
         readOnly: Boolean(opts.readOnly),
         session: opts.session,
         memory,
@@ -232,6 +235,10 @@ async function record(engine, input, result, startedAt, durationMs) {
             title: `${engine.name} · ${run.id}`,
             architecture: await engine.runner.describe(),
             memory: engine.runner.services.memory?.store,
+            mounts: [
+                { at: engine.workspaceMount, href: pathToFileURL(engine.files.root).href },
+                ...engine.files.mounts.map((m) => ({ at: m.at, href: pathToFileURL(m.host).href })),
+            ],
         });
         await writeFile(run.report, renderReportHtml(built), 'utf8');
         report = run.report;

package/dist/eventlog.d.ts

@@ -0,0 +1,64 @@
+import { type AgentEvent } from '@zenera/neo';
+export type EventBody = {
+    type: 'llm';
+    model: string;
+    in: number;
+    cached: number;
+    out: number;
+    reasoning: number;
+    ms?: number;
+} | {
+    type: 'tool';
+    phase: 'start';
+    id: string;
+    name: string;
+    subject: string;
+} | {
+    type: 'tool';
+    phase: 'end';
+    id: string;
+    name: string;
+    ok: boolean;
+    ms?: number;
+} | {
+    type: 'say';
+    text: string;
+} | {
+    type: 'think';
+    text: string;
+};
+export type EventLine = EventBody & {
+    t: string;
+};
+/** A thought summary's last `**heading**`, else its first sentence. */
+export declare function heading(thinking: string): string;
+/** A line that cannot be written is dropped: watching a run must not break it. */
+export declare function eventLog(path: string): (body: EventBody) => void;
+/** For `zen run`: the runtime's own events, folded to the shared lines. */
+export declare function agentEventLog(path: string): (event: AgentEvent) => void;
+/** One line of copilot's JSONL, as much of it as is read here. */
+export interface CopilotEvent {
+    type: string;
+    data?: Record<string, unknown>;
+}
+/** A model call read off copilot's span file - see `meta/tokens.ts`. */
+export interface CopilotCall {
+    model: string;
+    usage: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+        reasoningTokens: number;
+    };
+    durationMs: number;
+}
+/**
+ * For `zen meta run`: copilot's events and spans, folded to the same lines.
+ * Its JSONL has no token counts, so `llm` lines come from the spans instead,
+ * about a second after each call.
+ */
+export declare function copilotEventLog(path: string): {
+    event: (event: CopilotEvent) => void;
+    call: (call: CopilotCall) => void;
+};
+//# sourceMappingURL=eventlog.d.ts.map

package/dist/eventlog.js

@@ -0,0 +1,170 @@
+import { isCheckpoint } from '@zenera/neo';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+const MAX_TEXT = 400;
+const clip = (text) => {
+    const one = text.replace(/\s+/g, ' ').trim();
+    return one.length > MAX_TEXT ? `${one.slice(0, MAX_TEXT - 1)}…` : one;
+};
+/** A thought summary's last `**heading**`, else its first sentence. */
+export function heading(thinking) {
+    const bold = [...thinking.matchAll(/\*\*([^*\n]+)\*\*/g)].at(-1)?.[1];
+    if (bold) {
+        return clip(bold);
+    }
+    const one = clip(thinking);
+    return one.match(/^.+?[.!?](?=\s|$)/)?.[0] ?? one;
+}
+/** A line that cannot be written is dropped: watching a run must not break it. */
+export function eventLog(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    return (body) => {
+        try {
+            appendFileSync(path, `${JSON.stringify({ t: new Date().toISOString(), ...body })}\n`);
+        }
+        catch {
+            // See above.
+        }
+    };
+}
+/** For `zen run`: the runtime's own events, folded to the shared lines. */
+export function agentEventLog(path) {
+    const write = eventLog(path);
+    // Keyed by branch, since a fork has several model calls open at once.
+    const began = new Map();
+    const said = new Map();
+    const thought = new Map();
+    return (event) => {
+        const key = event.branch?.name ?? '';
+        if (!isCheckpoint(event)) {
+            if (event.type === 'text_delta') {
+                said.set(key, (said.get(key) ?? '') + event.delta);
+            }
+            else if (event.type === 'thinking_delta') {
+                thought.set(key, (thought.get(key) ?? '') + event.delta);
+            }
+            return;
+        }
+        switch (event.type) {
+            case 'before_llm_call':
+                began.set(key, Date.now());
+                said.delete(key);
+                thought.delete(key);
+                break;
+            case 'after_llm_call': {
+                const u = event.node.usage;
+                const at = began.get(key);
+                write({
+                    type: 'llm',
+                    model: event.node.model,
+                    in: u.inputTokens,
+                    cached: u.cachedInputTokens ?? 0,
+                    out: u.outputTokens,
+                    reasoning: u.reasoningTokens ?? 0,
+                    ...(at !== undefined ? { ms: Date.now() - at } : {}),
+                });
+                const thinking = thought.get(key)?.trim();
+                thought.delete(key);
+                if (thinking) {
+                    write({ type: 'think', text: heading(thinking) });
+                }
+                const text = said.get(key)?.trim();
+                said.delete(key);
+                if (text) {
+                    write({ type: 'say', text: clip(text) });
+                }
+                break;
+            }
+            case 'before_tool_call':
+                write({
+                    type: 'tool',
+                    phase: 'start',
+                    id: event.call.callId,
+                    name: event.call.name,
+                    subject: clip(event.call.args.preview ?? ''),
+                });
+                break;
+            case 'after_tool_call':
+                write({
+                    type: 'tool',
+                    phase: 'end',
+                    id: event.node.callId,
+                    name: event.node.name,
+                    ok: !event.node.isError,
+                    ...(event.node.durationMs !== undefined ? { ms: event.node.durationMs } : {}),
+                });
+                break;
+            default:
+                break;
+        }
+    };
+}
+/**
+ * For `zen meta run`: copilot's events and spans, folded to the same lines.
+ * Its JSONL has no token counts, so `llm` lines come from the spans instead,
+ * about a second after each call.
+ */
+export function copilotEventLog(path) {
+    const write = eventLog(path);
+    // Its completion names no tool, so the start is remembered by call id.
+    const began = new Map();
+    return {
+        event: (event) => {
+            const data = event.data ?? {};
+            const id = String(data.toolCallId ?? '');
+            switch (event.type) {
+                case 'assistant.message': {
+                    const text = String(data.content ?? '').trim();
+                    if (text) {
+                        write({ type: 'say', text: clip(text) });
+                    }
+                    break;
+                }
+                case 'tool.execution_start': {
+                    const args = (data.arguments ?? {});
+                    const subject = args.command ??
+                        args.description ??
+                        args.path ??
+                        args.skill ??
+                        args.pattern ??
+                        '';
+                    const name = String(data.toolName ?? 'tool');
+                    began.set(id, { at: Date.now(), name });
+                    write({
+                        type: 'tool',
+                        phase: 'start',
+                        id,
+                        name,
+                        subject: clip(typeof subject === 'string' ? subject : JSON.stringify(subject)),
+                    });
+                    break;
+                }
+                case 'tool.execution_complete': {
+                    const start = began.get(id);
+                    began.delete(id);
+                    write({
+                        type: 'tool',
+                        phase: 'end',
+                        id,
+                        name: start?.name ?? String(data.toolName ?? 'tool'),
+                        ok: data.success !== false,
+                        ...(start ? { ms: Date.now() - start.at } : {}),
+                    });
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+        call: (call) => write({
+            type: 'llm',
+            model: call.model,
+            in: call.usage.inputTokens,
+            cached: call.usage.cachedInputTokens,
+            out: call.usage.outputTokens,
+            reasoning: call.usage.reasoningTokens,
+            ms: call.durationMs,
+        }),
+    };
+}
+//# sourceMappingURL=eventlog.js.map

package/dist/liveness.d.ts

@@ -54,6 +54,13 @@ export interface ModelProbe {
     /** embeddings only: the width the model actually returned */
     dimensions?: number;
 }
+/**
+ * A chat model sized for a probe: 16 output tokens is enough for "ok", and
+ * Anthropic requires a cap at all. Only the adapters that read `maxTokens` are
+ * given one — the registry refuses a knob its adapter would never send, and the
+ * OpenAI adapters have no such knob.
+ */
+export declare function probeChat(provider: string, id: string): Model;
 export declare function probeModel(target: ModelTarget): Promise<ModelProbe>;
 /**
  * One round trip per model, run together — they are independent questions, and

package/dist/liveness.js

@@ -1,4 +1,4 @@
-import { EXA_BASE_URL, isUnfunded, ModelRegistry, text, } from '@zenera/neo';
+import { createModel, EXA_BASE_URL, isUnfunded, ModelRegistry, text, vertexRoute, } from '@zenera/neo';
 import { envOf, SHAPES, } from "./keys.js";
 // ---------------------------------------------------------------------------
 // Liveness
@@ -389,6 +389,17 @@ const UNSERVED = [
     'no access',
 ];
 const targetId = (target) => target.kind === 'model' ? target.model.id : target.embedder.id;
+/**
+ * A chat model sized for a probe: 16 output tokens is enough for "ok", and
+ * Anthropic requires a cap at all. Only the adapters that read `maxTokens` are
+ * given one — the registry refuses a knob its adapter would never send, and the
+ * OpenAI adapters have no such knob.
+ */
+export function probeChat(provider, id) {
+    const capped = { provider, model: id, maxTokens: 16 };
+    const unread = new ModelRegistry().knobs(capped).some((k) => k.knob === 'maxTokens');
+    return createModel(unread ? { provider, model: id } : capped);
+}
 /**
  * Refused by the provider, unreachable, or served.
  *
@@ -396,7 +407,7 @@ const targetId = (target) => target.kind === 'model' ? target.model.id : target.
  * accepted and the id was the thing refused, so the fix is another model rather
  * than another key. `dead` is left to mean the credential itself was rejected.
  */
-function classifyModel(err, target) {
+function classifyModel(err, target, ms) {
     const at = new Date().toISOString();
     const message = err instanceof Error ? err.message : String(err);
     const e = err;
@@ -408,11 +419,31 @@ function classifyModel(err, target) {
         return { state: 'blocked', at, detail: firstLine(message), fix: instead(target) };
     }
     const check = classify(err);
+    // classify() calls a 429 a live key; for a model it means nothing answered.
+    if (check.state === 'live') {
+        const said = err.detail;
+        return {
+            state: 'unknown',
+            at,
+            detail: `rate limited after ${(ms / 1000).toFixed(1)}s of retries: ${typeof said === 'string' ? said : firstLine(message)}`,
+            fix: limited(target),
+        };
+    }
     return check.state === 'blocked' && !check.fix ? { ...check, fix: instead(target) } : check;
 }
+function limited(target) {
+    const blame = "the key and the model id are fine, the provider's rate limit is not";
+    if (target.ref.endsWith(':free')) {
+        return `${blame} — free models share a small upstream quota; retry later, or test the paid id: zen models test ${target.ref.slice(0, -':free'.length)}`;
+    }
+    return `${blame} — retry later`;
+}
 /** The command that finds something this account can actually use. */
 function instead(target) {
     const provider = target.ref.includes(':') ? target.ref.split(':')[0] : undefined;
+    if (provider === 'vertex' && vertexRoute(targetId(target)) !== 'gemini') {
+        return 'enable it for this project in Model Garden: https://console.cloud.google.com/vertex-ai/model-garden';
+    }
     return provider
         ? `zen models ls ${provider}`
         : `zen models pick --${target.kind === 'embedding' ? 'embedding' : 'chat'}`;
@@ -455,7 +486,8 @@ export async function probeModel(target) {
         };
     }
     catch (err) {
-        return { ...common, check: classifyModel(err, target), ms: Date.now() - started };
+        const ms = Date.now() - started;
+        return { ...common, check: classifyModel(err, target, ms), ms };
     }
 }
 /**

package/dist/meta/editor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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,
+ * and they describe the file formats of the version of `zen` in hand, so the
+ * current answer is the only one worth having and a stale one is worse than
+ * none. Returns the relative paths that actually changed.
+ */
+export declare function editorFiles(dir: string): string[];
+//# sourceMappingURL=editor.d.ts.map

package/dist/meta/editor.js

@@ -0,0 +1,43 @@
+import { join } from 'node:path';
+import { copyTree, TEMPLATES } from "./host.js";
+// ---------------------------------------------------------------------------
+// Telling the editor which instructions are not for it
+//
+// The project's house rules are `agents/instructions.md`, deliberately not
+// `AGENTS.md`: every coding assistant now reads that name out of an open
+// folder and feeds it to itself as always-on instructions, and `zen open`
+// opens exactly this directory. A name nobody else claims means the two are
+// never confused, and `chat.useAgentsMdFile` no longer has to be switched off
+// to keep them apart.
+//
+// They sit under `agents/` because there is rarely only one of them. Anything
+// named `agents/<topic>-instructions.md` is read too, in filename order, so a
+// subject that is true for every agent but is about one capability — memory,
+// say — gets its own document instead of another section in a file that keeps
+// growing.
+//
+// `chat.useNestedAgentsMdFiles` is still written. It is already false by
+// default, but it is opt-in globally, and this is a directory the agent itself
+// writes into — someone who turned it on would otherwise have the editor pick
+// up whatever `AGENTS.md` a run happened to leave behind. It is a *restricted*
+// setting, so it applies only in a trusted workspace; that is the right way
+// round, since an untrusted folder is not one to run agents in either.
+//
+// `agents/instructions.md` addresses the *project's* agents. The editor's
+// assistant still needs a brief of its own, and what it needs to know is how
+// this kind of project is put together — the file formats, how a prompt is
+// written, when to add a skill rather than an agent. That is what the
+// `.github/` tree is: the standing brief, plus the prompt files and skills the
+// editor picks up from the same place.
+// ---------------------------------------------------------------------------
+/**
+ * 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,
+ * and they describe the file formats of the version of `zen` in hand, so the
+ * current answer is the only one worth having and a stale one is worse than
+ * none. Returns the relative paths that actually changed.
+ */
+export function editorFiles(dir) {
+    return copyTree(join(TEMPLATES, 'editor'), dir, '', {});
+}
+//# sourceMappingURL=editor.js.map

package/dist/meta/finetune/analyze-brief.d.ts

@@ -0,0 +1,26 @@
+import { type Brief, type Step } from './brief.ts';
+import type { Case } from './dataset/types.ts';
+import { type Phase } from './feedback.ts';
+import { type Attempt } from './report.ts';
+import type { Run } from './train.ts';
+import type { Tuning } from './tuning.ts';
+export interface AnalyzeBrief extends Brief {
+    run: Run;
+    case: Case;
+    phase: Phase;
+    attempt: number;
+    /** earlier tries of this case revision, oldest first */
+    earlier: Attempt[];
+    /** the patch a recheck checks */
+    recheck?: string;
+    /** skills an apply made for this case that the run never loaded */
+    missed?: string[];
+    /** the try's folder: brief.md, feedback.json and ask/ live here */
+    dir: string;
+}
+export declare const ANALYZE_BRIEF: Step<AnalyzeBrief>[];
+/** The analysis brief as markdown. */
+export declare function renderAnalyzeBrief(b: AnalyzeBrief, log: string, steps?: Step<AnalyzeBrief>[]): Promise<string>;
+/** Writes `brief.md` into the try's folder; the path is what `--prompt-file` takes. */
+export declare function writeAnalyzeBrief(t: Tuning, dir: string, at: Omit<AnalyzeBrief, 't' | 'systemDir' | 'project' | 'dir'>): Promise<string>;
+//# sourceMappingURL=analyze-brief.d.ts.map