@agentstep/agent-sdk 0.1.0

package/src/providers/apple.ts

@@ -0,0 +1,220 @@
+/**
+ * Apple Containers provider (macOS 26+).
+ *
+ * Runs CLI backends inside Apple's native container runtime instead of
+ * Docker or sprites.dev. Uses `child_process.spawn("container", [...])`
+ * to interact with Apple's container CLI. Requires macOS 26 (Tahoe)
+ * with Apple Silicon.
+ *
+ * The execution model is identical to Docker:
+ *   create → container create --name {name} node:22 sleep infinity + container start
+ *   exec   → container exec -i {name} with stdin piped + stdout captured
+ *   delete → container rm -f {name}
+ *
+ * Differences from Docker:
+ *   - CLI binary is `container` not `docker`
+ *   - List command is `container ls` not `docker ps`
+ *   - Uses Apple's Virtualization.framework (VM-per-container, not shared kernel)
+ *   - OCI-compatible: pulls from Docker Hub, uses same image format
+ *   - arm64 native on Apple Silicon; amd64 via Rosetta 2
+ *
+ * Ref: https://github.com/apple/container
+ */
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+
+const DEFAULT_IMAGE = process.env.APPLE_CONTAINER_IMAGE ?? "node:22";
+const CLI = "container"; // Apple's CLI binary name
+
+// ---------------------------------------------------------------------------
+// Helpers (same structure as docker.ts, different CLI binary)
+// ---------------------------------------------------------------------------
+
+function containerRun(
+  args: string[],
+  opts?: { stdin?: string; timeoutMs?: number },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(CLI, args, { stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => { stdout += buf.toString(); });
+    proc.stderr?.on("data", (buf: Buffer) => { stderr += buf.toString(); });
+
+    if (opts?.stdin) {
+      proc.stdin?.write(opts.stdin);
+    }
+    proc.stdin?.end();
+
+    const timer = opts?.timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`${CLI} command timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`${CLI} ${args[0]} failed (${code}): ${stderr.trim()}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+function containerExecOneShot(
+  containerName: string,
+  argv: string[],
+  stdin?: string,
+  timeoutMs?: number,
+): Promise<{ stdout: string; stderr: string; exit_code: number }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(CLI, ["exec", "-i", containerName, ...argv], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => { stdout += buf.toString(); });
+    proc.stderr?.on("data", (buf: Buffer) => { stderr += buf.toString(); });
+
+    if (stdin) proc.stdin?.write(stdin);
+    proc.stdin?.end();
+
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`${CLI} exec timed out after ${timeoutMs}ms`));
+        }, timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, exit_code: code ?? 1 });
+    });
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+function containerExecStreaming(
+  containerName: string,
+  opts: ExecOptions,
+): ExecSession {
+  const proc = spawn(CLI, ["exec", "-i", containerName, ...opts.argv], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  if (opts.stdin) proc.stdin?.write(opts.stdin);
+  proc.stdin?.end();
+
+  const stdout = Readable.toWeb(proc.stdout!) as ReadableStream<Uint8Array>;
+
+  let exitResolve: (v: { code: number }) => void;
+  let exitReject: (e: unknown) => void;
+  const exit = new Promise<{ code: number }>((res, rej) => {
+    exitResolve = res;
+    exitReject = rej;
+  });
+
+  proc.on("close", (code) => exitResolve({ code: code ?? 0 }));
+  proc.on("error", (err) => exitReject(err));
+
+  let timer: NodeJS.Timeout | null = null;
+  if (opts.timeoutMs) {
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      exitReject(new Error(`${CLI} exec timed out after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
+  }
+  exit.finally(() => { if (timer) clearTimeout(timer); });
+
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      proc.kill("SIGTERM");
+    } else {
+      opts.signal.addEventListener("abort", () => {
+        proc.kill("SIGTERM");
+        setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 3000);
+      });
+    }
+  }
+
+  return {
+    stdout,
+    exit,
+    async kill() {
+      proc.kill("SIGTERM");
+      setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 3000);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const appleProvider: ContainerProvider = {
+  name: "apple",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    if (process.platform !== "darwin") {
+      return { available: false, message: "Apple Containers requires macOS" };
+    }
+    try {
+      await containerRun(["--version"], { timeoutMs: 3000 });
+      return { available: true };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ENOENT")) {
+        return { available: false, message: "Apple Containers CLI not found. Requires macOS 26+" };
+      }
+      return { available: false, message: `Apple Containers not accessible: ${msg}` };
+    }
+  },
+
+  async create({ name }) {
+    await containerRun(["create", "--name", name, DEFAULT_IMAGE, "sleep", "infinity"]);
+    await containerRun(["start", name]);
+  },
+
+  async delete(name) {
+    await containerRun(["rm", "-f", name]).catch(() => {});
+  },
+
+  async list(opts) {
+    try {
+      // Apple uses `container ls` not `docker ps`
+      const out = await containerRun([
+        "ls",
+        "-a",
+        "--filter",
+        `name=${opts?.prefix ?? "ca-sess-"}`,
+        "--format",
+        "{{.Names}}",
+      ]);
+      return out.trim().split("\n").filter(Boolean).map((name) => ({ name }));
+    } catch {
+      return [];
+    }
+  },
+
+  async exec(name, argv, opts) {
+    return containerExecOneShot(name, argv, opts?.stdin, opts?.timeoutMs);
+  },
+
+  startExec(name, opts) {
+    return Promise.resolve(containerExecStreaming(name, opts));
+  },
+};

package/src/providers/daytona.ts

@@ -0,0 +1,217 @@
+/**
+ * Daytona provider using REST API via fetch.
+ *
+ * Uses Daytona's workspace API to create and manage dev environments.
+ * No SDK required — communicates via plain HTTP fetch.
+ *
+ * Container lifecycle:
+ *   create → POST /workspaces
+ *   exec   → POST /workspaces/{name}/exec
+ *   delete → DELETE /workspaces/{name}
+ *
+ * Env vars: DAYTONA_API_URL, DAYTONA_API_KEY
+ */
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+import { shellEscape } from "./shared";
+
+function getApiUrl(): string {
+  const url = process.env.DAYTONA_API_URL;
+  if (!url) throw new Error("DAYTONA_API_URL environment variable is required");
+  return url.replace(/\/+$/, "");
+}
+
+function getApiKey(): string {
+  const key = process.env.DAYTONA_API_KEY;
+  if (!key) throw new Error("DAYTONA_API_KEY environment variable is required");
+  return key;
+}
+
+function headers(): Record<string, string> {
+  return {
+    Authorization: `Bearer ${getApiKey()}`,
+    "Content-Type": "application/json",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const daytonaProvider: ContainerProvider = {
+  name: "daytona",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    if (!process.env.DAYTONA_API_URL) {
+      return { available: false, message: "Daytona requires DAYTONA_API_URL to be set" };
+    }
+    if (!process.env.DAYTONA_API_KEY) {
+      return { available: false, message: "Daytona requires DAYTONA_API_KEY to be set" };
+    }
+    return { available: true };
+  },
+
+  async create({ name }) {
+    const url = getApiUrl();
+    const res = await fetch(`${url}/workspaces`, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify({
+        name,
+        target: "local",
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Daytona create failed (${res.status}): ${body}`);
+    }
+  },
+
+  async delete(name) {
+    const url = getApiUrl();
+    try {
+      const res = await fetch(`${url}/workspaces/${encodeURIComponent(name)}`, {
+        method: "DELETE",
+        headers: headers(),
+      });
+      if (!res.ok && res.status !== 404) {
+        const body = await res.text().catch(() => "");
+        console.warn(`Daytona delete failed (${res.status}): ${body}`);
+      }
+    } catch {
+      // Best-effort — workspace may already be gone
+    }
+  },
+
+  async list(opts) {
+    const url = getApiUrl();
+    try {
+      const res = await fetch(`${url}/workspaces`, {
+        headers: headers(),
+      });
+      if (!res.ok) return [];
+      const data = (await res.json()) as Array<{ name: string }>;
+      const prefix = opts?.prefix ?? "ca-sess-";
+      return data
+        .filter((w) => w.name.startsWith(prefix))
+        .map((w) => ({ name: w.name }));
+    } catch {
+      return [];
+    }
+  },
+
+  async exec(name, argv, opts) {
+    const url = getApiUrl();
+    const cmd = argv.map((a) => shellEscape(a)).join(" ");
+    const body: Record<string, unknown> = { command: cmd };
+    if (opts?.stdin) body.stdin = opts.stdin;
+
+    const res = await fetch(
+      `${url}/workspaces/${encodeURIComponent(name)}/exec`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(body),
+        signal: opts?.timeoutMs
+          ? AbortSignal.timeout(opts.timeoutMs)
+          : undefined,
+      },
+    );
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Daytona exec failed (${res.status}): ${text}`);
+    }
+
+    const result = (await res.json()) as {
+      stdout?: string;
+      stderr?: string;
+      exit_code?: number;
+      exitCode?: number;
+    };
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      exit_code: result.exit_code ?? result.exitCode ?? 0,
+    };
+  },
+
+  async startExec(name, opts) {
+    const url = getApiUrl();
+    const cmd = opts.argv.map((a) => shellEscape(a)).join(" ");
+    const body: Record<string, unknown> = { command: cmd };
+    if (opts.stdin) body.stdin = opts.stdin;
+
+    const controller = new AbortController();
+    if (opts.signal) {
+      if (opts.signal.aborted) {
+        controller.abort();
+      } else {
+        opts.signal.addEventListener("abort", () => controller.abort());
+      }
+    }
+    if (opts.timeoutMs) {
+      setTimeout(() => controller.abort(), opts.timeoutMs);
+    }
+
+    const res = await fetch(
+      `${url}/workspaces/${encodeURIComponent(name)}/exec`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      },
+    );
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Daytona exec failed (${res.status}): ${text}`);
+    }
+
+    // If the response has a streaming body, pass it through directly.
+    // Otherwise, wrap the full text response in a ReadableStream.
+    if (res.body) {
+      const [streamForCaller, streamForExit] = res.body.tee();
+
+      const exit = (async () => {
+        const reader = streamForExit.getReader();
+        try {
+          for (;;) {
+            const { done } = await reader.read();
+            if (done) break;
+          }
+        } catch {
+          // Stream error
+        }
+        return { code: 0 };
+      })();
+
+      return {
+        stdout: streamForCaller,
+        exit,
+        async kill() {
+          controller.abort();
+        },
+      };
+    }
+
+    // Fallback: no streaming body — read entire response and wrap
+    const fullBody = await res.text();
+    const encoder = new TextEncoder();
+    const stdout = new ReadableStream<Uint8Array>({
+      start(c) {
+        c.enqueue(encoder.encode(fullBody));
+        c.close();
+      },
+    });
+
+    return {
+      stdout,
+      exit: Promise.resolve({ code: 0 }),
+      async kill() {
+        controller.abort();
+      },
+    };
+  },
+};

package/src/providers/docker.ts

@@ -0,0 +1,264 @@
+/**
+ * Docker container provider.
+ *
+ * Runs CLI backends inside local Docker containers instead of sprites.dev.
+ * Uses `child_process.spawn("docker", [...])` to interact with the Docker
+ * daemon via CLI. Requires Docker to be installed and accessible on the host.
+ *
+ * Container lifecycle:
+ *   create → docker create --name {name} node:22 sleep infinity + docker start
+ *   exec   → docker exec -i {name} with stdin piped + stdout captured
+ *   delete → docker rm -f {name}
+ *
+ * The `sleep infinity` entrypoint keeps the container alive for repeated
+ * `docker exec` calls throughout the session's lifetime (same model as
+ * sprites.dev: one container per session, multiple exec calls).
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { Readable } from "node:stream";
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+
+const DEFAULT_IMAGE = process.env.DOCKER_IMAGE ?? "node:22";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Run a docker CLI command and return stdout as a string. */
+function dockerRun(
+  args: string[],
+  opts?: { stdin?: string; timeoutMs?: number },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("docker", args, {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => {
+      stdout += buf.toString();
+    });
+    proc.stderr?.on("data", (buf: Buffer) => {
+      stderr += buf.toString();
+    });
+
+    if (opts?.stdin) {
+      proc.stdin?.write(opts.stdin);
+      proc.stdin?.end();
+    } else {
+      proc.stdin?.end();
+    }
+
+    const timer = opts?.timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`docker command timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`docker ${args[0]} failed (${code}): ${stderr.trim()}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/** One-shot docker exec: run, wait for exit, return output. */
+async function dockerExecOneShot(
+  containerName: string,
+  argv: string[],
+  stdin?: string,
+  timeoutMs?: number,
+): Promise<{ stdout: string; stderr: string; exit_code: number }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("docker", ["exec", "-i", containerName, ...argv], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => {
+      stdout += buf.toString();
+    });
+    proc.stderr?.on("data", (buf: Buffer) => {
+      stderr += buf.toString();
+    });
+
+    if (stdin) {
+      proc.stdin?.write(stdin);
+    }
+    proc.stdin?.end();
+
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`docker exec timed out after ${timeoutMs}ms`));
+        }, timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, exit_code: code ?? 1 });
+    });
+
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/** Streaming docker exec: returns ExecSession with ReadableStream stdout. */
+function dockerExecStreaming(
+  containerName: string,
+  opts: ExecOptions,
+): ExecSession {
+  const proc = spawn("docker", ["exec", "-i", containerName, ...opts.argv], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  // Pipe stdin
+  if (opts.stdin) {
+    proc.stdin?.write(opts.stdin);
+  }
+  proc.stdin?.end();
+
+  // Convert Node Readable to Web ReadableStream
+  // Readable.toWeb() is available since Node 17 and stable in Node 22.
+  // Do NOT set encoding on spawn — default produces Buffer (Uint8Array subtype).
+  const stdout = Readable.toWeb(proc.stdout!) as ReadableStream<Uint8Array>;
+
+  // Exit promise
+  let exitResolve: (v: { code: number }) => void;
+  let exitReject: (e: unknown) => void;
+  const exit = new Promise<{ code: number }>((res, rej) => {
+    exitResolve = res;
+    exitReject = rej;
+  });
+
+  proc.on("close", (code) => {
+    exitResolve({ code: code ?? 0 });
+  });
+  proc.on("error", (err) => {
+    exitReject(err);
+  });
+
+  // Timeout
+  let timer: NodeJS.Timeout | null = null;
+  if (opts.timeoutMs) {
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      exitReject(new Error(`docker exec timed out after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
+  }
+  // Clean up timer on exit
+  exit.finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+
+  // Link caller's abort signal
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      proc.kill("SIGTERM");
+    } else {
+      opts.signal.addEventListener("abort", () => {
+        proc.kill("SIGTERM");
+        // Escalate to SIGKILL after 3s if still alive
+        setTimeout(() => {
+          if (!proc.killed) proc.kill("SIGKILL");
+        }, 3000);
+      });
+    }
+  }
+
+  return {
+    stdout,
+    exit,
+    async kill() {
+      proc.kill("SIGTERM");
+      setTimeout(() => {
+        if (!proc.killed) proc.kill("SIGKILL");
+      }, 3000);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const dockerProvider: ContainerProvider = {
+  name: "docker",
+  stripControlChars: false, // Docker doesn't add HTTP framing bytes
+
+  async checkAvailability() {
+    try {
+      await dockerRun(["version", "--format", "{{.Server.Version}}"], { timeoutMs: 3000 });
+      return { available: true };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ENOENT")) {
+        return { available: false, message: "Docker CLI is not installed. Install it from https://docs.docker.com/get-docker/" };
+      }
+      return { available: false, message: `Docker is not running or not accessible: ${msg}` };
+    }
+  },
+
+  async create({ name }) {
+    // Create container with sleep infinity to keep it alive for repeated exec calls
+    await dockerRun([
+      "create",
+      "--name",
+      name,
+      DEFAULT_IMAGE,
+      "sleep",
+      "infinity",
+    ]);
+    await dockerRun(["start", name]);
+  },
+
+  async delete(name) {
+    await dockerRun(["rm", "-f", name]).catch(() => {
+      // Best-effort — container may already be gone
+    });
+  },
+
+  async list(opts) {
+    try {
+      const out = await dockerRun([
+        "ps",
+        "-a",
+        "--filter",
+        `name=${opts?.prefix ?? "ca-sess-"}`,
+        "--format",
+        "{{.Names}}",
+      ]);
+      return out
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((name) => ({ name }));
+    } catch {
+      // Docker not available or no matching containers
+      return [];
+    }
+  },
+
+  async exec(name, argv, opts) {
+    return dockerExecOneShot(name, argv, opts?.stdin, opts?.timeoutMs);
+  },
+
+  startExec(name, opts) {
+    return Promise.resolve(dockerExecStreaming(name, opts));
+  },
+};