noumen 0.3.0 → 0.5.0

package/dist/docker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/virtual/docker-fs.ts","../src/virtual/docker-computer.ts","../src/virtual/docker-sandbox.ts"],"sourcesContent":["import * as path from \"node:path\";\nimport type { VirtualFs, FileEntry, FileStat, ReadOptions } from \"./fs.js\";\nimport type { DockerContainer } from \"./docker-computer.js\";\n\nexport interface DockerFsOptions {\n  /** A dockerode Container instance for the target container. */\n  container: DockerContainer;\n  /** Working directory for relative path resolution (default: /). */\n  workingDir?: string;\n}\n\n/**\n * VirtualFs backed by file operations inside a Docker container.\n *\n * Uses `container.exec()` to run filesystem commands (cat, tee, rm, mkdir,\n * stat, etc.) inside the container. File writes use exec + tee to avoid\n * tar archive overhead for text content.\n *\n * Requires `dockerode` as an optional peer dependency.\n * The user is responsible for container lifecycle.\n */\nexport class DockerFs implements VirtualFs {\n  private container: DockerContainer;\n  private workingDir: string;\n\n  constructor(opts: DockerFsOptions) {\n    this.container = opts.container;\n    this.workingDir = opts.workingDir ?? \"/\";\n  }\n\n  private resolvePath(p: string): string {\n    if (p.includes(\"\\0\")) {\n      throw new Error(\"Path contains null bytes\");\n    }\n    const normalizedBase = this.workingDir.endsWith(\"/\") ? this.workingDir : this.workingDir + \"/\";\n    if (p.startsWith(\"/\")) {\n      const normalized = path.normalize(p);\n      if (normalized !== this.workingDir && !normalized.startsWith(normalizedBase)) {\n        throw new Error(`Absolute path \"${p}\" is outside working directory \"${this.workingDir}\"`);\n      }\n      return normalized;\n    }\n    const resolved = path.resolve(this.workingDir, p);\n    if (resolved !== this.workingDir && !resolved.startsWith(normalizedBase)) {\n      throw new Error(`Path \"${p}\" escapes working directory \"${this.workingDir}\"`);\n    }\n    return resolved;\n  }\n\n  private async exec(\n    cmd: string[],\n  ): Promise<{ exitCode: number; stdout: string; stderr: string }> {\n    const execInstance = await this.container.exec({\n      Cmd: cmd,\n      AttachStdout: true,\n      AttachStderr: true,\n      Tty: false,\n    });\n    const stream = await execInstance.start({ hijack: true, stdin: false });\n    const result = await collectExecStream(stream);\n    const inspection = await execInstance.inspect();\n    return { exitCode: inspection.ExitCode, ...result };\n  }\n\n  async readFile(path: string, _opts?: ReadOptions): Promise<string> {\n    const resolved = this.resolvePath(path);\n    const { exitCode, stdout, stderr } = await this.exec([\n      \"cat\",\n      resolved,\n    ]);\n    if (exitCode !== 0) {\n      throw new Error(`DockerFs readFile failed: ${stderr.trim() || `exit code ${exitCode}`}`);\n    }\n    return stdout;\n  }\n\n  async readFileBytes(path: string, maxBytes?: number): Promise<Buffer> {\n    const resolved = this.resolvePath(path);\n    const cmd = maxBytes !== undefined\n      ? [\"head\", \"-c\", String(maxBytes), resolved]\n      : [\"cat\", resolved];\n    const { exitCode, stdout, stderr } = await this.exec([\n      \"bash\", \"-c\",\n      `${cmd.map(shellEscape).join(\" \")} | base64`,\n    ]);\n    if (exitCode !== 0) {\n      throw new Error(`DockerFs readFileBytes failed: ${stderr.trim() || `exit code ${exitCode}`}`);\n    }\n    return Buffer.from(stdout.trim(), \"base64\");\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    const resolved = this.resolvePath(path);\n    const dir = resolved.substring(0, resolved.lastIndexOf(\"/\"));\n    if (dir) {\n      await this.exec([\"mkdir\", \"-p\", dir]);\n    }\n\n    const encoded = Buffer.from(content, \"utf-8\").toString(\"base64\");\n\n    const MAX_INLINE_LEN = 100_000;\n    if (encoded.length <= MAX_INLINE_LEN) {\n      const { exitCode, stderr } = await this.exec([\n        \"bash\",\n        \"-c\",\n        `echo ${shellEscape(encoded)} | base64 -d > ${shellEscape(resolved)}`,\n      ]);\n      if (exitCode !== 0) {\n        throw new Error(`DockerFs writeFile failed: ${stderr.trim()}`);\n      }\n    } else {\n      const execInstance = await this.container.exec({\n        Cmd: [\"bash\", \"-c\", `base64 -d > ${shellEscape(resolved)}`],\n        AttachStdout: true,\n        AttachStderr: true,\n        AttachStdin: true,\n        Tty: false,\n      });\n      const stream = await execInstance.start({ hijack: true, stdin: true });\n      const writable = stream as unknown as NodeJS.WritableStream;\n      writable.write(encoded);\n      writable.end();\n      const result = await collectExecStream(stream as unknown as NodeJS.ReadableStream);\n      const inspection = await execInstance.inspect();\n      if (inspection.ExitCode !== 0) {\n        throw new Error(`DockerFs writeFile failed: ${result.stderr.trim()}`);\n      }\n    }\n  }\n\n  async appendFile(path: string, content: string): Promise<void> {\n    const resolved = this.resolvePath(path);\n    const dir = resolved.substring(0, resolved.lastIndexOf(\"/\"));\n    if (dir) {\n      await this.exec([\"mkdir\", \"-p\", dir]);\n    }\n    const encoded = Buffer.from(content, \"utf-8\").toString(\"base64\");\n    const { exitCode, stderr } = await this.exec([\n      \"bash\",\n      \"-c\",\n      `echo ${shellEscape(encoded)} | base64 -d >> ${shellEscape(resolved)}`,\n    ]);\n    if (exitCode !== 0) {\n      throw new Error(`DockerFs appendFile failed: ${stderr.trim()}`);\n    }\n  }\n\n  async deleteFile(\n    path: string,\n    opts?: { recursive?: boolean },\n  ): Promise<void> {\n    const resolved = this.resolvePath(path);\n    const args = opts?.recursive ? [\"rm\", \"-rf\", resolved] : [\"rm\", \"-f\", resolved];\n    await this.exec(args);\n  }\n\n  async mkdir(path: string, opts?: { recursive?: boolean }): Promise<void> {\n    const resolved = this.resolvePath(path);\n    const args = opts?.recursive\n      ? [\"mkdir\", \"-p\", resolved]\n      : [\"mkdir\", resolved];\n    await this.exec(args);\n  }\n\n  async readdir(\n    path: string,\n    _opts?: { recursive?: boolean },\n  ): Promise<FileEntry[]> {\n    const resolved = this.resolvePath(path);\n    const { exitCode, stdout, stderr } = await this.exec([\n      \"bash\",\n      \"-c\",\n      `find ${shellEscape(resolved)} -maxdepth 1 -mindepth 1 -printf '%y %p\\\\n' 2>/dev/null`,\n    ]);\n    if (exitCode !== 0 && stderr.trim()) {\n      throw new Error(`DockerFs readdir failed: ${stderr.trim()}`);\n    }\n\n    const entries: FileEntry[] = [];\n    for (const line of stdout.trim().split(\"\\n\")) {\n      if (!line) continue;\n      const spaceIdx = line.indexOf(\" \");\n      const type = line.substring(0, spaceIdx);\n      const fullPath = line.substring(spaceIdx + 1);\n      const name = fullPath.substring(fullPath.lastIndexOf(\"/\") + 1);\n      entries.push({\n        name,\n        path: fullPath,\n        isDirectory: type === \"d\",\n        isFile: type === \"f\",\n      });\n    }\n    return entries;\n  }\n\n  async exists(path: string): Promise<boolean> {\n    const resolved = this.resolvePath(path);\n    const { exitCode } = await this.exec([\"test\", \"-e\", resolved]);\n    return exitCode === 0;\n  }\n\n  async stat(path: string): Promise<FileStat> {\n    const resolved = this.resolvePath(path);\n    const { exitCode, stdout, stderr } = await this.exec([\n      \"stat\",\n      \"-c\",\n      \"%s\\t%F\\t%W\\t%Y\",\n      resolved,\n    ]);\n    if (exitCode !== 0) {\n      throw new Error(`DockerFs stat failed: ${stderr.trim() || `exit code ${exitCode}`}`);\n    }\n\n    const parts = stdout.trim().split(\"\\t\");\n    const size = parseInt(parts[0], 10);\n    const fileType = parts[1];\n    const createdEpoch = parseInt(parts[2], 10);\n    const modifiedEpoch = parseInt(parts[3], 10);\n\n    return {\n      size,\n      isDirectory: fileType === \"directory\",\n      isFile: fileType.startsWith(\"regular\"),\n      createdAt: createdEpoch > 0 ? new Date(createdEpoch * 1000) : undefined,\n      modifiedAt: modifiedEpoch > 0 ? new Date(modifiedEpoch * 1000) : undefined,\n    };\n  }\n}\n\nfunction shellEscape(s: string): string {\n  return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n}\n\nfunction collectExecStream(\n  stream: NodeJS.ReadableStream,\n): Promise<{ stdout: string; stderr: string }> {\n  return new Promise((resolve, reject) => {\n    const stdoutBufs: Buffer[] = [];\n    const stderrBufs: Buffer[] = [];\n    let pending: Buffer = Buffer.alloc(0);\n\n    stream.on(\"data\", (chunk: Buffer) => {\n      let buf = pending.length > 0 ? Buffer.concat([pending, chunk]) : chunk;\n      let offset = 0;\n      while (offset + 8 <= buf.length) {\n        const payloadLen = buf.readUInt32BE(offset + 4);\n        if (offset + 8 + payloadLen > buf.length) break;\n        const streamType = buf[offset];\n        const payload = buf.subarray(offset + 8, offset + 8 + payloadLen);\n        if (streamType === 2) {\n          stderrBufs.push(payload);\n        } else {\n          stdoutBufs.push(payload);\n        }\n        offset += 8 + payloadLen;\n      }\n      pending = offset < buf.length ? buf.subarray(offset) : Buffer.alloc(0);\n    });\n\n    stream.on(\"end\", () => {\n      resolve({\n        stdout: Buffer.concat(stdoutBufs).toString(\"utf-8\"),\n        stderr: Buffer.concat(stderrBufs).toString(\"utf-8\"),\n      });\n    });\n\n    stream.on(\"error\", (err: Error) => reject(err));\n  });\n}\n","import type { VirtualComputer, ExecOptions, CommandResult } from \"./computer.js\";\n\n/**\n * Minimal subset of the dockerode Container interface used by DockerComputer.\n * Avoids a hard import of dockerode at the module level.\n */\nexport interface DockerContainer {\n  exec(\n    options: Record<string, unknown>,\n  ): Promise<{ start(opts?: Record<string, unknown>): Promise<NodeJS.ReadableStream>; inspect(): Promise<{ ExitCode: number }> }>;\n}\n\nexport interface DockerComputerOptions {\n  /** A dockerode Container instance for the target container. */\n  container: DockerContainer;\n  /** Default working directory for commands (default: /). */\n  defaultCwd?: string;\n  /** Default timeout in ms for commands (default: 30000). */\n  defaultTimeout?: number;\n}\n\n/**\n * VirtualComputer backed by command execution inside a Docker container.\n *\n * Requires `dockerode` as an optional peer dependency.\n * The user is responsible for container lifecycle (create, start, stop).\n */\nexport class DockerComputer implements VirtualComputer {\n  private container: DockerContainer;\n  private defaultCwd: string;\n  private defaultTimeout: number;\n\n  constructor(opts: DockerComputerOptions) {\n    this.container = opts.container;\n    this.defaultCwd = opts.defaultCwd ?? \"/\";\n    this.defaultTimeout = opts.defaultTimeout ?? 30_000;\n  }\n\n  async executeCommand(\n    command: string,\n    opts?: ExecOptions,\n  ): Promise<CommandResult> {\n    const cwd = opts?.cwd ?? this.defaultCwd;\n    const timeout = opts?.timeout ?? this.defaultTimeout;\n\n    const execOpts: Record<string, unknown> = {\n      Cmd: [\"bash\", \"-c\", `cd ${shellEscape(cwd)} && ${command}`],\n      AttachStdout: true,\n      AttachStderr: true,\n      Tty: false,\n    };\n    if (opts?.env) {\n      execOpts.Env = Object.entries(opts.env).map(\n        ([k, v]) => `${k}=${v}`,\n      );\n    }\n\n    const exec = await this.container.exec(execOpts);\n    const stream = await exec.start({ hijack: true, stdin: false });\n\n    const { stdout, stderr } = await collectStream(stream, timeout);\n    const inspection = await exec.inspect();\n\n    return {\n      exitCode: inspection.ExitCode,\n      stdout,\n      stderr,\n    };\n  }\n}\n\nfunction shellEscape(s: string): string {\n  return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n}\n\nfunction collectStream(\n  stream: NodeJS.ReadableStream,\n  timeout: number,\n): Promise<{ stdout: string; stderr: string }> {\n  return new Promise((resolve, reject) => {\n    const stdoutBufs: Buffer[] = [];\n    const stderrBufs: Buffer[] = [];\n    let pending: Buffer = Buffer.alloc(0);\n\n    const timer = setTimeout(() => {\n      (stream as unknown as { destroy?: () => void }).destroy?.();\n      resolve({\n        stdout: Buffer.concat(stdoutBufs).toString(\"utf-8\"),\n        stderr: Buffer.concat(stderrBufs).toString(\"utf-8\") +\n          \"\\n[timeout after \" + timeout + \"ms]\",\n      });\n    }, timeout);\n\n    stream.on(\"data\", (chunk: Buffer) => {\n      let buf = pending.length > 0 ? Buffer.concat([pending, chunk]) : chunk;\n      let offset = 0;\n      while (offset + 8 <= buf.length) {\n        const payloadLen = buf.readUInt32BE(offset + 4);\n        if (offset + 8 + payloadLen > buf.length) break;\n        const streamType = buf[offset];\n        const payload = buf.subarray(offset + 8, offset + 8 + payloadLen);\n        if (streamType === 2) {\n          stderrBufs.push(payload);\n        } else {\n          stdoutBufs.push(payload);\n        }\n        offset += 8 + payloadLen;\n      }\n      pending = offset < buf.length ? buf.subarray(offset) : Buffer.alloc(0);\n    });\n\n    stream.on(\"end\", () => {\n      clearTimeout(timer);\n      resolve({\n        stdout: Buffer.concat(stdoutBufs).toString(\"utf-8\"),\n        stderr: Buffer.concat(stderrBufs).toString(\"utf-8\"),\n      });\n    });\n\n    stream.on(\"error\", (err: Error) => {\n      clearTimeout(timer);\n      reject(err);\n    });\n  });\n}\n","import type { Sandbox } from \"./sandbox.js\";\nimport { DockerFs } from \"./docker-fs.js\";\nimport { DockerComputer, type DockerContainer } from \"./docker-computer.js\";\nimport { createFsProxy, createComputerProxy } from \"./proxy.js\";\n\nexport interface DockerSandboxOptions {\n  /**\n   * A pre-existing dockerode Container instance. When provided the sandbox\n   * attaches to this container directly — no auto-creation occurs and\n   * `dispose()` will **not** stop or remove it.\n   *\n   * When omitted, a new container is created from `image` on the first\n   * `init()` call via a dynamic import of `dockerode`. The auto-created\n   * container is stopped and removed when `dispose()` is called.\n   */\n  container?: DockerContainer;\n  /**\n   * Docker image to use for auto-creation (e.g. `\"ubuntu:22.04\"`).\n   * Required when `container` is omitted; ignored when `container` is provided.\n   */\n  image?: string;\n  /** Command to run in the auto-created container (default: `[\"sleep\", \"infinity\"]`). */\n  cmd?: string[];\n  /** Environment variables for the auto-created container. */\n  env?: string[];\n  /** Extra options passed to dockerode `createContainer`. */\n  dockerOptions?: Record<string, unknown>;\n  /** Working directory inside the container. */\n  cwd?: string;\n  /** Default timeout (ms) for shell commands. */\n  defaultTimeout?: number;\n}\n\n/**\n * Create a `Sandbox` backed by a Docker container.\n * Requires `dockerode` as an optional peer dependency.\n *\n * **Auto-creation:** When `container` is omitted and `image` is provided,\n * the container is created and started lazily on the first `init()` call.\n * The container ID is available through `sandboxId()` for session\n * persistence. Pass the stored ID back through `init(storedId)` to\n * reattach to an existing container on resume.\n *\n * **Explicit container:** When `container` is provided, `init()` binds\n * it immediately. `dispose()` is a no-op — the caller owns the\n * container's lifecycle.\n *\n * @example\n * ```ts\n * // Auto-create from image\n * const sandbox = DockerSandbox({ image: \"ubuntu:22.04\", cwd: \"/workspace\" });\n *\n * // Explicit container (lifecycle managed externally)\n * const sandbox = DockerSandbox({ container: myDockerodeContainer });\n * ```\n */\nexport function DockerSandbox(opts: DockerSandboxOptions): Sandbox {\n  if (opts.container) {\n    const c = opts.container;\n    return {\n      fs: new DockerFs({ container: c, workingDir: opts.cwd }),\n      computer: new DockerComputer({\n        container: c,\n        defaultCwd: opts.cwd,\n        defaultTimeout: opts.defaultTimeout,\n      }),\n      sandboxId: () => (c as any).id as string | undefined,\n    };\n  }\n\n  if (!opts.image) {\n    throw new Error(\"DockerSandbox requires either `container` or `image`\");\n  }\n\n  const fsProxy = createFsProxy();\n  const computerProxy = createComputerProxy();\n  let containerId: string | undefined;\n  let containerRef: any;\n  let autoCreated = false;\n  let initPromise: Promise<void> | null = null;\n\n  async function doInit(reconnectId?: string): Promise<void> {\n    const Docker = (await import(\"dockerode\")).default;\n    const docker = new Docker();\n\n    let container: any;\n    if (reconnectId) {\n      container = docker.getContainer(reconnectId);\n      try {\n        await container.inspect();\n      } catch {\n        container = await docker.createContainer({\n          Image: opts.image!,\n          Cmd: opts.cmd ?? [\"sleep\", \"infinity\"],\n          Env: opts.env,\n          Tty: false,\n          ...opts.dockerOptions,\n        });\n        await container.start();\n        autoCreated = true;\n      }\n    } else {\n      container = await docker.createContainer({\n        Image: opts.image!,\n        Cmd: opts.cmd ?? [\"sleep\", \"infinity\"],\n        Env: opts.env,\n        Tty: false,\n        ...opts.dockerOptions,\n      });\n      await container.start();\n      autoCreated = true;\n    }\n\n    containerRef = container;\n    containerId = container.id;\n    fsProxy.setTarget(new DockerFs({ container, workingDir: opts.cwd }));\n    computerProxy.setTarget(new DockerComputer({\n      container,\n      defaultCwd: opts.cwd,\n      defaultTimeout: opts.defaultTimeout,\n    }));\n  }\n\n  return {\n    fs: fsProxy,\n    computer: computerProxy,\n    sandboxId: () => containerId,\n\n    init(sandboxId?: string): Promise<void> {\n      if (!initPromise) {\n        initPromise = doInit(sandboxId).catch((err) => {\n          initPromise = null;\n          throw err;\n        });\n      }\n      return initPromise;\n    },\n\n    async dispose(): Promise<void> {\n      if (initPromise) {\n        await initPromise.catch(() => {});\n      }\n      if (!autoCreated || !containerRef) return;\n      try { await containerRef.stop(); } catch { /* may already be stopped */ }\n      try { await containerRef.remove(); } catch { /* best-effort */ }\n    },\n  };\n}\n"],"mappings":"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","names":["path","resolve","shellEscape","resolve"]}

package/dist/e2b.d.ts

@@ -0,0 +1,157 @@
+import { S as Sandbox } from './sandbox-9qeMTNrD.js';
+import { V as VirtualComputer, E as ExecOptions, C as CommandResult, a as VirtualFs, R as ReadOptions, F as FileEntry, b as FileStat } from './computer-BPdxSo6X.js';
+
+/**
+ * Minimal subset of the E2B Sandbox interface used by E2BComputer and E2BFs.
+ * Avoids a hard import of `e2b` at the module level.
+ */
+interface E2BSandboxInstance {
+    commands: {
+        run(cmd: string, opts?: {
+            cwd?: string;
+            timeout?: number;
+            envs?: Record<string, string>;
+        }): Promise<{
+            exitCode: number;
+            stdout: string;
+            stderr: string;
+        }>;
+    };
+    files: {
+        read(path: string, opts?: {
+            format?: string;
+        }): Promise<string>;
+        write(path: string, data: string): Promise<unknown>;
+        remove(path: string): Promise<void>;
+        makeDir(path: string): Promise<unknown>;
+        list(path: string): Promise<Array<{
+            name: string;
+            path: string;
+            type?: string;
+            size?: number;
+            modifiedTime?: Date;
+        }>>;
+        exists(path: string): Promise<boolean>;
+        getInfo(path: string): Promise<{
+            name: string;
+            path: string;
+            type?: string;
+            size?: number;
+            modifiedTime?: Date;
+        }>;
+    };
+}
+interface E2BComputerOptions {
+    /** An E2B Sandbox instance created via `Sandbox.create()`. */
+    sandbox: E2BSandboxInstance;
+    /** Default working directory for commands. */
+    defaultCwd?: string;
+    /** Default timeout in ms for commands (default: 30000). */
+    defaultTimeout?: number;
+}
+/**
+ * VirtualComputer backed by command execution in an E2B cloud sandbox.
+ *
+ * Requires `e2b` as an optional peer dependency.
+ * The user is responsible for sandbox lifecycle (create, close).
+ */
+declare class E2BComputer implements VirtualComputer {
+    private sandbox;
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts: E2BComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+interface E2BSandboxOptions {
+    /**
+     * A pre-existing E2B Sandbox instance (e.g. from `Sandbox.create()`).
+     * When provided the sandbox attaches to this instance — no auto-creation
+     * occurs and `dispose()` will **not** kill it.
+     *
+     * When omitted, a new E2B sandbox is created on the first `init()` call
+     * via a dynamic import of the `e2b` package. The auto-created sandbox
+     * is killed when `dispose()` is called.
+     */
+    sandbox?: E2BSandboxInstance;
+    /**
+     * E2B template to use for auto-creation (default: `"base"`).
+     * Only used when `sandbox` is omitted.
+     */
+    template?: string;
+    /**
+     * E2B API key. Falls back to the `E2B_API_KEY` environment variable
+     * when omitted. Only used during auto-creation.
+     */
+    apiKey?: string;
+    /** Timeout (ms) for the auto-created E2B sandbox (default: E2B SDK default). */
+    timeoutMs?: number;
+    /** Working directory inside the sandbox. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+}
+/**
+ * Create a `Sandbox` backed by an E2B cloud sandbox.
+ * Requires `e2b` as an optional peer dependency.
+ *
+ * **Auto-creation:** When `sandbox` is omitted the E2B sandbox is
+ * provisioned lazily on the first `init()` call via the E2B SDK.
+ * The sandbox ID is available through `sandboxId()` for session
+ * persistence. Pass the stored ID back through `init(storedId)` to
+ * reconnect to the same sandbox on resume (via `Sandbox.connect()`).
+ *
+ * **Explicit instance:** When `sandbox` is provided, `init()` binds
+ * it immediately. `dispose()` is a no-op — the caller owns the
+ * sandbox's lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-create — sandbox provisioned on first init()
+ * const sandbox = E2BSandbox({ template: "base" });
+ *
+ * // Explicit — attach to pre-existing instance
+ * const sandbox = E2BSandbox({ sandbox: await E2BSdk.Sandbox.create() });
+ * ```
+ */
+declare function E2BSandbox(opts: E2BSandboxOptions): Sandbox;
+
+interface E2BFsOptions {
+    /** An E2B Sandbox instance created via `Sandbox.create()`. */
+    sandbox: E2BSandboxInstance;
+    /** Working directory for relative path resolution. */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by the E2B cloud sandbox filesystem.
+ *
+ * Requires `e2b` as an optional peer dependency.
+ * The user is responsible for sandbox lifecycle (create, close).
+ */
+declare class E2BFs implements VirtualFs {
+    private sandbox;
+    private workingDir;
+    constructor(opts: E2BFsOptions);
+    private resolvePath;
+    readFile(path: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(path: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * @warning Not atomic. Concurrent appends may lose data due to
+     * read-then-write TOCTOU. The E2B SDK does not expose an append primitive.
+     */
+    appendFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+}
+
+export { E2BComputer, type E2BComputerOptions, E2BFs, type E2BFsOptions, E2BSandbox, type E2BSandboxInstance, type E2BSandboxOptions };

package/dist/e2b.js

@@ -0,0 +1,202 @@
+import {
+  createComputerProxy,
+  createFsProxy
+} from "./chunk-I5SBSOS6.js";
+import "./chunk-DGUM43GV.js";
+
+// src/virtual/e2b-fs.ts
+import * as path from "path";
+var E2BFs = class {
+  sandbox;
+  workingDir;
+  constructor(opts) {
+    this.sandbox = opts.sandbox;
+    this.workingDir = opts.workingDir;
+  }
+  resolvePath(p) {
+    if (!this.workingDir) return p;
+    const normalizedBase = this.workingDir.endsWith("/") ? this.workingDir : this.workingDir + "/";
+    if (p.startsWith("/")) {
+      if (p !== this.workingDir && !p.startsWith(normalizedBase)) {
+        throw new Error(`Absolute path "${p}" is outside working directory "${this.workingDir}"`);
+      }
+      return p;
+    }
+    const resolved = path.resolve(this.workingDir, p);
+    if (resolved !== this.workingDir && !resolved.startsWith(normalizedBase)) {
+      throw new Error(`Path "${p}" escapes working directory "${this.workingDir}"`);
+    }
+    return resolved;
+  }
+  async readFile(path2, _opts) {
+    return this.sandbox.files.read(this.resolvePath(path2), {
+      format: "text"
+    });
+  }
+  async readFileBytes(path2, maxBytes) {
+    const data = await this.sandbox.files.read(this.resolvePath(path2), {
+      format: "bytes"
+    });
+    const buf = Buffer.from(data);
+    if (maxBytes !== void 0 && buf.length > maxBytes) {
+      return buf.subarray(0, maxBytes);
+    }
+    return buf;
+  }
+  async writeFile(path2, content) {
+    await this.sandbox.files.write(this.resolvePath(path2), content);
+  }
+  /**
+   * @warning Not atomic. Concurrent appends may lose data due to
+   * read-then-write TOCTOU. The E2B SDK does not expose an append primitive.
+   */
+  async appendFile(path2, content) {
+    let existing = "";
+    try {
+      existing = await this.readFile(path2);
+    } catch {
+    }
+    await this.writeFile(path2, existing + content);
+  }
+  async deleteFile(path2, _opts) {
+    await this.sandbox.files.remove(this.resolvePath(path2));
+  }
+  async mkdir(path2, _opts) {
+    await this.sandbox.files.makeDir(this.resolvePath(path2));
+  }
+  async readdir(path2, _opts) {
+    const entries = await this.sandbox.files.list(this.resolvePath(path2));
+    return entries.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      isDirectory: entry.type === "dir",
+      isFile: entry.type === "file",
+      size: entry.size
+    }));
+  }
+  async exists(path2) {
+    return this.sandbox.files.exists(this.resolvePath(path2));
+  }
+  async stat(path2) {
+    const info = await this.sandbox.files.getInfo(this.resolvePath(path2));
+    return {
+      size: info.size ?? 0,
+      isDirectory: info.type === "dir",
+      isFile: info.type === "file",
+      modifiedAt: info.modifiedTime
+    };
+  }
+};
+
+// src/virtual/e2b-computer.ts
+var E2BComputer = class {
+  sandbox;
+  defaultCwd;
+  defaultTimeout;
+  constructor(opts) {
+    this.sandbox = opts.sandbox;
+    this.defaultCwd = opts.defaultCwd;
+    this.defaultTimeout = opts.defaultTimeout ?? 3e4;
+  }
+  async executeCommand(command, opts) {
+    const result = await this.sandbox.commands.run(command, {
+      cwd: opts?.cwd ?? this.defaultCwd,
+      timeout: opts?.timeout ?? this.defaultTimeout,
+      envs: opts?.env
+    });
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? ""
+    };
+  }
+};
+
+// src/virtual/e2b-sandbox.ts
+function E2BSandbox(opts) {
+  if (opts.sandbox) {
+    const s = opts.sandbox;
+    return {
+      fs: new E2BFs({ sandbox: s, workingDir: opts.cwd }),
+      computer: new E2BComputer({
+        sandbox: s,
+        defaultCwd: opts.cwd,
+        defaultTimeout: opts.defaultTimeout
+      }),
+      sandboxId: () => s.sandboxId
+    };
+  }
+  const fsProxy = createFsProxy();
+  const computerProxy = createComputerProxy();
+  let resolvedId;
+  let sandboxRef;
+  let autoCreated = false;
+  let initPromise = null;
+  async function doInit(reconnectId) {
+    const e2b = await import("e2b");
+    const SandboxClass = e2b.Sandbox ?? e2b.default?.Sandbox;
+    if (!SandboxClass) {
+      throw new Error("Could not resolve Sandbox class from 'e2b' package");
+    }
+    let sandbox;
+    if (reconnectId) {
+      try {
+        sandbox = await SandboxClass.connect(reconnectId, {
+          apiKey: opts.apiKey
+        });
+      } catch {
+        sandbox = await SandboxClass.create({
+          template: opts.template ?? "base",
+          apiKey: opts.apiKey,
+          timeoutMs: opts.timeoutMs
+        });
+        autoCreated = true;
+      }
+    } else {
+      sandbox = await SandboxClass.create({
+        template: opts.template ?? "base",
+        apiKey: opts.apiKey,
+        timeoutMs: opts.timeoutMs
+      });
+      autoCreated = true;
+    }
+    sandboxRef = sandbox;
+    resolvedId = sandbox.sandboxId ?? reconnectId;
+    fsProxy.setTarget(new E2BFs({ sandbox, workingDir: opts.cwd }));
+    computerProxy.setTarget(new E2BComputer({
+      sandbox,
+      defaultCwd: opts.cwd,
+      defaultTimeout: opts.defaultTimeout
+    }));
+  }
+  return {
+    fs: fsProxy,
+    computer: computerProxy,
+    sandboxId: () => resolvedId,
+    init(sandboxId) {
+      if (!initPromise) {
+        initPromise = doInit(sandboxId).catch((err) => {
+          initPromise = null;
+          throw err;
+        });
+      }
+      return initPromise;
+    },
+    async dispose() {
+      if (initPromise) {
+        await initPromise.catch(() => {
+        });
+      }
+      if (!autoCreated || !sandboxRef) return;
+      if (typeof sandboxRef.kill === "function") {
+        await sandboxRef.kill();
+      }
+    }
+  };
+}
+export {
+  E2BComputer,
+  E2BFs,
+  E2BSandbox
+};
+//# sourceMappingURL=e2b.js.map

package/dist/e2b.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/virtual/e2b-fs.ts","../src/virtual/e2b-computer.ts","../src/virtual/e2b-sandbox.ts"],"sourcesContent":["import * as path from \"node:path\";\nimport type { VirtualFs, FileEntry, FileStat, ReadOptions } from \"./fs.js\";\nimport type { E2BSandboxInstance } from \"./e2b-computer.js\";\n\nexport interface E2BFsOptions {\n  /** An E2B Sandbox instance created via `Sandbox.create()`. */\n  sandbox: E2BSandboxInstance;\n  /** Working directory for relative path resolution. */\n  workingDir?: string;\n}\n\n/**\n * VirtualFs backed by the E2B cloud sandbox filesystem.\n *\n * Requires `e2b` as an optional peer dependency.\n * The user is responsible for sandbox lifecycle (create, close).\n */\nexport class E2BFs implements VirtualFs {\n  private sandbox: E2BSandboxInstance;\n  private workingDir: string | undefined;\n\n  constructor(opts: E2BFsOptions) {\n    this.sandbox = opts.sandbox;\n    this.workingDir = opts.workingDir;\n  }\n\n  private resolvePath(p: string): string {\n    if (!this.workingDir) return p;\n    const normalizedBase = this.workingDir.endsWith(\"/\") ? this.workingDir : this.workingDir + \"/\";\n    if (p.startsWith(\"/\")) {\n      if (p !== this.workingDir && !p.startsWith(normalizedBase)) {\n        throw new Error(`Absolute path \"${p}\" is outside working directory \"${this.workingDir}\"`);\n      }\n      return p;\n    }\n    const resolved = path.resolve(this.workingDir, p);\n    if (resolved !== this.workingDir && !resolved.startsWith(normalizedBase)) {\n      throw new Error(`Path \"${p}\" escapes working directory \"${this.workingDir}\"`);\n    }\n    return resolved;\n  }\n\n  async readFile(path: string, _opts?: ReadOptions): Promise<string> {\n    return this.sandbox.files.read(this.resolvePath(path), {\n      format: \"text\",\n    });\n  }\n\n  async readFileBytes(path: string, maxBytes?: number): Promise<Buffer> {\n    const data = await this.sandbox.files.read(this.resolvePath(path), {\n      format: \"bytes\",\n    } as Record<string, unknown>);\n    const buf = Buffer.from(data as unknown as ArrayBuffer);\n    if (maxBytes !== undefined && buf.length > maxBytes) {\n      return buf.subarray(0, maxBytes);\n    }\n    return buf;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.sandbox.files.write(this.resolvePath(path), content);\n  }\n\n  /**\n   * @warning Not atomic. Concurrent appends may lose data due to\n   * read-then-write TOCTOU. The E2B SDK does not expose an append primitive.\n   */\n  async appendFile(path: string, content: string): Promise<void> {\n    let existing = \"\";\n    try {\n      existing = await this.readFile(path);\n    } catch {\n      // file may not exist yet\n    }\n    await this.writeFile(path, existing + content);\n  }\n\n  async deleteFile(\n    path: string,\n    _opts?: { recursive?: boolean },\n  ): Promise<void> {\n    await this.sandbox.files.remove(this.resolvePath(path));\n  }\n\n  async mkdir(path: string, _opts?: { recursive?: boolean }): Promise<void> {\n    await this.sandbox.files.makeDir(this.resolvePath(path));\n  }\n\n  async readdir(\n    path: string,\n    _opts?: { recursive?: boolean },\n  ): Promise<FileEntry[]> {\n    const entries = await this.sandbox.files.list(this.resolvePath(path));\n    return entries.map((entry) => ({\n      name: entry.name,\n      path: entry.path,\n      isDirectory: entry.type === \"dir\",\n      isFile: entry.type === \"file\",\n      size: entry.size,\n    }));\n  }\n\n  async exists(path: string): Promise<boolean> {\n    return this.sandbox.files.exists(this.resolvePath(path));\n  }\n\n  async stat(path: string): Promise<FileStat> {\n    const info = await this.sandbox.files.getInfo(this.resolvePath(path));\n    return {\n      size: info.size ?? 0,\n      isDirectory: info.type === \"dir\",\n      isFile: info.type === \"file\",\n      modifiedAt: info.modifiedTime,\n    };\n  }\n}\n","import type { VirtualComputer, ExecOptions, CommandResult } from \"./computer.js\";\n\n/**\n * Minimal subset of the E2B Sandbox interface used by E2BComputer and E2BFs.\n * Avoids a hard import of `e2b` at the module level.\n */\nexport interface E2BSandboxInstance {\n  commands: {\n    run(\n      cmd: string,\n      opts?: {\n        cwd?: string;\n        timeout?: number;\n        envs?: Record<string, string>;\n      },\n    ): Promise<{\n      exitCode: number;\n      stdout: string;\n      stderr: string;\n    }>;\n  };\n  files: {\n    read(path: string, opts?: { format?: string }): Promise<string>;\n    write(path: string, data: string): Promise<unknown>;\n    remove(path: string): Promise<void>;\n    makeDir(path: string): Promise<unknown>;\n    list(path: string): Promise<\n      Array<{\n        name: string;\n        path: string;\n        type?: string;\n        size?: number;\n        modifiedTime?: Date;\n      }>\n    >;\n    exists(path: string): Promise<boolean>;\n    getInfo(path: string): Promise<{\n      name: string;\n      path: string;\n      type?: string;\n      size?: number;\n      modifiedTime?: Date;\n    }>;\n  };\n}\n\nexport interface E2BComputerOptions {\n  /** An E2B Sandbox instance created via `Sandbox.create()`. */\n  sandbox: E2BSandboxInstance;\n  /** Default working directory for commands. */\n  defaultCwd?: string;\n  /** Default timeout in ms for commands (default: 30000). */\n  defaultTimeout?: number;\n}\n\n/**\n * VirtualComputer backed by command execution in an E2B cloud sandbox.\n *\n * Requires `e2b` as an optional peer dependency.\n * The user is responsible for sandbox lifecycle (create, close).\n */\nexport class E2BComputer implements VirtualComputer {\n  private sandbox: E2BSandboxInstance;\n  private defaultCwd: string | undefined;\n  private defaultTimeout: number;\n\n  constructor(opts: E2BComputerOptions) {\n    this.sandbox = opts.sandbox;\n    this.defaultCwd = opts.defaultCwd;\n    this.defaultTimeout = opts.defaultTimeout ?? 30_000;\n  }\n\n  async executeCommand(\n    command: string,\n    opts?: ExecOptions,\n  ): Promise<CommandResult> {\n    const result = await this.sandbox.commands.run(command, {\n      cwd: opts?.cwd ?? this.defaultCwd,\n      timeout: opts?.timeout ?? this.defaultTimeout,\n      envs: opts?.env,\n    });\n\n    return {\n      exitCode: result.exitCode,\n      stdout: result.stdout ?? \"\",\n      stderr: result.stderr ?? \"\",\n    };\n  }\n}\n","import type { Sandbox } from \"./sandbox.js\";\nimport { E2BFs } from \"./e2b-fs.js\";\nimport { E2BComputer, type E2BSandboxInstance } from \"./e2b-computer.js\";\nimport { createFsProxy, createComputerProxy } from \"./proxy.js\";\n\nexport interface E2BSandboxOptions {\n  /**\n   * A pre-existing E2B Sandbox instance (e.g. from `Sandbox.create()`).\n   * When provided the sandbox attaches to this instance — no auto-creation\n   * occurs and `dispose()` will **not** kill it.\n   *\n   * When omitted, a new E2B sandbox is created on the first `init()` call\n   * via a dynamic import of the `e2b` package. The auto-created sandbox\n   * is killed when `dispose()` is called.\n   */\n  sandbox?: E2BSandboxInstance;\n  /**\n   * E2B template to use for auto-creation (default: `\"base\"`).\n   * Only used when `sandbox` is omitted.\n   */\n  template?: string;\n  /**\n   * E2B API key. Falls back to the `E2B_API_KEY` environment variable\n   * when omitted. Only used during auto-creation.\n   */\n  apiKey?: string;\n  /** Timeout (ms) for the auto-created E2B sandbox (default: E2B SDK default). */\n  timeoutMs?: number;\n  /** Working directory inside the sandbox. */\n  cwd?: string;\n  /** Default timeout (ms) for shell commands. */\n  defaultTimeout?: number;\n}\n\n/**\n * Create a `Sandbox` backed by an E2B cloud sandbox.\n * Requires `e2b` as an optional peer dependency.\n *\n * **Auto-creation:** When `sandbox` is omitted the E2B sandbox is\n * provisioned lazily on the first `init()` call via the E2B SDK.\n * The sandbox ID is available through `sandboxId()` for session\n * persistence. Pass the stored ID back through `init(storedId)` to\n * reconnect to the same sandbox on resume (via `Sandbox.connect()`).\n *\n * **Explicit instance:** When `sandbox` is provided, `init()` binds\n * it immediately. `dispose()` is a no-op — the caller owns the\n * sandbox's lifecycle.\n *\n * @example\n * ```ts\n * // Auto-create — sandbox provisioned on first init()\n * const sandbox = E2BSandbox({ template: \"base\" });\n *\n * // Explicit — attach to pre-existing instance\n * const sandbox = E2BSandbox({ sandbox: await E2BSdk.Sandbox.create() });\n * ```\n */\nexport function E2BSandbox(opts: E2BSandboxOptions): Sandbox {\n  if (opts.sandbox) {\n    const s = opts.sandbox;\n    return {\n      fs: new E2BFs({ sandbox: s, workingDir: opts.cwd }),\n      computer: new E2BComputer({\n        sandbox: s,\n        defaultCwd: opts.cwd,\n        defaultTimeout: opts.defaultTimeout,\n      }),\n      sandboxId: () => (s as any).sandboxId as string | undefined,\n    };\n  }\n\n  const fsProxy = createFsProxy();\n  const computerProxy = createComputerProxy();\n  let resolvedId: string | undefined;\n  let sandboxRef: any;\n  let autoCreated = false;\n  let initPromise: Promise<void> | null = null;\n\n  async function doInit(reconnectId?: string): Promise<void> {\n    const e2b = await import(\"e2b\");\n    const SandboxClass = (e2b as any).Sandbox ?? (e2b as any).default?.Sandbox;\n    if (!SandboxClass) {\n      throw new Error(\"Could not resolve Sandbox class from 'e2b' package\");\n    }\n\n    let sandbox: E2BSandboxInstance;\n    if (reconnectId) {\n      try {\n        sandbox = await SandboxClass.connect(reconnectId, {\n          apiKey: opts.apiKey,\n        });\n      } catch {\n        sandbox = await SandboxClass.create({\n          template: opts.template ?? \"base\",\n          apiKey: opts.apiKey,\n          timeoutMs: opts.timeoutMs,\n        });\n        autoCreated = true;\n      }\n    } else {\n      sandbox = await SandboxClass.create({\n        template: opts.template ?? \"base\",\n        apiKey: opts.apiKey,\n        timeoutMs: opts.timeoutMs,\n      });\n      autoCreated = true;\n    }\n\n    sandboxRef = sandbox;\n    resolvedId = (sandbox as any).sandboxId ?? reconnectId;\n    fsProxy.setTarget(new E2BFs({ sandbox, workingDir: opts.cwd }));\n    computerProxy.setTarget(new E2BComputer({\n      sandbox,\n      defaultCwd: opts.cwd,\n      defaultTimeout: opts.defaultTimeout,\n    }));\n  }\n\n  return {\n    fs: fsProxy,\n    computer: computerProxy,\n    sandboxId: () => resolvedId,\n\n    init(sandboxId?: string): Promise<void> {\n      if (!initPromise) {\n        initPromise = doInit(sandboxId).catch((err) => {\n          initPromise = null;\n          throw err;\n        });\n      }\n      return initPromise;\n    },\n\n    async dispose(): Promise<void> {\n      if (initPromise) {\n        await initPromise.catch(() => {});\n      }\n      if (!autoCreated || !sandboxRef) return;\n      if (typeof sandboxRef.kill === \"function\") {\n        await sandboxRef.kill();\n      }\n    },\n  };\n}\n"],"mappings":"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","names":["path"]}

package/dist/freestyle.d.ts

@@ -0,0 +1,174 @@
+import { S as Sandbox } from './sandbox-9qeMTNrD.js';
+import { V as VirtualComputer, E as ExecOptions, C as CommandResult, a as VirtualFs, R as ReadOptions, F as FileEntry, b as FileStat } from './computer-BPdxSo6X.js';
+
+/**
+ * Minimal subset of the Freestyle VM interface used by FreestyleComputer and
+ * FreestyleFs. Avoids a hard import of `freestyle-sandboxes` at the module
+ * level — the real SDK is only loaded dynamically during `FreestyleSandbox`
+ * auto-creation.
+ */
+interface FreestyleVmInstance {
+    exec(command: string, opts?: {
+        cwd?: string;
+        timeout?: number;
+    }): Promise<{
+        stdout: string | null;
+        stderr: string | null;
+        statusCode: number | null;
+    }>;
+    fs: {
+        readTextFile(path: string): Promise<string>;
+        writeTextFile(path: string, content: string): Promise<void>;
+        readDir(path: string): Promise<Array<{
+            name: string;
+            kind: string;
+        }>>;
+    };
+    suspend(): Promise<unknown>;
+    start(): Promise<unknown>;
+}
+interface FreestyleComputerOptions {
+    /** A Freestyle VM instance. */
+    vm: FreestyleVmInstance;
+    /** Default working directory for commands. */
+    defaultCwd?: string;
+    /** Default timeout in ms for commands (default: 30000). */
+    defaultTimeout?: number;
+}
+/**
+ * VirtualComputer backed by command execution in a Freestyle VM.
+ *
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ * The user is responsible for VM lifecycle when using explicit mode.
+ */
+declare class FreestyleComputer implements VirtualComputer {
+    private vm;
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts: FreestyleComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+interface FreestyleSandboxOptions {
+    /**
+     * A pre-existing Freestyle VM instance. When provided the sandbox
+     * attaches to this VM directly — no auto-creation occurs and
+     * `dispose()` will **not** suspend or delete it.
+     *
+     * When omitted, a new VM is created on the first `init()` call via
+     * a dynamic import of the `freestyle-sandboxes` package.
+     */
+    vm?: FreestyleVmInstance;
+    /**
+     * Freestyle API key. Falls back to the `FREESTYLE_API_KEY` environment
+     * variable when omitted. Only used during auto-creation.
+     */
+    apiKey?: string;
+    /** Snapshot ID to create the VM from. Only used during auto-creation. */
+    snapshotId?: string;
+    /**
+     * A `VmSpec` instance or configuration object passed through to
+     * `freestyle.vms.create()`. Only used during auto-creation.
+     */
+    spec?: unknown;
+    /**
+     * Idle timeout in seconds for the auto-created VM (default: 600).
+     * The VM auto-suspends after this many seconds of network inactivity.
+     */
+    idleTimeoutSeconds?: number;
+    /** Working directory inside the VM. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+    /** Files to provision at creation time. */
+    additionalFiles?: Record<string, {
+        content: string;
+        encoding?: string;
+    }>;
+    /** Git repos to clone at creation time. */
+    gitRepos?: Array<{
+        repo: string;
+        path: string;
+        rev?: string;
+    }>;
+    /**
+     * What to do with auto-created VMs on `dispose()`:
+     * - `"suspend"` (default) — suspends the VM, preserving full memory
+     *   state for near-instant resume on reconnect.
+     * - `"delete"` — permanently deletes the VM and frees all resources.
+     */
+    disposeStrategy?: "suspend" | "delete";
+}
+/**
+ * Create a `Sandbox` backed by a Freestyle VM.
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ *
+ * **Auto-creation:** When `vm` is omitted a new Freestyle VM is
+ * provisioned lazily on the first `init()` call. The VM ID is available
+ * through `sandboxId()` for session persistence. Pass the stored ID back
+ * through `init(storedId)` to reconnect (this also wakes suspended VMs).
+ *
+ * By default, auto-created VMs are **suspended** on `dispose()` rather
+ * than deleted. This preserves full memory state and allows near-instant
+ * resume. Set `disposeStrategy: "delete"` for full cleanup.
+ *
+ * **Explicit instance:** When `vm` is provided, `init()` binds it
+ * immediately. `dispose()` is a no-op — the caller owns the VM's
+ * lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-create — VM provisioned on first init()
+ * const sandbox = FreestyleSandbox({ cwd: "/workspace" });
+ *
+ * // Auto-create from a snapshot
+ * const sandbox = FreestyleSandbox({
+ *   snapshotId: "abc123",
+ *   cwd: "/workspace",
+ * });
+ *
+ * // Explicit — attach to pre-existing VM
+ * const sandbox = FreestyleSandbox({ vm: existingVm });
+ * ```
+ */
+declare function FreestyleSandbox(opts: FreestyleSandboxOptions): Sandbox;
+
+interface FreestyleFsOptions {
+    /** A Freestyle VM instance. */
+    vm: FreestyleVmInstance;
+    /** Working directory for relative path resolution. */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by a Freestyle VM.
+ *
+ * Uses `vm.fs.*` for operations with native SDK support (readTextFile,
+ * writeTextFile, readDir) and falls back to `vm.exec()` for the rest
+ * (stat, exists, mkdir, deleteFile, appendFile, readFileBytes).
+ *
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ * The user is responsible for VM lifecycle when using explicit mode.
+ */
+declare class FreestyleFs implements VirtualFs {
+    private vm;
+    private workingDir;
+    constructor(opts: FreestyleFsOptions);
+    private resolvePath;
+    readFile(filePath: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    appendFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(dirPath: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    stat(filePath: string): Promise<FileStat>;
+}
+
+export { FreestyleComputer, type FreestyleComputerOptions, FreestyleFs, type FreestyleFsOptions, FreestyleSandbox, type FreestyleSandboxOptions, type FreestyleVmInstance };