/**
 * Workspace Sandbox Interface
 *
 * Defines the contract for sandbox providers that can be used with Workspace.
 * Users pass sandbox provider instances to the Workspace constructor.
 *
 * Sandboxes provide isolated environments for code and command execution.
 * They may have their own filesystem that's separate from the workspace FS.
 *
 * Built-in providers (via ComputeSDK):
 * - E2B: Cloud sandboxes
 * - Modal: GPU-enabled sandboxes
 * - Docker: Container-based execution
 * - Local: Development-only local execution
 *
 * @example
 * ```typescript
 * import { Workspace } from '@mastra/core';
 * import { ComputeSDKSandbox } from '@mastra/workspace-sandbox-computesdk';
 *
 * const workspace = new Workspace({
 *   sandbox: new ComputeSDKSandbox({ provider: 'e2b' }),
 * });
 * ```
 */
import type { RequestContext } from '../../request-context/index.js';
import type { WorkspaceFilesystem } from '../filesystem/filesystem.js';
import type { MountResult } from '../filesystem/mount.js';
import type { SandboxLifecycle } from '../lifecycle.js';
import type { MountManager } from './mount-manager.js';
import type { SandboxProcessManager } from './process-manager/index.js';
import type { CommandResult, ExecuteCommandOptions, SandboxInfo } from './types.js';
/**
 * Optional networking capability for sandboxes that can expose ports publicly.
 *
 * Providers that support public port exposure (Vercel Sandbox, E2B, Daytona,
 * Modal, Blaxel, etc.) implement this to surface public URLs through the
 * abstraction. Enables preview URLs and sandbox deploys.
 */
export interface SandboxNetworking {
    /**
     * Get the public URL for an exposed port.
     *
     * @param port - The port number inside the sandbox
     * @returns The public URL for the port, or null if the port is not exposed
     *   or the sandbox is not running
     */
    getPortUrl(port: number): Promise<string | null>;
}
/** A file to write into the sandbox filesystem via {@link WorkspaceSandbox.writeFiles}. */
export interface SandboxFileInput {
    /** Destination path inside the sandbox */
    path: string;
    /** File contents */
    content: string | Buffer;
}
/**
 * Type guard: does this sandbox support the networking capability?
 *
 * @example
 * ```typescript
 * if (supportsNetworking(sandbox)) {
 *   const url = await sandbox.networking.getPortUrl(4111);
 * }
 * ```
 */
export declare function supportsNetworking(sandbox: WorkspaceSandbox): sandbox is WorkspaceSandbox & {
    networking: SandboxNetworking;
};
/**
 * Options for cloning a configured sandbox's configuration into an independent
 * sibling sandbox. See {@link WorkspaceSandbox.clone}.
 */
export interface SandboxCloneOptions {
    /** Unique identifier for the sandbox clone instance. */
    id?: string;
    /**
     * Reattach to an existing provider sandbox (by the provider's own id)
     * instead of provisioning a new one.
     */
    sandboxId?: string;
    /** Environment variables baked into the sandbox clone. */
    env?: Record<string, string>;
    /** Provider working directory for the sandbox clone. */
    workingDirectory?: string;
    /** Idle teardown window (minutes) for the sandbox clone. */
    idleTimeoutMinutes?: number;
    /**
     * Provider checkpoint used to seed and preserve the sandbox clone.
     * Providers without checkpoint support may ignore this option.
     */
    checkpointName?: string;
}
/**
 * Abstract sandbox interface for code and command execution.
 *
 * Providers implement this interface to provide execution capabilities.
 * Users instantiate providers and pass them to the Workspace constructor.
 *
 * Sandboxes provide isolated environments for running untrusted code.
 * They may have their own filesystem that's separate from the workspace FS.
 *
 * Lifecycle methods (from SandboxLifecycle interface) are all optional:
 * - start(): Begin operation (spin up instance)
 * - stop(): Pause operation (pause instance)
 * - destroy(): Clean up resources (terminate instance)
 * - isReady(): Check if ready for operations
 * - getInfo(): Get status and metadata
 */
export interface WorkspaceSandbox extends SandboxLifecycle<SandboxInfo> {
    /** Unique identifier for this sandbox instance */
    readonly id: string;
    /** Human-readable name (e.g., 'E2B Sandbox', 'Docker') */
    readonly name: string;
    /** Provider type identifier */
    readonly provider: string;
    /**
     * Get instructions describing how this sandbox works.
     * Used in tool descriptions to help agents understand execution context.
     *
     * @param opts - Optional options including request context for per-request customisation
     * @returns A string describing how to use this sandbox
     */
    getInstructions?(opts?: {
        requestContext?: RequestContext;
    }): string;
    /**
     * Construct an independent sibling sandbox that inherits this sandbox's
     * configuration (credentials, provider settings, defaults) with
     * per-instance overrides.
     *
     * Performs no I/O — the sandbox clone provisions (or reattaches, when
     * `sandboxId` is set) on its own `start()`. Implement this when one
     * configured sandbox should act as the template for a fleet of independent
     * sandboxes (e.g. one per project).
     *
     * Optional — consumers that need fleets (like the MastraCode web factory)
     * only support sandboxes that implement it.
     */
    clone?(options?: SandboxCloneOptions): WorkspaceSandbox;
    /**
     * Execute a shell command and wait for it to complete.
     * Optional - if not implemented, the workspace_execute_command tool won't be available.
     *
     * @example
     * ```typescript
     * await sandbox.executeCommand('npm install');
     *
     * // With options
     * await sandbox.executeCommand('npm install', [], { timeout: 60000 });
     *
     * // With args array (each arg is shell-quoted automatically)
     * await sandbox.executeCommand('npm', ['install'], { timeout: 60000 });
     * ```
     *
     * @throws {SandboxExecutionError} if command fails to start
     * @throws {SandboxTimeoutError} if command times out
     */
    executeCommand?(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<CommandResult>;
    /**
     * Networking capability for sandboxes that can expose ports publicly.
     * Optional - only available on providers that support public port exposure.
     * Enables preview URLs and sandbox deploys.
     *
     * @example
     * ```typescript
     * const url = await sandbox.networking?.getPortUrl(4111);
     * ```
     */
    readonly networking?: SandboxNetworking;
    /**
     * Bulk-write files into the sandbox's own filesystem.
     * Optional fast path - providers with a native file-upload API implement this.
     * Callers should fall back to `executeCommand` when unavailable.
     *
     * @example
     * ```typescript
     * await sandbox.writeFiles?.([{ path: '/app/index.mjs', content: bundle }]);
     * ```
     */
    writeFiles?(files: SandboxFileInput[]): Promise<void>;
    /**
     * Process manager.
     * Optional - if not implemented, process management tools won't be available.
     *
     * Provides methods to spawn long-running processes, list them, and interact
     * with them via their {@link ProcessHandle} (kill, sendStdin, wait, read output).
     *
     * @example
     * ```typescript
     * const handle = await sandbox.processes.spawn('node server.js');
     * console.log(handle.pid);
     *
     * const procs = await sandbox.processes.list();
     * const proc = await sandbox.processes.get(handle.pid);
     * await proc?.sendStdin('hello\n');
     * await proc?.kill();
     * ```
     */
    readonly processes?: SandboxProcessManager;
    /**
     * Mount manager for tracking and processing filesystem mounts.
     * Only available if the sandbox implements mount().
     *
     * @example
     * ```typescript
     * // Add pending mounts
     * sandbox.mounts?.add({ '/data': s3fs });
     *
     * // Check mount entries
     * const entries = sandbox.mounts?.entries;
     * ```
     */
    readonly mounts?: MountManager;
    /**
     * Mount a filesystem at a path in the sandbox.
     * Uses FUSE tools (s3fs, gcsfuse) to mount cloud storage.
     *
     * @param filesystem - The filesystem to mount
     * @param mountPath - Path in the sandbox where filesystem should be mounted
     * @returns Mount result with success status and mount path
     * @throws {MountError} if mount fails
     * @throws {MountNotSupportedError} if sandbox doesn't support mounting
     * @throws {FilesystemNotMountableError} if filesystem cannot be mounted
     */
    mount?(filesystem: WorkspaceFilesystem, mountPath: string): Promise<MountResult>;
    /**
     * Unmount a filesystem from a path in the sandbox.
     *
     * @param mountPath - Path to unmount
     */
    unmount?(mountPath: string): Promise<void>;
}
//# sourceMappingURL=sandbox.d.ts.map