@zenera/cli 1.1.10 → 1.1.12

package/dist/tui/theme.d.ts

@@ -13,8 +13,19 @@ export interface Theme {
     readonly accent: string;
     /** Read-only badge, busy label. */
     readonly warn: string;
-    /** Gutters and marks: structure, not content. Always drawn dim. */
-    readonly rule?: string;
+    /**
+     * Reasoning. It is not a tool call and it is not the answer, and drawn in
+     * the same dim foreground as the rows around it there was nothing to say
+     * which — a wall of one weight reads as one thing. Its own hue is what
+     * separates the model's thinking from the work it went on to do.
+     */
+    readonly thinking: LineStyle;
+    /**
+     * Branch colours, cycled in order of first sight. A fan-out is the one
+     * place where colour carries information rather than decoration: eight
+     * branches reporting at once are only separable if they are told apart.
+     */
+    readonly lanes: readonly string[];
 }
 export declare const THEMES: Record<Appearance, Theme>;
 export type ThemeChoice = Appearance | 'auto';

package/dist/tui/theme.js

@@ -4,13 +4,19 @@
 // A terminal already has a colour scheme, and it is not ours to replace. The
 // rule here is to name as few colours as possible and to name them by role:
 // the answer is drawn in the terminal's *own* foreground (no colour at all),
-// asides are drawn dim, and only the few things that must stand out —
-// the person's own turn, the agent name, a warning, an error — take a colour.
+// and only the few things that must stand out — the person's own turn, the
+// agent name, what it is reasoning about, a warning, an error — take a colour.
 //
 // That alone fixes most of it. `white` was the bug: it is legible on exactly
-// one kind of background, and half the world runs the other kind. What is left
-// is the handful of accents that ANSI *does* let a light theme get wrong —
-// `cyan` on paper, `gray` on paper — so those swap.
+// one kind of background, and half the world runs the other kind. `gray` was
+// the same bug wearing a hat — bright black, dimmed again, is a step from
+// unreadable on dark and invisible on paper. What is left is the handful of
+// accents that ANSI *does* let a light theme get wrong, so those swap.
+//
+// Dim is spent on *chrome* — box rules, clocks, the footer's numbers — and no
+// longer on content. Tool rows are most of what is on screen, and dimming them
+// put the bulk of the transcript one step from unreadable: the whole thing read
+// as too dark. They are content, so they get the foreground like content does.
 //
 // Note what is *not* here: no hex, no 256-colour ramps, no attempt at a brand.
 // A palette that ignores the user's scheme is worse on both schemes than one
@@ -21,28 +27,35 @@ const DARK = {
     line: {
         you: { color: 'cyan' },
         agent: {},
-        tool: { color: 'gray', dim: true },
-        note: { color: 'cyan', dim: true },
+        // Never dim, and never `gray`: bright black is already the faintest
+        // colour a terminal has, and either one puts the bulk of the
+        // transcript a step from unreadable.
+        tool: {},
+        note: { color: 'cyan' },
         error: { color: 'red' },
     },
     accent: 'cyan',
     warn: 'yellow',
-    rule: 'gray',
+    thinking: { color: 'magenta' },
+    lanes: ['cyan', 'green', 'yellow', 'blue', 'red', 'magenta'],
 };
-// On a light background `gray` is bright black — pale grey on white — and
-// `cyan` and `yellow` are barely darker than the paper. Dimmed default
-// foreground and `blue`/`magenta` are the same information, still legible.
+// On a light background `cyan` and `yellow` are barely darker than the paper.
+// Dimmed default foreground and `blue`/`magenta` are the same information,
+// still legible.
 const LIGHT = {
     appearance: 'light',
     line: {
         you: { color: 'blue' },
         agent: {},
-        tool: { dim: true },
-        note: { color: 'blue', dim: true },
+        tool: {},
+        note: { color: 'blue' },
         error: { color: 'red' },
     },
     accent: 'blue',
     warn: 'magenta',
+    thinking: { color: 'magenta' },
+    // No cyan or yellow: on paper they are barely darker than the paper.
+    lanes: ['blue', 'green', 'red', 'magenta'],
 };
 export const THEMES = { dark: DARK, light: LIGHT };
 export function parseChoice(value) {

package/dist/tui/wrap.d.ts

@@ -7,6 +7,98 @@
  * and bounds the work per keystroke on a stream that never stops growing.
  */
 export declare function windowOf(text: string, width: number, rows: number): string[];
+/**
+ * `text` flattened onto one row of at most `width` columns, ellipsized when it
+ * did not fit. Newlines and runs of space collapse: a row is a row, and a tool
+ * argument or a result preview arrives with whatever shape it happened to have.
+ */
+export declare function clip(text: string, width: number): string;
 /** Word wrap. Every returned row is at most `width` columns wide. */
 export declare function wrap(text: string, width: number): string[];
+/** The three footer rows, its margin, the prompt, and a row in hand. */
+export declare const CHROME_ROWS = 7;
+/** How much of the reasoning stream is worth showing. It is a progress bar. */
+export declare const THINKING_ROWS = 6;
+/** How much of the frame the work in flight may take. A branch is a box now,
+ *  not a row, so a fan-out of two costs fourteen of these. */
+export declare const ACTIVITY_ROWS = 16;
+/** The rule that opens a reasoning block and the one that closes it. */
+export declare const THINKING_CHROME = 2;
+export interface Budget {
+    /** rows for the list of what is in flight */
+    activity: number;
+    /** rows for the tail of the reasoning stream */
+    thinking: number;
+    /** rows for the answer as it arrives */
+    live: number;
+    /**
+     * What the three of them occupy together, rules included — a constant for
+     * a given terminal, whatever is happening inside it. The region grows to
+     * this and stops, and never shrinks back while the turn runs, which is what
+     * keeps the footer on one row instead of riding up and down on the
+     * reasoning block.
+     */
+    total: number;
+}
+/**
+ * How many rows each repainting block may draw in a terminal `rows` tall.
+ *
+ * Activity is capped first and never takes the last two rows: the answer as it
+ * arrives matters more than the machinery producing it. Reasoning yields to it
+ * in turn, because it is a progress indicator and the answer is the point.
+ *
+ * `thinking` is how many rows of reasoning are wanted, counting text only: none
+ * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
+ * settled and its tail is history rather than progress. The two rules are
+ * charged on top, so a block too cramped to be worth boxing is not drawn at all
+ * rather than drawn as a border with a line in it.
+ */
+export declare function budgetOf(rows: number, activity: number, thinking: number): Budget;
+/** The rows a branch box may spend on its own calls and its reasoning. */
+export declare const BRANCH_ROWS = 5;
+/** Rows a branch box spends on chrome: the title rule and the closing one. */
+export declare const BOX_CHROME = 2;
+/**
+ * How many call rows each of `count` branch boxes may draw, given the rows the
+ * activity region has to divide between them.
+ *
+ * Every branch gets the same number, because they are the same kind of thing
+ * and a fan-out is read across, not down. A wide fork spends its rows on being
+ * complete rather than on being detailed: eight branches showing one call each
+ * is a picture of the fork, eight rows of one branch is not.
+ */
+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
+ * page, not the paragraph.
+ */
+export declare function answerWidth(columns: number): number;
+/**
+ * A tool payload as a person would read it, rather than as it was serialised.
+ *
+ * A lone field is printed as its bare value, because the name of a generic tool
+ * says almost nothing on its own — `run_command` is every shell command there
+ * is, and the argument is the part that identifies THIS call.
+ *
+ * It scans rather than parses: previews are cut to a length, so the JSON very
+ * often does not close, and precisely the calls worth reading are the long ones
+ * that got cut.
+ */
+export declare function readable(preview: string): string;
+/** A run of lines from an answer, and whether it was fenced as code. */
+export interface Segment {
+    code: boolean;
+    /** the fence's info string, when it had one */
+    title?: string;
+    lines: string[];
+}
+/**
+ * Splits an answer on ``` fences. Prose is left exactly as it was — the common
+ * answer has no fence in it and comes back in one piece — but a fenced block is
+ * the one thing a terminal must not reflow: its indentation is its meaning, and
+ * wrapping it as prose destroys it.
+ */
+export declare function segmentsOf(text: string): Segment[];
 //# sourceMappingURL=wrap.d.ts.map

package/dist/tui/wrap.js

@@ -23,8 +23,23 @@
 export function windowOf(text, width, rows) {
     const w = Math.max(8, width);
     const n = Math.max(1, rows);
-    const wrapped = wrap(text.slice(-w * n * 2).replace(/\n{2,}/g, '\n'), w);
-    return wrapped.slice(-n);
+    // Trailing blank rows are never information, and a stream that ends on a
+    // paragraph break would spend one of the few rows it has on nothing.
+    const tail = text
+        .slice(-w * n * 2)
+        .replace(/\n{2,}/g, '\n')
+        .trimEnd();
+    return wrap(tail, w).slice(-n);
+}
+/**
+ * `text` flattened onto one row of at most `width` columns, ellipsized when it
+ * did not fit. Newlines and runs of space collapse: a row is a row, and a tool
+ * argument or a result preview arrives with whatever shape it happened to have.
+ */
+export function clip(text, width) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const w = Math.max(1, width);
+    return flat.length <= w ? flat : `${flat.slice(0, w - 1)}…`;
 }
 /** Word wrap. Every returned row is at most `width` columns wide. */
 export function wrap(text, width) {
@@ -59,4 +74,134 @@ export function wrap(text, width) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// Dividing the frame
+//
+// The same invariant, stated as arithmetic: every repainting block gets its
+// rows from here, and the sum is never more than the viewport has to give.
+// ---------------------------------------------------------------------------
+/** The three footer rows, its margin, the prompt, and a row in hand. */
+export const CHROME_ROWS = 7;
+/** How much of the reasoning stream is worth showing. It is a progress bar. */
+export const THINKING_ROWS = 6;
+/** How much of the frame the work in flight may take. A branch is a box now,
+ *  not a row, so a fan-out of two costs fourteen of these. */
+export const ACTIVITY_ROWS = 16;
+/** The rule that opens a reasoning block and the one that closes it. */
+export const THINKING_CHROME = 2;
+/**
+ * How many rows each repainting block may draw in a terminal `rows` tall.
+ *
+ * Activity is capped first and never takes the last two rows: the answer as it
+ * arrives matters more than the machinery producing it. Reasoning yields to it
+ * in turn, because it is a progress indicator and the answer is the point.
+ *
+ * `thinking` is how many rows of reasoning are wanted, counting text only: none
+ * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
+ * settled and its tail is history rather than progress. The two rules are
+ * charged on top, so a block too cramped to be worth boxing is not drawn at all
+ * rather than drawn as a border with a line in it.
+ */
+export function budgetOf(rows, activity, thinking) {
+    const total = Math.max(2, rows - CHROME_ROWS);
+    const shown = Math.min(Math.max(0, activity), ACTIVITY_ROWS, Math.max(0, total - 2));
+    const rest = total - shown;
+    const room = rest - 1 - THINKING_CHROME;
+    const tail = room >= 1 ? Math.min(Math.max(0, thinking), THINKING_ROWS, room) : 0;
+    return {
+        activity: shown,
+        thinking: tail,
+        live: rest - tail - (tail ? THINKING_CHROME : 0),
+        total,
+    };
+}
+/** The rows a branch box may spend on its own calls and its reasoning. */
+export const BRANCH_ROWS = 5;
+/** Rows a branch box spends on chrome: the title rule and the closing one. */
+export const BOX_CHROME = 2;
+/**
+ * How many call rows each of `count` branch boxes may draw, given the rows the
+ * activity region has to divide between them.
+ *
+ * Every branch gets the same number, because they are the same kind of thing
+ * and a fan-out is read across, not down. A wide fork spends its rows on being
+ * complete rather than on being detailed: eight branches showing one call each
+ * is a picture of the fork, eight rows of one branch is not.
+ */
+export function branchRows(count, allowance) {
+    if (count <= 0) {
+        return 0;
+    }
+    const each = Math.floor(Math.max(0, allowance) / count) - BOX_CHROME;
+    return Math.max(1, Math.min(BRANCH_ROWS, each));
+}
+/**
+ * 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
+ * page, not the paragraph.
+ */
+export function answerWidth(columns) {
+    return Math.max(24, Math.min(columns - 4, 96));
+}
+// ---------------------------------------------------------------------------
+// Reading a payload
+// ---------------------------------------------------------------------------
+/** One field of a preview: a JSON string, or a bare token when it was cut. */
+const FIELD = /"([A-Za-z_][\w-]*)"\s*:\s*("(?:[^"\\]|\\.)*"?|[^,}\s]+)/g;
+/**
+ * A tool payload as a person would read it, rather than as it was serialised.
+ *
+ * A lone field is printed as its bare value, because the name of a generic tool
+ * says almost nothing on its own — `run_command` is every shell command there
+ * is, and the argument is the part that identifies THIS call.
+ *
+ * It scans rather than parses: previews are cut to a length, so the JSON very
+ * often does not close, and precisely the calls worth reading are the long ones
+ * that got cut.
+ */
+export function readable(preview) {
+    const found = [...preview.matchAll(FIELD)];
+    if (!found.length) {
+        return preview.trim();
+    }
+    const fields = found.map((m) => [m[1], unquote(m[2])]);
+    const one = fields.length === 1 ? fields[0] : undefined;
+    return one ? one[1] : fields.map(([k, v]) => `${k}=${v}`).join(' ');
+}
+function unquote(raw) {
+    if (!raw.startsWith('"')) {
+        return raw;
+    }
+    const body = raw.length > 1 && raw.endsWith('"') ? raw.slice(1, -1) : raw.slice(1);
+    return body.replace(/\\[nrt]/g, ' ').replace(/\\(["\\/])/g, '$1');
+}
+/**
+ * Splits an answer on ``` fences. Prose is left exactly as it was — the common
+ * answer has no fence in it and comes back in one piece — but a fenced block is
+ * the one thing a terminal must not reflow: its indentation is its meaning, and
+ * wrapping it as prose destroys it.
+ */
+export function segmentsOf(text) {
+    const out = [];
+    let current = { code: false, lines: [] };
+    const flush = () => {
+        if (current.lines.length) {
+            out.push(current);
+        }
+    };
+    for (const raw of text.split('\n')) {
+        const fence = /^\s*```+\s*(\S*)/.exec(raw);
+        if (!fence) {
+            current.lines.push(raw);
+            continue;
+        }
+        flush();
+        current = current.code
+            ? { code: false, lines: [] }
+            : { code: true, title: fence[1] || undefined, lines: [] };
+    }
+    flush();
+    return out;
+}
 //# sourceMappingURL=wrap.js.map

package/dist/validate.d.ts

@@ -73,6 +73,8 @@ export interface SkillReport {
 export interface ModelReport {
     /** the alias it is declared under, or the reference itself */
     name: string;
+    /** what `name` resolves to, when it is an alias rather than a reference */
+    ref?: string;
     /** what the config declared it for */
     role: DeclaredRole;
     /** the provider it resolves to */

package/dist/validate.js

@@ -181,6 +181,7 @@ export async function validateProject(opts) {
     for (const spec of config.agents) {
         agents.push(checkAgent(root, config, spec, entry, available, record, add));
     }
+    checkReturnPaths(config, add);
     // -----------------------------------------------------------------------
     // Skills
     // -----------------------------------------------------------------------
@@ -244,7 +245,7 @@ async function askModels(targets, opts, add) {
         if (probe.check.state === 'live') {
             return;
         }
-        const where = `${report.role} "${report.name}"${report.provider ? ` (${report.provider})` : ''}`;
+        const where = named(report);
         if (probe.check.state === 'blocked') {
             const pick = report.role === 'embedding' ? '--embedding' : '--chat';
             add({
@@ -576,6 +577,75 @@ function checkAgent(root, config, spec, entry, available, record, add) {
         ownSandbox: Boolean(spec.sandbox),
     };
 }
+/**
+ * Every hand-off must be returnable.
+ *
+ * A hand-off is a one-way door: control moves to the other agent and stays
+ * there. Nothing hands it back on its own, so an agent reached by an edge that
+ * has no way home owns the conversation for the rest of the session — the next
+ * question, whatever it is about, is answered by the specialist the router sent
+ * the user to. That is not a runtime error; it is a system that quietly stops
+ * being the system that was drawn.
+ *
+ * So for every `A → B` there must be a path from B back to A. Indirect counts:
+ * `B → C → A` is a way home, which is the same as saying every hand-off edge
+ * lies on a cycle.
+ *
+ * Forks are exempt, and always will be. A branch runs, answers, and control
+ * returns to the agent that forked it — the return is the mechanism, not an
+ * edge someone has to remember to declare. An agent that wants an answer rather
+ * than to give up the conversation should fork, not hand off.
+ *
+ * A warning rather than an error: the project loads, runs, and answers. What it
+ * cannot do is come back. `--strict` is for the repository that wants that to
+ * fail the build.
+ */
+function checkReturnPaths(config, add) {
+    const known = new Set(config.agents.map((a) => a.name));
+    // Unknown names and self-hand-offs are already errors of their own; walking
+    // them here would only report the same mistake in a second vocabulary.
+    const edges = new Map(config.agents.map((a) => [
+        a.name,
+        (a.handoffs ?? []).filter((to) => to !== a.name && known.has(to)),
+    ]));
+    const reaches = (from, to) => {
+        const seen = new Set([from]);
+        const queue = [from];
+        while (queue.length) {
+            for (const next of edges.get(queue.shift()) ?? []) {
+                if (next === to) {
+                    return true;
+                }
+                if (!seen.has(next)) {
+                    seen.add(next);
+                    queue.push(next);
+                }
+            }
+        }
+        return false;
+    };
+    for (const [from, targets] of edges) {
+        for (const to of targets) {
+            if (reaches(to, from)) {
+                continue;
+            }
+            add({
+                severity: 'warning',
+                code: 'handoff.one-way',
+                where: `agents.${from}.handoffs`,
+                message: `"${to}" has no way back to "${from}": nothing it can hand off to, ` +
+                    `directly or through another agent, reaches "${from}" again. A hand-off ` +
+                    `does not return by itself, so once control moves to "${to}" it stays ` +
+                    `there — every later question in the session is answered by "${to}", ` +
+                    'whether or not it is that agent’s job',
+                fix: `add "${from}" to agents.${to}.handoffs (or to the handoffs of an agent ` +
+                    `"${to}" can reach), or — if "${from}" wants an answer rather than to give ` +
+                    `up the conversation — drop the edge and declare fork: { agents: [${to}] } ` +
+                    `on "${from}", because a branch returns on its own`,
+            });
+        }
+    }
+}
 async function checkSkills(root, config, available, record, add) {
     const declared = config.skills
         ? Array.isArray(config.skills)
@@ -1183,6 +1253,15 @@ function checkModels(root, config, keys, add, probe = false) {
             if (keys) {
                 report.credential = held.present ? 'present' : 'missing';
             }
+            // An alias is the one name the provider has never heard of, so the
+            // report says what it stands for — otherwise `main was refused`
+            // names nothing anyone can look up or retype.
+            const spec = typeof ref === 'string' ? registry.parse(ref) : ref;
+            const api = 'api' in spec && spec.api ? `/${spec.api}` : '';
+            const resolved = `${need.provider}${api}:${spec.model}`;
+            if (resolved !== name) {
+                report.ref = resolved;
+            }
         }
         catch (err) {
             add({
@@ -1208,7 +1287,7 @@ function checkModels(root, config, keys, add, probe = false) {
             add({
                 severity: 'warning',
                 code: `credential.${issue.reason}`,
-                where: `${role} "${name}" (${issue.provider})`,
+                where: named(report, issue.provider),
                 message: issue.reason === 'missing'
                     ? `nothing to authenticate with — ${issue.env} is not set, and the ` +
                         'keyring holds no key for this provider'
@@ -1257,6 +1336,12 @@ function checkModels(root, config, keys, add, probe = false) {
     }
     return { providers: registry.names(), models, targets };
 }
+/** How a finding names a model: as written, and as resolved when the two differ. */
+function named(report, provider = report.provider) {
+    return (`${report.role} "${report.name}"` +
+        (report.ref ? ` = ${report.ref}` : '') +
+        (provider ? ` (${provider})` : ''));
+}
 /** The config key a bad reference was written under. */
 function whereFor(config, role, name, usedBy) {
     if (role === 'embedding') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.10",
+    "version": "1.1.12",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.10",
+        "@zenera/neo": "^1.1.12",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",