@agent-sandbox/api 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @agent-sandbox/api
+
+Programmatic wrapper for Agent Sandbox.
+
+## Install
+
+```bash
+npm install @agent-sandbox/api
+```
+
+## Requirements
+
+- Docker running locally
+
+## Quick Start
+
+```ts
+import { AgentSandbox } from "@agent-sandbox/api";
+
+const sandbox = new AgentSandbox();
+const { sandboxId } = await sandbox.create();
+
+const { output } = await sandbox.write({ sandboxId, input: "echo hello" });
+console.log(output);
+
+await sandbox.delete({ sandboxId });
+```
+
+## API Reference
+
+### `create(options?)`
+
+```ts
+sandbox.create(options?: {
+  name?: string;
+  image?: string;
+  volume?: string;
+}): Promise<{ sandboxId: string }>
+```
+
+### `delete(options)`
+
+```ts
+sandbox.delete(options: {
+  sandboxId: string;
+}): Promise<{ ok: boolean }>
+```
+
+### `list()`
+
+```ts
+sandbox.list(): Promise<{
+  sandboxes: Array<{
+    id: string;
+    name: string;
+    status: string;
+    createdAt: string;
+  }>;
+}>
+```
+
+### `read(options)`
+
+```ts
+sandbox.read(options: {
+  sandboxId: string;
+  tail?: number;
+}): Promise<{ output: string }>
+```
+
+Returns container logs. `tail` limits to the last N lines.
+
+### `write(options)`
+
+```ts
+sandbox.write(options: {
+  sandboxId: string;
+  input: string;
+  detach?: boolean;
+}): Promise<{ ok: boolean; output?: string; exitCode?: number }>
+```
+
+Runs the command and returns its output and exit code. Set `detach: true` to fire-and-forget
+(returns immediately with no output, useful for starting background processes).
+
+### `upload(options)`
+
+```ts
+sandbox.upload(options: {
+  sandboxId: string;
+  localPath: string;
+  remotePath: string;
+}): Promise<{ ok: boolean }>
+```
+
+Both paths must be absolute.
+
+### `download(options)`
+
+```ts
+sandbox.download(options: {
+  sandboxId: string;
+  remotePath: string;
+  localPath: string;
+}): Promise<{ ok: boolean }>
+```
+
+`remotePath` may be a file or directory. Both paths must be absolute.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,556 @@
+// @bun
+// ../../packages/core/src/errors.ts
+class SandboxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxError";
+  }
+}
+
+class ContainerNotFoundError extends SandboxError {
+  constructor(sandboxId) {
+    super(`Container not found: ${sandboxId}`);
+    this.name = "ContainerNotFoundError";
+  }
+}
+
+class DockerError extends SandboxError {
+  status;
+  constructor(status, message) {
+    super(`Docker API error ${status}: ${message}`);
+    this.name = "DockerError";
+    this.status = status;
+  }
+}
+
+class ExecError extends SandboxError {
+  constructor(message) {
+    super(`Exec failed: ${message}`);
+    this.name = "ExecError";
+  }
+}
+// ../../packages/core/src/docker/client.ts
+var DOCKER_HOST = "http://localhost";
+var CLIENT_API_VERSION = "1.53";
+var DOCKER_SOCKET_PATH = "/var/run/docker.sock";
+var cachedApiVersion = null;
+var resolvingApiVersion = null;
+function isRawBody(body) {
+  return typeof body === "string" || body instanceof Blob || body instanceof ArrayBuffer || body instanceof FormData || body instanceof URLSearchParams || body instanceof ReadableStream || ArrayBuffer.isView(body);
+}
+function parseApiVersion(version) {
+  const match = version.match(/^(\d+)\.(\d+)$/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2])];
+}
+function selectApiVersion(serverVersion) {
+  const client = parseApiVersion(CLIENT_API_VERSION);
+  const server = parseApiVersion(serverVersion);
+  if (!client || !server) {
+    return CLIENT_API_VERSION;
+  }
+  if (server[0] < client[0]) {
+    return serverVersion;
+  }
+  if (server[0] > client[0]) {
+    return CLIENT_API_VERSION;
+  }
+  return server[1] < client[1] ? serverVersion : CLIENT_API_VERSION;
+}
+function buildUrl(path, query, apiVersion = CLIENT_API_VERSION) {
+  const url = new URL(`${DOCKER_HOST}/v${apiVersion}${path}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+}
+async function dockerFetch(input, init) {
+  return fetch(input, {
+    ...init,
+    unix: DOCKER_SOCKET_PATH
+  });
+}
+async function readDockerErrorMessage(response) {
+  let text = "";
+  try {
+    text = await response.text();
+  } catch {
+    return response.statusText || "Request failed";
+  }
+  if (!text) {
+    return response.statusText || "Request failed";
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.message === "string" && parsed.message.trim()) {
+      return parsed.message;
+    }
+  } catch {}
+  return text;
+}
+async function probeApiVersion() {
+  try {
+    const response = await dockerFetch(`${DOCKER_HOST}/version`, {
+      method: "GET"
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json();
+    if (typeof payload.ApiVersion !== "string" || !payload.ApiVersion.trim()) {
+      return null;
+    }
+    return selectApiVersion(payload.ApiVersion);
+  } catch {
+    return null;
+  }
+}
+async function resolveApiVersion() {
+  if (cachedApiVersion) {
+    return cachedApiVersion;
+  }
+  if (!resolvingApiVersion) {
+    resolvingApiVersion = probeApiVersion().then((apiVersion) => {
+      if (apiVersion) {
+        cachedApiVersion = apiVersion;
+        return apiVersion;
+      }
+      return CLIENT_API_VERSION;
+    }).finally(() => {
+      resolvingApiVersion = null;
+    });
+  }
+  return resolvingApiVersion;
+}
+async function dockerRequest(options) {
+  const { method = "GET", path, query, body, headers = {}, allowStatus = [] } = options;
+  const requestHeaders = { ...headers };
+  let requestBody;
+  if (body !== undefined) {
+    if (isRawBody(body)) {
+      requestBody = body;
+    } else {
+      requestBody = JSON.stringify(body);
+      if (!Object.keys(requestHeaders).some((key) => key.toLowerCase() === "content-type")) {
+        requestHeaders["Content-Type"] = "application/json";
+      }
+    }
+  }
+  let response;
+  try {
+    const apiVersion = await resolveApiVersion();
+    response = await dockerFetch(buildUrl(path, query, apiVersion), {
+      method,
+      headers: requestHeaders,
+      body: requestBody
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown Docker transport error";
+    throw new DockerError(0, message);
+  }
+  if (!response.ok && !allowStatus.includes(response.status)) {
+    throw new DockerError(response.status, await readDockerErrorMessage(response));
+  }
+  return response;
+}
+async function dockerJSON(options) {
+  const response = await dockerRequest(options);
+  return await response.json();
+}
+
+// ../../packages/core/src/primitives/create.ts
+async function create(options = {}) {
+  const { name, image = "agent-sandbox", volume } = options;
+  const hostConfig = volume ? { Binds: [`${volume}:/home/sandbox`] } : undefined;
+  const createResponse = await dockerJSON({
+    method: "POST",
+    path: "/containers/create",
+    query: name ? { name } : undefined,
+    body: {
+      Image: image,
+      Labels: {
+        "agent-sandbox": "true"
+      },
+      ...hostConfig ? { HostConfig: hostConfig } : {}
+    }
+  });
+  await dockerRequest({
+    method: "POST",
+    path: `/containers/${createResponse.Id}/start`
+  });
+  return {
+    sandboxId: createResponse.Id.slice(0, 12)
+  };
+}
+// ../../packages/core/src/primitives/delete.ts
+function remapContainerNotFound(error, sandboxId) {
+  if (error instanceof DockerError && error.status === 404) {
+    throw new ContainerNotFoundError(sandboxId);
+  }
+  throw error;
+}
+async function deleteContainer(options) {
+  const { sandboxId } = options;
+  try {
+    await dockerRequest({
+      method: "POST",
+      path: `/containers/${sandboxId}/stop`,
+      allowStatus: [304]
+    });
+  } catch (error) {
+    remapContainerNotFound(error, sandboxId);
+  }
+  try {
+    await dockerRequest({
+      method: "DELETE",
+      path: `/containers/${sandboxId}`
+    });
+  } catch (error) {
+    remapContainerNotFound(error, sandboxId);
+  }
+  return {
+    ok: true
+  };
+}
+// ../../packages/core/src/primitives/download.ts
+import path2 from "path";
+
+// ../../packages/core/src/archive.ts
+import { tmpdir } from "os";
+import path from "path";
+import { mkdir, mkdtemp, readdir, rename, rm, stat } from "fs/promises";
+function ensureAbsoluteHostPath(targetPath) {
+  if (!path.isAbsolute(targetPath)) {
+    throw new SandboxError(`Host path must be absolute: ${targetPath}`);
+  }
+}
+async function ensurePathExists(targetPath) {
+  try {
+    await stat(targetPath);
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      throw new SandboxError(`Host path does not exist: ${targetPath}`);
+    }
+    if (error instanceof Error) {
+      throw new SandboxError(`Failed to access host path ${targetPath}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+async function ensureTarSuccess(process, action) {
+  const exitCode = await process.exited;
+  if (exitCode === 0) {
+    return;
+  }
+  const stderr = process.stderr;
+  const detail = stderr ? (await new Response(stderr).text()).trim() : "";
+  const suffix = detail ? `: ${detail}` : "";
+  throw new SandboxError(`${action} failed${suffix}`);
+}
+function spawnTar(command, options) {
+  try {
+    return Bun.spawn(command, options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown tar error";
+    throw new SandboxError(`Failed to start tar: ${message}`);
+  }
+}
+async function createTarStream(localPath) {
+  ensureAbsoluteHostPath(localPath);
+  await ensurePathExists(localPath);
+  const directory = path.dirname(localPath);
+  const name = path.basename(localPath);
+  const process = spawnTar(["tar", "-C", directory, "-cf", "-", name], {
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const stream = process.stdout;
+  if (!stream) {
+    throw new SandboxError("Tar create failed: tar did not produce an archive stream");
+  }
+  return {
+    stream,
+    complete: () => ensureTarSuccess(process, "Tar create"),
+    abort: () => {
+      try {
+        process.kill();
+      } catch {}
+    }
+  };
+}
+async function extractTarStream(stream, localPath) {
+  ensureAbsoluteHostPath(localPath);
+  const targetDirectory = path.dirname(localPath);
+  await mkdir(targetDirectory, { recursive: true });
+  const extractDirectory = await mkdtemp(path.join(tmpdir(), "agent-sandbox-download-"));
+  try {
+    const process = spawnTar(["tar", "-C", extractDirectory, "-xf", "-"], {
+      stdin: stream,
+      stdout: "ignore",
+      stderr: "pipe"
+    });
+    await ensureTarSuccess(process, "Tar extract");
+    const extractedEntries = await readdir(extractDirectory);
+    const [firstEntry] = extractedEntries;
+    if (extractedEntries.length !== 1 || !firstEntry) {
+      throw new SandboxError("Tar extract failed: archive did not contain exactly one top-level entry");
+    }
+    const extractedPath = path.join(extractDirectory, firstEntry);
+    const extractedStats = await stat(extractedPath);
+    if (!extractedStats.isFile() && !extractedStats.isDirectory()) {
+      throw new SandboxError("Tar extract failed: archive did not contain a regular file or directory");
+    }
+    await rm(localPath, { recursive: true, force: true });
+    await rename(extractedPath, localPath);
+  } finally {
+    await rm(extractDirectory, { recursive: true, force: true });
+  }
+}
+
+// ../../packages/core/src/primitives/download.ts
+function ensureAbsoluteContainerPath(targetPath) {
+  if (!path2.posix.isAbsolute(targetPath)) {
+    throw new SandboxError(`Container path must be absolute: ${targetPath}`);
+  }
+}
+async function download(options) {
+  ensureAbsoluteContainerPath(options.remotePath);
+  if (!path2.isAbsolute(options.localPath)) {
+    throw new SandboxError(`Host path must be absolute: ${options.localPath}`);
+  }
+  let response;
+  try {
+    response = await dockerRequest({
+      path: `/containers/${options.sandboxId}/archive`,
+      query: {
+        path: options.remotePath
+      }
+    });
+  } catch (error) {
+    if (error instanceof DockerError && error.status === 404 && error.message.includes("No such container")) {
+      throw new ContainerNotFoundError(options.sandboxId);
+    }
+    throw error;
+  }
+  if (!response.body) {
+    throw new SandboxError("Docker archive response was empty");
+  }
+  await extractTarStream(response.body, options.localPath);
+  return {
+    ok: true
+  };
+}
+// ../../packages/core/src/primitives/list.ts
+async function list() {
+  const containers = await dockerJSON({
+    path: "/containers/json",
+    query: {
+      filters: JSON.stringify({
+        label: ["agent-sandbox=true"]
+      })
+    }
+  });
+  const sandboxes = containers.map((container) => {
+    const name = (container.Names[0] ?? "").replace(/^\//, "");
+    return {
+      id: container.Id.slice(0, 12),
+      name,
+      status: container.State,
+      createdAt: new Date(container.Created * 1000).toISOString()
+    };
+  });
+  return { sandboxes };
+}
+// ../../packages/core/src/docker/parse-log.ts
+function parseLogOutput(bytes) {
+  const chunks = [];
+  let totalLength = 0;
+  let offset = 0;
+  while (offset < bytes.length) {
+    if (bytes.length - offset < 8) {
+      throw new SandboxError("Malformed Docker log stream");
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset + offset + 4, 4);
+    const payloadLength = view.getUint32(0);
+    const payloadStart = offset + 8;
+    const payloadEnd = payloadStart + payloadLength;
+    if (payloadEnd > bytes.length) {
+      throw new SandboxError("Malformed Docker log stream");
+    }
+    const chunk = bytes.slice(payloadStart, payloadEnd);
+    chunks.push(chunk);
+    totalLength += chunk.length;
+    offset = payloadEnd;
+  }
+  const output = new Uint8Array(totalLength);
+  let writeOffset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, writeOffset);
+    writeOffset += chunk.length;
+  }
+  return new TextDecoder().decode(output);
+}
+
+// ../../packages/core/src/primitives/read.ts
+async function read(options) {
+  const query = {
+    stdout: "1",
+    stderr: "1"
+  };
+  if (options.tail !== undefined) {
+    query.tail = String(options.tail);
+  }
+  let response;
+  try {
+    response = await dockerRequest({
+      path: `/containers/${options.sandboxId}/logs`,
+      query
+    });
+  } catch (error) {
+    if (error instanceof DockerError && error.status === 404) {
+      throw new ContainerNotFoundError(options.sandboxId);
+    }
+    throw error;
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  return {
+    output: parseLogOutput(bytes)
+  };
+}
+// ../../packages/core/src/primitives/upload.ts
+import path3 from "path";
+function ensureAbsoluteContainerPath2(targetPath) {
+  if (!path3.posix.isAbsolute(targetPath)) {
+    throw new SandboxError(`Container path must be absolute: ${targetPath}`);
+  }
+}
+function remapUploadError(error, sandboxId) {
+  if (error instanceof DockerError && error.status === 404) {
+    throw new ContainerNotFoundError(sandboxId);
+  }
+  throw error;
+}
+async function upload(options) {
+  ensureAbsoluteContainerPath2(options.remotePath);
+  const archive = await createTarStream(options.localPath);
+  try {
+    await dockerRequest({
+      method: "PUT",
+      path: `/containers/${options.sandboxId}/archive`,
+      query: {
+        path: path3.posix.dirname(options.remotePath)
+      },
+      body: archive.stream,
+      headers: {
+        "Content-Type": "application/x-tar"
+      }
+    });
+  } catch (error) {
+    archive.abort();
+    remapUploadError(error, options.sandboxId);
+  }
+  await archive.complete();
+  return {
+    ok: true
+  };
+}
+// ../../packages/core/src/primitives/write.ts
+function getDockerMessage(error) {
+  return error.message.replace(/^Docker API error \d+: /, "");
+}
+async function write(options) {
+  const detach = options.detach ?? false;
+  let execId;
+  try {
+    const response = await dockerJSON({
+      method: "POST",
+      path: `/containers/${options.sandboxId}/exec`,
+      body: {
+        Cmd: ["/bin/sh", "-c", options.input],
+        AttachStdout: !detach,
+        AttachStderr: !detach
+      }
+    });
+    execId = response.Id;
+  } catch (error) {
+    if (error instanceof DockerError && error.status === 404) {
+      throw new ContainerNotFoundError(options.sandboxId);
+    }
+    throw error;
+  }
+  if (detach) {
+    try {
+      await dockerRequest({
+        method: "POST",
+        path: `/exec/${execId}/start`,
+        body: {
+          Detach: true
+        }
+      });
+    } catch (error) {
+      if (error instanceof DockerError) {
+        throw new ExecError(getDockerMessage(error));
+      }
+      throw error;
+    }
+    return { ok: true };
+  }
+  let startResponse;
+  try {
+    startResponse = await dockerRequest({
+      method: "POST",
+      path: `/exec/${execId}/start`,
+      body: {
+        Detach: false,
+        Tty: false
+      }
+    });
+  } catch (error) {
+    if (error instanceof DockerError) {
+      throw new ExecError(getDockerMessage(error));
+    }
+    throw error;
+  }
+  const bytes = new Uint8Array(await startResponse.arrayBuffer());
+  const output = parseLogOutput(bytes);
+  const inspect = await dockerJSON({
+    method: "GET",
+    path: `/exec/${execId}/json`
+  });
+  return {
+    ok: true,
+    output,
+    exitCode: inspect.ExitCode
+  };
+}
+// src/agent-sandbox.ts
+class AgentSandbox {
+  async create(options = {}) {
+    return create(options);
+  }
+  async delete(options) {
+    return deleteContainer(options);
+  }
+  async list() {
+    return list();
+  }
+  async read(options) {
+    return read(options);
+  }
+  async write(options) {
+    return write(options);
+  }
+  async upload(options) {
+    return upload(options);
+  }
+  async download(options) {
+    return download(options);
+  }
+}
+export {
+  AgentSandbox
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@agent-sandbox/api",
+  "version": "0.1.0",
+  "description": "Programmatic API wrapper for Agent Sandbox",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./index.ts --outfile dist/index.js --target bun",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@agent-sandbox/core": "*",
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}