@tangleai/agents 0.21.1 → 0.25.0

package/src/program-shape.js

@@ -1,53 +1,60 @@
-//@ts-check
 /** Recursive answers carry the same envelope as map elements. Query engines stay injected. */
 export const RECURSIVE_ITEM_SCHEMA = {
-  type: 'object', properties: { slot: { type: 'string' }, value: {} }, required: ['slot', 'value'],
+    type: 'object', properties: { slot: { type: 'string' }, value: {} }, required: ['slot', 'value'],
 };
-
 /** Query singleton normalization: empty sequence, one item, or several items.
- * @param {any} value */
+ * @param value */
 export function recursiveItems(value) {
-  const items = value === null ? [] : Array.isArray(value) ? value : [value];
-  return items.every((item) => item !== null && typeof item === 'object' && !Array.isArray(item)
-    && typeof item.slot === 'string' && Object.hasOwn(item, 'value')) ? items : null;
+    const items = value === null ? [] : Array.isArray(value) ? value : [value];
+    return items.every((item) => item !== null && typeof item === 'object' && !Array.isArray(item)
+        && typeof item.slot === 'string' && Object.hasOwn(item, 'value')) ? items : null;
 }
-
 /** Conservatively prove a declared item/sequence schema. Unknown schema keywords
  * never manufacture required properties. Runtime validation enforces the full declaration.
- * @param {any} schema @param {boolean} [item] @returns {boolean} */
+ * @param schema @param [item] @returns */
 export function recursiveSchema(schema, item = false) {
-  if (!schema || typeof schema !== 'object') return false;
-  if (schema.type === 'array') return !item && recursiveSchema(schema.items, true);
-  if (schema.anyOf) return schema.anyOf.every((branch) => recursiveSchema(branch, item));
-  return schema.type === 'object' && schema.required?.includes('slot')
-    && schema.required?.includes('value') && schema.properties?.slot?.type === 'string';
+    if (!schema || typeof schema !== 'object')
+        return false;
+    if (schema.type === 'array')
+        return !item && recursiveSchema(schema.items, true);
+    if (schema.anyOf)
+        return schema.anyOf.every((branch) => recursiveSchema(branch, item));
+    return schema.type === 'object' && schema.required?.includes('slot')
+        && schema.required?.includes('value') && schema.properties?.slot?.type === 'string';
 }
-
 /** Three-valued structural proof over the existing annotated query AST.
- * @param {any} node @param {boolean} [item] @returns {'compatible'|'incompatible'|'unknown'} */
+ * @param node @param [item] @returns */
 export function recursiveShape(node, item = false) {
-  if (!node) return 'unknown';
-  if (node.kind === 'let') return recursiveShape(node.ret, item);
-  if (node.kind === 'flwor') {
-    const output = recursiveShape(node.ret, node.fold ? item : true);
-    if (!node.fold) return output;
-    const initial = recursiveShape(node.fold.expr, item);
-    return initial === output ? output : 'unknown';
-  }
-  if (node.kind === 'array') {
-    if (item) return 'incompatible';
-    const shapes = node.elements.map((element) => recursiveShape(element, true));
-    return shapes.includes('incompatible') ? 'incompatible' : shapes.includes('unknown') ? 'unknown' : 'compatible';
-  }
-  if (node.kind === 'literal') return (item && (Array.isArray(node.value) || node.value === null))
-    || recursiveItems(node.value) === null ? 'incompatible' : 'compatible';
-  if (node.kind === 'object') {
-    const slot = node.entries.find((entry) => entry.name === 'slot')?.expr;
-    const value = node.entries.find((entry) => entry.name === 'value');
-    if (!slot || !value) return 'incompatible';
-    if (slot.type?.type === 'string' && slot.type.optional === false) return 'compatible';
-    return !slot.type || slot.type.type === 'unknown' ? 'unknown' : 'incompatible';
-  }
-  if (node.type?.type && !['unknown', 'object', 'array'].includes(node.type.type)) return 'incompatible';
-  return 'unknown';
+    if (!node)
+        return 'unknown';
+    if (node.kind === 'let')
+        return recursiveShape(node.ret, item);
+    if (node.kind === 'flwor') {
+        const output = recursiveShape(node.ret, node.fold ? item : true);
+        if (!node.fold)
+            return output;
+        const initial = recursiveShape(node.fold.expr, item);
+        return initial === output ? output : 'unknown';
+    }
+    if (node.kind === 'array') {
+        if (item)
+            return 'incompatible';
+        const shapes = node.elements.map((element) => recursiveShape(element, true));
+        return shapes.includes('incompatible') ? 'incompatible' : shapes.includes('unknown') ? 'unknown' : 'compatible';
+    }
+    if (node.kind === 'literal')
+        return (item && (Array.isArray(node.value) || node.value === null))
+            || recursiveItems(node.value) === null ? 'incompatible' : 'compatible';
+    if (node.kind === 'object') {
+        const slot = node.entries.find((entry) => entry.name === 'slot')?.expr;
+        const value = node.entries.find((entry) => entry.name === 'value');
+        if (!slot || !value)
+            return 'incompatible';
+        if (slot.type?.type === 'string' && slot.type.optional === false)
+            return 'compatible';
+        return !slot.type || slot.type.type === 'unknown' ? 'unknown' : 'incompatible';
+    }
+    if (node.type?.type && !['unknown', 'object', 'array'].includes(node.type.type))
+        return 'incompatible';
+    return 'unknown';
 }

package/src/program.d.ts

@@ -1,3 +1,92 @@
+/**
+ * The action language: compile it, then run it.
+ *
+ * HORIZON_06 put the corpus outside the context and gave the root a
+ * digest instead. That fixed what the model *sees*; this file fixes what
+ * it can *do*. The model authors a small program naming slots and
+ * operations, the program is compiled before anything runs, and the
+ * harness executes it — fanning model sub-calls out over the pieces in
+ * parallel and writing every result back to a slot.
+ *
+ * Why this closes the pairwise question. A relation over every record
+ * needs every record, and no summariser and no `recall` can put forty
+ * rounds into a budget they were cut to fit. A program does not have to:
+ * `map` visits all forty pieces, each sub-call reads one of them, and
+ * `reduce` computes over the forty small results. The root never sees
+ * any of it — it sees a plan going out and one slot's metadata coming
+ * back — so the request stays the same size whether the corpus is ten
+ * kilobytes or ten megabytes.
+ *
+ * Four rules hold without exception:
+ *
+ *  - **A program that does not compile never runs.** `run` compiles
+ *    first and returns the compile errors; no step has executed and no
+ *    slot has been written when it does. The errors are coded and
+ *    `docPath`'d into the program document, which is the error class
+ *    this package's field notes say small models actually repair.
+ *  - **`map` is the only step that calls a model** — so `maxSubcalls`
+ *    and `maxConcurrentSubcalls` are the whole cost model, and one place
+ *    threads the `AbortSignal`.
+ *  - **A sub-call failure is a result, not a crash.** It lands as
+ *    `{ error }` in its own result slot and the map completes, exactly
+ *    as the toolbox never throws for content-level problems. A map whose
+ *    sub-calls all failed is a finished map with forty recorded errors.
+ *  - **Nothing bulk comes back.** Every step reports metadata; the one
+ *    place content returns to the caller is the final `answer` step, and
+ *    it is capped.
+ *
+ * **The decision this file exists to record** (asked once per reader, so
+ * it is answered here): why not register an async `$llm` operator into
+ * the JSLT registry and let a stylesheet call a model inline? Because
+ * `@jarenjs/core`'s operators are pure synchronous functions and the
+ * query/JSLT evaluators are synchronous by construction. Making them
+ * async to accommodate one caller would change an engine every other
+ * package in the suite depends on — a `queryJson` that returned a
+ * promise would break `@jarenjs/db`'s pushdown, `@jarenjs/md`'s
+ * directives and `@jarenjs/app`'s state derivation, all to save this
+ * package a `map` step. So the division is fixed: **the program selects
+ * (pure, synchronous, compiled) and the harness awaits (async, bounded,
+ * cancellable).** `map` is the seam between the two halves, and it is
+ * the only one.
+ */
+import { CodedError } from '@jarenjs/core/errors';
+export { readProgramAnswer } from './program-result.ts';
+/**
+ * A program that will not compile.
+ *
+ * Thrown, unlike `refine.ts`'s AI01xx records, because this is a
+ * COMPILER and the suite's compilers throw coded errors with a
+ * `docPath` — which is what makes the documented two-line gate adapter
+ * (`try { compile(doc) } catch (e) { … }`) work here exactly as it does
+ * for a query, a stylesheet or a flow machine. {@link programGate} is
+ * that adapter, so a caller never writes it.
+ *
+ * The codes:
+ *
+ *   AI0200 — the document is not a program
+ *   AI0201 — a step reads a name nothing produced
+ *   AI0202 — a name is bound twice
+ *   AI0203 — the last step is not `answer`, or there is more than one
+ *   AI0204 — a `reduce` reads something that is not a `map`
+ *   AI0205 — the program is longer than its cap
+ *   AI0206 — a step needs the query seam and none is wired
+ *   AI0207 — a step reading ONE slot was given a family of pieces
+ *   AI0208 — a recursive result has an incompatible or unknown envelope
+ *   AI0209 — a runtime result violates its declared recursive shape
+ *
+ * A query that does not compile keeps the QUERY engine's own code
+ * (`JQ0002`, …) and its pointer is rebased onto the program document,
+ * so the model is told which step and which member — the same posture
+ * `refine.ts` takes with the patch engine's codes.
+ */
+export declare class ProgramError extends CodedError {
+    /**
+     * @param code - 'AI0200' … 'AI0209'
+     * @param reason - the bare reason
+     * @param [docPath] - JSON Pointer into the program document
+     */
+    constructor(code: string, reason: string, docPath?: string);
+}
 /**
  * Compile a program document.
  *
@@ -7,9 +96,8 @@
  * model, so a compile is cheap enough to run on every authored candidate
  * — which is exactly what makes it usable as a decoding gate.
  *
- * @param {any} doc - the program document
- * @param {{ compileQuery?: ((document: any) => (data: any) => any) | null,
- *   known?: Iterable<string>, recursive?: boolean, analyzeQuery?: any, annotateTypes?: any }} [options]
+ * @param doc - the program document
+ * @param [options]
  *   - `compileQuery` is the D3 seam. Absent, a program using `select` or
  *     `reduce` is refused with AI0206 rather than half-compiled.
  *   - `known` is what the environment already holds. Given, a `from`
@@ -18,11 +106,10 @@
  *     reason a compile gate catches what a schema cannot. Absent, only
  *     bindings are resolved: nothing else can be checked without an
  *     environment, and inventing an error would be worse than saying so.
- * @returns {{ steps: any[], answer: { from: string, chars: number },
- *   bindings: string[], chars: number }}
+ * @returns
  * @throws {ProgramError}
  */
-export function compileProgram(doc: any, options?: {
+export declare function compileProgram(doc: any, options?: {
     compileQuery?: ((document: any) => (data: any) => any) | null;
     known?: Iterable<string>;
     recursive?: boolean;
@@ -43,10 +130,9 @@ export function compileProgram(doc: any, options?: {
  * One implementation of "does this program compile", used by the
  * authoring path and by the runner, so a program that authored cleanly
  * cannot fail differently when it runs.
- * @param {{ compileQuery?: any, known?: Iterable<string>, recursive?: boolean, analyzeQuery?: any, annotateTypes?: any }} [options]
- * @returns {(doc: any) => true | { valid: false, errors: any[] }}
+ * @param [options]
  */
-export function programGate(options?: {
+export declare function programGate(options?: {
     compileQuery?: any;
     known?: Iterable<string>;
     recursive?: boolean;
@@ -59,17 +145,6 @@ export function programGate(options?: {
 /**
  * Create a runner over an environment.
  *
- * @param {{ environment: any,
- *   client?: { complete: (request: any) => Promise<any> },
- *   compileQuery?: any,
- *   recursive?: boolean, analyzeQuery?: any, annotateTypes?: any,
- *   selectModel?: any, limits?: any, onRoute?: any, depth?: number,
- *   model?: string,
- *   maxSubcalls?: number, maxConcurrentSubcalls?: number,
- *   subcallChars?: number, maxReduceChars?: number,
- *   sequential?: boolean,
- *   subcall?: (name: string, prompt: string, signal?: AbortSignal, index?: number) => Promise<any>,
- *   account?: { reserve: Function, settle: Function, stop: () => string | null } }} options
  *   - `client` is only needed by `map`; a program without one is a
  *     perfectly good program (chunk / grep / select / stat / answer are
  *     model-free), and running a `map` without a client is a stated
@@ -86,9 +161,8 @@ export function programGate(options?: {
  *   - `account` is a budget shared with everything else in the run,
  *     including other depths. Checked before each sub-call and charged
  *     by it, so a tree cannot outspend the sum of its branches.
- * @returns {{ run: (doc: any, hooks?: { signal?: AbortSignal }) => Promise<ProgramRunResult> }}
  */
-export function createProgramRunner(options: {
+export declare function createProgramRunner(options: {
     environment: any;
     client?: {
         complete: (request: any) => Promise<any>;
@@ -118,6 +192,48 @@ export function createProgramRunner(options: {
         signal?: AbortSignal;
     }) => Promise<ProgramRunResult>;
 };
+/** The example, so a test can compile it. Exported for exactly that:
+ * the prompt's correctness is a property worth a gate. */
+export declare const PROGRAM_EXAMPLE: {
+    steps: ({
+        op: string;
+        from: string;
+        as: string;
+        strategy: string;
+        size: number;
+        prompt?: undefined;
+        query?: undefined;
+    } | {
+        op: string;
+        from: string;
+        as: string;
+        prompt: string;
+        strategy?: undefined;
+        size?: undefined;
+        query?: undefined;
+    } | {
+        op: string;
+        from: string;
+        as: string;
+        query: {
+            $for: {
+                r: string;
+            };
+            $return: string;
+        };
+        strategy?: undefined;
+        size?: undefined;
+        prompt?: undefined;
+    } | {
+        op: string;
+        from: string;
+        as?: undefined;
+        strategy?: undefined;
+        size?: undefined;
+        prompt?: undefined;
+        query?: undefined;
+    })[];
+};
 /**
  * Author a program with a model, gated on the compiler.
  *
@@ -127,20 +243,14 @@ export function createProgramRunner(options: {
  * decoding, the compile gate constrains meaning, and a rejected
  * candidate goes back with its code and its pointer.
  *
- * @param {{ client: any, environment: any, compileQuery?: any,
- *   recursive?: boolean, analyzeQuery?: any, annotateTypes?: any,
- *   selectModel?: any, limits?: any, onRoute?: any, depth?: number, account?: any,
- *   createStructuredOutput: (options: any) => { generate: Function },
- *   querySchema?: any, maxRepairs?: number, system?: string }} options
  *   - `createStructuredOutput` is injected rather than imported so a
  *     caller can wrap it (a probe counting attempts, a cache); the
  *     package's own is the obvious argument.
  *   - `querySchema` is the published query grammar. Given, `select` and
  *     `reduce` are shape-constrained too and it is registered as a
  *     `$ref`; absent, the compile gate carries it alone (D3).
- * @returns {{ author: (question: string, hooks?: { signal?: AbortSignal }) => Promise<any> }}
  */
-export function createProgramAuthor(options: {
+export declare function createProgramAuthor(options: {
     client: any;
     environment: any;
     compileQuery?: any;
@@ -163,82 +273,4 @@ export function createProgramAuthor(options: {
         signal?: AbortSignal;
     }) => Promise<any>;
 };
-export { readProgramAnswer } from "./program-result.js";
-/**
- * A program that will not compile.
- *
- * Thrown, unlike `refine.js`'s AI01xx records, because this is a
- * COMPILER and the suite's compilers throw coded errors with a
- * `docPath` — which is what makes the documented two-line gate adapter
- * (`try { compile(doc) } catch (e) { … }`) work here exactly as it does
- * for a query, a stylesheet or a flow machine. {@link programGate} is
- * that adapter, so a caller never writes it.
- *
- * The codes:
- *
- *   AI0200 — the document is not a program
- *   AI0201 — a step reads a name nothing produced
- *   AI0202 — a name is bound twice
- *   AI0203 — the last step is not `answer`, or there is more than one
- *   AI0204 — a `reduce` reads something that is not a `map`
- *   AI0205 — the program is longer than its cap
- *   AI0206 — a step needs the query seam and none is wired
- *   AI0207 — a step reading ONE slot was given a family of pieces
- *   AI0208 — a recursive result has an incompatible or unknown envelope
- *   AI0209 — a runtime result violates its declared recursive shape
- *
- * A query that does not compile keeps the QUERY engine's own code
- * (`JQ0002`, …) and its pointer is rebased onto the program document,
- * so the model is told which step and which member — the same posture
- * `refine.js` takes with the patch engine's codes.
- */
-export class ProgramError extends CodedError {
-    /**
-     * @param {string} code - 'AI0200' … 'AI0209'
-     * @param {string} reason - the bare reason
-     * @param {string} [docPath] - JSON Pointer into the program document
-     */
-    constructor(code: string, reason: string, docPath?: string);
-}
-export namespace PROGRAM_EXAMPLE {
-    let steps: ({
-        op: string;
-        from: string;
-        as: string;
-        strategy: string;
-        size: number;
-        prompt?: undefined;
-        query?: undefined;
-    } | {
-        op: string;
-        from: string;
-        as: string;
-        prompt: string;
-        strategy?: undefined;
-        size?: undefined;
-        query?: undefined;
-    } | {
-        op: string;
-        from: string;
-        as: string;
-        query: {
-            $for: {
-                r: string;
-            };
-            $return: string;
-        };
-        strategy?: undefined;
-        size?: undefined;
-        prompt?: undefined;
-    } | {
-        op: string;
-        from: string;
-        as?: undefined;
-        strategy?: undefined;
-        size?: undefined;
-        prompt?: undefined;
-        query?: undefined;
-    })[];
-}
-export type ProgramRunResult = import("./program-result.js").ProgramRunResult;
-import { CodedError } from '@jarenjs/core/errors';
+export type ProgramRunResult = import('./program-result.ts').ProgramRunResult;