@tangle-network/agent-runtime 0.105.0 → 0.106.1

package/dist/supervise-4_48wwvy.d.ts

@@ -1,379 +0,0 @@
-import { W as WorkerProgress, S as Scope, a as Settled, b as ResultBlobStore, B as Budget, A as Agent, c as SpawnJournal, d as WaitProbeRegistry, e as SupervisedResult } from './types-CvNwMzQt.js';
-import { M as MakeWorkerAgent, A as AnalystRegistry, W as WorkerWatchOptions, E as ExecutorConfig } from './coordination-BZZSVYpZ.js';
-import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './sanitize-DEbPNtyI.js';
-import { D as DeliverableSpec } from './completion-gate-BMy5LGoP.js';
-
-/**
- *
- * PROGRESS-BASED STOP RULES — end a long-horizon run for the right reason.
- *
- * Every existing bound is a CEILING: iterations, tokens, dollars, an absolute deadline, a turn
- * cap. A ceiling answers "may this run continue?" and never "is this run still getting anywhere?".
- * So a supervision tree that stopped learning at settle 4 keeps buying workers until it hits a
- * wall — the run ends on exhaustion, and the operator cannot tell a run that finished from a run
- * that ran out.
- *
- * A stop rule reads the run's own PROGRESS and decides. Three signals feed it:
- *   - the objective curve over settled work (best-so-far, from `anytime.ts` — see below),
- *   - the LIVE worker feed (`WorkerProgress`: `idleMs`, `stalled`, `turns`, `tokens`),
- *   - tree-level shape (how many are in flight, how many are waiting, when the last settle landed).
- *
- * ── Two boundaries this module holds deliberately ───────────────────────────────────────────────
- *
- * ENFORCEMENT lives here; THRESHOLDS do not. "Stop after 5 settles with no improvement" is a
- * judgment about a domain — how noisy its scores are, how expensive a worker is, how much a late
- * breakthrough is worth. That belongs to the caller (a loop, a bench, a product). Every rule below
- * takes its thresholds as required options with no hidden defaults for the numbers that decide;
- * the module ships the MECHANISM and refuses to ship the judgment.
- *
- * A stop rule can only ADD a stop, never remove one. The driver evaluates the hard ceilings
- * (`poolStarved`, `deadlinePassed`, abort, the driver's own stop) FIRST and independently; the
- * rule is consulted only when they all say "continue". So no rule can talk a run past its budget.
- *
- * ── What is reused, not re-derived ──────────────────────────────────────────────────────────────
- *
- * `anytime.ts` already computed best-so-far curves, their area, and plateau detection — but only
- * after a run was over, from waterfall spans. Rather than write a second copy for the live path,
- * `bestSoFar` / `areaUnderCurve` / `plateauLength` were extracted there and are imported here. A
- * stop rule that calls a run plateaued therefore agrees, number for number, with the report that
- * later judges whether stopping was right.
- *
- * @experimental
- */
-
-/** One settled unit of work, reduced to what a stop rule reads. `objective` is the run's own
- *  quality signal (a verdict score, a test pass-rate, a judge rating); `undefined` = this
- *  settlement produced no measurable objective (it failed, or nothing scored it). */
-interface ProgressSample {
-    readonly id: string;
-    /** Epoch ms the settlement was observed. */
-    readonly at: number;
-    readonly objective?: number;
-    /** True when the settlement passed its deliverable check — a scored-but-undelivered result is
-     *  not progress. */
-    readonly delivered: boolean;
-}
-/** The read-model a `StopRule` decides from — the run's progress, not its budget. */
-interface ProgressView {
-    readonly now: number;
-    /** Settlements observed so far, in the order they landed. */
-    readonly settles: number;
-    /** Of those, how many passed their deliverable check. */
-    readonly delivered: number;
-    /** Best-so-far objective after each settlement (`anytime.bestSoFar`). */
-    readonly curve: ReadonlyArray<number>;
-    /** The current best objective; `0` when nothing has scored. */
-    readonly best: number;
-    /** Mean of the best-so-far curve — how EARLY the run climbed (`anytime.areaUnderCurve`). */
-    readonly auc: number;
-    /** Epoch ms of the most recent settlement; `0` when none has landed. */
-    readonly lastSettleAt: number;
-    /** Epoch ms of the most recent improvement in best-so-far; `0` when none. */
-    readonly lastImprovementAt: number;
-    /** Settlements since the last improvement — `0` right after one improves. */
-    readonly settlesSinceImprovement: number;
-    /** Live read of every non-terminal worker (the `Scope.progress` feed). Empty when the caller
-     *  supplied no scope. */
-    readonly workers: ReadonlyArray<WorkerProgress>;
-    /** Nodes running or acquiring. */
-    readonly inFlight: number;
-    /** Armed wait-state nodes — deliberately separate from `inFlight`: a tree whose only remaining
-     *  nodes are waits is NOT stalled, it is waiting on the world. */
-    readonly waiting: number;
-}
-/** A stop rule's answer. `reason` is required when stopping — a run that ends must be able to say
- *  why in the result, and an unexplained early stop is indistinguishable from a bug. */
-type StopDecision = {
-    readonly stop: false;
-} | {
-    readonly stop: true;
-    readonly reason: string;
-};
-/** Evaluated from the progress feed, never from the budget. Pure and synchronous: it is called on
- *  the driver's hot path, once per turn. */
-type StopRule = (view: ProgressView) => StopDecision;
-/** Accumulates settlements and materializes a `ProgressView`. Idempotent by settlement id, so a
- *  caller may re-push its whole roster every turn (the driver does exactly that) without
- *  double-counting or moving a recorded timestamp. */
-interface ProgressTracker {
-    /** Record a settlement. A second call with the same `id` is ignored. Returns true when it was
-     *  new. */
-    record(sample: ProgressSample): boolean;
-    /** Materialize the view. Pass the live `Scope` to include the worker feed and tree shape. */
-    view(scope?: Scope<unknown>, opts?: {
-        readonly stallAfterMs?: number;
-    }): ProgressView;
-    /** Evaluate a rule against the current view. */
-    evaluate(rule: StopRule, scope?: Scope<unknown>, opts?: {
-        readonly stallAfterMs?: number;
-    }): StopDecision;
-    /** The samples recorded so far, in order. */
-    samples(): ReadonlyArray<ProgressSample>;
-}
-interface ProgressTrackerOptions {
-    /** Clock for `view().now`. Defaults to `Date.now`. */
-    readonly now?: () => number;
-    /** Treat a settlement that did NOT pass its deliverable check as having no objective. Default
-     *  true — "scored 0.9 but never delivered" is not progress, and counting it as progress is the
-     *  exact way a plateau rule gets talked out of firing. */
-    readonly requireDelivered?: boolean;
-    /** How much the best-so-far must rise for a settlement to count as an IMPROVEMENT. Default 0
-     *  (any strict rise counts). Raise it to ignore score noise. */
-    readonly minImprovement?: number;
-}
-/** Build the settled-work ledger a `StopRule` decides from: record each settlement (idempotent by
- *  id) and materialize a `ProgressView` combining the best-so-far curve with the live worker feed. */
-declare function createProgressTracker(opts?: ProgressTrackerOptions): ProgressTracker;
-/** Build a `ProgressSample` from a scope settlement. The objective is the verdict score and
- *  `delivered` is the verdict's `valid` — the SAME single delivery signal `finalizeBestDelivered`
- *  and `defaultSelectWinner` use, so "progress" and "winner" cannot disagree. */
-declare function sampleFromSettled(settled: Settled<unknown>, at: number): ProgressSample;
-interface NoProgressForOptions {
-    /** Stop when this many ms have passed since the last SETTLEMENT. Omit to not bound on time. */
-    readonly ms?: number;
-    /** Stop when this many settlements have landed with no improvement in best-so-far. Omit to not
-     *  bound on settles. */
-    readonly settles?: number;
-    /** Never stop before this many settlements have landed — the warm-up that stops a rule from
-     *  firing on an empty run. Default 1. */
-    readonly minSettles?: number;
-}
-/**
- * "Nothing new has happened." Fires when the run has produced no new settled work for `ms`, or no
- * IMPROVEMENT over the last `settles` settlements.
- *
- * A tree whose only remaining nodes are armed WAITS is exempt from the time bound: a run waiting
- * on CI is not a run that stopped making progress, and killing it there would defeat mechanic C.
- */
-declare function noProgressFor(opts: NoProgressForOptions): StopRule;
-interface PlateauOptions {
-    /** How many trailing settlements to judge. The rule fires when the whole window failed to lift
-     *  the best-so-far by more than `minDelta`. */
-    readonly window: number;
-    /** The rise that counts as an improvement — the domain's noise floor. `0` means any strict rise
-     *  counts. */
-    readonly minDelta: number;
-    /** Never fire before this many settlements. Defaults to `window` (so the first decision is made
-     *  on a full window, not on a partial one). */
-    readonly minSettles?: number;
-}
-/**
- * "The objective has stopped climbing." Fires when the best-so-far curve has risen by no more than
- * `minDelta` across the last `window` settlements.
- *
- * Built on `anytime.plateauLength` — the same plateau math the post-run anytime report uses, so a
- * rule that stops a run and a report that grades the decision cannot disagree about whether the
- * run was flat.
- */
-declare function plateau(opts: PlateauOptions): StopRule;
-interface AllWorkersStalledOptions {
-    /** Require at least this many live workers before the rule can fire — one stalled worker in a
-     *  one-worker tree is a weaker signal than a whole fleet going quiet. Default 1. */
-    readonly minWorkers?: number;
-    /** Idle time that counts as stalled, passed through to the live progress read. Omit = the
-     *  runtime default (`DEFAULT_STALL_AFTER_MS`). */
-    readonly stallAfterMs?: number;
-}
-/**
- * "Everyone is stuck." Fires when every live worker reads `stalled` — no metered activity for
- * longer than the stall threshold — and none of the tree is merely waiting.
- *
- * `stalled` is a derived read at observation time, never a background watchdog; this rule only
- * reads it. A tree with armed waits never fires: waiting is not stalling.
- */
-declare function allWorkersStalled(opts?: AllWorkersStalledOptions): StopRule;
-/** Stop when ANY rule stops — the ordinary composition (each rule is a separate reason to end). */
-declare function anyOf(...rules: ReadonlyArray<StopRule>): StopRule;
-/** Stop only when EVERY rule stops — for a conservative gate that needs corroboration. */
-declare function allOf(...rules: ReadonlyArray<StopRule>): StopRule;
-
-/** The supervisor's profile — the subset of an `AgentProfile` that selects + shapes its brain.
- *  `harness` is the backend-as-data discriminant; `systemPrompt` is the standing instruction. */
-interface SupervisorProfile {
-    readonly name?: string;
-    /** null/undefined → router brain (in-process tool-loop); a coding-CLI harness → sandboxed brain. */
-    readonly harness?: string | null;
-    /** The router model when the brain is router-driven (falls back to the deps router config). */
-    readonly model?: string;
-    /** The standing instructions ("you delegate, you do not solve"). */
-    readonly systemPrompt?: string;
-}
-/** How to run a sandboxed harness as the DRIVER, with the coordination verbs mounted — the substrate
- *  seam the caller supplies (mirrors `makeWorkerAgent` for spawned children). It runs `profile` on
- *  `task` in its backend (sandbox / cli-bridge) with `coordinationMcpUrl` mounted as an MCP server,
- *  so the harness calls spawn_agent / await_event / stop as native tools over the live scope. */
-type DriveHarness = (args: {
-    readonly profile: SupervisorProfile;
-    readonly task: unknown;
-    readonly scope: Scope<unknown>;
-    readonly coordinationMcpUrl: string;
-}) => Promise<void>;
-interface SupervisorAgentDeps {
-    readonly blobs: ResultBlobStore;
-    /** Resolve a spawned worker `profile` to a leaf agent — the recursion seam (same for both arms). */
-    readonly makeWorkerAgent: MakeWorkerAgent;
-    /** Per-child budget reserved from the conserved pool on each spawn. */
-    readonly perWorker: Budget;
-    /** Hard cap on simultaneously-LIVE workers across both arms — `spawn_agent` fails closed once
-     *  this many are in flight (a concurrency fence on top of the conserved-pool fence; bounds live
-     *  boxes/sandboxes, not total work). Omit/`<= 0` = no cap. */
-    readonly maxLiveWorkers?: number;
-    /** Router substrate for a router-brained supervisor (`harness` null). The profile's model wins. */
-    readonly router?: RouterConfig;
-    /** Inject the brain directly (tests / advanced) instead of resolving `routerBrain` from the profile. */
-    readonly brain?: ToolLoopChat;
-    /** Required for a sandboxed-harness supervisor (`harness` set): runs the harness as the driver. */
-    readonly driveHarness?: DriveHarness;
-    /** WORK tools the supervisor may call DIRECTLY (router arm) — so it can do simple work ITSELF and
-     *  only delegate when it needs parallelism. Pair with `executeExtraTool`. */
-    readonly extraTools?: ReadonlyArray<{
-        readonly name: string;
-        readonly description?: string;
-        readonly parameters: Record<string, unknown>;
-    }>;
-    /** Runs an `extraTools` call; null/undefined falls through to the coordination dispatch. */
-    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
-    /** Analyst lenses available to the driver (both arms). Required for `analyzeOnSettle`. */
-    readonly analysts?: AnalystRegistry;
-    /** Analyst kinds run on each worker-settle → a `finding` the driver composes its next steer from
-     *  (the self-improving UP-leg). Unset/empty = status quo (no analyst feed). Requires `analysts`. */
-    readonly analyzeOnSettle?: ReadonlyArray<string>;
-    /** Run the ONLINE detector panel over each worker's LIVE tool trace (both arms) so the driver
-     *  learns a worker is looping mid-run instead of at settle. Omit = no online watching. */
-    readonly watchWorkers?: WorkerWatchOptions;
-    /** Idle time after which `observe_agent` reports a worker as stalled. Omit = runtime default. */
-    readonly stallAfterMs?: number;
-    /** PROGRESS-derived stop rule (router arm). Ends a run that has stopped learning BEFORE it
-     *  exhausts a ceiling; it can never keep a run alive past one. Build it with `plateau` /
-     *  `noProgressFor` / `allWorkersStalled` from `supervise/stop-rules` — the thresholds are the
-     *  caller's judgment. Omit = ceilings only. */
-    readonly stopRule?: StopRule;
-    /** One-shot notification of WHY a `stopRule` ended the run. */
-    readonly onProgressStop?: (reason: string) => void;
-    readonly maxTurns?: number;
-    /** Give the supervisor brain a chapter-lifecycle on its OWN context window (router arm only) — it
-     *  distills its coordination transcript to a compact progress note once it exceeds the threshold,
-     *  instead of re-billing the whole thing every turn. See `DriverAgentOptions.compaction`. */
-    readonly compaction?: ToolLoopCompactionOptions;
-}
-/** Build a supervisor `Agent` from its profile: the brain resolves from `profile.harness` (backend-as-data), the same resolution rule as every worker. */
-declare function supervisorAgent(profile: SupervisorProfile, deps: SupervisorAgentDeps): Agent<unknown, unknown>;
-
-/** Build the worker seam from a backend (WHERE workers run) + an optional completion oracle (the
- *  deliverable check that makes "settled ⟺ delivered" true — the guard against "ran but didn't
- *  deliver"). The ONE place a backend becomes a spawnable worker. */
-declare function workerFromBackend(backend: ExecutorConfig, deliverable?: DeliverableSpec<unknown>): MakeWorkerAgent;
-interface SuperviseOptions {
-    /** The conserved compute pool for the whole run. */
-    readonly budget: Budget;
-    /** WHERE workers run — derives the worker seam. Provide this OR an explicit `makeWorkerAgent`. */
-    readonly backend?: ExecutorConfig;
-    /** The completion oracle for backend-derived workers (settled ⟺ delivered). Strongly recommended:
-     *  without it the supervisor trusts a worker's self-report — exactly the "ran but didn't deliver"
-     *  failure mode of a static orchestrator. */
-    readonly deliverable?: DeliverableSpec<unknown>;
-    /** Override the worker seam directly (tests / advanced) instead of deriving it from `backend`. */
-    readonly makeWorkerAgent?: MakeWorkerAgent;
-    /** The supervisor's router substrate (`harness` null). The profile's model wins. */
-    readonly router?: RouterConfig;
-    /** Inject the supervisor brain directly (tests / advanced). */
-    readonly brain?: ToolLoopChat;
-    /** Run a sandboxed-harness supervisor (`harness` set). */
-    readonly driveHarness?: DriveHarness;
-    /** WORK tools the supervisor may call DIRECTLY — so a recursive atom can ACT (do simple work
-     *  itself) OR SPAWN (delegate when it needs parallelism), not be a pure manager. Pair with
-     *  `executeExtraTool`. Router arm only (`harness` null). */
-    readonly extraTools?: ReadonlyArray<{
-        readonly name: string;
-        readonly description?: string;
-        readonly parameters: Record<string, unknown>;
-    }>;
-    /** Runs an `extraTools` call; null/undefined falls through to the coordination dispatch. */
-    readonly executeExtraTool?: (name: string, args: Record<string, unknown>) => Promise<string | null | undefined>;
-    /** Per-child budget reserved on each spawn. Defaults to a quarter of the pool's tokens. */
-    readonly perWorker?: Budget;
-    /** Hard cap on simultaneously-LIVE workers — `spawn_agent` fails closed once this many are in
-     *  flight. The conserved pool bounds TOTAL work; this bounds SIMULTANEOUS work (live boxes/
-     *  sandboxes a real fleet runs at once). Omit/`<= 0` = no cap (the pool stays the only fence). */
-    readonly maxLiveWorkers?: number;
-    /** Analyst lenses available to the driver. Required for `analyzeOnSettle`. Unset → status quo
-     *  (the driver receives settled worker outputs, no analyst findings). */
-    readonly analysts?: AnalystRegistry;
-    /** Analyst kind ids run AUTOMATICALLY when a worker settles `done` — each re-enters as a `finding`
-     *  the driver pulls (`await_event`) and composes its next steer from. The self-improving UP-leg,
-     *  threaded to the driver at this level (propagate to sub-drivers via a recursive `makeWorkerAgent`).
-     *  Omit/empty = status quo (no analyst feed). Requires `analysts`. */
-    readonly analyzeOnSettle?: ReadonlyArray<string>;
-    /**
-     * Watch every worker's LIVE tool trace with the online detector panel and raise a `finding` the
-     * moment one loops or error-storms — so the supervisor learns it mid-run (via `await_event`)
-     * instead of at settle. Pairs with a steerable worker: the finding is the evidence, `steer_agent`
-     * is the correction. Requires a backend whose executor exposes a trace source (the steerable
-     * sandbox worker and the pi wrapper do); other runtimes are simply not watched.
-     *
-     * Omit = off (status quo — no online watching, no extra events).
-     */
-    readonly watchWorkers?: WorkerWatchOptions;
-    /** Idle time after which `observe_agent` reports a running worker as `stalled`. A derived read
-     *  at observation time — nothing is killed or retried. Omit = the runtime default. */
-    readonly stallAfterMs?: number;
-    /** Worker output store. Defaults to in-memory. */
-    readonly blobs?: ResultBlobStore;
-    /**
-     * Make the run DURABLE: journal + result blobs are file-backed under this directory
-     * (`createFileRunContext`), fsynced per write, and the supervisor reads the prior tree first.
-     * Re-running with the same `runDir` AND the same `runId` resumes — the children that already
-     * settled are replayed onto `Scope.resume` with their real outputs, and the scope's counters
-     * continue past the journaled maxima. Unset = in-memory, fresh every call.
-     *
-     * What that does and does not buy you, precisely: the run's history survives the process and is
-     * replayable, and a resumed run never corrupts the tree. It does NOT by itself make the built-in
-     * supervisor brain skip committed work — `supervisorAgent`'s driver does not read
-     * `Scope.resume`, so out of the box a resumed run re-spawns children it already paid for. Only a
-     * root `Agent.act` that reads `scope.resume.settled` (as the durable-resume test's root does)
-     * turns durability into work-skipping. Wiring that into the default brain is separate work.
-     *
-     * `runId` matters here: it defaults to the constant `'supervise'`, which is fine for a single
-     * resumable run per directory but collides across concurrent runs sharing one `runDir`.
-     */
-    readonly runDir?: string;
-    /** Override the spawn journal directly (advanced; `runDir` is the ordinary durable path). Pair
-     *  with `blobs` — a journal whose result payloads live in a different store cannot replay. */
-    readonly journal?: SpawnJournal;
-    /** Predicate registry for `poll` wait-states (`Scope.wait`). A `poll` names its predicate so the
-     *  wait survives a restart; this is what the name resolves against. Unset ⇒ `poll` waits are
-     *  refused `unknown-probe` and `timer` waits still work. */
-    readonly probes?: WaitProbeRegistry;
-    /**
-     * PROGRESS-derived stop rule (router-brained supervisor). Ends a run that has stopped LEARNING
-     * before it exhausts a ceiling — the answer to "a run should end because it is done or stuck,
-     * not because it ran out". It composes with the budget guards and can never override one.
-     *
-     * Build it from `supervise/stop-rules`: `plateau({window, minDelta})`,
-     * `noProgressFor({ms, settles})`, `allWorkersStalled({...})`, combined with `anyOf`/`allOf`. The
-     * thresholds are policy and stay with you; the enforcement lives in the runtime. Omit = ceilings
-     * only (unchanged behavior).
-     */
-    readonly stopRule?: StopRule;
-    /** One-shot notification of WHY a `stopRule` ended the run — so a caller records the reason
-     *  instead of inferring an early stop from an unexhausted budget. */
-    readonly onProgressStop?: (reason: string) => void;
-    readonly maxDepth?: number;
-    readonly maxTurns?: number;
-    /** Give the supervisor brain a chapter-lifecycle on its OWN context window (router arm only): once
-     *  its coordination transcript exceeds `thresholdTokens` it distills to a compact progress note and
-     *  continues, instead of re-billing the whole transcript every turn (the cost that makes the LLM-brain
-     *  front door lose to a dumb-Ralph respawn). The live `Scope` roster is the durable state across
-     *  chapters. Default off. `distill` defaults to a brain self-summary + the settled-worker roster. */
-    readonly compaction?: ToolLoopCompactionOptions;
-    readonly runId?: string;
-    readonly now?: () => number;
-    /** Restrict the run to this subset of models. When set, every configured model — the
-     *  supervisor router model, the profile's model, and the backend's model — must be a member,
-     *  or `supervise()` throws a `ConfigError` before any compute is spent. Unset = unrestricted. */
-    readonly allowedModels?: readonly string[];
-}
-/** One-call supervisor: build + run a supervisor from its profile with sensible defaults; the raw `supervisorAgent` + `createSupervisor().run` seams stay available for power use. */
-declare function supervise(profile: SupervisorProfile, task: unknown, opts: SuperviseOptions): Promise<SupervisedResult<unknown>>;
-
-export { type AllWorkersStalledOptions as A, type DriveHarness as D, type NoProgressForOptions as N, type PlateauOptions as P, type StopRule as S, type SupervisorProfile as a, type ProgressSample as b, type ProgressTracker as c, type ProgressTrackerOptions as d, type ProgressView as e, type StopDecision as f, type SuperviseOptions as g, type SupervisorAgentDeps as h, allOf as i, allWorkersStalled as j, anyOf as k, createProgressTracker as l, supervise as m, noProgressFor as n, supervisorAgent as o, plateau as p, sampleFromSettled as s, workerFromBackend as w };