@sandblocks/sdk 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @sandblocks/sdk
+
+Programmatic Sandblocks sandbox and agent orchestration for Node.js, Bun, and TypeScript.
+
+```bash
+npm install --save-dev @sandblocks/sdk
+npx sandblocks-sdk init
+```
+
+```ts
+import { run, CodexAgent } from "@sandblocks/sdk";
+import { DockerProvider } from "@sandblocks/sdk/providers/docker";
+
+const result = await run({
+  provider: new DockerProvider({ image: "node:22-bookworm" }),
+  agent: new CodexAgent({ model: "gpt-5.3-codex" }),
+  prompt: "Implement and verify the requested change.",
+});
+```
+
+See [`docs/SDK.md`](../../../docs/SDK.md) in the Sandblocks repository for providers, reusable sandboxes, hooks, worktrees, logging, structured output, security, and CLI parity.

package/dist/agents.js

@@ -0,0 +1,209 @@
+// 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];
+}
+export {
+  pi,
+  codex,
+  claudeCode,
+  PiAgent,
+  CommandAgent,
+  CodexAgent,
+  ClaudeCodeAgent
+};

package/dist/bin.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+// src/init.ts
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+async function initSdk(options = {}) {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const root = resolve(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 = resolve(root, relative);
+    await mkdir(resolve(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/bin.ts
+var [command, directory] = process.argv.slice(2);
+if (command !== "init") {
+  console.error("Usage: sandblocks-sdk init [directory]");
+  process.exitCode = 1;
+} else {
+  const files = await initSdk({ cwd: directory, force: process.argv.includes("--force") });
+  console.log(files.length ? `Created ${files.length} SDK files` : "SDK files already exist");
+}