eve/dist/src/harness/sandbox-surface.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import type { ToolSet } from "ai";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
/**
 * A model-facing code-execution sandbox over a *subset* of the agent's tools.
 *
 * `code_mode` and `Workflow` are two instances of this one concept: each is a
 * QuickJS sandbox the model drives by writing JavaScript, differing only in
 * which tools it exposes and how it presents itself. Modeling them as surfaces
 * (rather than parallel boolean branches) keeps the partition uniform and makes
 * a third sandbox a one-line addition.
 */
export interface SandboxSurface {
    /** Reserved model-facing tool name (e.g. `"code_mode"`, `"Workflow"`). */
    readonly toolName: string;
    /**
     * Whether this surface wraps the given tool into its sandbox. A tool enters
     * *every* active surface that claims it, so an agent tool — claimed by both
     * surfaces — is callable from either sandbox when both are enabled.
     */
    readonly claims: (harnessTool: HarnessToolDefinition | undefined, tool: ToolSet[string]) => boolean;
    /**
     * Optional transform applied to the description auto-generated by
     * `createCodeModeTool`. Receives the generated text (which lists the callable
     * tool signatures) and the names of the tools in this sandbox, so the framing
     * can adapt to what is actually callable. Omit to use the generated
     * description as-is.
     */
    readonly describe?: (input: {
        readonly generated: string;
        readonly toolNames: readonly string[];
    }) => string;
}
/**
 * The `Workflow` sandbox: agents only. Its sole callable operations are the
 * agent's subagents and remote agents, for orchestrating them from
 * model-authored JavaScript.
 */
export declare const WORKFLOW_SURFACE: SandboxSurface;
/**
 * The `code_mode` sandbox: every sandboxable tool — subagent/remote-agent
 * (`runtimeAction`) tools and ordinary executable host tools (bash, fs, web,
 * skills). Provider-managed tools with no executor are never sandboxed. This is
 * unchanged by whether `Workflow` is also enabled.
 */
export declare const CODE_MODE_SURFACE: SandboxSurface;
/**
 * Active sandbox surfaces for a harness config. A tool enters every surface
 * that claims it, so the two compose without interfering: `code_mode` is the
 * full sandbox (agents + host tools) regardless of `Workflow`, and `Workflow`
 * is an additional agents-only sandbox. When both are enabled, agents are
 * callable from either; other host tools remain only in `code_mode`. Order is
 * the emission order and does not affect routing.
 */
export declare function selectSandboxSurfaces(config: {
    readonly codeMode?: boolean;
    readonly workflow?: boolean;
}): SandboxSurface[];
/** Whether any sandbox surface is active — i.e. the model gets a sandbox tool. */
export declare function isSandboxEnabled(config: {
    readonly codeMode?: boolean;
    readonly workflow?: boolean;
}): boolean;
/**
 * Every known surface. Used on replay to rebuild the full sandbox tool set
 * without knowing which surface a pending interrupt came from — a script only
 * references its own tools, so the superset is safe.
 */
export declare const ALL_SANDBOX_SURFACES: readonly SandboxSurface[];