import { RemoteRuntime, type RemoteHealth } from "./client.js";
export interface SandboxLimits {
    cpus?: number;
    memoryBytes?: number;
    pids?: number;
}
/** A template is an image plus an optional workspace archive in the kernel's portable format. */
export interface SandboxTemplate {
    image?: string;
    workspace?: Uint8Array;
}
export interface ProviderStartSpec {
    id: string;
    token: string;
    image?: string;
    limits?: SandboxLimits;
    volume?: string;
}
/** What a provider returns for a started sandbox; `name` is the provider's own handle. */
export interface ProviderStarted {
    name: string;
    url: string;
}
/** What provider pause means for live processes. Workspace snapshots never include them. */
export type SandboxPauseMode = "freeze-processes" | "restart-processes";
/** The four calls every backend implements, plus optional volume and shutdown hooks. */
export interface SandboxProvider {
    readonly pauseMode: SandboxPauseMode;
    start(spec: ProviderStartSpec): Promise<ProviderStarted> | ProviderStarted;
    pause(started: ProviderStarted): Promise<void> | void;
    /** May return a new address when the backend brings the sandbox back elsewhere. */
    resume(started: ProviderStarted): Promise<{
        url?: string;
    } | void> | {
        url?: string;
    } | void;
    stop(started: ProviderStarted): Promise<void> | void;
    running(): Promise<Set<string>> | Set<string>;
    removeVolume?(volume: string): Promise<void> | void;
    close?(): void;
}
export interface Sandbox {
    readonly id: string;
    readonly token: string;
    readonly url: string;
    readonly runtime: RemoteRuntime;
    readonly idleTimeoutMs: number;
    readonly createdAt: number;
    readonly template: SandboxTemplate;
    readonly limits: SandboxLimits | undefined;
    readonly volume: string | undefined;
    readonly pauseMode: SandboxPauseMode;
    state: "running" | "paused" | "killed";
    pause(): Promise<void>;
    resume(): Promise<void>;
    kill(): Promise<void>;
    health(): Promise<RemoteHealth>;
}
/** A portable workspace checkpoint. Process and engine memory are deliberately excluded. */
export interface SandboxWorkspaceSnapshot {
    kind: "substrate-workspace";
    version: 1;
    sourceSandboxId: string;
    createdAt: number;
    processState: "excluded";
    format: "tar";
    bytes: Uint8Array;
    integrity: string;
    entries: number;
    fileBytes: number;
}
export interface SandboxManagerOptions {
    provider: SandboxProvider;
    idleTimeoutMs?: number;
    reapEveryMs?: number;
    /** How long a new or resumed sandbox may take to answer; a loaded host needs more. */
    healthTimeoutMs?: number;
}
export interface CreateSandboxOptions {
    idleTimeoutMs?: number;
    template?: SandboxTemplate;
    limits?: SandboxLimits;
    volume?: string;
}
/** One agent is one sandbox; the manager creates them through a provider and reaps idle ones. */
export declare class SandboxManager {
    readonly idleTimeoutMs: number;
    readonly healthTimeoutMs: number;
    private readonly provider;
    private readonly sandboxes;
    private readonly reaper;
    constructor({ provider, idleTimeoutMs, reapEveryMs, healthTimeoutMs }: SandboxManagerOptions);
    create({ idleTimeoutMs, template, limits, volume }?: CreateSandboxOptions): Promise<Sandbox>;
    /** Captures the portable workspace boundary. Running processes are never represented. */
    snapshot(id: string): Promise<SandboxWorkspaceSnapshot>;
    /** Creates a new sandbox from a portable workspace snapshot. */
    restore(snapshot: SandboxWorkspaceSnapshot, options?: Omit<CreateSandboxOptions, "template">): Promise<Sandbox>;
    /** A new sandbox seeded with a running sandbox's workspace: "fork this artifact". */
    fork(id: string, options?: Omit<CreateSandboxOptions, "template">): Promise<Sandbox>;
    get(id: string): Sandbox | undefined;
    list(): Array<{
        id: string;
        state: Sandbox["state"];
        createdAt: number;
        url: string;
        pauseMode: SandboxPauseMode;
    }>;
    /** Kills running sandboxes whose agent reports no activity within their idle timeout. */
    reap(): Promise<void>;
    close(): Promise<void>;
}
//# sourceMappingURL=manager.d.ts.map