@aragon-agent/cli 0.6.17 → 0.6.18

package/dist/input/limits.d.ts

@@ -64,6 +64,21 @@ export declare const PASTE_CLOSE = "\0]";
  * no payload, so one constant replaces the OPEN/CLOSE pair.
  */
 export declare const ENTER_NEWLINE_FRAME = "\0n";
+/**
+ * The inline frame that carries ONE "Ctrl+I was pressed" intent from the stdin
+ * filter to `App` (project-indexer Ctrl+I trigger).
+ *
+ * WHY A FRAME AND NOT `key.ctrl && input === 'i'`. Legacy terminals encode
+ * Ctrl+I as the same byte as Tab (0x09), so by the time the stream reaches Ink
+ * the two are indistinguishable. Under win32-input-mode (`?9001h`) and kitty
+ * CSI-u the modifiers ARE known at translation time, and both translators emit
+ * this frame instead of the legacy Tab byte. Same NUL-delimiter guarantee as
+ * `ENTER_NEWLINE_FRAME`: no terminal delivers NUL for a key and pasted text is
+ * stripped of NUL, so a payload can never forge it. Terminals without keyboard
+ * enhancement keep the legacy collapse — Ctrl+I there is Tab, documented in the
+ * README keybindings table.
+ */
+export declare const INDEX_KEY_FRAME = "\0i";
 /**
  * The one channel from the stdin filter to `App`'s notice dispatch (P1-3 / I-15).
  *

package/dist/input/limits.js

@@ -64,6 +64,21 @@ export const PASTE_CLOSE = '\u0000]';
  * no payload, so one constant replaces the OPEN/CLOSE pair.
  */
 export const ENTER_NEWLINE_FRAME = '\u0000n';
+/**
+ * The inline frame that carries ONE "Ctrl+I was pressed" intent from the stdin
+ * filter to `App` (project-indexer Ctrl+I trigger).
+ *
+ * WHY A FRAME AND NOT `key.ctrl && input === 'i'`. Legacy terminals encode
+ * Ctrl+I as the same byte as Tab (0x09), so by the time the stream reaches Ink
+ * the two are indistinguishable. Under win32-input-mode (`?9001h`) and kitty
+ * CSI-u the modifiers ARE known at translation time, and both translators emit
+ * this frame instead of the legacy Tab byte. Same NUL-delimiter guarantee as
+ * `ENTER_NEWLINE_FRAME`: no terminal delivers NUL for a key and pasted text is
+ * stripped of NUL, so a payload can never forge it. Terminals without keyboard
+ * enhancement keep the legacy collapse — Ctrl+I there is Tab, documented in the
+ * README keybindings table.
+ */
+export const INDEX_KEY_FRAME = '\u0000i';
 /** Human-readable byte size for the refusal toast (`4.1 MB`, `812.0 KB`, `7 B`). */
 export function formatPasteSize(bytes) {
     if (bytes >= 1024 * 1024)

package/dist/input/win32-input-mode.js

@@ -20,7 +20,7 @@
  *
  * Pure: no node/React imports, callable from any test environment.
  */
-import { ENTER_NEWLINE_FRAME } from './limits.js';
+import { ENTER_NEWLINE_FRAME, INDEX_KEY_FRAME } from './limits.js';
 /** Enable / disable win32-input-mode (private mode 9001). */
 export const WIN32_INPUT_ENABLE = '\x1b[?9001h';
 export const WIN32_INPUT_DISABLE = '\x1b[?9001l';
@@ -190,6 +190,12 @@ export function translateWin32Key(record) {
             // A modified Enter NEVER submits -- same rule as `ENTER_SEQUENCES`.
             return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
         case VK_TAB:
+            // Ctrl+I is the project-indexer trigger, and the ONLY place the two are
+            // tell-apart is right here: legacy encoding collapses it to the Tab
+            // byte. Shift keeps ESC [ Z (Shift+Tab) so the mode toggle stays intact,
+            // and Ctrl+Shift+I stays on that Shift branch.
+            if (ctrl && !shift && !alt)
+                return INDEX_KEY_FRAME;
             return shift ? '\x1b[Z' : '\t';
         case VK_ESCAPE:
             return alt ? '\x1b\x1b' : '\x1b';

package/dist/logging/install.d.ts

@@ -292,6 +292,15 @@ export type TeamLogEvent = {
         subject?: string;
         body?: string;
     };
+} | {
+    type: 'overseer';
+    dispatchId: string;
+    label?: string;
+    decision?: {
+        action?: string;
+        reason?: string;
+    };
+    trigger?: string;
 } | {
     type: 'dispatch_end';
     dispatchId: string;

package/dist/logging/install.js

@@ -510,6 +510,17 @@ export function attachTeamEvents(logger, controller) {
                     subject: event.message?.subject,
                 });
                 break;
+            case 'overseer':
+                // REASON ONLY, and at debug: interventions are routine supervision,
+                // not failures; the report and the panel carry them to the user.
+                logger.debug('agent', 'team_overseer', {
+                    dispatchId: event.dispatchId,
+                    label: event.label,
+                    action: event.decision?.action,
+                    trigger: event.trigger,
+                    reason: event.decision?.reason,
+                });
+                break;
             case 'dispatch_end': {
                 const outcome = event.outcome;
                 const runs = outcome?.runs ?? [];

package/dist/team/human-queue.d.ts

@@ -33,7 +33,18 @@ export declare class TeamHumanQueue {
     private readonly confirm;
     /** The chain. Never rejects: a failed request resolves `false` (deny). */
     private tail;
+    /**
+     * Labels with a request chained but not yet answered (team-overseer I-OV3).
+     *
+     * The queue pauses the CHILD's own watchdog on enqueue; the supervisor's
+     * soft silence timer needs the same fact one level up, or a user who takes
+     * four minutes over the first dialog burns inspection budget on siblings
+     * that are third in the FIFO and provably fine.
+     */
+    private readonly waiting;
     constructor(confirm: (req: ConfirmRequest) => Promise<boolean>);
+    /** Whether `label` has a confirmation queued or displayed right now. */
+    isWaiting(label: string): boolean;
     /**
      * Ask the human about `req` on behalf of `label`, one at a time.
      *

package/dist/team/human-queue.js

@@ -27,9 +27,22 @@ export class TeamHumanQueue {
     confirm;
     /** The chain. Never rejects: a failed request resolves `false` (deny). */
     tail = Promise.resolve();
+    /**
+     * Labels with a request chained but not yet answered (team-overseer I-OV3).
+     *
+     * The queue pauses the CHILD's own watchdog on enqueue; the supervisor's
+     * soft silence timer needs the same fact one level up, or a user who takes
+     * four minutes over the first dialog burns inspection budget on siblings
+     * that are third in the FIFO and provably fine.
+     */
+    waiting = new Set();
     constructor(confirm) {
         this.confirm = confirm;
     }
+    /** Whether `label` has a confirmation queued or displayed right now. */
+    isWaiting(label) {
+        return this.waiting.has(label);
+    }
     /**
      * Ask the human about `req` on behalf of `label`, one at a time.
      *
@@ -41,13 +54,17 @@ export class TeamHumanQueue {
      */
     request(child, label, req, signal) {
         child?.pauseIdleWatchdog();
+        this.waiting.add(label);
         const queued = this.enqueue(async () => {
             if (signal?.aborted)
                 return false;
             return this.confirm({ ...req, summary: `[${label}] ${req.summary}` });
         });
         const raced = signal ? Promise.race([queued, abortsToFalse(signal)]) : queued;
-        return raced.finally(() => child?.resumeIdleWatchdog());
+        return raced.finally(() => {
+            this.waiting.delete(label);
+            child?.resumeIdleWatchdog();
+        });
     }
     /**
      * Chain `run` after everything already queued.

package/dist/team/limits.d.ts

@@ -101,6 +101,46 @@ export declare const TEAM_LIMITS: {
      *  nothing a re-dispatch by the lead would not buy better. */
     readonly maxColdStartRetries: 1;
     readonly retryBackoffMs: 2000;
+    /**
+     * Wall-clock budget of everything one inspection may carry. The digest holds
+     * run facts, the supervisor's own memory and the tail of the child's live
+     * history; unbounded, one look at a child that read five big files would
+     * make the "cheap" supervision call cost more than the child (the argument
+     * FAST_LIMITS.digestMaxChars makes, one level up).
+     */
+    readonly overseerDigestBytes: 8000;
+    /** Clamp on a `nudge` guidance text. Advice, not a second brief. */
+    readonly overseerGuidanceChars: 1200;
+    /** Clamp on the decision `reason` recorded in the report. */
+    readonly overseerReasonChars: 200;
+    /**
+     * Inspections PER CHILD per dispatch. An indecisive supervisor must stop
+     * burning fast-tier calls; past the budget the child simply runs under its
+     * hard ceilings and the supervisor goes quiet.
+     */
+    readonly overseerMaxInspectionsPerChild: 4;
+    /**
+     * Rebuilds PER CHILD per dispatch. One: a replacement that also stalls dies
+     * on its own watchdog rather than ping-ponging fresh children at a task the
+     * supervisor already failed to rescue once.
+     */
+    readonly overseerMaxReplacementsPerChild: 1;
+    /**
+     * First wall-clock check when `team.subagentTimeoutMs === 0` (the shipped
+     * default): the supervisor still looks even when no ceiling was configured.
+     */
+    readonly overseerDefaultCheckMs: 300000;
+    /** Clamp on the model-chosen `nextCheckMs`, lower bound. */
+    readonly overseerNextCheckMinMs: 60000;
+    /** Clamp on the model-chosen `nextCheckMs`, upper bound. */
+    readonly overseerNextCheckMaxMs: 900000;
+    /**
+     * A child's OWN idle watchdog, multiplied by this while the supervisor is
+     * active, so the soft silence inspection at `idleTimeoutMs` always precedes
+     * the hard abort. The watchdog stays as the backstop for a child that
+     * wedges past every inspection.
+     */
+    readonly overseerWatchdogFactor: 4;
 };
 /**
  * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).

package/dist/team/limits.js

@@ -106,6 +106,47 @@ export const TEAM_LIMITS = {
      *  nothing a re-dispatch by the lead would not buy better. */
     maxColdStartRetries: 1,
     retryBackoffMs: 2_000,
+    // --- The dispatch supervisor (team-overseer) ---
+    /**
+     * Wall-clock budget of everything one inspection may carry. The digest holds
+     * run facts, the supervisor's own memory and the tail of the child's live
+     * history; unbounded, one look at a child that read five big files would
+     * make the "cheap" supervision call cost more than the child (the argument
+     * FAST_LIMITS.digestMaxChars makes, one level up).
+     */
+    overseerDigestBytes: 8_000,
+    /** Clamp on a `nudge` guidance text. Advice, not a second brief. */
+    overseerGuidanceChars: 1_200,
+    /** Clamp on the decision `reason` recorded in the report. */
+    overseerReasonChars: 200,
+    /**
+     * Inspections PER CHILD per dispatch. An indecisive supervisor must stop
+     * burning fast-tier calls; past the budget the child simply runs under its
+     * hard ceilings and the supervisor goes quiet.
+     */
+    overseerMaxInspectionsPerChild: 4,
+    /**
+     * Rebuilds PER CHILD per dispatch. One: a replacement that also stalls dies
+     * on its own watchdog rather than ping-ponging fresh children at a task the
+     * supervisor already failed to rescue once.
+     */
+    overseerMaxReplacementsPerChild: 1,
+    /**
+     * First wall-clock check when `team.subagentTimeoutMs === 0` (the shipped
+     * default): the supervisor still looks even when no ceiling was configured.
+     */
+    overseerDefaultCheckMs: 300_000,
+    /** Clamp on the model-chosen `nextCheckMs`, lower bound. */
+    overseerNextCheckMinMs: 60_000,
+    /** Clamp on the model-chosen `nextCheckMs`, upper bound. */
+    overseerNextCheckMaxMs: 900_000,
+    /**
+     * A child's OWN idle watchdog, multiplied by this while the supervisor is
+     * active, so the soft silence inspection at `idleTimeoutMs` always precedes
+     * the hard abort. The watchdog stays as the backstop for a child that
+     * wedges past every inspection.
+     */
+    overseerWatchdogFactor: 4,
 };
 /**
  * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).

package/dist/team/overseer.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The dispatch supervisor (team-overseer).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte.
+ *
+ * A TIME CEILING ON A CHILD IS AN INSPECTION TRIGGER, NOT A DEATH SENTENCE.
+ * When a child stalls (event silence) or simply runs long (the wall clock),
+ * the supervisor looks at it through ONE bounded fast-tier call and decides:
+ * keep waiting, steer a nudge in to help it recover, rebuild it with an
+ * amended brief, or abandon it with a recorded reason. Only the supervisor
+ * "decides"; the RUNTIME applies (see `runtime.ts`), because every child
+ * lifecycle change must funnel through the worker loop that awaits it
+ * (I-OV1).
+ *
+ * THE TRANSPORT IS THE REVIEWER'S, DELIBERATELY. One `complete` call, no
+ * tools, thinking off, temperature 0, output capped at
+ * `FAST_LIMITS.reviewOutputTokens` and wall clock at
+ * `FAST_LIMITS.reviewTimeoutMs` — a supervision call that could itself hang
+ * would need a second supervisor, which is the regress this design refuses.
+ *
+ * REPAIR, NEVER REJECT (the `normalizeSubagentSpecs` rule). An unparseable
+ * or out-of-budget decision becomes `wait` with the default interval: the
+ * failure mode of a supervisor must be "looked and let it run", never
+ * "looked and killed it" (I-OV2).
+ */
+import type { AssistantMessage, LLMRequest, Message } from '@aragon-agent/core';
+import type { ModelRole } from '../config/model-profiles.js';
+import type { CliConfig } from '../config/schema.js';
+import type { OverseerAction, OverseerDecision, SubagentRun, SubagentSpec } from './types.js';
+/** One remembered decision, so the second look knows the first happened. */
+export interface OverseerMemoryEntry {
+    /** Seconds into the dispatch. */
+    atSec: number;
+    action: OverseerAction;
+    reason: string;
+}
+/** Everything one digest is built from. Structural, so tests stub it whole. */
+export interface ChildDigestInput {
+    run: SubagentRun;
+    /** False only in the post-mortem inspection, after the child settled. */
+    childAlive: boolean;
+    trigger: 'silence' | 'clock' | 'postmortem';
+    /** The child's LIVE history (`SubagentAgentLike.state.messages`). */
+    messages: readonly Message[];
+    memory: readonly OverseerMemoryEntry[];
+    /** Seconds the child has been running. */
+    elapsedSec: number;
+}
+/**
+ * Build the bounded text one inspection reads.
+ *
+ * FACTS FIRST, HISTORY SECOND: the byte clamp (`overseerDigestBytes`, via the
+ * same `truncateBytes` the report uses so a CJK tail cannot be split mid
+ * sequence) bites the tail, and the tail is the least decisive part — a
+ * supervisor that cannot see the phase, the retry state and its own memory
+ * is worse than one missing the fifth message back.
+ */
+export declare function buildChildDigest(input: ChildDigestInput): string;
+/** Clamp a model-chosen next check into the structural range. */
+export declare function clampNextCheckMs(ms: unknown): number | undefined;
+/**
+ * Normalize a raw (JSON-parsed or garbage) decision into a safe one.
+ *
+ * `childAlive === false` PHYSICALLY REMOVES two actions: a dead child can be
+ * replaced or abandoned, never waited on or nudged, so those normalize to
+ * `abandon` rather than being rejected — a post-mortem answer the protocol
+ * cannot honour must still produce a decision the runtime can apply.
+ */
+export declare function normalizeOverseerDecision(raw: unknown, childAlive: boolean): OverseerDecision;
+/**
+ * Parse the model's answer text as one JSON decision object.
+ *
+ * Forgiving on PURPOSE: models wrap JSON in prose and fences. The FIRST `{`
+ * to the LAST `}` is the only span tried, and anything that does not parse is
+ * `wait` — the caller never sees a throw from parsing.
+ */
+export declare function parseOverseerDecisionText(text: string, childAlive: boolean): OverseerDecision;
+/** The slice the runtime needs: "can you look?" and "decide". */
+export interface OverseerProvider {
+    /** Live predicate, re-read per dispatch AND per inspection. */
+    active(): boolean;
+    /** One bounded decision call. Implementations must not throw. */
+    inspect(req: {
+        label: string;
+        goal: string;
+        digest: string;
+    }): Promise<OverseerDecision>;
+}
+/** Everything the fast-tier-backed provider needs from the session. */
+export interface FastOverseerDeps {
+    /** Read LIVE: a mid-dispatch `/fast off` must reach the next inspection. */
+    getConfig: () => CliConfig;
+    hasKey: (providerId: string, role?: ModelRole) => boolean;
+    getApiKey: (providerId: string, role?: ModelRole) => string | undefined;
+    /** `FastWiring.completeViaFastRegistry` — the shared fail-fast transport. */
+    complete: (providerId: string, request: LLMRequest) => Promise<AssistantMessage>;
+    /** `FastWiring.available()`. */
+    available: () => boolean;
+}
+/**
+ * The fast-tier-backed provider, mirroring `createChildReviewer`'s shape so
+ * the controller wires it the same way: shared transport, live predicates,
+ * fail-soft (any failure resolves to `wait` — I-OV2).
+ */
+export declare function createFastOverseerProvider(deps: FastOverseerDeps): OverseerProvider;
+/** One inspection request, as the runtime builds it. */
+export interface OverseerInspectRequest {
+    run: SubagentRun;
+    messages: readonly Message[];
+    trigger: 'silence' | 'clock' | 'postmortem';
+    childAlive: boolean;
+}
+export interface TeamOverseerOptions {
+    /** The dispatch's start, so memory entries read as "N s in". */
+    startedAt: number;
+    now?: () => number;
+}
+export declare const OVERSEER_DEFAULT_NEXT_CHECK_MS: 300000;
+/**
+ * Per-dispatch supervisor state: memory, budgets and the single-flight guard.
+ *
+ * THE CLASS NEVER TOUCHES A CHILD (I-OV1). It looks and decides; `runtime.ts`
+ * steers, flags, aborts and rebuilds, because only the worker loop can apply
+ * a lifecycle change without orphaning the replacement.
+ */
+export declare class TeamOverseer {
+    private readonly provider;
+    private readonly options;
+    private readonly memory;
+    private readonly inspections;
+    private readonly replacements;
+    private readonly inFlight;
+    constructor(provider: OverseerProvider, options: TeamOverseerOptions);
+    /** Never throws: a provider bug must not take the dispatch down. */
+    isActive(): boolean;
+    inspectionsExhausted(label: string): boolean;
+    replacementsLeft(label: string): boolean;
+    /** Called by the runtime when it APPLIES a replace, not when it merely reads one. */
+    noteReplacement(label: string): void;
+    /**
+     * ONE inspection. `null` means QUIET — not active, no budget left, or one
+     * already in flight for this child — and the caller then does nothing,
+     * which is exactly what quiet should do.
+     */
+    inspect(req: OverseerInspectRequest): Promise<OverseerDecision | null>;
+}
+/**
+ * Prepend the supervisor's note to a spec's prompt, bounding the TOTAL to
+ * `TEAM_LIMITS.promptChars` so the replacement fits exactly what a
+ * model-supplied spec would have been allowed to carry.
+ *
+ * THE NOTE TELLS THE FRESH CHILD WHAT THE DEAD ONE DID (`filesTouched` is
+ * best-effort, the same caveat the report's conflict warning carries): a
+ * replacement that rewrites a half-written file blind is not a recovery.
+ */
+export declare function buildReplacementPrompt(spec: SubagentSpec, decision: OverseerDecision, previousRun: SubagentRun): string;