@animalabs/agent-framework 0.23.1 → 0.24.0

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

@@ -0,0 +1,114 @@
+/**
+ * A script's call record, kept in the parent, outside the child, so losing
+ * the child loses none of it. A call goes in at
+ * dispatch, as running until it's answered. Answered calls are counted; those
+ * whose answer the script didn't see are named, with their arguments, so an
+ * agent can tell which effects may have taken place. A script can live a day,
+ * so the record is bounded: it names at most CALLS_NAMED and counts the rest
+ * by tool, and it holds a counted call only while it runs. A named call stays
+ * until the script ends, and its state can still change after the call ends,
+ * as when a timed-out call's answer comes.
+ */
+/** A call's arguments, or a later answer's start, as a return names it: at most this many characters. */
+export declare const CALL_BRIEF_CHARS = 120;
+/** How many calls whose answer the script didn't see a return names; it counts the rest by tool. */
+export declare const CALLS_NAMED = 10;
+/** How a return names a tool, as the agent writes it in a script. */
+export declare const toolRef: (tool: string) => string;
+/**
+ * A copy of `text` that shares no storage with it. A slice of a string can
+ * keep the whole string it was cut from alive, in V8 and in JavaScriptCore, so
+ * a short piece kept from a long text is copied first.
+ */
+export declare function fresh(text: string): string;
+/** `text` cut to CALL_BRIEF_CHARS with "…", never between a surrogate pair's halves, as a copy of its own. */
+export declare function callBrief(text: string): string;
+/** A call whose answer the script didn't see, as a return names it. */
+export interface NamedCall {
+    tool: string;
+    /** Its arguments as the script sent them, cut to CALL_BRIEF_CHARS. */
+    args: string;
+    /**
+     * - `uncertain`: still running when the script ended, so it may or may not take effect.
+     * - `timed-out`: no answer came within the call's timeout, so it may still take effect. The script was given a TimeoutError, unless it ended before reading it.
+     * - `timed-out-answered`: no answer came within the call's timeout, and one came later; `answer` is its start.
+     * - `too-large`: answered, with a result the script couldn't receive (too large for its memory, or nested too deep), so it got ResultTooLarge in its place.
+     * - `unseen`: answered, and the script was stopped or crashed before it read the answer.
+     */
+    state: 'uncertain' | 'timed-out' | 'timed-out-answered' | 'too-large' | 'unseen';
+    /** For `timed-out-answered`: the answer's start, cut to CALL_BRIEF_CHARS. */
+    answer?: string;
+}
+/** The record as a return reports it. */
+export interface CallSummary {
+    /** Calls the script made. */
+    made: number;
+    /** Answered while the script waited, with a result that wasn't an error. */
+    answered: number;
+    /** Answered while the script waited, with a result marked as an error. */
+    failed: number;
+    /** Refused before they ran: nothing was done. */
+    refused: number;
+    /** Never sent, so nothing was done: they timed out while they waited for room in the host, the run ended while they waited, or the host read them once the script's process had exited. */
+    unsent: number;
+    /** Still in flight, the script waiting on them. */
+    running: number;
+    /** Waiting their turn in the host, not sent yet: calls waiting for room, and wakes waiting for theirs. */
+    waiting: number;
+    /** Those whose answer the script didn't see, the first CALLS_NAMED of them, in the order each became so. */
+    named: NamedCall[];
+    /** The rest of those, counted by tool. */
+    more: Record<string, number>;
+}
+/** How a call that the script waited on was answered. */
+export type CallOutcome = 'answered' | 'failed' | 'refused' | 'too-large';
+/** One call the record still follows, held by the caller between its start and its end. */
+export interface CallEntry {
+    readonly tool: string;
+    readonly args: string;
+    /** Set once the call has a place among the named, so a later answer can say what it was. */
+    named: NamedCall | null;
+    /** True once the call's timeout passed with no answer: the script is given a TimeoutError, unless it ended before reading it. */
+    timedOut: boolean;
+    /** True once the record holds the call's last word. */
+    done: boolean;
+}
+export declare class CallLog {
+    private made;
+    private readonly counts;
+    private readonly running;
+    /** Timed-out calls among the named whose answer hasn't come: it can still be named, until the script ends. */
+    private readonly awaiting;
+    private readonly named;
+    private readonly more;
+    /** A call went out: it's running until it's answered. */
+    start(tool: string, argsJson: string): CallEntry;
+    /**
+     * A call or wake the script made was never sent, so nothing was done: a
+     * call that timed out while it waited for room in the host, or that the run
+     * ended, or its process exited, before it went out, and one read after the
+     * process exited; a wake still waiting for its turn when the run ended, or
+     * once a stop was asked or the process exited.
+     */
+    unsent(): void;
+    /** The call's timeout passed with no answer, and the script is given a TimeoutError. Its answer may still come. */
+    timedOut(entry: CallEntry): void;
+    /** The call's answer came. `brief` is the start of what the tool answered, for a call the script stopped waiting for. */
+    answered(entry: CallEntry, outcome: CallOutcome, brief: string): void;
+    /**
+     * The call was answered, and the script ended before it read the answer: a
+     * refusal did nothing, and is counted; any other answer is named.
+     */
+    unseen(entry: CallEntry, outcome: CallOutcome): void;
+    /**
+     * The script ended: every call still running may or may not take effect,
+     * and the record stays as it stands, so it names the calls as the host saw
+     * them when the script ended.
+     */
+    ended(): void;
+    /** The record, with `waiting` calls the host holds back, for room or a wake's turn, which the script has made too. */
+    summary(waiting?: number): CallSummary;
+    /** A place among the named, or a count by tool past CALLS_NAMED. */
+    private name;
+}
+//# sourceMappingURL=calls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../../../src/code-execution/isolate/calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,yGAAyG;AACzG,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,oGAAoG;AACpG,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,qEAAqE;AACrE,eAAO,MAAM,OAAO,SAAU,MAAM,KAAG,MAAqF,CAAC;AAE7H;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,8GAA8G;AAC9G,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,oBAAoB,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjF,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,2LAA2L;IAC3L,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB,4GAA4G;IAC5G,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;AAE1E,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,iIAAiI;IACjI,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,OAAO;IAClB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,8GAA8G;IAC9G,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAElD,yDAAyD;IACzD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAK/C;IAED;;;;;;OAMG;IACH,MAAM,IAAI,IAAI,CAGb;IAED,mHAAmH;IACnH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAO/B;IAED,yHAAyH;IACzH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAcpE;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAOnD;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAQZ;IAED,sHAAsH;IACtH,OAAO,CAAC,OAAO,SAAI,GAAG,WAAW,CAShC;IAED,oEAAoE;IACpE,OAAO,CAAC,IAAI;CASb"}

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

@@ -0,0 +1,145 @@
+/**
+ * A script's call record, kept in the parent, outside the child, so losing
+ * the child loses none of it. A call goes in at
+ * dispatch, as running until it's answered. Answered calls are counted; those
+ * whose answer the script didn't see are named, with their arguments, so an
+ * agent can tell which effects may have taken place. A script can live a day,
+ * so the record is bounded: it names at most CALLS_NAMED and counts the rest
+ * by tool, and it holds a counted call only while it runs. A named call stays
+ * until the script ends, and its state can still change after the call ends,
+ * as when a timed-out call's answer comes.
+ */
+/** A call's arguments, or a later answer's start, as a return names it: at most this many characters. */
+export const CALL_BRIEF_CHARS = 120;
+/** How many calls whose answer the script didn't see a return names; it counts the rest by tool. */
+export const CALLS_NAMED = 10;
+/** How a return names a tool, as the agent writes it in a script. */
+export const toolRef = (tool) => (tool === 'wake_agent' ? 'wake_agent()' : `tools[${JSON.stringify(tool)}]`);
+/**
+ * A copy of `text` that shares no storage with it. A slice of a string can
+ * keep the whole string it was cut from alive, in V8 and in JavaScriptCore, so
+ * a short piece kept from a long text is copied first.
+ */
+export function fresh(text) {
+    return JSON.parse(JSON.stringify(text));
+}
+/** `text` cut to CALL_BRIEF_CHARS with "…", never between a surrogate pair's halves, as a copy of its own. */
+export function callBrief(text) {
+    if (text.length <= CALL_BRIEF_CHARS)
+        return fresh(text);
+    let cut = CALL_BRIEF_CHARS - 1;
+    const before = text.charCodeAt(cut - 1);
+    if (before >= 0xd800 && before <= 0xdbff)
+        cut -= 1;
+    return fresh(`${text.slice(0, cut)}…`);
+}
+export class CallLog {
+    made = 0;
+    counts = { answered: 0, failed: 0, refused: 0, unsent: 0 };
+    running = new Set();
+    /** Timed-out calls among the named whose answer hasn't come: it can still be named, until the script ends. */
+    awaiting = new Set();
+    named = [];
+    more = new Map();
+    /** A call went out: it's running until it's answered. */
+    start(tool, argsJson) {
+        this.made += 1;
+        const entry = { tool, args: callBrief(argsJson), named: null, timedOut: false, done: false };
+        this.running.add(entry);
+        return entry;
+    }
+    /**
+     * A call or wake the script made was never sent, so nothing was done: a
+     * call that timed out while it waited for room in the host, or that the run
+     * ended, or its process exited, before it went out, and one read after the
+     * process exited; a wake still waiting for its turn when the run ended, or
+     * once a stop was asked or the process exited.
+     */
+    unsent() {
+        this.made += 1;
+        this.counts.unsent += 1;
+    }
+    /** The call's timeout passed with no answer, and the script is given a TimeoutError. Its answer may still come. */
+    timedOut(entry) {
+        if (entry.done || entry.timedOut)
+            return;
+        entry.timedOut = true;
+        this.running.delete(entry);
+        entry.named = this.name(entry, 'timed-out');
+        if (entry.named)
+            this.awaiting.add(entry);
+        else
+            entry.done = true;
+    }
+    /** The call's answer came. `brief` is the start of what the tool answered, for a call the script stopped waiting for. */
+    answered(entry, outcome, brief) {
+        if (entry.done)
+            return;
+        entry.done = true;
+        this.running.delete(entry);
+        this.awaiting.delete(entry);
+        if (entry.timedOut) {
+            if (entry.named) {
+                entry.named.state = 'timed-out-answered';
+                entry.named.answer = callBrief(brief);
+            }
+            return;
+        }
+        if (outcome === 'too-large')
+            this.name(entry, 'too-large');
+        else
+            this.counts[outcome] += 1;
+    }
+    /**
+     * The call was answered, and the script ended before it read the answer: a
+     * refusal did nothing, and is counted; any other answer is named.
+     */
+    unseen(entry, outcome) {
+        if (entry.done)
+            return;
+        entry.done = true;
+        this.running.delete(entry);
+        this.awaiting.delete(entry);
+        if (outcome === 'refused')
+            this.counts.refused += 1;
+        else
+            this.name(entry, 'unseen');
+    }
+    /**
+     * The script ended: every call still running may or may not take effect,
+     * and the record stays as it stands, so it names the calls as the host saw
+     * them when the script ended.
+     */
+    ended() {
+        for (const entry of this.running) {
+            entry.done = true;
+            this.name(entry, 'uncertain');
+        }
+        this.running.clear();
+        for (const entry of this.awaiting)
+            entry.done = true;
+        this.awaiting.clear();
+    }
+    /** The record, with `waiting` calls the host holds back, for room or a wake's turn, which the script has made too. */
+    summary(waiting = 0) {
+        return {
+            made: this.made + waiting,
+            ...this.counts,
+            running: this.running.size,
+            waiting,
+            named: this.named.map((c) => ({ ...c })),
+            more: Object.fromEntries(this.more),
+        };
+    }
+    /** A place among the named, or a count by tool past CALLS_NAMED. */
+    name(entry, state) {
+        if (this.named.length < CALLS_NAMED) {
+            const named = { tool: entry.tool, args: entry.args, state };
+            this.named.push(named);
+            return named;
+        }
+        this.more.set(entry.tool, (this.more.get(entry.tool) ?? 0) + 1);
+        return null;
+    }
+}
+//# sourceMappingURL=calls.js.map

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

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

package/dist/src/code-execution/isolate/child-entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=child-entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"child-entry.d.ts","sourceRoot":"","sources":["../../../../src/code-execution/isolate/child-entry.ts"],"names":[],"mappings":""}

package/dist/src/code-execution/isolate/child-entry.js

@@ -0,0 +1,5 @@
+/** The script the parent spawns for each script: the child, on the engine. */
+import { loadEngine } from '../engine.js';
+import { childMain } from './child-main.js';
+childMain(loadEngine);
+//# sourceMappingURL=child-entry.js.map

package/dist/src/code-execution/isolate/child-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-entry.js","sourceRoot":"","sources":["../../../../src/code-execution/isolate/child-entry.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,SAAS,CAAC,UAAU,CAAC,CAAC"}

package/dist/src/code-execution/isolate/child-main.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The child's process: reads the parent's frames on stdin, writes its own on
+ * fd 3, runs the script with the engine, and exits. Spawned by the parent with
+ * the parent's own runtime (`process.execPath`), Node's or Bun's.
+ *
+ * The channel is the one way that works the same under both runtimes, as
+ * probes under Bun 1.4.3, Node 24.19.0 and Node 20.20.2 showed: a socket on
+ * another fd reads nothing under Bun, and a file stream on one leaves Node's
+ * exit waiting on a blocked read. The child writes with `writeSync`, since its slots run while
+ * the engine is mid-call, and output has to reach the parent while a guest
+ * computes without queuing in memory.
+ *
+ * `runChildProcess` takes the engine loader so a test can spawn a child whose
+ * engine is a stand-in; the entry the parent spawns in production passes the
+ * engine's binding.
+ */
+import { type LoadEngine } from './child.js';
+export declare function runChildProcess(loadEngine: LoadEngine): Promise<number>;
+/**
+ * The child's process as the parent spawns it: run the script, and exit. An
+ * engine that fails, rather than the script, ends the child with its reason
+ * on one line of stderr, which the parent puts in the crash it reports; any
+ * other throw is a fault here, and its stack goes there instead.
+ */
+export declare function childMain(loadEngine: LoadEngine): void;
+//# sourceMappingURL=child-main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"child-main.d.ts","sourceRoot":"","sources":["../../../../src/code-execution/isolate/child-main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAuErE,wBAAsB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB7E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAatD"}

package/dist/src/code-execution/isolate/child-main.js

@@ -0,0 +1,132 @@
+/**
+ * The child's process: reads the parent's frames on stdin, writes its own on
+ * fd 3, runs the script with the engine, and exits. Spawned by the parent with
+ * the parent's own runtime (`process.execPath`), Node's or Bun's.
+ *
+ * The channel is the one way that works the same under both runtimes, as
+ * probes under Bun 1.4.3, Node 24.19.0 and Node 20.20.2 showed: a socket on
+ * another fd reads nothing under Bun, and a file stream on one leaves Node's
+ * exit waiting on a blocked read. The child writes with `writeSync`, since its slots run while
+ * the engine is mid-call, and output has to reach the parent while a guest
+ * computes without queuing in memory.
+ *
+ * `runChildProcess` takes the engine loader so a test can spawn a child whose
+ * engine is a stand-in; the entry the parent spawns in production passes the
+ * engine's binding.
+ */
+import { writeSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
+import { EngineError, MAX_MEMORY_BYTES } from '../engine.js';
+import { runChild } from './child.js';
+import { encodeFrame, FrameDecoder, RESULT_FRAME_OVERHEAD } from './frames.js';
+import { MAX_CHILD_FRAME_BYTES } from './protocol.js';
+const TO_PARENT_FD = 3;
+/**
+ * The largest frame the child takes from its parent: a result as large as the
+ * largest memory can be given (a third of it, as the parent bounds a result),
+ * with its header. The parent is trusted; this only bounds a broken one.
+ */
+const MAX_PARENT_FRAME_BYTES = Math.floor(MAX_MEMORY_BYTES / 3) + RESULT_FRAME_OVERHEAD;
+/** A shared buffer to wait on, so a full pipe is retried after a short sleep without the event loop. */
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+/** Write all of `buf` to `fd`, synchronously, waiting a moment when the pipe is full. */
+function writeAll(fd, buf) {
+    let offset = 0;
+    while (offset < buf.length) {
+        try {
+            offset += writeSync(fd, buf, offset, buf.length - offset);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'EAGAIN' && code !== 'EWOULDBLOCK')
+                throw err;
+            Atomics.wait(sleeper, 0, 0, 1);
+        }
+    }
+}
+/** The parent's frames, as messages, from the child's stdin. The parent's frames are trusted: a bad one ends the child. */
+function parentFrames() {
+    const decoder = new FrameDecoder(MAX_PARENT_FRAME_BYTES, true);
+    const queue = [];
+    let ended = false;
+    let failure = null;
+    let wake = null;
+    const stream = process.stdin;
+    stream.on('data', (chunk) => {
+        try {
+            for (const value of decoder.push(chunk))
+                queue.push(value);
+        }
+        catch (err) {
+            failure = err;
+        }
+        wake?.();
+    });
+    const finish = () => {
+        ended = true;
+        wake?.();
+    };
+    stream.on('end', finish);
+    stream.on('error', (err) => {
+        failure = err;
+        finish();
+    });
+    return async () => {
+        for (;;) {
+            if (failure)
+                throw failure;
+            const next = queue.shift();
+            if (next)
+                return next;
+            if (ended)
+                return null;
+            await new Promise((resolve) => {
+                wake = () => {
+                    wake = null;
+                    resolve();
+                };
+            });
+        }
+    };
+}
+export async function runChildProcess(loadEngine) {
+    const next = parentFrames();
+    const first = await next();
+    if (first === null)
+        return 0;
+    if (first.t !== 'start')
+        throw new Error('the first frame from the parent was not a start');
+    const start = first;
+    const io = {
+        next,
+        // Against the parent's cap, so the two can't drift apart.
+        send: (message) => writeAll(TO_PARENT_FD, encodeFrame(message, MAX_CHILD_FRAME_BYTES)),
+        now: () => performance.now(),
+        // On Linux and macOS an orphan is reparented, so its parent's pid isn't
+        // the one the start named once its parent has gone, even if that went
+        // before this ran. Windows keeps the pid, so an orphan isn't seen there.
+        parentGone: () => process.ppid !== start.parentPid,
+        orphaned: () => process.exit(0),
+    };
+    await runChild(io, start, loadEngine);
+    return 0;
+}
+/**
+ * The child's process as the parent spawns it: run the script, and exit. An
+ * engine that fails, rather than the script, ends the child with its reason
+ * on one line of stderr, which the parent puts in the crash it reports; any
+ * other throw is a fault here, and its stack goes there instead.
+ */
+export function childMain(loadEngine) {
+    runChildProcess(loadEngine).then((code) => process.exit(code), (err) => {
+        // Written at once: a write to a pipe is asynchronous on macOS, and the exit would drop it.
+        try {
+            writeSync(2, err instanceof EngineError ? `${err.message}\n` : `${err instanceof Error ? err.stack : String(err)}\n`);
+        }
+        catch {
+            // The parent learns of the crash from the exit either way.
+        }
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=child-main.js.map

package/dist/src/code-execution/isolate/child-main.js.map

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

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

@@ -0,0 +1,44 @@
+/**
+ * A script's child: one process per script, which runs it in the engine and
+ * answers the engine's four imports. It takes its start from the parent's
+ * first frame, sends each tool call to the parent and settles it with the
+ * parent's answer, flushes the output in bounded batches, and reports how the
+ * script ended. A crash it can't report: the parent sees that the child ended
+ * without saying how.
+ *
+ * Stopping: the parent creates the stop file and sends a stop frame. A
+ * computing guest's interrupt import sees the file, checked at most every few
+ * milliseconds, so a stop reaches a spinning guest without its event loop; an
+ * idle guest's child reads the frame. Why the stop was asked is the parent's
+ * to say, so the child reports only that the script stopped.
+ */
+import { type Engine, type EngineLimits, type EngineSlots } from '../engine.js';
+import type { ParentMessage, StartMessage } from './protocol.js';
+/** How often, at most, the interrupt import looks for the stop file. */
+export declare const STOP_CHECK_MS = 3;
+export type LoadEngine = (limits: EngineLimits, slots: EngineSlots) => Promise<Engine>;
+export interface ChildIo {
+    /** The parent's frames, in order, each already decoded; done when the parent closes its end. */
+    next(): Promise<ParentMessage | null>;
+    /**
+     * Send one message now, synchronously: the engine may be mid-call. A message
+     * too long for a frame throws its FrameError, and nothing is sent.
+     */
+    send(message: unknown): void;
+    /** Milliseconds from some fixed point. */
+    now(): number;
+    /** Whether the parent has gone, so no one is left to stop the script or read its ending. */
+    parentGone?(): boolean;
+    /**
+     * End the child's process at once, its parent having gone: nothing it does
+     * reaches anyone, its unsent output included, and nothing is left to kill
+     * it if its guest keeps a stop from ending it. The child looks for its
+     * parent at the engine's interrupt checks, at most once a stop check
+     * (`STOP_CHECK_MS`), after a stop as before one. Without this, the child
+     * stops its guest instead.
+     */
+    orphaned?(): never;
+}
+/** Run the script `start` names to its end. Resolves once its ending is sent, or when the parent closes the channel. */
+export declare function runChild(io: ChildIo, start: StartMessage, loadEngine: LoadEngine): Promise<void>;
+//# sourceMappingURL=child.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"child.d.ts","sourceRoot":"","sources":["../../../../src/code-execution/isolate/child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAoB,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAmC,MAAM,cAAc,CAAC;AAKnI,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEjE,wEAAwE;AACxE,eAAO,MAAM,aAAa,IAAI,CAAC;AAS/B,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvF,MAAM,WAAW,OAAO;IACtB,gGAAgG;IAChG,IAAI,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,0CAA0C;IAC1C,GAAG,IAAI,MAAM,CAAC;IACd,4FAA4F;IAC5F,UAAU,CAAC,IAAI,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,KAAK,CAAC;CACpB;AAYD,wHAAwH;AACxH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmOtG"}