feat(agent): use stable /api/v2 chat routes with experimental fallback

[ThomasK33]

Summary

• Prefer /api/v2/chats for promoted REST routes and both chat WebSockets; retain the deprecated /api/experimental/chats/model-configs lookup independently.
• Negotiate the prefix per CoderChatClient, tolerating older deployments without buildinfo/semver gating.
• Replace all retired dev.coder.com references with dogfood.cdr.dev, document compatibility, and fix a checkpoint example mismatch exposed by typechecking all README snippets.

Upstream context

• coder/coder#28496 mounted the promoted chat API under /api/v2 (merged August 26, 2026), shipped in v2.37.0 on September 1.
• coder/coder#28497 switched codersdk to the stable prefix; #28760 removed the API reference's early-access label.
• Both prefixes serve the same promoted routes during CODAGT-921; the experimental mount is slated for removal under CODAGT-922. Older supported branches (including v2.36.4) have no stable chat mount, so an unconditional switch would break them.

Prefix negotiation

An unresolved client's actual REST call tries v2 first. Only a CoderApiError 404 retries the same call once on experimental. The first non-404 HTTP response, including an error, locks its prefix. Two 404s rethrow the original v2 error and leave the client unresolved; network/abort failures do not establish support. Once locked, even resource 404s do not renegotiate. Concurrent initial calls can probe independently, but cannot overwrite an established lock.

WebSockets resolve an unknown prefix with a read-only GET /chats before dialing. Resolution runs inside the existing reader cancellation wrappers, so return(), throw(), disposal and abort can cancel the preflight. This avoids depending on factory-specific upgrade-error messages. Non-replayable ReadableStream uploads use the same preflight before consuming the body; JSON/Blob requests use actual-call fallback. This small exception avoids unsafe upload replay without adding a general retry/buffering mechanism.

http:* paths remain the actual wire paths; no new event kinds were added. WebSocket preflights use op: "streamEvents" / "watchChats". The standalone watch helper defaults to v2; per-client negotiation is provided by CoderChatClient. Org-scoped model listing and its deprecated experimental fallback neither consult nor establish the chat-prefix lock.

Verification tiers and dogfooding

• Stable v2 routes: verified live on https://dogfood.cdr.dev, reporting v2.37.0-devel+acae170664. Ambient Coder credentials were checked with coder whoami; no tokens were created, revoked, printed, or unset. A transport-logging harness exercised REST create/archive, a successful per-chat stream upgrade, and a fresh client's listing preflight plus global watch upgrade. Screenshot, recording, and transcript are attached in a PR comment.
• Older-server fallback: verified against source plus unit tests. The supplied upstream verification of v2.36.4 coderd/coderd.go confirms no /api/v2/chats mount. Tests cover fallback success and non-404 failures, persistent locking, both-404 error fidelity, concurrent initialization, independent model lookup, body/signal preservation, streaming upload safety, and both WebSockets. No pre-2.37 deployment was available for a live fallback run.
• Docs/API behavior: source-verified against the implementation and the upstream references above; the minimum stable-prefix version is 2.37.0, not a prerequisite for using the fallback.

Gates

• pnpm format and pnpm check — pass.
• pnpm -r build, pnpm -r test — pass: 622 tests (all 597 existing + 25 new). Agent 351, provider 22, sandbox 191, effect 45, release tooling 13.
• pnpm publint, pnpm attw — pass.
• 28/28 README TypeScript fences assembled under examples/ into 26 typed scratch modules, pnpm --filter @coder/ai-sdk-agent typecheck passed, scratch removed.
• Live e2e: 7/7 on the submitted head; exact UTC timestamp and head are in the evidence comment.

Both Codex review loops and the Required CI gate must be clean on the current head before entering the squash merge queue.

---

Generated with mux • Model: coder:openai/gpt-6-astra • Thinking: high

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[ThomasK33]

Live verification evidence

Head: 05aeaf0b6a84709b5ca2bc277b61421622708d72. Live e2e: 7/7 passed, started 2026-09-06 20:06:48 UTC (26.30 seconds), on dogfood.cdr.dev (v2.37.0-devel+acae170664). All 622 unit tests and the five required local gates passed.

The attached terminal screenshot and accelerated recording show actual SDK REST and stream transport events plus the successful global-watch factory upgrade. The proof ran at 20:04:59–20:05:02 UTC, on the same production source as this head (only documentation changed afterward). All created chats were archived; the watch was closed. No pre-2.37 deployment was available for a live fallback run; fallback is source- and unit-test-verified.

Transport transcript

LIVE ROUTE PROOF | 2026-09-06T20:04:59.454Z | https://dogfood.cdr.dev | v2.37.0-devel+acae170664
http:request GET /api/v2/organizations/703f72a1-76f6-4f89-9de6-8a3989693fe5/chats/models
http:response GET /api/v2/organizations/703f72a1-76f6-4f89-9de6-8a3989693fe5/chats/models -> 200
http:request POST /api/v2/chats
http:response POST /api/v2/chats -> 201
ws:dial wss://dogfood.cdr.dev/api/v2/chats/482ebaed-60da-45f6-bd25-917b6e203012/stream
ws:open (stream upgrade accepted)
ASSERT generation: stop; reply contains pong; stable HTTP + stream confirmed
http:request PATCH /api/v2/chats/482ebaed-60da-45f6-bd25-917b6e203012
http:response PATCH /api/v2/chats/482ebaed-60da-45f6-bd25-917b6e203012 -> 204
http:request GET /api/v2/chats op=watchChats
http:response GET /api/v2/chats op=watchChats -> 200
watch factory dial wss://dogfood.cdr.dev/api/v2/chats/watch
ASSERT stable watch upgrade accepted; preflight cancellation/cleanup complete
LIVE_V2_PROOF_PASS 2026-09-06T20:05:02.506Z

---

Generated with mux • Model: coder:openai/gpt-6-astra • Thinking: high

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T20:11:55.048431Z	05aeaf0	Manual request
🔒 Security Review	✅ Completed 2026-09-06T20:13:05.545302Z	05aeaf0	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 05aeaf0b6a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: 05aeaf0b6a

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.