noumen 0.3.0 → 0.5.0

package/dist/sprites.js

@@ -0,0 +1,334 @@
+import {
+  createComputerProxy,
+  createFsProxy
+} from "./chunk-I5SBSOS6.js";
+import "./chunk-DGUM43GV.js";
+
+// src/virtual/sprites-fs.ts
+import * as path from "path";
+var SpritesFs = class {
+  token;
+  spriteName;
+  baseURL;
+  workingDir;
+  constructor(opts) {
+    this.token = opts.token;
+    this.spriteName = opts.spriteName;
+    this.baseURL = (opts.baseURL ?? "https://api.sprites.dev").replace(
+      /\/$/,
+      ""
+    );
+    this.workingDir = opts.workingDir ?? "/home/sprite";
+  }
+  fsUrl(endpoint, params) {
+    const url = new URL(
+      `${this.baseURL}/v1/sprites/${this.spriteName}/fs${endpoint}`
+    );
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        url.searchParams.set(k, v);
+      }
+    }
+    return url.toString();
+  }
+  resolvePath(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;
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.token}`
+    };
+  }
+  async readFile(filePath, _opts) {
+    const url = this.fsUrl("/read", { path: this.resolvePath(filePath) });
+    const res = await fetch(url, { headers: this.headers() });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs readFile failed (${res.status}): ${await res.text()}`
+      );
+    }
+    return res.text();
+  }
+  async readFileBytes(filePath, maxBytes) {
+    const url = this.fsUrl("/read", {
+      path: this.resolvePath(filePath),
+      binary: "true"
+    });
+    const res = await fetch(url, { headers: this.headers() });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs readFileBytes failed (${res.status}): ${await res.text()}`
+      );
+    }
+    const arrayBuf = await res.arrayBuffer();
+    const buf = Buffer.from(arrayBuf);
+    if (maxBytes !== void 0 && buf.length > maxBytes) {
+      return buf.subarray(0, maxBytes);
+    }
+    return buf;
+  }
+  async writeFile(filePath, content) {
+    const url = this.fsUrl("/write");
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...this.headers(),
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path: this.resolvePath(filePath),
+        content
+      })
+    });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs writeFile failed (${res.status}): ${await res.text()}`
+      );
+    }
+  }
+  /**
+   * @warning Not atomic. Concurrent appends may lose data due to
+   * read-then-write TOCTOU. The Sprites API does not expose an append primitive.
+   */
+  async appendFile(filePath, content) {
+    let existing = "";
+    try {
+      existing = await this.readFile(filePath);
+    } catch {
+    }
+    await this.writeFile(filePath, existing + content);
+  }
+  async deleteFile(filePath, opts) {
+    const url = this.fsUrl("/remove");
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...this.headers(),
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path: this.resolvePath(filePath),
+        recursive: opts?.recursive ?? false
+      })
+    });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs deleteFile failed (${res.status}): ${await res.text()}`
+      );
+    }
+  }
+  async mkdir(dirPath, opts) {
+    const url = this.fsUrl("/mkdir");
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...this.headers(),
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path: this.resolvePath(dirPath),
+        recursive: opts?.recursive ?? false
+      })
+    });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs mkdir failed (${res.status}): ${await res.text()}`
+      );
+    }
+  }
+  async readdir(dirPath, _opts) {
+    const url = this.fsUrl("/readdir", { path: this.resolvePath(dirPath) });
+    const res = await fetch(url, { headers: this.headers() });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs readdir failed (${res.status}): ${await res.text()}`
+      );
+    }
+    const data = await res.json();
+    return data.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      isDirectory: entry.is_dir,
+      isFile: !entry.is_dir,
+      size: entry.size
+    }));
+  }
+  async exists(filePath) {
+    try {
+      await this.stat(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async stat(filePath) {
+    const url = this.fsUrl("/stat", { path: this.resolvePath(filePath) });
+    const res = await fetch(url, { headers: this.headers() });
+    if (!res.ok) {
+      throw new Error(
+        `SpritesFs stat failed (${res.status}): ${await res.text()}`
+      );
+    }
+    const data = await res.json();
+    return {
+      size: data.size,
+      isDirectory: data.is_dir,
+      isFile: !data.is_dir,
+      createdAt: data.created_at ? new Date(data.created_at) : void 0,
+      modifiedAt: data.modified_at ? new Date(data.modified_at) : void 0
+    };
+  }
+};
+
+// src/virtual/sprites-computer.ts
+var SpritesComputer = class {
+  token;
+  spriteName;
+  baseURL;
+  workingDir;
+  constructor(opts) {
+    this.token = opts.token;
+    this.spriteName = opts.spriteName;
+    this.baseURL = (opts.baseURL ?? "https://api.sprites.dev").replace(
+      /\/$/,
+      ""
+    );
+    this.workingDir = opts.workingDir ?? "/home/sprite";
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      "Content-Type": "application/json"
+    };
+  }
+  async executeCommand(command, opts) {
+    const cwd = opts?.cwd ?? this.workingDir;
+    const wrappedCommand = `cd ${this.shellEscape(cwd)} && ${command}`;
+    const url = `${this.baseURL}/v1/sprites/${this.spriteName}/exec`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({
+        command: ["bash", "-c", wrappedCommand],
+        timeout: opts?.timeout ?? 3e4,
+        env: opts?.env
+      })
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `Sprites exec failed (${res.status}): ${text}`
+      };
+    }
+    const data = await res.json();
+    return {
+      exitCode: data.exit_code,
+      stdout: data.stdout ?? "",
+      stderr: data.stderr ?? ""
+    };
+  }
+  shellEscape(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+  }
+};
+
+// src/virtual/sprites-sandbox.ts
+function SpritesSandbox(opts) {
+  const baseURL = (opts.baseURL ?? "https://api.sprites.dev").replace(/\/$/, "");
+  const userProvidedName = opts.spriteName;
+  if (userProvidedName) {
+    const fsOpts = { ...opts, spriteName: userProvidedName };
+    return {
+      fs: new SpritesFs(fsOpts),
+      computer: new SpritesComputer(fsOpts),
+      sandboxId: () => userProvidedName
+    };
+  }
+  const fsProxy = createFsProxy();
+  const computerProxy = createComputerProxy();
+  let resolvedName;
+  let autoCreated = false;
+  let initPromise = null;
+  async function doInit(reconnectId) {
+    let name = reconnectId ?? `${opts.namePrefix ?? "noumen-"}${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let needsCreate = !reconnectId;
+    if (reconnectId) {
+      const check = await fetch(`${baseURL}/v1/sprites/${reconnectId}`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${opts.token}` }
+      });
+      if (!check.ok) {
+        name = `${opts.namePrefix ?? "noumen-"}${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        needsCreate = true;
+      }
+    }
+    if (needsCreate) {
+      const res = await fetch(`${baseURL}/v1/sprites`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${opts.token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ name })
+      });
+      if (!res.ok) {
+        throw new Error(`Sprites auto-create failed (${res.status}): ${await res.text()}`);
+      }
+      autoCreated = true;
+    }
+    resolvedName = name;
+    const childOpts = { ...opts, spriteName: name };
+    fsProxy.setTarget(new SpritesFs(childOpts));
+    computerProxy.setTarget(new SpritesComputer(childOpts));
+  }
+  return {
+    fs: fsProxy,
+    computer: computerProxy,
+    sandboxId: () => resolvedName,
+    init(sandboxId) {
+      if (!initPromise) {
+        initPromise = doInit(sandboxId).catch((err) => {
+          initPromise = null;
+          throw err;
+        });
+      }
+      return initPromise;
+    },
+    async dispose() {
+      if (initPromise) {
+        await initPromise.catch(() => {
+        });
+      }
+      if (!autoCreated || !resolvedName) return;
+      try {
+        const res = await fetch(`${baseURL}/v1/sprites/${resolvedName}`, {
+          method: "DELETE",
+          headers: { Authorization: `Bearer ${opts.token}` }
+        });
+        if (!res.ok && res.status !== 404) {
+          throw new Error(`Sprites dispose failed (${res.status}): ${await res.text()}`);
+        }
+      } catch {
+      }
+    }
+  };
+}
+export {
+  SpritesComputer,
+  SpritesFs,
+  SpritesSandbox
+};
+//# sourceMappingURL=sprites.js.map

package/dist/sprites.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/virtual/sprites-fs.ts","../src/virtual/sprites-computer.ts","../src/virtual/sprites-sandbox.ts"],"sourcesContent":["import * as path from \"node:path\";\nimport type { VirtualFs, FileEntry, FileStat, ReadOptions } from \"./fs.js\";\n\nexport interface SpritesFsOptions {\n  /** sprites.dev API token */\n  token: string;\n  /** Name of the sprite container */\n  spriteName: string;\n  /** Base URL for sprites API (default: https://api.sprites.dev) */\n  baseURL?: string;\n  /** Working directory inside the sprite (default: /home/sprite) */\n  workingDir?: string;\n}\n\n/**\n * Sandboxed VirtualFs backed by a remote sprites.dev container. All file\n * operations are executed over the sprites.dev HTTP API — the agent has no\n * access to the host filesystem. This is the recommended VirtualFs for\n * production deployments and untrusted agents. See `LocalFs` for an\n * unsandboxed local alternative.\n */\nexport class SpritesFs implements VirtualFs {\n  private token: string;\n  private spriteName: string;\n  private baseURL: string;\n  private workingDir: string;\n\n  constructor(opts: SpritesFsOptions) {\n    this.token = opts.token;\n    this.spriteName = opts.spriteName;\n    this.baseURL = (opts.baseURL ?? \"https://api.sprites.dev\").replace(\n      /\\/$/,\n      \"\",\n    );\n    this.workingDir = opts.workingDir ?? \"/home/sprite\";\n  }\n\n  private fsUrl(endpoint: string, params?: Record<string, string>): string {\n    const url = new URL(\n      `${this.baseURL}/v1/sprites/${this.spriteName}/fs${endpoint}`,\n    );\n    if (params) {\n      for (const [k, v] of Object.entries(params)) {\n        url.searchParams.set(k, v);\n      }\n    }\n    return url.toString();\n  }\n\n  private resolvePath(p: string): string {\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  private headers(): Record<string, string> {\n    return {\n      Authorization: `Bearer ${this.token}`,\n    };\n  }\n\n  async readFile(filePath: string, _opts?: ReadOptions): Promise<string> {\n    const url = this.fsUrl(\"/read\", { path: this.resolvePath(filePath) });\n    const res = await fetch(url, { headers: this.headers() });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs readFile failed (${res.status}): ${await res.text()}`,\n      );\n    }\n    return res.text();\n  }\n\n  async readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer> {\n    const url = this.fsUrl(\"/read\", {\n      path: this.resolvePath(filePath),\n      binary: \"true\",\n    });\n    const res = await fetch(url, { headers: this.headers() });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs readFileBytes failed (${res.status}): ${await res.text()}`,\n      );\n    }\n    const arrayBuf = await res.arrayBuffer();\n    const buf = Buffer.from(arrayBuf);\n    if (maxBytes !== undefined && buf.length > maxBytes) {\n      return buf.subarray(0, maxBytes);\n    }\n    return buf;\n  }\n\n  async writeFile(filePath: string, content: string): Promise<void> {\n    const url = this.fsUrl(\"/write\");\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        ...this.headers(),\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({\n        path: this.resolvePath(filePath),\n        content,\n      }),\n    });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs writeFile failed (${res.status}): ${await res.text()}`,\n      );\n    }\n  }\n\n  /**\n   * @warning Not atomic. Concurrent appends may lose data due to\n   * read-then-write TOCTOU. The Sprites API does not expose an append primitive.\n   */\n  async appendFile(filePath: string, content: string): Promise<void> {\n    let existing = \"\";\n    try {\n      existing = await this.readFile(filePath);\n    } catch {\n      // file may not exist yet\n    }\n    await this.writeFile(filePath, existing + content);\n  }\n\n  async deleteFile(\n    filePath: string,\n    opts?: { recursive?: boolean },\n  ): Promise<void> {\n    const url = this.fsUrl(\"/remove\");\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        ...this.headers(),\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({\n        path: this.resolvePath(filePath),\n        recursive: opts?.recursive ?? false,\n      }),\n    });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs deleteFile failed (${res.status}): ${await res.text()}`,\n      );\n    }\n  }\n\n  async mkdir(\n    dirPath: string,\n    opts?: { recursive?: boolean },\n  ): Promise<void> {\n    const url = this.fsUrl(\"/mkdir\");\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        ...this.headers(),\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({\n        path: this.resolvePath(dirPath),\n        recursive: opts?.recursive ?? false,\n      }),\n    });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs mkdir failed (${res.status}): ${await res.text()}`,\n      );\n    }\n  }\n\n  async readdir(\n    dirPath: string,\n    _opts?: { recursive?: boolean },\n  ): Promise<FileEntry[]> {\n    const url = this.fsUrl(\"/readdir\", { path: this.resolvePath(dirPath) });\n    const res = await fetch(url, { headers: this.headers() });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs readdir failed (${res.status}): ${await res.text()}`,\n      );\n    }\n    const data = (await res.json()) as Array<{\n      name: string;\n      path: string;\n      is_dir: boolean;\n      size?: number;\n    }>;\n    return data.map((entry) => ({\n      name: entry.name,\n      path: entry.path,\n      isDirectory: entry.is_dir,\n      isFile: !entry.is_dir,\n      size: entry.size,\n    }));\n  }\n\n  async exists(filePath: string): Promise<boolean> {\n    try {\n      await this.stat(filePath);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  async stat(filePath: string): Promise<FileStat> {\n    const url = this.fsUrl(\"/stat\", { path: this.resolvePath(filePath) });\n    const res = await fetch(url, { headers: this.headers() });\n    if (!res.ok) {\n      throw new Error(\n        `SpritesFs stat failed (${res.status}): ${await res.text()}`,\n      );\n    }\n    const data = (await res.json()) as {\n      size: number;\n      is_dir: boolean;\n      created_at?: string;\n      modified_at?: string;\n    };\n    return {\n      size: data.size,\n      isDirectory: data.is_dir,\n      isFile: !data.is_dir,\n      createdAt: data.created_at ? new Date(data.created_at) : undefined,\n      modifiedAt: data.modified_at ? new Date(data.modified_at) : undefined,\n    };\n  }\n}\n","import type {\n  VirtualComputer,\n  ExecOptions,\n  CommandResult,\n} from \"./computer.js\";\n\nexport interface SpritesComputerOptions {\n  /** sprites.dev API token */\n  token: string;\n  /** Name of the sprite container */\n  spriteName: string;\n  /** Base URL for sprites API (default: https://api.sprites.dev) */\n  baseURL?: string;\n  /** Working directory inside the sprite (default: /home/sprite) */\n  workingDir?: string;\n}\n\n/**\n * Sandboxed VirtualComputer that executes commands inside a remote\n * sprites.dev container. All shell execution is fully isolated — the agent\n * has no access to the host machine's processes, filesystem, or network.\n *\n * This is the recommended VirtualComputer for production deployments and\n * untrusted agents. See `LocalComputer` for an unsandboxed local alternative.\n *\n * Uses the non-interactive exec REST endpoint (POST command, receive\n * stdout/stderr/exit_code). The WebSocket exec endpoint can be used for\n * streaming/TTY use cases, but REST is sufficient for tool calls.\n */\nexport class SpritesComputer implements VirtualComputer {\n  private token: string;\n  private spriteName: string;\n  private baseURL: string;\n  private workingDir: string;\n\n  constructor(opts: SpritesComputerOptions) {\n    this.token = opts.token;\n    this.spriteName = opts.spriteName;\n    this.baseURL = (opts.baseURL ?? \"https://api.sprites.dev\").replace(\n      /\\/$/,\n      \"\",\n    );\n    this.workingDir = opts.workingDir ?? \"/home/sprite\";\n  }\n\n  private headers(): Record<string, string> {\n    return {\n      Authorization: `Bearer ${this.token}`,\n      \"Content-Type\": \"application/json\",\n    };\n  }\n\n  async executeCommand(\n    command: string,\n    opts?: ExecOptions,\n  ): Promise<CommandResult> {\n    const cwd = opts?.cwd ?? this.workingDir;\n    const wrappedCommand = `cd ${this.shellEscape(cwd)} && ${command}`;\n\n    const url = `${this.baseURL}/v1/sprites/${this.spriteName}/exec`;\n\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: this.headers(),\n      body: JSON.stringify({\n        command: [\"bash\", \"-c\", wrappedCommand],\n        timeout: opts?.timeout ?? 30_000,\n        env: opts?.env,\n      }),\n    });\n\n    if (!res.ok) {\n      const text = await res.text();\n      return {\n        exitCode: 1,\n        stdout: \"\",\n        stderr: `Sprites exec failed (${res.status}): ${text}`,\n      };\n    }\n\n    const data = (await res.json()) as {\n      exit_code: number;\n      stdout: string;\n      stderr: string;\n    };\n\n    return {\n      exitCode: data.exit_code,\n      stdout: data.stdout ?? \"\",\n      stderr: data.stderr ?? \"\",\n    };\n  }\n\n  private shellEscape(s: string): string {\n    return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n  }\n}\n","import type { Sandbox } from \"./sandbox.js\";\nimport { SpritesFs } from \"./sprites-fs.js\";\nimport { SpritesComputer } from \"./sprites-computer.js\";\nimport { createFsProxy, createComputerProxy } from \"./proxy.js\";\n\nexport interface SpritesSandboxOptions {\n  /** sprites.dev API token. */\n  token: string;\n  /**\n   * Name of an existing sprite container. When provided the sandbox\n   * attaches to this sprite directly — no auto-creation occurs and\n   * `dispose()` will **not** delete it (lifecycle is yours to manage).\n   *\n   * When omitted a new sprite is provisioned on the first `init()` call\n   * (via `POST /v1/sprites`). The auto-created sprite is deleted when\n   * `dispose()` is called, and its name is available via `sandboxId()`\n   * for session persistence.\n   */\n  spriteName?: string;\n  /** Base URL for sprites API (default: https://api.sprites.dev). */\n  baseURL?: string;\n  /** Working directory inside the sprite (default: /home/sprite). */\n  workingDir?: string;\n  /**\n   * Optional prefix for auto-generated sprite names (default: \"noumen-\").\n   * Only used when `spriteName` is omitted.\n   */\n  namePrefix?: string;\n}\n\n/**\n * Create a `Sandbox` backed by a remote sprites.dev container.\n * Full isolation — the agent has no access to the host machine.\n *\n * **Auto-creation:** When `spriteName` is omitted the sandbox is created\n * lazily on the first `init()` call via the Sprites REST API. The sprite\n * name is available through `sandboxId()` so callers can persist it in\n * session metadata for reconnection on resume. Pass the stored name back\n * through `init(storedId)` to reattach instead of creating a new sprite.\n *\n * **Explicit ID:** When `spriteName` is provided the sandbox attaches to\n * that sprite immediately on `init()`. `dispose()` is a no-op in this\n * case — the caller owns the sprite's lifecycle.\n *\n * @example\n * ```ts\n * // Auto-create — sprite provisioned on first init()\n * const sandbox = SpritesSandbox({ token: process.env.SPRITES_TOKEN! });\n *\n * // Explicit — attach to pre-existing sprite, no auto-lifecycle\n * const sandbox = SpritesSandbox({\n *   token: process.env.SPRITES_TOKEN!,\n *   spriteName: \"my-sprite\",\n * });\n * ```\n */\nexport function SpritesSandbox(opts: SpritesSandboxOptions): Sandbox {\n  const baseURL = (opts.baseURL ?? \"https://api.sprites.dev\").replace(/\\/$/, \"\");\n  const userProvidedName = opts.spriteName;\n\n  if (userProvidedName) {\n    const fsOpts = { ...opts, spriteName: userProvidedName };\n    return {\n      fs: new SpritesFs(fsOpts),\n      computer: new SpritesComputer(fsOpts),\n      sandboxId: () => userProvidedName,\n    };\n  }\n\n  const fsProxy = createFsProxy();\n  const computerProxy = createComputerProxy();\n  let resolvedName: string | undefined;\n  let autoCreated = false;\n  let initPromise: Promise<void> | null = null;\n\n  async function doInit(reconnectId?: string): Promise<void> {\n    let name = reconnectId ?? `${opts.namePrefix ?? \"noumen-\"}${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n    let needsCreate = !reconnectId;\n\n    if (reconnectId) {\n      const check = await fetch(`${baseURL}/v1/sprites/${reconnectId}`, {\n        method: \"GET\",\n        headers: { Authorization: `Bearer ${opts.token}` },\n      });\n      if (!check.ok) {\n        name = `${opts.namePrefix ?? \"noumen-\"}${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n        needsCreate = true;\n      }\n    }\n\n    if (needsCreate) {\n      const res = await fetch(`${baseURL}/v1/sprites`, {\n        method: \"POST\",\n        headers: {\n          Authorization: `Bearer ${opts.token}`,\n          \"Content-Type\": \"application/json\",\n        },\n        body: JSON.stringify({ name }),\n      });\n      if (!res.ok) {\n        throw new Error(`Sprites auto-create failed (${res.status}): ${await res.text()}`);\n      }\n      autoCreated = true;\n    }\n\n    resolvedName = name;\n    const childOpts = { ...opts, spriteName: name };\n    fsProxy.setTarget(new SpritesFs(childOpts));\n    computerProxy.setTarget(new SpritesComputer(childOpts));\n  }\n\n  return {\n    fs: fsProxy,\n    computer: computerProxy,\n    sandboxId: () => resolvedName,\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 || !resolvedName) return;\n      try {\n        const res = await fetch(`${baseURL}/v1/sprites/${resolvedName}`, {\n          method: \"DELETE\",\n          headers: { Authorization: `Bearer ${opts.token}` },\n        });\n        if (!res.ok && res.status !== 404) {\n          throw new Error(`Sprites dispose failed (${res.status}): ${await res.text()}`);\n        }\n      } catch {\n        // Best-effort cleanup — network errors during dispose are non-fatal\n      }\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/ssh.d.ts

@@ -0,0 +1,187 @@
+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 ssh2 Channel interface used by SshComputer / SshFs.
+ * Avoids a hard import of ssh2 at the module level.
+ */
+interface SshChannel {
+    on(event: string, listener: (...args: any[]) => void): SshChannel;
+    stderr: {
+        on(event: string, listener: (...args: any[]) => void): unknown;
+    };
+    destroy?(): void;
+}
+/**
+ * Minimal subset of the ssh2 SFTPWrapper interface used by SshFs.
+ */
+interface SshSftpSession {
+    readFile(path: string, callback: (err: Error | undefined, data: Buffer) => void): void;
+    readFile(path: string, opts: {
+        encoding: string;
+    }, callback: (err: Error | undefined, data: string) => void): void;
+    writeFile(path: string, data: string | Buffer, callback: (err: Error | undefined) => void): void;
+    appendFile(path: string, data: string | Buffer, callback: (err: Error | undefined) => void): void;
+    unlink(path: string, callback: (err: Error | undefined) => void): void;
+    rmdir(path: string, callback: (err: Error | undefined) => void): void;
+    mkdir(path: string, callback: (err: Error | undefined) => void): void;
+    readdir(path: string, callback: (err: Error | undefined, list: Array<{
+        filename: string;
+        longname: string;
+        attrs: {
+            size: number;
+            isDirectory(): boolean;
+            isFile(): boolean;
+            mtime: number;
+            atime: number;
+        };
+    }>) => void): void;
+    stat(path: string, callback: (err: Error | undefined, stats: {
+        size: number;
+        isDirectory(): boolean;
+        isFile(): boolean;
+        mtime: number;
+        atime: number;
+    }) => void): void;
+    open(path: string, flags: string, callback: (err: Error | undefined, handle: Buffer) => void): void;
+    read(handle: Buffer, buffer: Buffer, offset: number, length: number, position: number, callback: (err: Error | undefined, bytesRead: number, buf: Buffer) => void): void;
+    close(handle: Buffer, callback: (err: Error | undefined) => void): void;
+    end(): void;
+}
+/**
+ * Minimal subset of the ssh2 Client interface used by SshComputer and SshFs.
+ * Avoids a hard import of ssh2 at the module level.
+ */
+interface SshClient {
+    exec(command: string, callback: (err: Error | undefined, channel: SshChannel) => void): void;
+    exec(command: string, opts: Record<string, unknown>, callback: (err: Error | undefined, channel: SshChannel) => void): void;
+    sftp(callback: (err: Error | undefined, sftp: SshSftpSession) => void): void;
+    end(): void;
+    on(event: string, listener: (...args: any[]) => void): this;
+}
+interface SshComputerOptions {
+    /** A connected ssh2 Client instance. */
+    client: SshClient;
+    /** Default working directory for commands (default: /). */
+    defaultCwd?: string;
+    /** Default timeout in ms for commands (default: 30000). */
+    defaultTimeout?: number;
+}
+/**
+ * VirtualComputer backed by command execution over SSH.
+ *
+ * Requires `ssh2` as an optional peer dependency.
+ * The caller is responsible for the Client lifecycle (connect, end).
+ */
+declare class SshComputer implements VirtualComputer {
+    private client;
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts: SshComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+interface SshSandboxOptions {
+    /**
+     * A pre-connected ssh2 Client instance. When provided the sandbox uses
+     * this client directly — no auto-connect occurs and `dispose()` will
+     * **not** call `client.end()`.
+     *
+     * When omitted, a new ssh2 Client is created and connected on the first
+     * `init()` call using `host`, `port`, `username`, and the provided
+     * credentials. The client is ended when `dispose()` is called.
+     */
+    client?: SshClient;
+    /**
+     * SSH hostname. Required when `client` is omitted; ignored when `client`
+     * is provided.
+     */
+    host?: string;
+    /** SSH port (default: 22). Only used during auto-connect. */
+    port?: number;
+    /** SSH username (default: "root"). Only used during auto-connect. */
+    username?: string;
+    /** Password for password-based authentication. Only used during auto-connect. */
+    password?: string;
+    /** Private key for key-based authentication (PEM string or Buffer). Only used during auto-connect. */
+    privateKey?: string | Buffer;
+    /** Passphrase for an encrypted private key. Only used during auto-connect. */
+    passphrase?: string;
+    /** Working directory on the remote host. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+}
+/**
+ * Create a `Sandbox` backed by a remote host over SSH.
+ * Requires `ssh2` as an optional peer dependency.
+ *
+ * **Auto-connect:** When `client` is omitted and `host` is provided,
+ * an ssh2 Client is created and connected lazily on the first `init()`
+ * call. The connection identifier (`host:port`) is available through
+ * `sandboxId()` for session persistence.
+ *
+ * **Explicit client:** When `client` is provided, `init()` binds it
+ * immediately. `dispose()` is a no-op — the caller owns the client's
+ * lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-connect with private key
+ * const sandbox = SshSandbox({
+ *   host: "dev.example.com",
+ *   username: "deploy",
+ *   privateKey: fs.readFileSync("~/.ssh/id_ed25519"),
+ *   cwd: "/home/deploy/project",
+ * });
+ *
+ * // Explicit client (lifecycle managed externally)
+ * const sandbox = SshSandbox({ client: myConnectedClient, cwd: "/workspace" });
+ * ```
+ */
+declare function SshSandbox(opts: SshSandboxOptions): Sandbox;
+
+interface SshFsOptions {
+    /** A connected ssh2 Client instance. */
+    client: SshClient;
+    /** Working directory for relative path resolution (default: /). */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by SFTP file operations over SSH.
+ *
+ * Uses the ssh2 Client's SFTP subsystem for all file I/O. The SFTP session
+ * is opened lazily on the first operation and reused for the lifetime of
+ * the SshFs instance.
+ *
+ * Requires `ssh2` as an optional peer dependency.
+ * The caller is responsible for the Client lifecycle.
+ */
+declare class SshFs implements VirtualFs {
+    private client;
+    private workingDir;
+    private sftpSession;
+    private sftpPromise;
+    constructor(opts: SshFsOptions);
+    private getSftp;
+    private resolvePath;
+    readFile(path: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(path: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(path: string, content: string): Promise<void>;
+    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>;
+    private mkdirRecursive;
+    private rmRecursive;
+}
+
+export { type SshChannel, type SshClient, SshComputer, type SshComputerOptions, SshFs, type SshFsOptions, SshSandbox, type SshSandboxOptions, type SshSftpSession };