bare-agent 0.19.0 → 0.20.0

package/src/recurse.d.ts

@@ -0,0 +1,361 @@
+/**
+ * The per-run runtime blob — the wiring, threaded down the whole recursion tree (and forwarded to the worker
+ * Loop's `policy`/governance via `options.ctx`). Distinct from `opts` (the policy knobs).
+ */
+export type RecurseCtx = {
+    /**
+     * - The model the workers call. Required (here or on `opts.provider`).
+     */
+    provider?: import("../types").Provider | undefined;
+    /**
+     * - bareguard `policy(tool, args, ctx)` — the gate. Sees `ctx.depth` so it can
+     * enforce `limits.maxDepth`/budget/calls. recurse adds NO second guard layer (§6).
+     */
+    policy?: Function | undefined;
+    /**
+     * - Budget hook forwarded to every worker Loop AND the verifier — judge
+     * and worker tokens are all real spend (BA1: never invisible).
+     */
+    onLlmResult?: Function | undefined;
+    /**
+     * - The current recursion depth (0 at the top). Incremented on each self-call;
+     * threaded into `policy`. Callers normally omit it (defaults to 0).
+     */
+    depth?: number | undefined;
+    /**
+     * - Optional event stream forwarded to each worker Loop (receipts substrate).
+     */
+    stream?: object;
+    /**
+     * - Optional litectx handle (RC-5, §10 step 7). Backs the `search`
+     * retrieval mode (`recall`). NOT used by `scan` — litectx has no exhaustive enumerate verb today; scan reads
+     * the generic array slice-source `opts.corpus` instead (the litectx-resident scan case waits on the litectx
+     * `enumerate` verb and drops in behind the same socket).
+     */
+    litectx?: {
+        recall: Function;
+    } | undefined;
+};
+export type RecurseOptions = {
+    /**
+     * - Fallback provider if `ctx.provider` is absent.
+     */
+    provider?: import("../types").Provider | undefined;
+    /**
+     * - Open topology ceiling (§1): the depth past which the `spawn_child` tool is
+     * no longer offered (`maxDepth=1` ⇒ flat fan-out, no nesting). NOT the safety halt — that is bareguard's,
+     * and actual depth is always ≤ `limits.maxDepth`.
+     */
+    maxDepth?: number | undefined;
+    /**
+     * - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
+     * `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
+     */
+    tools?: import("../types").ToolDef[] | undefined;
+    /**
+     * - Definition of done (A3). When present, the verifier grades against THIS,
+     * not the loose task, and verification always runs.
+     */
+    contract?: string | undefined;
+    /**
+     * Override the verifier (fills `recurse()`'s verify slot, §7.1). Default = an `Evaluator` rubric pass.
+     */
+    evaluate?: ((result: any, ctx: {
+        contract: string | null;
+        task: string;
+    }) => (Verdict | Promise<Verdict>)) | undefined;
+    /**
+     * Override synthesis/reduce (NB-3). A FUNCTION is a deterministic code-reduce over the child `results` — the
+     * §9.1 aggregation path (LLM arithmetic over partials carried ~10–15% error). A STRATEGY string runs the
+     * built-in reducer: `'concat'` (lossless no-LLM join) or `'merge'` (an isolated Loop-driven subjective
+     * merge); a string is ignored when no child ran. Default (unset) = the worker's own final text (Family A:
+     * the parent model already combined the children's results in its closing turn).
+     */
+    synthesize?: "concat" | "merge" | ((args: {
+        task: string;
+        text: string | null;
+        results: any[];
+        children: object[];
+        ctx: RecurseCtx;
+    }) => any) | undefined;
+    /**
+     * - (Opt-in, NB-2 / Family B) FORCED fan-out: decompose into exactly this many
+     * independent parallel workers via `Planner`→`runPlan`, then reduce. A positive integer here is the count;
+     * it OVERRIDES the tier→count map. Setting it (or `mode:'fanout'`) takes the deterministic-parallelism path
+     * instead of the model-driven Family-A default. For known-parallel tasks where the caller wants guaranteed
+     * fan-out, not the model's adaptive choice.
+     */
+    count?: number | undefined;
+    /**
+     * - (Opt-in, NB-2 / Family B) `'fanout'` = forced semantic fan-out
+     * WITHOUT a fixed count — derived from `assessComplexity`'s tier via the calibrated map (medium/complex/
+     * critical → 2/4/6; simple → 1); `opts.count` takes precedence. `'partition'` = the DATA-DRIVEN WIDTH path
+     * (§11): measure `opts.corpus` and partition it into `max(opts.count floor, ⌈size/workerBudget⌉)` parallel
+     * scan-workers (capped by the guards), CODE-reducing the per-chunk counts. Distinct from `'fanout'`: a data
+     * partition, not a `Planner` semantic split.
+     */
+    mode?: "fanout" | "partition" | undefined;
+    /**
+     * - (`mode:'partition'`) items per worker; width = `⌈corpus.length /
+     * workerBudget⌉` (default 100). A calibratable knob (the §9.1 algorithm), not a discovered constant.
+     */
+    workerBudget?: number | undefined;
+    /**
+     * - (Family B) max workers run at once per wave (default 4). The wave
+     * structure is `runPlan`'s; bareguard still bounds the family rate independently.
+     */
+    concurrency?: number | undefined;
+    /**
+     * - (§10 step 7) the retrieval shape for a task OVER A
+     * CORPUS, routed by question shape (§9.2.1). `'scan'` (the default WHEN `opts.corpus` is present) = process
+     * every slice + LLM-judge + CODE-count — the only COMPLETE path (for "how many / all"). `'search'` = litectx
+     * `recall` handle tool offered to the worker (needle; CANNOT count; requires `ctx.litectx`). `'exact'` = a
+     * deterministic code-side AND-term filter tool over `opts.corpus`. `'tools'` = the PER-QUERY Family-A face:
+     * offer the worker `scan_count` (over `opts.corpus`) + `search_memory` (when `ctx.litectx`) + `exact_match`
+     * (array corpus) ALL AT ONCE, and let it pick the shape PER SUB-QUERY — the routing lives in the tool
+     * descriptions (scan says "use for how many / all / count"; search says "never count"), so a mixed task gets
+     * needle-search AND complete-count without per-sub-query adopter declaration. The completeness guard upgrades a
+     * `'search'` on a "how many / all" ask to `'scan'` (UPGRADE-only, never a silent downgrade); it does NOT fire
+     * for `'tools'` (the complete `scan_count` is always offered there, so a mixed task keeps its search tool).
+     * Absent `corpus` AND `retrieval`, behaviour is unchanged (Family A / single-shot) — fully backward-compatible.
+     */
+    retrieval?: "tools" | "search" | "scan" | "exact" | undefined;
+    /**
+     * - (§10 step 7) the generic slice-source scan/partition
+     * reads: an in-hand `{id, text}[]` array, OR an async `() => Promise<Slice[]>` (e.g. `litectxCorpus(litectx,
+     * {kind})` materializing a litectx-resident corpus via `enumerate`). recurse depends on this SHAPE, never on
+     * litectx. Malformed entries are dropped, never miscounted.
+     */
+    corpus?: Slice[] | (() => Promise<Slice[]>) | undefined;
+    /**
+     * - (scan) items per judge window. Default 8 (§9.2.1 recall knee — the one
+     * calibrated number; per-model).
+     */
+    window?: number | undefined;
+    /**
+     * - (scan) shuffled-boundary passes unioned for recall. Default 2 (~0.91 recall).
+     */
+    passes?: number | undefined;
+};
+/**
+ * One audit/receipts node (RC-10) — the recursion tree reconstructs from these alone: parent→child lineage
+ * (`spawned`), each subgoal (`task`), each gap report (`verdict`), cost per node (`tokens`).
+ */
+export type RecurseNode = {
+    task: string;
+    depth: number;
+    complexity: {
+        level: string;
+        score: number;
+    };
+    critical: boolean;
+    /**
+     * - Child nodes (lineage).
+     */
+    spawned: RecurseNode[];
+    verdict: Verdict | null;
+    incomplete: boolean;
+    halted: boolean;
+    /**
+     * - The worker Loop's `metrics.tokens`.
+     */
+    tokens: object | null;
+    model: string | null;
+    /**
+     * - (§10 step 7) the retrieval mode this node ran (`scan`/`search`/`exact`),
+     * or null/absent for a plain reasoning node.
+     */
+    retrieval?: string | null | undefined;
+    /**
+     * - set when the completeness guard upgraded the mode (e.g.
+     * `'search→scan (completeness)'`) — the audit trail for RC-9-applied-to-retrieval.
+     */
+    retrievalUpgraded?: string | undefined;
+    /**
+     * - (scan) the scan
+     * shape: window/passes used, slices scanned, ids matched (CODE-counted).
+     */
+    scan?: {
+        window: number;
+        passes: number;
+        scanned: number;
+        matched: number;
+    } | undefined;
+    /**
+     * - (`mode:'partition'`) the data-driven width audit: corpus size, the budget knob, the count floor, the
+     * data-derived width `⌈size/budget⌉`, the chosen `width = max(floor, dataWidth)`, and matched count.
+     */
+    partition?: {
+        size: number;
+        workerBudget: number;
+        floor: number;
+        dataWidth: number;
+        width: number;
+        matched?: number;
+    } | undefined;
+};
+export type RecurseResult = {
+    /**
+     * - The synthesized answer (on convergence).
+     */
+    result?: any;
+    /**
+     * - The verifier's gap report (null when verification did not run).
+     */
+    verdict?: import("./evaluator").Verdict | null | undefined;
+    /**
+     * - true on guard exhaustion / a dead worker / an incomplete child (RC-9) —
+     * never a faked pass.
+     */
+    incomplete?: boolean | undefined;
+    /**
+     * - The best partial answer when `incomplete` (RC-9).
+     */
+    best?: any;
+    /**
+     * - When `incomplete` because a child failed: the sub-task(s) that came
+     * back incomplete (§9 scenario 1) — the anti-survivor-sum signal, not a quiet undercount.
+     */
+    missingSlices?: string[] | undefined;
+    /**
+     * - The audit node for this call (RC-10).
+     */
+    receipts: RecurseNode;
+};
+export type Provider = import("../types").Provider;
+export type ToolDef = import("../types").ToolDef;
+export type Verdict = import("./evaluator").Verdict;
+export type Slice = {
+    id: string;
+    text: string;
+};
+/**
+ * @typedef {object} RecurseCtx
+ * The per-run runtime blob — the wiring, threaded down the whole recursion tree (and forwarded to the worker
+ * Loop's `policy`/governance via `options.ctx`). Distinct from `opts` (the policy knobs).
+ * @property {Provider} [provider] - The model the workers call. Required (here or on `opts.provider`).
+ * @property {Function} [policy] - bareguard `policy(tool, args, ctx)` — the gate. Sees `ctx.depth` so it can
+ *   enforce `limits.maxDepth`/budget/calls. recurse adds NO second guard layer (§6).
+ * @property {Function} [onLlmResult] - Budget hook forwarded to every worker Loop AND the verifier — judge
+ *   and worker tokens are all real spend (BA1: never invisible).
+ * @property {number} [depth] - The current recursion depth (0 at the top). Incremented on each self-call;
+ *   threaded into `policy`. Callers normally omit it (defaults to 0).
+ * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate).
+ * @property {{recall: Function}} [litectx] - Optional litectx handle (RC-5, §10 step 7). Backs the `search`
+ *   retrieval mode (`recall`). NOT used by `scan` — litectx has no exhaustive enumerate verb today; scan reads
+ *   the generic array slice-source `opts.corpus` instead (the litectx-resident scan case waits on the litectx
+ *   `enumerate` verb and drops in behind the same socket).
+ */
+/**
+ * @typedef {object} RecurseOptions
+ * @property {Provider} [provider] - Fallback provider if `ctx.provider` is absent.
+ * @property {number} [maxDepth=3] - Open topology ceiling (§1): the depth past which the `spawn_child` tool is
+ *   no longer offered (`maxDepth=1` ⇒ flat fan-out, no nesting). NOT the safety halt — that is bareguard's,
+ *   and actual depth is always ≤ `limits.maxDepth`.
+ * @property {ToolDef[]} [tools] - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
+ *   `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
+ * @property {string} [contract] - Definition of done (A3). When present, the verifier grades against THIS,
+ *   not the loose task, and verification always runs.
+ * @property {(result: any, ctx: {contract: string|null, task: string}) => (Verdict|Promise<Verdict>)} [evaluate]
+ *   Override the verifier (fills `recurse()`'s verify slot, §7.1). Default = an `Evaluator` rubric pass.
+ * @property {((args: {task: string, text: string|null, results: any[], children: object[], ctx: RecurseCtx}) => any) | 'concat' | 'merge'} [synthesize]
+ *   Override synthesis/reduce (NB-3). A FUNCTION is a deterministic code-reduce over the child `results` — the
+ *   §9.1 aggregation path (LLM arithmetic over partials carried ~10–15% error). A STRATEGY string runs the
+ *   built-in reducer: `'concat'` (lossless no-LLM join) or `'merge'` (an isolated Loop-driven subjective
+ *   merge); a string is ignored when no child ran. Default (unset) = the worker's own final text (Family A:
+ *   the parent model already combined the children's results in its closing turn).
+ * @property {number} [count] - (Opt-in, NB-2 / Family B) FORCED fan-out: decompose into exactly this many
+ *   independent parallel workers via `Planner`→`runPlan`, then reduce. A positive integer here is the count;
+ *   it OVERRIDES the tier→count map. Setting it (or `mode:'fanout'`) takes the deterministic-parallelism path
+ *   instead of the model-driven Family-A default. For known-parallel tasks where the caller wants guaranteed
+ *   fan-out, not the model's adaptive choice.
+ * @property {'fanout'|'partition'} [mode] - (Opt-in, NB-2 / Family B) `'fanout'` = forced semantic fan-out
+ *   WITHOUT a fixed count — derived from `assessComplexity`'s tier via the calibrated map (medium/complex/
+ *   critical → 2/4/6; simple → 1); `opts.count` takes precedence. `'partition'` = the DATA-DRIVEN WIDTH path
+ *   (§11): measure `opts.corpus` and partition it into `max(opts.count floor, ⌈size/workerBudget⌉)` parallel
+ *   scan-workers (capped by the guards), CODE-reducing the per-chunk counts. Distinct from `'fanout'`: a data
+ *   partition, not a `Planner` semantic split.
+ * @property {number} [workerBudget] - (`mode:'partition'`) items per worker; width = `⌈corpus.length /
+ *   workerBudget⌉` (default 100). A calibratable knob (the §9.1 algorithm), not a discovered constant.
+ * @property {number} [concurrency] - (Family B) max workers run at once per wave (default 4). The wave
+ *   structure is `runPlan`'s; bareguard still bounds the family rate independently.
+ * @property {'scan'|'search'|'exact'|'tools'} [retrieval] - (§10 step 7) the retrieval shape for a task OVER A
+ *   CORPUS, routed by question shape (§9.2.1). `'scan'` (the default WHEN `opts.corpus` is present) = process
+ *   every slice + LLM-judge + CODE-count — the only COMPLETE path (for "how many / all"). `'search'` = litectx
+ *   `recall` handle tool offered to the worker (needle; CANNOT count; requires `ctx.litectx`). `'exact'` = a
+ *   deterministic code-side AND-term filter tool over `opts.corpus`. `'tools'` = the PER-QUERY Family-A face:
+ *   offer the worker `scan_count` (over `opts.corpus`) + `search_memory` (when `ctx.litectx`) + `exact_match`
+ *   (array corpus) ALL AT ONCE, and let it pick the shape PER SUB-QUERY — the routing lives in the tool
+ *   descriptions (scan says "use for how many / all / count"; search says "never count"), so a mixed task gets
+ *   needle-search AND complete-count without per-sub-query adopter declaration. The completeness guard upgrades a
+ *   `'search'` on a "how many / all" ask to `'scan'` (UPGRADE-only, never a silent downgrade); it does NOT fire
+ *   for `'tools'` (the complete `scan_count` is always offered there, so a mixed task keeps its search tool).
+ *   Absent `corpus` AND `retrieval`, behaviour is unchanged (Family A / single-shot) — fully backward-compatible.
+ * @property {Slice[] | (() => Promise<Slice[]>)} [corpus] - (§10 step 7) the generic slice-source scan/partition
+ *   reads: an in-hand `{id, text}[]` array, OR an async `() => Promise<Slice[]>` (e.g. `litectxCorpus(litectx,
+ *   {kind})` materializing a litectx-resident corpus via `enumerate`). recurse depends on this SHAPE, never on
+ *   litectx. Malformed entries are dropped, never miscounted.
+ * @property {number} [window] - (scan) items per judge window. Default 8 (§9.2.1 recall knee — the one
+ *   calibrated number; per-model).
+ * @property {number} [passes] - (scan) shuffled-boundary passes unioned for recall. Default 2 (~0.91 recall).
+ */
+/**
+ * @typedef {object} RecurseNode
+ * One audit/receipts node (RC-10) — the recursion tree reconstructs from these alone: parent→child lineage
+ * (`spawned`), each subgoal (`task`), each gap report (`verdict`), cost per node (`tokens`).
+ * @property {string} task
+ * @property {number} depth
+ * @property {{level: string, score: number}} complexity
+ * @property {boolean} critical
+ * @property {RecurseNode[]} spawned - Child nodes (lineage).
+ * @property {Verdict|null} verdict
+ * @property {boolean} incomplete
+ * @property {boolean} halted
+ * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
+ * @property {string|null} model
+ * @property {string|null} [retrieval] - (§10 step 7) the retrieval mode this node ran (`scan`/`search`/`exact`),
+ *   or null/absent for a plain reasoning node.
+ * @property {string} [retrievalUpgraded] - set when the completeness guard upgraded the mode (e.g.
+ *   `'search→scan (completeness)'`) — the audit trail for RC-9-applied-to-retrieval.
+ * @property {{window: number, passes: number, scanned: number, matched: number}} [scan] - (scan) the scan
+ *   shape: window/passes used, slices scanned, ids matched (CODE-counted).
+ * @property {{size: number, workerBudget: number, floor: number, dataWidth: number, width: number, matched?: number}} [partition]
+ *   - (`mode:'partition'`) the data-driven width audit: corpus size, the budget knob, the count floor, the
+ *   data-derived width `⌈size/budget⌉`, the chosen `width = max(floor, dataWidth)`, and matched count.
+ */
+/**
+ * @typedef {object} RecurseResult
+ * @property {any} [result] - The synthesized answer (on convergence).
+ * @property {Verdict|null} [verdict] - The verifier's gap report (null when verification did not run).
+ * @property {boolean} [incomplete] - true on guard exhaustion / a dead worker / an incomplete child (RC-9) —
+ *   never a faked pass.
+ * @property {any} [best] - The best partial answer when `incomplete` (RC-9).
+ * @property {string[]} [missingSlices] - When `incomplete` because a child failed: the sub-task(s) that came
+ *   back incomplete (§9 scenario 1) — the anti-survivor-sum signal, not a quiet undercount.
+ * @property {RecurseNode} receipts - The audit node for this call (RC-10).
+ */
+/**
+ * Decompose a task into fresh-context workers, verify against a setpoint, and synthesize one result —
+ * assembled from existing primitives, not reimplemented (G1/G6).
+ *
+ * ⚠️ RESOURCE BOUNDS ARE bareguard's, not recurse()'s — OPEN BY DESIGN (§6, "no second guard layer"), and the
+ * one thing to know before running it. `recurse()` adds NO intrinsic total-work cap. The **Family-A default**
+ * (model-driven `spawn_child`) lets a node spawn UP TO each Loop's `HARD_ROUND_LIMIT` (100) children PER LEVEL,
+ * each recursing to `opts.maxDepth` (default 3) — so node count, and therefore TOKEN + $ SPEND, compounds
+ * multiplicatively and is **not capped by recurse itself**. (The forced paths — `mode:'fanout'`/`'partition'` —
+ * ARE bounded: a deterministic `count` + a `concurrency` cap. The uncapped path is the model-driven default.)
+ * This is real, not theoretical: a live POC (`poc/rlm-defer2-history-overflow.mjs`) showed a weak model
+ * over-decomposing into 40–117 calls on a single run. **So: running WITHOUT bareguard — or without ANY
+ * token/cost cap — CAN BURN TOKENS / $ unboundedly (up to ~100×depth nodes).** **WIRE bareguard**
+ * (`ctx.policy` via `wireGate`) for any non-trivial or untrusted run — it enforces depth/budget/call caps and
+ * the pre-wave fan-out checkpoint, turning a runaway into a clean `{incomplete}`. With no gate available, the
+ * only local brakes are `opts.maxDepth: 1` (flat — no nesting) and the provider/key's own usage limits.
+ *
+ * @param {string} task - The goal.
+ * @param {RecurseCtx} [ctx] - The runtime wiring (provider, policy, depth, …). Threaded down the tree.
+ * @param {RecurseOptions} [opts] - The policy knobs.
+ * @returns {Promise<RecurseResult>} `{ result, verdict, receipts }` on convergence; `{ incomplete, best,
+ *   receipts }` on guard exhaustion. NEVER a fabricated success (RC-9).
+ * @throws {Error} no provider supplied (on neither `ctx.provider` nor `opts.provider`).
+ */
+export function recurse(task: string, ctx?: RecurseCtx, opts?: RecurseOptions): Promise<RecurseResult>;