@sandblocks/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1018 @@
+// src/agents.ts
+class CommandAgent {
+  options;
+  id;
+  constructor(options) {
+    this.options = options;
+    this.id = options.id ?? "command";
+  }
+  async run(context) {
+    const startedAt = new Date().toISOString();
+    const base = typeof this.options.command === "function" ? this.options.command(context) : [...this.options.command];
+    const promptMode = this.options.prompt ?? "stdin";
+    const command = promptMode === "argument" ? [...base, context.prompt] : base;
+    const idle = new AbortController;
+    const completed = new AbortController;
+    let idleTimer;
+    let completionTimer;
+    const resetIdle = () => {
+      if (idleTimer)
+        clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => idle.abort(new Error(`agent idle timeout after ${context.idleTimeoutSeconds}s`)), context.idleTimeoutSeconds * 1000);
+    };
+    resetIdle();
+    let output = "";
+    let stdout = "";
+    let stderr = "";
+    let lineBuffer = "";
+    let completionSignal;
+    const consume = async (chunk, stream) => {
+      resetIdle();
+      output += chunk;
+      if (stream === "stdout")
+        stdout += chunk;
+      else
+        stderr += chunk;
+      lineBuffer += chunk;
+      const lines = lineBuffer.split(/\r?\n/);
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines)
+        await this.emitLine(line, stream, context);
+      completionSignal ??= context.completionSignal.find((signal) => output.includes(signal));
+      if (completionSignal && !completionTimer) {
+        completionTimer = setTimeout(() => completed.abort(new Error("agent did not exit after its completion signal")), context.completionTimeoutSeconds * 1000);
+      }
+    };
+    try {
+      const signals = [context.signal, idle.signal, completed.signal].filter(Boolean);
+      try {
+        const result = await context.runtime.exec(command, {
+          env: this.options.env,
+          stdin: promptMode === "stdin" ? context.prompt : undefined,
+          signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
+          onStdout: (chunk) => consume(chunk, "stdout"),
+          onStderr: (chunk) => consume(chunk, "stderr")
+        });
+        stdout = result.stdout;
+        stderr = result.stderr;
+        return this.result(context, startedAt, result.exitCode, stdout, stderr, completionSignal);
+      } catch (error) {
+        if (!completionSignal)
+          throw error;
+        return this.result(context, startedAt, 0, stdout, stderr, completionSignal);
+      }
+    } finally {
+      if (idleTimer)
+        clearTimeout(idleTimer);
+      if (completionTimer)
+        clearTimeout(completionTimer);
+      if (lineBuffer)
+        await this.emitLine(lineBuffer, "stdout", context);
+    }
+  }
+  result(context, startedAt, exitCode, stdout, stderr, completionSignal) {
+    const sessionId = this.options.sessionId?.(stdout, stderr);
+    return {
+      iteration: context.iteration,
+      exitCode,
+      stdout,
+      stderr,
+      ...sessionId ? { sessionId } : {},
+      ...completionSignal ? { completionSignal } : {},
+      startedAt,
+      finishedAt: new Date().toISOString()
+    };
+  }
+  async emitLine(line, stream, context) {
+    const timestamp = new Date().toISOString();
+    const parsed = this.options.parseEvent?.(line, { iteration: context.iteration, timestamp });
+    const events = parsed ? Array.isArray(parsed) ? parsed : [parsed] : [
+      {
+        type: "raw",
+        line: stream === "stderr" ? `[stderr] ${line}` : line,
+        iteration: context.iteration,
+        timestamp
+      }
+    ];
+    for (const event of events)
+      await context.emit(event);
+  }
+}
+
+class ClaudeCodeAgent extends CommandAgent {
+  constructor(options) {
+    super({
+      id: "claude-code",
+      env: credentialEnvironment(options.env, options.credential),
+      prompt: "argument",
+      command: (context) => [
+        options.binary ?? "claude",
+        "--print",
+        "--model",
+        options.model,
+        ...options.effort ? ["--effort", options.effort] : [],
+        ...options.extraArgs ?? []
+      ],
+      sessionId: extractSessionId,
+      parseEvent: parseJsonAgentEvent
+    });
+  }
+}
+
+class CodexAgent extends CommandAgent {
+  constructor(options) {
+    super({
+      id: "codex",
+      env: credentialEnvironment(options.env, options.credential),
+      prompt: "argument",
+      command: (context) => [
+        options.binary ?? "codex",
+        "exec",
+        "--model",
+        options.model,
+        ...options.reasoningEffort ? ["--config", `model_reasoning_effort=${options.reasoningEffort}`] : [],
+        ...options.extraArgs ?? []
+      ],
+      sessionId: extractSessionId,
+      parseEvent: parseJsonAgentEvent
+    });
+  }
+}
+
+class PiAgent extends CommandAgent {
+  constructor(options) {
+    super({
+      id: "pi",
+      env: credentialEnvironment(options.env, options.credential),
+      prompt: "argument",
+      command: (context) => [
+        options.binary ?? "pi",
+        "--print",
+        "--model",
+        options.model,
+        ...options.skills?.flatMap((skill) => ["--skill", skill]) ?? [],
+        ...options.extraArgs ?? []
+      ],
+      sessionId: extractSessionId,
+      parseEvent: parseJsonAgentEvent
+    });
+  }
+}
+var claudeCode = (model, options = {}) => new ClaudeCodeAgent({ model, ...options });
+var codex = (model, options = {}) => new CodexAgent({ model, ...options });
+var pi = (model, options = {}) => new PiAgent({ model, ...options });
+function parseJsonAgentEvent(line, context) {
+  let value;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return { type: "raw", line, ...context };
+  }
+  const type = String(value.type ?? "");
+  if (/tool/i.test(type)) {
+    return {
+      type: "toolCall",
+      name: String(value.name ?? value.tool ?? value.tool_name ?? "tool"),
+      ...value.input !== undefined ? { input: value.input } : {},
+      ...context
+    };
+  }
+  const text = value.text ?? value.message ?? value.content;
+  return typeof text === "string" ? { type: "text", text, ...context } : { type: "raw", line, ...context };
+}
+function credentialEnvironment(env, credential) {
+  if (!credential)
+    return env;
+  if (!/^[A-Z][A-Z0-9_]*$/.test(credential.environment))
+    throw new Error("credential environment name is invalid");
+  const value = process.env[credential.environment];
+  if (value === undefined)
+    return env;
+  const target = credential.target ?? credential.environment;
+  if (!/^[A-Z][A-Z0-9_]*$/.test(target))
+    throw new Error("credential target name is invalid");
+  return { ...env, [target]: value };
+}
+function extractSessionId(stdout, stderr) {
+  const match = `${stdout}
+${stderr}`.match(/(?:session[_ -]?id|session)[:=\s]+([A-Za-z0-9._-]{8,})/i);
+  return match?.[1];
+}
+
+// src/output.ts
+var Output = {
+  string(input) {
+    return { kind: "string", tag: validTag(input.tag) };
+  },
+  object(input) {
+    return { kind: "object", tag: validTag(input.tag), schema: input.schema };
+  }
+};
+async function extractOutput(spec, text) {
+  const pattern = new RegExp(`<${escapeRegex(spec.tag)}>([\\s\\S]*?)<\\/${escapeRegex(spec.tag)}>`);
+  const match = text.match(pattern);
+  if (!match)
+    throw new Error(`structured output tag <${spec.tag}> was not found`);
+  const content = match[1]?.trim();
+  if (content === undefined)
+    throw new Error(`structured output tag <${spec.tag}> is empty`);
+  if (spec.kind === "string")
+    return content;
+  let value;
+  try {
+    value = JSON.parse(content);
+  } catch {
+    throw new Error(`structured output <${spec.tag}> is not valid JSON`);
+  }
+  const schema = spec.schema;
+  if (schema["~standard"]) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues?.length)
+      throw new Error(`structured output validation failed: ${JSON.stringify(result.issues)}`);
+    return result.value;
+  }
+  if (schema.safeParse) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+      throw new Error(`structured output validation failed: ${String(result.error)}`);
+    return result.data;
+  }
+  if (schema.parse)
+    return schema.parse(value);
+  throw new Error("structured output schema is unsupported");
+}
+function validTag(tag) {
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(tag))
+    throw new Error("output tag is invalid");
+  return tag;
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/providers/custom.ts
+function createSandboxProvider(options) {
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(options.kind))
+    throw new Error("custom provider kind is invalid");
+  const reconnect = options.reconnect;
+  return {
+    kind: options.kind,
+    capabilities: Object.freeze({ ...options.capabilities }),
+    create: (input) => options.create(input),
+    ...reconnect ? { reconnect: (input) => reconnect(input) } : {}
+  };
+}
+function createBindMountSandboxProvider(options) {
+  return createSandboxProvider({
+    ...options,
+    capabilities: {
+      bindMounts: true,
+      isolatedFilesystem: true,
+      persistent: true,
+      networks: false,
+      devices: false,
+      snapshots: false,
+      reconnect: Boolean(options.reconnect),
+      remote: false,
+      ...options.capabilities
+    }
+  });
+}
+function createIsolatedSandboxProvider(options) {
+  return createSandboxProvider({
+    ...options,
+    capabilities: {
+      bindMounts: false,
+      isolatedFilesystem: true,
+      persistent: true,
+      networks: true,
+      devices: false,
+      snapshots: false,
+      reconnect: Boolean(options.reconnect),
+      remote: true,
+      ...options.capabilities
+    }
+  });
+}
+// src/orchestration.ts
+import { randomUUID } from "node:crypto";
+import { appendFile, cp, mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+// src/process.ts
+import { spawn } from "node:child_process";
+async function executeProcess(command, options = {}) {
+  if (!command.length || command.some((part) => !part || part.includes("\x00"))) {
+    throw new Error("command must contain safe non-empty arguments");
+  }
+  const startedAt = new Date().toISOString();
+  const [executable, ...args] = command;
+  if (!executable)
+    throw new Error("command executable is required");
+  const child = spawn(executable, args, {
+    cwd: options.cwd ?? options.hostCwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"]
+  });
+  if (options.stdin !== undefined)
+    child.stdin?.end(options.stdin);
+  let timedOut = false;
+  let stdout = "";
+  let stderr = "";
+  let callbackQueue = Promise.resolve();
+  child.stdout?.on("data", (chunk) => {
+    const text = chunk.toString();
+    stdout = `${stdout}${text}`.slice(-4 * 1024 * 1024);
+    callbackQueue = callbackQueue.then(() => options.onStdout?.(text)).then(() => {
+      return;
+    });
+  });
+  child.stderr?.on("data", (chunk) => {
+    const text = chunk.toString();
+    stderr = `${stderr}${text}`.slice(-4 * 1024 * 1024);
+    callbackQueue = callbackQueue.then(() => options.onStderr?.(text)).then(() => {
+      return;
+    });
+  });
+  const stop = () => child.kill("SIGTERM");
+  options.signal?.addEventListener("abort", stop, { once: true });
+  const timer = options.timeoutMs ? setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGKILL");
+  }, options.timeoutMs) : undefined;
+  try {
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+    await callbackQueue;
+    if (options.signal?.aborted)
+      throw options.signal.reason ?? new Error("operation aborted");
+    return {
+      exitCode: timedOut ? 124 : exitCode,
+      stdout,
+      stderr,
+      timedOut,
+      startedAt,
+      finishedAt: new Date().toISOString()
+    };
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    options.signal?.removeEventListener("abort", stop);
+  }
+}
+function expandHome(path) {
+  if (path === "~")
+    return process.env.HOME ?? path;
+  if (path.startsWith("~/"))
+    return `${process.env.HOME ?? "~"}/${path.slice(2)}`;
+  return path;
+}
+
+// src/orchestration.ts
+class SandblocksSandbox {
+  runtime;
+  options;
+  git;
+  id;
+  provider;
+  cwd;
+  failed = false;
+  disposed = false;
+  eventQueue = [];
+  eventWaiters = [];
+  constructor(runtime, options, git) {
+    this.runtime = runtime;
+    this.options = options;
+    this.git = git;
+    this.id = runtime.id;
+    this.provider = runtime.provider;
+    this.cwd = runtime.cwd;
+  }
+  exec(command, options = {}) {
+    return this.runtime.exec(command, options);
+  }
+  upload(source, destination) {
+    if (!this.runtime.upload)
+      throw new Error(`${this.provider} provider does not support upload`);
+    return this.runtime.upload(source, destination);
+  }
+  download(source, destination) {
+    if (!this.runtime.download)
+      throw new Error(`${this.provider} provider does not support download`);
+    return this.runtime.download(source, destination);
+  }
+  stop(reason) {
+    return this.runtime.stop(reason);
+  }
+  async* events(options = {}) {
+    while (!this.disposed || this.eventQueue.length) {
+      if (options.signal?.aborted)
+        return;
+      const queued = this.eventQueue.shift();
+      if (queued) {
+        yield queued;
+        continue;
+      }
+      const event = await new Promise((resolve2) => {
+        const abort = () => resolve2(undefined);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        this.eventWaiters.push((value) => {
+          options.signal?.removeEventListener("abort", abort);
+          resolve2(value);
+        });
+      });
+      if (!event)
+        return;
+      yield event;
+    }
+  }
+  async run(options) {
+    if (options.output && (options.maxIterations ?? 1) !== 1)
+      throw new Error("structured output requires maxIterations === 1");
+    const startedAt = new Date().toISOString();
+    const prompt = await resolvePrompt(options);
+    const signals = array(options.completionSignal ?? "<promise>COMPLETE</promise>");
+    const logger = createLogger(options.logging, this.git.hostCwd);
+    const baseline = await gitHead(this.git.runtimeCwd);
+    const iterations = [];
+    try {
+      await runSandboxHooks(this.runtime, options.hooks?.sandbox?.beforeAgent);
+      for (let iteration = 1;iteration <= (options.maxIterations ?? 1); iteration += 1) {
+        const result = await options.agent.run({
+          runtime: this.runtime,
+          prompt,
+          iteration,
+          signal: options.signal,
+          idleTimeoutSeconds: options.idleTimeoutSeconds ?? 600,
+          completionTimeoutSeconds: options.completionTimeoutSeconds ?? 60,
+          completionSignal: signals,
+          emit: async (event) => {
+            this.publish(event);
+            await logger(event);
+          }
+        });
+        iterations.push(result);
+        if (result.exitCode !== 0)
+          throw new Error(result.stderr || `${options.agent.id} exited ${result.exitCode}`);
+        if (result.completionSignal)
+          break;
+      }
+      await runSandboxHooks(this.runtime, options.hooks?.sandbox?.afterAgent);
+      await this.runtime.syncToHost?.();
+      const commits = await collectCommits(this.git.runtimeCwd, baseline, this.options.timeouts?.commitCollectionMs);
+      if (this.git.mergeToHead && this.git.branch)
+        await mergeBranch(this.git, this.options.timeouts?.mergeToHostMs);
+      const allOutput = iterations.map((item) => item.stdout).join(`
+`);
+      const completionSignal = iterations.find((item) => item.completionSignal)?.completionSignal;
+      return {
+        sandboxId: this.id,
+        provider: this.provider,
+        iterations,
+        commits,
+        ...this.git.branch ? { branch: this.git.branch } : {},
+        ...completionSignal ? { completionSignal } : {},
+        ...options.output ? { output: await extractOutput(options.output, allOutput) } : {},
+        startedAt,
+        finishedAt: new Date().toISOString()
+      };
+    } catch (error) {
+      this.failed = true;
+      throw error;
+    }
+  }
+  async destroy() {
+    if (this.disposed)
+      return;
+    this.disposed = true;
+    await runHostHooks(this.options.hooks?.host?.beforeDestroy, this.git.hostCwd);
+    const retention = this.options.retention ?? "destroy";
+    if (retention === "destroy" || retention === "on-failure" && !this.failed)
+      await this.runtime.destroy();
+    for (const waiter of this.eventWaiters.splice(0))
+      waiter(undefined);
+    if (this.git.worktree && retention !== "always") {
+      await executeProcess([
+        "git",
+        "-C",
+        this.git.hostCwd,
+        "worktree",
+        "remove",
+        "--force",
+        this.git.worktree
+      ]);
+      await rm(this.git.worktree, { recursive: true, force: true });
+    }
+  }
+  async[Symbol.asyncDispose]() {
+    await this.destroy();
+  }
+  publish(event) {
+    const waiter = this.eventWaiters.shift();
+    if (waiter)
+      waiter(event);
+    else
+      this.eventQueue.push(event);
+  }
+}
+async function createSandbox(options) {
+  const provider = options.provider ?? options.sandbox;
+  if (!provider)
+    throw new Error("sandbox provider is required");
+  assertProviderCapabilities(provider, options);
+  const hostCwd = resolve(options.cwd ?? process.cwd());
+  await runHostHooks(options.hooks?.host?.beforeCreate, hostCwd);
+  const branchStrategy = options.branch ?? options.branchStrategy ?? { type: "head" };
+  if (options.copyToWorktree?.length && branchStrategy.type === "head") {
+    throw new Error("copyToWorktree is not supported with the head branch strategy");
+  }
+  const git = await prepareGit(hostCwd, branchStrategy, options.timeouts?.gitSetupMs);
+  await runHostHooks(options.hooks?.host?.onWorktreeReady, git.runtimeCwd);
+  for (const file of options.copyToWorktree ?? []) {
+    const source = resolve(hostCwd, file);
+    const destination = resolve(git.runtimeCwd, file);
+    await mkdir(dirname(destination), { recursive: true });
+    await withTimeout(cp(source, destination, { recursive: true }), options.timeouts?.copyToWorktreeMs ?? 60000, `copying '${file}'`);
+  }
+  const id = options.id ?? randomUUID();
+  const runtime = await provider.create({
+    id,
+    cwd: git.runtimeCwd,
+    image: options.image,
+    env: options.env,
+    mounts: options.mounts,
+    network: options.network,
+    groups: options.groups,
+    devices: options.devices,
+    cpus: options.cpus,
+    memoryMb: options.memoryMb,
+    pids: options.pids,
+    tmpfsMb: options.tmpfsMb,
+    signal: options.signal,
+    idempotencyKey: options.idempotencyKey,
+    metadata: options.metadata
+  });
+  const sandbox = new SandblocksSandbox(runtime, options, git);
+  try {
+    await runHostHooks(options.hooks?.host?.onSandboxReady, hostCwd);
+    await runHostHooks(options.hooks?.host?.afterCreate, hostCwd);
+    await runSandboxHooks(runtime, options.hooks?.sandbox?.onSandboxReady);
+    await runSandboxHooks(runtime, options.hooks?.sandbox?.afterCreate);
+    return sandbox;
+  } catch (error) {
+    await sandbox.destroy().catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+async function connectSandbox(options) {
+  if (!options.provider.reconnect)
+    throw new Error(`${options.provider.kind} provider does not support reconnect`);
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const runtime = await options.provider.reconnect({ id: options.id, cwd });
+  return new SandblocksSandbox(runtime, { provider: options.provider, cwd, retention: options.retention ?? "always" }, { hostCwd: cwd, runtimeCwd: cwd });
+}
+async function run(options) {
+  const sandbox = await createSandbox(options);
+  try {
+    return await sandbox.run(options);
+  } finally {
+    await sandbox.destroy();
+  }
+}
+async function resolvePrompt(options) {
+  if (Boolean(options.prompt) === Boolean(options.promptFile))
+    throw new Error("provide exactly one of prompt or promptFile");
+  const promptFile = options.promptFile;
+  let prompt = options.prompt ?? await readFile(resolve(process.cwd(), promptFile ?? ""), "utf8");
+  for (const [key, value] of Object.entries(options.promptArgs ?? {}))
+    prompt = prompt.replaceAll(`{{${key}}}`, value);
+  return prompt;
+}
+async function prepareGit(hostCwd, strategy, timeoutMs = 30000) {
+  if (strategy.type === "head")
+    return { hostCwd, runtimeCwd: hostCwd };
+  const originalHead = await gitHead(hostCwd);
+  if (strategy.type === "branch") {
+    await checked(["git", "-C", hostCwd, "switch", "-C", strategy.name], timeoutMs);
+    return { hostCwd, runtimeCwd: hostCwd, branch: strategy.name, originalHead };
+  }
+  const branch = strategy.name ?? `sandblocks/${randomUUID().slice(0, 8)}`;
+  const worktree = resolve(hostCwd, ".sandblocks", "worktrees", branch.replace(/[^A-Za-z0-9_.-]/g, "-"));
+  await mkdir(dirname(worktree), { recursive: true });
+  await checked(["git", "-C", hostCwd, "worktree", "add", "-B", branch, worktree, "HEAD"], timeoutMs);
+  return {
+    hostCwd,
+    runtimeCwd: worktree,
+    branch,
+    worktree,
+    mergeToHead: strategy.type === "merge-to-head",
+    originalHead
+  };
+}
+async function mergeBranch(git, timeoutMs = 60000) {
+  if (!git.branch)
+    throw new Error("merge branch is unavailable");
+  await checked(["git", "-C", git.hostCwd, "merge", "--no-edit", git.branch], timeoutMs);
+}
+async function gitHead(cwd) {
+  const result = await executeProcess(["git", "-C", cwd, "rev-parse", "HEAD"]);
+  return result.exitCode === 0 ? result.stdout.trim() : "";
+}
+async function collectCommits(cwd, baseline, timeoutMs = 30000) {
+  if (!baseline)
+    return [];
+  const result = await executeProcess(["git", "-C", cwd, "log", "--format=%H%x00%s", `${baseline}..HEAD`], {
+    timeoutMs
+  });
+  if (result.exitCode !== 0 || !result.stdout.trim())
+    return [];
+  return result.stdout.trim().split(`
+`).map((line) => {
+    const [sha, message] = line.split("\x00");
+    if (!sha)
+      throw new Error("Git returned an invalid commit record");
+    return { sha, ...message ? { message } : {} };
+  });
+}
+async function checked(command, timeoutMs) {
+  const result = await executeProcess(command, { timeoutMs });
+  if (result.exitCode !== 0)
+    throw new Error(`${command[0]} failed: ${result.stderr || result.stdout}`);
+}
+async function runHostHooks(hooks, cwd) {
+  for (const hook of hooks ?? []) {
+    const command = hookCommand(hook);
+    const result = await executeProcess(command, {
+      cwd: resolve(cwd, hook.cwd ?? "."),
+      env: hook.env,
+      timeoutMs: hook.timeoutMs
+    });
+    if (result.exitCode !== 0)
+      throw new Error(`host hook failed: ${result.stderr || result.stdout}`);
+  }
+}
+async function runSandboxHooks(runtime, hooks) {
+  for (const hook of hooks ?? []) {
+    const result = await runtime.exec(hookCommand(hook), {
+      cwd: hook.cwd,
+      env: hook.env,
+      timeoutMs: hook.timeoutMs
+    });
+    if (result.exitCode !== 0)
+      throw new Error(`sandbox hook failed: ${result.stderr || result.stdout}`);
+  }
+}
+function hookCommand(hook) {
+  if (Boolean(hook.command) === Boolean(hook.shell))
+    throw new Error("hook requires exactly one of command or shell");
+  if (hook.command)
+    return hook.command;
+  if (!hook.shell)
+    throw new Error("hook shell command is required");
+  return ["sh", "-lc", hook.shell];
+}
+function createLogger(options, cwd) {
+  const config = options ?? { type: "file" };
+  const file = resolve(cwd, config.path ?? `.sandblocks/logs/${Date.now()}.log`);
+  return async (event) => {
+    const line = `${JSON.stringify(event)}
+`;
+    if (config.type === "stdout")
+      process.stdout.write(event.type === "text" ? event.text : event.type === "raw" ? `${event.line}
+` : line);
+    if (config.type !== "stdout" && config.type !== "silent") {
+      await mkdir(dirname(file), { recursive: true });
+      await appendFile(file, line);
+    }
+    try {
+      await config.onAgentStreamEvent?.(event);
+    } catch {}
+  };
+}
+async function withTimeout(promise, timeoutMs, label) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+}
+function assertProviderCapabilities(provider, options) {
+  const capabilities = provider.capabilities;
+  if (options.mounts?.length && !capabilities.bindMounts)
+    throw new Error(`${provider.kind} provider does not support bind mounts`);
+  if (options.network && !capabilities.networks)
+    throw new Error(`${provider.kind} provider does not support network selection`);
+  if (options.devices?.length && !capabilities.devices)
+    throw new Error(`${provider.kind} provider does not support devices`);
+  if ((options.retention === "always" || options.retention === "on-failure") && !capabilities.persistent)
+    throw new Error(`${provider.kind} provider does not support retained sandboxes`);
+}
+function array(value) {
+  return Array.isArray(value) ? value : [value];
+}
+// src/init.ts
+import { access, mkdir as mkdir2, writeFile } from "node:fs/promises";
+import { resolve as resolve2 } from "node:path";
+async function initSdk(options = {}) {
+  const cwd = resolve2(options.cwd ?? process.cwd());
+  const root = resolve2(cwd, ".sandblocks");
+  const files = {
+    "main.ts": `import { ClaudeCodeAgent, createSandbox } from "@sandblocks/sdk";
+import { DockerProvider } from "@sandblocks/sdk/providers/docker";
+
+await using sandbox = await createSandbox({
+  provider: new DockerProvider({ image: "node:22-bookworm" }),
+  cwd: process.cwd(),
+});
+
+const result = await sandbox.run({
+  agent: new ClaudeCodeAgent({ model: "claude-sonnet-4-6" }),
+  promptFile: ".sandblocks/prompts/implement.md",
+  logging: { type: "stdout" },
+});
+
+console.log(result);
+`,
+    "prompts/implement.md": `Implement the requested change, run the relevant checks, and commit the result.
+
+<promise>COMPLETE</promise>
+`,
+    ".env.example": `# Prefer Sandblocks managed secrets for remote providers.
+CLAUDE_CODE_OAUTH_TOKEN=
+# ANTHROPIC_API_KEY=
+SANDBLOCKS_API_URL=
+SANDBLOCKS_API_KEY=
+`,
+    "config.json": `${JSON.stringify({ provider: "docker", image: "node:22-bookworm", agent: "claude-code", model: "claude-sonnet-4-6", branchStrategy: "head" }, null, 2)}
+`
+  };
+  const written = [];
+  for (const [relative, content] of Object.entries(files)) {
+    const path = resolve2(root, relative);
+    await mkdir2(resolve2(path, ".."), { recursive: true });
+    if (!options.force && await access(path).then(() => true).catch(() => false))
+      continue;
+    await writeFile(path, content, { mode: relative.includes(".env") ? 384 : 420 });
+    written.push(path);
+  }
+  return written;
+}
+
+// src/index.ts
+class SandblocksClient {
+  options;
+  baseUrl;
+  fetchImpl;
+  constructor(options) {
+    this.options = options;
+    if (!options.apiKey.trim())
+      throw new Error("Sandblocks API key is required");
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  listSandboxes(projectId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/sandboxes`);
+  }
+  recordSandbox(projectId, sandbox) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/sandboxes`, {
+      method: "POST",
+      body: JSON.stringify(sandbox)
+    });
+  }
+  deployServices(input) {
+    return this.request(`/v1/projects/${encodeURIComponent(input.projectId)}/deployments`, {
+      method: "POST",
+      headers: { "idempotency-key": input.idempotencyKey },
+      body: JSON.stringify(input)
+    });
+  }
+  destroyServices(input) {
+    return this.request(`/v1/projects/${encodeURIComponent(input.projectId)}/deployments/${encodeURIComponent(input.deploymentId)}`, {
+      method: "DELETE",
+      headers: { "idempotency-key": input.idempotencyKey }
+    });
+  }
+  issueSandboxLease(input) {
+    return this.request(`/v1/projects/${encodeURIComponent(input.projectId)}/sandboxes/${encodeURIComponent(input.sandboxId)}/leases`, {
+      method: "POST",
+      body: JSON.stringify({ subject: input.subject, scopes: input.scopes, ttlSeconds: input.ttlSeconds })
+    });
+  }
+  listSandboxLeases(projectId, sandboxId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/sandboxes/${encodeURIComponent(sandboxId)}/leases`);
+  }
+  revokeSandboxLease(projectId, sandboxId, leaseId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/sandboxes/${encodeURIComponent(sandboxId)}/leases/${encodeURIComponent(leaseId)}`, { method: "DELETE" });
+  }
+  listRoutingAliases(projectId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/routing-aliases`);
+  }
+  listRoutingHistory(projectId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/routing-aliases/history`);
+  }
+  promoteRoutingAliases(projectId, sandboxId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/routing-aliases/promote`, {
+      method: "POST",
+      body: JSON.stringify({ sandboxId })
+    });
+  }
+  getRoutingPolicy(projectId, stack, deploymentType) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/routing-policies/${encodeURIComponent(stack)}/${encodeURIComponent(deploymentType)}`);
+  }
+  setRoutingPolicy(projectId, stack, deploymentType, policy) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/routing-policies/${encodeURIComponent(stack)}/${encodeURIComponent(deploymentType)}`, {
+      method: "PUT",
+      body: JSON.stringify(policy)
+    });
+  }
+  rollbackRoutingAliases(projectId, sandboxId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/routing-aliases/rollback`, {
+      method: "POST",
+      body: JSON.stringify({ sandboxId })
+    });
+  }
+  getSandbox(projectId, sandboxId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/sandboxes/${encodeURIComponent(sandboxId)}`);
+  }
+  createWorkspace(input) {
+    return this.request(`/v1/projects/${encodeURIComponent(input.projectId)}/workspaces`, {
+      method: "POST",
+      headers: {
+        "idempotency-key": input.idempotencyKey,
+        ...input.gitCredential ? { "x-sandblocks-git-credential": input.gitCredential } : {}
+      },
+      body: JSON.stringify({
+        workspaceId: input.workspaceId,
+        repositoryUrl: input.repositoryUrl,
+        revision: input.revision,
+        placement: input.placement
+      })
+    });
+  }
+  executeWorkspace(input) {
+    return this.request(`/v1/projects/${encodeURIComponent(input.projectId)}/workspaces/${encodeURIComponent(input.workspaceId)}/exec`, {
+      method: "POST",
+      headers: { "idempotency-key": input.idempotencyKey },
+      body: JSON.stringify({ executable: input.executable, args: input.args })
+    });
+  }
+  destroyWorkspace(input) {
+    return this.request(`/v1/projects/${encodeURIComponent(input.projectId)}/workspaces/${encodeURIComponent(input.workspaceId)}`, { method: "DELETE", headers: { "idempotency-key": input.idempotencyKey } });
+  }
+  getOperation(operationId) {
+    return this.request(`/v1/operations/${encodeURIComponent(operationId)}`);
+  }
+  listOperations(projectId, sandboxId) {
+    const query = sandboxId ? `?sandboxId=${encodeURIComponent(sandboxId)}` : "";
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/operations${query}`);
+  }
+  listOperationEvents(operationId) {
+    return this.request(`/v1/operations/${encodeURIComponent(operationId)}/events`);
+  }
+  cancelOperation(operationId) {
+    return this.request(`/v1/operations/${encodeURIComponent(operationId)}/cancel`, { method: "POST" });
+  }
+  cancelSandboxOperations(projectId, sandboxId) {
+    return this.request(`/v1/projects/${encodeURIComponent(projectId)}/sandboxes/${encodeURIComponent(sandboxId)}/operations/cancel`, { method: "POST" });
+  }
+  async waitForOperation(operationId, options = {}) {
+    const deadline = Date.now() + (options.timeoutMs ?? 120000);
+    while (Date.now() < deadline) {
+      const { operation } = await this.getOperation(operationId);
+      if (operation.state === "succeeded")
+        return operation;
+      if (["failed", "cancelled"].includes(operation.state)) {
+        throw new Error(operation.failureReason ?? `Sandblocks operation ${operation.state}`);
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, options.pollMs ?? 500));
+    }
+    throw new Error("Sandblocks operation timed out");
+  }
+  async request(path, init2 = {}) {
+    const headers = new Headers(init2.headers);
+    headers.set("x-sandblocks-api-key", this.options.apiKey);
+    if (init2.body)
+      headers.set("content-type", "application/json");
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, { ...init2, headers });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+      throw new Error(body.error ?? `Sandblocks request failed (${response.status})`);
+    return body;
+  }
+}
+
+class Sandblocks extends SandblocksClient {
+}
+
+class SandblocksSandboxClient {
+  baseUrl;
+  fetchImpl;
+  leaseToken;
+  sandboxId;
+  constructor(options) {
+    if (!options.leaseToken.startsWith("sbs_"))
+      throw new Error("Sandblocks sandbox lease token is required");
+    if (!/^[a-f0-9-]{36}$/.test(options.sandboxId))
+      throw new Error("Sandblocks sandbox ID is required");
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.leaseToken = options.leaseToken;
+    this.sandboxId = options.sandboxId;
+  }
+  getSession() {
+    return this.request("/v1/sandbox-session");
+  }
+  readFile(repository, path, idempotencyKey) {
+    return this.workspaceRequest(repository, "read", { path }, idempotencyKey);
+  }
+  search(repository, query, input, idempotencyKey) {
+    return this.workspaceRequest(repository, "search", { query, ...input }, idempotencyKey);
+  }
+  writeFile(repository, path, content, idempotencyKey) {
+    return this.workspaceRequest(repository, "write", { path, content }, idempotencyKey);
+  }
+  execute(repository, executable, args, idempotencyKey) {
+    return this.workspaceRequest(repository, "exec", { executable, args }, idempotencyKey);
+  }
+  git(repository, input, idempotencyKey) {
+    const { gitCredential, ...body } = input;
+    return this.workspaceRequest(repository, "git", body, idempotencyKey, gitCredential);
+  }
+  getOperation(operationId) {
+    return this.request(`/v1/sandbox-operations/${encodeURIComponent(operationId)}`);
+  }
+  listOperationEvents(operationId, after = 0) {
+    return this.request(`/v1/sandbox-operations/${encodeURIComponent(operationId)}/events?after=${after}`);
+  }
+  cancelOperation(operationId) {
+    return this.request(`/v1/sandbox-operations/${encodeURIComponent(operationId)}/cancel`, {
+      method: "POST"
+    });
+  }
+  async waitForOperation(operationId, options = {}) {
+    const deadline = Date.now() + (options.timeoutMs ?? 120000);
+    while (Date.now() < deadline) {
+      const { operation } = await this.getOperation(operationId);
+      if (operation.state === "succeeded")
+        return operation;
+      if (["failed", "cancelled"].includes(operation.state))
+        throw new Error(operation.failureReason ?? `Sandblocks operation ${operation.state}`);
+      await new Promise((resolve3) => setTimeout(resolve3, options.pollMs ?? 500));
+    }
+    throw new Error("Sandblocks sandbox operation timed out");
+  }
+  workspaceRequest(repository, action, body, idempotencyKey, gitCredential) {
+    return this.request(`/v1/sandboxes/${encodeURIComponent(this.sandboxId)}/workspaces/${encodeURIComponent(repository)}/${action}`, {
+      method: "POST",
+      headers: {
+        "idempotency-key": idempotencyKey,
+        ...gitCredential ? { "x-sandblocks-git-credential": gitCredential } : {}
+      },
+      body: JSON.stringify(body)
+    });
+  }
+  async request(path, init2 = {}) {
+    const headers = new Headers(init2.headers);
+    headers.set("authorization", `Bearer ${this.leaseToken}`);
+    if (init2.body)
+      headers.set("content-type", "application/json");
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, { ...init2, headers });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+      throw new Error(body.error ?? `Sandblocks sandbox request failed (${response.status})`);
+    return body;
+  }
+}
+export {
+  run,
+  pi,
+  initSdk,
+  extractOutput,
+  createSandboxProvider,
+  createSandbox,
+  createIsolatedSandboxProvider,
+  createBindMountSandboxProvider,
+  connectSandbox,
+  codex,
+  claudeCode,
+  SandblocksSandboxClient,
+  SandblocksSandbox,
+  SandblocksClient,
+  Sandblocks,
+  PiAgent,
+  Output,
+  CommandAgent,
+  CodexAgent,
+  ClaudeCodeAgent
+};