@aragon-agent/cli 0.6.21 → 0.6.22

package/dist/team/overseer.d.ts

@@ -1,33 +1,56 @@
 /**
- * The dispatch supervisor (team-overseer).
+ * The dispatch supervisor (team-overseer, upgraded by subagent-overseer-v2).
  *
  * 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:
+ * When a child stalls (event silence) or a cadence tick comes due, 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 SUPERVISOR IS A NO-LOOP, BOUNDED, REMEMBERED CALLEE - NOT AN AGENT
+ * (subagent-overseer-v2 D-1). The requirement says "a dedicated supervising
+ * subagent on the fast model"; it is satisfied by a per-dispatch, remembered,
+ * cadence-woken caller on the fast tier rather than a real `Agent.prompt()`
+ * loop, because a supervisor that can itself wedge needs a second supervisor.
+ *
+ * TWO INSPECTION SHAPES (D-3). Event silence triggers a SINGLE-child look
+ * (fast reaction to a suspected stall, unchanged from round 1); the cadence
+ * ladder triggers a BATCH look that carries every live child in one digest
+ * and returns one JSON array of per-child decisions. The batch call carries
+ * its own output budget (`overseerBatchOutputTokens`, R-P0-1): a full
+ * ten-child reply does not physically fit in the single-inspection 512
+ * tokens, and a truncated reply would parse to nothing - all wait, exactly
+ * when help is most needed.
+ *
  * 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.
+ * tools, thinking off, temperature 0, output capped (512 single /
+ * 2048 batch) 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).
+ * "looked and killed it" (I-OV2). In a batch, one bad ENTRY degrades only
+ * that entry; a wholly unparseable reply degrades the whole batch to wait
+ * with zero action side effects (R-P0-1 / AC-13).
  */
-import type { AssistantMessage, LLMRequest, Message } from '@aragon-agent/core';
+import type { AssistantMessage, LLMRequest, Message, TokenUsage } 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';
+/**
+ * Bumped whenever either supervisor protocol prompt changes (D-9), so a
+ * behaviour report can be tied to a prompt revision with one grep.
+ * `TEAM_BLOCK_VERSION` covers only the LEAD's `<team>` block, not these.
+ */
+export declare const OVERSEER_PROMPT_VERSION = "v2-2026-10";
 /** One remembered decision, so the second look knows the first happened. */
 export interface OverseerMemoryEntry {
     /** Seconds into the dispatch. */
@@ -57,6 +80,38 @@ export interface ChildDigestInput {
  * is worse than one missing the fifth message back.
  */
 export declare function buildChildDigest(input: ChildDigestInput): string;
+/**
+ * The per-child sections of one batch payload (D-3).
+ *
+ * SORTED BY LABEL so the same roster produces the byte-identical payload -
+ * the batch is the one place where ordering is observable to the model and
+ * to every test that asserts on it. Each child's digest is clamped to
+ * `overseerPerChildDigestBytes` (facts first, history tail last - R-P2-5).
+ * The whole-batch ceiling is applied by the joiner in the provider request.
+ */
+export declare function buildBatchSections(children: readonly ChildDigestInput[]): Array<{
+    label: string;
+    goal: string;
+    digest: string;
+}>;
+/**
+ * The FIRST cadence check, from the D-8 priority: `overseerIntervalMs` when
+ * the user named one; otherwise a positive `subagentTimeoutMs` (compat with
+ * users who already treated it as a trigger); otherwise the structural
+ * default. Read-only derivation - the user's stored config is never
+ * rewritten to "resolve" this.
+ */
+export declare function resolveOverseerFirstCheckMs(team: {
+    overseerIntervalMs: number;
+    subagentTimeoutMs: number;
+}): number;
+/**
+ * The next ladder step after one that produced no action: grow by
+ * `overseerCadenceRatio`, clamped to the structural range. With the shipped
+ * 300 s base the checks land at 300 / 780 / 1548 / 2448 / ... seconds - a
+ * healthy slow child is looked at logarithmically in its run time (AC-11).
+ */
+export declare function nextOverseerLadderStepMs(previousMs: number): number;
 /** Clamp a model-chosen next check into the structural range. */
 export declare function clampNextCheckMs(ms: unknown): number | undefined;
 /**
@@ -66,6 +121,10 @@ export declare function clampNextCheckMs(ms: unknown): number | undefined;
  * 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.
+ *
+ * The single-inspection char limits (200/1200) are the defaults here; the
+ * batch path calls `normalizeWithLimits` directly with the tighter protocol
+ * limits (R-P0-1).
  */
 export declare function normalizeOverseerDecision(raw: unknown, childAlive: boolean): OverseerDecision;
 /**
@@ -76,16 +135,47 @@ export declare function normalizeOverseerDecision(raw: unknown, childAlive: bool
  * `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". */
+/**
+ * Parse the model's answer text as a JSON ARRAY of per-child decisions (D-3).
+ *
+ * Same forgiving span rule as the single path - first `[` to last `]` - and
+ * the same failure semantics: a reply that is not an array (prose, a single
+ * object, or TRUNCATED output with no closing `]`) is `[]`, which the caller
+ * turns into all-wait with zero action side effects (R-P0-1 / AC-13). Never
+ * throws.
+ */
+export declare function parseOverseerBatchText(text: string): unknown[];
+/**
+ * The slice the runtime needs: "can you look?", "decide", "what did looking
+ * cost?". The provider is the CALL boundary; `TeamOverseer` owns budgets,
+ * memory and normalization, so a stub in a test scripts decisions by
+ * returning objects or arrays and nothing else.
+ */
 export interface OverseerProvider {
-    /** Live predicate, re-read per dispatch AND per inspection. */
+    /** Live predicate, re-read per tick: this, not the dispatch-time value, decides assisted vs unassisted (R-P0-2). */
     active(): boolean;
-    /** One bounded decision call. Implementations must not throw. */
+    /** One bounded SINGLE-child decision call (silence path). Must not throw. */
     inspect(req: {
         label: string;
         goal: string;
         digest: string;
     }): Promise<OverseerDecision>;
+    /**
+     * One bounded BATCH call (cadence path, D-3). Returns the RAW reply - the
+     * fast provider answers the assistant TEXT - for `TeamOverseer` to parse
+     * and normalize. Must not throw.
+     */
+    inspectBatch(req: ReadonlyArray<{
+        label: string;
+        goal: string;
+        digest: string;
+    }>): Promise<unknown>;
+    /**
+     * Everything this provider has spent on inspection calls (D-7, honest
+     * accounting). Read once by the runtime at dispatch end; there is exactly
+     * one accounting of it and no second aggregation path.
+     */
+    usage(): TokenUsage;
 }
 /** Everything the fast-tier-backed provider needs from the session. */
 export interface FastOverseerDeps {
@@ -102,6 +192,11 @@ export interface FastOverseerDeps {
  * 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).
+ *
+ * USAGE IS ACCUMULATED HERE (D-7), off every `AssistantMessage` the shared
+ * transport returns, along the same `usageOf` / `accumulateUsage` path the
+ * fast reviewer already proved. A reply without a usage block contributes
+ * nothing rather than a fabricated zero-cost total.
  */
 export declare function createFastOverseerProvider(deps: FastOverseerDeps): OverseerProvider;
 /** One inspection request, as the runtime builds it. */
@@ -123,27 +218,70 @@ export declare const OVERSEER_DEFAULT_NEXT_CHECK_MS: 300000;
  * 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.
+ *
+ * LOOKS AND ACTIONS ARE SEPARATE LEDGERS (D-5). A LOOK is cost: every
+ * inspection of a child spends one, including a call that failed softly -
+ * which is what closes G-6 (a flaky transport used to burn the budget the
+ * same as a decision, and the supervisor went quiet exactly when the team
+ * was hardest to see). An ACTION is a mutation (nudge / replace / abandon)
+ * and is counted only when the runtime APPLIES it, through the `note*`
+ * methods below. A label skipped because an inspection is already in flight
+ * spends NOTHING (R-P1-4).
  */
 export declare class TeamOverseer {
     private readonly provider;
     private readonly options;
     private readonly memory;
-    private readonly inspections;
+    private readonly looks;
+    private readonly nudges;
     private readonly replacements;
+    private readonly abandons;
     private readonly inFlight;
+    private looksTotal;
+    private callCount;
     constructor(provider: OverseerProvider, options: TeamOverseerOptions);
     /** Never throws: a provider bug must not take the dispatch down. */
     isActive(): boolean;
-    inspectionsExhausted(label: string): boolean;
+    /** Whether ANY inspection of `label` is in flight (single or batch). */
+    isInFlight(label: string): boolean;
+    /** Per-child look budget spent (D-5). */
+    looksExhausted(label: string): boolean;
+    /** The fool-proof dispatch-wide total (R-P1-6). */
+    dispatchLooksExhausted(): boolean;
+    nudgesLeft(label: string): boolean;
     replacementsLeft(label: string): boolean;
+    abandonsLeft(label: string): boolean;
+    /** Called by the runtime when it APPLIES a nudge, not when it merely reads one. */
+    noteNudge(label: string): void;
     /** Called by the runtime when it APPLIES a replace, not when it merely reads one. */
     noteReplacement(label: string): void;
+    /** Called by the runtime when it APPLIES an abandon, not when it merely reads one. */
+    noteAbandon(label: string): void;
+    /** The provider's own accumulated inspection spend (D-7), zero when unreadable. */
+    usage(): TokenUsage;
+    /** Provider invocations, including ones that failed softly (D-7). */
+    calls(): number;
     /**
-     * ONE inspection. `null` means QUIET — not active, no budget left, or one
-     * already in flight for this child — and the caller then does nothing,
+     * ONE single-child inspection (the silence-triggered path, round-1
+     * behaviour preserved). `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>;
+    /**
+     * ONE batch inspection over every requested child (the cadence path, D-3):
+     * a single fast-tier call, a JSON array back, one decision per child.
+     *
+     * SKIPS FIRST, CALLS SECOND (R-P1-4): a label whose single inspection is
+     * still in flight, or whose look budget is spent, simply gets NO entry -
+     * no decision, no look charged, ladder untouched by the caller. A label
+     * that IS carried but whose reply entry is missing or garbage gets `wait`
+     * (repair, never reject). A wholly unparseable or truncated reply is ALL
+     * wait with zero action side effects (R-P0-1 / AC-13).
+     */
+    inspectBatch(reqs: readonly OverseerInspectRequest[]): Promise<Map<string, OverseerDecision>>;
+    private spendLook;
+    private remember;
 }
 /**
  * Prepend the supervisor's note to a spec's prompt, bounding the TOTAL to