@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/ui/overlays/team-fanout-state.js

@@ -0,0 +1,97 @@
+/**
+ * Settings > Team fan-out: the pure half of the page (subagent-fanout 3.4.2).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE PAGE WRITES THREE KEYS AND CANNOT BE MADE TO WRITE A FOURTH (D-17 /
+ * R-P0-1). `TeamFanoutPatch` is `Pick<TeamConfig, 'maxSubagents' |
+ * 'maxConcurrent' | 'overseer'>`, and `stepFanoutValue` returns
+ * `Partial<TeamFanoutPatch>`: a width adjustment therefore CANNOT carry `model`
+ * or `modelProfileId` into `draft.patch.team`. That matters because
+ * `releasedSlots` reads those two keys as "the user re-decided the subagent
+ * slot", so a page that returned the whole section would silently release the
+ * model a session kit had just installed - and no test would notice, because
+ * every value on screen would still be right.
+ *
+ * EVERYTHING HERE IS A PURE FUNCTION over the draft. The page owns exactly one
+ * piece of state (its cursor); values come from the reducer, which is the same
+ * discipline the rest of this screen follows.
+ */
+import { clampTeamConfig, HARD_MAX_SUBAGENTS } from '../../config/schema.js';
+function clampInt(value, min, max) {
+    return Math.max(min, Math.min(max, Math.floor(value)));
+}
+/**
+ * The CLAMPED team section this draft would save (R-P0-2), for display only.
+ *
+ * THE CLAMP IS NOT COSMETIC. Without it a patch carrying only
+ * `maxSubagents: 6` renders "6 per dispatch, 8 at once" on top of an 8-wide
+ * baseline, while `mergePersistedConfig` clamps the same patch to 6/6 on the way
+ * to disk - so the screen and the file disagree, and every arrow key makes the
+ * user reconcile them by hand.
+ */
+export function teamFanoutValues(draft) {
+    return clampTeamConfig({ ...draft.baseline.team, ...draft.patch.team });
+}
+/**
+ * The PATCH FRAGMENT for one arrow press, clamped exactly like `clampTeamConfig`.
+ *
+ * `current` must be the value the screen actually shows (`teamFanoutValues`), so
+ * a step always starts from a number the user can see.
+ *
+ * NO WRAPAROUND: a form control is not a ring, and `Left` at 1 jumping to 10
+ * would be a way to widen a dispatch while trying to narrow it.
+ */
+export function stepFanoutValue(current, field, delta) {
+    if (field === 'overseer') {
+        // Both arrows toggle: `Supervisor` has two states, so a direction has no
+        // meaning beyond "the user pressed an arrow".
+        return { overseer: !current.overseer };
+    }
+    if (field === 'maxConcurrent') {
+        const ceiling = Math.min(HARD_MAX_SUBAGENTS, current.maxSubagents);
+        return { maxConcurrent: clampInt(current.maxConcurrent + delta, 1, ceiling) };
+    }
+    const next = clampInt(current.maxSubagents + delta, 1, HARD_MAX_SUBAGENTS);
+    // THE FOLLOW-DOWN IS WRITTEN INTO THE PATCH (R-P1-9), not just rendered: a
+    // narrower population cannot keep a wider pool, but a DISPLAY-only correction
+    // would snap back the moment the user widened again, so "the change I just
+    // made" would not stick - the exact complaint this design exists to answer.
+    return current.maxConcurrent > next
+        ? { maxSubagents: next, maxConcurrent: next }
+        : { maxSubagents: next };
+}
+/**
+ * The page's three rows.
+ *
+ * TWO HINTS CARRY A CONDITION THE DESIGN OWNS RATHER THAN DECORATION (R-1 / C-2):
+ * the default pool is now 8, which is 8 simultaneous streams against one API key,
+ * and the honest mitigation for an HTTP 429 storm is "lower this number" - said
+ * HERE, where the number is, not only in a risk table nobody reads.
+ */
+export function fanoutRows(team) {
+    return [
+        {
+            field: 'maxSubagents',
+            label: 'Max subagents',
+            value: String(team.maxSubagents),
+            hint: `children per dispatch; ${HARD_MAX_SUBAGENTS} is the hard ceiling`,
+        },
+        {
+            field: 'maxConcurrent',
+            label: 'Run at once',
+            value: String(team.maxConcurrent),
+            hint: 'provider limits: lower this if you see rate-limit errors',
+        },
+        {
+            field: 'overseer',
+            label: 'Supervisor',
+            value: team.overseer ? 'on' : 'off',
+            hint: 'checks stalled children; never kills them',
+        },
+    ];
+}
+/** The one-line summary the settings root row prints for this page. */
+export function fanoutSummary(team) {
+    return `${team.maxSubagents} per dispatch, ${team.maxConcurrent} at once`;
+}

package/dist/ui/shortcuts.d.ts

@@ -0,0 +1,81 @@
+/**
+ * THE shortcut table (tui-shortcut-drawer-and-task-summary §4.6 / appendix B).
+ *
+ * ASCII ONLY, AND THAT IS A HARD CONSTRAINT RATHER THAN A STYLE CHOICE: this file
+ * is inside `glyphs.test.ts::inScope` (`ui/` prefix), whose `A-1` case fails on a
+ * single non-ASCII byte. Every `keyword` and `detail` below is English on
+ * purpose; translating them would turn the scanner red, and the only escape
+ * hatch - adding this file to the exemptions - is the thing that helper's own
+ * comment argues against.
+ *
+ * THIS IS THE ONLY TRUTH ABOUT SHORTCUTS. The drawer, `/keys` and the tests all
+ * derive from it, and `shortcut-table.test.ts` holds it in a BIDIRECTIONAL set
+ * relation with `HelpOverlay`'s key column (D-8). The reverse direction is the
+ * one that matters: without it `Alt+K`, `Esc twice` and `Esc again` could sit in
+ * `/help` forever and never appear in the panel whose entire requirement is
+ * "list ALL of them".
+ *
+ * `keyword` IS CAPPED AT 10 CELLS (`SHORTCUT_PANEL_LIMITS.keywordMaxCells`). A
+ * longer one is a spec error, not a width problem: at 80 columns the keyword
+ * column is 11 cells wide, and the only remaining remedy would be truncating it -
+ * which is the exact defect (a column of `promp...`) this table exists to avoid.
+ */
+export type ShortcutGroupId = 'compose' | 'run' | 'panels' | 'session' | 'view';
+/**
+ * When a row can actually be used. Unavailable rows are STILL LISTED - the user
+ * needs to know the key exists - but they render dim and explain themselves in
+ * the detail line when selected.
+ */
+export type ShortcutAvailability = 'always' | 'idle' | 'running' | 'app' | 'native';
+export interface ShortcutEntry {
+    /** Stable id used by tests and by `/keys <query>`. */
+    id: string;
+    /** The primary binding, spelled in full the way `HelpOverlay` spells it. */
+    keys: string;
+    /** One to two words, ASCII only, at most 10 columns. The requirement's second column. */
+    keyword: string;
+    /** One ASCII sentence, shown when the row is selected. */
+    detail: string;
+    group: ShortcutGroupId;
+    availability: ShortcutAvailability;
+    /** Extra spellings that must also resolve in `/keys <query>`. */
+    aliases?: readonly string[];
+}
+export declare const SHORTCUT_GROUPS: readonly {
+    id: ShortcutGroupId;
+    title: string;
+}[];
+/**
+ * The 31 rows, in reading order. Group order is fixed by `SHORTCUT_GROUPS`, and
+ * within a group the order is "how often a user reaches for it", not alphabetical:
+ * a reference panel is scanned from the top.
+ */
+export declare const SHORTCUTS: readonly ShortcutEntry[];
+/**
+ * The longest `keys` string in cells - the input the column derivation needs.
+ *
+ * DERIVED, NEVER HARD-CODED: v1 fixed the key column at 21 cells, which left six
+ * for the keyword at 80 columns and turned `prompt library` into `promp...`. A
+ * derived value cannot go stale the day someone adds a longer binding.
+ */
+export declare function widestKeysCells(entries: readonly ShortcutEntry[]): number;
+/**
+ * Filter for `/keys <query>`: case-insensitive substring over id, keys, keyword
+ * and aliases.
+ *
+ * NO KEYBOARD SEARCH IN THE PANEL ITSELF (§11 F-2): typing would fight `Esc` for
+ * "clear the filter or close the panel", and `Esc` is App-owned. The command is
+ * the zero-conflict way to reach the same filter.
+ */
+export declare function filterShortcuts(entries: readonly ShortcutEntry[], query: string): ShortcutEntry[];
+/**
+ * Whether a row can be used right now.
+ *
+ * `running` MEANS "ONLY WHILE RUNNING", not "unavailable while running" - the two
+ * halves of the table would otherwise need two different predicates, which is the
+ * kind of asymmetry a later reader gets backwards.
+ */
+export declare function isAvailable(entry: ShortcutEntry, context: {
+    native: boolean;
+    running: boolean;
+}): boolean;

package/dist/ui/shortcuts.js

@@ -0,0 +1,221 @@
+/**
+ * THE shortcut table (tui-shortcut-drawer-and-task-summary §4.6 / appendix B).
+ *
+ * ASCII ONLY, AND THAT IS A HARD CONSTRAINT RATHER THAN A STYLE CHOICE: this file
+ * is inside `glyphs.test.ts::inScope` (`ui/` prefix), whose `A-1` case fails on a
+ * single non-ASCII byte. Every `keyword` and `detail` below is English on
+ * purpose; translating them would turn the scanner red, and the only escape
+ * hatch - adding this file to the exemptions - is the thing that helper's own
+ * comment argues against.
+ *
+ * THIS IS THE ONLY TRUTH ABOUT SHORTCUTS. The drawer, `/keys` and the tests all
+ * derive from it, and `shortcut-table.test.ts` holds it in a BIDIRECTIONAL set
+ * relation with `HelpOverlay`'s key column (D-8). The reverse direction is the
+ * one that matters: without it `Alt+K`, `Esc twice` and `Esc again` could sit in
+ * `/help` forever and never appear in the panel whose entire requirement is
+ * "list ALL of them".
+ *
+ * `keyword` IS CAPPED AT 10 CELLS (`SHORTCUT_PANEL_LIMITS.keywordMaxCells`). A
+ * longer one is a spec error, not a width problem: at 80 columns the keyword
+ * column is 11 cells wide, and the only remaining remedy would be truncating it -
+ * which is the exact defect (a column of `promp...`) this table exists to avoid.
+ */
+import { cellWidth } from './layout/cells.js';
+export const SHORTCUT_GROUPS = [
+    { id: 'compose', title: 'COMPOSE' },
+    { id: 'run', title: 'RUN' },
+    { id: 'panels', title: 'PANELS' },
+    { id: 'session', title: 'SESSION' },
+    { id: 'view', title: 'VIEW' },
+];
+/**
+ * The 31 rows, in reading order. Group order is fixed by `SHORTCUT_GROUPS`, and
+ * within a group the order is "how often a user reaches for it", not alphabetical:
+ * a reference panel is scanned from the top.
+ */
+export const SHORTCUTS = [
+    // --- COMPOSE ---------------------------------------------------------------
+    {
+        id: 'enter', keys: 'Enter', keyword: 'send', group: 'compose', availability: 'always',
+        detail: 'Submits when idle; queues as steering while running;'
+            + ' re-pins the view to the newest output.',
+    },
+    {
+        id: 'alt-enter', keys: 'Alt+Enter', keyword: 'newline', group: 'compose',
+        availability: 'always',
+        detail: 'Multiline input; the host may intercept this combination.',
+    },
+    {
+        id: 'shift-enter', keys: 'Shift+Enter', keyword: 'newline', group: 'compose',
+        availability: 'always',
+        detail: 'Needs keyboard enhancement; /terminal-setup explains how to bind it.',
+    },
+    {
+        id: 'ctrl-j', keys: 'Ctrl+J', keyword: 'newline', group: 'compose', availability: 'always',
+        detail: 'Newline fallback that does not depend on keyboard enhancement.',
+    },
+    {
+        id: 'history', keys: 'Up / Down', keyword: 'history', group: 'compose', availability: 'always',
+        detail: 'Recalls earlier prompts when the input box is empty.',
+    },
+    {
+        id: 'paste', keys: 'Paste', keyword: 'paste', group: 'compose', availability: 'always',
+        detail: 'Up to 6 lines inserted as-is; larger becomes [Pasted text #N]; --no-paste disables.',
+    },
+    {
+        id: 'ctrl-o', keys: 'Ctrl+O', keyword: 'expand', group: 'compose', availability: 'always',
+        detail: 'Expands the newest tool output; in native mode it reprints it as a new block.',
+    },
+    {
+        id: 'ctrl-c', keys: 'Ctrl+C', keyword: 'copy/exit', group: 'compose', availability: 'always',
+        aliases: ['Ctrl+C (with a selection)'],
+        detail: 'Copies a pending selection; with a draft x2 clears and x3 exits;'
+            + ' empty input x2 exits.',
+    },
+    // --- RUN -------------------------------------------------------------------
+    {
+        id: 'esc', keys: 'Esc', keyword: 'close', group: 'run', availability: 'always',
+        detail: 'Closes the open overlay or menu; with nothing open it arms the interrupt ladder.',
+    },
+    {
+        id: 'esc-twice', keys: 'Esc twice', keyword: 'interrupt', group: 'run', availability: 'running',
+        aliases: ['Esc again'],
+        detail: 'Requests an interrupt within 1.5s; the next press forces the stop.',
+    },
+    {
+        id: 'shift-tab', keys: 'Shift+Tab', keyword: 'plan mode', group: 'run', availability: 'always',
+        detail: 'Toggles BUILD and PLAN; writes are refused and the agent only investigates.',
+    },
+    {
+        id: 'ctrl-n', keys: 'Ctrl+N', keyword: 'plan mode', group: 'run', availability: 'always',
+        detail: 'The same toggle, for Windows consoles that cannot deliver Shift+Tab.',
+    },
+    {
+        id: 'ctrl-t', keys: 'Ctrl+T', keyword: 'thinking', group: 'run', availability: 'always',
+        detail: "Shows or hides the model's thinking (off by default).",
+    },
+    {
+        id: 'ctrl-r', keys: 'Ctrl+R', keyword: 'redraw', group: 'run', availability: 'always',
+        detail: 'Repaints the whole frame; use it when the terminal is garbled.',
+    },
+    // --- PANELS ----------------------------------------------------------------
+    {
+        id: 'ctrl-g', keys: 'Ctrl+G', keyword: 'all keys', group: 'panels', availability: 'always',
+        detail: 'Opens this panel; a second Ctrl+G closes it. Every shortcut is listed here.',
+    },
+    {
+        id: 'ctrl-b', keys: 'Ctrl+B', keyword: 'agents', group: 'panels', availability: 'always',
+        detail: 'Read-only subagent board: every child, its facts and its timeline.',
+    },
+    {
+        id: 'ctrl-p', keys: 'Ctrl+P', keyword: 'prompts', group: 'panels', availability: 'always',
+        detail: 'Quick prompt library: pick, edit, reorder.',
+    },
+    {
+        id: 'ctrl-k', keys: 'Ctrl+K', keyword: 'kits', group: 'panels', availability: 'always',
+        detail: 'Switch the main / fast / subagent model kit for this session.',
+    },
+    {
+        id: 'ctrl-i', keys: 'Ctrl+I', keyword: 'index', group: 'panels', availability: 'idle',
+        detail: 'Unavailable while running; asks first, then runs the project-indexer skill.',
+    },
+    {
+        id: 'alt-k', keys: 'Alt+K', keyword: 'kill line', group: 'panels', availability: 'always',
+        detail: 'Deletes from the cursor to the end of the line'
+            + ' (this was Ctrl+K before the kit picker).',
+    },
+    {
+        id: 'help', keys: '/help', keyword: 'reference', group: 'panels', availability: 'always',
+        detail: 'Full reference: keys, slash commands, plan mode, team, skills.',
+    },
+    // --- SESSION ---------------------------------------------------------------
+    {
+        id: 'ctrl-l', keys: 'Ctrl+L', keyword: 'branch', group: 'session', availability: 'always',
+        detail: 'Opens this session in a new terminal window with its own session id.',
+    },
+    {
+        id: 'clear', keys: '/clear', keyword: 'new task', group: 'session', availability: 'always',
+        detail: 'Archives the old conversation, clears the context;'
+            + ' the task summary is cleared with it.',
+    },
+    {
+        id: 'resume', keys: '/resume', keyword: 'switch', group: 'session', availability: 'always',
+        detail: 'Loads a saved session; the current session moves to a new id.',
+    },
+    {
+        id: 'session', keys: '/session', keyword: 'identity', group: 'session', availability: 'always',
+        detail: 'Shows the session id and file, copies the resume command, pins the id.',
+    },
+    // --- VIEW ------------------------------------------------------------------
+    {
+        id: 'page', keys: 'PgUp / PgDn', keyword: 'page', group: 'view', availability: 'always',
+        detail: 'Pages the transcript, or the overlay that currently owns the keyboard.',
+    },
+    {
+        id: 'wheel', keys: 'Wheel', keyword: 'scroll', group: 'view', availability: 'app',
+        detail: 'Scrolls the transcript in app mode; in native mode the terminal owns this.',
+    },
+    {
+        id: 'shift-wheel', keys: 'Shift+Wheel', keyword: 'page', group: 'view', availability: 'app',
+        detail: 'Scrolls a whole page.',
+    },
+    {
+        id: 'shift-arrows', keys: 'Shift+Up / Shift+Down', keyword: 'line', group: 'view',
+        availability: 'app',
+        detail: 'Scrolls one line; native mode leaves this to the terminal.',
+    },
+    {
+        id: 'drag-edge', keys: 'Drag right edge', keyword: 'scrollbar', group: 'view',
+        availability: 'app',
+        detail: 'Drags the right-edge scrollbar; the input stays fixed.',
+    },
+    {
+        id: 'drag-text', keys: 'Drag text (left button)', keyword: 'select', group: 'view',
+        availability: 'app',
+        detail: 'Drags to select on-screen text; the highlight waits for a copy.',
+    },
+];
+/**
+ * The longest `keys` string in cells - the input the column derivation needs.
+ *
+ * DERIVED, NEVER HARD-CODED: v1 fixed the key column at 21 cells, which left six
+ * for the keyword at 80 columns and turned `prompt library` into `promp...`. A
+ * derived value cannot go stale the day someone adds a longer binding.
+ */
+export function widestKeysCells(entries) {
+    return entries.reduce((widest, entry) => Math.max(widest, cellWidth(entry.keys)), 0);
+}
+/**
+ * Filter for `/keys <query>`: case-insensitive substring over id, keys, keyword
+ * and aliases.
+ *
+ * NO KEYBOARD SEARCH IN THE PANEL ITSELF (§11 F-2): typing would fight `Esc` for
+ * "clear the filter or close the panel", and `Esc` is App-owned. The command is
+ * the zero-conflict way to reach the same filter.
+ */
+export function filterShortcuts(entries, query) {
+    const needle = query.trim().toLowerCase();
+    if (needle.length === 0)
+        return [...entries];
+    return entries.filter((entry) => {
+        const haystack = [entry.id, entry.keys, entry.keyword, ...(entry.aliases ?? [])];
+        return haystack.some((field) => field.toLowerCase().includes(needle));
+    });
+}
+/**
+ * Whether a row can be used right now.
+ *
+ * `running` MEANS "ONLY WHILE RUNNING", not "unavailable while running" - the two
+ * halves of the table would otherwise need two different predicates, which is the
+ * kind of asymmetry a later reader gets backwards.
+ */
+export function isAvailable(entry, context) {
+    switch (entry.availability) {
+        case 'always': return true;
+        case 'idle': return !context.running;
+        case 'running': return context.running;
+        case 'app': return !context.native;
+        case 'native': return context.native;
+        default: return true;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.38",
+  "version": "0.6.40",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.50",
+    "@aragon-agent/core": "^0.2.52",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",