@agentstep/agent-sdk 0.1.0

package/src/providers/e2b.ts

@@ -0,0 +1,203 @@
+/**
+ * E2B sandbox provider.
+ *
+ * Uses the `@e2b/sdk` npm package to create and manage cloud sandboxes.
+ * The SDK is optional — if not installed, a clear error is thrown on first use.
+ *
+ * Container lifecycle:
+ *   create → Sandbox.create({ template })
+ *   exec   → sandbox.commands.run(cmd)
+ *   delete → sandbox.kill()
+ *
+ * Env vars: E2B_API_KEY, E2B_TEMPLATE (default: "base")
+ */
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+import { shellEscape } from "./shared";
+
+// Lazy-loaded SDK types. The actual import happens at runtime via loadSdk().
+type E2BSandbox = {
+  commands: {
+    run(
+      cmd: string,
+      opts?: {
+        onStdout?: (data: string) => void;
+        onStderr?: (data: string) => void;
+        timeout?: number;
+      },
+    ): Promise<{ exitCode: number; stdout: string; stderr: string }>;
+  };
+  kill(): Promise<void>;
+};
+
+type E2BSandboxClass = {
+  create(opts: {
+    template?: string;
+    apiKey?: string;
+  }): Promise<E2BSandbox>;
+};
+
+let SandboxClass: E2BSandboxClass | null = null;
+
+async function loadSdk(): Promise<E2BSandboxClass> {
+  if (SandboxClass) return SandboxClass;
+  try {
+    // @ts-ignore — optional dependency, may not be installed
+    const mod = await import("@e2b/sdk");
+    SandboxClass = (mod.Sandbox ?? mod.default?.Sandbox ?? mod.default) as E2BSandboxClass;
+    if (!SandboxClass?.create) {
+      throw new Error("Sandbox.create not found in @e2b/sdk exports");
+    }
+    return SandboxClass;
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      (err.message.includes("Cannot find module") ||
+        err.message.includes("MODULE_NOT_FOUND") ||
+        err.message.includes("ERR_MODULE_NOT_FOUND"))
+    ) {
+      throw new Error(
+        "E2B provider requires the @e2b/sdk package. Install it with: npm install @e2b/sdk",
+      );
+    }
+    throw err;
+  }
+}
+
+// HMR-safe sandbox instance map
+type GlobalWithE2B = typeof globalThis & { __caE2BSandboxes?: Map<string, E2BSandbox> };
+const g = globalThis as GlobalWithE2B;
+if (!g.__caE2BSandboxes) g.__caE2BSandboxes = new Map();
+const sandboxes = g.__caE2BSandboxes;
+
+const DEFAULT_TEMPLATE = process.env.E2B_TEMPLATE ?? "base";
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const e2bProvider: ContainerProvider = {
+  name: "e2b",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    try { await loadSdk(); } catch {
+      return { available: false, message: "E2B requires the @e2b/sdk package. Install with: npm install @e2b/sdk" };
+    }
+    if (!process.env.E2B_API_KEY) {
+      return { available: false, message: "E2B requires E2B_API_KEY to be set" };
+    }
+    return { available: true };
+  },
+
+  async create({ name }) {
+    const Sandbox = await loadSdk();
+    const apiKey = process.env.E2B_API_KEY;
+    if (!apiKey) throw new Error("E2B_API_KEY environment variable is required");
+
+    const sandbox = await Sandbox.create({
+      template: DEFAULT_TEMPLATE,
+      apiKey,
+    });
+    sandboxes.set(name, sandbox);
+  },
+
+  async delete(name) {
+    const sandbox = sandboxes.get(name);
+    if (!sandbox) return;
+    try {
+      await sandbox.kill();
+    } catch {
+      // Best-effort — sandbox may already be gone
+    }
+    sandboxes.delete(name);
+  },
+
+  async list(opts) {
+    // NOTE: @e2b/sdk does not expose a Sandbox.list() method to enumerate
+    // running sandboxes server-side. After a server restart the in-memory map
+    // is empty, so previously-created sandboxes will not appear here. This is
+    // an accepted limitation — callers must handle missing containers
+    // gracefully (e.g. re-create on demand).
+    const prefix = opts?.prefix ?? "ca-sess-";
+    return Array.from(sandboxes.keys())
+      .filter((n) => n.startsWith(prefix))
+      .map((name) => ({ name }));
+  },
+
+  async exec(name, argv, opts) {
+    const sandbox = sandboxes.get(name);
+    if (!sandbox) throw new Error(`E2B sandbox not found: ${name}`);
+
+    const cmd = argv.map((a) => shellEscape(a)).join(" ");
+    // If stdin is provided, pipe it via shell: echo '...' | cmd
+    const fullCmd = opts?.stdin
+      ? `echo ${shellEscape(opts.stdin)} | ${cmd}`
+      : cmd;
+
+    const result = await sandbox.commands.run(fullCmd, {
+      timeout: opts?.timeoutMs,
+    });
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exit_code: result.exitCode,
+    };
+  },
+
+  async startExec(name, opts) {
+    const sandbox = sandboxes.get(name);
+    if (!sandbox) throw new Error(`E2B sandbox not found: ${name}`);
+
+    const cmd = opts.argv.map((a) => shellEscape(a)).join(" ");
+    const fullCmd = opts.stdin
+      ? `echo ${shellEscape(opts.stdin)} | ${cmd}`
+      : cmd;
+
+    const encoder = new TextEncoder();
+    let streamController: ReadableStreamDefaultController<Uint8Array>;
+
+    const stdout = new ReadableStream<Uint8Array>({
+      start(controller) {
+        streamController = controller;
+      },
+    });
+
+    const resultPromise = sandbox.commands.run(fullCmd, {
+      onStdout: (data: string) => {
+        try {
+          streamController.enqueue(encoder.encode(data));
+        } catch {
+          // Stream may be closed
+        }
+      },
+      onStderr: (_data: string) => {
+        // stderr is not streamed to stdout
+      },
+      timeout: opts.timeoutMs,
+    });
+
+    const exit = resultPromise.then((result) => {
+      try {
+        streamController.close();
+      } catch {
+        // Already closed
+      }
+      return { code: result.exitCode };
+    }).catch((err) => {
+      try {
+        streamController.error(err);
+      } catch {
+        // Already closed
+      }
+      throw err;
+    });
+
+    return {
+      stdout,
+      exit,
+      async kill() {
+        // E2B doesn't support killing individual commands — best-effort no-op
+      },
+    };
+  },
+};

package/src/providers/fly.ts

@@ -0,0 +1,276 @@
+/**
+ * Fly.io Machines provider using REST API.
+ *
+ * Uses the Fly Machines API to create and manage containers on Fly.io's
+ * infrastructure. No SDK required — communicates via plain HTTP fetch.
+ *
+ * Container lifecycle:
+ *   create → POST /v1/apps/{app}/machines
+ *   exec   → POST /v1/apps/{app}/machines/{id}/exec
+ *   delete → DELETE /v1/apps/{app}/machines/{id}?force=true
+ *
+ * Fly Machines are identified by machine IDs (not names), so we maintain
+ * a name→id map to conform to the ContainerProvider interface.
+ *
+ * Env vars: FLY_API_TOKEN, FLY_APP_NAME, FLY_IMAGE (default: "node:22")
+ */
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+import { shellEscape } from "./shared";
+
+const BASE_URL = "https://api.machines.dev";
+
+function getToken(): string {
+  const token = process.env.FLY_API_TOKEN;
+  if (!token) throw new Error("FLY_API_TOKEN environment variable is required");
+  return token;
+}
+
+function getAppName(): string {
+  const app = process.env.FLY_APP_NAME;
+  if (!app) throw new Error("FLY_APP_NAME environment variable is required");
+  return app;
+}
+
+function headers(): Record<string, string> {
+  return {
+    Authorization: `Bearer ${getToken()}`,
+    "Content-Type": "application/json",
+  };
+}
+
+// HMR-safe name→machineId map
+type GlobalWithFly = typeof globalThis & { __caFlyMachines?: Map<string, string> };
+const g = globalThis as GlobalWithFly;
+if (!g.__caFlyMachines) g.__caFlyMachines = new Map();
+const machines = g.__caFlyMachines;
+
+const DEFAULT_IMAGE = process.env.FLY_IMAGE ?? "node:22";
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const flyProvider: ContainerProvider = {
+  name: "fly",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    if (!process.env.FLY_API_TOKEN) {
+      return { available: false, message: "Fly.io requires FLY_API_TOKEN to be set" };
+    }
+    if (!process.env.FLY_APP_NAME) {
+      return { available: false, message: "Fly.io requires FLY_APP_NAME to be set" };
+    }
+    return { available: true };
+  },
+
+  async create({ name }) {
+    const app = getAppName();
+    const res = await fetch(`${BASE_URL}/v1/apps/${app}/machines`, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify({
+        name,
+        config: {
+          image: DEFAULT_IMAGE,
+          auto_destroy: true,
+          processes: [
+            { cmd: ["sleep", "infinity"] },
+          ],
+        },
+      }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Fly create failed (${res.status}): ${body}`);
+    }
+
+    const data = (await res.json()) as { id: string };
+    machines.set(name, data.id);
+
+    // Wait for the machine to start
+    const machineId = data.id;
+    const startRes = await fetch(
+      `${BASE_URL}/v1/apps/${app}/machines/${machineId}/wait?state=started&timeout=60`,
+      { headers: headers() },
+    );
+    if (!startRes.ok) {
+      const body = await startRes.text().catch(() => "");
+      console.warn(`Fly machine wait-for-start warning (${startRes.status}): ${body}`);
+    }
+  },
+
+  async delete(name) {
+    const machineId = machines.get(name);
+    if (!machineId) return;
+    const app = getAppName();
+    try {
+      // Stop first, then destroy
+      await fetch(`${BASE_URL}/v1/apps/${app}/machines/${machineId}/stop`, {
+        method: "POST",
+        headers: headers(),
+      }).catch(() => {});
+
+      const res = await fetch(
+        `${BASE_URL}/v1/apps/${app}/machines/${machineId}?force=true`,
+        {
+          method: "DELETE",
+          headers: headers(),
+        },
+      );
+      if (!res.ok && res.status !== 404) {
+        const body = await res.text().catch(() => "");
+        console.warn(`Fly delete failed (${res.status}): ${body}`);
+      }
+    } catch {
+      // Best-effort
+    }
+    machines.delete(name);
+  },
+
+  async list(opts) {
+    const app = getAppName();
+    try {
+      const res = await fetch(`${BASE_URL}/v1/apps/${app}/machines`, {
+        headers: headers(),
+      });
+      if (!res.ok) return [];
+      const data = (await res.json()) as Array<{ id: string; name?: string }>;
+      const prefix = opts?.prefix ?? "ca-sess-";
+
+      // Update our name→id map from the API response
+      for (const m of data) {
+        if (m.name) machines.set(m.name, m.id);
+      }
+
+      return data
+        .filter((m) => m.name?.startsWith(prefix))
+        .map((m) => ({ name: m.name! }));
+    } catch {
+      return [];
+    }
+  },
+
+  async exec(name, argv, opts) {
+    const machineId = machines.get(name);
+    if (!machineId) throw new Error(`Fly machine not found for name: ${name}`);
+    const app = getAppName();
+
+    const cmd = argv.map((a) => shellEscape(a)).join(" ");
+    const execBody: Record<string, unknown> = {
+      cmd: ["bash", "-c", opts?.stdin ? `echo ${shellEscape(opts.stdin)} | ${cmd}` : cmd],
+    };
+
+    const res = await fetch(
+      `${BASE_URL}/v1/apps/${app}/machines/${machineId}/exec`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(execBody),
+        signal: opts?.timeoutMs
+          ? AbortSignal.timeout(opts.timeoutMs)
+          : undefined,
+      },
+    );
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Fly 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 machineId = machines.get(name);
+    if (!machineId) throw new Error(`Fly machine not found for name: ${name}`);
+    const app = getAppName();
+
+    const cmd = opts.argv.map((a) => shellEscape(a)).join(" ");
+    const execBody: Record<string, unknown> = {
+      cmd: ["bash", "-c", opts.stdin ? `echo ${shellEscape(opts.stdin)} | ${cmd}` : cmd],
+    };
+
+    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(
+      `${BASE_URL}/v1/apps/${app}/machines/${machineId}/exec`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(execBody),
+        signal: controller.signal,
+      },
+    );
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Fly exec failed (${res.status}): ${text}`);
+    }
+
+    // If the response has a streaming body, tee it
+    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: wrap full response in a ReadableStream
+    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/modal.ts

@@ -0,0 +1,222 @@
+/**
+ * Modal provider using REST API (buffered exec only).
+ *
+ * Uses Modal's sandbox API to create and manage sandboxes.
+ * No SDK required — communicates via plain HTTP fetch.
+ * Exec is buffered (no streaming) — startExec wraps the full
+ * response in a ReadableStream that emits all at once.
+ *
+ * Container lifecycle:
+ *   create → POST /v1/sandboxes
+ *   exec   → POST /v1/sandboxes/{id}/exec
+ *   delete → DELETE /v1/sandboxes/{id}
+ *
+ * Env vars: MODAL_TOKEN_ID, MODAL_TOKEN_SECRET
+ */
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+import { shellEscape } from "./shared";
+
+const BASE_URL = "https://api.modal.com";
+
+function getAuth(): { tokenId: string; tokenSecret: string } {
+  const tokenId = process.env.MODAL_TOKEN_ID;
+  const tokenSecret = process.env.MODAL_TOKEN_SECRET;
+  if (!tokenId) throw new Error("MODAL_TOKEN_ID environment variable is required");
+  if (!tokenSecret) throw new Error("MODAL_TOKEN_SECRET environment variable is required");
+  return { tokenId, tokenSecret };
+}
+
+function headers(): Record<string, string> {
+  const { tokenId, tokenSecret } = getAuth();
+  return {
+    Authorization: `Bearer ${tokenId}:${tokenSecret}`,
+    "Content-Type": "application/json",
+  };
+}
+
+// HMR-safe name→sandboxId map
+type GlobalWithModal = typeof globalThis & { __caModalSandboxes?: Map<string, string> };
+const g = globalThis as GlobalWithModal;
+if (!g.__caModalSandboxes) g.__caModalSandboxes = new Map();
+const sandboxes = g.__caModalSandboxes;
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export const modalProvider: ContainerProvider = {
+  name: "modal",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    if (!process.env.MODAL_TOKEN_ID) {
+      return { available: false, message: "Modal requires MODAL_TOKEN_ID to be set" };
+    }
+    if (!process.env.MODAL_TOKEN_SECRET) {
+      return { available: false, message: "Modal requires MODAL_TOKEN_SECRET to be set" };
+    }
+    return { available: true };
+  },
+
+  async create({ name }) {
+    const res = await fetch(`${BASE_URL}/v1/sandboxes`, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify({
+        name,
+        image: "node:22",
+        command: ["sleep", "infinity"],
+      }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Modal create failed (${res.status}): ${body}`);
+    }
+
+    const data = (await res.json()) as { id?: string; sandbox_id?: string };
+    const sandboxId = data.id ?? data.sandbox_id;
+    if (!sandboxId) throw new Error("Modal create response missing sandbox id");
+    sandboxes.set(name, sandboxId);
+  },
+
+  async delete(name) {
+    const sandboxId = sandboxes.get(name);
+    if (!sandboxId) return;
+    try {
+      const res = await fetch(`${BASE_URL}/v1/sandboxes/${sandboxId}`, {
+        method: "DELETE",
+        headers: headers(),
+      });
+      if (!res.ok && res.status !== 404) {
+        const body = await res.text().catch(() => "");
+        console.warn(`Modal delete failed (${res.status}): ${body}`);
+      }
+    } catch {
+      // Best-effort
+    }
+    sandboxes.delete(name);
+  },
+
+  async list(opts) {
+    const prefix = opts?.prefix ?? "ca-sess-";
+    try {
+      const res = await fetch(`${BASE_URL}/v1/sandboxes`, {
+        headers: headers(),
+      });
+      if (!res.ok) {
+        // Fall back to in-memory map on API failure
+        return Array.from(sandboxes.keys())
+          .filter((n) => n.startsWith(prefix))
+          .map((name) => ({ name }));
+      }
+      const data = (await res.json()) as Array<{
+        id?: string;
+        sandbox_id?: string;
+        name?: string;
+      }>;
+
+      // Re-populate the in-memory name→id map from the API response
+      for (const s of data) {
+        const id = s.id ?? s.sandbox_id;
+        if (s.name && id) sandboxes.set(s.name, id);
+      }
+
+      return data
+        .filter((s) => s.name?.startsWith(prefix))
+        .map((s) => ({ name: s.name! }));
+    } catch {
+      // Fall back to in-memory map on network error
+      return Array.from(sandboxes.keys())
+        .filter((n) => n.startsWith(prefix))
+        .map((name) => ({ name }));
+    }
+  },
+
+  async exec(name, argv, opts) {
+    const sandboxId = sandboxes.get(name);
+    if (!sandboxId) throw new Error(`Modal sandbox not found for name: ${name}`);
+
+    const cmd = argv.map((a) => shellEscape(a)).join(" ");
+    const execBody: Record<string, unknown> = {
+      command: opts?.stdin ? `echo ${shellEscape(opts.stdin)} | ${cmd}` : cmd,
+    };
+
+    const res = await fetch(`${BASE_URL}/v1/sandboxes/${sandboxId}/exec`, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify(execBody),
+      signal: opts?.timeoutMs
+        ? AbortSignal.timeout(opts.timeoutMs)
+        : undefined,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Modal 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 sandboxId = sandboxes.get(name);
+    if (!sandboxId) throw new Error(`Modal sandbox not found for name: ${name}`);
+
+    const cmd = opts.argv.map((a) => shellEscape(a)).join(" ");
+    const execBody: Record<string, unknown> = {
+      command: opts.stdin ? `echo ${shellEscape(opts.stdin)} | ${cmd}` : cmd,
+    };
+
+    const res = await fetch(`${BASE_URL}/v1/sandboxes/${sandboxId}/exec`, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify(execBody),
+      signal: opts.signal,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Modal exec failed (${res.status}): ${text}`);
+    }
+
+    // Modal exec is buffered — wrap the complete response in a stream
+    const result = (await res.json()) as {
+      stdout?: string;
+      stderr?: string;
+      exit_code?: number;
+      exitCode?: number;
+    };
+
+    const encoder = new TextEncoder();
+    const stdoutText = result.stdout ?? "";
+    const exitCode = result.exit_code ?? result.exitCode ?? 0;
+
+    const stdout = new ReadableStream<Uint8Array>({
+      start(controller) {
+        if (stdoutText) {
+          controller.enqueue(encoder.encode(stdoutText));
+        }
+        controller.close();
+      },
+    });
+
+    return {
+      stdout,
+      exit: Promise.resolve({ code: exitCode }),
+      async kill() {
+        // Buffered exec — nothing to kill
+      },
+    };
+  },
+};