@tangleai/agents 0.21.1

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@tangleai/agents",
+  "version": "0.21.1",
+  "description": "Validated tools, bounded agents, action programs, recursive execution and guarded refinement.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./toolbox": {
+      "types": "./src/toolbox.d.ts",
+      "import": "./src/toolbox.js",
+      "default": "./src/toolbox.js"
+    },
+    "./agent": {
+      "types": "./src/agent.d.ts",
+      "import": "./src/agent.js",
+      "default": "./src/agent.js"
+    },
+    "./program": {
+      "types": "./src/program.d.ts",
+      "import": "./src/program.js",
+      "default": "./src/program.js"
+    },
+    "./recursive": {
+      "types": "./src/recursive.d.ts",
+      "import": "./src/recursive.js",
+      "default": "./src/recursive.js"
+    },
+    "./refine": {
+      "types": "./src/refine.d.ts",
+      "import": "./src/refine.js",
+      "default": "./src/refine.js"
+    },
+    "./schemas/program": {
+      "types": "./src/schemas/program.d.ts",
+      "import": "./src/schemas/program.js",
+      "default": "./src/schemas/program.js"
+    },
+    "./program-result": {
+      "types": "./src/program-result.d.ts",
+      "import": "./src/program-result.js",
+      "default": "./src/program-result.js"
+    },
+    "./program-session": {
+      "types": "./src/program-session.d.ts",
+      "import": "./src/program-session.js",
+      "default": "./src/program-session.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@jarenjs/core": "0.84.3",
+    "@jarenjs/validate": "0.84.3",
+    "@tangleai/models": "^0.21.1",
+    "@tangleai/context": "^0.21.1",
+    "@jarenjs/contract": "0.84.3"
+  },
+  "private": false,
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/tangleai.git",
+    "directory": "packages/agents"
+  }
+}

package/src/agent.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @typedef {Object} AgentHooks
+ * @property {(text: string) => void} [onDelta] - streamed reply text
+ * @property {(text: string) => void} [onReasoning] - streamed thinking
+ * @property {(call: { name: string, arguments: string }) => void} [onToolCall]
+ * @property {(step: { name: string, result: any }) => void} [onToolResult]
+ * @property {AbortSignal} [signal]
+ */
+/**
+ * @param {{ client: { complete: (request: any) => Promise<any> },
+ *   toolbox?: { toFunctionTools: () => any[], execute: (name: string, args: any) => any } | null,
+ *   system?: string, maxToolRounds?: number, maxToolResultChars?: number,
+ *   historyBudget?: number, ledger?: any,
+ *   budget?: { turns?: number, tokens?: number, ms?: number,
+ *     spent?: { turns?: number, tokens?: number, ms?: number } },
+ *   retrieval?: { memories?: { tags?: string[], where?: any, limit?: number },
+ *     skills?: { tags?: string[], where?: any, limit?: number } },
+ *   now?: () => number,
+ *   environment?: any, transcript?: { slot?: string, window?: number },
+ *   compaction?: (droppedRounds: any[][], addresses?: any[]) => string }} options
+ *   - `historyBudget` caps the request history in CHARACTERS (tokens
+ *   are provider-private; characters are deterministic). When a
+ *   request would exceed it, the middle of the conversation is
+ *   replaced by one synopsis message; the system prompt, the first
+ *   user message and the largest tail that fits always survive, and
+ *   cuts happen only at tool-round boundaries so `tool_calls`/`tool`
+ *   pairing stays wire-legal. `compaction` replaces the built-in
+ *   synopsis writer (it receives the dropped rounds, each an array of
+ *   wire messages, and — with a ledger — the address of each). The
+ *   returned transcript is always the FULL, uncompacted history.
+ *   - `ledger` (anything with `putSlot`/`getSlot`/`readSlot`, normally
+ *   `createLedger()`) makes compaction RECOVERABLE: each dropped round
+ *   is archived to a content-addressed slot before the synopsis is
+ *   written, every synopsis line carries its address, and a `recall`
+ *   tool is registered so the model can fetch one back. Nothing leaves
+ *   the request without a copy that can be named. With no ledger the
+ *   original lossy path runs unchanged. A ledger also supplies the
+ *   active goal composed into every request, and the memories and
+ *   skills `retrieval` asks for.
+ *   - `budget` is a hard stop, not a warning: `turns` (one turn is one
+ *   MODEL CALL — the unit that costs money and the unit a resumed
+ *   session keeps counting), `tokens` and `ms` each end the run with a
+ *   named `stopReason` (`budget-turns`, `budget-tokens`, `budget-ms`)
+ *   and a message saying what remains. Each is optional; `spent` seeds
+ *   the counters so a budget survives a reload. The `ms` clock starts at
+ *   the first model call and is wall-clock from there.
+ *   - `retrieval` composes ledger memories and skills into the system
+ *   prompt of every request, with the ledger's own `recall` query shape.
+ *   Absent, nothing is retrieved — the goal is unconditional, but what
+ *   else is worth carrying is the host's call.
+ *   - `now` returns milliseconds (`Date.now` by default), injected so a
+ *   time budget is testable.
+ *   - `environment` (from `createEnvironment`) registers the corpus
+ *   operations as tools — `env_digest`, `env_peek`, `env_grep`,
+ *   `env_chunk`, `env_stat`, `env_read` — beside the host's, skipping any
+ *   name the host already registered. Content never enters a request
+ *   unasked: every one of them answers with metadata and addresses
+ *   except `env_read`, which makes the model state a character budget.
+ *   - `transcript` (needs `environment`) makes the CONVERSATION one of
+ *   those slots: it is written whole before every call and the request
+ *   keeps `window` round units plus the address of the rest. That is the
+ *   alternative to `historyBudget` rather than a tuning of it — there is
+ *   no budget to exceed when the history is addressed instead of resent.
+ *   Both together is legal and redundant; neither changes the other's
+ *   behaviour.
+ * @returns {{ send: (history: any[], hooks?: AgentHooks) => Promise<{
+ *   message: any, messages: any[], steps: any[], stopReason: string }>,
+ *   resume: (history?: any[], hooks?: AgentHooks) => Promise<{
+ *   message: any, messages: any[], steps: any[], stopReason: string }>,
+ *   spend: () => { turns: number, tokens: number, ms: number } }}
+ */
+export function createAgent(options: {
+    client: {
+        complete: (request: any) => Promise<any>;
+    };
+    toolbox?: {
+        toFunctionTools: () => any[];
+        execute: (name: string, args: any) => any;
+    } | null;
+    system?: string;
+    maxToolRounds?: number;
+    maxToolResultChars?: number;
+    historyBudget?: number;
+    ledger?: any;
+    budget?: {
+        turns?: number;
+        tokens?: number;
+        ms?: number;
+        spent?: {
+            turns?: number;
+            tokens?: number;
+            ms?: number;
+        };
+    };
+    retrieval?: {
+        memories?: {
+            tags?: string[];
+            where?: any;
+            limit?: number;
+        };
+        skills?: {
+            tags?: string[];
+            where?: any;
+            limit?: number;
+        };
+    };
+    now?: () => number;
+    environment?: any;
+    transcript?: {
+        slot?: string;
+        window?: number;
+    };
+    compaction?: (droppedRounds: any[][], addresses?: any[]) => string;
+}): {
+    send: (history: any[], hooks?: AgentHooks) => Promise<{
+        message: any;
+        messages: any[];
+        steps: any[];
+        stopReason: string;
+    }>;
+    resume: (history?: any[], hooks?: AgentHooks) => Promise<{
+        message: any;
+        messages: any[];
+        steps: any[];
+        stopReason: string;
+    }>;
+    spend: () => {
+        turns: number;
+        tokens: number;
+        ms: number;
+    };
+};
+/**
+ * The conversation as text a `grep` can answer from: one header line per
+ * message, then its content. Line-oriented on purpose — `grep` reports
+ * the line that matched, so a tool result written as one JSON line comes
+ * back as one legible hit with its address beside it.
+ * @param {any[]} messages
+ * @returns {string}
+ */
+export function transcriptText(messages: any[]): string;
+export type AgentHooks = {
+    /**
+     * - streamed reply text
+     */
+    onDelta?: (text: string) => void;
+    /**
+     * - streamed thinking
+     */
+    onReasoning?: (text: string) => void;
+    onToolCall?: (call: {
+        name: string;
+        arguments: string;
+    }) => void;
+    onToolResult?: (step: {
+        name: string;
+        result: any;
+    }) => void;
+    signal?: AbortSignal;
+};