@tangleai/agents 0.21.1 → 0.24.1

package/src/recursive.d.ts

@@ -1,3 +1,57 @@
+/**
+ * The long-horizon entry point: a job, not a conversation.
+ *
+ * `createAgent` is a bounded tool loop — you talk to it. This is the
+ * other shape: you hand it a corpus and a question, and it authors a
+ * program over an environment, fans model calls out across the pieces,
+ * and may let any of those calls be **another agent over its own slice**
+ * — depth-capped, budget-shared, and traced at every level.
+ *
+ * Four things about recursion are load-bearing, and each one exists
+ * because the RLM paper reports the failure it prevents:
+ *
+ *  - **Depth defaults to 1 and caps at 3.** The paper runs depths 0–3
+ *    and finds most of its gain at depth 1, with depth 3 helping only on
+ *    information-dense tasks. Depth multiplies cost on every task where
+ *    it does not help, so the default is the depth that usually pays and
+ *    the cap is asserted rather than documented — a program asking for
+ *    more is clamped, and the clamp is recorded in the trajectory rather
+ *    than applied silently.
+ *  - **Budgets are shared by the whole tree, not per call.** Depth times
+ *    fan-out is multiplicative: depth 3 fanning 20 ways at each level is
+ *    8000 leaf calls. A per-call budget cannot bound that. One account is
+ *    threaded through every depth, charged by every model call, and when
+ *    it runs out the tree stops with a named reason and **leaves its
+ *    partial work in slots** — which is why Phase A came first: a
+ *    budget-stopped run is resumable because its work is durable.
+ *  - **A child cannot reach a sibling.** Each child gets an environment
+ *    scoped to a prefix of its own. Isolation is what makes one failing
+ *    branch containable instead of a corruption of the shared corpus.
+ *  - **A child's failure is a value.** A child whose program will not
+ *    compile returns `{ error, depth, slot }` to its parent, recorded and
+ *    addressable. The paper reports syntax errors propagating silently
+ *    through recursion; here the parent's map completes with a recorded
+ *    failure in the child's own result slot, exactly as a failed leaf
+ *    sub-call does.
+ *
+ * **What is not here, stated rather than implied:** guardrails for
+ * recursive LM systems are under-explored, and this package does not
+ * pretend otherwise. Three bounds exist and they are the only three —
+ * the depth cap, the shared budget and the abort signal. There is no
+ * general proof of a child's factual correctness or loop detection beyond
+ * depth. Recursive envelopes are compile/runtime checked; hosts may also
+ * opt into checked root reuse and per-call route limits.
+ */
+/** The deepest a tree may go, whatever it asks for. */
+export declare const MAX_DEPTH = 3;
+/** The conservative default; local depth measurements have not justified raising it. */
+export declare const DEFAULT_DEPTH = 1;
+/**
+ * The dimensions a tree is bounded by. The same three the agent loop
+ * uses, in the same order, because a caller who has budgeted one should
+ * not have to learn a second vocabulary for the other.
+ */
+export declare const BUDGET_DIMENSIONS: readonly ["turns", "tokens", "ms"];
 /**
  * One account, charged by every model call at every depth.
  *
@@ -6,9 +60,8 @@
  * branch spend the full budget independently, which is precisely the
  * runaway the cap exists to prevent.
  *
- * @param {{ turns?: number, tokens?: number, ms?: number,
- *   spent?: { turns?: number, tokens?: number, ms?: number } }} [budget]
- * @param {() => number} [clock]
+ * @param [budget]
+ * @param [clock]
  * **Turns are reserved, tokens are settled**, and the split is what makes
  * a concurrent fan-out bounded. A budget checked before a call and
  * charged after it can be beaten by concurrency: four sub-calls launched
@@ -19,11 +72,8 @@
  * at most `maxConcurrentSubcalls - 1` calls' worth. That is stated here
  * rather than hidden, because a caller sizing a budget needs it.
  *
- * @returns {{ reserve: () => void, settle: (usage: any, text?: string) => void,
- *   stop: () => string | null, spent: () => { turns: number, tokens: number, ms: number },
- *   remaining: () => Record<string, number | null> }}
  */
-export function createBudgetAccount(budget?: {
+export declare function createBudgetAccount(budget?: {
     turns?: number;
     tokens?: number;
     ms?: number;
@@ -51,10 +101,8 @@ export function createBudgetAccount(budget?: {
  * calls it made and the slots it wrote, at every depth. Kept as plain
  * data so a host can persist it, render it, or diff two runs.
  *
- * @returns {{ add: (entry: any) => any, entries: () => any[],
- *   summary: () => { steps: number, calls: number, slots: number, depths: number[] } }}
  */
-export function createTrajectory(): {
+export declare function createTrajectory(): {
     add: (entry: any) => any;
     entries: () => any[];
     summary: () => {
@@ -70,13 +118,15 @@ export function createTrajectory(): {
  * Returns the depth AND whether it was clamped, because a run that
  * quietly did less than it was asked to is indistinguishable from one
  * that failed to find anything — the caller has to be able to tell.
- * @param {number | undefined} requested
- * @returns {{ depth: number, clamped: boolean }}
  */
-export function resolveDepth(requested: number | undefined): {
+export declare function resolveDepth(requested: number | undefined): {
     depth: number;
     clamped: boolean;
 };
+/** The slot prefix a child at `depth` working on `index` owns. Derived,
+ * like every other address in this package, so nothing has to store a
+ * mapping from a child to its workspace. */
+export declare const childScope: (depth: any, index: any) => string;
 /**
  * The long-horizon entry point: hand it a question and an environment,
  * get back an answer and the trajectory that produced it.
@@ -86,23 +136,12 @@ export function resolveDepth(requested: number | undefined): {
  * CONVERSATION, this is for a JOB — something with a corpus, a question
  * over all of it, and no user waiting to answer a follow-up.
  *
- * @param {{ client: any, environment: any, compileQuery?: any,
- *   analyzeQuery?: any, annotateTypes?: any, reuse?: any,
- *   selectModel?: any, limits?: any, onRoute?: any,
- *   createStructuredOutput: (options: any) => { generate: Function },
- *   createProgramAuthor: (options: any) => { author: Function },
- *   createProgramRunner: (options: any) => { run: Function },
- *   createEnvironment: (options: any) => any,
- *   querySchema?: any, budget?: any, depth?: number,
- *   maxConcurrentSubcalls?: number, maxSubcalls?: number,
- *   subcallChars?: number, maxAnswerChars?: number, clock?: () => number }} options
  *   The three factories and `createEnvironment` are injected for the
  *   same reason everything heavy in this package is: it keeps this
- *   module free of a cycle with `program.js` and lets a probe wrap any
+ *   module free of a cycle with `program.ts` and lets a probe wrap any
  *   of them to count what a run actually did.
- * @returns {{ run: (question: string, hooks?: { signal?: AbortSignal }) => Promise<any> }}
  */
-export function createLongHorizonAgent(options: {
+export declare function createLongHorizonAgent(options: {
     client: any;
     environment: any;
     compileQuery?: any;
@@ -135,14 +174,3 @@ export function createLongHorizonAgent(options: {
         signal?: AbortSignal;
     }) => Promise<any>;
 };
-/** The deepest a tree may go, whatever it asks for. */
-export const MAX_DEPTH: 3;
-/** The conservative default; local depth measurements have not justified raising it. */
-export const DEFAULT_DEPTH: 1;
-/**
- * The dimensions a tree is bounded by. The same three the agent loop
- * uses, in the same order, because a caller who has budgeted one should
- * not have to learn a second vocabulary for the other.
- */
-export const BUDGET_DIMENSIONS: readonly ["turns", "tokens", "ms"];
-export function childScope(depth: any, index: any): string;