@anvia/sandbox 0.6.0 → 1.0.0-rc.10

package/dist/index.d.ts

@@ -1,307 +1,285 @@
 import { AnyTool } from '@anvia/core/tool';
 
-type SandboxFileType = "file" | "directory" | "symlink" | "other";
-type SandboxNetworkMode = boolean | "none" | "host" | string;
-type SandboxWorkspaceOptions = {
-    mode?: "ephemeral";
-} | {
-    mode: "persistent";
-    id: string;
-    destroyOnSessionDestroy?: boolean;
-};
-interface SandboxLifecycleOptions {
-    ttlMs?: number;
-    idleTimeoutMs?: number;
-    autoDestroy?: boolean;
-}
-interface Sandbox {
-    readonly provider: string;
-    createSession(options?: SandboxCreateSessionOptions): Promise<SandboxSession>;
-}
-interface SandboxSession {
-    readonly id: string;
-    readonly provider: string;
-    readonly workdir: string;
-    exec(options: SandboxExecOptions): Promise<SandboxExecResult>;
-    execStream(options: SandboxExecOptions): AsyncIterable<SandboxExecStreamEvent>;
-    readFile(path: string): Promise<Uint8Array>;
-    readTextFile(path: string): Promise<string>;
-    readTextFilePage?(path: string, options?: SandboxTextFileReadOptions): Promise<SandboxTextFileReadResult>;
-    writeFile(path: string, data: string | Uint8Array): Promise<void>;
-    writeTextFile(path: string, content: string): Promise<void>;
-    listFiles(path?: string): Promise<SandboxFileEntry[]>;
-    destroy(): Promise<void>;
-}
-interface SandboxTextFileReadOptions {
-    startLine?: number;
-    lineCount?: number;
-    maxBytes?: number;
-}
-interface SandboxTextFileReadResult {
-    content: string;
-    startLine: number;
-    endLine: number | null;
-    nextStartLine: number | null;
-    truncated: boolean;
-    truncatedBy: "lines" | "bytes" | null;
-}
-interface SandboxPortSession extends SandboxSession {
-    readonly publishedPorts: readonly SandboxPublishedPort[];
-    waitForPort(containerPort: number, options?: SandboxWaitForPortOptions): Promise<SandboxPublishedPort>;
-}
-interface SandboxProcessSession extends SandboxSession {
-    startProcess(options: SandboxProcessStartOptions): Promise<SandboxProcessInfo>;
-    listProcesses(): Promise<SandboxProcessInfo[]>;
-    readProcessLogs(processId: string, options?: SandboxProcessLogsOptions): Promise<SandboxProcessLogs>;
-    stopProcess(processId: string, options?: SandboxProcessStopOptions): Promise<SandboxProcessInfo>;
-}
-interface DockerSandboxSession extends SandboxPortSession, SandboxProcessSession {
-    readTextFilePage(path: string, options?: SandboxTextFileReadOptions): Promise<SandboxTextFileReadResult>;
-}
-interface SandboxCreateSessionOptions {
-    id?: string;
-    workspace?: SandboxWorkspaceOptions;
-    manifest?: SandboxManifest;
-    metadata?: Record<string, string>;
-}
-interface DockerSandboxCreateSessionOptions extends SandboxCreateSessionOptions {
+type DockerSandboxFileType = "file" | "directory" | "symlink" | "other";
+type DockerSandboxWorkspace = Readonly<{
+    type: "ephemeral";
+}> | Readonly<{
+    type: "docker-volume";
+    name: string;
+}>;
+type DockerSandboxNetwork = Readonly<{
+    mode: "none";
+}> | Readonly<{
+    mode: "bridge";
     ports?: readonly number[];
-}
-interface SandboxManifest {
-    files?: Record<string, string | Uint8Array>;
-    directories?: string[];
-    env?: Record<string, string>;
-}
-interface SandboxLimits {
-    timeoutMs?: number;
-    maxOutputBytes?: number;
-    maxFileBytes?: number;
+}>;
+type DockerSandboxState = "running" | "stopping" | "stopped" | "destroying" | "destroyed" | "error";
+type DockerSandboxResources = Readonly<{
     memoryMb?: number;
     cpus?: number;
     pidsLimit?: number;
+    sharedMemoryMb?: number;
+}>;
+type DockerSandboxRuntimeLimits = Readonly<{
+    commandTimeoutMs?: number;
+    maxOutputBytes?: number;
+    maxFileBytes?: number;
     maxProcesses?: number;
-}
-interface SandboxExecOptions {
+}>;
+type DockerSandboxSecurity = Readonly<{
+    readonlyRootfs?: boolean;
+    noNewPrivileges?: boolean;
+    dropCapabilities?: readonly string[];
+    addCapabilities?: readonly string[];
+    seccompProfile?: Readonly<{
+        type: "path";
+        path: string;
+    }>;
+}>;
+type CreateDockerSandboxOptions = Readonly<{
+    id?: string;
+    image: string;
+    workdir?: string;
+    workspace: DockerSandboxWorkspace;
+    network: DockerSandboxNetwork;
+    files?: Readonly<Record<string, string | Uint8Array>>;
+    directories?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+    user?: string;
+    labels?: Readonly<Record<string, string>>;
+    resources?: DockerSandboxResources;
+    runtime?: DockerSandboxRuntimeLimits;
+    security?: DockerSandboxSecurity;
+    abortSignal?: AbortSignal;
+}>;
+type ResumeDockerSandboxOptions = Readonly<{
+    id: string;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxClientOptions = Readonly<{
+    dockerPath?: string;
+}>;
+type PullDockerImageOptions = Readonly<{
+    image: string;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxExecOptions = Readonly<{
     command: string;
-    args?: string[];
+    args?: readonly string[];
     cwd?: string;
-    env?: Record<string, string>;
+    env?: Readonly<Record<string, string>>;
     timeoutMs?: number;
     input?: string | Uint8Array;
-    signal?: AbortSignal;
-    onStdout?: (chunk: Uint8Array) => void;
-    onStderr?: (chunk: Uint8Array) => void;
-}
-interface SandboxExecResult {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxExecResultBase = Readonly<{
+    stdout: Uint8Array;
+    stderr: Uint8Array;
     durationMs: number;
-    timedOut: boolean;
-    aborted: boolean;
     stdoutTruncated: boolean;
     stderrTruncated: boolean;
-}
-type SandboxExecStreamEvent = {
+}>;
+type DockerSandboxExecResult = (DockerSandboxExecResultBase & Readonly<{
+    status: "exited";
+    exitCode: number;
+}>) | (DockerSandboxExecResultBase & Readonly<{
+    status: "timed_out";
+}>);
+type DockerSandboxExecStreamEvent = Readonly<{
     type: "stdout";
-    chunk: Uint8Array;
-    text: string;
-} | {
+    data: Uint8Array;
+}> | Readonly<{
     type: "stderr";
-    chunk: Uint8Array;
+    data: Uint8Array;
+}> | Readonly<{
+    type: "result";
+    result: DockerSandboxExecResult;
+}>;
+type DockerSandboxReadFileOptions = Readonly<{
+    path: string;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxReadTextFilePageOptions = DockerSandboxReadFileOptions & Readonly<{
+    startLine?: number;
+    lineCount?: number;
+    maxBytes?: number;
+}>;
+type DockerSandboxTextFilePage = Readonly<{
+    content: string;
+    startLine: number;
+    endLine: number | null;
+    nextStartLine: number | null;
+    truncated: boolean;
+    truncatedBy: "lines" | "bytes" | null;
+}>;
+type DockerSandboxWriteFileOptions = Readonly<{
+    path: string;
+    data: Uint8Array;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxWriteTextFileOptions = Readonly<{
+    path: string;
     text: string;
-} | {
-    type: "exit";
-    result: SandboxExecResult;
-};
-interface SandboxFileEntry {
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxListFilesOptions = Readonly<{
+    path?: string;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxFileEntry = Readonly<{
     path: string;
-    type: SandboxFileType;
+    type: DockerSandboxFileType;
     size?: number;
-}
-interface SandboxPublishedPort {
+}>;
+type DockerSandboxPublishedPort = Readonly<{
     containerPort: number;
     host: "127.0.0.1";
     hostPort: number;
     protocol: "tcp";
-}
-interface SandboxWaitForPortOptions {
+}>;
+type DockerSandboxWaitForPortOptions = Readonly<{
+    containerPort: number;
     timeoutMs?: number;
     intervalMs?: number;
-    signal?: AbortSignal;
-}
-interface SandboxProcessStartOptions {
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxProcessStartOptions = Readonly<{
     command: string;
-    args?: string[];
+    args?: readonly string[];
     cwd?: string;
-    env?: Record<string, string>;
-}
-type SandboxProcessStatus = "running" | "exited" | "stopped";
-interface SandboxProcessInfo {
+    env?: Readonly<Record<string, string>>;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxProcessStatus = "running" | "exited" | "stopped";
+type DockerSandboxProcessInfo = Readonly<{
     id: string;
     command: string;
-    args: string[];
+    args: readonly string[];
     cwd?: string;
-    status: SandboxProcessStatus;
+    status: DockerSandboxProcessStatus;
     exitCode?: number;
     startedAt: string;
     endedAt?: string;
-}
-interface SandboxProcessLogsOptions {
+}>;
+type DockerSandboxListProcessesOptions = Readonly<{
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxReadProcessLogsOptions = Readonly<{
+    processId: string;
     tailBytes?: number;
-}
-interface SandboxProcessLogs {
-    stdout: string;
-    stderr: string;
+    abortSignal?: AbortSignal;
+}>;
+type DockerSandboxProcessLogs = Readonly<{
+    stdout: Uint8Array;
+    stderr: Uint8Array;
     stdoutTruncated: boolean;
     stderrTruncated: boolean;
-}
-interface SandboxProcessStopOptions {
+}>;
+type DockerSandboxStopProcessOptions = Readonly<{
+    processId: string;
     gracePeriodMs?: number;
-}
-interface DockerSandboxSecurityOptions {
-    readonlyRootfs?: boolean;
-    noNewPrivileges?: boolean;
-    dropCapabilities?: string[];
-}
-interface DockerSandboxNetworkOptions {
-    mode: SandboxNetworkMode;
-}
-interface SandboxSessionEvent {
-    sessionId: string;
-    provider: string;
+    abortSignal?: AbortSignal;
+}>;
+interface DockerSandboxRuntime {
+    readonly id: string;
+    readonly provider: "docker";
+    readonly workdir: string;
+    readonly publishedPorts: readonly DockerSandboxPublishedPort[];
+    exec(options: DockerSandboxExecOptions): Promise<DockerSandboxExecResult>;
+    execStream(options: DockerSandboxExecOptions): AsyncIterable<DockerSandboxExecStreamEvent>;
+    readFile(options: DockerSandboxReadFileOptions): Promise<Uint8Array>;
+    readTextFile(options: DockerSandboxReadFileOptions): Promise<string>;
+    readTextFilePage(options: DockerSandboxReadTextFilePageOptions): Promise<DockerSandboxTextFilePage>;
+    writeFile(options: DockerSandboxWriteFileOptions): Promise<void>;
+    writeTextFile(options: DockerSandboxWriteTextFileOptions): Promise<void>;
+    listFiles(options?: DockerSandboxListFilesOptions): Promise<readonly DockerSandboxFileEntry[]>;
+    startProcess(options: DockerSandboxProcessStartOptions): Promise<DockerSandboxProcessInfo>;
+    listProcesses(options?: DockerSandboxListProcessesOptions): Promise<readonly DockerSandboxProcessInfo[]>;
+    readProcessLogs(options: DockerSandboxReadProcessLogsOptions): Promise<DockerSandboxProcessLogs>;
+    stopProcess(options: DockerSandboxStopProcessOptions): Promise<DockerSandboxProcessInfo>;
+    waitForPort(options: DockerSandboxWaitForPortOptions): Promise<DockerSandboxPublishedPort>;
+}
+type DockerSandboxInspectionOptions = Readonly<{
+    files?: boolean;
+    ports?: boolean;
+    processes?: boolean;
+}>;
+type DockerSandboxInspector = Readonly<{
+    id: string;
+    provider: "docker";
     workdir: string;
+    listFiles?: DockerSandboxRuntime["listFiles"];
+    readFile?: DockerSandboxRuntime["readFile"];
+    publishedPorts?: readonly DockerSandboxPublishedPort[];
+    listProcesses?: DockerSandboxRuntime["listProcesses"];
+    readProcessLogs?: DockerSandboxRuntime["readProcessLogs"];
+}>;
+type StopDockerSandboxOptions = Readonly<{
+    abortSignal?: AbortSignal;
+}>;
+interface DockerSandbox extends AsyncDisposable {
+    readonly id: string;
+    readonly state: DockerSandboxState;
+    readonly runtime: DockerSandboxRuntime;
+    inspector(options: DockerSandboxInspectionOptions): DockerSandboxInspector;
+    stop(options?: StopDockerSandboxOptions): Promise<void>;
+    destroy(): Promise<void>;
 }
-interface SandboxExecEvent extends SandboxSessionEvent {
-    command: string;
-    args: string[];
-    cwd?: string;
-}
-interface SandboxExecEndEvent extends SandboxExecEvent {
-    result: SandboxExecResult;
-}
-interface SandboxFileWriteEvent extends SandboxSessionEvent {
-    path: string;
-    size: number;
-}
-interface SandboxHooks {
-    onSessionCreate?: (event: SandboxSessionEvent) => void | Promise<void>;
-    onExecStart?: (event: SandboxExecEvent) => void | Promise<void>;
-    onExecEnd?: (event: SandboxExecEndEvent) => void | Promise<void>;
-    onFileWrite?: (event: SandboxFileWriteEvent) => void | Promise<void>;
-    onDestroy?: (event: SandboxSessionEvent) => void | Promise<void>;
-}
-interface DockerSandboxOptions {
-    image?: string;
-    pull?: "missing" | "always" | "never";
-    workdir?: string;
-    workspace?: SandboxWorkspaceOptions;
-    lifecycle?: SandboxLifecycleOptions;
-    network?: SandboxNetworkMode | DockerSandboxNetworkOptions;
-    user?: string;
-    dockerPath?: string;
-    labels?: Record<string, string>;
-    limits?: SandboxLimits;
-    security?: DockerSandboxSecurityOptions;
-    hooks?: SandboxHooks;
-}
-interface SandboxToolsOptions {
-    allow?: SandboxToolName[];
-    include?: SandboxToolName[];
-    execTimeoutMs?: number;
-    exec?: SandboxExecToolPolicy;
-    readFile?: SandboxReadFileToolPolicy;
-    writeFile?: SandboxFileToolPolicy;
-    process?: SandboxProcessToolPolicy;
-}
-type SandboxToolName = "exec_command" | "read_file" | "write_file" | "list_files" | "list_ports" | "start_process" | "list_processes" | "read_process_logs" | "stop_process" | "wait_for_port";
-interface SandboxExecToolPolicy {
-    allowedCommands?: string[];
-    blockedCommands?: string[];
+type DockerSandboxToolName = "exec_command" | "read_file" | "write_file" | "list_files" | "list_ports" | "start_process" | "list_processes" | "read_process_logs" | "stop_process" | "wait_for_port";
+type DockerSandboxCommandPolicy = Readonly<{
+    mode: "allow";
+    values: readonly string[];
+}> | Readonly<{
+    mode: "block";
+    values: readonly string[];
+}>;
+type DockerSandboxExecToolPolicy = Readonly<{
+    commands?: DockerSandboxCommandPolicy;
     defaultTimeoutMs?: number;
     maxTimeoutMs?: number;
-}
-interface SandboxFileToolPolicy {
+}>;
+type DockerSandboxFileToolPolicy = Readonly<{
     maxBytes?: number;
-}
-interface SandboxReadFileToolPolicy extends SandboxFileToolPolicy {
+}>;
+type DockerSandboxReadFileToolPolicy = DockerSandboxFileToolPolicy & Readonly<{
     defaultLineCount?: number;
     maxLineCount?: number;
-}
-interface SandboxProcessToolPolicy {
+}>;
+type DockerSandboxProcessToolPolicy = Readonly<{
     maxLogBytes?: number;
     defaultWaitTimeoutMs?: number;
     maxWaitTimeoutMs?: number;
     stopGracePeriodMs?: number;
-}
-type SandboxToolsFactory = (session: SandboxSession, options?: SandboxToolsOptions) => AnyTool[];
-
-declare function isSandboxPortSession(session: SandboxSession): session is SandboxPortSession;
-declare function isSandboxProcessSession(session: SandboxSession): session is SandboxProcessSession;
+}>;
+type CreateDockerSandboxToolsOptions = Readonly<{
+    sandbox: DockerSandboxRuntime;
+    tools: readonly [DockerSandboxToolName, ...DockerSandboxToolName[]];
+    exec?: DockerSandboxExecToolPolicy;
+    readFile?: DockerSandboxReadFileToolPolicy;
+    writeFile?: DockerSandboxFileToolPolicy;
+    process?: DockerSandboxProcessToolPolicy;
+}>;
 
-declare class DockerSandbox implements Sandbox {
-    readonly provider = "docker";
-    private readonly image;
-    private readonly pull;
-    private readonly workdir;
-    private readonly workspace;
-    private readonly lifecycle;
-    private readonly network;
+declare class DockerSandboxClient {
     private readonly dockerPath;
-    private readonly labels;
-    private readonly limits;
-    private readonly security;
-    private readonly hooks;
-    private readonly user;
-    constructor(options?: DockerSandboxOptions);
-    static node(options?: DockerSandboxOptions): DockerSandbox;
-    static python(options?: DockerSandboxOptions): DockerSandbox;
-    static deno(options?: DockerSandboxOptions): DockerSandbox;
-    createSession(options?: DockerSandboxCreateSessionOptions): Promise<DockerSandboxSession>;
-    private ensureImage;
-    private createRunArgs;
-    private appendNetworkArgs;
-    private assertPortNetworkCompatible;
-    private inspectPublishedPorts;
-    private appendLimitArgs;
-    private appendSecurityArgs;
+    constructor(options?: DockerSandboxClientOptions);
+    pullImage(options: PullDockerImageOptions): Promise<void>;
+    createSandbox(options: CreateDockerSandboxOptions): Promise<DockerSandbox>;
+    resumeSandbox(options: ResumeDockerSandboxOptions): Promise<DockerSandbox>;
+    private createHandle;
+    private assertImageExists;
+    private assertContainerDoesNotExist;
+    private assertVolumeExists;
     private cliOptions;
-    private cleanup;
 }
 
-declare class SandboxError extends Error {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
-}
-declare class SandboxDockerUnavailableError extends SandboxError {
-}
-declare class SandboxDockerCommandError extends SandboxError {
-    readonly result: {
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    };
-    constructor(message: string, result: {
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    });
-}
-declare class SandboxSessionDestroyedError extends SandboxError {
-}
-declare class SandboxPathError extends SandboxError {
-}
-declare class SandboxTimeoutError extends SandboxError {
-}
-declare class SandboxFileSizeError extends SandboxError {
-}
-declare class SandboxToolPolicyError extends SandboxError {
-}
-declare class SandboxPortError extends SandboxError {
-}
-declare class SandboxProcessError extends SandboxError {
+type DockerSandboxErrorCode = "docker_unavailable" | "docker_command_failed" | "image_not_found" | "volume_not_found" | "sandbox_not_found" | "invalid_state" | "invalid_path" | "timeout" | "file_too_large" | "tool_policy" | "port" | "process";
+declare class DockerSandboxError extends Error {
+    readonly code: DockerSandboxErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: DockerSandboxErrorCode, details?: unknown | undefined, options?: ErrorOptions);
 }
 
-declare function createSandboxTools(session: SandboxSession, options?: SandboxToolsOptions): AnyTool[];
+declare function createDockerSandboxTools(options: CreateDockerSandboxToolsOptions): readonly AnyTool[];
 
-export { DockerSandbox, type DockerSandboxCreateSessionOptions, type DockerSandboxNetworkOptions, type DockerSandboxOptions, type DockerSandboxSecurityOptions, type DockerSandboxSession, type Sandbox, type SandboxCreateSessionOptions, SandboxDockerCommandError, SandboxDockerUnavailableError, SandboxError, type SandboxExecEndEvent, type SandboxExecEvent, type SandboxExecOptions, type SandboxExecResult, type SandboxExecStreamEvent, type SandboxExecToolPolicy, type SandboxFileEntry, SandboxFileSizeError, type SandboxFileToolPolicy, type SandboxFileType, type SandboxFileWriteEvent, type SandboxHooks, type SandboxLifecycleOptions, type SandboxLimits, type SandboxManifest, type SandboxNetworkMode, SandboxPathError, SandboxPortError, type SandboxPortSession, SandboxProcessError, type SandboxProcessInfo, type SandboxProcessLogs, type SandboxProcessLogsOptions, type SandboxProcessSession, type SandboxProcessStartOptions, type SandboxProcessStatus, type SandboxProcessStopOptions, type SandboxProcessToolPolicy, type SandboxPublishedPort, type SandboxReadFileToolPolicy, type SandboxSession, SandboxSessionDestroyedError, type SandboxSessionEvent, type SandboxTextFileReadOptions, type SandboxTextFileReadResult, SandboxTimeoutError, type SandboxToolName, SandboxToolPolicyError, type SandboxToolsFactory, type SandboxToolsOptions, type SandboxWaitForPortOptions, type SandboxWorkspaceOptions, createSandboxTools, isSandboxPortSession, isSandboxProcessSession };
+export { type CreateDockerSandboxOptions, type CreateDockerSandboxToolsOptions, type DockerSandbox, DockerSandboxClient, type DockerSandboxClientOptions, type DockerSandboxCommandPolicy, DockerSandboxError, type DockerSandboxErrorCode, type DockerSandboxExecOptions, type DockerSandboxExecResult, type DockerSandboxExecStreamEvent, type DockerSandboxExecToolPolicy, type DockerSandboxFileEntry, type DockerSandboxFileToolPolicy, type DockerSandboxFileType, type DockerSandboxInspectionOptions, type DockerSandboxInspector, type DockerSandboxListFilesOptions, type DockerSandboxListProcessesOptions, type DockerSandboxNetwork, type DockerSandboxProcessInfo, type DockerSandboxProcessLogs, type DockerSandboxProcessStartOptions, type DockerSandboxProcessStatus, type DockerSandboxProcessToolPolicy, type DockerSandboxPublishedPort, type DockerSandboxReadFileOptions, type DockerSandboxReadFileToolPolicy, type DockerSandboxReadProcessLogsOptions, type DockerSandboxReadTextFilePageOptions, type DockerSandboxResources, type DockerSandboxRuntime, type DockerSandboxRuntimeLimits, type DockerSandboxSecurity, type DockerSandboxState, type DockerSandboxStopProcessOptions, type DockerSandboxTextFilePage, type DockerSandboxToolName, type DockerSandboxWaitForPortOptions, type DockerSandboxWorkspace, type DockerSandboxWriteFileOptions, type DockerSandboxWriteTextFileOptions, type PullDockerImageOptions, type ResumeDockerSandboxOptions, type StopDockerSandboxOptions, createDockerSandboxTools };