@zenera/cli 1.1.24 → 1.1.26

package/dist/commands/meta.js

@@ -1,16 +1,60 @@
-import { createModel, readProjectConfig } from '@zenera/neo';
+import { readProjectConfig } from '@zenera/neo';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { parse } from "../args.js";
 import { loadProjectEnv } from "../env.js";
+import { copilotEventLog } from "../eventlog.js";
 import { ensureHome } from "../home.js";
 import { assertOwner, KeyStore, PROVIDERS } from "../keys.js";
-import { probeModel } from "../liveness.js";
-import { answerBox, chooseModel, defaultRef, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, RECOMMENDED, SOURCE_LABELS, splitRef, wire, writeMeta, } from "../meta.js";
+import { probeChat, probeModel } from "../liveness.js";
+import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, RECOMMENDED, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, writeMeta, } from "../meta/index.js";
+import { splitRef } from "../modelref.js";
+import { duration } from "../narrate.js";
 import * as Projects from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
-import { editorFiles } from "../scaffold.js";
 import { bold, choose, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, readStdin, table, usageError, warn, write, writeAll, } from "../term.js";
+import { appendUsage, LEDGER_ENV, ledgerPath, META_PROMPT_ENV, META_SESSION_ENV, } from "../usage.js";
 const USAGE = 'zen meta run [project] [prompt] [options]';
-const VERBS = new Set(['model', 'run', 'prompts']);
+const VERBS = new Set(['model', 'run', 'prompts', 'resume', 'dataset', 'finetune']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A copilot session id, or the 7+ hex prefix of one it also accepts. */
+const SESSION_ID = /^[0-9a-f]{7,}(?:-[0-9a-f]+)*$/i;
+/** Verbs that own their flags and their help page. */
+const SUBCOMMANDS = {
+    dataset: {
+        run: runDataset,
+        projectFlag: datasetProjectFlag,
+        page: { usage: DATASET_USAGE, summary: DATASET_SUMMARY, details: DATASET_DETAILS },
+    },
+    finetune: {
+        run: runFinetune,
+        projectFlag: finetuneProjectFlag,
+        page: { usage: FINETUNE_USAGE, summary: FINETUNE_SUMMARY, details: FINETUNE_DETAILS },
+    },
+};
+/** `zen meta dataset ...` or `zen meta acme dataset ...`: which one, and where its own args start. */
+function subcommand(args) {
+    for (const name of Object.keys(SUBCOMMANDS)) {
+        if (args[0] === name) {
+            return { name, at: 0 };
+        }
+        if (args[1] === name && !args[0]?.startsWith('-')) {
+            return { name, at: 1 };
+        }
+    }
+    return undefined;
+}
+function page(p) {
+    write(bold(p.usage));
+    write(`\n  ${p.summary}`);
+    write('');
+    for (const line of p.details) {
+        write(line ? `  ${line}` : '');
+    }
+}
 export const meta = {
     summary: 'Run the meta agent over this project, on your own keys.',
     usage: USAGE,
@@ -21,9 +65,13 @@ export const meta = {
         '  zen meta run [project] /<name> [words]   run a stored prompt',
         '  zen meta run [project]                   pick one of its stored prompts',
         '  zen meta prompts [project]               list the stored prompts',
+        '  zen meta resume [project] [session]      carry on a run that stopped',
         '  zen meta model [ref]                     show or set the model it uses',
+        '  zen meta dataset <verb>                  the cases it tunes against',
+        '  zen meta finetune <verb>                 tune the project on those cases',
         '',
         'The project may come before the verb instead: `zen meta acme run`.',
+        '`zen meta dataset --help` and `zen meta finetune --help` have their own pages.',
         '',
         'Arguments:',
         '  [project]   Name of a project. Default: the one you are in.',
@@ -35,14 +83,21 @@ export const meta = {
         '  --project <name|dir>   Which project to work in. The agent is rooted there.',
         '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
         '  --provider <name>      Force the key to use. Default: the model ref says.',
+        '  --prompt-file <file>   Append this file to the prompt, after any words.',
         '  --agent <name>         A .github/agents/<name>.agent.md.',
         '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
         '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
         '  --ask                  Have it ask before each tool. Default: it does not.',
         '  --add-dir <dir>        Another directory it may touch. Repeatable.',
         '  --resume <id>          Continue a copilot session. --continue takes the last.',
+        '  --session-id <uuid>    Start a new session under this id. Default: a random one.',
+        `  --retries <n>          Resume after a rate limit or outage. Default ${DEFAULT_RESUMES}, 0 = off.`,
         '  --share <file>         Write the transcript to a markdown file.',
+        '  --events <file>        Append what the agent does to this file as it does it:',
+        '                         one JSON line per model call, tool call and message.',
         '  --dry-run              Print what would run, secrets masked, and stop.',
+        '  --no-refresh           Leave the editor files as they are (parallel runs).',
+        '  --json                 Print one object: answer, answerFile, sessionId, exitCode, tokens.',
         '',
         'It always uses your own keys — `zen key add` — and never a coding-agent',
         'subscription. The answer goes to stdout and the progress to stderr, so',
@@ -53,6 +108,13 @@ export const meta = {
         'watching to answer. Narrow it with --allow-tool, or restore the asking',
         'with --ask.',
         '',
+        '`zen meta resume` picks up the last session the project ran - or the one',
+        'named - where it stopped. A run that ends any way but success prints it.',
+        '',
+        'Its tokens are counted as it runs and summed when it ends. In a project with',
+        'a finetune/, every call - and every zen run and inspect ask it makes - is',
+        'appended to finetune/usage/ledger.jsonl, and finetune/USAGE.md is rewritten.',
+        '',
         'Nothing it needs is put on a command line: every credential reaches it',
         'through the environment, where other processes cannot read it.',
         '',
@@ -75,22 +137,43 @@ export const meta = {
         '  zen meta prompts',
         '  zen meta run /project-review',
         '  zen meta run acme /spec-sync-project agents/triage.md',
+        '  zen meta run acme /analyze --json',
+        '  zen meta resume acme',
         '  git diff | zen meta run "what broke?" --allow-tool read',
         '  zen meta model vertex/gemini-3.8-flash',
         '  zen meta model --pick',
         '  zen meta run --dry-run "hello"',
     ],
+    help: (ctx) => {
+        const sub = subcommand(ctx.args);
+        page(sub ? SUBCOMMANDS[sub.name].page : { ...meta, details: meta.details ?? [] });
+    },
     run: async (ctx) => {
+        // These own their flags, so they are routed before the meta agent's are parsed.
+        const sub = subcommand(ctx.args);
+        if (sub) {
+            const { run, projectFlag } = SUBCOMMANDS[sub.name];
+            const args = ctx.args.slice(sub.at + 1);
+            const found = await resolveProject({
+                cwd: ctx.cwd,
+                project: projectFlag(args) ?? (sub.at === 1 ? ctx.args[0] : undefined),
+            });
+            return await run({ args, json: ctx.json, cwd: ctx.cwd }, found);
+        }
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
             provider: { type: 'string' },
             model: { type: 'string' },
             prompt: { type: 'string', short: 'p' },
+            'prompt-file': { type: 'string' },
             agent: { type: 'string' },
             effort: { type: 'string' },
             share: { type: 'string' },
+            events: { type: 'string' },
             resume: { type: 'string' },
             continue: { type: 'boolean' },
+            'session-id': { type: 'string' },
+            retries: { type: 'string' },
             'allow-all': { type: 'boolean' },
             'allow-tool': { type: 'string' },
             ask: { type: 'boolean' },
@@ -100,6 +183,7 @@ export const meta = {
             pick: { type: 'boolean' },
             clear: { type: 'boolean' },
             force: { type: 'boolean' },
+            'no-refresh': { type: 'boolean' },
         }, USAGE);
         // `zen meta acme run` is typed at least as often as `zen meta run acme`,
         // and read literally it asks the agent the one-word question "run" —
@@ -126,6 +210,9 @@ export const meta = {
         if (verb === 'prompts') {
             return await prompts(ctx, values, args);
         }
+        if (verb === 'resume') {
+            return await resumeRun(ctx, values, args);
+        }
         throw usageError(first === undefined ? 'nothing to run' : 'a prompt goes through `run`', `try: zen meta run ${positionals.map(requote).join(' ') || '"what does this project do?"'}`);
     },
 };
@@ -158,7 +245,9 @@ async function where(ctx, flag, positionals) {
 function refresh(project) {
     try {
         const written = editorFiles(project.dir);
-        note(dim(`refreshed ${written.length} editor files in ${project.name}`));
+        if (written.length) {
+            note(dim(`refreshed ${written.length} editor files in ${project.name}`));
+        }
     }
     catch (err) {
         warn(`could not refresh the editor files — ${err.message}`);
@@ -191,11 +280,13 @@ async function stored(ctx, values, args) {
         rest = args;
     }
     const { project } = await where(ctx, values.project, head);
-    refresh(project);
+    if (!values['no-refresh']) {
+        refresh(project);
+    }
     if (name) {
         return await runPrompt(ctx, values, project, name, rest);
     }
-    const question = (values.prompt ?? rest.join(' ')).trim() || (await readStdin());
+    const question = withFile(values, (values.prompt ?? rest.join(' ')).trim()) || (await readStdin());
     if (question) {
         return await go(ctx, values, project, question);
     }
@@ -207,8 +298,23 @@ async function runPrompt(ctx, values, project, name, extra) {
     if (found.description) {
         note(dim(found.description));
     }
-    const prompt = extra.length > 0 ? `${found.body}\n\n${extra.join(' ')}` : found.body;
-    await go(ctx, values, project, prompt);
+    const prompt = withFile(values, extra.length > 0 ? `${found.body}\n\n${extra.join(' ')}` : found.body);
+    await go(ctx, values, project, prompt, name.replace(/^\//, ''));
+}
+/** The prompt with `--prompt-file` after it: text too long, or too awkward to quote, for a word. */
+function withFile(values, prompt) {
+    const file = values['prompt-file'];
+    if (!file) {
+        return prompt;
+    }
+    let text;
+    try {
+        text = readFileSync(resolve(file), 'utf8').trim();
+    }
+    catch {
+        throw usageError(`no prompt file at ${file}`, 'name a file that exists');
+    }
+    return [prompt, text].filter(Boolean).join('\n\n');
 }
 async function pickPrompt(ctx, project) {
     const names = await listPrompts(project.dir);
@@ -243,9 +349,40 @@ async function prompts(ctx, values, args) {
     note(dim(`run one: zen meta run /${found[0].name}`));
 }
 // ---------------------------------------------------------------------------
+// zen meta resume [project] [session id] [words...]
+//
+// A long run stops for reasons nobody chose - a refused request, a closed
+// laptop, Ctrl-C. Copilot keeps the session; this hands it back, by default the
+// last one the project ran, with the words (or a plain "continue") as the turn.
+// ---------------------------------------------------------------------------
+async function resumeRun(ctx, values, args) {
+    const { project, rest } = await where(ctx, values.project, args);
+    const named = rest[0] !== undefined && SESSION_ID.test(rest[0]) ? rest[0] : undefined;
+    const words = named ? rest.slice(1) : rest;
+    const session = named ?? values.resume ?? lastSession(project.dir);
+    if (!session) {
+        throw usageError(`no meta session recorded in ${project.name}`, `name one: zen meta resume ${project.name} <session id>`);
+    }
+    note(dim(`resuming session ${session}`));
+    if (!values['no-refresh']) {
+        refresh(project);
+    }
+    const message = withFile(values, (values.prompt ?? words.join(' ')).trim()) || RESUME_PROMPT;
+    await go(ctx, { ...values, resume: session, continue: false }, project, message);
+}
+// ---------------------------------------------------------------------------
 // The run itself
 // ---------------------------------------------------------------------------
-async function go(ctx, values, project, prompt) {
+async function go(ctx, values, project, prompt, promptName) {
+    const fresh = values['session-id'];
+    if (fresh !== undefined) {
+        if (values.resume || values.continue) {
+            throw usageError('--session-id starts a new session', 'drop --resume / --continue');
+        }
+        if (!UUID.test(fresh)) {
+            throw usageError(`--session-id must be a UUID, not ${fresh}`, 'try: uuidgen');
+        }
+    }
     const shell = process.env[MODEL_ENV];
     loadProjectEnv(project.dir);
     ensureHome();
@@ -280,7 +417,19 @@ async function go(ctx, values, project, prompt) {
     }
     const wiring = wire(store, entry, id);
     const binary = locate();
-    const args = argv(values, project.dir, prompt, wiring.secret);
+    // Copilot cannot carry a session to another model: the resume fails on the first call.
+    const ran = values.resume ? sessionModel(values.resume) : undefined;
+    if (values.resume && ran && !sameModel(ran, wiring.model)) {
+        if (prompt === RESUME_PROMPT) {
+            throw usageError(`session ${values.resume} ran on ${ran}, and the meta model is now ${wiring.model} - copilot cannot carry a session to another model`, `switch back for it: zen meta model ${owner}/${ran.replace(/^.*\//, '')} - or ask again, which starts a new session`);
+        }
+        warn(`session ${values.resume} ran on ${ran}; the meta model is now ${wiring.model}, so this starts a new session`);
+        values = { ...values, resume: undefined };
+    }
+    // Named up front, so a run killed before copilot reports its id can still be resumed.
+    let session = values.resume ?? (values.continue ? undefined : (fresh ?? randomUUID()));
+    const args = argv(values, project.dir, prompt, wiring.secret, session);
+    const retries = count(values.retries, '--retries') ?? DEFAULT_RESUMES;
     if (values['dry-run']) {
         const lines = masked(wiring.env, wiring.secret);
         if (ctx.json) {
@@ -310,33 +459,112 @@ async function go(ctx, values, project, prompt) {
         note(dim('set another: zen meta model <provider>/<id>'));
     }
     note(cyan(`${owner} · ${wiring.model} · ${project.name}`));
-    const log = openLog(project.dir);
+    const log = openLog(project.dir, new Date(), session);
     note(`log  ${log.path}`);
     const elided = args.map((a, i) => (args[i - 1] === '-p' ? '<prompt>' : a));
     log.line(`zen meta ${new Date().toISOString()}`);
     log.line(`project ${project.name} ${project.dir}`);
     log.line(`model   ${chosen.ref} from ${SOURCE_LABELS[chosen.from]}`);
     log.line(`command ${[binary.command, ...binary.args, ...elided].join(' ')}`);
+    if (session) {
+        recordSession(project.dir, session);
+        log.line(`session ${session}`);
+    }
+    const relay = wiring.relay ? await startVertexRelay(wiring.relay) : undefined;
+    if (relay) {
+        wiring.env.COPILOT_PROVIDER_BASE_URL = relay.url;
+        log.line(`relay   ${relay.url} -> vertex rawPredict`);
+    }
     log.line('');
     log.line('--- prompt ---');
     log.line(prompt);
     log.line('');
     log.line('--- run ---');
+    const resumeHint = () => session ? `resume it: zen meta resume ${project.name} ${session}` : undefined;
+    // Every zen command the agent runs inherits these, so a batch it starts or
+    // an ask it makes lands in the same ledger, tagged with this session.
+    const spans = log.path.replace(/\.log$/, '.otel.jsonl');
+    const ledger = ledgerPath(project.dir);
+    const env = {
+        ...wiring.env,
+        COPILOT_OTEL_FILE_EXPORTER_PATH: spans,
+        ...(ledger ? { [LEDGER_ENV]: ledger } : {}),
+        ...(session ? { [META_SESSION_ENV]: session } : {}),
+        ...(promptName ? { [META_PROMPT_ENV]: promptName } : {}),
+    };
+    const tally = new Tally();
+    const record = values.events ? copilotEventLog(resolve(ctx.cwd, values.events)) : undefined;
+    const tail = tailSpans(spans, (call) => {
+        tally.add(call);
+        record?.call(call);
+        appendUsage(project.dir, {
+            kind: 'meta.call',
+            ts: new Date(Date.parse(call.startedAt) + call.durationMs).toISOString(),
+            ...call,
+            session: call.session ?? session,
+        });
+    });
+    const reporter = usageReporter(project.dir);
+    const tokens = () => {
+        tail.stop();
+        return tally.toString();
+    };
     // A run that dies still has to leave a readable file behind.
     try {
-        const outcome = await launch({
-            binary,
-            args,
-            env: wiring.env,
-            cwd: project.dir,
-            log,
-        });
+        let resumes = 0;
+        const run = async (argList) => {
+            const launchedAt = new Date();
+            const outcome = await launch({
+                binary,
+                args: argList,
+                env,
+                cwd: project.dir,
+                log,
+                sink: ctx.json ? terminalSink : undefined,
+                onEvent: record?.event,
+                status: () => (tally.calls > 0 ? tally.toString() : ''),
+            });
+            if (outcome.sessionId && outcome.sessionId !== session) {
+                session = outcome.sessionId;
+                recordSession(project.dir, session);
+            }
+            const models = session ? sessionTotals(session) : undefined;
+            if (session && models) {
+                appendUsage(project.dir, {
+                    kind: 'meta.session',
+                    ts: new Date().toISOString(),
+                    session,
+                    models,
+                    exitCode: outcome.exitCode,
+                    resumes,
+                    startedAt: launchedAt.toISOString(),
+                    durationMs: Date.now() - launchedAt.getTime(),
+                });
+            }
+            return outcome;
+        };
+        let outcome = await run(args);
+        for (let reason = transient(outcome); reason && resumes < retries;) {
+            const wait = resumeDelayMs(resumes);
+            resumes += 1;
+            const said = `${reason}: resuming in ${duration(wait)} (${resumes}/${retries})`;
+            warn(said);
+            log.line('');
+            log.line(`--- resume ${resumes}: ${said} ---`);
+            await pause(wait, resumeHint());
+            const again = { ...values, resume: session, continue: false };
+            outcome = await run(argv(again, project.dir, RESUME_PROMPT, wiring.secret));
+            reason = transient(outcome);
+        }
         log.line('');
         log.line('--- answer ---');
         log.line(outcome.answer);
         if (outcome.answer) {
             log.saveAnswer(outcome.answer);
         }
+        const spent = tokens();
+        log.line('');
+        log.line(`tokens  ${spent}`);
         if (ctx.json) {
             json({
                 project: project.dir,
@@ -344,7 +572,9 @@ async function go(ctx, values, project, prompt) {
                 model: chosen.ref,
                 sessionId: outcome.sessionId,
                 exitCode: outcome.exitCode,
+                resumes,
                 usage: outcome.usage,
+                tokens: { calls: tally.calls, ...tally.usage },
                 answer: outcome.answer,
                 answerFile: outcome.answer ? log.answerPath : undefined,
             });
@@ -355,16 +585,82 @@ async function go(ctx, values, project, prompt) {
             // have read enough to want it in an editor.
             note(cyan(log.answerPath));
         }
+        if (!ctx.json && tally.calls > 0) {
+            note(dim(`tokens  ${spent}`));
+        }
         if (outcome.exitCode !== 0) {
-            throw new CliError(`the meta agent exited ${outcome.exitCode}`, EXIT.failed, binary.from === 'npx' ? 'install it: npm i -g @github/copilot' : undefined);
+            throw new CliError(`the meta agent exited ${outcome.exitCode}`, EXIT.failed, resumeHint() ??
+                (binary.from === 'npx' ? 'install it: npm i -g @github/copilot' : undefined));
+        }
+    }
+    catch (err) {
+        const hint = resumeHint();
+        if (hint && !(err instanceof CliError)) {
+            note(dim(hint));
         }
+        throw err;
     }
     finally {
+        tail.stop();
+        reporter.stop();
+        await relay?.close();
         log.close();
     }
 }
+/** How often a running meta agent rewrites the fine-tuning's usage report. */
+const REPORT_EVERY_MS = 5 * 60_000;
+/**
+ * Rewrites `finetune/USAGE.md` on a timer and once more at the end, when the
+ * project is being tuned. Detached and silent: the report is a by-product, and
+ * neither its time nor its failure belongs to the run.
+ */
+function usageReporter(dir) {
+    const script = join(dir, '.github/skills/zen-finetune/scripts/usage.mjs');
+    if (!existsSync(join(dir, 'finetune')) || !existsSync(script)) {
+        return { stop: () => undefined };
+    }
+    let running = false;
+    const refresh = () => {
+        if (running) {
+            return;
+        }
+        running = true;
+        const child = spawn(process.execPath, [script, '-q'], {
+            cwd: dir,
+            stdio: 'ignore',
+            detached: true,
+        });
+        child.on('exit', () => (running = false));
+        child.on('error', () => (running = false));
+        child.unref();
+    };
+    const timer = setInterval(refresh, REPORT_EVERY_MS);
+    timer.unref();
+    return {
+        stop: () => {
+            clearInterval(timer);
+            running = false;
+            refresh();
+        },
+    };
+}
+/** The wait before a resume, cut short by Ctrl-C - which still says how to resume. */
+async function pause(ms, hint) {
+    const stop = new AbortController();
+    const onInt = () => stop.abort();
+    process.once('SIGINT', onInt);
+    try {
+        await sleep(ms, undefined, { signal: stop.signal });
+    }
+    catch {
+        throw new CliError('interrupted', EXIT.failed, hint);
+    }
+    finally {
+        process.off('SIGINT', onInt);
+    }
+}
 /** Copilot's own flags, assembled once. Nothing secret goes on this line. */
-function argv(values, dir, prompt, secret) {
+function argv(values, dir, prompt, secret, fresh) {
     const args = ['-C', dir, '-p', prompt, '--output-format', 'json', '--no-color'];
     // A prompt written for an editor expects to read, write and run things, and
     // there is nobody at a `-p` run to answer the question. Naming tools is the
@@ -390,9 +686,12 @@ function argv(values, dir, prompt, secret) {
     if (values.resume) {
         args.push('--resume', values.resume);
     }
-    if (values.continue) {
+    else if (values.continue) {
         args.push('--continue');
     }
+    else if (fresh) {
+        args.push('--session-id', fresh);
+    }
     if (secret.length > 0) {
         args.push('--secret-env-vars', secret.join(','));
     }
@@ -417,6 +716,16 @@ function projectModel(dir) {
         return undefined;
     }
 }
+function count(text, flag) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const value = Number(text);
+    if (!Number.isInteger(value) || value < 0) {
+        throw usageError(`${flag} takes a whole number, 0 or more`, `got "${text}"`);
+    }
+    return value;
+}
 function asProvider(name) {
     const owner = assertOwner(name);
     if (owner === 'exa') {
@@ -534,7 +843,7 @@ async function vet(ctx, ref) {
         // The colon form, so a refusal suggests `zen models ls <provider>`.
         ref: `${owner}:${id}`,
         kind: 'model',
-        model: createModel({ provider: owner, model: id, maxTokens: 16 }),
+        model: probeChat(owner, id),
     });
     bar?.done();
     if (probe.check.state !== 'live') {