/** * Sandboxed code execution (Python parity: `Agent(sandbox=...)`, * `agent/sandbox_mixin.py` `SandboxMixin`, `sandbox/config.py`, * `sandbox/security.py`). * * `sandbox: true` gives the agent a subprocess sandbox; a config object names * a different one. Two things then become true of `agent.executeCode()`: * * 1. The code is analysed BEFORE it runs, and the warnings travel with the * result. Python's note applies here too -- the analysis is best-effort * static pattern matching for the operator's awareness; the sandbox is * what actually isolates. * 2. Without a sandbox configured (and no per-call `runIn`), the call fails * with an error that names both ways to fix it, rather than quietly * running the code in this process. * * The runner is an injectable interface. Only `subprocess` ships here; * `docker`, `e2b` and friends are provider integrations a host registers with * {@link registerSandboxRunner}, and naming one that is not registered fails * loudly instead of silently downgrading to local execution. */ /** Python `SandboxConfig` (the subset the Agent needs). */ export interface SandboxConfig { sandboxType: string; image: string; workingDir: string; /** Child variables; the host env is not inherited beyond {@link buildChildEnv}'s basics. */ env: Record; autoCleanup: boolean; persistFiles: boolean; /** Seconds a single execution may take. */ timeout: number; metadata: Record; } /** Python's `SandboxConfig` defaults (`sandbox/config.py`). */ export declare function defaultSandboxConfig(sandboxType?: string): SandboxConfig; /** Python `SecurityWarning`. */ export interface SecurityWarning { pattern: string; message: string; severity: 'low' | 'medium' | 'high' | 'critical'; lineNumber?: number; context?: string; } /** Python `SandboxResult` (the fields the Agent surfaces). */ export interface SandboxResult { success: boolean; stdout: string; stderr: string; exitCode: number; metadata?: Record; } /** Anything that can run code somewhere isolated. */ export interface SandboxRunner { readonly sandboxType: string; execute(code: string, options: { language: string; config: SandboxConfig; }): Promise; } /** * Static analysis of code about to be sandboxed (Python `check_code_safety`). * Warnings only: the sandbox provides the real isolation. */ export declare function checkCodeSafety(code: string, language?: string): SecurityWarning[]; /** Python `format_warnings`. */ export declare function formatWarnings(warnings: readonly SecurityWarning[]): string; /** * Resolve the constructor option. `true` selects the subprocess sandbox * (Python `SandboxConfig.subprocess()`), a string names the sandbox type, an * object supplies fields (snake_case accepted). */ export declare function resolveSandbox(input: boolean | string | Record | undefined | null): SandboxConfig | undefined; /** * Register a sandbox implementation for a `sandboxType`. `docker`, `e2b` and * the rest are provider integrations, so a host supplies them; naming an * unregistered type errors rather than downgrading to local execution. */ export declare function registerSandboxRunner(sandboxType: string, factory: (config: SandboxConfig) => SandboxRunner): void; /** Forget a sandbox runner registration. `subprocess` cannot be removed. */ export declare function unregisterSandboxRunner(sandboxType: string): boolean; /** Every registered sandbox type. */ export declare function sandboxRunnerNames(): string[]; /** * The built-in `subprocess` runner: the code goes to a temp file and runs in a * child process with the config's cwd, environment and timeout. Isolation is * process-level only -- that is exactly what Python's subprocess sandbox is, * and why the config carries `docker` as an option. */ export declare function createSubprocessRunner(config: SandboxConfig): SandboxRunner; /** Build the runner for a config, or throw naming what is registered. */ export declare function createSandboxRunner(config: SandboxConfig): SandboxRunner; /** Per-call options of `Agent.executeCode` (Python `execute_code`). */ export interface ExecuteCodeOptions { /** `python` (default), `bash`, `javascript`, ... */ language?: string; /** Run the static pre-check (default true). */ checkSecurity?: boolean; /** * Where to run THIS call: a sandbox type, a config object, or `true` for * the default subprocess sandbox. Overrides the agent's `sandbox`. */ runIn?: boolean | string | Record; } /** * Run `code` in a sandbox, exactly as Python's `Agent.execute_code` does: * resolve where it runs, analyse it first, execute, and attach the warnings * to the result rather than only logging them. * * Runners are cached per sandbox type in `runners`: building a fresh one per * call would start and tear down a container each time, which for Docker is * seconds of latency and for any backend loses the previous call's files. */ export declare function executeCodeInSandbox(params: { code: string; options?: ExecuteCodeOptions; /** The agent's own `sandbox` config, used when the call names no `runIn`. */ defaultConfig?: SandboxConfig; runners: Map; /** Used only to make the "no sandbox configured" error read naturally. */ agentName: string; onWarning?: (message: string) => void; }): Promise;