docs(sdk): codex examples, compatibility matrix, and module docs (#137)

Third and final PR of the codex-native stack (PLAN Step 3), stacked on
#135 (`feat/codex-connection`), which is stacked on #134. See
`sdk/src/codex/PLAN.md`.

## Examples

- **`feature-examples/src/agents.ts`**: adds a native `codex` agent
(`broker_mount: { protocol: "codex", agent_binary: "codex" }`,
`OPENAI_API_KEY` secret). `codex-acp` is kept — downstream consumers
still use it.
- **New use cases** demonstrating codex-native behavior that differs
from Claude:
- `approval-codex` — server-initiated command approval round-trip via
`onApprovalRequest` (thread started with `sandbox: "read-only"` +
`approvalPolicy: "on-request"` to force an approval; both the current
and legacy approval methods are handled).
- `thread-resume-codex` — client-driven `resumeThread()`: establish
context on thread A, switch to a fresh thread B, resume A, and verify
the codeword is still in context.
- **Framework plumbing**: `types.ts`/`scaffold.ts`/`main.ts` extended
with the `codex` protocol (connection setup with no initialize step,
`--protocol codex` filter, Codex column in the generated matrix).
- **Blueprint**: `examples/blueprint/Dockerfile` now installs
`@openai/codex@0.144.1` (matches the SDK's vendored-protocol pin).

## Compatibility matrix

`compatibility.md` (and the `llms.txt` use-case index) were **updated by
hand, not machine-regenerated** — running `feature-compat` requires live
`RUNLOOP_API_KEY`/`OPENAI_API_KEY` credentials plus broker-side codex
support, none of which are available in this environment. The hand-edit
matches the generator's output format exactly: codex cells show
`pending` (the generator's no-results status), and the
template/generator were updated so the next full run produces the Codex
column automatically. `bun run feature-compat --validate` passes against
the hand-edited files.

## Docs

- **`sdk/README.md`**: Codex row in the module table, broker `protocol`
option table (`acp` / `claude_json` / `codex`), Codex quickstart
mirroring the Claude one, a full "Codex Module" section (connection
options, methods, approval requests incl. the `approval_policy=never`
launch-args alternative, timeline guards, transport), Codex timeline
events, architecture comparison, and updated known limitations.
- **`sdk/AGENTS.md`**: module table, codex quick start + key-methods
table, `codex_protocol` timeline kind, constraints (auto-approve
default, no initialize step, no extra dependency).

## Validation

- `bun run check` / `bun run typecheck` / `bun run build` / `bun run
test` (529 tests) — pass
- `feature-examples`: `bun run typecheck` and `bun run feature-compat
--validate` — pass
- The new use cases could **not** be executed end-to-end here (no live
credentials); they typecheck against the vendored protocol types.

## Notes for reviewers

- The `codex` agent entry assumes a `codex` agent exists in the Runloop
agent catalog (mirroring `codex-acp`); adjust `agentName` if the catalog
entry differs.
- `scaffold.ts` casts the broker-mount `protocol` because the published
`@runloop/api-client` (≤1.25.0) doesn't include `"codex"` in its mount
types yet — drop the cast once the client catches up.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Combined app (added in follow-up)

`examples/combined-app` now supports Codex as a third agent type
end-to-end:

- **Server**: `codex-manager.ts` (provisions a `protocol: "codex"`
broker mount pointing at `/home/user/.local/bin/codex`, injects
`OPENAI_API_KEY`, starts a thread, maps
`workingDir`/`model`/`systemPrompt` onto `threadStartParams`),
`routes/codex.ts` (`POST /api/approval-response`), plus codex branches
in lifecycle/prompt/cancel routes and the agent registry. With
"Auto-approve approvals" off, the thread starts with `approvalPolicy:
"on-request"` and command/file approvals are forwarded to the browser;
with it on, the SDK's default auto-approve handlers answer.
- **Client**: `useCodexAgent` hook renders app-server frames as turn
blocks (agent-message deltas → text, reasoning deltas → thinking,
commandExecution/fileChange/mcpToolCall/webSearch items → tool calls
with streamed output), an `ApprovalPrompt` dialog for interactive
approvals, a Codex button + fields in the setup card, timeline sidebar
CODEX badges, and thread-id display.
- Attachments: images are sent as data-URL `UserInput` image items; file
attachments are flattened into text.
- Validation: `tsc --noEmit` and `vite build` pass; the Express server
boots with the new routes. Not exercised against a live devbox (no
credentials here).

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Reflex <reflex@runloop.ai>
Co-authored-by: OpenAI Codex <noreply@openai.com>
Co-authored-by: OpenAI Codex <codex@openai.com>

Author: 4 people

README.md

@@ -295,7 +295,7 @@ examples/
   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)
+  combined-app/           → Full-stack combined demo (Claude + Codex + ACP, Express + React)
   feature-examples/       → Runnable SDK recipes (single-prompt, elicitation, etc.)
 ```
 

examples/blueprint/Dockerfile

@@ -7,3 +7,4 @@ WORKDIR /home/user
 
 RUN curl -fsSL https://claude.ai/install.sh | bash
 RUN curl -fsSL https://opencode.ai/install | bash
+RUN curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=true sh -s -- --release 0.144.1

examples/blueprint/README.md

@@ -43,6 +43,7 @@ See [`Dockerfile`](Dockerfile) for the exact contents. At the time of writing it
 - [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
+- [Codex CLI](https://developers.openai.com/codex/cli) — for native Codex module examples (pinned to 0.144.1, matching the SDK's vendored protocol types)
 
 ## Alternatives
 

examples/combined-app/.env.example

@@ -1,2 +1,3 @@
 RUNLOOP_API_KEY=your_runloop_api_key
 ANTHROPIC_API_KEY=your_anthropic_api_key
+OPENAI_API_KEY=your_openai_api_key

examples/combined-app/README.md

@@ -2,13 +2,14 @@
 
 > **Alpha — subject to change.** This example uses an SDK in early development. APIs and behavior may change without notice between versions.
 
-A full-stack demo that supports both ACP and Claude Code agents running in Runloop devboxes. An Express backend manages agent connections (one per protocol) and fans out SDK timeline events to a React frontend over a single WebSocket. Multiple agents can run concurrently.
+A full-stack demo that supports ACP, Claude Code, and Codex agents running in Runloop devboxes. An Express backend manages agent connections (one per protocol) and fans out SDK timeline events to a React frontend over a single WebSocket. Multiple agents can run concurrently.
 
 ## Prerequisites
 
 - Node.js 22+
 - A [Runloop](https://runloop.ai) API key
 - An [Anthropic](https://anthropic.com) API key (required for Claude agents)
+- An [OpenAI](https://platform.openai.com) API key (required for Codex agents)
 - The `@runloop/remote-agents-sdk` SDK built locally (`cd ../../sdk && bun run build`)
 
 ## Setup
@@ -27,11 +28,12 @@ Add your keys to `.env`:
 ```
 RUNLOOP_API_KEY=your_runloop_api_key
 ANTHROPIC_API_KEY=your_anthropic_api_key
+OPENAI_API_KEY=your_openai_api_key
 ```
 
 ### Build the shared blueprint (one-time, required)
 
-This example provisions devboxes with `blueprint_name: "axon-agents"` (see [`src/server/acp-manager.ts`](src/server/acp-manager.ts) and [`src/server/claude-manager.ts`](src/server/claude-manager.ts)). That blueprint must exist on your Runloop account before starting an agent from the UI — otherwise `POST /api/start` will fail when creating the devbox.
+This example provisions devboxes with `blueprint_name: "axon-agents"` (see [`src/server/acp-manager.ts`](src/server/acp-manager.ts), [`src/server/claude-manager.ts`](src/server/claude-manager.ts), and [`src/server/codex-manager.ts`](src/server/codex-manager.ts)). That blueprint must exist on your Runloop account before starting an agent from the UI — otherwise `POST /api/start` will fail when creating the devbox. Codex agents require a blueprint built after the Codex CLI was added to the [`Dockerfile`](../blueprint/Dockerfile) — re-run the command below if your `axon-agents` image predates it.
 
 From the monorepo root:
 
@@ -55,8 +57,8 @@ Open http://localhost:5176. The Vite dev server proxies `/api/*` and `/ws` to th
 
 ## How It Works
 
-1. **Start an agent** — the setup card lets you choose ACP or Claude, configure the agent binary / blueprint, and optionally set a system prompt. `POST /api/start` provisions an Axon channel and devbox, then opens the appropriate SDK connection (`ACPAxonConnection` or `ClaudeAxonConnection`).
-2. **Send a prompt** — `POST /api/prompt` dispatches to the active connection's `prompt()` (ACP) or `send()` (Claude) and returns immediately.
+1. **Start an agent** — the setup card lets you choose ACP, Claude, or Codex, configure the agent binary / blueprint, and optionally set a system prompt. `POST /api/start` provisions an Axon channel and devbox, then opens the appropriate SDK connection (`ACPAxonConnection`, `ClaudeAxonConnection`, or `CodexAxonConnection`).
+2. **Send a prompt** — `POST /api/prompt` dispatches to the active connection's `prompt()` (ACP) or `send()` (Claude/Codex) and returns immediately.
 3. **Stream events** — the SDK's `onTimelineEvent` callback fires for every classified event (protocol messages, system turns, unknowns). The server broadcasts each event over WebSocket with an `agentId` tag.
 4. **Render blocks** — the React client filters events by `agentId`, builds incremental turn blocks (`useBlockManager`), and renders them through `AssistantTurn` / `TurnBlocks`.
 
@@ -72,6 +74,7 @@ src/
 │   ├── acp-manager.ts       ACP connection lifecycle
 │   ├── acp-client.ts        ACP Client implementation (permissions, elicitation)
 │   ├── claude-manager.ts    Claude connection lifecycle
+│   ├── codex-manager.ts     Codex connection lifecycle (threads, approvals)
 │   └── agent-registry.ts    Multi-agent bookkeeping
 └── client/
     ├── main.tsx             React entry point
@@ -81,6 +84,7 @@ src/
     │   ├── useAgent.ts      Unified hook (delegates to protocol-specific hooks)
     │   ├── useACPAgent.ts   ACP event handling and state
     │   ├── useClaudeAgent.ts Claude event handling and state
+    │   ├── useCodexAgent.ts Codex event handling and state (items, approvals)
     │   ├── useBlockManager.ts Turn block accumulation
     │   ├── useAgentList.ts  Agent list polling
     │   ├── useAttachments.ts File/image attachment handling

examples/combined-app/src/client/App.css

@@ -1874,6 +1874,7 @@ html, body, #root {
 .tl-kind-system { background: rgba(210, 153, 34, 0.15); color: var(--warning); }
 .tl-kind-acp { background: rgba(63, 185, 80, 0.15); color: var(--success); }
 .tl-kind-claude { background: rgba(136, 87, 255, 0.15); color: #a78bfa; }
+.tl-kind-codex { background: rgba(240, 246, 252, 0.12); color: #e6edf3; }
 .tl-kind-unknown { background: rgba(139, 148, 158, 0.15); color: var(--text-secondary); }
 .tl-kind-custom { background: rgba(56, 189, 248, 0.15); color: #38bdf8; }
 

examples/combined-app/src/client/App.tsx

@@ -15,6 +15,7 @@ import { AgentSidebar } from "./components/AgentSidebar.js";
 import { ControlsBar } from "./components/ControlsBar.js";
 import { AssistantTurn } from "./components/AssistantTurn.js";
 import { AttachmentBar } from "./components/AttachmentBar.js";
+import { ApprovalPrompt } from "./components/ApprovalPrompt.js";
 import { ElicitationForm } from "./components/ElicitationForm.js";
 import { PermissionDialog } from "./components/PermissionDialog.js";
 import { ControlRequestPrompt } from "./components/ControlRequestPrompt.js";
@@ -234,12 +235,19 @@ export default function App() {
           autoApprovePermissions: startAutoApprove,
           ...sharedConfig,
         }
-      : {
-          blueprintName: blueprintName || undefined,
-          model: model || undefined,
-          dangerouslySkipPermissions: startAutoApprove,
-          ...sharedConfig,
-        };
+      : selectedAgentType === "codex"
+        ? {
+            blueprintName: blueprintName || undefined,
+            model: model || undefined,
+            autoApprovePermissions: startAutoApprove,
+            ...sharedConfig,
+          }
+        : {
+            blueprintName: blueprintName || undefined,
+            model: model || undefined,
+            dangerouslySkipPermissions: startAutoApprove,
+            ...sharedConfig,
+          };
 
     try {
       const resp = await api<{ agentId: string; agentType: AgentType; [key: string]: unknown }>(
@@ -255,7 +263,9 @@ export default function App() {
         agentType: resp.agentType,
         name: selectedAgentType === "claude"
           ? (blueprintName || "Claude Agent")
-          : (agentBinary || "ACP Agent"),
+          : selectedAgentType === "codex"
+            ? (blueprintName || "Codex Agent")
+            : (agentBinary || "ACP Agent"),
         axonId: resp.axonId as string,
         devboxId: resp.devboxId as string,
         createdAt: Date.now(),
@@ -415,7 +425,11 @@ export default function App() {
 
   const showChatView = selectedAgentId && !showSetup && selectedEntry;
 
-  const agentLabel = agent.agentType === "claude" ? "Claude Code" : "ACP Agent";
+  const agentLabel = agent.agentType === "claude"
+    ? "Claude Code"
+    : agent.agentType === "codex"
+      ? "Codex"
+      : "ACP Agent";
 
   // Derive devbox status from the last devbox_lifecycle system event in messages
   const lastDevboxEvent = [...agent.messages].reverse().find(
@@ -495,6 +509,12 @@ export default function App() {
                 </div>
               )}
 
+              {agent.agentType === "codex" && agent.threadId && (
+                <div className="controls-bar">
+                  <span className="config-label">Thread: {agent.threadId}</span>
+                </div>
+              )}
+
               <div className="chat-area" ref={chatAreaRef}>
                 {agent.messages.length === 0 && agent.currentTurnBlocks.length === 0 && !agent.isAgentTurn && agent.connectionPhase === "ready" && (
                   <div className="empty-state">Send a message to start chatting</div>
@@ -542,6 +562,13 @@ export default function App() {
                   />
                 )}
 
+                {agent.agentType === "codex" && agent.pendingApproval && (
+                  <ApprovalPrompt
+                    approval={agent.pendingApproval}
+                    onRespond={agent.respondToApproval}
+                  />
+                )}
+
                 {agent.agentType === "acp" && agent.pendingPermission && (
                   <PermissionDialog
                     permission={agent.pendingPermission}

examples/combined-app/src/client/components/AgentSidebar.tsx

@@ -42,7 +42,7 @@ export function AgentSidebar({
           >
             <div className="agent-sidebar-item-top">
               <span className="agent-sidebar-type-badge">
-                {agent.agentType === "claude" ? "C" : "A"}
+                {agent.agentType === "claude" ? "C" : agent.agentType === "codex" ? "X" : "A"}
               </span>
               <span className="agent-sidebar-item-name">{agent.name}</span>
               <button

examples/combined-app/src/client/components/ApprovalPrompt.tsx

@@ -0,0 +1,34 @@
+import type { PendingApproval } from "../types.js";
+
+export function ApprovalPrompt({
+  approval,
+  onRespond,
+}: {
+  approval: PendingApproval;
+  onRespond: (requestId: string, approve: boolean) => void;
+}) {
+  return (
+    <div className="elicitation-form">
+      <div className="elicitation-message">
+        Approval requested: <strong>{approval.summary}</strong>
+      </div>
+      <pre className="permission-raw-input">
+        {JSON.stringify(approval.rawRequest.params, null, 2)}
+      </pre>
+      <div className="permission-actions">
+        <button
+          className="btn permission-btn permission-btn-allow"
+          onClick={() => onRespond(approval.requestId, true)}
+        >
+          Approve
+        </button>
+        <button
+          className="btn permission-btn permission-btn-reject"
+          onClick={() => onRespond(approval.requestId, false)}
+        >
+          Decline
+        </button>
+      </div>
+    </div>
+  );
+}

examples/combined-app/src/client/components/SetupCard.tsx

@@ -37,7 +37,7 @@ export function SetupCard({
       <div className="setup-header">
         <h2>Combined App</h2>
         <p className="setup-subtitle">
-          Launch a <strong>Claude Code</strong> or <strong>ACP</strong> agent in a secure cloud sandbox and interact through a unified interface.
+          Launch a <strong>Claude Code</strong>, <strong>Codex</strong>, or <strong>ACP</strong> agent in a secure cloud sandbox and interact through a unified interface.
         </p>
       </div>
 
@@ -79,6 +79,13 @@ export function SetupCard({
             >
               Claude Code
             </button>
+            <button
+              className={`agent-type-btn ${agentType === "codex" ? "active" : ""}`}
+              onClick={() => setAgentType("codex")}
+              disabled={connecting}
+            >
+              Codex
+            </button>
             <button
               className={`agent-type-btn ${agentType === "acp" ? "active" : ""}`}
               onClick={() => setAgentType("acp")}
@@ -104,7 +111,7 @@ export function SetupCard({
           </>
         )}
 
-        {agentType === "claude" && (
+        {(agentType === "claude" || agentType === "codex") && (
           <>
             <div className="form-group">
               <label>Blueprint Name</label>
@@ -113,8 +120,15 @@ export function SetupCard({
             </div>
             <div className="form-group">
               <label>Model</label>
-              <div className="form-hint">Claude model to use. Leave empty for default.</div>
-              <input value={model} onChange={(e) => setModel(e.target.value)} placeholder="claude-sonnet-4-20250514" disabled={connecting} />
+              <div className="form-hint">
+                {agentType === "claude" ? "Claude model to use. Leave empty for default." : "Codex model to use. Leave empty for default."}
+              </div>
+              <input
+                value={model}
+                onChange={(e) => setModel(e.target.value)}
+                placeholder={agentType === "claude" ? "claude-sonnet-4-20250514" : "gpt-5.1-codex"}
+                disabled={connecting}
+              />
             </div>
           </>
         )}
@@ -142,7 +156,11 @@ export function SetupCard({
             disabled={connecting}
           />
           <span className="config-toggle-label">
-            {agentType === "claude" ? "Skip permissions (--dangerously-skip-permissions)" : "Auto-approve permissions"}
+            {agentType === "claude"
+              ? "Skip permissions (--dangerously-skip-permissions)"
+              : agentType === "codex"
+                ? "Auto-approve approvals"
+                : "Auto-approve permissions"}
           </span>
         </label>
       </div>