Swap Codex in as the AGNT fleet adapter (30-minute walkthrough)

The naive way to change a model backend is: stop the agent, update its config, start it again. That works for a single agent in isolation but breaks in a fleet because you lose cwd state, you break in-flight tool calls, and the leader-election cron gets confused if the agent happens to be the supervisor leader at the moment you restart it.

AGNT's adapter interface is narrow by design: four methods (`complete`, `stream`, `supports_tools`, `health_check`). The runtime swaps the adapter pointer under the agent without the agent ever knowing. The next tool call lands on the new model. No restart, no cwd loss, no cron confusion.

Pick the agent you want to swap. Get its current state:

curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  http://localhost:3100/api/agents/$AGENT_ID

Verify two fields: `adapter` (should be `claude_local`) and `cwd` (the agent's current working directory). Write down the cwd — you'll check it survived the swap later.

Before patching the agent, make sure Codex actually works in the fleet's environment. From the same host the fleet runs on:

codex --version
codex --help | head

If Codex needs an API key, verify `$OPENAI_API_KEY` is set in the fleet's env. A failed health check during the swap will auto-rollback, but it's faster to catch a missing env var before you start.

Swap the adapter:

curl -X PATCH \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adapter": "codex_local", "preserve_cwd": true}' \
  http://localhost:3100/api/agents/$AGENT_ID

`preserve_cwd: true` is the critical flag. Without it, the runtime resets the agent's cwd to its default (usually the fleet root), which will confuse any in-progress work. With it, the runtime passes the captured cwd into the new adapter's process env.

Poll the health endpoint for 30 seconds:

for i in {1..15}; do
  curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
    http://localhost:3100/api/agents/$AGENT_ID/health
  sleep 2
done

Look for `{"status": "healthy", "adapter": "codex_local", "last_message_age_s": <10}`. The `last_message_age_s` field is the tell: if it's rising, the new adapter isn't processing anything and you should rollback.

If the health check fails, immediately rollback:

curl -X PATCH \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adapter": "claude_local", "preserve_cwd": true}' \
  http://localhost:3100/api/agents/$AGENT_ID

This is the same call with the source adapter. Because `preserve_cwd: true` is set, the cwd survives the rollback too. You're back where you started.

Before you trust the swap, give the agent a low-stakes task and verify it completes end-to-end. Check the heartbeat log for any adapter-specific error patterns — Codex's tool-call shape is slightly different from Claude's, and the adapter layer normalizes them, but edge cases occasionally leak through.

Common issues and their signatures: missing `tool_use_id` in Codex responses (the adapter adds a synthetic ID — look for `synthetic:` prefix), different max_tokens defaults (Codex caps are usually lower), and different function-call JSON shapes (normalization happens in `fleet/adapters/codex_local.py`).

Once the swap lands, the agent runs on Codex with no code changes anywhere else in the fleet. Its tools still work. Its soul loader still works. Its spend is wrapped by the same $500/day global cap. The only difference is which model backend answers its next prompt.

This is the property that makes the fleet layer worth the complexity: backend choice is a runtime decision, not a build-time decision. You can A/B test adapters, move between them based on cost, or run different adapters for different tiers — all without touching agent code.