/**
 * `codeExecutionTool` — an `AIToolDefinition` that runs model-generated
 * JavaScript inside an `@absolutejs/isolated-jsc` sandbox.
 *
 * Drop into any `tools: {...}` map:
 *
 * ```ts
 * import { codeExecutionTool } from '@absolutejs/ai/tools';
 *
 * const tools = {
 *   run_code: codeExecutionTool({
 *     memoryLimit: 64,
 *     timeout: 1000,
 *     expose: {
 *       lookup_user: async (id) => db.users.findById(id as string),
 *       round: (n) => Math.round(n as number),
 *     },
 *   }),
 * };
 * ```
 *
 * The model emits `{ code: '<JS source>' }` as the tool input; the host
 * runs the code in a fresh context inside a pooled isolate and returns
 * a JSON-stringified result containing:
 *
 *   - `result` — the script's return value (JSON-clonable).
 *   - `log` — array of strings captured via the host-injected `log(...)`.
 *   - `error` — error message + name if the script threw or timed out.
 *   - `cpuMs`, `heapBytes` — per-call telemetry (Phase 3 docs / monitoring).
 *
 * Defaults to the FFI backend on macOS + Linux (with libJSC installed),
 * Worker fallback elsewhere. Per-isolate pool is created once per
 * `codeExecutionTool()` call; pool key is `'default'` (one isolate for
 * all calls). For per-tenant isolation, create one tool instance per
 * tenant.
 *
 * Constraint: when using the FFI backend, **exposed host fns must be
 * synchronous**. Async host fns (returning a Promise that doesn't settle
 * synchronously — `fetch`, `setTimeout`-resolved Promises, real I/O)
 * require `backend: 'worker'` per isolated-jsc 0.3 documented limit.
 * Set `backend: 'worker'` in the tool options if any of your `expose`d
 * fns are async-settling.
 */
import type { AIToolDefinition } from "../../../types/ai";
/** Options for {@link codeExecutionTool}. */
export type CodeExecutionToolOptions = {
    /**
     * Per-isolate heap memory cap (MB). Default 64. Note that the
     * sandbox's cold-start baseline differs by backend (FFI ~300 KB vs
     * Worker ~46 MB), so the practical floor for Worker is ~64 MB.
     */
    memoryLimit?: number;
    /** Wall-clock timeout per `run_code` call (ms). Default 1000. */
    timeout?: number;
    /**
     * isolated-jsc backend. Default `"auto"` (FFI when reachable, Worker
     * otherwise). Set to `"worker"` if your `expose`d fns are async-settling
     * — the FFI backend only supports sync host fns (see Reference docs).
     */
    backend?: "auto" | "ffi" | "worker";
    /**
     * Host functions the model can call from inside the sandbox. Names
     * become globals; the model invokes them with `await name(...)`.
     * The function's description (`.toString()` first line, if a doc
     * comment) is included in the tool's description so the model knows
     * what's available.
     */
    expose?: Record<string, (...args: unknown[]) => unknown>;
    /**
     * Override the tool's description string. Default is auto-generated
     * from the exposed function list.
     */
    description?: string;
    /**
     * Pool size cap — max concurrent isolates across all parallel tool
     * calls. Default 8.
     */
    poolSize?: number;
    /**
     * Recycle the isolate after N successful runs to bound per-context
     * heap creep. Default 50.
     */
    recycleAfter?: number;
};
export declare const codeExecutionTool: (options?: CodeExecutionToolOptions) => AIToolDefinition;