@zenera/cli 1.1.16 → 1.1.18

package/dist/podman.js

@@ -1,5 +1,5 @@
 import { runProcess, SandboxError } from '@zenera/neo';
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
@@ -111,9 +111,71 @@ function instructions() {
         case 'win32':
             return 'install it with: winget install RedHat.Podman';
         default:
-            return 'install it with your package manager, e.g. apt install podman';
+            return linuxInstructions();
     }
 }
+/**
+ * How podman gets installed, by distribution — podman.io/docs/installation,
+ * which is where any of these should be checked against.
+ *
+ * "Install it with your package manager" is advice nobody needs and everybody
+ * has to translate; the host already says which one it has, so the message may
+ * as well be the line to paste. It stops at the line: `sudo` wants a terminal
+ * to ask for a password on and `runProcess` gives it a pipe, so running this
+ * for the user would hang rather than help.
+ */
+const LINUX_INSTALL = {
+    alpine: 'install it with: sudo apk add podman',
+    arch: 'install it with: sudo pacman -S podman',
+    centos: 'install it with: sudo dnf -y install podman',
+    debian: 'install it with: sudo apt-get -y install podman',
+    fedora: 'install it with: sudo dnf -y install podman',
+    gentoo: 'install it with: sudo emerge app-containers/podman',
+    // Nix installs nothing imperatively worth keeping: the podman that works
+    // rootless is the one the module turns on.
+    nixos: 'enable it with: virtualisation.podman.enable = true; then: sudo nixos-rebuild switch',
+    opensuse: 'install it with: sudo zypper install podman',
+    rhel: 'install it with: sudo dnf -y install podman',
+    sles: 'install it with: sudo zypper install podman',
+    suse: 'install it with: sudo zypper install podman',
+    ubuntu: 'install it with: sudo apt-get update && sudo apt-get -y install podman',
+    void: 'install it with: sudo xbps-install -S podman',
+};
+function linuxInstructions() {
+    for (const id of osRelease()) {
+        // `opensuse-leap` and `rhel-9` name the same package manager as their
+        // family does, so a miss on the whole id is worth one on its stem.
+        const how = LINUX_INSTALL[id] ?? LINUX_INSTALL[id.split(/[-.]/)[0] ?? ''];
+        if (how) {
+            return how;
+        }
+    }
+    return 'install it with your package manager, e.g. apt-get install podman';
+}
+/**
+ * `ID` first, then `ID_LIKE` — the distribution's own name, then the families
+ * it claims to behave like, which is how Rocky, Alma and Mint get answered
+ * without being listed.
+ */
+function osRelease() {
+    let text;
+    try {
+        text = readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const read = (key) => {
+        const line = new RegExp(`^${key}=(.*)$`, 'm').exec(text)?.[1] ?? '';
+        return line
+            .trim()
+            .replace(/^["']|["']$/g, '')
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(Boolean);
+    };
+    return [...read('ID'), ...read('ID_LIKE')];
+}
 // ---------------------------------------------------------------------------
 // The machine
 // ---------------------------------------------------------------------------

package/dist/projects.d.ts

@@ -16,7 +16,7 @@ export interface Project {
  * and does not edit — and the paths are resolved, because the podman machine on
  * macOS shares the real path or nothing.
  */
-export declare function projectMounts(root: string, config: ProjectConfig): SandboxMount[];
+export declare function projectMounts(root: string, config: ProjectConfig, memoryAt?: string): SandboxMount[];
 /** Walks up from `start` looking for a project configuration. */
 export declare function findUp(start: string): Promise<Project | undefined>;
 export declare function openDir(dir: string): Promise<Project>;
@@ -70,6 +70,14 @@ export declare const sessionsDir: (projectDir: string) => string;
 /** Session ids, oldest first. Only well-formed stamps count as sessions. */
 export declare function sessionIds(projectDir: string): string[];
 export declare function runIds(sessionDir: string): string[];
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export declare function lastUsedAt(projectDir: string): string | undefined;
 /**
  * What a tree occupies, in allocated blocks rather than in bytes, because a
  * sparse file costs what it was given and not what it claims. Symlinks are

package/dist/projects.js

@@ -35,7 +35,7 @@ export function isProjectDir(dir) {
  * and does not edit — and the paths are resolved, because the podman machine on
  * macOS shares the real path or nothing.
  */
-export function projectMounts(root, config) {
+export function projectMounts(root, config, memoryAt) {
     const mounts = [];
     const assets = assetsDir(root, config);
     if (assets) {
@@ -47,7 +47,7 @@ export function projectMounts(root, config) {
     for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
         mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
     }
-    const memory = memoryDir(root, config);
+    const memory = memoryDir(root, config, memoryAt);
     if (memory) {
         // Created here because the mount is decided before the project is
         // loaded, and podman would refuse a source that does not exist yet.
@@ -224,6 +224,23 @@ export function sessionIds(projectDir) {
 export function runIds(sessionDir) {
     return stampedChildren(join(sessionDir, 'runs'));
 }
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export function lastUsedAt(projectDir) {
+    let last;
+    for (const id of sessionIds(projectDir)) {
+        const newest = runIds(join(sessionsDir(projectDir), id)).at(-1) ?? id;
+        if (!last || newest > last) {
+            last = newest;
+        }
+    }
+    return last;
+}
 function stampedChildren(dir) {
     if (!existsSync(dir)) {
         return [];

package/dist/resolve.js

@@ -23,7 +23,13 @@ export async function project(want) {
     if (!isInteractive()) {
         throw usageError('not inside a project', 'name one with --project');
     }
-    const chosen = await choose('Which project?', known.map((e) => ({ label: e.name, detail: e.path, value: e })));
+    // Most recently worked in first: the answer to "which project" is nearly
+    // always the one from last time, and registration order is nothing to a
+    // person. A project never run sorts last, by name.
+    const ranked = known
+        .map((entry) => ({ entry, used: Projects.lastUsedAt(entry.path) ?? '' }))
+        .sort((a, b) => b.used.localeCompare(a.used) || a.entry.name.localeCompare(b.entry.name));
+    const chosen = await choose('Which project?', ranked.map(({ entry }) => ({ label: entry.name, detail: entry.path, value: entry })));
     return Projects.openDir(chosen.path);
 }
 // ---------------------------------------------------------------------------

package/dist/sandbox.d.ts

@@ -10,6 +10,8 @@ export interface SandboxSetup {
     build?: ResolvedBuild;
     /** host side of the container's `$HOME`, created only if it is ever needed */
     home: string;
+    /** every tree bound into the container besides the workspace itself */
+    mounts: readonly SandboxMount[];
 }
 export interface SandboxInputs {
     config: ProjectConfig;
@@ -28,6 +30,15 @@ export interface SandboxInputs {
     image?: string;
     /** `--no-keys`: refuse to forward credentials, whatever the config says */
     keys?: boolean;
+    /**
+     * Names from the project's `.env`, forwarded into the container the same
+     * way a credential is — by name, so the value stays out of the argv.
+     *
+     * They travel with the keys rather than beside them: a `.env` is where an
+     * api token lives, so `--no-keys` has to withhold it too or the flag is a
+     * promise it does not keep.
+     */
+    env?: readonly string[];
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**

package/dist/sandbox.js

@@ -82,7 +82,7 @@ export function buildSandbox(opts) {
     // read-only directory fails on writing its own `__pycache__` — a confusing
     // error about a file nobody asked for.
     const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(keys?.env ?? {}) };
-    const spec = toSpec(base, extra, keys?.secrets);
+    const spec = toSpec(base, extra, secretsOf(keys?.secrets, opts.env));
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
@@ -92,7 +92,7 @@ export function buildSandbox(opts) {
             // so the variable is what actually decides, and without it the file
             // sitting there is not a credential anything will look for.
             const own = merged.keys === false ? undefined : keys;
-            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own?.secrets);
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
         }
     }
     const pool = new SandboxPool({
@@ -103,7 +103,7 @@ export function buildSandbox(opts) {
         readOnly: opts.readOnly,
         mounts,
     });
-    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home };
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home, mounts };
 }
 /**
  * An agent's overrides on the project's block. `image` and `build` answer the
@@ -121,10 +121,30 @@ function merge(base, agent) {
     }
     return merged;
 }
+/**
+ * The two sources of forwarded names, as one list: the credentials the keyring
+ * selected, and whatever the project's `.env` declares. Deduped, because the
+ * same variable named twice is the same `--env` twice.
+ *
+ * `undefined` in means keys are withheld, and the file goes with them.
+ */
+function secretsOf(secrets, env) {
+    if (!secrets) {
+        return undefined;
+    }
+    return [...new Set([...secrets, ...(env ?? [])])];
+}
 /**
  * Config names a variable; this reads it. A name that is not set on this host
  * is simply not forwarded — an empty string in the container is a different
  * thing from an absent one, and tools test for absence.
+ *
+ * A name that has already been answered with a value drops off the forwarded
+ * list: `--env NAME=value` and `--env NAME` are the same variable twice, and
+ * the one that carries a value is the one that was resolved on purpose. That
+ * matters for `GOOGLE_APPLICATION_CREDENTIALS`, which is rewritten here to
+ * where the key file was mounted — a `.env` naming it must not put the host's
+ * path back, since that path does not exist inside the container.
  */
 function toSpec(config, extra, secrets) {
     const env = { ...extra };
@@ -144,7 +164,7 @@ function toSpec(config, extra, secrets) {
         user: config.user,
         persist: config.persist,
         env,
-        secrets,
+        secrets: secrets?.filter((name) => !(name in env)),
     };
 }
 /**

package/dist/scaffold.d.ts

@@ -14,6 +14,12 @@ export interface ScaffoldOptions {
     modelOptions?: string;
     /** give the default agent `exa:*` — set when a key for it is on hand */
     web?: boolean;
+    /**
+     * What vectorises the memory graph, as a provider-prefixed ref. Left out
+     * when the project's provider publishes no embeddings API — memory still
+     * works, ranking recall by term overlap instead of by meaning.
+     */
+    embedding?: string;
 }
 export interface Scaffolded {
     /** the project's own files, in the order they were written */

package/dist/scaffold.js

@@ -1,5 +1,5 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { join } from 'node:path';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 // Scaffolding
@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url';
 //
 // The trees are copied whole and nothing enumerates them, so adding a file to
 // a new project is adding a file to `templates/project/` and nothing else.
+// `MEMORY_RULES` is the single exception, and it is named below.
 //
 // What is there is deliberately close to empty: a template full of
 // commented-out options is a template nobody reads and everybody deletes. The
@@ -32,6 +33,10 @@ import { fileURLToPath } from 'node:url';
 const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
 const TEMPLATE = '.tmpl';
+/** How to use the memory graph: a house rules file, landing under `agents/`. */
+const MEMORY_RULES = join('agents', 'memory-instructions.md');
+/** 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');
 /**
  * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
  * The publishable packages move in lockstep, so one number covers them all.
@@ -98,17 +103,24 @@ function modelSection(ref, options) {
     });
 }
 /**
- * The name a template file lands under.
+ * Template files that land under a name they cannot be stored under.
  *
- * `gitignore` gains its dot here because it cannot have one in the repository:
- * npm strips a `.gitignore` out of a published tarball, and git would read this
- * one as rules about `packages/cli/templates/` rather than as content.
+ * `gitignore` cannot have its dot in the repository: npm strips a `.gitignore`
+ * out of a published tarball, and git would read this one as rules about
+ * `packages/cli/templates/` rather than as content. `env` cannot have its dot
+ * for a plainer reason — this repository ignores `.env` everywhere, as every
+ * repository should, so the template would never be committed at all.
  */
+const DOTFILES = {
+    gitignore: '.gitignore',
+    env: '.env',
+};
+/** The name a template file lands under. */
 function target(name) {
     if (name.endsWith(TEMPLATE)) {
         return name.slice(0, -TEMPLATE.length);
     }
-    return name === 'gitignore' ? '.gitignore' : name;
+    return DOTFILES[name] ?? name;
 }
 /**
  * Copies one template directory into `dir` at `rel`, depth first, sorted so the
@@ -145,13 +157,19 @@ function copyTree(from, dir, rel, opts) {
 // ---------------------------------------------------------------------------
 // Telling the editor which instructions are not for it
 //
-// The project's house rules are `INSTRUCTIONS.md`, deliberately not
+// 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
@@ -159,12 +177,12 @@ function copyTree(from, dir, rel, opts) {
 // 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.
 //
-// `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.
+// `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
@@ -174,7 +192,21 @@ function copyTree(from, dir, rel, opts) {
  * none. Returns the relative paths written.
  */
 export function editorFiles(dir) {
-    return copyTree(join(TEMPLATES, 'editor'), dir, '', {});
+    const written = copyTree(join(TEMPLATES, 'editor'), dir, '', {});
+    // The one file that belongs to both trees. It is a project file first —
+    // house rules prepended to 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;
 }
 /**
  * Writes a project. Never overwrites the project's own files — a second `init`
@@ -198,6 +230,9 @@ export function scaffold(opts) {
             // different readers — and a tool nothing says to use is not one.
             web: opts.web ? part('exa.spec.md') : '',
             webPrompt: opts.web ? part('exa.prompt.md') : '',
+            memory: opts.embedding
+                ? part('memory.yaml', { embedding: opts.embedding })
+                : part('memory-terms.yaml'),
             version: ownVersion(),
         },
     });
@@ -209,6 +244,12 @@ export function scaffold(opts) {
     mkdirSync(join(opts.dir, 'agents', 'skills'), { recursive: true });
     mkdirSync(join(opts.dir, 'sessions'), { recursive: true });
     mkdirSync(join(opts.dir, '.tmp'), { recursive: true });
+    // Where `/spec-sync-project` records what it applied, so the next pass works
+    // the difference rather than the whole specification again. Empty here, and
+    // git does not carry an empty directory: what says a pass has completed is
+    // `baseline/manifest.txt`, never the directory itself.
+    mkdirSync(join(opts.dir, '.spec-sync', 'baseline'), { recursive: true });
+    mkdirSync(join(opts.dir, '.spec-sync', 'history'), { recursive: true });
     // The project directory is what `zen open` opens, so this is where the
     // editor actually reads them.
     return { files, editor: editorFiles(opts.dir) };

package/dist/session.d.ts

@@ -71,6 +71,16 @@ export interface RunMeta {
     error?: string;
 }
 export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;
+export interface RunSummary {
+    id: string;
+    startedAt?: string;
+    finishedAt?: string;
+    agent?: string;
+    stopReason?: string;
+    error?: string;
+}
+/** Newest first — the order a picker wants. */
+export declare function listRuns(session: SessionPaths): Promise<RunSummary[]>;
 export declare function newestRun(session: SessionPaths): string | undefined;
 /** A path to show a human: relative when that is shorter, absolute otherwise. */
 export declare function display(path: string, from?: string): string;

package/dist/session.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { hostname } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
-import { isStamp, stamp } from "./ids.js";
+import { isStamp, stamp, stampInstant } from "./ids.js";
 import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, EXIT, invalidError, usageError } from "./term.js";
 export function sessionPaths(projectDir, id) {
@@ -145,6 +145,24 @@ export function createRun(session) {
 export function writeRunMeta(p, meta) {
     writeJson(p.meta, meta, 0o644);
 }
+/** Newest first — the order a picker wants. */
+export async function listRuns(session) {
+    const out = [];
+    for (const id of runIds(session.dir).reverse()) {
+        // A run killed before it recorded anything still has an id, and the id
+        // says when it started, so it is listable without its meta.
+        const meta = await readJson(runPaths(session, id).meta, {});
+        out.push({
+            id,
+            startedAt: meta.startedAt ?? stampInstant(id),
+            finishedAt: meta.finishedAt,
+            agent: meta.agent,
+            stopReason: meta.stopReason,
+            error: meta.error,
+        });
+    }
+    return out;
+}
 export function newestRun(session) {
     return runIds(session.dir).at(-1);
 }

package/dist/term.d.ts

@@ -26,6 +26,13 @@ export declare const red: (s: string) => string;
 export declare const green: (s: string) => string;
 export declare const yellow: (s: string) => string;
 export declare const cyan: (s: string) => string;
+/**
+ * Whether anything should be coloured at all — `styleText`'s own answer, asked
+ * by the places that write escape codes directly and so cannot inherit it.
+ */
+export declare const styled: () => boolean;
+/** The text as it reads without styling, which is what a file wants. */
+export declare const plain: (s: string) => string;
 export declare function pad(s: string, to: number): string;
 /** Column-aligned rows. Trailing whitespace is trimmed so `diff` stays quiet. */
 export declare function table(rows: readonly (readonly string[])[], gap?: number): string[];

package/dist/term.js

@@ -45,10 +45,17 @@ export const red = (s) => styleText('red', s);
 export const green = (s) => styleText('green', s);
 export const yellow = (s) => styleText('yellow', s);
 export const cyan = (s) => styleText('cyan', s);
+/**
+ * Whether anything should be coloured at all — `styleText`'s own answer, asked
+ * by the places that write escape codes directly and so cannot inherit it.
+ */
+export const styled = () => styleText('dim', '.') !== '.';
 /** Visible width — style codes must not count towards column alignment. */
 // eslint-disable-next-line no-control-regex
 const ANSI = /\u001b\[[0-9;]*m/g;
-const width = (s) => s.replace(ANSI, '');
+/** The text as it reads without styling, which is what a file wants. */
+export const plain = (s) => s.replace(ANSI, '');
+const width = plain;
 export function pad(s, to) {
     return s + ' '.repeat(Math.max(0, to - width(s).length));
 }

package/dist/tui/app.js

@@ -43,7 +43,7 @@ function Answer({ text }) {
     const { stdout } = useStdout();
     const width = answerWidth(stdout?.columns ?? 80);
     const segments = segmentsOf(text);
-    // Bounded, like every answer in `examples/`: prose that runs the width of a
+    // Bounded, like every answer in `examples/sdk/`: prose that runs the width of a
     // wide terminal is a worse read than prose that stops, and the box is also
     // what separates the answer from the machinery that produced it.
     return (_jsx(Box, { flexDirection: "column", width: width, borderStyle: "round", borderDimColor: true, paddingX: 1, marginY: 1, children: segments.map((s, i) => s.code ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: `\u250c\u2500${s.title ? ` ${s.title}` : ''}` }), s.lines.map((l, j) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { dimColor: true, children: '\u2502 ' }), _jsx(Text, { wrap: "truncate-end", children: l || ' ' })] }, j))), _jsx(Text, { dimColor: true, children: '\u2514\u2500' })] }, i)) : (_jsx(Text, { children: s.lines.join('\n') }, i))) }));
@@ -431,7 +431,7 @@ function App({ engine, options, theme }) {
             recall(1);
         }
     });
-    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly, started: options.started }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), _jsxs(Box, { flexDirection: "column", justifyContent: "flex-end", height: busy ? grown.current : undefined, overflow: "hidden", children: [_jsx(Branches, { boxes: fitted.boxes, spin: spin, columns: columns }), _jsx(Activity, { rows: fitted.trunk, hidden: fitted.hidden }), thinking && budget.thinking ? (_jsx(Thinking, { text: thinking, columns: columns, rows: budget.thinking, spin: spin, live: streaming })) : null, live ? _jsx(Live, { text: live, columns: columns, rows: budget.live }) : null] }), _jsx(Footer, { agent: agent, busy: busy, spin: spin, running: mine, forked: branches.current.size, step: step, model: model, stats: stats, inflight: inflight, reasoning: streaming, columns: columns }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { defaultValue: draft, placeholder: "Ask something\u2026 (\u2191 for history, /help for commands)", onChange: remember, onSubmit: submit }, generation)] }))] }) }));
+    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly, started: options.started }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), _jsxs(Box, { flexDirection: "column", justifyContent: "flex-end", height: busy ? grown.current : undefined, overflow: "hidden", children: [_jsx(Branches, { boxes: fitted.boxes, spin: spin, columns: columns }), _jsx(Activity, { rows: fitted.trunk, hidden: fitted.hidden }), thinking && budget.thinking ? (_jsx(Thinking, { text: thinking, columns: columns, rows: budget.thinking, spin: spin, live: streaming })) : null, live ? _jsx(Live, { text: live, columns: columns, rows: budget.live }) : null] }), _jsx(Footer, { agent: agent, busy: busy, spin: spin, frame: frame, running: mine, forked: branches.current.size, step: step, model: model, stats: stats, inflight: inflight, reasoning: streaming, columns: columns }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { defaultValue: draft, placeholder: "Ask something\u2026 (\u2191 for history, /help for commands)", onChange: remember, onSubmit: submit }, generation)] }))] }) }));
 }
 function Header({ engine, readOnly, started, }) {
     const theme = useTheme();
@@ -467,7 +467,7 @@ const GUTTER = 2;
 /**
  * A fan-out, demultiplexed into one box per branch. Interleaving eight
  * branches' calls into a single list is not a picture of parallel work, it is
- * eight pictures shuffled together; a box per branch is what `examples/board.ts`
+ * eight pictures shuffled together; a box per branch is what `examples/sdk/board.ts`
  * gets right and what makes the shape of the fork legible at a glance.
  *
  * A box shows the last few calls the branch made and whatever it has in flight,
@@ -655,7 +655,35 @@ function Live({ text, columns, rows }) {
 }
 /** The label column the two number rows line up behind. */
 const LABEL = 10;
-function Footer({ agent, busy, spin, running, forked, step, model, stats, inflight, reasoning, columns, }) {
+/** Frames the crest spends past the end, so a sweep reads as a pass, not a loop. */
+const SWEEP_GAP = 6;
+/**
+ * A crest of weight travelling through a word, left to right.
+ *
+ * The spinner is proof the process is alive, but it is chrome and the eye
+ * reads the word beside it — a word that never moves is what a hung run looks
+ * like. The wave is weight rather than hue because the theme has no ramp to
+ * spend: dim at rest, the terminal's own weight at the crest, and the word
+ * keeps whatever colour its role gave it.
+ */
+function Shimmer({ text, frame, color, }) {
+    const chars = [...text];
+    // A new word is a new thing to say, so the sweep starts over on it rather
+    // than picking the crest up wherever the last word had got to.
+    const begun = useRef(frame);
+    const said = useRef(text);
+    if (said.current !== text) {
+        said.current = text;
+        begun.current = frame;
+    }
+    const head = (frame - begun.current) % (chars.length + SWEEP_GAP);
+    return (_jsx(Text, { children: chars.map((ch, i) => {
+            // The crest sits on the head and the tail drags behind it.
+            const behind = head - i;
+            return (_jsx(Text, { color: color, bold: behind === 0, dimColor: behind < 0 || behind > 2, children: ch }, i));
+        }) }));
+}
+function Footer({ agent, busy, spin, frame, running, forked, step, model, stats, inflight, reasoning, columns, }) {
     const theme = useTheme();
     // Who before what. The agent is the subject of the sentence, and in a
     // handoff it is the thing that changed.
@@ -687,7 +715,7 @@ function Footer({ agent, busy, spin, running, forked, step, model, stats, inflig
     // Nothing of its own in flight means the word above is about reasoning, so
     // it takes the same hue the reasoning block does.
     const musing = !running.length && !forked;
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: agent }), busy ? (_jsxs(Text, { color: musing ? theme.thinking.color : theme.warn, children: ['  ', spin, " ", status] })) : null, busy ? _jsx(Text, { dimColor: true, children: `  ${aside}` }) : null] }), inflight ? (_jsxs(Text, { dimColor: true, children: ['this turn'.padEnd(LABEL), tokens(inflight.usage), ` · ${secs(inflight.durationMs)}`] })) : (_jsxs(_Fragment, { children: [stats.turn ? (_jsxs(Text, { dimColor: true, children: ['last turn'.padEnd(LABEL), tokens(stats.turn), stats.durationMs === undefined
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: agent }), busy ? (_jsxs(Text, { color: musing ? theme.thinking.color : theme.warn, children: ['  ', spin, ' ', _jsx(Shimmer, { text: status, frame: frame, color: musing ? theme.thinking.color : theme.warn })] })) : null, busy ? _jsx(Text, { dimColor: true, children: `  ${aside}` }) : null] }), inflight ? (_jsxs(Text, { dimColor: true, children: ['this turn'.padEnd(LABEL), tokens(inflight.usage), ` · ${secs(inflight.durationMs)}`] })) : (_jsxs(_Fragment, { children: [stats.turn ? (_jsxs(Text, { dimColor: true, children: ['last turn'.padEnd(LABEL), tokens(stats.turn), stats.durationMs === undefined
                                 ? ''
                                 : ` · ${durationOf(stats.durationMs) ?? ''}`] })) : null, _jsxs(Text, { dimColor: true, children: ['session'.padEnd(LABEL), tokens(stats.session), stats.calls
                                 ? ` · ${stats.calls} ${stats.calls === 1 ? 'call' : 'calls'}`

package/dist/tui/wrap.d.ts

@@ -71,7 +71,7 @@ export declare function branchRows(count: number, allowance: number): number;
 /**
  * How wide the answer is drawn. A line of prose spanning a 200-column terminal
  * is measurably harder to read than one that stops, which is why every demo in
- * `examples/` puts its answer in a box of bounded width — the terminal is the
+ * `examples/sdk/` puts its answer in a box of bounded width — the terminal is the
  * page, not the paragraph.
  */
 export declare function answerWidth(columns: number): number;

package/dist/tui/wrap.js

@@ -138,7 +138,7 @@ export function branchRows(count, allowance) {
 /**
  * How wide the answer is drawn. A line of prose spanning a 200-column terminal
  * is measurably harder to read than one that stops, which is why every demo in
- * `examples/` puts its answer in a box of bounded width — the terminal is the
+ * `examples/sdk/` puts its answer in a box of bounded width — the terminal is the
  * page, not the paragraph.
  */
 export function answerWidth(columns) {