@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/ui/governance-status.js

@@ -0,0 +1,326 @@
+/**
+ * Governance status: snapshot -> display derivations (governance-mode section 10.3).
+ *
+ * Pure: no Ink, no clock (callers inject `now`), no I/O. ASCII ONLY.
+ *
+ * WHAT LIVES HERE AND WHAT DOES NOT. The panel, the chip, the card and the board each
+ * need the same few JUDGEMENTS - which colour a score label gets, whether a score change
+ * is still inside its emphasis window, which pipeline step is current, what an agent's
+ * state looks like to `team-status.ts`. Putting each judgement here once is the same
+ * discipline `team-status.ts` records: the roster, the card and the chip used to disagree
+ * about what "running" looked like because nine files each answered it.
+ *
+ * COLOUR IS A SEMANTIC KEY, NOT A THEME FIELD. The layout modules emit `Tone` values and
+ * the components resolve them through `toneColor`, so a layout test never needs a `Theme`
+ * and a theme change never touches a layout.
+ */
+import { POSTURE_LABEL } from '../governance/posture.js';
+import { MODE_LABEL } from '../agent/agent-mode.js';
+import { GOV_LIMITS } from '../governance/limits.js';
+/**
+ * A table, not a switch: exhaustive over `Tone` at compile time (a new tone is a
+ * missing-key error) and flat in complexity however many tones there are.
+ */
+const TONE_COLOR = {
+    text: (theme) => theme.assistant,
+    muted: (theme) => theme.muted,
+    hint: (theme) => theme.hintFg,
+    border: (theme) => theme.border,
+    primary: (theme) => theme.primary,
+    govern: (theme) => theme.governAccent,
+    ok: (theme) => theme.toolDone,
+    warn: (theme) => theme.noticeWarn,
+    error: (theme) => theme.noticeError,
+    pending: (theme) => theme.toolPending,
+    running: (theme) => theme.toolRunning,
+};
+/** Resolve a tone against a theme. The ONLY place a `Tone` becomes a colour. */
+export function toneColor(tone, theme) {
+    return TONE_COLOR[tone](theme);
+}
+export function segment(text, tone, bold = false) {
+    return bold ? { text, tone, bold } : { text, tone };
+}
+// ---------------------------------------------------------------------------
+// Agent state -> the team roster's vocabulary
+// ---------------------------------------------------------------------------
+/**
+ * A governance agent state, read as a `team-status.ts` `ChildStatus`, so the glyph and
+ * the colour come from THAT module (`statusGlyph` / `statusMarkerCell`) and not from a
+ * second table (spec 10.3, "do not make a second copy").
+ *
+ * `idle` and `queued` are both "not doing anything yet"; `eliminated` borrows the
+ * failure reading because the marker for it is the cross and the colour is the error
+ * colour - the row's TEXT says `replaced by ...`, which is what stops it reading as a
+ * crash.
+ */
+const STATUS_BY_STATE = {
+    queued: 'queued',
+    idle: 'queued',
+    working: 'running',
+    submitted: 'done',
+    failed: 'failed',
+    eliminated: 'failed',
+};
+export function govChildStatus(state) {
+    return STATUS_BY_STATE[state];
+}
+/**
+ * The tone that `statusColor(status, theme)` resolves to, as a key. A test pins the pair
+ * (`toneColor(statusTone(s), theme) === statusColor(s, theme)` for every status and every
+ * theme) so the two tables cannot drift apart.
+ */
+const TONE_BY_STATUS = {
+    queued: 'pending',
+    running: 'running',
+    done: 'ok',
+    failed: 'error',
+    aborted: 'warn',
+};
+export function statusTone(status) {
+    return TONE_BY_STATUS[status];
+}
+export function scoreTone(label) {
+    switch (label) {
+        case 'NORMAL':
+            return 'ok';
+        case 'WARNING':
+            return 'warn';
+        case 'DANGER':
+        case 'KILLED':
+            return 'danger';
+        case 'NOT_SCORED':
+            return 'muted';
+    }
+}
+const TONE_BY_SCORE = {
+    ok: 'ok',
+    warn: 'warn',
+    danger: 'error',
+    muted: 'muted',
+};
+export function scoreToneKey(label) {
+    return TONE_BY_SCORE[scoreTone(label)];
+}
+/** The short word for a label in the roster's tag column; `NORMAL` says nothing. */
+export function labelTag(label) {
+    switch (label) {
+        case 'WARNING':
+            return 'WARN';
+        case 'DANGER':
+            return 'DANGER';
+        case 'KILLED':
+            return 'KILLED';
+        case 'NORMAL':
+        case 'NOT_SCORED':
+            return '';
+    }
+}
+/** Scored agents start here; the gauge is full at this value. */
+export const GAUGE_FULL_SCORE = GOV_LIMITS.initialTokens;
+export const GAUGE_CELLS = 10;
+/**
+ * Filled cells of the 10-cell score gauge: `round(confirmed / 100 * 10)` clamped to
+ * [0, 10] (spec 10.3). Non-finite input draws an empty bar rather than throwing - the
+ * gauge is decoration over a number that is printed beside it.
+ */
+export function gaugeFilledCells(confirmed) {
+    if (!Number.isFinite(confirmed))
+        return 0;
+    const raw = Math.round((confirmed / GAUGE_FULL_SCORE) * GAUGE_CELLS);
+    return Math.min(GAUGE_CELLS, Math.max(0, raw));
+}
+/** `115+` when the score is over the starting value, otherwise the plain number. */
+export function scoreText(confirmed) {
+    const rounded = Math.round(confirmed);
+    return rounded > GAUGE_FULL_SCORE ? `${rounded}+` : String(Math.max(0, rounded));
+}
+// ---------------------------------------------------------------------------
+// Delta emphasis (AC-27)
+// ---------------------------------------------------------------------------
+/** How long a score change stays emphasised on its row. */
+export const DELTA_EMPHASIS_MS = 4000;
+const NO_DELTA = { text: '', tone: 'muted', bold: false };
+/** Signed delta text; a provisional gain carries the `P` suffix (`+15P`). */
+export function signedDeltaText(delta, provisional) {
+    const sign = delta > 0 ? '+' : delta < 0 ? '-' : '';
+    return `${sign}${Math.abs(Math.round(delta))}${provisional && delta > 0 ? 'P' : ''}`;
+}
+/**
+ * The emphasised delta of a row.
+ *
+ * Motion allowed: bold + coloured for `DELTA_EMPHASIS_MS` after the change, then gone.
+ * Reduced motion: nothing is time-windowed, so nothing flashes - the delta stays, plain,
+ * until the engine replaces or clears `lastDelta` at the next phase (spec 10.3 "the
+ * increment text is kept until the next phase"). A zero delta says nothing in either mode.
+ */
+export function deltaCell(row, now, reducedMotion) {
+    const last = row.lastDelta;
+    if (last === null || last.delta === 0)
+        return NO_DELTA;
+    const tone = last.delta > 0 ? 'ok' : 'error';
+    const text = signedDeltaText(last.delta, last.provisional);
+    if (reducedMotion)
+        return { text, tone, bold: false };
+    const age = now - last.at;
+    if (age < 0 || age > DELTA_EMPHASIS_MS)
+        return NO_DELTA;
+    return { text, tone, bold: true };
+}
+/**
+ * Mount rule (D-17): a running stage -> the full panel (which REPLACES the team roster);
+ * a live run between stages -> the two-line strip; no run, a closed run or an abandoned
+ * run -> nothing at all (zero rows, zero layout shift).
+ */
+export function governancePanelMode(snapshot) {
+    if (snapshot === null)
+        return 'none';
+    if (isFinishedRun(snapshot.status))
+        return 'none';
+    return snapshot.stageRunning ? 'panel' : 'run-strip';
+}
+/**
+ * EXACTLY ONE LIVE ROSTER (D-17 / AC-25). A running governed stage owns the region even
+ * though the same children are also in `state.team` (the reducer still writes it for
+ * `/agents`); between stages the two-line strip shows only when no dispatch is live; with
+ * no live governed run the team roster behaves exactly as it always did.
+ */
+export function liveRosterSurface(snapshot, teamLive) {
+    const mode = governancePanelMode(snapshot);
+    if (mode === 'panel')
+        return 'governance';
+    if (mode === 'run-strip' && !teamLive)
+        return 'governance';
+    return teamLive ? 'team' : 'none';
+}
+export function isFinishedRun(status) {
+    return status === 'closed' || status === 'abandoned';
+}
+/** Agents currently doing something: the minimal tier's "4 working". */
+export function workingCount(snapshot) {
+    return snapshot.roster.filter((row) => row.state === 'working').length;
+}
+/** Display position in the pipeline: the active step's key, or the stage, or null. */
+export function activeStepKey(snapshot) {
+    const active = snapshot.pipeline.find((step) => step.state === 'active');
+    if (active !== undefined && active.key !== 'intake')
+        return active.key;
+    return snapshot.stage;
+}
+/** Tokens spent by the governed team (spec 8.5: team tokens, never the session total). */
+export function teamTokens(snapshot) {
+    return snapshot.usage.inputTokens + snapshot.usage.outputTokens;
+}
+/**
+ * Budget readout for the chip's `$` hint: 'none' without a budget, 'warn' from 80%,
+ * 'over' from 100% (spec 8.5). Only budgets > 0 are budgets.
+ */
+export function budgetState(snapshot) {
+    if (snapshot.budgetTokens <= 0)
+        return 'none';
+    const fraction = teamTokens(snapshot) / snapshot.budgetTokens;
+    if (fraction >= 1)
+        return 'over';
+    return fraction >= 0.8 ? 'warn' : 'ok';
+}
+/** Short run id for the header: the last five alphanumerics, so ids that share a prefix differ. */
+export function shortRunId(runId) {
+    const clean = runId.replace(/[^A-Za-z0-9]/g, '');
+    return clean.length <= 5 ? clean : clean.slice(clean.length - 5);
+}
+/**
+ * Fold a snapshot into the first-seen-eliminated map.
+ *
+ * WHY THE PANEL KEEPS THIS ITSELF: `RosterRow` carries no "eliminated in phase N" field,
+ * and the board still needs the full roster from the same snapshot, so the engine cannot
+ * simply drop the row. A member that disappears from the map's keys (never happens) or
+ * that was never seen eliminated is treated as "eliminated now" by `isRetired`. Returns
+ * the SAME object when nothing changed so React memo / ref comparisons stay cheap.
+ */
+export function trackEliminated(previous, snapshot) {
+    let next = null;
+    for (const row of snapshot.roster) {
+        if (row.state !== 'eliminated' || previous[row.id] !== undefined)
+            continue;
+        next ??= { ...previous };
+        next[row.id] = snapshot.phase;
+    }
+    return next ?? previous;
+}
+/**
+ * True when an eliminated member's one visible phase is over: it was first seen in an
+ * earlier phase than the one now displayed.
+ */
+export function isRetired(row, phase, since) {
+    if (row.state !== 'eliminated')
+        return false;
+    const seen = since[row.id];
+    return seen !== undefined && phase > seen;
+}
+// ---------------------------------------------------------------------------
+// Sorting
+// ---------------------------------------------------------------------------
+const ROLE_ORDER = { DEV: 0, REV: 1, TEST: 2, INSP: 3 };
+/**
+ * Roster order: DEV -> REV -> TEST -> INSP, active members before eliminated ones, then
+ * by generation and id so `dev2` precedes its successor `dev2-r1` and the order is total
+ * (a stable roster does not reshuffle between snapshots).
+ */
+export function sortRoster(roster) {
+    return [...roster].sort((a, b) => {
+        const gone = Number(a.state === 'eliminated') - Number(b.state === 'eliminated');
+        if (gone !== 0)
+            return gone;
+        const role = ROLE_ORDER[a.role] - ROLE_ORDER[b.role];
+        if (role !== 0)
+            return role;
+        if (a.generation !== b.generation)
+            return a.generation - b.generation;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+}
+// ---------------------------------------------------------------------------
+// PLAN+GOVERN interview chip
+// ---------------------------------------------------------------------------
+/**
+ * `PLAN+GOVERN  interview round 2/2+` while rounds are still owed, and `... 2/2 OK` once
+ * the minimum is met (governance-mode 10.6). The trailing `+` reads "at least this many":
+ * the model may ask more rounds than the minimum.
+ */
+export function interviewChipText(round, required) {
+    const answered = Math.max(0, Math.floor(round));
+    const needed = Math.max(0, Math.floor(required));
+    const met = answered >= needed;
+    return `${POSTURE_LABEL.plan_govern}  interview round ${answered}/${needed}${met ? ' OK' : '+'}`;
+}
+// ---------------------------------------------------------------------------
+// Posture words
+// ---------------------------------------------------------------------------
+/**
+ * A `/gov pause` is waiting for the running stage to finish (governance-mode-v1-1 6.4).
+ * Only meaningful while the run is still `executing`: once it is `paused` the request has
+ * been redeemed, and an `escalated` run drops it.
+ */
+export function isPausePending(snapshot) {
+    return snapshot.pauseRequested === true && snapshot.status === 'executing';
+}
+/** True for the two governed postures, given a mode OR posture value as a string. */
+export function isGovernedModeValue(value) {
+    return value === 'govern' || value === 'plan_govern';
+}
+/**
+ * The status row's word for a mode OR a posture. `MODE_LABEL` answers for `build` /
+ * `plan` (so the byte-identical pre-governance output is preserved); the two governed
+ * postures are the only values that reach the second table.
+ *
+ * Short form: the first letter, except `plan_govern` which is `PG` - `P` is already PLAN
+ * and a status row that cannot tell them apart has defeated the badge.
+ */
+export function modeWord(value, full) {
+    const label = MODE_LABEL[value] ?? POSTURE_LABEL[value];
+    if (label === undefined)
+        return undefined;
+    if (full)
+        return label;
+    return value === 'plan_govern' ? 'PG' : label[0];
+}

package/dist/ui/interaction-copy.d.ts

@@ -69,6 +69,10 @@ export declare const interactionCopy: {
     readonly stopServices: "Ctrl+C stop services";
     readonly exit: "Ctrl+C x2 exit";
     readonly exitDraft: "Ctrl+C x2 clear input, x3 exit";
+    readonly governIdle: "type a task - the Orchestrator will assemble the team";
+    readonly governInterrupt: "Esc x2 interrupt (run is resumable)";
+    readonly governInterruptAgain: "Esc interrupt (run is resumable)";
+    readonly governPausePending: "pause pending: /gov pause cancel";
     readonly help: "/help";
     readonly shiftNewline: "Shift+Enter newline needs terminal support";
     readonly mode: "Shift+Tab switch mode";

package/dist/ui/interaction-copy.js

@@ -27,6 +27,11 @@ export const interactionCopy = {
     complete: 'Tab complete', select: 'Up/Down select', scroll: 'PgUp/PgDn scroll',
     confirm: 'Enter confirm', stopServices: 'Ctrl+C stop services', exit: 'Ctrl+C x2 exit',
     exitDraft: 'Ctrl+C x2 clear input, x3 exit',
+    // GOVERN posture (governance-mode 10.6). The run is resumable, so Esc is not destructive.
+    governIdle: 'type a task - the Orchestrator will assemble the team',
+    governInterrupt: 'Esc x2 interrupt (run is resumable)',
+    governInterruptAgain: 'Esc interrupt (run is resumable)',
+    governPausePending: 'pause pending: /gov pause cancel',
     help: '/help', shiftNewline: 'Shift+Enter newline needs terminal support',
     mode: 'Shift+Tab switch mode', update: '/update',
     idlePlaceholder: 'Ask a question or describe a task...', runningPlaceholder: 'Add a follow-up...',

package/dist/ui/interaction-hints.d.ts

@@ -19,6 +19,23 @@ export interface ActionHintInput {
     modeToggleKey?: string;
     /** Draft present: the exit clause becomes the clear-then-exit ladder. */
     hasDraft?: boolean;
+    /**
+     * The session is in a governed posture (governance-mode 10.6): the idle row teaches
+     * what the first message does, and the running row says an interrupt is resumable.
+     * ABSENT = every clause below is byte-identical to the pre-governance build.
+     */
+    governed?: boolean;
+    /**
+     * A `/gov pause` is waiting for the running stage to finish (governance-mode-v1-1 6.4):
+     * the row says so and how to undo it. Absent keeps every clause byte-identical.
+     */
+    govPausePending?: boolean;
+    /**
+     * The word after the toggle key, from `postureHintWord(nextPosture(...))`. Absent keeps
+     * the classic `switch mode`; only the wiring that knows the live posture cycle can say
+     * which posture is next, so this layer never guesses.
+     */
+    nextPostureWord?: string;
 }
 export declare function escapeClause(input: ActionHintInput): string;
 export declare function clipStatusText(text: string, cells: number): string;

package/dist/ui/interaction-hints.js

@@ -13,6 +13,9 @@ export function escapeClause(input) {
         return input.interruptPhase === 'armed' ? copy.cancelStartAgain : copy.cancelStart;
     if (input.interactionPhase !== 'running')
         return '';
+    if (input.governed) {
+        return input.interruptPhase === 'armed' ? copy.governInterruptAgain : copy.governInterrupt;
+    }
     return input.interruptPhase === 'armed' ? copy.interruptAgain : copy.interrupt;
 }
 export function clipStatusText(text, cells) {
@@ -40,6 +43,9 @@ export function actionCandidates(input) {
             ...(selects ? [input.overlay === 'settings' ? copy.saveSettings : copy.confirm] : [])];
     }
     const actions = [];
+    if (input.governed && input.govPausePending && input.interactionPhase === 'running') {
+        actions.push(copy.governPausePending);
+    }
     if (input.selectionPending)
         actions.push(copy.copy);
     else if (input.services)
@@ -48,7 +54,13 @@ export function actionCandidates(input) {
         actions.push(...(input.completion === 'slash' ? [copy.executeCommand] : []), copy.complete, copy.select);
         return actions;
     }
-    if (input.hintsEnabled !== false && input.interactionPhase !== 'starting')
+    // THE GOVERNED IDLE SENTENCE REPLACES `Enter send` / `newline` rather than joining them:
+    // at 120 columns it is 53 of the row's 119 cells, and the clause that would be crowded
+    // out is `Shift+Tab <next>`, the one the posture cycle most needs taught.
+    if (input.hintsEnabled !== false && input.governed && input.interactionPhase === 'idle') {
+        actions.push(copy.governIdle);
+    }
+    else if (input.hintsEnabled !== false && input.interactionPhase !== 'starting')
         actions.push(input.interactionPhase === 'running' ? copy.enqueue : copy.send, input.cols < 72 ? copy.newline : copy.newlineLong);
     return actions;
 }
@@ -78,7 +90,7 @@ export function buildActionClauses(input) {
         if (input.updateAvailable)
             add(copy.update);
         add(input.hasDraft ? copy.exitDraft : copy.exit);
-        add((input.modeToggleKey ?? 'Shift+Tab') + ' ' + copy.modeLabel);
+        add((input.modeToggleKey ?? 'Shift+Tab') + ' ' + (input.nextPostureWord ?? copy.modeLabel));
         add(copy.help);
     }
     return result;

package/dist/ui/layout/governance-board.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The `/gov board` overlay's model and geometry (governance-mode section 10.5): the tab
+ * model, the data adapters, the row builders and the scroll arithmetic - every decision
+ * the overlay makes, in pure code.
+ *
+ * Pure and total: no Ink, no clock (`now` is not even needed: rows carry sequence
+ * numbers, not times), no I/O. ASCII ONLY.
+ *
+ * TWO DATA SOURCES, ONE SHAPE. The live `GovernanceSnapshot` knows the roster and the
+ * ticker; the work-package matrix, the full ledger and the claims live in `RunState` /
+ * `LedgerState`. `GovernanceBoardData` is the UI's own flat projection of all of it, with
+ * two builders: `boardDataFromSnapshot` (what the renderer always has) and
+ * `boardDataFromRun` (what the wiring can supply). A board built from the snapshot alone
+ * still reads correctly - the tabs it cannot fill say so instead of going blank.
+ *
+ * EVERY ROW IS ONE TERMINAL ROW. Rows are `Segment[]` rendered `wrap="truncate"`, so
+ * scrolling is arithmetic on a list length (`sliceWindow`), never a re-measure.
+ */
+import type { GovernanceSnapshot, LedgerState, RunState, WorkPackage } from '../../governance/types.js';
+import type { Glyphs } from '../glyphs.js';
+import { type Segment } from '../governance-status.js';
+export type BoardTab = 'roster' | 'work' | 'ledger' | 'claims';
+export declare const BOARD_TABS: readonly BoardTab[];
+/** Terminals narrower than this get the single-column form with a `1/4` pager. */
+export declare const BOARD_NARROW_COLS = 80;
+/** Recent ledger lines shown under each identity on the roster tab (spec 10.5). */
+export declare const BOARD_RECENT_PER_AGENT = 5;
+/** Ledger rows kept in the projection, newest first. */
+export declare const BOARD_LEDGER_MAX = 200;
+/** The tab `delta` steps away, wrapping at both ends. */
+export declare function stepTab(tab: BoardTab, delta: number): BoardTab;
+export declare function tabIndex(tab: BoardTab): number;
+export interface BoardLedgerRow {
+    seq: number;
+    agentId: string;
+    code: string;
+    delta: number;
+    provisional: boolean;
+    /** `engine` / `inspector:insp`; '' when the source does not say. */
+    by: string;
+    reason: string;
+    evidence: string;
+    capped: boolean;
+}
+export interface BoardWorkPackage {
+    id: string;
+    title: string;
+    status: WorkPackage['status'];
+    reworkCount: number;
+    assignee: string;
+    reviewer: string;
+    tester: string;
+    fileCount: number;
+    blockedAt: string;
+}
+export interface BoardClaimRow {
+    id: string;
+    kind: 'claim' | 'escalation';
+    status: string;
+    /** `missed_by_review`, `wp_rework_cap`, ... */
+    detail: string;
+    /** Who is involved: `dev1 -> rev2` for a claim, the WP / phase for an escalation. */
+    subject: string;
+    text: string;
+}
+export interface GovernanceBoardData {
+    snapshot: GovernanceSnapshot;
+    workPackages: BoardWorkPackage[];
+    ledger: BoardLedgerRow[];
+    claims: BoardClaimRow[];
+    /** Absolute path of `board.md`, for the `e` key; null when unknown. */
+    boardPath: string | null;
+}
+/** What the renderer always has: the live snapshot. WPs and claims stay empty. */
+export declare function boardDataFromSnapshot(snapshot: GovernanceSnapshot, boardPath?: string | null): GovernanceBoardData;
+export interface BoardDataInput {
+    snapshot: GovernanceSnapshot;
+    run: RunState;
+    ledger: LedgerState;
+    boardPath?: string | null;
+}
+/** The full projection, for a wiring that can read the run and the ledger. */
+export declare function boardDataFromRun(input: BoardDataInput): GovernanceBoardData;
+export interface BoardLine {
+    key: string;
+    segments: Segment[];
+}
+export interface BoardTabStrip {
+    segments: Segment[];
+    /** `1/4` in the narrow form, `''` in the wide one. */
+    pager: string;
+}
+export declare function buildTabStrip(tab: BoardTab, data: GovernanceBoardData, narrow: boolean, glyphs: Glyphs): BoardTabStrip;
+export interface GovernanceBoardInput {
+    /** Overlay CONTENT width (the frame's chrome already subtracted). */
+    cols: number;
+    tab: BoardTab;
+    data: GovernanceBoardData | null;
+    glyphs: Glyphs;
+}
+export interface GovernanceBoardLayout {
+    narrow: boolean;
+    tabStrip: BoardTabStrip;
+    /** Every row of the active tab; the overlay windows them. */
+    lines: BoardLine[];
+}
+export declare function buildGovernanceBoardLayout(input: GovernanceBoardInput): GovernanceBoardLayout;
+/** Body rows left for content once the tab strip has taken one of the frame's rows. */
+export declare function boardBodyRows(frameBodyRows: number): number;
+export interface BoardWindow {
+    start: number;
+    visible: number;
+    total: number;
+    /** The offset after clamping: feed it back so the owner's counter cannot run away. */
+    clamped: number;
+}
+export declare function boardWindow(total: number, offset: number, height: number): BoardWindow;
+/** Position text for the footer, e.g. `3-14/40`; '' when everything fits. */
+export declare function boardPosition(window: BoardWindow, glyphs: Glyphs): string;
+/** Footer hint, shortened to the width the frame can print on one row. */
+export declare function boardHint(cols: number, glyphs: Glyphs): string;