@zenera/cli 1.1.17 → 1.1.19

package/dist/commands/run.js

@@ -1,4 +1,5 @@
 import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
 import { parse } from "../args.js";
 import * as Engine from "../engine.js";
 import { duration, Narrator, stopMark, summary } from "../narrate.js";
@@ -12,33 +13,42 @@ export const run = {
     summary: 'Run the project — the TUI on a terminal, one shot otherwise.',
     usage: USAGE,
     details: [
-        '  --project <name|dir>   Which project. Inferred from the directory.',
-        '  --session <id>         Continue a particular session.',
-        '  --new                  Start a fresh one.',
-        '  --workspace <dir>      What the agent can read and write.',
-        '  --model <ref>          Override the default model.',
-        '  --image <ref>          Override the sandbox image commands run in.',
-        '  --read-only            Give the agent no way to write.',
-        '  --no-keys              Keep the API keys out of the sandbox.',
-        '  --quiet                Answer only; no narration.',
-        '  --plain                One shot, even on a terminal.',
-        '  --theme <dark|light>   Force the palette. Detected otherwise; $ZENERA_THEME.',
-        '  --out <file>           Write the answer here as well as to stdout.',
-        '  --yes                  Accept the questions this would otherwise ask.',
+        'Arguments:',
+        '  [project]   Name of a project. Default: the one you are in.',
+        '  [prompt]    Your question, in quotes. Without one, the TUI opens.',
         '',
-        'The first word is the project when it names one, as in `zen run acme`,',
-        'and the first word of the prompt when it does not. --project settles it.',
+        'Options:',
+        '  --project <name|dir>   Which project to run. Default: the one you are in.',
+        '  --session <id>         Continue this session.',
+        '  --new                  Start a new session without asking which one.',
+        '  --workspace <dir>      Directory the agent can read and write.',
+        '  --memory <dir>         Directory the agents remember into.',
+        '  --model <ref>          Use this model instead of the default.',
+        '  --image <ref>          Use this container image to run commands in.',
+        '  --read-only            Take away every tool that can write.',
+        '  --no-keys              Do not pass API keys into the container.',
+        '  --plain                Never open the TUI. Needs a prompt.',
+        '  --theme <dark|light>   Colours for the TUI. Default: auto.',
+        '  --out <file>           Put the answer in this file instead of on screen.',
+        '  --yes                  Answer yes to every question.',
         '',
-        "The project's .env is read before it loads, and every name in it is",
-        'forwarded into the sandbox. Your shell wins over the file, and the',
-        'keyring fills in the rest; --no-keys withholds all of it.',
+        'The first word is the project when it names one, otherwise the prompt.',
+        'The answer goes to stdout and the progress to stderr, so `> out.md` keeps',
+        'the answer alone and `2>/dev/null` hides the progress.',
         '',
-        'The prompt comes from the argument, or stdin, or the TUI. There is no',
-        '`resume`: a session continues itself, because its state is what it is.',
+        'A prompt always starts a new session, so --new is for the TUI, where the',
+        'alternative is being asked which session to continue.',
         '',
-        'With a prompt on the command line nothing is asked: a fresh session, the',
-        'directory you are in as the workspace, writable. --session, --workspace',
-        'and --read-only override that; the TUI still asks.',
+        'Examples:',
+        '  zen run                               open the TUI in this project',
+        '  zen run acme                          open the TUI in the acme project',
+        '  zen run "what changed?"               ask that, print the answer, exit',
+        '  git diff | zen run                    take the prompt from stdin',
+        '  zen run "what changed?" > out.md      redirect the answer into a file',
+        '  zen run --out out.md "what changed?"  write the answer to out.md only',
+        '  zen run --read-only "what changed?"   let it read but not write',
+        '  zen run --memory ./mem                remember into ./mem, not the project',
+        '  zen run --new                         open the TUI in a new session',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
@@ -46,12 +56,12 @@ export const run = {
             session: { type: 'string' },
             new: { type: 'boolean' },
             workspace: { type: 'string' },
+            memory: { type: 'string' },
             model: { type: 'string' },
             image: { type: 'string' },
             'no-keys': { type: 'boolean' },
             'read-only': { type: 'boolean' },
             yes: { type: 'boolean' },
-            quiet: { type: 'boolean' },
             plain: { type: 'boolean' },
             theme: { type: 'string' },
             out: { type: 'string' },
@@ -90,6 +100,9 @@ export const run = {
             readOnly: values['read-only'],
             model: values.model,
             image: values.image,
+            // Relative to where it was typed, like every other path on the line
+            // — the project root is not the cwd.
+            memoryDir: values.memory ? resolve(ctx.cwd, values.memory) : undefined,
             keys: values['no-keys'] ? false : undefined,
             yes: values.yes || ctx.json,
         });
@@ -100,7 +113,6 @@ export const run = {
             // over it would be worse than not drawing one.
             const drawing = !prompt &&
                 !values.plain &&
-                !values.quiet &&
                 !ctx.json &&
                 Boolean(process.stdout.isTTY && process.stdin.isTTY);
             if (drawing) {
@@ -127,7 +139,7 @@ export const run = {
 // ---------------------------------------------------------------------------
 async function once(engine, prompt, values, asJson, cwd, where) {
     const narrator = new Narrator({
-        quiet: Boolean(values.quiet) || asJson,
+        quiet: asJson,
         live: Boolean(process.stderr.isTTY),
     });
     // Ctrl-C asks the run to stop rather than killing the process, so the turn
@@ -135,7 +147,7 @@ async function once(engine, prompt, values, asJson, cwd, where) {
     const stopping = new AbortController();
     const onInterrupt = () => stopping.abort();
     process.once('SIGINT', onInterrupt);
-    if (!values.quiet && !asJson) {
+    if (!asJson) {
         // Two questions were just answered, possibly without being asked. Say
         // which way they went: a run that quietly resumed the wrong session, or
         // wrote into the directory you were standing in, is only explainable
@@ -158,25 +170,38 @@ async function once(engine, prompt, values, asJson, cwd, where) {
     }
     if (asJson) {
         json({
-            session: engine.session.id,
-            run: outcome.run.id,
+            session: { id: engine.session.id, dir: engine.session.dir },
+            run: {
+                id: outcome.run.id,
+                dir: outcome.run.dir,
+                input: outcome.run.input,
+                output: outcome.run.output,
+                state: outcome.run.state,
+                meta: outcome.run.meta,
+                ...(outcome.report ? { report: outcome.report } : {}),
+            },
+            mounts: Engine.mounts(engine),
             agent: outcome.result.agent,
             stopReason: outcome.result.stopReason,
             durationMs: outcome.durationMs,
             usage: outcome.result.usage,
             output: outcome.text,
-            report: outcome.run.report,
         });
         return;
     }
-    write(outcome.text);
-    if (!values.quiet) {
-        note('');
-        note(`${stopMark(outcome.result.stopReason)} ${dim(duration(outcome.durationMs))}  ` +
-            dim(summary(outcome.result.usage)));
-        if (outcome.report) {
-            note(dim(`report: ${cyan(display(outcome.report, cwd))}`));
-        }
+    // --out is a destination, not a copy: the answer goes there instead of to
+    // stdout, so a redirect and a file cannot both end up holding it.
+    if (values.out) {
+        note(dim(`answer: ${cyan(values.out)}`));
+    }
+    else {
+        write(outcome.text);
+    }
+    note('');
+    note(`${stopMark(outcome.result.stopReason)} ${dim(duration(outcome.durationMs))}  ` +
+        dim(summary(outcome.result.usage)));
+    if (outcome.report) {
+        note(dim(`report: ${cyan(display(outcome.report, cwd))}`));
     }
 }
 //# sourceMappingURL=run.js.map

package/dist/engine.d.ts

@@ -10,6 +10,8 @@ export interface EngineOptions {
     model?: string;
     /** sandbox image override — `--image` */
     image?: string;
+    /** another directory to remember into — `--memory` */
+    memoryDir?: string;
     /** whether credentials reach the sandbox — `--no-keys` sets this false */
     keys?: boolean;
     /** answer the sandbox's install question without asking — `--yes` */
@@ -20,6 +22,10 @@ export interface Engine {
     runner: AgentRunner;
     name: string;
     workspace: string;
+    /** where the workspace appears inside the container */
+    workspaceMount: string;
+    /** whether the agent was denied every writing tool */
+    readOnly: boolean;
     session: SessionPaths;
     /** the session's accumulated state, when it has one */
     state?: AgentState;
@@ -34,6 +40,15 @@ export interface Engine {
  * and the whole conversation, its memory and its blobs travel with it.
  */
 export declare function open(opts: EngineOptions): Promise<Engine>;
+export interface Mount {
+    /** the directory on this machine */
+    host: string;
+    /** where it appears to the agent */
+    at: string;
+    readOnly: boolean;
+}
+/** Every tree the agent can see, the workspace first. */
+export declare function mounts(engine: Engine): Mount[];
 export interface RunOutcome {
     run: RunPaths;
     result: RunResult<string>;

package/dist/engine.js

@@ -42,8 +42,13 @@ export async function open(opts) {
     let files;
     try {
         const { root, config } = readProjectConfig(opts.project.dir);
+        // Naming a directory declares the graph, but it cannot bind anyone to
+        // it — so say when the run is pointed at a memory no agent will touch.
+        if (opts.memoryDir && !config.agents.some((a) => a.memory)) {
+            warn('--memory names a directory no agent uses — none has `memory: true`');
+        }
         // Assets and the skill catalog are mounted for both, under one name.
-        const mounts = projectMounts(root, config);
+        const mounts = projectMounts(root, config, opts.memoryDir);
         sandbox = buildSandbox({
             config,
             root,
@@ -78,6 +83,7 @@ export async function open(opts) {
                 ...exaTools(),
             ],
             skillsAt: SKILLS_MOUNT,
+            memoryDir: opts.memoryDir,
             payloads,
             resolveFile: (path) => files.within(path),
         });
@@ -109,6 +115,8 @@ export async function open(opts) {
         runner,
         name: opts.project.name,
         workspace,
+        workspaceMount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+        readOnly: Boolean(opts.readOnly),
         session: opts.session,
         state,
         sandbox,
@@ -132,6 +140,17 @@ async function loadState(session) {
         throw invalidError(`${session.state} is not a usable run state`, 'start a fresh session with --new');
     }
 }
+/** Every tree the agent can see, the workspace first. */
+export function mounts(engine) {
+    return [
+        { host: engine.workspace, at: engine.workspaceMount, readOnly: engine.readOnly },
+        ...engine.sandbox.mounts.map((m) => ({
+            host: m.host,
+            at: m.at,
+            readOnly: Boolean(m.readOnly),
+        })),
+    ];
+}
 /**
  * One turn. The session's state decides whether this starts a run or continues
  * one — which is the whole of what `resume` used to be, and why it is not a

package/dist/home.d.ts

@@ -5,6 +5,8 @@ export declare const paths: {
     keys: () => string;
     keyDir: () => string;
     faker: () => string;
+    /** what the meta agent runs on, which is a choice about a tool, not a project */
+    meta: () => string;
     /** work already done and worth keeping: vectors, parses, model listings */
     cache: () => string;
 };

package/dist/home.js

@@ -26,6 +26,8 @@ export const paths = {
     keys: () => join(home(), 'keys.json'),
     keyDir: () => join(home(), 'keys'),
     faker: () => join(home(), 'faker'),
+    /** what the meta agent runs on, which is a choice about a tool, not a project */
+    meta: () => join(home(), 'meta.json'),
     /** work already done and worth keeping: vectors, parses, model listings */
     cache: () => join(home(), 'cache'),
 };

package/dist/main.js

@@ -60,7 +60,7 @@ async function main(argv) {
     const ragSearch = name === 'rag' && ['docs', 'schema'].includes(rest[0]) && rest[1] === 'search';
     const interactive = rest.includes('--interactive');
     if (!json && (!ragSearch || interactive)) {
-        const brand = external && hasExternal(external) ? external.banner : undefined;
+        const brand = external && hasExternal(external) ? external.banner : command?.banner;
         printBanner(brand ?? NEO_BANNER, { full: ragSearch && interactive });
     }
     if (parts.name === 'help') {

package/dist/meta.d.ts

@@ -0,0 +1,221 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type KeyEntry, type KeyStore, type Provider } from './keys.ts';
+export declare const PROMPT_DIR = ".github/prompts";
+/** The variable a project's `.env` names it with — a zen ref, not a wire id. */
+export declare const MODEL_ENV = "ZENERA_META_MODEL";
+export type ModelSource = 'flag' | 'shell' | 'env' | 'store' | 'project' | 'default';
+export interface ModelChoice {
+    /** a zen ref: `vertex/gemini-3.8-flash`, or a bare id for the default provider */
+    ref: string;
+    from: ModelSource;
+}
+export interface ModelSources {
+    flag?: string;
+    /** `ZENERA_META_MODEL` as it stood before the project's `.env` was folded in */
+    shell?: string;
+    /** the same variable after it was, which is the `.env` answer when they differ */
+    env?: string;
+    stored?: string;
+    /** the project's `agents.yaml` `model:` */
+    project?: string;
+    /** what a held key recommends, when nothing above answered */
+    fallback?: string;
+}
+/** Where the answer is looked for, best first. */
+export declare const ORDER: readonly ModelSource[];
+export declare function chooseModel(sources: ModelSources): ModelChoice | undefined;
+export declare const SOURCE_LABELS: Record<ModelSource, string>;
+/** First of each row is the default; the rest are what `--pick` offers beside it. */
+export declare const RECOMMENDED: Partial<Record<Provider, readonly string[]>>;
+/** The recommended ref for the first provider with a key, or for `only`. */
+export declare function defaultRef(store: KeyStore, only?: Provider): string | undefined;
+export interface MetaFile {
+    version: 1;
+    model?: string;
+}
+export declare const readMeta: () => Promise<MetaFile>;
+export declare function writeMeta(file: MetaFile): void;
+/**
+ * `vertex/gemini-3.8-flash` splits; `gpt-5.6-sol` does not. Only a known provider
+ * counts as a prefix, because `google/gemini-3.8-flash` is also a perfectly good
+ * bare id on an endpoint that speaks publisher names.
+ *
+ * The colon form is the library's own — `openai:gpt-5.6-sol`, and with an api
+ * selector `openai/responses:gpt-5.6-sol` — which is what arrives when the ref
+ * came from `agents.yaml`.
+ */
+export declare function splitRef(ref: string): {
+    provider?: Provider;
+    id: string;
+};
+/**
+ * The provider a misspelt prefix was reaching for, if that is what it is.
+ *
+ * `vertes/gemini-3.8-flash` is shaped exactly like the OpenRouter id
+ * `meta-llama/llama-4`, so an unknown prefix cannot be an error on its own —
+ * only one close enough to a real provider name to be a slip of the hand.
+ */
+export declare function misspelledProvider(ref: string): Provider | undefined;
+/**
+ * Copilot offers its tools as OpenAI *custom* tools, which the completions API
+ * rejects outright — `400 Invalid value: 'custom'`. Only the responses API
+ * takes them, and only the reasoning models serve it, so the wire API follows
+ * the model rather than being a flag nobody would know to set.
+ */
+export declare function wireApi(provider: Provider, id: string): string | undefined;
+export interface Wiring {
+    provider: Provider;
+    /** what the model is called on the wire */
+    model: string;
+    /** every `COPILOT_*` name and value, ready to hand to the child */
+    env: Record<string, string>;
+    /** names whose values are secret, for `--secret-env-vars` and for masking */
+    secret: string[];
+    /** anything true but unwelcome: a location that will be slow, a stale default */
+    warnings: string[];
+}
+/**
+ * Turns a zen key entry and a model id into copilot's environment.
+ *
+ * `COPILOT_PROVIDER_BASE_URL` is what activates BYOK at all, so every provider
+ * gets one — including OpenAI, whose url copilot would otherwise have reached
+ * through a GitHub account we are deliberately not using.
+ */
+export declare function wire(store: KeyStore, entry: KeyEntry, id: string): Wiring;
+/** Values a `--dry-run` may print. A key is four characters and an apology. */
+export declare function masked(env: Record<string, string>, secret: readonly string[]): string[];
+/** `/project-review`, `project-review`, `project-review.prompt.md` or a path. */
+export declare function promptPath(dir: string, name: string): string;
+export interface StoredPrompt {
+    name: string;
+    path: string;
+    description?: string;
+    body: string;
+}
+/**
+ * Frontmatter is the editor's business — `mode`, `tools`, `description` — and
+ * none of it means anything to copilot, so only the body is sent. `description`
+ * is kept for the one line of narration that says which prompt is running.
+ */
+export declare function readPrompt(path: string, name: string, text: string): StoredPrompt;
+export declare function loadPrompt(dir: string, name: string): Promise<StoredPrompt>;
+export declare function listPrompts(dir: string): Promise<string[]>;
+export interface Binary {
+    command: string;
+    args: string[];
+    from: 'path' | 'npx';
+}
+/**
+ * A `copilot` already installed is used as it is; otherwise `npx` fetches one.
+ * Note that finding the name on `PATH` is not the same as finding the CLI —
+ * an editor may have put a shim there that installs it on first run — so this
+ * only decides how to launch, never whether it will work.
+ */
+export declare function locate(has?: (cmd: string) => boolean): Binary;
+interface Event {
+    type: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface Outcome {
+    /** the last thing the agent said that was not a preamble to a tool call */
+    answer: string;
+    exitCode: number;
+    sessionId?: string;
+    usage?: Record<string, unknown>;
+    events: Event[];
+}
+export interface Sink {
+    answer(text: string): void;
+    narrate(line: string): void;
+    warn(line: string): void;
+    /** Kept by the log, never shown: the step-by-step nobody reads while it runs. */
+    detail?(line: string): void;
+    /** A transient last row, replaced each time and never kept. '' removes it. */
+    status?(line: string): void;
+    /** Called once when the run ends, so a repainting sink can clear itself. */
+    close?(): void;
+}
+export declare const terminalSink: Sink;
+/** Rows of narration the window keeps on screen. */
+export declare const WINDOW_ROWS = 8;
+/** How often the border is redrawn — the wave's frame, not the clock's. */
+export declare const FRAME_MS = 80;
+/** Cells the crest travels per frame — a lap of a wide window in a few seconds. */
+export declare const WAVE_STEP = 3;
+/**
+ * How brightly one cell of the border is lit, given where the crest has got to.
+ *
+ * `position` counts clockwise from the top left corner, so one index walks the
+ * whole ring and the wave rounds the corners without a seam. Everything the
+ * tail has passed sits at the dimmest tone, which is the border's resting
+ * colour: the ring is always drawn, only the crest moves.
+ */
+export declare function toneAt(position: number, head: number, span: number): number;
+/**
+ * The bottom rule as cells, with the status label set into it near the left.
+ *
+ * Waiting belongs to the frame rather than to the narration: a row of its own
+ * costs a step of what the agent is doing every time, and it settles just
+ * under the last line, which is where the eye already is. Near the left, where
+ * reading starts, and not so near that it displaces the corner.
+ */
+export declare function footerCells(label: string, width: number): string[];
+/**
+ * Narration held to a fixed number of rows that rewrite themselves in place.
+ *
+ * A long run is hundreds of tool calls, and printing each as its own line
+ * scrolls the question, the model line and every warning off the top of the
+ * screen — by the end the terminal holds a transcript nobody asked for and the
+ * answer is somewhere in the middle of it. Only the last few steps say what it
+ * is doing now, which is the only thing narration is for; the rest is in the
+ * session copilot recorded.
+ *
+ * Warnings are not narration: they leave the window and stay on the screen.
+ *
+ * Without a terminal there is nothing to rewrite over, so every line is its
+ * own — which is what a CI log wants anyway.
+ */
+export declare function windowSink(rows?: number): Sink;
+/**
+ * The answer in the same box `zen run` draws it in: bounded width, rounded
+ * rule, fenced blocks kept as they were written.
+ *
+ * Redirected output gets the text and nothing else — `zen meta run ... > out.md`
+ * is meant to produce a file you can read, not one with a border down its side.
+ */
+export declare function answerBox(text: string, columns?: number): string[];
+export interface Log {
+    readonly path: string;
+    /** Where the answer alone goes, beside the log and openable on its own. */
+    readonly answerPath: string;
+    line(text: string): void;
+    saveAnswer(text: string): void;
+    close(): void;
+}
+/** `<project>/.tmp/logs/meta.<when>.log`, opened for append. */
+export declare function openLog(dir: string, now?: Date): Log;
+/**
+ * Folds one event into the outcome and says what, if anything, to show for it.
+ *
+ * `assistant.message` carries both the running commentary and the final word;
+ * what separates them is `toolRequests`, so the last message that asked for no
+ * tool is the answer and the rest are narration.
+ */
+export declare function absorb(event: Event, out: Outcome, sink: Sink, width: number): void;
+export interface Launch {
+    binary: Binary;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    sink?: Sink;
+    log?: Log;
+    width?: number;
+    /** injected by the tests, which have no copilot and want none */
+    spawn?: typeof nodeSpawn;
+}
+export declare function launch(opts: Launch): Promise<Outcome>;
+/** Non-fatal, said once, because a competing file is a silent override. */
+export declare function providersWarning(): string | undefined;
+export {};
+//# sourceMappingURL=meta.d.ts.map