@animalabs/agent-framework 0.23.2 → 0.24.0

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

@@ -0,0 +1,401 @@
+/**
+ * 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.
+ */
+import { MAX_CALLS_IN_FLIGHT } from './protocol.js';
+import { cutOf } from './render.js';
+/** The host call name `wake_agent()` uses. Parentheses can't be in a tool's name, so it never names a tool. */
+export 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 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 const SCRIPT_FRAME = /^\s+at\s[^]*<input>:\d{1,10}:\d+\)?$/;
+/** A script frame's place, at its end: its line is renumbered as the agent wrote it. */
+export const SCRIPT_PLACE = /<input>:(\d{1,10})(:\d+\)?)$/;
+/**
+ * SCRIPT_FRAME as it reads a line within a whole stack, from the line's
+ * start (sticky) to the line feed or the stack's end that closes it, so that
+ * no string is made for the line: a line holds no line feed, so there `\s`
+ * is `[^\S\n]` and `[^]` is `[^\n]`. A test holds the two to one reading.
+ */
+const SCRIPT_FRAME_IN_STACK = /[^\S\n]+at[^\S\n][^\n]*<input>:\d{1,10}:\d+\)?(?=\n|$)/y;
+/**
+ * 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 function scriptFrames(stack, max = Infinity) {
+    // Two walks of the stack, a line at a time, making no string for a line
+    // that isn't a frame, or for a frame the cut doesn't keep: a stack the
+    // script set can be any length, as many lines as characters or one line as
+    // long as the stack, and beside it the child holds only what the cut keeps.
+    // The first walk measures the frames' text; the second takes what the cut
+    // keeps of it, all of it if it fits `max`, or else its first and last
+    // halves (bounded's cut, cutOf).
+    let length = -1;
+    eachFrame(stack, (start, place, line, rest, end) => {
+        length += 1 + (place - start) + LABEL_CHARS + digits(line) + (end - rest);
+    });
+    if (length < 0)
+        return '';
+    const fits = length <= max;
+    const half = fits ? length : Math.floor(max / 2);
+    const tailFrom = length - (fits ? 0 : half);
+    const head = [];
+    const tail = [];
+    let at = 0;
+    // The part of the frames' text from `at` that `text` gives from `from` to
+    // `to`: what of it falls in the head or the tail goes there.
+    const put = (text, from, to) => {
+        const n = to - from;
+        if (at < half)
+            head.push(text.slice(from, from + Math.min(n, half - at)));
+        if (at + n > tailFrom)
+            tail.push(text.slice(from + Math.max(0, tailFrom - at), to));
+        at += n;
+    };
+    eachFrame(stack, (start, place, line, rest, end) => {
+        if (at > 0)
+            put('\n', 0, 1);
+        put(stack, start, place);
+        const n = LABEL_CHARS + digits(line);
+        if (at < half || at + n > tailFrom)
+            put(`script:${line}`, 0, n);
+        else
+            at += n;
+        put(stack, rest, end);
+    });
+    return fits ? head.join('') : cutOf(head.join(''), tail.join(''), length);
+}
+/** `script:`, which a frame's place is renumbered with. */
+const LABEL_CHARS = 7;
+/** How many digits a whole number from 1 to 9,999,999,999 is written with. */
+function digits(n) {
+    let count = 1;
+    for (let rest = n; rest >= 10; rest = Math.floor(rest / 10))
+        count += 1;
+    return count;
+}
+/**
+ * Each of the script's frames in `stack`, in order, as scriptFrames reads
+ * them, with no string made for a line: where its line starts, where its
+ * place starts, its place's line as the agent wrote it, where the rest of its
+ * place starts (`:COLUMN`, and a closing parenthesis), and where its line
+ * ends.
+ */
+function eachFrame(stack, frame) {
+    for (let start = 0; start <= stack.length;) {
+        let end = stack.indexOf('\n', start);
+        if (end === -1)
+            end = stack.length;
+        SCRIPT_FRAME_IN_STACK.lastIndex = start;
+        if (SCRIPT_FRAME_IN_STACK.test(stack)) {
+            // A frame ends in its place, and no later `<input>:` fits in what
+            // follows it there. Its line has at most ten digits, so the number is
+            // exact and digits() ends, as it wouldn't on the Infinity that a few
+            // hundred digits parse to.
+            const place = stack.lastIndexOf('<input>:', end);
+            let line = 0;
+            let rest = place + 8;
+            for (let c = stack.charCodeAt(rest); c >= 48 && c <= 57; c = stack.charCodeAt(++rest))
+                line = line * 10 + (c - 48);
+            frame(start, place, Math.max(1, line - SCRIPT_LINE_OFFSET), rest, end);
+        }
+        start = end + 1;
+    }
+}
+/**
+ * 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 function preludeSource(tools) {
+    const toolsJson = JSON.stringify(tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema ?? null })));
+    return `(function (host, out, toolList) {
+  "use strict";
+  const stringify = JSON.stringify;
+  const ErrorCtor = Error;
+  const TypeErrorCtor = TypeError;
+  const scriptOffset = ${SCRIPT_LINE_OFFSET};
+
+  // QuickJS stacks list frames only: lead with "Name: message", as V8 does, and
+  // keep only the script's own frames, leaving out this prelude's, the
+  // engine's native ones and the line that started the script, each numbered
+  // as the agent wrote its lines. The child applies the same rule to every
+  // failure's stack (scriptFrames), reading each line in place.
+  const scriptFrame = ${SCRIPT_FRAME};
+  const scriptPlace = ${SCRIPT_PLACE};
+  function errorText(error) {
+    const head = error.message ? String(error.name) + ": " + String(error.message) : String(error.name);
+    const stack = typeof error.stack === "string" ? error.stack : "";
+    const frames = stack.split("\\n")
+      .filter((line) => scriptFrame.test(line))
+      .map((line) => line.replace(scriptPlace, (m, n, rest) => "script:" + Math.max(1, Number(n) - scriptOffset) + rest));
+    return [head, ...frames].join("\\n");
+  }
+
+  function format(value) {
+    if (typeof value === "string") return value;
+    if (value instanceof ErrorCtor) return errorText(value);
+    try {
+      const json = stringify(value);
+      return json === undefined ? String(value) : json;
+    } catch {
+      return String(value);
+    }
+  }
+
+  function write(stream, value) {
+    let rendered;
+    try {
+      rendered = format(value);
+    } catch (error) {
+      throw new TypeErrorCtor(error instanceof ErrorCtor ? error.message : String(error));
+    }
+    out(stream, rendered + "\\n");
+  }
+
+  // A refusal before dispatch arrives as its JSON, { name, message, ...fields }.
+  function asError(reason) {
+    if (reason instanceof ErrorCtor) return reason;
+    const fields = reason !== null && typeof reason === "object" ? reason : { message: String(reason) };
+    const error = new ErrorCtor(typeof fields.message === "string" ? fields.message : "the call was refused");
+    for (const key of Object.keys(fields)) {
+      if (key === "name" || key === "message" || key === "stack") continue;
+      Object.defineProperty(error, key, { value: fields[key], writable: true, enumerable: true, configurable: true });
+    }
+    if (typeof fields.name === "string" && fields.name) error.name = fields.name;
+    return error;
+  }
+
+  function toJson(name, args) {
+    let json;
+    try {
+      json = stringify(args);
+    } catch (error) {
+      throw new TypeErrorCtor(name + "'s arguments aren't JSON (" + (error instanceof ErrorCtor ? error.message : String(error)) + "); nothing was sent");
+    }
+    if (json === undefined) throw new TypeErrorCtor(name + "'s arguments aren't JSON; nothing was sent");
+    return json;
+  }
+
+  // At most maxInFlight of the script's tool calls are out at once. One past
+  // them waits here, in the script's own memory, until one is answered, and
+  // its place passes straight to it: never refused, only paced.
+  const maxInFlight = ${MAX_CALLS_IN_FLIGHT};
+  let inFlight = 0;
+  const waiting = [];
+  function release() {
+    const next = waiting.shift();
+    if (next) next();
+    else inFlight -= 1;
+  }
+  function call(name, args) {
+    let json;
+    try {
+      json = args === undefined ? "{}" : toJson(name, args);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return new Promise((resolve, reject) => {
+      const go = () => {
+        let pending;
+        try {
+          pending = host(name, json);
+        } catch (error) {
+          release();
+          reject(asError(error));
+          return;
+        }
+        pending.then(
+          (value) => { release(); resolve(value); },
+          (reason) => { release(); reject(asError(reason)); },
+        );
+      };
+      if (inFlight < maxInFlight) {
+        inFlight += 1;
+        go();
+      } else {
+        waiting.push(go);
+      }
+    });
+  }
+
+  // wake_agent() takes no place among the calls in flight. The child refuses
+  // a payload too large, and a wake past the script's cap, before any goes out.
+  function wake(payload) {
+    let json;
+    try {
+      json = toJson("wake_agent()", payload === undefined ? null : payload);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return host(${JSON.stringify(WAKE_CALL_NAME)}, json).then((value) => value, (reason) => { throw asError(reason); });
+  }
+
+  const tools = Object.create(null);
+  const allTools = [];
+  for (const { name, description, inputSchema } of toolList) {
+    if (name in tools) continue;
+    tools[name] = (args) => call(name, args);
+    allTools.push(Object.freeze({ name, description, inputSchema }));
+  }
+  Object.freeze(tools);
+  Object.freeze(allTools);
+
+  // A name that isn't a tool throws at once, naming the close matches, rather
+  // than failing later as "not a function". \`in\` still answers false.
+  const comparable = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const names = allTools.map((tool) => tool.name);
+  const toolsProxy = new Proxy(tools, {
+    get(object, property, receiver) {
+      if (typeof property !== "string" || property in object || property in Object.prototype || property === "then" || property === "toJSON") {
+        return Reflect.get(object, property, receiver);
+      }
+      const wanted = comparable(property);
+      const exact = names.filter((name) => comparable(name) === wanted);
+      const close = exact.length > 0 ? exact : names.filter((name) => wanted && (comparable(name).includes(wanted) || wanted.includes(comparable(name))));
+      let message = "tools[" + stringify(property) + "] is not one of your tools.";
+      if (close.length > 0) message += " Did you mean " + close.slice(0, 5).map((name) => "tools[" + stringify(name) + "]").join(", ") + "?";
+      else if (names.length === 0) message += " You have no tools.";
+      else if (names.length <= 20) message += " Your tools: " + names.join(", ") + ".";
+      else message += " ALL_TOOLS lists them.";
+      message += " Nothing was sent.";
+      throw new TypeErrorCtor(message);
+    },
+  });
+
+  const consoleObject = {};
+  for (const level of ["log", "info", "debug"]) consoleObject[level] = (...args) => out(1, args.map(format).join(" ") + "\\n");
+  for (const level of ["warn", "error"]) consoleObject[level] = (...args) => out(2, args.map(format).join(" ") + "\\n");
+  Object.freeze(consoleObject);
+
+  const AsyncFunction = (async function () {}).constructor;
+  // The script's value, as the JSON text of what it returned, serialized here
+  // once: its toJSON and getters run once, and the engine serializes this text
+  // as a string, which runs no script code however often it's read. A value
+  // JSON can't hold, such as a function, a cycle or a BigInt, is its string form.
+  async function run(src) {
+    let value;
+    try {
+      const fn = new AsyncFunction(src);
+      value = await fn.call(undefined);
+    } catch (error) {
+      // An Error goes as it is, a syntax error's included: the child puts its
+      // frames as the agent reads them (scriptFrames). Anything else thrown,
+      // such as a plain object or a string, fails the script with its JSON or
+      // its string form as the message, so the agent reads what was thrown;
+      // its stack, made here, holds no frame of the script's.
+      if (error instanceof ErrorCtor) throw error;
+      const failure = new ErrorCtor(format(error));
+      failure.name = "";
+      throw failure;
+    }
+    if (value === undefined) return undefined;
+    let json;
+    try {
+      json = stringify(value);
+    } catch {
+      json = undefined;
+    }
+    if (json !== undefined) return json;
+    // Said as a string, so the agent reads that the value itself didn't come back.
+    let text;
+    try {
+      text = "JSON can't hold the returned value, so this is its string form: " + String(value);
+    } catch {
+      text = "JSON can't hold the returned value, and it has no string form";
+    }
+    return stringify(text);
+  }
+
+  Object.defineProperty(globalThis, "tools", { value: toolsProxy, enumerable: true });
+  Object.defineProperty(globalThis, "ALL_TOOLS", { value: allTools, enumerable: true });
+  Object.defineProperty(globalThis, "console", { value: consoleObject, enumerable: true, configurable: true });
+  Object.defineProperty(globalThis, "text", { value: (value) => write(1, value), enumerable: true });
+  Object.defineProperty(globalThis, "wake_agent", { value: wake, enumerable: true });
+  Object.defineProperty(globalThis, "__run", { value: run });
+  try { delete globalThis.__host; delete globalThis.__output; } catch {}
+})(globalThis.__host, globalThis.__output, JSON.parse(${JSON.stringify(toolsJson)}));
+`;
+}
+/** The one line `start` evaluates after the prelude: the script, as a string literal, handed to `__run`. */
+export function scriptCall(script) {
+    return `await __run(${JSON.stringify(script)});`;
+}
+//# sourceMappingURL=prelude.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prelude.js","sourceRoot":"","sources":["../../../../src/code-execution/isolate/prelude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,+GAA+G;AAC/G,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,sCAAsC,CAAC;AACnE,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG,8BAA8B,CAAC;AAC3D;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,yDAAyD,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,GAAG,GAAG,QAAQ;IACxD,wEAAwE;IACxE,uEAAuE;IACvE,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,sEAAsE;IACtE,iCAAiC;IACjC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC;IAChB,SAAS,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACjD,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IACH,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,MAAM,IAAI,GAAG,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,0EAA0E;IAC1E,6DAA6D;IAC7D,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,IAAY,EAAE,EAAU,EAAQ,EAAE;QAC3D,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACpB,IAAI,EAAE,GAAG,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1E,IAAI,EAAE,GAAG,CAAC,GAAG,QAAQ;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACpF,EAAE,IAAI,CAAC,CAAC;IACV,CAAC,CAAC;IACF,SAAS,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACjD,IAAI,EAAE,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACzB,MAAM,CAAC,GAAG,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,EAAE,GAAG,IAAI,IAAI,EAAE,GAAG,CAAC,GAAG,QAAQ;YAAE,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;;YAC3D,EAAE,IAAI,CAAC,CAAC;QACb,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED,2DAA2D;AAC3D,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,8EAA8E;AAC9E,SAAS,MAAM,CAAC,CAAS;IACvB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC;QAAE,KAAK,IAAI,CAAC,CAAC;IACxE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,KAAa,EAAE,KAAsF;IACtH,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,KAAK,CAAC,MAAM,GAAI,CAAC;QAC5C,IAAI,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;QACnC,qBAAqB,CAAC,SAAS,GAAG,KAAK,CAAC;QACxC,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,kEAAkE;YAClE,sEAAsE;YACtE,qEAAqE;YACrE,2BAA2B;YAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;YACjD,IAAI,IAAI,GAAG,CAAC,CAAC;YACb,IAAI,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;YACrB,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;gBAAE,IAAI,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YACnH,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,kBAAkB,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAA6B;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACvI,OAAO;;;;;yBAKgB,kBAAkB;;;;;;;wBAOnB,YAAY;wBACZ,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA0DZ,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAgDzB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wDAsFQ,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;CAChF,CAAC;AACF,CAAC;AAED,4GAA4G;AAC5G,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,eAAe,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,151 @@
+/**
+ * The messages between a script's parent and its child, and the checks that
+ * turn a decoded frame from the child into one of them. Every frame from a
+ * child is untrusted: the parent acts only on a
+ * message `decodeChildMessage` accepts, and any other ends the script as
+ * crashed.
+ */
+import { countJsonValues } from './frames.js';
+import type { PreludeTool } from './prelude.js';
+export { countJsonValues };
+/**
+ * The most tool calls a script has out at once, from the call until the
+ * script has its answer. One past them waits in the script, in its own memory,
+ * until one is answered, and is never refused, so a `Promise.all` over many
+ * calls still works, only paced, and what waits is the script's to hold. A
+ * child that sends more crashes its run. `wake_agent()` takes no place: its
+ * answer holds nothing, and its own cap bounds it.
+ */
+export declare const MAX_CALLS_IN_FLIGHT = 16;
+/**
+ * The most JSON a tool call's arguments may be, in UTF-8 bytes: room for a
+ * generated file of a few MB of ordinary text as one string (escaping takes
+ * more room for quotes, backslashes and control characters). With MAX_ARGUMENT_VALUES it bounds
+ * what the host holds for a call while it runs: its arguments' text and their
+ * parsed value, at most about twice these bytes each (a string the runtime
+ * keeps in two bytes a character) and about 92 bytes a value, the most a
+ * value cost in a parse under Node 24 and Bun 1.4.
+ */
+export declare const MAX_ARGUMENT_BYTES: number;
+/** The most values a tool call's arguments may hold: each object, array and element counts. */
+export declare const MAX_ARGUMENT_VALUES = 100000;
+/** The most JSON a `wake_agent()` payload may be, in UTF-8 bytes: a wake says what happened, and a longer result is written with a tool. */
+export declare const MAX_WAKE_PAYLOAD_BYTES: number;
+/** A cap as the tool's text says it, such as 4 MiB. */
+export declare const capText: (bytes: number) => string;
+/** A `wake_agent()` payload the host won't take, said to the script: nothing was sent. Null when it may go out. */
+export declare function wakeRefusal(payloadJson: string): {
+    name: 'WakeRefused';
+    message: string;
+    bytes: number;
+} | null;
+/**
+ * The longest frame a child sends: a call frame carries its arguments escaped,
+ * at most six bytes for each of the 4 MiB the script may send, with room for
+ * its name and the rest. The child encodes its frames against it, and the
+ * parent refuses a longer one before its body is kept, so one frame being
+ * read costs the host at most this much as bytes, and its text and its parse
+ * up to twice as much again each.
+ */
+export declare const MAX_CHILD_FRAME_BYTES: number;
+/** A wake past the script's cap, said to the script: nothing was sent. */
+export declare function wakeLimitRefusal(maxWakes: number): {
+    name: 'WakeRefused';
+    message: string;
+};
+/** A call's arguments the host won't take, said to the script: nothing was sent. Null when they may go out. */
+export declare function argumentsRefusal(tool: string, argsJson: string): {
+    name: 'ArgumentsTooLarge';
+    message: string;
+    bytes: number;
+} | null;
+/** The error a script gets for a call whose result was too large for its memory: the call took effect. */
+export declare const RESULT_TOO_LARGE = "ResultTooLarge";
+/** Why a stop was asked for: by the agent, or at the script's limit. Only the parent knows it. */
+export type StopReason = 'agent' | 'limit';
+/** The first frame to the child: the script and everything it runs with. */
+export interface StartMessage {
+    t: 'start';
+    script: string;
+    tools: PreludeTool[];
+    /** The WebAssembly memory's maximum: the child's budget. */
+    memoryMaxBytes: number;
+    maxStackBytes?: number;
+    /** The file whose appearance stops the script: its content says nothing. */
+    stopFile: string;
+    /** How often, at most, waiting output is flushed while the guest runs. */
+    flushMs: number;
+    /** The most wakes the script may send: the child refuses one past them itself. */
+    maxWakes: number;
+    /** The parent's pid: the child ends its process once its parent is another, its parent having gone. */
+    parentPid: number;
+}
+/**
+ * A tool call's answer, as the child decodes a result frame: `ok` resolves the
+ * guest's promise with the parsed `json`, otherwise rejects with it. The JSON
+ * stays bytes, for the engine to parse in the guest.
+ */
+export type { ResultFrame as ResultMessage } from './frames.js';
+import type { ResultFrame } from './frames.js';
+/** A stop for a child whose guest is idle, waiting on calls; a computing guest sees the stop file instead. */
+export interface StopMessage {
+    t: 'stop';
+}
+export type ParentMessage = StartMessage | ResultFrame | StopMessage;
+/** The guest called a tool, or `wake_agent()`, by the prelude's call name. */
+export interface CallMessage {
+    t: 'call';
+    id: number;
+    name: string;
+    /** The arguments as the guest's JSON text. */
+    args: string;
+}
+/** Output the guest wrote since the last such frame. */
+export interface OutMessage {
+    t: 'out';
+    text: string;
+}
+/** An error as the guest describes it. */
+export interface GuestError {
+    name: string;
+    message: string;
+    /** The script's frames, one per line, as the agent reads them (scriptFrames): the name and message aren't in it. */
+    stack?: string;
+}
+/**
+ * The engine settled a call's result, so its place is free. `unfit` when the
+ * result didn't fit the guest's memory, so the script got ResultTooLarge in
+ * its place. The parent's record counts a call as the script saw it.
+ */
+export interface SeenMessage {
+    t: 'seen';
+    id: number;
+    unfit?: true;
+}
+/**
+ * How the script ended, as the child saw it. A crash is the parent's to see:
+ * the child can't report it. A stop's reason is the parent's too, since it
+ * asked for the stop.
+ */
+export type EndMessage = {
+    t: 'end';
+    how: 'finished';
+    value?: string;
+} | {
+    t: 'end';
+    how: 'failed';
+    error: GuestError;
+    stalled?: boolean;
+} | {
+    t: 'end';
+    how: 'stopped';
+};
+export type ChildMessage = CallMessage | OutMessage | SeenMessage | EndMessage;
+/**
+ * A frame from a child, as a message the parent may act on, or the reason it
+ * can't be one. Fields beyond those a message has are ignored.
+ */
+export declare function decodeChildMessage(value: unknown): ChildMessage | {
+    invalid: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

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

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