@animalabs/agent-framework 0.23.2 → 0.24.0

package/dist/src/code-execution/isolate/output.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A script's output, bounded once, in the parent: every return, whether a
+ * yield, a wait or the ending's, gives what the script wrote since the
+ * previous one, its first and last characters within the bound and a count of
+ * what was dropped between. A long stretch keeps its start, since that's
+ * often where its trouble began, such as the first error before a cascade.
+ *
+ * The child can't know when the parent returns, since its frames reach it only
+ * while its guest is idle, so the bound sits in the parent: the child holds
+ * one bounded batch of what the guest writes and flushes it, and the parent
+ * keeps the head and tail of each return's stretch, starting both afresh at
+ * each return. Memory is bounded by construction on both sides; the price is
+ * that a printing loop's whole output crosses the pipe, in batches.
+ */
+export interface OutputBounds {
+    /** Characters kept from the start of each return's stretch. */
+    headChars: number;
+    /** Characters kept from its end. */
+    tailChars: number;
+}
+export declare const DEFAULT_OUTPUT_BOUNDS: OutputBounds;
+/** The most one output frame carries, so a single large write is sent in pieces. */
+export declare const MAX_BATCH_CHARS: number;
+/** The child's side: what the guest wrote since the last flush, at most a batch of it at a time. */
+export declare class OutputBatch {
+    private pending;
+    private size;
+    /** Characters waiting to be flushed. */
+    get unflushed(): number;
+    /** True once the batch is full, so the caller flushes now. */
+    write(text: string): boolean;
+    /** The waiting text in pieces of at most a batch each, emptying it; empty when nothing waits. */
+    flush(): string[];
+}
+/** A return's stretch of output: its head and tail, and the count dropped between them. */
+export interface OutputWindow {
+    head: string;
+    tail: string;
+    dropped: number;
+}
+/**
+ * The stretch as the model sees it: the head, a line naming what was dropped
+ * if anything was, and the tail. Past `max`, its start and its end are cut
+ * alike to fit it, each taking the room the other doesn't need, and the count
+ * takes in what they gave up, so a return held to its agent's inline cap
+ * still shows both ends. A `max` that leaves no room for that line gets the
+ * line alone, which passes it.
+ */
+export declare function renderOutput(w: OutputWindow, max?: number): string;
+/** The parent's side: the head and tail of what arrived since the last return, and the count dropped between. */
+export declare class WindowOutput {
+    private readonly bounds;
+    private head;
+    private tail;
+    private dropped;
+    constructor(bounds: OutputBounds);
+    /** Add text the child flushed. */
+    apply(text: string): void;
+    /** Characters dropped from the stretch so far. */
+    get droppedChars(): number;
+    /** The stretch as it stands. */
+    window(): OutputWindow;
+    /** The stretch as the model sees it, whole (renderOutput). */
+    render(): string;
+    /** The stretch, and a fresh one from here. */
+    take(): OutputWindow;
+}
+//# sourceMappingURL=output.d.ts.map

package/dist/src/code-execution/isolate/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../../src/code-execution/isolate/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,qBAAqB,EAAE,YAAqD,CAAC;AAE1F,oFAAoF;AACpF,eAAO,MAAM,eAAe,QAAY,CAAC;AASzC,oGAAoG;AACpG,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,IAAI,CAAK;IAEjB,wCAAwC;IACxC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,8DAA8D;IAC9D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK3B;IAED,iGAAiG;IACjG,KAAK,IAAI,MAAM,EAAE,CAahB;CACF;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,SAAW,GAAG,MAAM,CAgBpE;AAED,iHAAiH;AACjH,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,OAAO,CAAK;IAEpB,YAA6B,MAAM,EAAE,YAAY,EAAI;IAErD,kCAAkC;IAClC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqBxB;IAED,kDAAkD;IAClD,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,gCAAgC;IAChC,MAAM,IAAI,YAAY,CAErB;IAED,8DAA8D;IAC9D,MAAM,IAAI,MAAM,CAEf;IAED,8CAA8C;IAC9C,IAAI,IAAI,YAAY,CAMnB;CACF"}

package/dist/src/code-execution/isolate/output.js

@@ -0,0 +1,143 @@
+/**
+ * A script's output, bounded once, in the parent: every return, whether a
+ * yield, a wait or the ending's, gives what the script wrote since the
+ * previous one, its first and last characters within the bound and a count of
+ * what was dropped between. A long stretch keeps its start, since that's
+ * often where its trouble began, such as the first error before a cascade.
+ *
+ * The child can't know when the parent returns, since its frames reach it only
+ * while its guest is idle, so the bound sits in the parent: the child holds
+ * one bounded batch of what the guest writes and flushes it, and the parent
+ * keeps the head and tail of each return's stretch, starting both afresh at
+ * each return. Memory is bounded by construction on both sides; the price is
+ * that a printing loop's whole output crosses the pipe, in batches.
+ */
+export const DEFAULT_OUTPUT_BOUNDS = { headChars: 8_000, tailChars: 8_000 };
+/** The most one output frame carries, so a single large write is sent in pieces. */
+export const MAX_BATCH_CHARS = 64 * 1024;
+/** Where to cut `text` near `at` without parting a surrogate pair: one earlier if `at` falls inside one. */
+function safeCut(text, at) {
+    if (at <= 0 || at >= text.length)
+        return Math.max(0, Math.min(at, text.length));
+    const before = text.charCodeAt(at - 1);
+    return before >= 0xd800 && before <= 0xdbff ? at - 1 : at;
+}
+/** The child's side: what the guest wrote since the last flush, at most a batch of it at a time. */
+export class OutputBatch {
+    pending = [];
+    size = 0;
+    /** Characters waiting to be flushed. */
+    get unflushed() {
+        return this.size;
+    }
+    /** True once the batch is full, so the caller flushes now. */
+    write(text) {
+        if (text.length === 0)
+            return this.size >= MAX_BATCH_CHARS;
+        this.pending.push(text);
+        this.size += text.length;
+        return this.size >= MAX_BATCH_CHARS;
+    }
+    /** The waiting text in pieces of at most a batch each, emptying it; empty when nothing waits. */
+    flush() {
+        if (this.size === 0)
+            return [];
+        let text = this.pending.join('');
+        this.pending = [];
+        this.size = 0;
+        const pieces = [];
+        while (text.length > MAX_BATCH_CHARS) {
+            const cut = safeCut(text, MAX_BATCH_CHARS);
+            pieces.push(text.slice(0, cut));
+            text = text.slice(cut);
+        }
+        if (text.length > 0)
+            pieces.push(text);
+        return pieces;
+    }
+}
+/** The line naming what was dropped, at its longest, as renderOutput puts it between the head and the tail. */
+const DROPPED_LINE_CHARS = `\n[… ${Number.MAX_SAFE_INTEGER} characters of output dropped here …]\n`.length;
+/**
+ * The stretch as the model sees it: the head, a line naming what was dropped
+ * if anything was, and the tail. Past `max`, its start and its end are cut
+ * alike to fit it, each taking the room the other doesn't need, and the count
+ * takes in what they gave up, so a return held to its agent's inline cap
+ * still shows both ends. A `max` that leaves no room for that line gets the
+ * line alone, which passes it.
+ */
+export function renderOutput(w, max = Infinity) {
+    const whole = w.dropped === 0 ? w.head + w.tail : `${w.head}\n[… ${w.dropped} characters of output dropped here …]\n${w.tail}`;
+    if (whole.length <= max)
+        return whole;
+    const room = Math.max(0, Math.floor(max) - DROPPED_LINE_CHARS);
+    // With nothing dropped yet, the head and the tail are one stretch, whose end
+    // lies in the head while the tail is short or empty: it's cut as one.
+    const [first, last] = w.dropped === 0 ? [whole, whole] : [w.head, w.tail];
+    const lastKeep = Math.min(last.length, Math.max(Math.floor(room / 2), room - first.length));
+    const head = first.slice(0, safeCut(first, Math.min(first.length, room - lastKeep)));
+    // Kept from the end, never starting on a pair's second half.
+    let from = last.length - lastKeep;
+    const at = last.charCodeAt(from);
+    if (from > 0 && at >= 0xdc00 && at <= 0xdfff)
+        from += 1;
+    const tail = last.slice(from);
+    const dropped = w.dropped === 0 ? whole.length - head.length - tail.length : w.dropped + (first.length - head.length) + from;
+    return `${head}\n[… ${dropped} characters of output dropped here …]\n${tail}`;
+}
+/** The parent's side: the head and tail of what arrived since the last return, and the count dropped between. */
+export class WindowOutput {
+    bounds;
+    head = '';
+    tail = '';
+    dropped = 0;
+    constructor(bounds) {
+        this.bounds = bounds;
+    }
+    /** Add text the child flushed. */
+    apply(text) {
+        let rest = text;
+        if (this.tail.length === 0 && this.dropped === 0) {
+            const room = this.bounds.headChars - this.head.length;
+            if (room > 0) {
+                const cut = safeCut(rest, room);
+                this.head += rest.slice(0, cut);
+                rest = rest.slice(cut);
+                if (rest.length === 0)
+                    return;
+            }
+        }
+        this.tail += rest;
+        const over = this.tail.length - this.bounds.tailChars;
+        if (over > 0) {
+            // Drop from the front, never splitting a pair: the cut moves later by one if it would.
+            let cut = over;
+            const at = this.tail.charCodeAt(cut - 1);
+            if (at >= 0xd800 && at <= 0xdbff)
+                cut += 1;
+            this.dropped += cut;
+            this.tail = this.tail.slice(cut);
+        }
+    }
+    /** Characters dropped from the stretch so far. */
+    get droppedChars() {
+        return this.dropped;
+    }
+    /** The stretch as it stands. */
+    window() {
+        return { head: this.head, tail: this.tail, dropped: this.dropped };
+    }
+    /** The stretch as the model sees it, whole (renderOutput). */
+    render() {
+        return renderOutput(this.window());
+    }
+    /** The stretch, and a fresh one from here. */
+    take() {
+        const window = this.window();
+        this.head = '';
+        this.tail = '';
+        this.dropped = 0;
+        return window;
+    }
+}
+//# sourceMappingURL=output.js.map

package/dist/src/code-execution/isolate/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../../src/code-execution/isolate/output.ts"],"names":[],"mappings":"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"}

package/dist/src/code-execution/isolate/prelude.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The guest's prelude: JavaScript the engine evaluates before a script, which
+ * builds what a script meets from the binding's two globals, `__host(name,
+ * argsJson)` and `__output(stream, text)`:
+ *
+ * - `tools[name](args)`, each tool by its exact name, answering one result
+ *   shape, `{ content, structuredContent, isError }`. A refusal before
+ *   dispatch rejects with an Error carrying the refusal's fields. Reading a
+ *   name that isn't a tool throws at once, naming the close matches.
+ *   At most MAX_CALLS_IN_FLIGHT are out at once, and one past them waits
+ *   here, in the script's own memory, until one is answered.
+ * - `ALL_TOOLS`, each tool's name, description and input schema.
+ * - `text(value)` and `console.log/info/warn/error/debug(...)`, which write
+ *   the script's output: a string as it is, anything else as JSON.
+ * - `wake_agent(payload)`, which asks the host to wake the agent.
+ * - `__run(src)`, which runs a script as the body of an async function, so it
+ *   may `await` at its top level and `return` a value.
+ *
+ * Nothing here guards a boundary: the guest's whole world is this instance,
+ * and every call it makes is checked by the host. Built-ins aren't frozen, so a
+ * script that patches one breaks only itself: its calls and its ending are
+ * recorded outside the guest.
+ *
+ * Adapted from pi-codemode's guest prelude (`@earendil-works/pi-codemode`
+ * 1.3.0, `dist/runtime/prelude-source.js`): the tools proxy and its
+ * close-match error, the output helpers and the error formatting. Its licence,
+ * the LICENSE at the root of github.com/earendil-works/pi, which the package's
+ * `license: "MIT"` refers to:
+ *
+ * MIT License. Copyright (c) 2025 Mario Zechner. Permission is hereby granted,
+ * free of charge, to any person obtaining a copy of this software and
+ * associated documentation files (the "Software"), to deal in the Software
+ * without restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions: The above copyright notice and this
+ * permission notice shall be included in all copies or substantial portions
+ * of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ * KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+ * EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+/** The host call name `wake_agent()` uses. Parentheses can't be in a tool's name, so it never names a tool. */
+export declare const WAKE_CALL_NAME = "(wake_agent)";
+/**
+ * How many lines QuickJS's async function constructor puts before a script's
+ * first line, and the filename it gives the script's code: a script's frames
+ * read `<input>:N:C`, with its own line N less this.
+ */
+export declare const SCRIPT_LINE_OFFSET = 2;
+/**
+ * A frame of the script's own code, as QuickJS writes one in a stack: "    at
+ * NAME (PLACE)", or "    at PLACE" for a syntax error, its PLACE at the end
+ * and the script's, `<input>:LINE:COLUMN`, its LINE of at most ten digits, as
+ * QuickJS writes a line (a 32-bit integer). A NAME may hold any character but
+ * a line feed, which the stack's lines are split at, so `[^]` rather than
+ * `.`, which stops at a carriage return and U+2028 and U+2029 too. The
+ * guest's copy of the rule (errorText) is given these two patterns as they
+ * are.
+ */
+export declare const SCRIPT_FRAME: RegExp;
+/** A script frame's place, at its end: its line is renumbered as the agent wrote it. */
+export declare const SCRIPT_PLACE: RegExp;
+/**
+ * A failure's frames as the agent reads them, one per line: the script's own,
+ * numbered as the agent wrote its lines, leaving out the prelude's frames and
+ * the engine's native ones. QuickJS gives an Error's stack as its frames
+ * alone, and nothing here adds the failure's name and message to it, so the
+ * script's frames are the lines shaped as its frames are (SCRIPT_FRAME): a
+ * line of a stack the script or its Error.prepareStackTrace set is one if it
+ * is shaped so, and isn't otherwise. A function's name holding a line feed
+ * splits its frame in two, and each half is read on its own, so the frame is
+ * lost unless a half is itself shaped as a frame. Code the script compiles at
+ * run time is named `<input>` as the script is, so the rule takes its frames
+ * for the script's: an eval's read at its string's lines less two, and a
+ * Function constructor's at its body's own lines, plus one for each line
+ * break in its parameters, since the constructor puts its parameters and two
+ * lines before the body, as the prelude's AsyncFunction does. The prelude's
+ * errorText applies this rule in the guest, to an Error the script logs,
+ * leading with the name and message, while a string the script logs, an
+ * Error's `stack` among them, shows as QuickJS or the script wrote it; the
+ * child applies the rule here to every failure's stack. The two are one rule:
+ * the guest is given the pair of patterns as they are, and the walk here
+ * reads SCRIPT_FRAME as SCRIPT_FRAME_IN_STACK and renumbers a place itself,
+ * as SCRIPT_PLACE says, so a change to one has to be made to all three, and
+ * tests hold them together.
+ */
+export declare function scriptFrames(stack: string, max?: number): string;
+/** One tool as the prelude lists it in ALL_TOOLS. */
+export interface PreludeTool {
+    name: string;
+    description: string;
+    /** The tool's input schema, as the agent's own tool list gives it. */
+    inputSchema?: unknown;
+}
+/**
+ * The prelude, for these tools. The child, not the prelude, refuses a wake
+ * past the script's cap (child.ts). The tool list goes in as
+ * a JSON string the prelude parses, so a schema's `__proto__` key stays a key,
+ * as it would not in an object literal, and the prelude is one string the
+ * engine evaluates as global code.
+ */
+export declare function preludeSource(tools: readonly PreludeTool[]): string;
+/** The one line `start` evaluates after the prelude: the script, as a string literal, handed to `__run`. */
+export declare function scriptCall(script: string): string;
+//# sourceMappingURL=prelude.d.ts.map

package/dist/src/code-execution/isolate/prelude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prelude.d.ts","sourceRoot":"","sources":["../../../../src/code-execution/isolate/prelude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH,+GAA+G;AAC/G,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,QAAyC,CAAC;AACnE,wFAAwF;AACxF,eAAO,MAAM,YAAY,QAAiC,CAAC;AAS3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAW,GAAG,MAAM,CAoClE;AAuCD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAiNnE;AAED,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD"}