@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/team/types.d.ts

@@ -1,354 +0,0 @@
-/**
- * Runtime shapes for team mode (team-subagents §5.1 / §5.2).
- *
- * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
- *
- * `TeamEvent` is a CLI-LOCAL stream and must stay that way (D-10 / I-5).
- * `packages/core` freezes its runtime export list (`public-api.test.ts`) and
- * forbids host coupling (`no-host-coupling.test.ts`); adding a member to core's
- * `AgentEvent` union would break the first and teach core about a host shape
- * (`SubagentRun`) it has no business defining. The whole feature therefore
- * changes ZERO files under `packages/core/` (AC-12).
- */
-import type { TokenUsage } from '@aragon-agent/core';
-import type { ActivityArgs } from './activity.js';
-import type { TimelineEntry } from './timeline.js';
-import type { GovernanceSpecExt } from '../governance/types.js';
-/** One normalized delegation request. Produced only by `normalizeSubagentSpecs`. */
-export interface SubagentSpec {
-    /** Slug, unique within the dispatch. Shown in the panel, the report and logs. */
-    label: string;
-    /** <= TEAM_LIMITS.descriptionChars. What this subagent is for. */
-    description: string;
-    /** <= TEAM_LIMITS.promptChars. Self-contained: the child sees no history. */
-    prompt: string;
-    /**
-     * Force the plan-mode gate on for this child regardless of session mode.
-     * TIGHTENING ONLY (D-13): there is no field anywhere that gives a child more
-     * permission than the session it was spawned from.
-     */
-    readOnly: boolean;
-    /**
-     * Set only by the governance engine (governance-mode section 8.3). Its presence is what
-     * `isGovernedDispatch` reads to keep a governed dispatch out of the transcript.
-     */
-    governance?: GovernanceSpecExt;
-}
-export type SubagentPhase = 'queued' | 'starting' | 'thinking' | 'tool' | 'waiting' | 'done' | 'failed' | 'aborted';
-/** Live, mutable record of one child. Projected into the UI and the report. */
-export interface SubagentRun {
-    label: string;
-    description: string;
-    phase: SubagentPhase;
-    startedAt?: number;
-    endedAt?: number;
-    turns: number;
-    toolCalls: number;
-    lastTool?: string;
-    usage: TokenUsage;
-    /**
-     * Paths seen going through `write_file` / `edit_file`, deduped and capped at
-     * `TEAM_LIMITS.filesTouchedMax`.
-     *
-     * BEST-EFFORT BY CONSTRUCTION: a child that writes through `bash` is invisible
-     * here. The conflict warning in the report says "review before trusting
-     * either" rather than claiming completeness, and that wording is load-bearing
-     * (R-2).
-     */
-    filesTouched: string[];
-    messagesSent: number;
-    /** The child's final assistant text. The only thing the lead sees of its work. */
-    summary?: string;
-    error?: string;
-    /** Hit `team.maxTurnsPerSubagent` and was stopped mid-work. */
-    truncated?: boolean;
-    /**
-     * Compactions this child performed on its OWN history
-     * (context-auto-compaction-hardening §3.4.4 / W3).
-     *
-     * OPTIONAL, so every existing construction site and fixture compiles
-     * unchanged. Absent and `0` mean the same thing to every reader.
-     */
-    compactions?: number;
-    /**
-     * Prose the child is writing right now, sanitized and clamped to
-     * `TEAM_LIMITS.activityChars`. Set only between tool calls; cleared on
-     * `turn_start`, on `tool_execution_start` and on `tool_execution_end` so it
-     * can never describe work the child has already finished.
-     *
-     * THE CLAMP HERE IS A STORAGE CEILING, NOT A COLUMN WIDTH (P0-1). The panel
-     * re-clamps to `activityBudget(cols)` at render. Do not "simplify" by clamping
-     * to the display budget here: this value has no terminal.
-     *
-     * NEVER LOGGED and never persisted: it is ephemeral by construction and a
-     * resumed session has no live dispatch.
-     */
-    activity?: string;
-    /**
-     * The five argument fields any of the nine known tools might want to show,
-     * picked at capture time by `pickActivityArgs` and elided to
-     * `TEAM_LIMITS.activityArgChars` each.
-     *
-     * A PICKED SUBSET, NOT `event.args` (P1-4). The run is shallow-copied into the
-     * live snapshot and into every `agent_update` event by `publish()`, and again
-     * into `DispatchOutcome.runs` by `dispatch()`, which `TeamCard` holds in the
-     * transcript for the session. Holding `event.args` would mean holding
-     * `write_file`'s `content` - a whole file, unbounded - along all of those
-     * paths, and would put a file body one `JSON.stringify` from a log.
-     *
-     * Stored unformatted because the PANEL owns the wide/narrow decision and it is
-     * the only object that knows the terminal width. A formatted string here would
-     * bake one terminal's width into a value the report and the headless writer
-     * also read.
-     *
-     * Cleared on `turn_start` and `tool_execution_end` (P1-5).
-     */
-    activityArgs?: ActivityArgs;
-    /** `team_wait` calls refused as unanswerable (F-3). Pulled from the bus on
-     *  `tool_execution_end`, the same way `messagesSent` is. */
-    blockedWaits?: number;
-    /** Cold-start retries spent (F-4). 0 or absent for the overwhelming majority
-     *  of runs; `1` at most under `TEAM_LIMITS.maxColdStartRetries`. */
-    retries?: number;
-    /**
-     * Whether the error that ended this attempt was transport-level and
-     * retryable, read structurally off `LLMError.retryable`.
-     *
-     * NOT RENDERED ANYWHERE. It exists so `TeamRuntime` can decide without
-     * re-parsing `run.error`, which is a human-facing sentence produced by
-     * `formatStreamError` and must never become a machine-readable contract.
-     */
-    retryable?: boolean;
-    /**
-     * The child's LIVE API-retry state (llm-api-retry-backoff §6.10), or absent when
-     * it is not in a backoff.
-     *
-     * THIS EXISTS BECAUSE A CHILD'S RETRY IS OTHERWISE INVISIBLE (R-14). Subagents
-     * inherit the lead's retry policy for free — `TeamRuntime` reuses the lead's
-     * registry instance — but a child's `retry_scheduled` goes to that CHILD's own
-     * `Agent` listeners and never reaches the lead's `ViewState`. Without this field
-     * a subagent spending three minutes in backoff shows no card, no chip and no
-     * countdown: the dispatch simply appears hung, which is the single worst reading
-     * of a mechanism whose whole claim is that waiting is now legible.
-     *
-     * The fix uses the channel that already exists rather than inventing a second
-     * card: `TeamCard` and `transcript-text` already render one row per child, and
-     * this rides on it. `ViewState.retry` stays LEAD-ONLY, and the lead's status-bar
-     * chip is deliberately NOT driven by children — `agents 3/5` already reports the
-     * dispatch, and a second aggregate would put two numbers on the bar that
-     * disagree about what "3" means.
-     *
-     * EPHEMERAL, exactly like `activity` and `activityArgs`: cleared on the child's
-     * next `turn_end` or terminal error, never persisted, and a settled team entry
-     * keeps only what the run finally did.
-     *
-     * NO `resumeAt`, DELIBERATELY, and this is the one place §6.10's sketch is not
-     * followed. A countdown needs something to re-render it, and nothing does: the
-     * team row is drawn from `agent_update`, a child in backoff emits exactly ONE
-     * event for the whole wait, and the lead's 1 Hz `retryTick` is gated on the
-     * LEAD's own `state.retry`. A `7s` that never changed for thirty seconds is a
-     * worse readout than no number at all — it reads as a hung countdown, which is
-     * precisely the impression this row exists to remove. The counter alone is
-     * honest and is what AC-34 asserts.
-     */
-    retry?: {
-        attempt: number;
-        maxRetries: number;
-    };
-    /**
-     * Supervisor inspections this child received (team-overseer). Optional so
-     * every existing fixture compiles; absent and `0` read the same.
-     */
-    interventions?: number;
-    /**
-     * Supervisor-driven rebuilds this child went through (team-overseer). The
-     * run object survives a rebuild with the same label, so this is where the
-     * report reads "this row is the Nth body of the same brief".
-     */
-    replacements?: number;
-    /**
-     * The most recent supervisor decision applied to this child
-     * (subagent-overseer-v2 section 6). TRANSIENT, never persisted - the
-     * same rule as `activity` / `activityArgs`; a resumed session has no
-     * live dispatch. The strip that enforces it is `PERSIST_STRIP_FIELDS` in
-     * `team/settled.ts` (tui-subagent-panel §4.5.4): it stays on the settled run,
-     * because the card's badge and the supervision report read it there, and the
-     * SAVE boundary is where it is removed.
-     *
-     * `at` is ABSOLUTE epoch ms, the same units as `startedAt` / `endedAt`
-     * (R-P2-3), so the panel renders `nudged 2m` with one subtraction and
-     * no second clock convention. `reasonHead` <= 60 chars, for the UI
-     * badge line only.
-     */
-    lastIntervention?: {
-        action: OverseerAction;
-        at: number;
-        reasonHead: string;
-    };
-    /**
-     * The last `TEAM_LIMITS.timelineEntries` (24) events of this child
-     * (tui-subagent-panel §4.5 / §7).
-     *
-     * EPHEMERAL, on exactly the same terms as `activity` / `activityArgs` / `retry`, and
-     * guaranteed by TWO independent strips (`team/settled.ts`): `settledRun()` at the
-     * dispatch exit and `stripEphemeralRuns()` in `saveSession`'s chain. One gate is not
-     * enough - the live entry's runs are written by `teamUpdate` during a dispatch, so a
-     * checkpoint or an exit flush would otherwise carry the ring to disk (§4.5.4).
-     *
-     * NEVER persisted, never in `aragon exec`'s stream either: `exec/runner.ts`'s
-     * `emitTeam` builds its events from an explicit field list, so a new run field cannot
-     * leak into `stream-json` (AC-22).
-     *
-     * `at` is ABSOLUTE epoch ms (the units of `startedAt` / `lastIntervention.at`), and
-     * each `text` is already sanitized and clamped, so appending is the only write and
-     * `appendTimeline` is the only appender.
-     */
-    timeline?: TimelineEntry[];
-}
-/** What the supervisor may do with one inspected child. */
-export type OverseerAction = 'wait' | 'nudge' | 'replace' | 'abandon';
-/**
- * One supervisor decision, already normalized and clamped.
- *
- * Produced ONLY by `normalizeOverseerDecision` (repair, never reject): an
- * unparseable or out-of-budget model answer becomes `wait` with the default
- * interval, because supervision must not kill a healthy child.
- */
-export interface OverseerDecision {
-    action: OverseerAction;
-    /** <= TEAM_LIMITS.overseerReasonChars. Why, for the report and the log. */
-    reason: string;
-    /** `nudge` only: <= TEAM_LIMITS.overseerGuidanceChars. Steered into the child. */
-    guidance?: string;
-    /** Model-chosen next check, clamped to the structural range. */
-    nextCheckMs?: number;
-}
-/** One supervisor intervention, as recorded on the outcome and rendered. */
-export interface OverseerIntervention {
-    label: string;
-    at: number;
-    action: OverseerAction;
-    reason: string;
-    /**
-     * What the trigger was: event stall, wall-clock check, the child's turn
-     * cap (F-8 A'2 - an inspection the supervisor then ruled on), post-mortem,
-     * or the supervisor going QUIET (subagent-overseer-v2 D-10) - the look
-     * budget ran out and supervision stopped waking this child. A VALUE OF
-     * THE UNION, never a reason prefix: a human-readable sentence is not a
-     * machine contract (the `run.error` rule).
-     */
-    trigger: 'silence' | 'clock' | 'turncap' | 'postmortem' | 'quiet';
-}
-/**
- * A terminal supervisor decision handed to the WORKER LOOP, which is the only
- * place a child's `prompt()` is awaited and therefore the only place a
- * lifecycle change can be applied without orphaning the replacement (I-OV1).
- *
- * Set by `TeamRuntime` on the handle, then `handle.abort()`; consumed and
- * left in place (never cleared) by `runOne` after the await resolves.
- */
-export interface OverseerVerdict {
-    action: 'replace' | 'abandon';
-    reason: string;
-    guidance?: string;
-}
-/** One message on the team bus. */
-export interface TeamMessage {
-    from: string;
-    to: string;
-    subject: string;
-    body: string;
-    at: number;
-}
-/** Everything one dispatch produced. The sole input to `buildDispatchReport`. */
-export interface DispatchOutcome {
-    dispatchId: string;
-    runs: SubagentRun[];
-    /** Specs the model asked for, BEFORE the cap — the "n of m requested" line. */
-    requested: number;
-    startedAt: number;
-    endedAt: number;
-    aborted: boolean;
-    /** Messages addressed to `lead`; surfaced in their own report section. */
-    leadMail: TeamMessage[];
-    /**
-     * Every supervisor decision that was applied (team-overseer), in order.
-     * Bounded by the per-child inspection budget; rendered as the report's
-     * Overseer section so the lead can see WHO was nudged or replaced and why.
-     */
-    interventions?: OverseerIntervention[];
-    /**
-     * Summed across all children. Real spend; it must reach the status bar
-     * (§3.9). Every child runs the LEAD's model (main-agent parity), so one
-     * total priced at the lead's table is the honest accounting.
-     */
-    usage: TokenUsage;
-    /**
-     * The supervisor's own fast-tier spend for this dispatch
-     * (subagent-overseer-v2 D-7). Absent when nothing supervised the
-     * dispatch; read straight off the provider at dispatch end so there is
-     * exactly one accounting of it.
-     */
-    overseerUsage?: TokenUsage;
-    /** Inspection calls made, including ones that failed softly. */
-    overseerCalls?: number;
-    /**
-     * EDGE-LATCHED, once per dispatch (D-10): the fast tier was missing at
-     * least one cadence tick and the children waited UNASSISTED - announced,
-     * never killed. The per-child wait events of a degraded tick
-     * deliberately do NOT enter `interventions`; this flag plus the tick
-     * count below are the report's aggregate note.
-     */
-    overseerDegraded?: boolean;
-    /** How many cadence ticks ran unassisted (the aggregate note's number). */
-    overseerDegradedTicks?: number;
-}
-/**
- * What the UI renders: a cheap immutable projection, rebuilt per event.
- *
- * Held in `ViewState.team` and NEVER persisted — a resumed session has no live
- * dispatch, and pretending otherwise is what P1-5 is about.
- */
-export interface TeamSnapshot {
-    dispatchId: string;
-    active: boolean;
-    runs: SubagentRun[];
-    requested: number;
-    startedAt: number;
-    messageCount: number;
-    lastMessage?: TeamMessage;
-}
-/**
- * The CLI-local event stream. `TeamRuntime` emits; `AgentController.subscribeTeam`
- * forwards; `App`, `runHeadless` and `attachTeamEvents` consume.
- */
-export type TeamEvent = {
-    type: 'dispatch_start';
-    dispatchId: string;
-    requested: number;
-    specs: SubagentSpec[];
-} | {
-    type: 'agent_update';
-    dispatchId: string;
-    run: SubagentRun;
-} | {
-    type: 'usage';
-    dispatchId: string;
-    label: string;
-    usage: TokenUsage;
-} | {
-    type: 'message';
-    dispatchId: string;
-    message: TeamMessage;
-} | {
-    type: 'overseer';
-    dispatchId: string;
-    label: string;
-    decision: OverseerDecision;
-    trigger: OverseerIntervention['trigger'];
-} | {
-    type: 'dispatch_end';
-    dispatchId: string;
-    outcome: DispatchOutcome;
-};
-export type TeamEventListener = (event: TeamEvent) => void;

package/dist/team/types.js

@@ -1,13 +0,0 @@
-/**
- * Runtime shapes for team mode (team-subagents §5.1 / §5.2).
- *
- * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
- *
- * `TeamEvent` is a CLI-LOCAL stream and must stay that way (D-10 / I-5).
- * `packages/core` freezes its runtime export list (`public-api.test.ts`) and
- * forbids host coupling (`no-host-coupling.test.ts`); adding a member to core's
- * `AgentEvent` union would break the first and teach core about a host shape
- * (`SubagentRun`) it has no business defining. The whole feature therefore
- * changes ZERO files under `packages/core/` (AC-12).
- */
-export {};

package/dist/todo/acceptance.d.ts

@@ -1,120 +0,0 @@
-/**
- * The acceptance-criteria model (todo-acceptance-criteria §6.2 / §6.3 / §6.6.2).
- *
- * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
- *
- * PURE: no I/O, no timers, no `Date.now()`. The clock is injected where a
- * timestamp is needed, exactly as `TodoStore`'s constructor does (P2-4).
- *
- * ONE PRINCIPLE RUNS THROUGH THE WHOLE FILE, and it is the reason this module
- * exists: **a verdict is evidence, a plan is a belief**. A verdict is never
- * destroyed by omission - not by re-sending the criterion as `pending`, and not
- * by leaving it out of the list altogether - because a full replacement means the
- * model re-sends the whole table on every turn and one lapse would silently erase
- * a conclusion the user was shown. An unchecked criterion, by contrast, IS a
- * plan, so a re-plan is free to drop it.
- *
- * NEVER THROWS, NEVER REJECTS, ONLY REPAIRS (I-9): the same discipline
- * `normalize.ts` records for the todo list itself.
- */
-import type { AcceptanceItem, AcceptanceSnapshot, PlanPhase, TodoItem, TodoSnapshot } from './types.js';
-export interface NormalizeAcceptanceResult {
-    items: AcceptanceItem[];
-    /** How many entries the payload contained BEFORE dropping and capping. */
-    requested: number;
-    /** Human-readable repair notes, already bounded. Empty when nothing was wrong. */
-    repairs: string[];
-}
-export interface NormalizeAcceptanceOptions {
-    /** `todo.acceptance`, read LIVE (D-11). False short-circuits everything below. */
-    enabled: boolean;
-    /**
-     * Per-lineage dedupe of the restoration note (§6.2.1 step 9 / P2-4).
-     *
-     * OWNED BY `TodoStore`, not by this module: the note would otherwise be
-     * re-printed on every turn, because the model has no way to know the server
-     * restored a verdict and would keep sending the same `pending` row. Passing the
-     * set in keeps this function pure and keeps the dedupe state in the one object
-     * that already owns the plan's lifetime.
-     */
-    restoredNotes?: Set<string>;
-}
-/**
- * Repair whatever arrived in the `acceptance` field of a `todo_write` call.
- *
- * ORDER IS SEMANTICS, and one step of that order is load-bearing enough to be a
- * review condition (C-2): `enabled` short-circuits FIRST, then `undefined`, then
- * `Array.isArray`. `undefined` (the key is absent) and `[]` (the model sent an
- * empty array) are NOT the same thing: absent means "I am only updating steps,
- * keep the table", empty means "this plan needs no criteria". This is the one
- * place in the feature where the two differ (§9).
- */
-export declare function normalizeAcceptance(raw: unknown, previous: readonly AcceptanceItem[], options: NormalizeAcceptanceOptions): NormalizeAcceptanceResult;
-/**
- * The immutable projection of one committed table (§6.2.2).
- *
- * CALLED FROM EXACTLY ONE PLACE PER COMMIT - `TodoStore`'s `write` / `restore` /
- * `clear` / `reopenAll` - and stored, never recomputed on read. `snapshot()` runs
- * on every event; recomputing here would stamp a new `now()` and a new object
- * each frame, invalidating `TodoCard`'s `React.memo` and the transcript's height
- * cache (P1-3).
- */
-export declare function acceptanceSummary(items: readonly AcceptanceItem[], now: () => number): AcceptanceSnapshot;
-/**
- * The ONE judge of "which phase is this plan in" (I-3 / D-5).
- *
- * Derived rather than stored, so the model, the rail, the transcript card and the
- * machine event stream cannot disagree: a stored field would be a second writer
- * of a fact that two lists already determine. Callers must not invoke this for a
- * `null` plan.
- */
-export declare function derivePlanPhase(items: readonly TodoItem[], acceptance: readonly AcceptanceItem[] | null): PlanPhase;
-/**
- * "Is there nothing left to do in this plan" - THE single judge (G-4 / I-3).
- *
- * Referenced by follow-through, by `App`'s grace-window re-check and by
- * `TodoStore.beginUserTurn`, because "every step is completed" stopped being the
- * same claim as "the work is done" the moment acceptance criteria existed. Three
- * copies of the old equation is exactly how a plan gets cleared while its last
- * criterion is still unchecked.
- */
-export declare function planIsResolved(items: readonly TodoItem[], acceptance: readonly AcceptanceItem[] | null): boolean;
-export declare function countUnfinishedSteps(items: readonly TodoItem[]): number;
-export declare function countUncheckedCriteria(acceptance: readonly AcceptanceItem[] | null): number;
-/** What is left in a plan, as the two numbers the notices are written from. */
-export interface Outstanding {
-    steps: number;
-    checks: number;
-}
-/**
- * The six follow-through exits all need "how much is left", and after this
- * feature that quantity has two halves (§6.6.1.1). One function decides it, so no
- * exit can print `0 steps left` on a plan whose steps are all done but whose
- * criteria are not - which is what `total - doneCount` would say on every verify
- * turn.
- */
-export declare function outstandingOf(snapshot: TodoSnapshot): Outstanding;
-/**
- * Singular and plural decided in ONE place (§6.6.1.1): six call sites must not
- * each spell their own.
- */
-export declare function criteriaPhrase(count: number): string;
-/**
- * A bounded enumeration of what a plan still owes, for the tool result text
- * (§6.3). Ordered `todoFirst` because the tool result is read top-down and the
- * step being worked on is the more urgent of the two when both exist.
- *
- * BOUNDED BY CONSTRUCTION at `VERIFY_MESSAGE_LIMITS.uncheckedItems` rows: this
- * string is paid for on every call (I-11).
- */
-export declare function planOutstanding(items: readonly TodoItem[], acceptance: readonly AcceptanceItem[] | null, todoFirst: boolean): string[];
-/**
- * The continuation text for the verification phase (§6.6.2).
- *
- * CONSTRUCTIVELY BOUNDED, which is what AC-22 asserts: the unchecked list stops
- * at 5 rows, the failed list at 2, `check` is clipped to 100 characters and
- * `evidence` to 60. Both truncations are deliberate - the full text is already in
- * the model's own previous payload, so re-sending it is paying twice for the same
- * bytes; what the model needs is a reminder of WHICH rows are open.
- */
-export declare function buildVerifyMessage(snapshot: TodoSnapshot): string;