@aragon-agent/cli 0.6.35 → 0.6.36

package/dist/ui/layout/cells.js

@@ -0,0 +1,156 @@
+/**
+ * Display-width cell arithmetic (tui-subagent-panel §5 #1).
+ *
+ * EVERY FUNCTION HERE IS PURE AND TOTAL: no Ink, no clock, no terminal, and no
+ * input that throws. The panel row and the Agents board both need to place text
+ * in a FIXED number of terminal columns, and `padEnd` cannot do that: it counts
+ * code units while a terminal counts cells, so a CJK description padded with
+ * `padEnd` overflows its box by one column per wide character and pushes the
+ * next cell off the row. That is exactly the defect this round removes from the
+ * roster, one layer down.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so the
+ * ellipsis and any other symbol a caller wants must be passed IN (the board
+ * hands over `glyphs.ellipsis`), never spelled here.
+ */
+import stringWidth from 'string-width';
+/** Invalid geometry becomes zero, exactly like the layout modules' `nonNegativeInt`. */
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/** Display columns a string occupies, or 0 for a non-string (defensive at the edge only). */
+export function cellWidth(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return 0;
+    return stringWidth(text);
+}
+/**
+ * Cut `text` to at most `cells` display columns, marking the cut with `ellipsis`.
+ *
+ * THE ELLIPSIS IS PART OF THE BUDGET, not an extra column: a caller that asks for
+ * 8 cells gets a string that MEASURES 8, which is what makes a fixed-width cell
+ * a cell rather than a hope. When the budget cannot hold the ellipsis plus one
+ * character, the string is hard-cut instead - a marker wider than the cell it
+ * marks is the one outcome worse than no marker.
+ *
+ * Wide characters are never split: a surrogate pair or a double-width glyph that
+ * does not fit is dropped whole, so the result can measure one column less than
+ * asked but never one more.
+ */
+export function fitCells(text, cells, ellipsis = '...') {
+    const budget = nonNegativeInt(cells);
+    if (budget === 0)
+        return '';
+    if (cellWidth(text) <= budget)
+        return text;
+    const mark = cellWidth(ellipsis) < budget ? ellipsis : '';
+    const room = budget - cellWidth(mark);
+    let out = '';
+    let used = 0;
+    // `Array.from` iterates by CODE POINT, so a surrogate pair is one step and can
+    // never be cut in half by this loop.
+    for (const char of Array.from(text)) {
+        const width = cellWidth(char);
+        if (used + width > room)
+            break;
+        out += char;
+        used += width;
+    }
+    return `${out}${mark}`;
+}
+/**
+ * Pad `text` to exactly `cells` columns (or leave it alone when it already
+ * measures at least that).
+ *
+ * NOT `padEnd`: see this file's header. A padded cell is what keeps the next
+ * column at a stable offset, which is the whole point of the panel's table.
+ */
+export function padCells(text, cells) {
+    const budget = nonNegativeInt(cells);
+    const width = cellWidth(text);
+    if (width >= budget)
+        return text;
+    return `${text}${' '.repeat(budget - width)}`;
+}
+/** `fitCells` then `padCells`: the result ALWAYS measures exactly `cells`. */
+export function alignRightCells(text, cells, ellipsis = '...') {
+    const budget = nonNegativeInt(cells);
+    return padCells(fitCells(text, budget, ellipsis), budget);
+}
+/**
+ * Fold `text` into at most `maxRows` lines of at most `cells` columns each.
+ *
+ * BREAKS AT SPACES, HARD-CUTS ONLY WHEN A SINGLE TOKEN CANNOT FIT: a word that is
+ * wider than the column is the one case where an honest over-long token beats a
+ * line of nothing, so it is cut rather than pushed to a line that still cannot
+ * hold it. The last allowed line, when text remains, carries the `(+N lines)`
+ * tail so the reader learns that the section was truncated instead of believing
+ * the prose ended mid-sentence.
+ *
+ * Pure and total: `cells <= 0` or `maxRows <= 0` yields no lines, and the caller
+ * decides what an empty section means (the board omits it).
+ */
+export function wrapCells(text, cells, maxRows, ellipsis = '...') {
+    const width = nonNegativeInt(cells);
+    const limit = nonNegativeInt(maxRows);
+    const flat = (text ?? '').replace(/\s+/g, ' ').trim();
+    if (width === 0 || limit === 0 || flat.length === 0) {
+        return { lines: [], dropped: flat.length === 0 ? 0 : limit === 0 ? 1 : 0 };
+    }
+    const lines = [];
+    let rest = flat;
+    while (rest.length > 0) {
+        if (cellWidth(rest) <= width) {
+            lines.push(rest);
+            rest = '';
+            break;
+        }
+        const cut = breakCells(rest, width);
+        lines.push(cut.line);
+        rest = cut.rest;
+    }
+    if (lines.length <= limit)
+        return { lines, dropped: 0 };
+    const kept = lines.slice(0, limit);
+    const dropped = lines.length - limit;
+    const tail = `(+${dropped} lines)`;
+    // THE ANNOUNCEMENT IS RESERVED, not appended and then truncated away: a reader who
+    // sees prose stop mid-sentence with no marker reads it as the end of the fact, which
+    // is exactly the wrong conclusion. When the column is too narrow to hold the marker
+    // at all, the line is simply cut - the caller's section is unusable at that width.
+    const tailCells = cellWidth(tail) + 1;
+    const last = kept[limit - 1] ?? '';
+    kept[limit - 1] = tailCells < width
+        ? `${fitCells(last, width - tailCells, ellipsis)} ${tail}`
+        : fitCells(last, width, ellipsis);
+    return { lines: kept, dropped };
+}
+/**
+ * The longest prefix of `text` that fits `width` columns, preferring a space.
+ *
+ * Returns the consumed line and what is left, so the caller's loop is one
+ * assignment per iteration and the "one function does one thing" rule holds.
+ */
+function breakCells(text, width) {
+    let used = 0;
+    let taken = 0;
+    let lastSpace = -1;
+    for (const char of Array.from(text)) {
+        const charWidth = cellWidth(char);
+        if (used + charWidth > width)
+            break;
+        used += charWidth;
+        taken += char.length;
+        if (char === ' ')
+            lastSpace = taken;
+    }
+    // A single token wider than the column: hard-cut it rather than emit nothing.
+    if (taken === 0) {
+        const first = Array.from(text)[0] ?? '';
+        return { line: fitCells(first, width), rest: text.slice(first.length) };
+    }
+    if (lastSpace > 0) {
+        return { line: text.slice(0, lastSpace).trimEnd(), rest: text.slice(lastSpace).trimStart() };
+    }
+    return { line: text.slice(0, taken), rest: text.slice(taken).trimStart() };
+}

package/dist/ui/layout/header-hints.d.ts

@@ -46,7 +46,7 @@ export declare const HEADER_HINT_LIMITS: {
      */
     readonly separatorCells: 2;
 };
-export type HeaderHintId = 'branch' | 'index' | 'kit' | 'detail';
+export type HeaderHintId = 'branch' | 'prompts' | 'index' | 'kit' | 'detail';
 export interface HeaderHintClause {
     id: HeaderHintId;
     text: string;
@@ -66,8 +66,9 @@ export interface HeaderHintPlan {
 /**
  * Plan the right-hand hints.
  *
- * The four inputs are exactly the props `Header` already receives - the call site
- * does not change, only the arithmetic behind it (spec 3.11 step 5).
+ * The inputs are the props `Header` receives plus the two switches that decide which
+ * clauses exist at all - the call site does not change, only the arithmetic behind it
+ * (spec 3.11 step 5).
  */
 export declare function planHeaderHints(input: {
     columns: number;
@@ -84,4 +85,13 @@ export declare function planHeaderHints(input: {
      * switch, and it degrades the six expanded rungs back into today's four.
      */
     kitHint?: boolean;
+    /**
+     * Whether the `^P prompts` clause exists at all (default `true`).
+     *
+     * `false` is the `prompts.hint` config key and the only reason the ladder is
+     * parameterised: a user who turned the header hint off must get exactly the row
+     * they had before this feature, which is what the unfiltered ladder below
+     * degenerates into.
+     */
+    promptsHint?: boolean;
 }): HeaderHintPlan;

package/dist/ui/layout/header-hints.js

@@ -58,6 +58,25 @@ const INDEX_CLAUSE = { collapsed: '^I Index', expanded: '^I build index' };
  * leftward on every launch for a key pressed twice a session.
  */
 const KIT_CLAUSE = { expanded: '^K switch kit' };
+/**
+ * THE PROMPT LIBRARY KEY HAS EXACTLY ONE FORM, AND IT IS THE SHORT ONE
+ * (quick-prompt-library D-15).
+ *
+ * `^P` is a REQUIREMENT (the user must be able to see that `ctrl+P` exists), and
+ * the collapsed row is where that requirement is met. The expanded row's job is to
+ * reveal MORE keys than the collapsed one, so inserting a 17-cell
+ * `^P prompt library` before `^I` there would trade `^I` and `^K` away on an
+ * 80-column terminal - a user who pressed `^G` asking for more would be shown less.
+ *
+ * The second thing this constant's position encodes is an explicit REVISION of the
+ * `RV-P1-2` ordering constraint for the COLLAPSED ladder: `^P` sits before `^I`
+ * there, so `^I Index` now appears from 66 columns instead of 54. That is a
+ * deliberate, documented loss: `^I` is a once-per-project action and `^P` is the
+ * entry point this feature is about. The expanded ladder keeps its full existing
+ * order, so `RV-P1-2` still holds there and `^I` never disappears from a row where
+ * it used to fit.
+ */
+const PROMPTS_CLAUSE = '^P prompts';
 const DETAIL_CLAUSE = { collapsed: '^G more', expanded: '^G less' };
 /** L3 gives the key name and nothing else: discoverability at the last width. */
 const BRANCH_KEY_ONLY = '^L';
@@ -69,8 +88,9 @@ const SCROLL_CHIP_MAX = 9999;
 /**
  * Plan the right-hand hints.
  *
- * The four inputs are exactly the props `Header` already receives - the call site
- * does not change, only the arithmetic behind it (spec 3.11 step 5).
+ * The inputs are the props `Header` receives plus the two switches that decide which
+ * clauses exist at all - the call site does not change, only the arithmetic behind it
+ * (spec 3.11 step 5).
  */
 export function planHeaderHints(input) {
     // NORMALISED HERE, NOT TRUSTED (R-14). `Header` defaults to 80, but a test or a
@@ -86,7 +106,7 @@ export function planHeaderHints(input) {
         const detail = input.statusExpanded ? DETAILS_ON : DETAILS_OFF;
         return buildPlan([{ id: 'detail', text: detail }], scrollCells, true);
     }
-    const ladder = ladderFor(input.statusExpanded, input.kitHint !== false);
+    const ladder = ladderFor(input.statusExpanded, input.kitHint !== false, input.promptsHint !== false);
     // THE SEPARATOR IS SPENT OUT OF THE SAME ROW (defect 12): left half + gap + this
     // column have to add up to `columns`, so the gap comes off the budget instead of
     // being assumed free.
@@ -114,7 +134,7 @@ export function planHeaderHints(input) {
  * `^I` everything from 64 to 78 columns - a permanent loss, paid for a
  * low-frequency key.
  */
-function ladderFor(statusExpanded, kitHint) {
+function ladderFor(statusExpanded, kitHint, promptsHint) {
     const branch = {
         id: 'branch',
         text: statusExpanded ? BRANCH_CLAUSE.expanded : BRANCH_CLAUSE.collapsed,
@@ -127,25 +147,39 @@ function ladderFor(statusExpanded, kitHint) {
         id: 'detail',
         text: statusExpanded ? DETAIL_CLAUSE.expanded : DETAIL_CLAUSE.collapsed,
     };
-    const base = [
-        [branch, index, detail],
+    const branchKey = { id: 'branch', text: BRANCH_KEY_ONLY };
+    const prompts = { id: 'prompts', text: PROMPTS_CLAUSE };
+    const kit = { id: 'kit', text: KIT_CLAUSE.expanded };
+    // THE LADDERS ARE WRITTEN WITH EVERY CLAUSE IN PLACE AND THEN FILTERED, rather
+    // than branched per width. Two independently written tables drift: the day one of
+    // them gains a rung, the `prompts.hint=false` / `kitHint=false` degradations stop
+    // being "the same row minus that clause" and nothing would notice. Filtering a
+    // single table makes that property structural.
+    const keep = (clause) => (promptsHint || clause.id !== 'prompts') && (kitHint || clause.id !== 'kit');
+    // COLLAPSED (six rungs). `^P prompts` sits between the branch and the index, and
+    // the third rung is where `^L` loses its label in favour of `^P` - see the note
+    // on `PROMPTS_CLAUSE` above for the revision of `RV-P1-2` this encodes.
+    const collapsed = [
+        [branch, prompts, index, detail],
+        [branch, prompts, detail],
+        [branchKey, prompts, detail],
         [branch, detail],
-        [{ id: 'branch', text: BRANCH_KEY_ONLY }, detail],
+        [branchKey, detail],
         [detail],
     ];
-    // THE COLLAPSED LADDER IS UNTOUCHED (D-11): `^K` has no collapsed form, so a
-    // user who never presses `ctrl+G` sees the row they always saw (I-9).
-    if (!statusExpanded || !kitHint)
-        return base;
-    const kit = { id: 'kit', text: KIT_CLAUSE.expanded };
-    return [
+    // EXPANDED (seven rungs). `^P` appears in the WIDEST rung only, and AFTER `^K`,
+    // so E2..E7 - the rungs that decide what a 34..90 column terminal shows - are
+    // byte-identical to the pre-feature answers.
+    const expanded = [
+        [branch, index, kit, prompts, detail],
         [branch, index, kit, detail],
         [branch, index, detail],
         [branch, kit, detail],
         [branch, detail],
-        [{ id: 'branch', text: BRANCH_KEY_ONLY }, detail],
+        [branchKey, detail],
         [detail],
     ];
+    return (statusExpanded ? expanded : collapsed).map((rung) => rung.filter(keep));
 }
 /**
  * Compose the final string. The chip carries its OWN trailing spacing and is the

package/dist/ui/layout/status-detail-layout.js

@@ -55,6 +55,15 @@ export function planStatusDetail(input) {
         add(statusField('team', 'Team ' + status.teamActive.running + '/' + status.teamActive.total));
     if (status.todoActive)
         add(statusField('todo', 'Todo ' + status.todoActive.done + '/' + status.todoActive.total));
+    // AFTER `todo`, AND THE ORDER IS THE PRIORITY (D-12): `add()` only appends while
+    // the whole row still fits, so a later field is dropped FIRST. `Todo 3/7` is the
+    // more important of the two numbers, so it goes first and survives the narrower
+    // terminal; `Accept 2/5` degrades before it.
+    if (status.acceptanceActive) {
+        const acceptance = status.acceptanceActive;
+        add(statusField('acceptance', 'Accept ' + acceptance.checked + '/' + acceptance.total
+            + (acceptance.failed > 0 ? ' !' + acceptance.failed : ''), acceptance.failed > 0 ? 'error' : 'normal'));
+    }
     add(statusField('model', input.provider + ':' + input.model));
     if (status.fastActive)
         add(statusField('fast', 'Fast' + (status.fastActive.inFlight ? ' active' : '')));

package/dist/ui/layout/status-layout.d.ts

@@ -51,6 +51,19 @@ export interface StatusLayoutInput {
         done: number;
         total: number;
     };
+    /**
+     * The acceptance counter (todo-acceptance-criteria §6.11).
+     *
+     * A FALLBACK, exactly like `todoActive`: present only when the rail is NOT already
+     * reporting the number, because printing `2/5` twice in one row is the defect
+     * RV-P2-4 records. Whether it is present is decided by `acceptanceChip()` in
+     * `ui/layout/todo-layout.ts`, which owns "what did the rail actually draw".
+     */
+    acceptanceActive?: {
+        checked: number;
+        total: number;
+        failed: number;
+    };
     ecoRung?: number;
     fastActive?: {
         inFlight: boolean;

package/dist/ui/layout/team-row.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Panel row geometry — the ONE authority for how a subagent row is measured and
+ * what it says (tui-subagent-panel §4.2 / §6.1).
+ *
+ * WHY THIS FILE EXISTS. The roster used to place its right-hand columns by
+ * `flexGrow`, and a fixed-height parent box makes Yoga stretch the column to its
+ * widest CHILD instead of to the available width: on a 100-column terminal inside
+ * the band slot the row measured 48 (spec §0.1, cases 3/4), so `grep  22.1s` sat
+ * hard against the description and the right half of the row was blank. Flex
+ * cannot fix that, because the number it needs - "how wide is this terminal" - is
+ * not part of the layout it is given. So the widths are COMPUTED here, by a total
+ * pure function, and the component only places fixed-width boxes at the offsets
+ * this module names.
+ *
+ * THE FIVE CELLS, in drawing order:
+ *
+ *     marker(1+status+1) label(8) description(flex) gap(2) activity(n) clock(8)
+ *
+ * `description` is the ONLY flexible cell, and it is the one that absorbs every
+ * width pressure - the same degradation discipline `StatusBar` documents for its
+ * left cluster. The two right-hand cells are fixed and `flexShrink={0}`, so their
+ * absolute offsets follow from `rowWidth = parentWidth` and the sum of the fixed
+ * cells in front of them, and never from how a particular frame allocates slack.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan.
+ *
+ * THE ACTIVITY HELPERS LIVE HERE TOO (v2 implementation note, recorded in the
+ * spec's "implementation findings"). `teamRowCells` has to compose the activity
+ * text with the supervisor badge, which is what `activityWithBadge` already does;
+ * leaving those in `TeamPanel.tsx` would make this module and the component
+ * import each other. `TeamPanel` therefore RE-EXPORTS every symbol below, so the
+ * existing import sites (three test files) keep their import path unchanged.
+ */
+import type { OverseerAction, SubagentRun } from '../../team/types.js';
+import type { Glyphs } from '../glyphs.js';
+/** The clock cell: wide enough for `125m07s` (7) with one column of headroom. */
+export declare const TEAM_CLOCK_CELLS = 8;
+/** `run.label.padEnd(8).slice(0,8)` — unchanged from the row this replaces. */
+export declare const TEAM_LABEL_CELLS = 8;
+/** The two spaces in front of the activity cell. */
+export declare const TEAM_GAP_CELLS = 2;
+/**
+ * The description column's floor: below this the row is unreadable, so the
+ * activity cell gives way instead (`activityDropCols`).
+ */
+export declare const TEAM_MIN_DESCRIPTION_CELLS = 12;
+export interface TeamRowGeometry {
+    marker: number;
+    label: number;
+    gap: number;
+    activity: number;
+    clock: number;
+    /** The description column's reserved MINIMUM; the real width comes from flex. */
+    minDescription: number;
+}
+/**
+ * How many characters the activity cell may spend at this width.
+ *
+ * `TEAM_LIMITS.activityChars` is a STORAGE ceiling; a terminal has a COLUMN
+ * budget, and the two are not the same number. Below
+ * `TEAM_LIMITS.activityDropCols` the cell gives way ENTIRELY (returns 0) rather
+ * than shrinking to its 12-character floor: at 40 columns those twelve characters
+ * would push the description below its own floor, and "who is doing what" outranks
+ * "what they are writing right now" exactly when there is room for one of them.
+ * That is a semantic change to a shipped assertion (`activityBudget(40)` used to
+ * return 12) and is recorded in the spec's §10 collateral table.
+ *
+ * `markerCells` defaults to the Unicode tier so the three existing single-argument
+ * call sites keep compiling; the panel passes the real tier's width.
+ */
+export declare function activityBudget(cols: number, markerCells?: number): number;
+/**
+ * The row's cell widths. A TOTAL function: every cell is a non-negative integer
+ * and the five of them never sum past `cols`, for any `cols >= 0` and either
+ * glyph tier (I-3, `team-row-geometry.test.ts`'s property test).
+ *
+ * THE LADDER IS THE SPECIFICATION (§4.2.2), in the order the cells give way:
+ *   1. a wide enough terminal gets the business budget;
+ *   2. below `activityDropCols` the activity cell is 0;
+ *   3. description still negative -> the gap goes;
+ *   4. still negative -> the label shrinks to `max(3, cols - marker - clock)`;
+ *   5. still negative -> the clock shrinks (`cols < marker + 3 + clock`);
+ *   6. the residue (a terminal narrower than the marker itself) is clamped so the
+ *      sum stays inside `cols` — unreachable on a real device, where native mode
+ *      degrades to the placeholder below 40x12, but the function is total because
+ *      the property test runs `cols = 1..400`.
+ */
+export declare function teamRowGeometry(cols: number, glyphs: Glyphs): TeamRowGeometry;
+/**
+ * The clock cell's text: this child's elapsed time, or empty when it never
+ * started (a `queued` row has no clock to show, and `0ms` would be a lie).
+ */
+export declare function teamClockText(run: SubagentRun, at: number): string;
+/** The past-tense word the supervisor badge and status line render. */
+export declare function interventionWord(action: OverseerAction): string;
+/**
+ * The row's supervisor badge (subagent-overseer-v2 AC-5): what the supervisor
+ * last did to THIS child and how long ago, e.g. `nudged 2m03s`.
+ *
+ * `lastIntervention.at` is ABSOLUTE epoch ms (R-P2-3), the same units as
+ * `startedAt`, so this is one subtraction - no second clock convention.
+ */
+export declare function overseerBadge(run: SubagentRun, at: number): string;
+/**
+ * The middle cell: what this child is doing right now, in a few words.
+ *
+ * Two width policies, answering different questions. `wide` decides WHICH FACT to
+ * show - a whole path or its basename, a whole command line or its program name -
+ * mirroring `StatusBar`'s `statusCompactCols` degradation rather than inventing a
+ * second threshold. `activityBudget(cols)` decides HOW MUCH OF IT FITS, and it is
+ * a continuous function of width rather than a threshold, because the failure it
+ * prevents - a row wider than the terminal - is continuous.
+ */
+export declare function activityLine(run: SubagentRun, cols: number, markerCells?: number): string;
+/**
+ * The activity cell WITH the badge composed in (AC-5 / risk table): the badge
+ * rides the SAME allocation the prose uses, so a row can never grow past its
+ * terminal; on a narrow terminal the badge degrades to the action word alone -
+ * the who-acted fact outranks the what-they-are-doing tail exactly when there is
+ * room for only one.
+ */
+export declare function activityWithBadge(run: SubagentRun, cols: number, at: number, markerCells?: number): string;
+/** The five text fragments of one row, each already clamped to its cell's policy. */
+export interface TeamRowCells {
+    marker: string;
+    label: string;
+    description: string;
+    activity: string;
+    clock: string;
+}
+/**
+ * The five text fragments of one row.
+ *
+ * The description is normalized here rather than in the component because
+ * truncation preserves explicit newlines and the band reserves exactly ONE row
+ * for a child: a description carrying a newline would make the row two rows tall
+ * and every row below it would land one row lower than `band.teamRows` allows.
+ */
+export declare function teamRowCells(run: SubagentRun, cols: number, at: number, glyphs: Glyphs): TeamRowCells;