@animalabs/agent-framework 0.23.2 → 0.24.0

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

@@ -1,191 +0,0 @@
-/**
- * PyRunner — subprocess lifecycle + protocol driver for the client-side
- * programmatic tool calling (`code_execution`) runtime.
- *
- * One runner per agent. The interpreter is spawned lazily on first exec,
- * persists between execs (script globals survive — container-reuse
- * semantics), and is reclaimed after an idle period, mirroring the managed
- * runtime's ~5-minute container reclaim.
- *
- * This is a ROBUSTNESS boundary, not a security sandbox — same doctrine as
- * GateScript: the agent already has broader host access through its tools.
- * What this class guarantees is liveness: a wedged or runaway script cannot
- * hang the agent turn (cancel + SIGINT -> grace -> SIGKILL -> respawn) and a crashed
- * interpreter surfaces as a tool result, never as an unhandled rejection.
- */
-export interface InjectedTool {
-    /** Python identifier the tool is bound to (sanitized, `--` -> `__`). */
-    pyName: string;
-    /** Exact framework tool name, sent back on tool_call ops. */
-    toolName: string;
-}
-export interface ExecResult {
-    stdout: string;
-    stderr: string;
-    returnCode: number;
-    /** Set when the host killed the script (deadline / abort / crash). */
-    aborted?: boolean;
-    /** Background execs: rolling tail of interleaved stdout+stderr (for the
-     *  crash/finish envelope; the full journal is in the log file). */
-    tail?: string;
-}
-/** Per-exec options for background (daemon) scripts. */
-export interface BackgroundExecOptions {
-    /** Absolute path for the line-buffered stdout+stderr journal (null: tail only). */
-    logPath: string | null;
-    /**
-     * Called on each wake_agent() from the script. Resolve with null to ack
-     * (deliver), or an error string to refuse (raises RuntimeError in-script).
-     * May resolve late — rate limiting backpressures inside wake_agent().
-     */
-    onWake: (line: number, payload: unknown) => Promise<string | null>;
-    /** Overrides the runner's scriptTimeoutMs (background lifetime). */
-    lifetimeMs: number;
-}
-/**
- * An inner tool call's result as the script gets it. `text` is the string
- * its await returns, and the runner sets `.is_error` on that string from
- * `isError`. With `structuredJson`, `text` is the JSON object a structured
- * result reaches a script as, in any of its forms, and `.structured` reads
- * its `structuredContent`, None for a form that holds none, such as one past
- * the size cap; without it, `.structured` is None.
- */
-export interface ScriptToolResult {
-    text: string;
-    isError: boolean;
-    structuredJson?: boolean;
-}
-/**
- * Resolves inner tool calls. Must never reject — map errors to results; a
- * rejection reaches the script as an `Error: …` result. A plain string is
- * the result's text with nothing said about it, so the script's
- * `.is_error` and `.structured` are None.
- */
-export type ScriptToolCallHandler = (toolName: string, args: Record<string, unknown>) => Promise<string | ScriptToolResult>;
-export interface PyRunnerOptions {
-    pythonPath?: string;
-    /** Per-tool-call timeout surfaced as TimeoutError inside the script. */
-    toolCallTimeoutMs?: number;
-    /** Whole-script deadline; exceeded -> cancel, grace, kill. */
-    scriptTimeoutMs?: number;
-    /** How long a script gets to stop after its deadline before the interpreter is killed (default 10s). */
-    cancelGraceMs?: number;
-    /** Idle interpreter reclaim (state lost), mirroring container reclaim. */
-    idleReclaimMs?: number;
-    onToolCall: ScriptToolCallHandler;
-    /** Log prefix, typically the agent name. */
-    label?: string;
-    /** Variables for the interpreter beyond what it inherits, such as
-     *  PYTHONPATH or a venv's. It inherits only what stdio MCPL children do
-     *  (CHILD_ENV_ALLOWLIST and LC_*, CA bundles and proxy variables among
-     *  them, and a proxy URL can carry credentials), then these, then
-     *  PYTHONUNBUFFERED and PYTHONIOENCODING, which the runner sets last.
-     *  Like the allowlist, this limits what the model's code inherits, not
-     *  what a process running as the same user can read. */
-    env?: Record<string, string>;
-    /** Pass the host's whole environment instead of the allowlist, as before
-     *  `env` existed. That hands every host variable, provider keys included,
-     *  to the model's code and to every subprocess a script starts; listing
-     *  what scripts need in `env` is the safer route. */
-    inheritEnv?: boolean;
-}
-/** The longest delay Node's timers honour (~24.8 days); a longer one fires after ~1 ms. */
-export declare const MAX_TIMER_MS = 2147483647;
-/** A time limit for a message: "45s", "10 min", "2.5 h". */
-export declare function formatLimit(ms: number): string;
-export declare class PyRunner {
-    private readonly pythonPath;
-    private readonly toolCallTimeoutMs;
-    private readonly scriptTimeoutMs;
-    private readonly cancelGraceMs;
-    private readonly idleReclaimMs;
-    private readonly onToolCall;
-    private readonly label;
-    private readonly envOptions;
-    private onWake;
-    private child;
-    private childReady;
-    private reader;
-    private runtimeDir;
-    private pending;
-    private idleTimer;
-    private execCounter;
-    private disposed;
-    constructor(options: PyRunnerOptions);
-    get busy(): boolean;
-    /**
-     * Run one script. Tools are (re-)injected before every exec so the
-     * interpreter always reflects the current tool surface (list_changed etc.).
-     * Never rejects: every failure mode resolves to an ExecResult.
-     *
-     * With `background` options the exec is a daemon: output journals to the
-     * log file, wake_agent() is available in-script, and the deadline is the
-     * background lifetime. A background runner should be DEDICATED to that one
-     * script (the framework creates one per background script).
-     *
-     * `opts.deadlineMs` replaces the runner's scriptTimeoutMs for this exec (a
-     * per-call time limit); a background exec uses its `lifetimeMs` instead.
-     * `opts.ceilingMs` is the longest limit the deployment allows this kind of
-     * script: a script stopped at its limit is offered a longer one only below
-     * it. Without it, the stop doesn't say whether a longer limit would help.
-     * `opts.backgroundCeilingMs`, for a foreground exec, is the longest a
-     * background script may run: one stopped at its ceiling is offered
-     * background mode when that is longer.
-     */
-    exec(code: string, tools: InjectedTool[], background?: BackgroundExecOptions, opts?: {
-        deadlineMs?: number;
-        ceilingMs?: number;
-        backgroundCeilingMs?: number;
-    }): Promise<ExecResult>;
-    /**
-     * Abort the runner's script (its turn ended or is reset to run again, or the
-     * agent was reset or stopped), whether it's running or still waiting for its
-     * interpreter to start; a waiting script then never runs. The exec settles
-     * at once, and the interpreter is reclaimed, a starting one too: after an
-     * abort its state is suspect (a script died midway), and the next exec gets
-     * a fresh one.
-     */
-    abort(reason: string): void;
-    dispose(): void;
-    private ensureChild;
-    private readyResolver;
-    /** Fails the readiness of an interpreter that is still starting (see reclaim). */
-    private readyFailer;
-    private handleLine;
-    private settlePending;
-    /**
-     * Answer the interpreter that asked. Call and wake ids restart in every
-     * interpreter, so an answer that outlives its interpreter (the script was
-     * aborted, killed or crashed, or the interpreter reclaimed) would resolve
-     * the same id in the one that replaced it, inside another script: drop it.
-     */
-    private reply;
-    private send;
-    /**
-     * SIGINT the interpreter: blocking code in the running script raises
-     * KeyboardInterrupt. Not on Windows, where Node's kill() ends the process
-     * outright; there the cancel op and the kill grace remain.
-     * process.kill rather than child.kill, which would mark the child `killed`:
-     * a killed child gets no more protocol messages and is respawned on the
-     * next exec, losing the interpreter state this keeps.
-     */
-    private interruptChild;
-    /** Kill interpreter + clean temp dir. State is lost (by design). */
-    private reclaim;
-    private teardownChild;
-    private armIdleTimer;
-    private clearIdleTimer;
-}
-/**
- * Map framework tool names to python identifiers: `--` (the framework's
- * prefix separator) becomes `__`, and every remaining character that is not
- * valid in a python identifier becomes `_` (fleet reality: module and server
- * ids contain single hyphens — `mcpl-admin`, `dog-events` — found live on
- * the first canary run, 2026-07-26). A leading digit gets a `_` prefix.
- *
- * Names that sanitize to nothing, or that collide after sanitization, are
- * skipped loudly — a skipped tool is unreachable from scripts (the
- * exact-name tools[...] dict is built from this same list).
- */
-export declare function buildInjectedTools(toolNames: string[], log?: (message: string) => void): InjectedTool[];
-//# sourceMappingURL=py-runner.d.ts.map

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

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