noumen 0.4.0 → 0.6.0

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 };

package/dist/freestyle.js

@@ -0,0 +1,240 @@
+import {
+  createComputerProxy,
+  createFsProxy
+} from "./chunk-I5SBSOS6.js";
+import "./chunk-DGUM43GV.js";
+
+// src/virtual/freestyle-fs.ts
+import * as path from "path";
+var FreestyleFs = class {
+  vm;
+  workingDir;
+  constructor(opts) {
+    this.vm = opts.vm;
+    this.workingDir = opts.workingDir;
+  }
+  resolvePath(p) {
+    if (p.includes("\0")) {
+      throw new Error("Path contains null bytes");
+    }
+    if (!this.workingDir) return p;
+    const normalizedBase = this.workingDir.endsWith("/") ? this.workingDir : this.workingDir + "/";
+    if (p.startsWith("/")) {
+      const normalized = path.normalize(p);
+      if (normalized !== this.workingDir && !normalized.startsWith(normalizedBase)) {
+        throw new Error(`Absolute path "${p}" is outside working directory "${this.workingDir}"`);
+      }
+      return normalized;
+    }
+    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(filePath, _opts) {
+    return this.vm.fs.readTextFile(this.resolvePath(filePath));
+  }
+  async readFileBytes(filePath, maxBytes) {
+    const resolved = this.resolvePath(filePath);
+    const cmd = maxBytes !== void 0 ? `head -c ${maxBytes} ${shellEscape(resolved)} | base64` : `base64 ${shellEscape(resolved)}`;
+    const { statusCode, stdout, stderr } = await this.vm.exec(cmd);
+    if (statusCode !== 0) {
+      throw new Error(`FreestyleFs readFileBytes failed: ${stderr?.trim() || `exit code ${statusCode}`}`);
+    }
+    return Buffer.from((stdout ?? "").trim(), "base64");
+  }
+  async writeFile(filePath, content) {
+    await this.vm.fs.writeTextFile(this.resolvePath(filePath), content);
+  }
+  async appendFile(filePath, content) {
+    const resolved = this.resolvePath(filePath);
+    const encoded = Buffer.from(content, "utf-8").toString("base64");
+    const { statusCode, stderr } = await this.vm.exec(
+      `echo ${shellEscape(encoded)} | base64 -d >> ${shellEscape(resolved)}`
+    );
+    if (statusCode !== 0) {
+      throw new Error(`FreestyleFs appendFile failed: ${stderr?.trim() || `exit code ${statusCode}`}`);
+    }
+  }
+  async deleteFile(filePath, opts) {
+    const resolved = this.resolvePath(filePath);
+    const flag = opts?.recursive ? "-rf" : "-f";
+    await this.vm.exec(`rm ${flag} ${shellEscape(resolved)}`);
+  }
+  async mkdir(filePath, opts) {
+    const resolved = this.resolvePath(filePath);
+    const flag = opts?.recursive ? "-p " : "";
+    await this.vm.exec(`mkdir ${flag}${shellEscape(resolved)}`);
+  }
+  async readdir(dirPath, _opts) {
+    const resolved = this.resolvePath(dirPath);
+    const items = await this.vm.fs.readDir(resolved);
+    return items.map((entry) => ({
+      name: entry.name,
+      path: resolved === "/" ? `/${entry.name}` : `${resolved}/${entry.name}`,
+      isDirectory: entry.kind === "dir" || entry.kind === "directory",
+      isFile: entry.kind === "file"
+    }));
+  }
+  async exists(filePath) {
+    const resolved = this.resolvePath(filePath);
+    const { statusCode } = await this.vm.exec(`test -e ${shellEscape(resolved)}`);
+    return statusCode === 0;
+  }
+  async stat(filePath) {
+    const resolved = this.resolvePath(filePath);
+    const { statusCode, stdout, stderr } = await this.vm.exec(
+      `stat -c '%s	%F	%W	%Y' ${shellEscape(resolved)}`
+    );
+    if (statusCode !== 0) {
+      throw new Error(`FreestyleFs stat failed: ${stderr?.trim() || `exit code ${statusCode}`}`);
+    }
+    const parts = (stdout ?? "").trim().split("	");
+    const size = parseInt(parts[0], 10);
+    const fileType = parts[1];
+    const createdEpoch = parseInt(parts[2], 10);
+    const modifiedEpoch = parseInt(parts[3], 10);
+    return {
+      size,
+      isDirectory: fileType === "directory",
+      isFile: fileType.startsWith("regular"),
+      createdAt: createdEpoch > 0 ? new Date(createdEpoch * 1e3) : void 0,
+      modifiedAt: modifiedEpoch > 0 ? new Date(modifiedEpoch * 1e3) : void 0
+    };
+  }
+};
+function shellEscape(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+// src/virtual/freestyle-computer.ts
+var FreestyleComputer = class {
+  vm;
+  defaultCwd;
+  defaultTimeout;
+  constructor(opts) {
+    this.vm = opts.vm;
+    this.defaultCwd = opts.defaultCwd;
+    this.defaultTimeout = opts.defaultTimeout ?? 3e4;
+  }
+  async executeCommand(command, opts) {
+    const result = await this.vm.exec(command, {
+      cwd: opts?.cwd ?? this.defaultCwd,
+      timeout: opts?.timeout ?? this.defaultTimeout
+    });
+    return {
+      exitCode: result.statusCode ?? 1,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? ""
+    };
+  }
+};
+
+// src/virtual/freestyle-sandbox.ts
+function FreestyleSandbox(opts) {
+  if (opts.vm) {
+    const v = opts.vm;
+    return {
+      fs: new FreestyleFs({ vm: v, workingDir: opts.cwd }),
+      computer: new FreestyleComputer({
+        vm: v,
+        defaultCwd: opts.cwd,
+        defaultTimeout: opts.defaultTimeout
+      }),
+      sandboxId: () => v.vmId
+    };
+  }
+  const fsProxy = createFsProxy();
+  const computerProxy = createComputerProxy();
+  let resolvedId;
+  let vmRef = null;
+  let autoCreated = false;
+  let initPromise = null;
+  async function doInit(reconnectId) {
+    const mod = await import("freestyle-sandboxes");
+    const freestyle = mod.freestyle ?? mod.default?.freestyle;
+    if (!freestyle?.vms) {
+      throw new Error("Could not resolve freestyle client from 'freestyle-sandboxes' package");
+    }
+    let vm;
+    if (reconnectId) {
+      try {
+        const result = await freestyle.vms.get({ vmId: reconnectId });
+        vm = result.vm;
+        resolvedId = reconnectId;
+      } catch {
+        const result = await freestyle.vms.create({
+          ...opts.spec ? { spec: opts.spec } : {},
+          snapshotId: opts.snapshotId,
+          workdir: opts.cwd,
+          idleTimeoutSeconds: opts.idleTimeoutSeconds ?? 600,
+          additionalFiles: opts.additionalFiles,
+          gitRepos: opts.gitRepos
+        });
+        vm = result.vm;
+        resolvedId = result.vmId ?? result.id;
+        autoCreated = true;
+      }
+    } else {
+      const result = await freestyle.vms.create({
+        ...opts.spec ? { spec: opts.spec } : {},
+        snapshotId: opts.snapshotId,
+        workdir: opts.cwd,
+        idleTimeoutSeconds: opts.idleTimeoutSeconds ?? 600,
+        additionalFiles: opts.additionalFiles,
+        gitRepos: opts.gitRepos
+      });
+      vm = result.vm;
+      resolvedId = result.vmId ?? result.id;
+      autoCreated = true;
+    }
+    vmRef = vm;
+    fsProxy.setTarget(new FreestyleFs({ vm, workingDir: opts.cwd }));
+    computerProxy.setTarget(new FreestyleComputer({
+      vm,
+      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 || !vmRef || !resolvedId) return;
+      try {
+        const strategy = opts.disposeStrategy ?? "suspend";
+        if (strategy === "suspend") {
+          await vmRef.suspend();
+        } else {
+          const mod = await import("freestyle-sandboxes");
+          const freestyle = mod.freestyle ?? mod.default?.freestyle;
+          if (freestyle?.vms) {
+            await freestyle.vms.delete({ vmId: resolvedId });
+          }
+        }
+      } catch {
+      }
+    }
+  };
+}
+export {
+  FreestyleComputer,
+  FreestyleFs,
+  FreestyleSandbox
+};
+//# sourceMappingURL=freestyle.js.map