@karpeleslab/teamclaude 1.0.7 → 1.0.8

package/README.md

@@ -15,13 +15,17 @@ Sits transparently between Claude Code and the Anthropic API, managing multiple
 
 - **Automatic account rotation** — switches to the next account when session (5h) or weekly (7d) quota reaches the configured threshold (default 98%)
 - **Auto-retry on 429** — waits the `retry-after` duration and retries the same account; switches to the next on persistent errors
-- **Interactive TUI** — real-time dashboard with color-coded quota bars, reset countdowns, activity log, and keyboard controls
+- **Interactive TUI** — real-time dashboard with color-coded quota bars, reset countdowns, activity log, and keyboard controls; a settings screen (`g`) edits the rotation threshold, quota-probe interval, and sx.org proxy live
 - **OAuth token management** — automatically refreshes tokens nearing expiry and persists them to config; client token refreshes pass through untouched
-- **Hot-reload accounts** — add accounts via `import` or `login` while the server is running, press **R** to pick them up
+- **Hot-reload accounts** — add or change accounts while the server is running; press **R** in the TUI, or run headless and CLI changes auto-reload via a local control endpoint
+- **Headless mode** — run the proxy without the TUI (`--headless`) for backgrounding/services
 - **Org-aware accounts** — one email can hold multiple accounts across different organizations (e.g. corp + personal); dedup is keyed on account + org, and names disambiguate as `email (Org)`
 - **Rotation priority** — pin a preferred account order with `teamclaude priority`
 - **Enable/disable accounts** — temporarily pause an account without removing it (`teamclaude disable`/`enable`, or `d` in the TUI); re-enabling also clears a stuck error state
 - **Quota persistence** — observed quota survives restarts (saved to a sibling state file), so rotation state isn't lost on restart; stale windows are discarded automatically
+- **Optional quota probe** — off by default; when enabled, periodically refreshes idle accounts' quota from the usage endpoint (no message spend), and surfaces the Sonnet weekly bucket
+- **Optional MITM proxy mode** — `teamclaude run --mitm` routes claude via an HTTPS forward proxy with a local CA so even hardcoded `api.anthropic.com` endpoints (e.g. the Claude Design MCP) get the real token injected
+- **Optional sx.org proxy mode** — off by default; set an [sx.org](https://sx.org) API key in the TUI settings screen (`g`) and TeamClaude auto-provisions a residential proxy to change the egress IP and work around IP-based `429`s. Three modes (`m` to cycle): **always** (route all upstream traffic), **on 429 only** (stay direct, fail over to the proxy after a 429), or **off** (keep the key but don't use it). TLS stays end-to-end with Anthropic (the proxy only relays ciphertext)
 - **Request logging** — optional full request/response logging for debugging
 - **Zero dependencies** — uses only Node.js built-in modules
 
@@ -103,7 +107,15 @@ When running from a TTY, shows an interactive TUI with:
 - Real-time activity log with request tracking
 - Keyboard shortcuts (see below)
 
-Falls back to plain log output when not a TTY (e.g. running as a service).
+Falls back to plain log output when not a TTY (e.g. running as a service). Pass `--headless` (or `--no-tui`) to force the plain-log mode even from a terminal — useful for backgrounding the proxy.
+
+When running headless, you can re-sync accounts from the config without a restart by POSTing to the local control endpoint (the equivalent of pressing **R** in the TUI):
+
+```bash
+curl -X POST http://localhost:3456/teamclaude/reload
+```
+
+You usually don't need to call it directly: `teamclaude login`, `import`, `enable`, `disable`, and `priority` automatically notify a running server to reload. (New accounts and credential/priority/enable-disable changes are picked up live; account *removals* still require a restart.)
 
 #### TUI Keyboard Shortcuts
 
@@ -154,6 +166,7 @@ teamclaude remove <name>     # Remove an account (by name or email)
 teamclaude disable <name>    # Temporarily exclude an account from rotation
 teamclaude enable <name>     # Re-enable it (also clears a stuck error state)
 teamclaude priority <name> 1 # Set rotation priority (lower = preferred)
+teamclaude probe 300         # Enable background quota refresh (off by default)
 teamclaude alias             # Print/install a `claude` alias that routes via the proxy
 teamclaude api <path>        # Call an API endpoint with account credentials
 teamclaude help              # Show all commands
@@ -195,6 +208,7 @@ TEAMCLAUDE_CONFIG=./my-config.json teamclaude server
   },
   "upstream": "https://api.anthropic.com",
   "switchThreshold": 0.98,
+  "sx": { "apiKey": "your-sx-org-api-key", "mode": "always" },
   "accounts": [
     {
       "name": "user@example.com (Acme)",
@@ -216,12 +230,79 @@ TEAMCLAUDE_CONFIG=./my-config.json teamclaude server
 | `proxy.port` | Local port the proxy listens on |
 | `proxy.apiKey` | API key clients use to authenticate with the proxy |
 | `upstream` | Upstream API base URL |
-| `switchThreshold` | Quota utilization (0–1) at which to switch accounts |
+| `switchThreshold` | Quota utilization (0–1) at which to switch accounts (TUI: `g` → `t`) |
+| `quotaProbeSeconds` | Background quota-probe interval in seconds (`0` = off, the default; CLI `probe` or TUI `g` → `p`) |
+| `sx.apiKey` | [sx.org](https://sx.org) API key. When set, TeamClaude auto-provisions a residential proxy (egress-IP 429 workaround). Absent/empty = off |
+| `sx.mode` | `always` (route all upstream traffic), `429` (direct, fail over to the proxy after a 429), or `off` (keep the key but don't use it). Defaults to `always` when a key is set |
 | `accounts[].accountUuid` | Anthropic account (person) id; set automatically from the OAuth profile |
 | `accounts[].orgUuid` / `orgName` | Organization the account is scoped to — lets one email hold multiple org accounts |
 | `accounts[].priority` | Rotation preference, lower = preferred (default 0) |
 | `accounts[].disabled` | If `true`, the account is excluded from rotation until re-enabled |
 
+### Quota probe (optional, off by default)
+
+By default TeamClaude is **passive** — it learns each account's quota only from the responses that flow through it, so an account that hasn't been used yet shows unknown quota until it's first rotated to.
+
+If you'd rather keep idle accounts' quota fresh, enable the background probe:
+
+```bash
+teamclaude probe 300    # refresh every 300s
+teamclaude probe off    # back to passive (default)
+teamclaude probe        # show current setting
+```
+
+You can also set the interval live from the TUI settings screen (`g` → `p`), alongside the rotation threshold (`t`).
+
+It reads each OAuth account's utilization from Anthropic's usage endpoint (`/api/oauth/usage`), which reports quota **without consuming any message quota**. Minimum interval is 30s. Changing it takes effect on a running server immediately (no restart). When enabled, it also surfaces the **Sonnet 7-day** bucket as an extra bar in the TUI / `status` (when your plan exposes it).
+
+### MITM proxy mode (optional, off by default)
+
+The normal reverse-proxy only intercepts what `ANTHROPIC_BASE_URL` covers. Some Claude Code features (e.g. the **Claude Design MCP**) use a **hardcoded** `https://api.anthropic.com` URL that ignores that variable, so they bypass the proxy. MITM proxy mode captures those too.
+
+Run claude with the `--mitm` flag:
+
+```bash
+teamclaude run --mitm -- <claude args...>
+```
+
+That launches claude pointed at teamclaude as an **HTTPS forward proxy** (`HTTPS_PROXY`) and trusts a locally-generated CA (`NODE_EXTRA_CA_CERTS`). For an intercepted host, teamclaude **dials the real upstream first, mirrors its negotiated ALPN** (HTTP/2 or HTTP/1.1), then terminates TLS toward claude with the same protocol and relays the traffic **as transparently as possible** — rewriting only what it must:
+
+- the **`authorization`** header → the active account's real token (dropping any client `x-api-key`);
+- the **`account_uuid`** inside `metadata.user_id` → the active account's UUID (so the body agrees with the injected token);
+- and it reads `anthropic-ratelimit-*` from responses for quota.
+
+Everything else is copied byte-for-byte (HTTP/2 is handled with a built-in HPACK codec so the only header changed is the auth one). Any host other than the upstream is blind-tunnelled. The server accepts *both* base-URL and proxy clients at once, so instances launched with and without `--mitm` can share one server.
+
+Trust model:
+- The CA is generated locally, stored in the config dir, and trusted **only** by the claude process you launch via `teamclaude run` (through `NODE_EXTRA_CA_CERTS`) — it is **never** added to your system trust store. The leaf private key is `0600`; the CA private key is never written to disk.
+- teamclaude still verifies the **real** Anthropic certificate on the upstream leg.
+
+Verify the proxy + CA without any credentials — the proxy always answers a built-in test host:
+
+```bash
+# (with the server running and certs generated, e.g. after one `teamclaude run`)
+curl --proxy http://localhost:3456 --cacert ~/.config/teamclaude-ca.pem https://www.example.org/
+# → {"teamclaude":"mitm-proxy-ok","host":"www.example.org",...}
+```
+
+### sx.org proxy mode (optional, off by default)
+
+Some transient `429`s key on the proxy's **outbound IP**, not the account — so rotating accounts doesn't help. To work around them, TeamClaude can route upstream requests through a residential proxy from [sx.org](https://sx.org), giving a different egress IP.
+
+Open the TUI and press **`g`** for the settings screen, then **`k`** to paste your sx.org API key (stored in `config.sx.apiKey`). TeamClaude reuses an existing active proxy port on your sx.org account, or auto-creates a residential US one, and dials the upstream through it via HTTP `CONNECT` on **both** the reverse-proxy and `--mitm` paths.
+
+Press **`m`** to cycle the **mode**:
+
+| Mode | Behavior |
+|------|----------|
+| **always** | Tunnel **every** upstream request through sx.org. |
+| **on 429 only** | Connect directly; on a `429` (which is IP-based), immediately retry that request through sx.org's fresh egress IP — no wait. On the `--mitm` path, a recent `429` routes new tunnels through sx.org for a short window. |
+| **off** | Never use sx.org, but **keep the API key** so you can re-enable it instantly. |
+
+TLS is established **end-to-end with `api.anthropic.com` over the tunnel**, so the sx.org proxy only ever relays ciphertext and the real Anthropic certificate is still verified. Mode and key changes apply live (no restart). Press **`x`** to forget the key entirely.
+
+> **Cost:** in **always** mode *all* Claude traffic flows through the residential proxy, which sx.org meters by bandwidth — expect real per-GB cost. **on 429 only** uses the proxy just when you're actually being throttled, so it's the cheaper way to ride out rate limits.
+
 ## How It Works
 
 1. Claude Code connects to the local proxy instead of `api.anthropic.com`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karpeleslab/teamclaude",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Multi-account Claude proxy with automatic quota-based rotation",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -5,7 +5,8 @@ import { sameIdentity } from './identity.js';
 // windows, learned passively from upstream responses. Transient/derived state
 // (probing, requalify, rateLimitedUntil) is intentionally excluded.
 const PERSISTED_QUOTA_FIELDS = [
-  'unified5h', 'unified7d', 'unified5hReset', 'unified7dReset', 'unifiedStatus',
+  'unified5h', 'unified7d', 'unified7dSonnet',
+  'unified5hReset', 'unified7dReset', 'unified7dSonnetReset', 'unifiedStatus',
   'tokensLimit', 'tokensRemaining', 'requestsLimit', 'requestsRemaining', 'resetsAt',
 ];
 
@@ -17,17 +18,22 @@ function emptyQuota() {
     requestsLimit: null,
     requestsRemaining: null,
     // Unified rate limits (Claude Max accounts)
-    unified5h: null,       // utilization 0-1
-    unified7d: null,       // utilization 0-1
-    unified5hReset: null,  // ms timestamp
-    unified7dReset: null,  // ms timestamp
-    unifiedStatus: null,   // allowed | allowed_warning | rejected
+    unified5h: null,            // utilization 0-1
+    unified7d: null,            // utilization 0-1
+    unified7dSonnet: null,      // utilization 0-1 (Sonnet-specific weekly bucket)
+    unified5hReset: null,       // ms timestamp
+    unified7dReset: null,       // ms timestamp
+    unified7dSonnetReset: null, // ms timestamp
+    unifiedStatus: null,        // allowed | allowed_warning | rejected
     resetsAt: null,
   };
 }
 
 export class AccountManager {
-  constructor(accounts, switchThreshold = 0.98) {
+  constructor(accounts, switchThreshold = 0.98, { refreshFn = refreshAccessToken } = {}) {
+    // Injectable for tests (mirrors Prober's probeFn); defaults to the real
+    // OAuth token refresh.
+    this._refreshFn = refreshFn;
     this.accounts = accounts.map((acct, index) => ({
       index,
       name: acct.name,
@@ -55,35 +61,114 @@ export class AccountManager {
     }));
     this.currentIndex = 0;
     this.switchThreshold = switchThreshold;
+    // When every account reads as over-quota we would otherwise refuse locally
+    // forever (a stale cached utilization is never re-validated because no
+    // request is ever sent). Instead, allow one real upstream probe at most this
+    // often to refresh the cached quota. See _selectProbe.
+    this.probeIntervalMs = 60_000;
+    this._nextProbeAt = 0;
   }
 
   /**
    * Get the best available account, rotating if the current one is near quota.
    * Returns null if all accounts are exhausted.
    */
-  getActiveAccount() {
+  getActiveAccount(exclude = null) {
     // Clear expired quotas across all accounts and switch proactively if a
     // session reset made a sooner-expiring account the better choice. This runs
     // on every request so the behaviour holds without the TUI render loop.
     this.refreshExpiredQuotas();
     const current = this.accounts[this.currentIndex];
+    // `exclude` is a per-request set of indices already tried this request (e.g.
+    // an account that just threw a transport error). It is never a persistent
+    // status change — the account stays healthy for the next request.
     // We just learned a probed account's weekly quota — re-evaluate which
     // account is best now that its limit is known.
     if (current && current.requalify) {
       current.requalify = false;
-      const next = this._selectNext();
+      const next = this._selectNext(exclude);
       if (next) return next;
     }
-    if (this._isAvailable(current)) {
+    if (this._isAvailable(current) && !exclude?.has(current.index)) {
       // A strictly higher-priority (lower value) available account preempts a
       // healthy current one. Within the same priority tier we stay put, so the
       // common case (all accounts at the default priority 0) is unchanged and
       // never thrashes — preemption only triggers when priorities differ.
       const betterExists = this.accounts.some(a =>
-        this._isAvailable(a) && (a.priority || 0) < (current.priority || 0));
-      return betterExists ? this._selectNext() : current;
+        this._isAvailable(a) && !exclude?.has(a.index) && (a.priority || 0) < (current.priority || 0));
+      return betterExists ? this._selectNext(exclude) : current;
     }
-    return this._selectNext();
+    const next = this._selectNext(exclude);
+    if (next) return next;
+    // No account is under the switch threshold. Before refusing locally, allow a
+    // throttled probe so a stale/poisoned cached quota can't pin us in a
+    // permanent "all exhausted" state — the probe's real response refreshes the
+    // quota (or upstream's own 429 converts soft exhaustion into a hard
+    // rate-limit hold). null here means the caller emits the synthetic 429.
+    return this._selectProbe(exclude);
+  }
+
+  _isProbeable(account) {
+    if (!account) return false;
+    // Never probe an account the operator has taken out of rotation, one whose
+    // token is broken, or one upstream has explicitly rate-limited — those are
+    // hard states, not stale soft-quota guesses.
+    if (account.disabled) return false;
+    if (account.status === 'error' || account.status === 'exhausted') return false;
+    if (account.status === 'throttled' && account.rateLimitedUntil
+        && Date.now() < account.rateLimitedUntil) return false;
+    return true;
+  }
+
+  /** Highest utilization across all known quota dimensions (0-1), used to pick
+   * the least-exhausted probe target. Mirrors the ratios in _isNearQuota. */
+  _maxUtilization(account) {
+    const q = account.quota;
+    let max = 0;
+    if (q.unified5h != null) max = Math.max(max, q.unified5h);
+    if (q.unified7d != null) max = Math.max(max, q.unified7d);
+    if (q.tokensLimit != null && q.tokensRemaining != null) {
+      max = Math.max(max, 1 - q.tokensRemaining / q.tokensLimit);
+    }
+    if (q.requestsLimit != null && q.requestsRemaining != null) {
+      max = Math.max(max, 1 - q.requestsRemaining / q.requestsLimit);
+    }
+    return max;
+  }
+
+  /**
+   * Pick an account to send a single revalidation probe upstream when every
+   * account reads as over the switch threshold. Throttled to one probe per
+   * probeIntervalMs so a genuinely-exhausted fleet isn't hammered — between
+   * probes this returns null and the caller falls back to the synthetic 429.
+   * The chosen account is the least-utilized probeable one (most likely to have
+   * stale headroom), so the refreshed quota corrects the cache fastest.
+   */
+  _selectProbe(exclude = null) {
+    const now = Date.now();
+    if (now < this._nextProbeAt) return null;
+
+    let best = null;
+    let bestPriority = Infinity;
+    let bestUsage = Infinity;
+    for (const account of this.accounts) {
+      if (exclude?.has(account.index)) continue;
+      if (!this._isProbeable(account)) continue;
+      const priority = account.priority || 0;
+      const usage = this._maxUtilization(account);
+      if (priority < bestPriority ||
+          (priority === bestPriority && usage < bestUsage)) {
+        bestPriority = priority;
+        bestUsage = usage;
+        best = account;
+      }
+    }
+    if (!best) return null;
+
+    this._nextProbeAt = now + this.probeIntervalMs;
+    this.currentIndex = best.index;
+    console.log(`[TeamClaude] All accounts over threshold — probing "${best.name}" to refresh quota`);
+    return best;
   }
 
   _isAvailable(account) {
@@ -134,6 +219,11 @@ export class AccountManager {
       q.unifiedStatus = null;
       changed = true;
     }
+    if (q.unified7dSonnet != null && q.unified7dSonnetReset && now >= q.unified7dSonnetReset) {
+      q.unified7dSonnet = null;
+      q.unified7dSonnetReset = null;
+      changed = true;
+    }
 
     // Clear expired standard quotas
     if (q.resetsAt && now >= new Date(q.resetsAt).getTime()) {
@@ -224,22 +314,25 @@ export class AccountManager {
     return false;
   }
 
-  _selectNext() {
-    // Selection order among available accounts:
-    //   1. lowest `priority` value (operator-controlled; default 0, lower = preferred)
-    //   2. then the account with no known weekly limit — using it lets us
-    //      discover its quota
-    //   3. then the account whose weekly limit expires soonest: that quota is
-    //      closest to refreshing, so spending it first preserves accounts whose
-    //      weekly window resets further out.
-    // With all priorities at the default 0, this reduces to the original
-    // weekly-reset heuristic.
+  /**
+   * Pick the best available account by selection order, WITHOUT mutating state:
+   *   1. lowest `priority` value (operator-controlled; default 0, lower = preferred)
+   *   2. then the account with no known weekly limit — using it lets us
+   *      discover its quota
+   *   3. then the account whose weekly limit expires soonest: that quota is
+   *      closest to refreshing, so spending it first preserves accounts whose
+   *      weekly window resets further out.
+   * With all priorities at the default 0, this reduces to the weekly-reset
+   * heuristic. Returns the account or null if none are available.
+   */
+  _pickBestAvailable(exclude = null) {
     let best = null;
     let bestPriority = Infinity;
     let bestReset = Infinity;
 
     for (let i = 0; i < this.accounts.length; i++) {
       const account = this.accounts[i];
+      if (exclude?.has(account.index)) continue;
       // _isAvailable filters out accounts at/above the switch threshold, so the
       // soonest-expiring pick only ever lands on an account whose 5-hour quota
       // is still below 98%.
@@ -255,7 +348,31 @@ export class AccountManager {
         best = account;
       }
     }
+    return best;
+  }
 
+  /**
+   * Select the active account up front (e.g. on daemon launch, once persisted
+   * quota has been restored) so we start on the highest-priority / soonest-
+   * resetting account instead of blindly on index 0. Mirrors rotation order.
+   * Returns the chosen account, or the existing current one if none are
+   * available (the server still starts; requests 429 until a window resets).
+   */
+  selectActiveAccount() {
+    this.refreshExpiredQuotas(); // drop any restored windows that already expired
+    const best = this._pickBestAvailable();
+    if (!best) return this.accounts[this.currentIndex] || null;
+    this.currentIndex = best.index;
+    best.probing = best.quota.unified7dReset == null;
+    const wk = best.quota.unified7d != null
+      ? `${(best.quota.unified7d * 100).toFixed(1)}% weekly used`
+      : 'weekly quota unknown';
+    console.log(`[TeamClaude] Starting on account "${best.name}" (priority ${best.priority || 0}, ${wk})`);
+    return best;
+  }
+
+  _selectNext(exclude = null) {
+    const best = this._pickBestAvailable(exclude);
     if (best) {
       const switched = best.index !== this.currentIndex;
       this.currentIndex = best.index;
@@ -273,6 +390,7 @@ export class AccountManager {
     let soonestTime = Infinity;
 
     for (const account of this.accounts) {
+      if (exclude?.has(account.index)) continue;
       const resetTime = account.rateLimitedUntil
         || account.quota.unified5hReset
         || account.quota.unified7dReset
@@ -380,6 +498,37 @@ export class AccountManager {
     }
   }
 
+  /**
+   * Apply quota learned from the OAuth usage endpoint (the background probe).
+   * Updates utilization/reset for the 5h, 7d, and Sonnet-7d buckets WITHOUT
+   * touching usage counters — a probe is not real client traffic.
+   */
+  applyUsageData(accountIndex, usage) {
+    const account = this.accounts[accountIndex];
+    if (!account || !usage) return;
+    const q = account.quota;
+
+    if (usage.fiveHour) {
+      if (usage.fiveHour.utilization != null) q.unified5h = usage.fiveHour.utilization;
+      if (usage.fiveHour.resetAt != null) q.unified5hReset = usage.fiveHour.resetAt;
+    }
+    if (usage.sevenDay) {
+      if (usage.sevenDay.utilization != null) q.unified7d = usage.sevenDay.utilization;
+      if (usage.sevenDay.resetAt != null) q.unified7dReset = usage.sevenDay.resetAt;
+    }
+    if (usage.sevenDaySonnet) {
+      if (usage.sevenDaySonnet.utilization != null) q.unified7dSonnet = usage.sevenDaySonnet.utilization;
+      if (usage.sevenDaySonnet.resetAt != null) q.unified7dSonnetReset = usage.sevenDaySonnet.resetAt;
+    }
+
+    // If we just learned this account's weekly window while probing, re-evaluate
+    // selection (same path as learning it from a live response).
+    if (account.probing && q.unified7dReset != null) {
+      account.probing = false;
+      account.requalify = true;
+    }
+  }
+
   /**
    * Mark an account as rate-limited for a given duration.
    */
@@ -408,7 +557,7 @@ export class AccountManager {
     account._refreshPromise = (async () => {
       console.log(`[TeamClaude] Refreshing token for account "${account.name}"...`);
       try {
-        const newTokens = await refreshAccessToken(account.refreshToken);
+        const newTokens = await this._refreshFn(account.refreshToken);
         account.credential = newTokens.accessToken;
         account.refreshToken = newTokens.refreshToken;
         account.expiresAt = newTokens.expiresAt;
@@ -416,10 +565,16 @@ export class AccountManager {
         this._onTokenRefresh?.(accountIndex, newTokens);
       } catch (err) {
         console.error(`[TeamClaude] Token refresh failed for "${account.name}": ${err.message}`);
-        // Only mark as error if the access token is actually expired;
-        // a failed proactive refresh shouldn't kill a still-valid token
-        if (!account.expiresAt || Date.now() >= account.expiresAt) {
+        // Reserve 'error' (which drops the account from rotation until re-login)
+        // for a GENUINE auth rejection: the refresh token itself is no longer
+        // valid — revoked, or invalidated by an account/plan migration. A
+        // transient failure (network, 5xx, timeout) must NOT sideline a healthy
+        // account: keep its current token and retry on the next request. This is
+        // what kept accounts wrongly "errored" after a momentary refresh blip.
+        const isAuthRejection = err.status === 400 || err.status === 401 || err.status === 403;
+        if (isAuthRejection) {
           account.status = 'error';
+          console.error(`[TeamClaude] Account "${account.name}" needs re-login (refresh token rejected) — run: teamclaude login`);
         }
       } finally {
         account._refreshPromise = null;

package/src/account-uuid-rewrite.js

@@ -0,0 +1,115 @@
+// Rewrite the request body's account_uuid to match the account whose token we
+// inject. Claude Code puts the logged-in account's UUID inside `metadata.user_id`
+// (a stringified JSON) of /v1/messages; under rotation that would disagree with
+// the injected token.
+//
+// This is a STREAMING, byte-exact JSON state machine — no regex, no whole-body
+// buffering — so it handles arbitrarily large bodies fed in chunks. It tracks
+// JSON structure (container stack, current key, in-string/escape) to find the
+// `metadata.user_id` string value, and only inside that value does it look for
+// the `account_uuid` field and overwrite its 36-char value with the new UUID
+// (same length → no content-length/flow-control changes). A stray `account_uuid`
+// elsewhere in the body (user content, tool results) is never touched.
+
+// Byte sequence of `account_uuid":"` as it appears INSIDE the (escaped) user_id
+// string: account_uuid \ " : \ "
+const PREFIX = Buffer.from('account_uuid\\":\\"', 'latin1');
+
+export class AccountUuidPatcher {
+  constructor(newUuid) {
+    this.newUuid = (typeof newUuid === 'string' && newUuid.length === 36) ? Buffer.from(newUuid, 'latin1') : null;
+    this.frames = [];          // container stack: { container:'obj'|'arr', name, key, awaitingKey }
+    this.inStr = false;
+    this.esc = false;
+    this.readingKey = false;
+    this.keyBuf = [];
+    this.target = false;       // inside the metadata.user_id string value
+    this.matchPos = 0;         // PREFIX match progress (within target)
+    this.uuidRemaining = 0;    // value bytes left to overwrite
+    this.done = false;         // patched the one account_uuid already
+    this.changed = false;
+  }
+
+  /** Feed a chunk; returns a same-length chunk (patched in place). */
+  push(chunk) {
+    if (!this.newUuid || this.done) return chunk;
+    const out = Buffer.from(chunk);
+    for (let i = 0; i < out.length; i++) {
+      out[i] = this.#byte(out[i]);
+      if (this.done) break; // rest passes through unchanged
+    }
+    return out;
+  }
+
+  #top() { return this.frames[this.frames.length - 1]; }
+
+  #byte(b) {
+    if (this.target) return this.#targetByte(b);
+
+    if (this.inStr) {
+      if (this.esc) { this.esc = false; if (this.readingKey) this.keyBuf.push(b); return b; }
+      if (b === 0x5c) { this.esc = true; return b; }             // backslash
+      if (b === 0x22) {                                          // end of string
+        this.inStr = false;
+        if (this.readingKey) { this.#top().key = Buffer.from(this.keyBuf).toString('latin1'); this.keyBuf = []; this.readingKey = false; }
+        return b;
+      }
+      if (this.readingKey) this.keyBuf.push(b);
+      return b;
+    }
+
+    const top = this.#top();
+    switch (b) {
+      case 0x7b: this.frames.push({ container: 'obj', name: top ? top.key : null, key: null, awaitingKey: true }); break; // {
+      case 0x5b: this.frames.push({ container: 'arr', name: top ? top.key : null, key: null, awaitingKey: false }); break; // [
+      case 0x7d: case 0x5d: this.frames.pop(); break;            // } ]
+      case 0x3a: if (top) top.awaitingKey = false; break;        // : (key → value)
+      case 0x2c: if (top && top.container === 'obj') top.awaitingKey = true; break; // ,
+      case 0x22:                                                 // string start
+        if (top && top.container === 'obj' && top.awaitingKey) {
+          this.readingKey = true; this.keyBuf = []; this.inStr = true; this.esc = false;
+        } else {
+          this.inStr = true; this.esc = false; this.readingKey = false;
+          if (top && top.container === 'obj' && top.name === 'metadata' && top.key === 'user_id' && this.frames.length === 2) {
+            this.target = true; this.matchPos = 0; this.uuidRemaining = 0;
+          }
+        }
+        break;
+      default: break; // scalars / whitespace
+    }
+    return b;
+  }
+
+  // Inside the metadata.user_id string value: stream-match the account_uuid key
+  // and overwrite its 36-byte value. Detect the (unescaped) closing quote to exit.
+  #targetByte(b) {
+    if (this.uuidRemaining > 0) {
+      const outByte = this.newUuid[this.newUuid.length - this.uuidRemaining];
+      this.uuidRemaining--;
+      if (outByte !== b) this.changed = true;
+      if (this.uuidRemaining === 0) this.done = true; // only one account_uuid per body
+      return outByte;
+    }
+    if (this.esc) { this.esc = false; this.#match(b); return b; }
+    if (b === 0x5c) { this.esc = true; this.#match(b); return b; }
+    if (b === 0x22) { this.target = false; this.matchPos = 0; return b; } // end of user_id value
+    this.#match(b);
+    return b;
+  }
+
+  #match(b) {
+    if (b === PREFIX[this.matchPos]) {
+      this.matchPos++;
+      if (this.matchPos === PREFIX.length) { this.uuidRemaining = 36; this.matchPos = 0; }
+    } else {
+      this.matchPos = (b === PREFIX[0]) ? 1 : 0; // PREFIX has no internal repeat of its first byte
+    }
+  }
+}
+
+/** One-shot convenience (whole-buffer); returns the same instance if unchanged. */
+export function patchAccountUuid(buf, newUuid) {
+  const p = new AccountUuidPatcher(newUuid);
+  const out = p.push(buf);
+  return p.changed ? out : buf;
+}

package/src/h2/frames.js

@@ -0,0 +1,83 @@
+// Minimal HTTP/2 framing (RFC 7540 §4) — just what the MITM relay needs:
+// split a byte stream into frames, re-serialize frames, and (de)construct
+// HEADERS/CONTINUATION header blocks so we can rewrite one header and re-emit.
+// All other frame types are forwarded verbatim by the relay.
+
+export const FRAME = {
+  DATA: 0x0, HEADERS: 0x1, PRIORITY: 0x2, RST_STREAM: 0x3, SETTINGS: 0x4,
+  PUSH_PROMISE: 0x5, PING: 0x6, GOAWAY: 0x7, WINDOW_UPDATE: 0x8, CONTINUATION: 0x9,
+};
+export const FLAG = { END_STREAM: 0x1, END_HEADERS: 0x4, PADDED: 0x8, PRIORITY: 0x20 };
+
+// Client connection preface: "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n" (RFC 7540 §3.5).
+export const PREFACE = Buffer.from('505249202a20485454502f322e300d0a0d0a534d0d0a0d0a', 'hex');
+
+/**
+ * Split as many complete frames as possible out of `buf`.
+ * Returns { frames, rest } where rest is the unconsumed tail (incomplete frame).
+ * Each frame: { type, flags, streamId, payload, raw } (payload/raw are subarrays).
+ */
+export function readFrames(buf) {
+  const frames = [];
+  let off = 0;
+  while (buf.length - off >= 9) {
+    const length = buf.readUIntBE(off, 3);
+    if (buf.length - off < 9 + length) break;
+    frames.push({
+      type: buf[off + 3],
+      flags: buf[off + 4],
+      streamId: buf.readUInt32BE(off + 5) & 0x7fffffff,
+      payload: buf.subarray(off + 9, off + 9 + length),
+      raw: buf.subarray(off, off + 9 + length),
+    });
+    off += 9 + length;
+  }
+  return { frames, rest: buf.subarray(off) };
+}
+
+/** Serialize one frame. */
+export function buildFrame({ type, flags = 0, streamId, payload = Buffer.alloc(0) }) {
+  const h = Buffer.alloc(9);
+  h.writeUIntBE(payload.length, 0, 3);
+  h[3] = type;
+  h[4] = flags;
+  h.writeUInt32BE(streamId & 0x7fffffff, 5);
+  return Buffer.concat([h, payload]);
+}
+
+/**
+ * Pull the header-block fragment out of a HEADERS payload, stripping any
+ * PADDED / PRIORITY prefixes. Returns { block, priority } where priority is the
+ * 5-byte priority field (or null). Padding is discarded.
+ */
+export function stripHeadersPayload(payload, flags) {
+  let off = 0;
+  let padLen = 0;
+  if (flags & FLAG.PADDED) { padLen = payload[0]; off = 1; }
+  let priority = null;
+  if (flags & FLAG.PRIORITY) { priority = Buffer.from(payload.subarray(off, off + 5)); off += 5; }
+  const block = Buffer.from(payload.subarray(off, payload.length - padLen));
+  return { block, priority };
+}
+
+/**
+ * Build a HEADERS frame (+ CONTINUATION frames if the block exceeds
+ * maxFrameSize) for a re-encoded header block. Padding is not re-added.
+ */
+export function buildHeaderBlock(streamId, block, { endStream = false, priority = null, maxFrameSize = 16384 } = {}) {
+  const prio = priority || Buffer.alloc(0);
+  const firstCap = Math.max(0, maxFrameSize - prio.length);
+  const firstChunk = block.subarray(0, firstCap);
+  let rest = block.subarray(firstChunk.length);
+
+  let hFlags = (endStream ? FLAG.END_STREAM : 0) | (priority ? FLAG.PRIORITY : 0);
+  if (rest.length === 0) hFlags |= FLAG.END_HEADERS;
+
+  const out = [buildFrame({ type: FRAME.HEADERS, flags: hFlags, streamId, payload: Buffer.concat([prio, firstChunk]) })];
+  while (rest.length) {
+    const chunk = rest.subarray(0, maxFrameSize);
+    rest = rest.subarray(chunk.length);
+    out.push(buildFrame({ type: FRAME.CONTINUATION, flags: rest.length === 0 ? FLAG.END_HEADERS : 0, streamId, payload: chunk }));
+  }
+  return Buffer.concat(out);
+}