@animalabs/agent-framework 0.23.1 → 0.24.0

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

@@ -0,0 +1,250 @@
+/**
+ * The parent's side of one script: its child process, the calls it makes, its
+ * output, and how it ends. One `ScriptRun` per script, and one child per run,
+ * which ends with it, so nothing a script held stays after it.
+ *
+ * Every frame from the child is decoded and checked before the parent acts on
+ * it, since the child is untrusted. A frame that breaks the protocol, a child
+ * that exits without saying how the script ended, or one that doesn't stop
+ * when asked, ends the run as crashed. A tool call goes to `onToolCall`, the
+ * bridge to the framework's dispatcher, and its outcome goes into the run's
+ * call record at dispatch, as running until it's answered.
+ *
+ * What the host holds for a script is bounded: at most MAX_CALLS_IN_FLIGHT of
+ * its calls wait for answers at once, and at most MAX_CALLS_IN_FLIGHT are out
+ * in the host, timed-out ones whose tools still run included, with any past
+ * those waiting here as their text. Each call's arguments are within
+ * MAX_ARGUMENT_BYTES and MAX_ARGUMENT_VALUES, and each answer is at most
+ * `maxResultBytes`. Answers wait for the child as their frames, written while
+ * its stdin takes them and after its 'drain' once it hasn't, so each is held
+ * once, in bytes.
+ */
+import { type OutputBounds, type OutputWindow } from './output.js';
+import { type PreludeTool } from './prelude.js';
+import { type CallSummary } from './calls.js';
+import { MAX_CALLS_IN_FLIGHT, type GuestError, type StopReason } from './protocol.js';
+/** A call's answer for the guest: `ok` resolves its promise with the parsed JSON, otherwise rejects with it. */
+export interface CallAnswer {
+    ok: boolean;
+    json: string;
+}
+/** A tool call's answer from the bridge. */
+export interface ToolAnswer extends CallAnswer {
+    /** The result was marked as an error. */
+    isError?: boolean;
+    /** The start of what the tool answered, as an agent would read it, for naming a call the script stopped waiting for. */
+    brief?: string;
+    /**
+     * No result came from the host in time, so the bridge answered for it: the
+     * tool may still be running, holding its work, or its result was lost, and
+     * the host can't tell which. Its place stays taken until the run ends.
+     */
+    held?: boolean;
+}
+/** How a script ended. */
+export type Ending = {
+    how: 'finished';
+    value?: string;
+} | {
+    how: 'failed';
+    error: GuestError;
+    stalled?: boolean;
+}
+/** `short` when the child had to be ended, so its output so far may be short. */
+ | {
+    how: 'stopped';
+    reason: StopReason;
+    short?: boolean;
+    why?: string;
+} | {
+    how: 'crashed';
+    detail: string;
+};
+/** A run as it stands: its output since the last return, its calls, and its ending once it has one. */
+export interface RunSnapshot {
+    output: string;
+    calls: CallSummary;
+    ending: Ending | null;
+}
+/** How many script children a host runs at once, counted until each child's process has exited. */
+export declare class ChildCapacity {
+    readonly max: number;
+    private live;
+    constructor(max: number);
+    get running(): number;
+    /** Take a place, or false when the host is full. */
+    take(): boolean;
+    release(): void;
+}
+/**
+ * The child's entry, beside this module and with its extension: `.ts` where
+ * the host runs this package's source, as a Bun host does through the
+ * package's `bun` export, and `.js` where it runs the build. So the runtime
+ * is given a file that exists: given a `.js` path that it maps to the `.ts`
+ * beside it, Bun runs it as `bun run` would, with npm_* variables and a PATH
+ * of its own in the child's environment.
+ */
+export declare const CHILD_ENTRY: string;
+export interface ScriptRunOptions {
+    /** The child's entry: a script the runtime runs as the child process (CHILD_ENTRY, but for tests). */
+    childEntry: string;
+    /** Arguments after the entry, if any. */
+    childArgs?: readonly string[];
+    /** The runtime to run it with: by default the parent's own. */
+    execPath?: string;
+    memoryMaxBytes: number;
+    maxStackBytes?: number;
+    output: OutputBounds;
+    /** How often, at most, the child flushes output while its guest computes. */
+    flushMs: number;
+    /** The script's limit: at this age it's stopped, as "stopped at its limit". */
+    lifetimeMs: number;
+    /** How long a call may go unanswered before the script is told it timed out. */
+    toolCallTimeoutMs: number;
+    /** How long a stopped child has to report its ending before it's ended. */
+    stopGraceMs: number;
+    /** The least time between two of the script's wakes: an early one waits for its turn. */
+    wakeMinIntervalMs: number;
+    /** The most wakes one script may send; past it, a wake is refused. */
+    maxWakes: number;
+    /** The bridge: dispatch one tool call. Never rejects; a refusal is `ok: false`. */
+    onToolCall(name: string, argsJson: string): Promise<ToolAnswer>;
+    /** Send `wake_agent(payload)`, the script's `n`th wake, once its turn has come: answers the guest's promise. */
+    onWake(payloadJson: string, n: number): Promise<CallAnswer>;
+    /** Called once, when the run has an ending. */
+    onEnd?(ending: Ending): void;
+}
+export { MAX_CALLS_IN_FLIGHT };
+/**
+ * The largest result the parent sends a script: a third of its linear memory,
+ * since parsing one takes about three times its size there (a heap run under
+ * Bun 1.4.3 and Node 24.19.0). A larger one would fail in the guest anyway,
+ * after growing the child past its budget, so it's refused before it's sent,
+ * and the script's ResultTooLarge says the call took effect.
+ */
+export declare function maxResultBytes(memoryMaxBytes: number): number;
+export declare class ScriptRun {
+    private readonly options;
+    private child;
+    private dir;
+    private readonly output;
+    private readonly log;
+    /** The ids of the guest's calls the child named, reserved until it says the script has their answer. */
+    private readonly pendingIds;
+    /** The calls answered and not yet seen: only these may the child say the script has. */
+    private readonly answeredIds;
+    /** The script's tools, the only names its calls may have. */
+    private toolNames;
+    /** Results sent to the guest and not yet seen: each is counted once the child says the script has it, and whether it fit. */
+    private readonly delivered;
+    private ending;
+    private readonly waiters;
+    private stderr;
+    private lifetimeTimer;
+    private killTimer;
+    private processExited;
+    private stopAsked;
+    /** Each unanswered call's timeout, cleared when it's answered or the run ends. */
+    private readonly callTimers;
+    /** The calls holding a place among those in flight, by id, until the child says the script has their answer. */
+    private readonly inFlight;
+    /**
+     * How many calls the bridge holds, until it answers each: a call that timed
+     * out in the script, and so left its place there, may still hold its
+     * arguments in the host. Counted, not keyed by id, since the child may name
+     * a timed-out call's id again once the script has seen its TimeoutError.
+     * At most MAX_CALLS_IN_FLIGHT; a call past them waits in `dispatchWaiting`,
+     * as its text, until one is answered. One the bridge answered for (`held`)
+     * keeps its place until the run ends.
+     */
+    private hostCalls;
+    /** Calls waiting for the bridge to hold fewer: each resolved with true when its turn comes, false when it won't be sent. */
+    private readonly dispatchWaiting;
+    /** Wakes the child has sent, which the cap counts: those refused once a stop was asked included, so a child that ignores the stop is still bounded. */
+    private wakeFrames;
+    /** Wakes handed to the host to deliver, whatever it answered: a wake's number, which the host is given. */
+    private wakes;
+    /** Wakes the host delivered, its answer neither a refusal nor a failure. */
+    private delivered_wakes;
+    /** Wakes waiting for their turn, which the run's end counts as never sent. */
+    private wakesWaiting;
+    /** When the next wake may go out, on the monotonic clock: the spacing counts from when the last wake's delivery ended. */
+    private nextWakeAt;
+    /** Settles once the latest wake has gone out, or won't: wakes go out in the order they were made. */
+    private wakeChain;
+    /** Wakes waiting out the spacing, each released at its time or when the run ends. */
+    private readonly wakeWaiters;
+    /**
+     * Results waiting for the child's stdin to drain, as their frames: each holds
+     * its JSON's bytes, which the result bound counts. A result's id becomes one
+     * the child may say it has seen once its frame is written.
+     */
+    private readonly resultQueue;
+    private draining;
+    private exitResolve;
+    private endedResolve;
+    /** Resolves when the run ends: a wake waiting behind another's delivery stops waiting then. */
+    private readonly endedSignal;
+    /** Resolves when the child's process has exited, or at once if it never started. */
+    readonly exited: Promise<void>;
+    constructor(options: ScriptRunOptions);
+    /**
+     * Spawn the child and send it the script. A start frame too long for a frame
+     * throws before anything is spawned, with `exited` resolved, so nothing is
+     * left running and the place it took frees at once. A child that can't be
+     * spawned crashes the run.
+     */
+    start(script: string, tools: readonly PreludeTool[]): void;
+    /** The run as it stands, its output since the last return included. */
+    snapshot(): RunSnapshot;
+    /** The output since the last return, as it stands. */
+    outputWindow(): OutputWindow;
+    /** The output since the last return, starting a fresh stretch from here. */
+    takeOutput(): OutputWindow;
+    get ended(): boolean;
+    /** End the child's process now if it's still alive, whatever the run's state. Resolves once it has exited. */
+    kill(): Promise<void>;
+    /** The wakes the host delivered to the script's agent: those it answered ok and not as an error. A refused wake isn't one, nor a failed one, though a failure may have taken effect. */
+    get wakesDelivered(): number;
+    /** Resolves when the script has ended, or after `ms`, whichever comes first. */
+    wait(ms: number): Promise<RunSnapshot>;
+    /**
+     * Ask the script to stop: the stop file for a computing guest, a frame for an
+     * idle one. If the child hasn't said how it ended within the grace, it's
+     * ended, and the ending says its output so far may be short. The reason is
+     * the one asked here, whatever the child says.
+     */
+    stop(reason: StopReason, why?: string): Promise<RunSnapshot>;
+    private send;
+    /** A call's result, as a result frame once its turn comes: the JSON's bytes go to the engine as they are. */
+    private sendResult;
+    /** Write waiting results, one frame at a time: after a write the pipe didn't take whole, the next waits for 'drain'. */
+    private pump;
+    private write;
+    private handle;
+    private call;
+    /**
+     * A call no longer holds a place in the host: the bridge answered it, or it
+     * won't be sent. The first call waiting for room takes the place, in the
+     * same step, so no later call can take it first. Whatever lets a waiting
+     * call go takes it off the queue. One given its place once the run has
+     * ended or its process has exited isn't sent (the call's own check), and
+     * the end lets the calls still waiting go.
+     */
+    private releasePlace;
+    /** An answer to the call the child named `id`, sent once its turn comes. The id stays reserved until the child says the script has it. */
+    private answer;
+    /** A call or wake that comes once a stop has been asked isn't sent: the script is ending. */
+    private stopRefusal;
+    /** Resolves once the spacing since the last wake has passed, or at once when the run has ended. */
+    private wakeTurn;
+    /**
+     * Once the process has exited and the run has ended, nothing more goes to
+     * the child: an ended run kept for a later wait holds none of it. Whichever
+     * of the two comes second calls this.
+     */
+    private release;
+    private crash;
+    private end;
+}
+//# sourceMappingURL=runner.d.ts.map

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

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