@zenera/cli 1.1.25 → 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';
@@ -37,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";
@@ -123,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,
@@ -233,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

@@ -23,10 +23,15 @@ export type EventBody = {
 } | {
     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. */

package/dist/eventlog.js

@@ -6,6 +6,15 @@ 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 });
@@ -24,18 +33,23 @@ export function agentEventLog(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;
@@ -49,6 +63,11 @@ export function agentEventLog(path) {
                     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) {
@@ -103,7 +122,12 @@ export function copilotEventLog(path) {
                 }
                 case 'tool.execution_start': {
                     const args = (data.arguments ?? {});
-                    const subject = args.command ?? args.description ?? args.path ?? args.skill ?? '';
+                    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({

package/dist/liveness.js

@@ -407,7 +407,7 @@ export function probeChat(provider, id) {
  * 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;
@@ -419,8 +419,25 @@ 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;
@@ -469,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

@@ -3,7 +3,7 @@
  * 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 written.
+ * 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

@@ -1,6 +1,5 @@
-import { copyFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { copyTree, MEMORY_RULES, TEMPLATES } from "./host.js";
+import { join } from 'node:path';
+import { copyTree, TEMPLATES } from "./host.js";
 // ---------------------------------------------------------------------------
 // Telling the editor which instructions are not for it
 //
@@ -31,30 +30,14 @@ import { copyTree, MEMORY_RULES, TEMPLATES } from "./host.js";
 // `.github/` tree is: the standing brief, plus the prompt files and skills the
 // editor picks up from the same place.
 // ---------------------------------------------------------------------------
-/** The same bytes, kept in the `zen-memory` skill to restore or diff against. */
-const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', 'memory-instructions.md');
 /**
  * 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 written.
+ * none. Returns the relative paths that actually changed.
  */
 export function editorFiles(dir) {
-    const written = copyTree(join(TEMPLATES, 'editor'), dir, '', {});
-    // The one file that belongs to both trees. It is a project file first —
-    // house rules reaching every agent that can see the graph — and it is
-    // written once and edited from then on, like every other project file. But
-    // a project whose copy drifted, or that deleted it and turned memory back
-    // on later, needs somewhere to get the current text from, and the editor
-    // tree is replaced on every `init` and `open`. Copying the same bytes into
-    // the skill's references is what makes `diff` between the two mean
-    // something, and what stops a second copy of these rules existing in the
-    // repository to fall out of step with the first.
-    const reference = join(dir, MEMORY_REFERENCE);
-    mkdirSync(dirname(reference), { recursive: true });
-    copyFileSync(join(TEMPLATES, 'project', MEMORY_RULES), reference);
-    written.push(MEMORY_REFERENCE);
-    return written;
+    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

package/dist/meta/finetune/analyze-brief.js

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SHARED_RULES, validateProject } from "../host.js";
+import { cut, files, oneLine, PHASE_WORD, renderBrief, skillIndex, STEP_MAX, word, } from "./brief.js";
+import { feedbackId } from "./feedback.js";
+import { fence, rubricScore, since } from "./report.js";
+export const ANALYZE_BRIEF = [
+    { zen: (b) => ['meta', 'dataset', 'show', `${b.case.id}@${b.case.rev}`, '--json'] },
+    { sh: () => "grep -nE 'memory:|handoffs:|fork:' agents.yaml" },
+    { zen: (b) => ['inspect', 'graph', '--dir', b.run.dir, '--no-style'] },
+    { cat: (b) => [join(b.run.dir, 'meta.json'), join(b.run.dir, 'input.md')] },
+    { cat: (b) => [join(b.run.dir, 'output.md')], max: 8000 },
+    { title: 'Earlier tries of this case', fn: earlierTries },
+    // It cuts the diff itself, inside its fence.
+    {
+        title: 'What changed in agents.yaml and agents/ since the last try',
+        fn: systemDiff,
+        max: Infinity,
+    },
+    { cat: (b) => (b.recheck ? [b.recheck] : undefined) },
+    { title: 'Skills an apply made for this case, never loaded by this run', fn: missedSkills },
+    { cat: () => ['agents.yaml'] },
+    {
+        cat: (b) => files(b, 'agents/*instructions.md').filter((f) => !SHARED_RULES.includes(f)),
+    },
+    { title: 'Skills: which agent can load which, and the index', fn: skillIndex },
+    // Last: the largest, and the agent can read a left-out prompt itself.
+    { cat: (b) => files(b, 'agents/prompts/*.md'), max: 40_000 },
+];
+/** The analysis brief as markdown. */
+export async function renderAnalyzeBrief(b, log, steps = ANALYZE_BRIEF) {
+    return renderBrief(b, log, steps, [
+        `The run is \`${b.run.dir}\`, on system v${b.run.system}: the project files below are as that version had them.\n`,
+        [
+            'Where to write - both folders exist, so no `mkdir` and no `test -f`:',
+            '',
+            `- each question for \`zen inspect ask\`: \`${join(b.dir, 'ask')}/<node>-<topic>.md\``,
+            `- the feedback file: \`${join(b.dir, 'feedback.json')}\`, not written yet - write it in one call`,
+            '',
+        ].join('\n'),
+    ]);
+}
+/** Writes `brief.md` into the try's folder; the path is what `--prompt-file` takes. */
+export async function writeAnalyzeBrief(t, dir, at) {
+    mkdirSync(join(dir, 'ask'), { recursive: true });
+    const snapshot = t.system.snapshotDir(at.run.system);
+    const systemDir = existsSync(snapshot) ? snapshot : t.root;
+    let report;
+    const b = {
+        ...at,
+        t,
+        dir,
+        systemDir,
+        project: () => (report ??= validateProject({ dir: systemDir })
+            .catch(() => validateProject({ dir: t.root }))
+            .catch(() => undefined)),
+    };
+    const file = join(dir, 'brief.md');
+    writeFileSync(file, await renderAnalyzeBrief(b, join(dir, 'brief.log')));
+    return file;
+}
+// ---------------------------------------------------------------------------
+// The computed sections
+// ---------------------------------------------------------------------------
+function earlierTries(b) {
+    const decided = b.t.improvements.decisions();
+    const round = b.t.round(b.case);
+    return b.earlier
+        .filter((a) => a.feedback)
+        .map((a) => {
+        const f = a.feedback;
+        const id = feedbackId(b.case.id, a.phase, a.attempt, round);
+        const cost = a.run
+            ? `, v${a.run.system}, ${a.run.turns ?? '?'} LLM calls, ${since(a.run.durationMs ?? 0)}`
+            : '';
+        const rows = f.improvements.map((i) => {
+            const d = decided[id]?.[i.id];
+            const decision = d?.decision
+                ? `${d.decision}${d.note ? `: ${d.note}` : ''}`
+                : 'not applied yet';
+            return `| ${i.id} | ${oneLine(i.change)} | ${oneLine(i.file ?? '-')} | ${oneLine(decision)} |`;
+        });
+        return [
+            `#### ${PHASE_WORD[a.phase]}, try ${a.attempt} - ${f.verdict}, rubric ${rubricScore(f)}${f.done ? ', done' : ''}${cost}`,
+            '',
+            ...f.summary
+                .trim()
+                .split('\n')
+                .map((l) => (l.trim() ? `> ${l}` : '>')),
+            '',
+            ...(rows.length > 0
+                ? ['| # | Change | File | Decision |', '| --- | --- | --- | --- |', ...rows, '']
+                : []),
+        ].join('\n');
+    })
+        .join('\n');
+}
+function systemDiff(b) {
+    const last = [...b.earlier].reverse().find((a) => a.run);
+    if (!last?.run || last.run.system === b.run.system) {
+        return undefined;
+    }
+    const diff = b.t.system.diff(last.run.system, b.run.system).trim();
+    if (!diff) {
+        return undefined;
+    }
+    const pad = (v) => `v${String(v).padStart(2, '0')}`;
+    const { body, note } = cut(diff, STEP_MAX, `the whole diff: git -C ${word(b.t.system.dir)} diff --no-index ${pad(last.run.system)} ${pad(b.run.system)}`);
+    const tick = fence(body);
+    return [
+        `From v${last.run.system} (${PHASE_WORD[last.phase]}, try ${last.attempt}) to v${b.run.system} (this run):`,
+        '',
+        `${tick}diff`,
+        body,
+        tick,
+        ...(note ? [note] : []),
+    ].join('\n');
+}
+async function missedSkills(b) {
+    if (!b.missed?.length) {
+        return undefined;
+    }
+    const entries = (await b.project())?.skills.entries ?? [];
+    return b.missed
+        .map((name) => {
+        const s = entries.find((e) => e.name === name);
+        return `- \`${name}\`: ${s ? s.description : '(no such skill in this version)'}`;
+    })
+        .join('\n');
+}
+//# sourceMappingURL=analyze-brief.js.map

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

@@ -0,0 +1,23 @@
+import { type Brief, type Step } from './brief.ts';
+import { type Feedback } from './feedback.ts';
+import type { Deferred } from './improvements.ts';
+import { type Tuning } from './tuning.ts';
+/** One entry of inputs.json. */
+export type Request = Feedback & {
+    file: string;
+    missedSkills?: string[];
+};
+export interface ApplyBrief extends Brief {
+    dir: string;
+    attempt: number;
+    inputs: Request[];
+    deferred: Deferred[];
+}
+/** The editor skills this project's capabilities call for, each with why. */
+export declare function editorSkills(root: string, inputs: {
+    phase: string;
+}[]): [string, string][];
+export declare const APPLY_BRIEF: Step<ApplyBrief>[];
+/** Writes `brief.md` into the apply's folder, for this attempt; returns its path. */
+export declare function writeApplyBrief(t: Tuning, dir: string, attempt: number): Promise<string>;
+//# sourceMappingURL=apply-brief.d.ts.map