eve/dist/src/public/sandbox/just-bash-sandbox.d.ts

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

import type { CustomCommand, IFileSystem } from "just-bash";
import type { SandboxSession } from "#shared/sandbox-session.js";
/**
 * Context passed to a custom just-bash filesystem factory for each live handle.
 */
export interface JustBashFilesystemContext {
    /** Resolves an application-relative path without exposing project layout. */
    resolveProjectPath(path: string): string;
    /** Stable provider-private storage directory for this sandbox. */
    readonly storagePath: string;
    /** eve's durable, session-owned filesystem, including `/workspace`. */
    readonly defaultFilesystem: IFileSystem;
    /** The just-bash engine resolved by eve after its optional installation check. */
    readonly justBash: typeof import("just-bash");
}
/**
 * Options accepted by just-bash environment constructors.
 *
 * The just-bash provider runs the workspace under the pure-JS `just-bash`
 * interpreter with a virtual filesystem — no daemon or VM required, but
 * no real binaries either. The `just-bash` package is not bundled with
 * eve; it is loaded lazily from the application install.
 */
export interface JustBashSandboxCreateOptions {
    /**
     * When the `just-bash` package is missing from the application,
     * install it automatically with the project's package manager. Only
     * runs during `eve dev`; production processes always fail with an
     * actionable install error instead. Defaults to `true`.
     */
    readonly autoInstall?: boolean;
    /**
     * Registers trusted host application code as commands in each live
     * just-bash interpreter. Custom commands can participate in normal shell
     * composition, including pipelines and redirections.
     *
     * Custom commands are not available during environment preparation. They run in
     * eve's host process, outside the virtual filesystem security boundary, and
     * are responsible for validating their own inputs and cleaning up host
     * resources.
     */
    readonly customCommands?: ReadonlyArray<CustomCommand>;
    /**
     * Composes the filesystem used by each live sandbox handle. The factory is
     * called when a handle opens with eve's durable default filesystem; return a
     * fresh filesystem that preserves eve-owned paths such as `/workspace`,
     * `/tmp`, and the home directory.
     *
     * This just-bash-specific escape hatch requires the application to install
     * a compatible `just-bash` version. It is not invoked during template
     * preparation.
     */
    readonly filesystem?: (context: JustBashFilesystemContext) => IFileSystem | Promise<IFileSystem>;
    /** Idempotent setup captured in the prepared virtual filesystem. */
    readonly prepare?: (sandbox: SandboxSession) => Promise<void> | void;
}