feat: acp http adapter

examples/CLAUDE.md

@@ -6,16 +6,16 @@
 - Do not bind mount host files or host directories into Docker example containers.
 - If an example needs tools, skills, or MCP servers, install them inside the container during setup.
 
-## Testing Examples (ACP v2)
+## Testing Examples (ACP v1)
 
-Examples should be validated against v2 endpoints:
+Examples should be validated against v1 endpoints:
 
 1. Start the example: `SANDBOX_AGENT_DEV=1 pnpm start`
-2. Create an ACP client by POSTing `initialize` to `/v2/rpc` with `x-acp-agent: mock` (or another installed agent).
-3. Capture `x-acp-connection-id` from the response headers.
-4. Open SSE stream: `GET /v2/rpc` with `x-acp-connection-id`.
-5. Send `session/new` then `session/prompt` via `POST /v2/rpc` with the same connection id.
-6. Close connection via `DELETE /v2/rpc` with `x-acp-connection-id`.
+2. Pick a server id, for example `example-smoke`.
+3. Create ACP transport by POSTing `initialize` to `/v1/acp/example-smoke?agent=mock` (or another installed agent).
+4. Open SSE stream: `GET /v1/acp/example-smoke`.
+5. Send `session/new` then `session/prompt` via `POST /v1/acp/example-smoke`.
+6. Close connection via `DELETE /v1/acp/example-smoke`.
 
 v1 reminder:
 

examples/cloudflare/Dockerfile

@@ -1,7 +1,7 @@
 FROM cloudflare/sandbox:0.7.0
 
 # Install sandbox-agent
-RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
+RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
 
 # Pre-install agents
 RUN sandbox-agent install-agent claude && \

examples/daytona/src/daytona-with-snapshot.ts

@@ -1,6 +1,6 @@
 import { Daytona, Image } from "@daytonaio/sdk";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId, waitForHealth } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl, waitForHealth } from "@sandbox-agent/example-shared";
 
 const daytona = new Daytona();
 
@@ -13,7 +13,7 @@ if (process.env.OPENAI_API_KEY)
 // Build a custom image with sandbox-agent pre-installed (slower first run, faster subsequent runs)
 const image = Image.base("ubuntu:22.04").runCommands(
 	"apt-get update && apt-get install -y curl ca-certificates",
-	"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh",
+	"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
 );
 
 console.log("Creating Daytona sandbox (first run builds the base image and may take a few minutes, subsequent runs are fast)...");
@@ -29,8 +29,8 @@ console.log("Waiting for server...");
 await waitForHealth({ baseUrl });
 
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, { agent: detectAgent() });
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log("  Press Ctrl+C to stop.");

examples/daytona/src/index.ts

@@ -1,6 +1,6 @@
 import { Daytona } from "@daytonaio/sdk";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId, waitForHealth } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl, waitForHealth } from "@sandbox-agent/example-shared";
 
 const daytona = new Daytona();
 
@@ -17,7 +17,7 @@ const sandbox = await daytona.create({ envVars, autoStopInterval: 0 });
 // Install sandbox-agent and start server
 console.log("Installing sandbox-agent...");
 await sandbox.process.executeCommand(
-	"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh",
+	"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
 );
 
 await sandbox.process.executeCommand(
@@ -30,8 +30,8 @@ console.log("Waiting for server...");
 await waitForHealth({ baseUrl });
 
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, { agent: detectAgent() });
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log("  Press Ctrl+C to stop.");

examples/docker/src/index.ts

@@ -1,6 +1,6 @@
 import Docker from "dockerode";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId, waitForHealth } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl, waitForHealth } from "@sandbox-agent/example-shared";
 
 const IMAGE = "alpine:latest";
 const PORT = 3000;
@@ -25,7 +25,7 @@ const container = await docker.createContainer({
   Image: IMAGE,
   Cmd: ["sh", "-c", [
     "apk add --no-cache curl ca-certificates libstdc++ libgcc bash",
-    "curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh",
+    "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
     "sandbox-agent install-agent claude",
     "sandbox-agent install-agent codex",
     `sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`,
@@ -46,8 +46,8 @@ const baseUrl = `http://127.0.0.1:${PORT}`;
 await waitForHealth({ baseUrl });
 
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, { agent: detectAgent() });
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log("  Press Ctrl+C to stop.");

examples/e2b/src/index.ts

@@ -1,6 +1,6 @@
 import { Sandbox } from "@e2b/code-interpreter";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId, waitForHealth } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl, waitForHealth } from "@sandbox-agent/example-shared";
 
 const envs: Record<string, string> = {};
 if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
@@ -16,7 +16,7 @@ const run = async (cmd: string) => {
 };
 
 console.log("Installing sandbox-agent...");
-await run("curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh");
+await run("curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh");
 
 console.log("Installing agents...");
 await run("sandbox-agent install-agent claude");
@@ -31,8 +31,8 @@ console.log("Waiting for server...");
 await waitForHealth({ baseUrl });
 
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, { agent: detectAgent() });
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log("  Press Ctrl+C to stop.");

examples/file-system/src/index.ts

@@ -1,5 +1,5 @@
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
 import { startDockerSandbox } from "@sandbox-agent/example-shared/docker";
 import * as tar from "tar";
 import fs from "node:fs";
@@ -47,8 +47,8 @@ const readmeText = new TextDecoder().decode(readmeBytes);
 console.log(`  README.md content: ${readmeText.trim()}`);
 
 console.log("Creating session...");
-const sessionId = generateSessionId();
-await client.createSession(sessionId, { agent: detectAgent() });
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/opt/my-project" } });
+const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "read the README in /opt/my-project"');
 console.log("  Press Ctrl+C to stop.");

examples/mcp-custom-tool/src/index.ts

@@ -1,5 +1,5 @@
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
 import { startDockerSandbox } from "@sandbox-agent/example-shared/docker";
 import fs from "node:fs";
 import path from "node:path";
@@ -31,16 +31,19 @@ console.log(`  Written: ${written.path} (${written.bytesWritten} bytes)`);
 
 // Create a session with the uploaded MCP server as a local command.
 console.log("Creating session with custom MCP tool...");
-const sessionId = generateSessionId();
-await client.createSession(sessionId, {
+const session = await client.createSession({
   agent: detectAgent(),
-  mcp: {
-    customTools: {
-      type: "local",
-      command: ["node", "/opt/mcp/custom-tools/mcp-server.cjs"],
-    },
+  sessionInit: {
+    cwd: "/root",
+    mcpServers: [{
+      name: "customTools",
+      command: "node",
+      args: ["/opt/mcp/custom-tools/mcp-server.cjs"],
+      env: [],
+    }],
   },
 });
+const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "generate a random number between 1 and 100"');
 console.log("  Press Ctrl+C to stop.");

examples/mcp/src/index.ts

@@ -1,5 +1,5 @@
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
 import { startDockerSandbox } from "@sandbox-agent/example-shared/docker";
 
 console.log("Starting sandbox...");
@@ -12,17 +12,19 @@ const { baseUrl, cleanup } = await startDockerSandbox({
 
 console.log("Creating session with everything MCP server...");
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, {
+const session = await client.createSession({
   agent: detectAgent(),
-  mcp: {
-    everything: {
-      type: "local",
-      command: ["mcp-server-everything"],
-      timeoutMs: 10000,
-    },
+  sessionInit: {
+    cwd: "/root",
+    mcpServers: [{
+      name: "everything",
+      command: "mcp-server-everything",
+      args: [],
+      env: [],
+    }],
   },
 });
+const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "generate a random number between 1 and 100"');
 console.log("  Press Ctrl+C to stop.");

examples/mock-acp-agent/README.md

@@ -0,0 +1,9 @@
+# @sandbox-agent/mock-acp-agent
+
+Minimal newline-delimited ACP JSON-RPC mock agent.
+
+Behavior:
+- Echoes every inbound message as `mock/echo` notification.
+- For requests (`method` + `id`), returns `result.echoed` payload.
+- For `mock/ask_client`, emits an agent-initiated `mock/request` before response.
+- For responses from client (`id` without `method`), emits `mock/client_response` notification.

examples/mock-acp-agent/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@sandbox-agent/mock-acp-agent",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Mock ACP agent for adapter integration testing",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "start": "node ./dist/index.js"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

examples/mock-acp-agent/src/index.ts

@@ -0,0 +1,100 @@
+import { createInterface } from "node:readline";
+
+interface JsonRpcRequest {
+  jsonrpc?: unknown;
+  id?: unknown;
+  method?: unknown;
+  params?: unknown;
+  result?: unknown;
+  error?: unknown;
+}
+
+let outboundRequestSeq = 0;
+
+function writeMessage(payload: unknown): void {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function echoNotification(message: unknown): void {
+  writeMessage({
+    jsonrpc: "2.0",
+    method: "mock/echo",
+    params: {
+      message,
+    },
+  });
+}
+
+function handleMessage(raw: string): void {
+  if (!raw.trim()) {
+    return;
+  }
+
+  let msg: JsonRpcRequest;
+  try {
+    msg = JSON.parse(raw) as JsonRpcRequest;
+  } catch (error) {
+    writeMessage({
+      jsonrpc: "2.0",
+      method: "mock/parse_error",
+      params: {
+        error: error instanceof Error ? error.message : String(error),
+        raw,
+      },
+    });
+    return;
+  }
+
+  echoNotification(msg);
+
+  const hasMethod = typeof msg.method === "string";
+  const hasId = msg.id !== undefined;
+
+  if (hasMethod && hasId) {
+    if (msg.method === "mock/ask_client") {
+      outboundRequestSeq += 1;
+      writeMessage({
+        jsonrpc: "2.0",
+        id: `agent-req-${outboundRequestSeq}`,
+        method: "mock/request",
+        params: {
+          prompt: "please respond",
+        },
+      });
+    }
+
+    writeMessage({
+      jsonrpc: "2.0",
+      id: msg.id,
+      result: {
+        echoed: msg,
+      },
+    });
+    return;
+  }
+
+  if (!hasMethod && hasId) {
+    writeMessage({
+      jsonrpc: "2.0",
+      method: "mock/client_response",
+      params: {
+        id: msg.id,
+        result: msg.result ?? null,
+        error: msg.error ?? null,
+      },
+    });
+  }
+}
+
+const rl = createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity,
+});
+
+rl.on("line", (line) => {
+  handleMessage(line);
+});
+
+rl.on("close", () => {
+  process.exit(0);
+});

examples/mock-acp-agent/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": false,
+    "noEmit": false,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}

examples/mock-acp-agent/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

examples/shared/Dockerfile.dev

@@ -6,9 +6,11 @@ WORKDIR /build
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
 
 # Copy packages needed for the inspector build chain:
-#   inspector -> sandbox-agent SDK -> cli-shared
+#   inspector -> sandbox-agent SDK -> acp-http-client, cli-shared, persist-indexeddb
 COPY sdks/typescript/ sdks/typescript/
+COPY sdks/acp-http-client/ sdks/acp-http-client/
 COPY sdks/cli-shared/ sdks/cli-shared/
+COPY sdks/persist-indexeddb/ sdks/persist-indexeddb/
 COPY frontend/packages/inspector/ frontend/packages/inspector/
 COPY docs/openapi.json docs/
 
@@ -16,6 +18,7 @@ COPY docs/openapi.json docs/
 # but not needed for the inspector build (avoids install errors).
 RUN set -e; for dir in \
       sdks/cli sdks/gigacode \
+      sdks/persist-postgres sdks/persist-sqlite sdks/persist-rivet \
       resources/agent-schemas resources/vercel-ai-sdk-schemas \
       scripts/release scripts/sandbox-testing \
       examples/shared examples/docker examples/e2b examples/vercel \
@@ -44,6 +47,7 @@ COPY Cargo.toml Cargo.lock ./
 COPY server/ ./server/
 COPY gigacode/ ./gigacode/
 COPY resources/agent-schemas/artifacts/ ./resources/agent-schemas/artifacts/
+COPY scripts/agent-configs/ ./scripts/agent-configs/
 COPY --from=frontend /build/frontend/packages/inspector/dist/ ./frontend/packages/inspector/dist/
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \

examples/skills-custom-tool/src/index.ts

@@ -1,5 +1,5 @@
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
 import { startDockerSandbox } from "@sandbox-agent/example-shared/docker";
 import fs from "node:fs";
 import path from "node:path";
@@ -36,15 +36,17 @@ const skillResult = await client.writeFsFile(
 );
 console.log(`  Skill:  ${skillResult.path} (${skillResult.bytesWritten} bytes)`);
 
-// Create a session with the uploaded skill as a local source.
+// Configure the uploaded skill.
+console.log("Configuring custom skill...");
+await client.setSkillsConfig(
+  { directory: "/", skillName: "random-number" },
+  { sources: [{ type: "local", source: "/opt/skills/random-number" }] },
+);
+
+// Create a session.
 console.log("Creating session with custom skill...");
-const sessionId = generateSessionId();
-await client.createSession(sessionId, {
-  agent: detectAgent(),
-  skills: {
-    sources: [{ type: "local", source: "/opt/skills/random-number" }],
-  },
-});
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "generate a random number between 1 and 100"');
 console.log("  Press Ctrl+C to stop.");

examples/skills/src/index.ts

@@ -1,5 +1,5 @@
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
 import { startDockerSandbox } from "@sandbox-agent/example-shared/docker";
 
 console.log("Starting sandbox...");
@@ -7,17 +7,16 @@ const { baseUrl, cleanup } = await startDockerSandbox({
   port: 3001,
 });
 
-console.log("Creating session with skill source...");
+console.log("Configuring skill source...");
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, {
-  agent: detectAgent(),
-  skills: {
-    sources: [
-      { type: "github", source: "rivet-dev/skills", skills: ["sandbox-agent"] },
-    ],
-  },
-});
+await client.setSkillsConfig(
+  { directory: "/", skillName: "rivet-dev-skills" },
+  { sources: [{ type: "github", source: "rivet-dev/skills", skills: ["sandbox-agent"] }] },
+);
+
+console.log("Creating session...");
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "How do I start sandbox-agent?"');
 console.log("  Press Ctrl+C to stop.");

examples/vercel/src/index.ts

@@ -1,6 +1,6 @@
 import { Sandbox } from "@vercel/sandbox";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl, generateSessionId, waitForHealth } from "@sandbox-agent/example-shared";
+import { detectAgent, buildInspectorUrl, waitForHealth } from "@sandbox-agent/example-shared";
 
 const envs: Record<string, string> = {};
 if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
@@ -22,7 +22,7 @@ const run = async (cmd: string, args: string[] = []) => {
 };
 
 console.log("Installing sandbox-agent...");
-await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"]);
+await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"]);
 
 console.log("Installing agents...");
 await run("sandbox-agent", ["install-agent", "claude"]);
@@ -42,8 +42,8 @@ console.log("Waiting for server...");
 await waitForHealth({ baseUrl });
 
 const client = await SandboxAgent.connect({ baseUrl });
-const sessionId = generateSessionId();
-await client.createSession(sessionId, { agent: detectAgent() });
+const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root" } });
+const sessionId = session.id;
 
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log("  Press Ctrl+C to stop.");