Handle AI usage cap gracefully in studio code

[gcsecsey]

Related issues

Related to STU-1555
Companion PR 211652-ghe-Automattic/wpcom

How AI was used in this PR

I used Claude to implement the changes and write tests. I reviewed and tested all changes manually.

Proposed Changes

When a user hit the AI usage cap while running studio code, the agent would appear to hang for minutes before eventually showing a generic error. The cause is two non-obvious behaviors of @anthropic-ai/claude-agent-sdk:

1. The SDK retries non-2xx responses up to 10 times by default (via CLAUDE_CODE_MAX_RETRIES). Cap responses won't recover from a retry, so the user just waits through exponential backoff before seeing anything.
2. The SDK only classifies HTTP errors when ANTHROPIC_BASE_URL points at api.anthropic.com. We point it at the WordPress.com proxy (https://public-api.wordpress.com/wpcom/v2/ai-api-proxy), so the SDK falls through to error: 'unknown' regardless of what shape the upstream 429 body has. The response body is forwarded into the assistant message as a text block, but SDKAssistantMessage.error never says 'rate_limit'.

This PR surfaces the cap and offers a path forward (/provider to switch to a personal Anthropic API key):

• Fail fast on 4xx: apps/cli/ai/providers.ts sets CLAUDE_CODE_MAX_RETRIES=0 for the wpcom provider so the SDK stops retrying and returns control immediately.
• Detect the cap from the SDK message: apps/cli/ai/ui.ts matches a studio_cap_exceeded marker (set by the backend in the 4xx response body) inside assistant content text blocks. Since the SDK forwards the upstream body, this is the only reliable signal we get through a proxy. Picking a marker we control instead of pattern-matching the upstream JSON shape keeps the contract explicit and survives any SDK debug-output changes.
• Suppress redundant errors: after surfacing the cap message, the SDK still emits a trailing "Claude Code process exited with code 1" from the agent runner. handleAgentTurnError checks ui.hasErrorBeenSurfaced() and bails out so the user only sees one clear message. The "Done" / "Thought for Xs" indicators are also suppressed when the turn ended in a cap.

I also experimented with a pre-flight quota check. It would only benefit the already-capped case, while mid-turn caps, the realistic failure mode for long agent loops where token budgets get debited as the turn runs, are handled entirely by the in-turn marker detection. Adding a per-turn round trip for a marginal UX gain wasn't worth it.

The companion PR 211652-ghe-Automattic/wpcom makes the marker show up in the response body.

Testing Instructions

• Follow the test instructions on 211652-ghe-Automattic/wpcom
• Checkout this branch
• Use curl 'https://public-api.wordpress.com/?amisandboxed' to confirm sandboxing is active
• Build the CLI with npm run cli:build
• Run the CLI agent: node apps/cli/dist/cli/main.mjs code (and log in if needed)
• With the cap not yet exceeded: send any prompt and confirm the agent responds normally
• Lower the cap on the backend, then send a prompt
• Check that the agent does not hang, the cap message appears within a second or two
• Check that you get the error message
• Check that there is no trailing "Done" indicator and no "Claude Code process exited with code 1" line
• Run /provider, switch to "Anthropic · API key", paste a key, and confirm subsequent prompts work
• Switch back to "WordPress.com" and confirm the cap message appears immediately on the next prompt

Cap reached	After switching to API key	After switching back to WP.com

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing f3acf5f vs trunk

app-size

Metric	trunk	f3acf5f	Diff	Change
App Size (Mac)	1490.96 MB	1490.96 MB	+0.00 MB	⚪ 0.0%

site-editor

Metric	trunk	f3acf5f	Diff	Change
load	1905 ms	1861 ms	44 ms	⚪ 0.0%

site-startup

Metric	trunk	f3acf5f	Diff	Change
siteCreation	8125 ms	8100 ms	25 ms	⚪ 0.0%
siteStartup	4947 ms	4947 ms	0 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[nightnei]

1. I tried a few times and always was waiting for aroudn 200s.
2. Also I got Claude Code process exited with code 1
   According to testing steps, it's not expected?

[gcsecsey]

1. I tried a few times and always was waiting for aroudn 200s.

   2. Also I got Claude Code process exited with code 1
      According to testing steps, it's not expected?

Thanks for testing @nightnei! Yes, neither the long wait nor the error message are expected. From the error message, it seems that you have the quota set on the backend correctly, so this might be something on the CLI side. 🤔

Strange, because in my testing, I got ~10s turnaround time from my sandbox, although I can reproduce the second error message being shown:

CleanShot.2026-04-21.at.10.53.12.mp4

I'll investigate further and fix this.

[gcsecsey]

@nightnei the error message detection drifted slightly between the backend and the cli changes, so you were essentially seeing the trunk behavior. I fixed it now, and now I get the error message as expected when following the testing steps in the PR description:

CleanShot.2026-04-21.at.11.39.51.mp4

Could you please give this another look? Thanks!

[nightnei]

Tested, it works well now and LGTM 👍