feat(acp): added codex-acp support (#105)

## What

<!-- Brief description of the changes -->
- Adds `codex-acp` support and adds a blueprint to the example builds
- Switches existing demos to use `agent_mounts` instead of blueprints
for every example.
- A few extra type guards and minor fixes

## Why

<!-- Motivation and context -->

## PR title format

<!--
PR titles must follow Conventional Commits: <type>(<scope>):
<description>

Types: feat | fix | docs | style | refactor | perf | test | build | ci |
chore | revert
  Scopes: sdk | acp | claude | examples | deps | project
  
  Examples:
    feat(sdk): add reconnect support
    fix(acp): handle timeout on long-running tasks
    docs(claude): update connection examples
    deps(sdk): bump @runloop/api-client to 1.5.0
    ci(project): add PR title validation workflow
-->

## Checklist

- [x] PR title follows `<type>(<scope>): <description>` format (see
above)
- [x] `bun run check` passes (lint + format)
- [x] `bun run build` passes
- [x] `bun run test` passes
- [ ] SDK documentation updated (if applicable)

Author: james-rl

README.md

@@ -280,18 +280,41 @@ See the [SDK documentation](sdk/README.md#custom-events-via-publish-and-tryparse
 
 See the [SDK documentation](sdk/README.md) for the full API reference, or browse the [hosted API docs](https://runloopai.github.io/agent-axon-client-ts/).
 
+## Getting Agents onto the Devbox
+
+There are two ways to ensure your agent binary is available on the devbox before execution starts:
+
+- **Agent mounts (late-binding)** — Install the agent at devbox creation time via a mount. The agent lands on the box just before the broker mount connects it to Axon. This works with any standard Runloop image, so you can pick or customize the base environment independently from the agent.
+- **Blueprints (pre-baked)** — Bake the agent (and any other tooling) directly into a custom devbox image. Subsequent devbox creations skip the install step entirely, giving you the fastest cold-start and a reproducible, versioned environment.
+
+The standalone examples (hello-world, CLI, combined-app) use a pre-baked **blueprint** for the fastest cold-start; the [feature-examples](examples/feature-examples/) default to **agent mounts** so they work with any standard image. Pick whichever fits your workflow — for example, blueprints when you want reproducible images, or mounts when you need to swap agent versions frequently or avoid maintaining custom images.
+
 ## Repository Structure
 
 ```
 sdk/                      → @runloop/agent-axon-client (the published npm package)
 examples/
+  blueprint/              → Builds the shared `axon-agents` blueprint (run this first)
   acp-hello-world/        → Minimal ACP single-prompt script
   acp-cli/                → Interactive ACP REPL
   claude-hello-world/     → Minimal Claude single-prompt script
   claude-cli/             → Interactive Claude REPL
   combined-app/           → Full-stack combined demo (Claude + ACP, Express + React)
+  feature-examples/       → Runnable SDK recipes (single-prompt, elicitation, etc.)
 ```
 
+### Running the examples
+
+> **Run the blueprint example first.** Every other example creates a devbox with `blueprint_name: "axon-agents"`. That blueprint is built by [`examples/blueprint`](examples/blueprint/) and must exist on your Runloop account before any other example will succeed.
+>
+> ```bash
+> bun install
+> bun run build
+> bun run build-blueprint   # one-time — builds the axon-agents blueprint
+> ```
+>
+> After the blueprint reports `build_complete`, you can run any of the other examples. See [`examples/blueprint/README.md`](examples/blueprint/README.md) for details and [`examples/README.md`](examples/README.md) for the full example index.
+
 ## Development
 
 **Prerequisites:**

bun.lock

@@ -8,11 +8,13 @@ Example applications and scripts showing how to use `@runloop/agent-axon-client`
 
 | Directory | Description |
 |-----------|-------------|
+| [`blueprint`](blueprint/) | **Run this first.** Builds the shared `axon-agents` Runloop blueprint that every other example depends on |
 | [`acp-hello-world`](acp-hello-world/) | Minimal ACP agent script — the simplest possible starting point |
 | [`acp-cli`](acp-cli/) | Interactive REPL for ACP-compatible agents (e.g. OpenCode) |
 | [`claude-hello-world`](claude-hello-world/) | Minimal Claude agent script — the simplest possible starting point |
 | [`claude-cli`](claude-cli/) | Interactive REPL for Claude Code agents |
 | [`combined-app`](combined-app/) | Full-stack combined demo (Claude + ACP) with a unified React UI |
+| [`feature-examples`](feature-examples/) | Runnable SDK recipes (single-prompt, elicitation, etc.) |
 
 ## Prerequisites
 
@@ -30,6 +32,23 @@ bun install
 bun run build
 ```
 
+### Build the shared blueprint (required, one-time)
+
+All examples create devboxes with `blueprint_name: "axon-agents"`. That blueprint is produced by the [`blueprint`](blueprint/) example and must exist on your Runloop account before any other example will succeed — otherwise devbox creation will fail.
+
+From the monorepo root:
+
+```bash
+export RUNLOOP_API_KEY=your_key
+bun run build-blueprint
+```
+
+Wait for the script to print `Blueprint build complete.`. You only need to do this once per account; re-run it to pick up changes to [`blueprint/Dockerfile`](blueprint/Dockerfile).
+
+See [`blueprint/README.md`](blueprint/README.md) for more detail, including what's baked into the image and alternatives to using a blueprint.
+
+### Run an example
+
 Each example reads `RUNLOOP_API_KEY` (and `ANTHROPIC_API_KEY` where needed) from the environment. Export them, or add a `.env` file in the example directory.
 
 See each example's own README for specific run instructions.

examples/README.md

@@ -17,8 +17,13 @@ bun install && bun run build
 
 # Set your API key
 export RUNLOOP_API_KEY=your_key
+
+# Build the shared `axon-agents` blueprint (one-time, required)
+bun run build-blueprint
 ```
 
+> This example creates a devbox with `blueprint_name: "axon-agents"`. The blueprint must be built once on your Runloop account before this example will work — otherwise `devbox.create()` will fail. See [`../blueprint`](../blueprint/) for details.
+
 ## Running
 
 ```bash

examples/acp-cli/README.md

@@ -4,6 +4,12 @@
  * Creates a Runloop Devbox + Axon session, connects via the ACP protocol,
  * and runs a REPL that streams session updates in real time.
  *
+ * Prerequisites:
+ *   - RUNLOOP_API_KEY must be set
+ *   - The shared `axon-agents` blueprint must exist on your Runloop account.
+ *     From the repo root, run `bun run build-blueprint` once before running
+ *     this example. See examples/blueprint/README.md for details.
+ *
  * Usage:
  *   bun run acp-cli.ts
  *   bun run acp-cli.ts --agent opencode
@@ -46,14 +52,14 @@ const AGENT_BINARY = args.agent ?? "opencode";
 const sdk = new RunloopSDK();
 
 console.log(`Starting devbox with agent "${AGENT_BINARY}"...`);
-// The runloop/agents blueprint has opencode pre-installed. The broker_mount
+// The axon-agents blueprint has agents pre-installed. The broker_mount
 // wires the Axon channel to the agent binary via the ACP protocol — the
 // broker launches the agent inside the devbox and bridges stdin/stdout to
 // the Axon event stream.
 const axon = await sdk.axon.create({ name: "acp-transport" });
 const devbox = await sdk.devbox.create({
   name: "acp-cli",
-  blueprint_name: "runloop/agents",
+  blueprint_name: "axon-agents",
   mounts: [
     {
       type: "broker_mount",

examples/acp-cli/acp-cli.ts

@@ -19,8 +19,13 @@ bun install && bun run build
 
 # Set your API key
 export RUNLOOP_API_KEY=your_key
+
+# Build the shared `axon-agents` blueprint (one-time, required)
+bun run build-blueprint
 ```
 
+> This example creates a devbox with `blueprint_name: "axon-agents"`. The blueprint must be built once on your Runloop account before this example will work — otherwise `devbox.create()` will fail. See [`../blueprint`](../blueprint/) for details.
+
 ## Running
 
 ```bash

examples/acp-hello-world/README.md

@@ -4,6 +4,12 @@
  * Creates a Runloop Devbox, connects via the ACP protocol,
  * sends a single prompt, prints the response, and exits.
  *
+ * Prerequisites:
+ *   - RUNLOOP_API_KEY must be set
+ *   - The shared `axon-agents` blueprint must exist on your Runloop account.
+ *     From the repo root, run `bun run build-blueprint` once before running
+ *     this example. See examples/blueprint/README.md for details.
+ *
  * Usage:
  *   bun run acp-hello-world.ts
  *   bun run acp-hello-world.ts --agent opencode
@@ -34,14 +40,14 @@ const AGENT_BINARY = args.agent ?? "opencode";
 const sdk = new RunloopSDK();
 
 console.log(`Starting devbox with agent "${AGENT_BINARY}"...`);
-// The runloop/agents blueprint has opencode pre-installed. The broker_mount
+// The axon-agents blueprint has agents pre-installed. The broker_mount
 // wires the Axon channel to the agent binary via the ACP protocol — the
 // broker launches the agent inside the devbox and bridges stdin/stdout to
 // the Axon event stream.
 const axon = await sdk.axon.create({ name: "acp-transport" });
 const devbox = await sdk.devbox.create({
   name: "acp-hello-world",
-  blueprint_name: "runloop/agents",
+  blueprint_name: "axon-agents",
   mounts: [
     {
       type: "broker_mount",

examples/acp-hello-world/acp-hello-world.ts

@@ -0,0 +1,9 @@
+FROM runloop:runloop/starter-x86_64
+
+RUN npm install -g @zed-industries/codex-acp
+
+USER user
+WORKDIR /home/user
+
+RUN curl -fsSL https://claude.ai/install.sh | bash
+RUN curl -fsSL https://opencode.ai/install | bash

examples/blueprint/Dockerfile

@@ -0,0 +1,49 @@
+# @runloop/example-blueprint
+
+> **Alpha — subject to change.** This example uses an SDK in early development. APIs and behavior may change without notice between versions.
+
+Builds the shared `axon-agents` Runloop [blueprint](https://docs.runloop.ai/guides/blueprints) used by examples that demonstrate pre-baked agent images. The blueprint bakes the agent binaries (Claude Code, OpenCode, Codex ACP) into a devbox image so subsequent devboxes start quickly and reproducibly.
+
+**You must run this once before any other example will work.** The other examples create devboxes with `blueprint_name: "axon-agents"` — if that blueprint does not exist on your Runloop account, devbox creation will fail.
+
+## Prerequisites
+
+- Node.js 22+ / [Bun](https://bun.sh)
+- A [Runloop](https://runloop.ai) API key (`RUNLOOP_API_KEY`)
+
+## Running
+
+From the monorepo root:
+
+```bash
+bun install
+bun run build-blueprint
+```
+
+Or directly from this directory:
+
+```bash
+cd examples/blueprint
+bun run build-blueprint.ts
+```
+
+The script builds the `axon-agents` blueprint and prints its status. A successful build ends with:
+
+```
+Blueprint build complete.
+Use blueprint_name: "axon-agents" in devbox.create()
+```
+
+You only need to do this once per Runloop account. Re-run it to update the image when the `Dockerfile` changes.
+
+## What's in the blueprint
+
+See [`Dockerfile`](Dockerfile) for the exact contents. At the time of writing it installs:
+
+- [Claude Code](https://docs.claude.com/en/docs/claude-code) — for the Claude module examples
+- [OpenCode](https://opencode.ai) — for ACP examples using OpenCode
+- [Codex ACP](https://www.npmjs.com/package/@zed-industries/codex-acp) — for ACP examples using Codex
+
+## Alternatives
+
+Using a pre-baked blueprint is the fastest path, but not the only option. You can instead attach agents to any standard Runloop image as late-binding mounts. See [Getting Agents onto the Devbox](../../README.md#getting-agents-onto-the-devbox) in the root README for a comparison.

examples/blueprint/README.md

@@ -0,0 +1,80 @@
+/**
+ * Build the shared agent blueprint for all examples.
+ *
+ * Usage:
+ *   bun run build-blueprint.ts
+ *
+ * Environment:
+ *   RUNLOOP_API_KEY - Required Runloop API key
+ *   RUNLOOP_BASE_URL - Optional API base URL override
+ */
+
+import { RunloopSDK } from "@runloop/api-client";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+export const BLUEPRINT_NAME = "axon-agents";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  const apiKey = process.env.RUNLOOP_API_KEY;
+  if (!apiKey) {
+    console.error("RUNLOOP_API_KEY not set");
+    process.exit(1);
+  }
+
+  const baseUrl = process.env.RUNLOOP_BASE_URL;
+  const sdk = new RunloopSDK({
+    bearerToken: apiKey,
+    ...(baseUrl ? { baseURL: baseUrl } : {}),
+  });
+
+  const dockerfilePath = join(__dirname, "Dockerfile");
+  const dockerfile = readFileSync(dockerfilePath, "utf-8");
+
+  console.log(`Building blueprint "${BLUEPRINT_NAME}"...`);
+  console.log("Dockerfile contents:");
+  console.log("---");
+  console.log(dockerfile);
+  console.log("---");
+
+  const blueprint = await sdk.blueprint.create({
+    name: BLUEPRINT_NAME,
+    dockerfile,
+    launch_parameters: {
+      user_parameters: {
+        uid: 1000,
+        username: "user",
+      },
+    },
+  });
+
+  console.log(`Blueprint created: ${blueprint.id}`);
+
+  // Get the final status
+  const info = await blueprint.getInfo();
+  console.log(`Name: ${info.name}`);
+  console.log(`Status: ${info.status}`);
+
+  if (info.status === "build_complete") {
+    console.log("\nBlueprint build complete.");
+    console.log(`Use blueprint_name: "${BLUEPRINT_NAME}" in devbox.create()`);
+  } else {
+    console.error(`\nUnexpected blueprint status: ${info.status}`);
+    const logs = await blueprint.logs();
+    if (logs.logs.length > 0) {
+      console.error("Build logs:");
+      for (const entry of logs.logs) {
+        console.error(`[${entry.level}] ${entry.message}`);
+      }
+    }
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});