@rikcodes/teamclaude 1.1.20-rik.14 → 1.1.20-rik.16

package/README.md

@@ -107,10 +107,12 @@ A Claude Code session can use OpenAI models alongside the Claude accounts. They
 **1. Install the sidecar and log it into your ChatGPT account** (one time):
 
 ```bash
-brew install raine/claude-code-proxy/claude-code-proxy
+curl -fsSL https://raw.githubusercontent.com/rikbrown/claude-code-proxy/rik/main/scripts/install.sh | bash
 claude-code-proxy codex auth login
 ```
 
+This installs [rikbrown/claude-code-proxy](https://github.com/rikbrown/claude-code-proxy), a fork of the reference sidecar. Take the fork rather than upstream's Homebrew build: it forwards Codex's quota headers, without which every bar on the account reads `unknown`, and it lets you raise the 60-second header timeout that otherwise kills a long reasoning turn. See [Timeouts](docs/openai.md#timeouts).
+
 **2. Connect it** — add four pieces to `~/.config/teamclaude.json`:
 
 ```json
@@ -161,11 +163,11 @@ Each request is routed by the model name in its body, so one session can freely
 
 1. Check that your sidecar build lists it: `curl -s http://127.0.0.1:18765/v1/models`. The sidecar has its own allow-list and rejects any id that it does not know, regardless of the TeamClaude configuration. Upgrade the sidecar if the id is missing.
 2. Add a `customModels` row. Codex publishes the window for each model as `context_window` in `~/.codex/models_cache.json`; copy it to `contextTokens`.
-3. Start a new `teamclaude run` session. The rows are read at launch, so you do not need to restart the server. If you upgraded the sidecar binary, restart the server — or send `SIGTERM` to the sidecar process and let the supervisor restart it with the new binary.
+3. Start a new `teamclaude run` session. The rows are read at launch, so you do not need to restart the server. If you upgraded the sidecar binary, restart the server — or send `SIGTERM` to the sidecar process and let the supervisor restart it with the new binary. The first `SIGTERM` only starts a graceful shutdown, which a request in flight holds open; send it a second time to force the exit.
 
-Claude Code prints one `[claude-code:unrecognized_model]` line to stderr for each custom model. This is expected; suppressing it would lose the correct context window. The quota bars for the sidecar account show `unknown` unless the sidecar forwards Codex's rate-limit headers — see [Quota](docs/openai.md#quota). Keep the sidecar on loopback.
+Claude Code prints one `[claude-code:unrecognized_model]` line to stderr for each custom model. This is expected; suppressing it would lose the correct context window. The quota bars for the sidecar account show `unknown` unless the sidecar forwards Codex's rate-limit headers, which the fork build in step 1 does and upstream's does not — see [Quota](docs/openai.md#quota). Keep the sidecar on loopback.
 
-The sidecar appears under the account table as a `⚙` line rather than a row because it holds no subscription, is the only account its route can use, and never rotates. The line also shows its supervised process state (`up pid 98018`, or `down (code 1) 3 restarts`).
+The sidecar appears under the account table as a `⚙` line rather than a row because it holds no subscription, is the only account its route can use, and never rotates. The line also shows its supervised process state (`up pid 98018`, or `down (code 1) 3 restarts`), followed by what the sidecar reports about itself while it is up (`2 active 3 errors`, read from its own `/monitor` endpoint; each is omitted at zero, and both are omitted if that endpoint does not answer).
 
 #### Several ChatGPT accounts
 
@@ -221,7 +223,7 @@ Three details matter:
 - **`CCP_CODEX_TRANSPORT=http` is required.** A WebSocket upgrade is relayed with the caller's own headers and draws no account, so the WebSocket transport cannot be pooled.
 - **Do not reuse a name across providers.** Routes address accounts by name, so a shared name admits both — including the Claude account that cannot serve `gpt-*`, which outranks the sidecar on priority and wins. TeamClaude warns at startup when it sees one.
 
-Two things differ from the single-account setup: each turn appears **twice** in the activity list, once per hop, and tokens are booked against the sidecar account, so a ChatGPT account reads `N req · 0 tok`. Its quota bars are unaffected because they come from the `x-codex-*` headers on the second hop, where the subscription is.
+One thing differs from the single-account setup: each turn appears **twice** in the activity list, once per hop. Tokens and quota bars both come from the second hop, where the subscription is, so they are booked against the ChatGPT account that served. The sidecar account holds a stub login and spends nothing of its own, so it reads `N req · 0 tok` — booking it as well would double every figure.
 
 Full details, including what happens to quota on each hop: [Several ChatGPT accounts behind one sidecar](docs/openai.md#several-chatgpt-accounts-behind-one-sidecar).
 
@@ -240,6 +242,7 @@ This feature is on by default. Each account row shows which window binds first:
 | [OpenAI models](docs/openai.md) | Codex sidecar setup, custom model registration, GPT subagents, limitations |
 | [Configuration](docs/configuration.md) | Config format, every field, environment variables, network tuning |
 | [Proxy modes](docs/proxy-modes.md) | MITM forward proxy, sx.org residential egress |
+| [Remote host](docs/remote.md) | Running the fleet on an always-on box: reaching it, moving the accounts, service supervision, pointing clients at it |
 | [Compliance](docs/compliance.md) | Terms of service notes |
 
 ## Releasing this fork

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.20-rik.14",
+  "version": "1.1.20-rik.16",
   "description": "Multi-account proxy for Claude Code and Codex: pools Claude Max, ChatGPT/Codex, API-key and third-party backend accounts, and rotates on quota",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -100,6 +100,23 @@ const PERSISTED_QUOTA_FIELDS = [
   'unifiedStatus', 'unifiedStatusSeenAt',
   'tokensLimit', 'tokensRemaining', 'requestsLimit', 'requestsRemaining', 'resetsAt',
   'scopedWeekly',
+  // Codex free rate-limit reset credits, `{ available, applicable, seenAt }`.
+  // Worth persisting although it is not a quota: the usage probe is off by
+  // default, so without this a restart forgets that an account holds a credit
+  // until something next reads /wham/usage — and the row that says so is the
+  // only place an operator sees one at all.
+  'resetCredits',
+  // The Codex subscription tier, a string from the response headers or the
+  // usage payload. Both sources are traffic, so without this a restarted server
+  // cannot name an account's plan until it next serves a request — and a plan
+  // an account is on does not change over a restart.
+  'planType',
+  // Codex's model-scoped weekly buckets, `{ [slug]: { name, utilization,
+  // resetAt, seenAt } }`. Learned the same way and just as lossy on restart,
+  // and the per-entry `seenAt` is load-bearing beyond the reading itself: it is
+  // what orders the eviction that keeps the table under its cap, so dropping
+  // the table also drops the history that decides what makes room next.
+  'codexModelBuckets',
 ];
 
 // The family (Fable/Sonnet) weekly buckets and the field holding when each was
@@ -127,6 +144,22 @@ function parseResetAt(value) {
   return Number.isNaN(parsed) ? null : parsed;
 }
 
+/**
+ * The quota fields a Codex account only ever LEARNS — from a `/wham/usage`
+ * payload or from the state restored off disk — so `emptyQuota` below does not
+ * seed them. Absent is meaningful for each: it says nothing has been read yet,
+ * which a seeded null would spell the same way as "read, and empty".
+ *
+ * Declared here so the few places that write them can say so (`@type` on the
+ * local that holds the quota), rather than each one reading as a property that
+ * does not exist.
+ *
+ * @typedef {object} CodexLearnedQuota
+ * @property {string} [planType]  the Codex subscription tier
+ * @property {{available: number, applicable: number|null, seenAt: number}} [resetCredits]  free rate-limit reset credits held, and when that was last seen
+ * @property {Record<string, {name: string, utilization: number, resetAt: number|null, seenAt: number}>} [codexModelBuckets]  model-scoped weekly buckets, keyed by slug
+ */
+
 function emptyQuota() {
   return {
     // Standard API rate limits (API key accounts)
@@ -223,6 +256,17 @@ function makeAccount(acct, index) {
     displayOrder: Number.isFinite(acct.displayOrder) ? acct.displayOrder : null,
     disabled: acct.disabled || false,
     maxUsage: acct.maxUsage ?? null,
+    // Whether this account is EXEMPT from spending one of its free Codex
+    // rate-limit reset credits (see codex-reset-credits.js). Negative-only, and
+    // the polarity is the opposite of what the name suggests: the switch that
+    // arms anything is the fleet-wide `autoRedeemResets`, because the policy it
+    // arms ("only when the whole Codex pool is dry") is a statement about the
+    // fleet. All this key can say is "never this one", so `true` and an absent
+    // key mean exactly the same thing here. Meaningless on an Anthropic
+    // account, which has no such credits — the redeemer checks the provider
+    // rather than making the field's default depend on it, so a config moved
+    // between providers keeps saying the same thing.
+    autoRedeemReset: acct.autoRedeemReset !== false,
     upstream: acct.upstream || null,
     modelMap: acct.modelMap || null,
     // Fields to drop from request bodies for this account (third-party upstreams
@@ -3492,7 +3536,9 @@ export class AccountManager {
     // threshold and every request fails, while a sibling sits at 0%.
     // A standalone sidecar (no Codex accounts here) is NOT a conduit: it holds
     // its own login, the forwarded numbers are its own, and they still apply.
-    if (!(isLocalUpstream(account) && this.accounts.some(a => providerOf(a) === 'codex'))) {
+    // Shares its definition with the token counters, which drop a conduit hop
+    // for the same reason: what it reports belongs to whoever served.
+    if (!this._isCodexConduit(account)) {
       for (const window of ['primary', 'secondary']) {
         const used = parseFloat(headers[`x-codex-${window}-used-percent`]);
         const minutes = parseInt(headers[`x-codex-${window}-window-minutes`], 10);
@@ -3563,12 +3609,62 @@ export class AccountManager {
     }
   }
 
+  /**
+   * Whether `account` merely RELAYS to this fleet's own Codex pool instead of
+   * holding a subscription of its own: a translating sidecar whose back leg is
+   * pointed back at this proxy, so each turn crosses this process twice — once
+   * inbound on `/v1/messages` and once outbound on `/backend-api/codex/*`
+   * (docs/openai.md, "Several ChatGPT accounts behind one sidecar").
+   *
+   * Keyed on three things, all of which the documented setup has and no other
+   * account does:
+   *
+   *   a loopback upstream   the sidecar runs on this machine.
+   *   the Anthropic wire    a conduit is reached on `/v1/messages`, so it
+   *                         carries no `provider` field — docs/openai.md warns
+   *                         that giving one `"provider": "codex"` puts it in the
+   *                         foreign-subscription partition and every `gpt-*`
+   *                         request then fails to find an account. A pooled
+   *                         ChatGPT account is therefore never a conduit,
+   *                         whatever its upstream says; it IS the pool.
+   *   a pool to relay to    a standalone sidecar holding its own ChatGPT login
+   *                         is NOT a conduit: everything it reports is its own,
+   *                         and it is the only hop there is.
+   *
+   * Still imprecise in one direction, deliberately: a fleet running BOTH a
+   * self-hosting local Anthropic backend and Codex accounts reads the former as
+   * a conduit. Narrowing that would mean correlating the two hops of one turn,
+   * which nothing here can do — they are separate requests sharing no id — and
+   * the cost of the false positive is a row that under-reports rather than one
+   * that misroutes.
+   *
+   * @param {any} account
+   */
+  _isCodexConduit(account) {
+    return isLocalUpstream(account)
+      && providerOf(account) === DEFAULT_PROVIDER
+      && this.accounts.some(a => providerOf(a) === 'codex');
+  }
+
+  /**
+   * Whether this account merely relays to our own Codex pool, for a caller
+   * outside this class that must not treat a relayed reading as the account's
+   * own. The private form above is the definition; this is the same question
+   * asked from the request path, where the distinction decides whether a quota
+   * rejection describes the account in hand or one behind it.
+   *
+   * @param {any} account
+   */
+  isCodexConduit(account) {
+    return this._isCodexConduit(account);
+  }
+
   /**
    * Update cumulative token usage from response body data.
    */
   updateUsage(accountIndex, inputTokens, outputTokens) {
     const account = this.accounts[accountIndex];
-    if (!account) return;
+    if (!account || this._isCodexConduit(account)) return;
     if (inputTokens) account.usage.totalInputTokens += inputTokens;
     if (outputTokens) account.usage.totalOutputTokens += outputTokens;
   }
@@ -3588,6 +3684,22 @@ export class AccountManager {
    */
   recordTokenUsage(accountIndex, sessionId, model, usage) {
     if (!usage) return;
+    // A conduit hop is the SAME tokens, translated: the sidecar rebuilt this
+    // report out of the Responses usage the pool sent it, and the pool's own hop
+    // records the original a moment later. Both scopes would double — the two
+    // account rows are distinct, but a session is one row and carries the same
+    // id on both hops, so its context and spend would read twice the truth.
+    //
+    // Dropped rather than deduplicated because there is nothing to deduplicate
+    // against: the two hops are separate requests that share no id, and the
+    // conduit spends nothing of its own anyway (its login is a stub). Booking at
+    // the hop that really spent is what keeps one turn one record.
+    //
+    // Only the ACCOUNT-scoped and SESSION-scoped counters stop here. Per-client
+    // attribution still runs on the inbound hop, in the caller, because that is
+    // the only hop that can see who asked: the outbound one comes from the
+    // sidecar on loopback and carries no client identity at all.
+    if (this._isCodexConduit(this.accounts[accountIndex])) return;
     // The same resolver routing uses, so a token total and a routing decision
     // agree about which family a request belonged to. Resolved here rather than
     // at the call sites: they parse a wire format and have no business knowing
@@ -3741,6 +3853,9 @@ export class AccountManager {
   applyCodexUsageData(accountIndex, usage) {
     const account = this.accounts[accountIndex];
     if (!account || !usage || usage.error) return;
+    // The three Codex-learned fields below are written here for the first time,
+    // so the empty-quota shape does not carry them. See CodexLearnedQuota.
+    /** @type {typeof account.quota & CodexLearnedQuota} */
     const q = account.quota;
     if (usage.fiveHour) {
       q.unified5h = usage.fiveHour.utilization;
@@ -3751,6 +3866,10 @@ export class AccountManager {
       q.unified7dReset = usage.sevenDay.resetAt ?? null;
     }
     if (usage.planType) q.planType = safeLine(usage.planType, 64);
+    // Stamped, because nothing else refreshes it: a payload that mentions no
+    // credits leaves the last reading alone rather than blanking it, so the
+    // age is the only thing that says how much the number is worth.
+    if (usage.resetCredits) q.resetCredits = { ...usage.resetCredits, seenAt: Date.now() };
     if (Array.isArray(usage.modelBuckets)) {
       q.codexModelBuckets = Object.fromEntries(usage.modelBuckets.slice(0, MAX_CODEX_MODEL_BUCKETS)
         .filter(bucket => bucket?.slug)
@@ -4077,6 +4196,20 @@ export class AccountManager {
       for (const f of PERSISTED_QUOTA_FIELDS) {
         if (match.quota[f] != null) account.quota[f] = match.quota[f];
       }
+      // Both writers of the Codex bucket table cap it, because its keys are
+      // upstream header names; restoring is the one way in that never passed a
+      // cap. A file we wrote cannot be over the ceiling, but an edited or
+      // half-written one can, and it would then stand until some slug this
+      // server has never seen turns up to evict the surplus. Newest readings
+      // kept, which is the same order the eviction there works in.
+      /** @type {typeof account.quota & CodexLearnedQuota} */
+      const quota = account.quota;
+      const restoredBuckets = quota.codexModelBuckets;
+      if (restoredBuckets && Object.keys(restoredBuckets).length > MAX_CODEX_MODEL_BUCKETS) {
+        quota.codexModelBuckets = Object.fromEntries(Object.entries(restoredBuckets)
+          .sort((a, b) => (b[1]?.seenAt || 0) - (a[1]?.seenAt || 0))
+          .slice(0, MAX_CODEX_MODEL_BUCKETS));
+      }
       for (const field of ['organizationType', 'rateLimitTier', 'seatTier', 'hasClaudeMax', 'hasClaudePro']) {
         if (match.profile?.[field] != null) account[field] = match.profile[field];
       }

package/src/claude-env.js

@@ -76,6 +76,66 @@ export function mergeNoProxy(...inherited) {
   return out.join(',');
 }
 
+/** The two ways a launched client can reach the proxy. */
+export const CLIENT_MODES = ['mitm', 'base-url'];
+
+/**
+ * Which mode `run` and `env` use: a `--mitm` or `--no-mitm` flag decides, else
+ * the config's `defaultClientMode`, else MITM.
+ *
+ * MITM routes every request of the launched client through the proxy, so the
+ * hard-coded api.anthropic.com endpoints and the Codex CLI (which honours only
+ * proxy variables) are covered. It is also the whole point of the setting: with
+ * `eval "$(teamclaude env)"` the proxy variables are shell-wide, and every other
+ * tool in that shell — gh, git, a package manager — follows them to a listener
+ * that only speaks to two hosts (#382). An operator who lives in such a shell
+ * sets `defaultClientMode: "base-url"` once and opts back in per launch.
+ *
+ * @param {{ defaultClientMode?: string }|null|undefined} config
+ * @param {string[]} flags  the invocation's own arguments
+ * @returns {'mitm'|'base-url'}
+ */
+export function resolveClientMode(config, flags) {
+  const mitm = flags.includes('--mitm');
+  const noMitm = flags.includes('--no-mitm');
+  if (mitm && noMitm) throw new Error('choose either --mitm or --no-mitm');
+  if (mitm) return 'mitm';
+  if (noMitm) return 'base-url';
+  return config?.defaultClientMode === 'base-url' ? 'base-url' : 'mitm';
+}
+
+const SHELL_PROXY_VARS = ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'http_proxy', 'https_proxy', 'all_proxy'];
+
+/**
+ * @param {unknown} value
+ * @param {number} port
+ */
+function pointsAtLoopback(value, port) {
+  if (!value) return false;
+  try {
+    const url = new URL(String(value));
+    const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return ['127.0.0.1', 'localhost', '::1'].includes(host) && Number(url.port || 80) === port;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `unset` lines for proxy variables a previous MITM-mode eval left in the
+ * shell, so re-evaluating in base-URL mode takes the proxy back out of it. Only
+ * a value naming THIS proxy's loopback port is touched: a real corporate proxy
+ * in the same variables is the operator's and stays.
+ *
+ * @param {unknown} port
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+export function clearSelfProxyEnvLines(port, env = process.env) {
+  const checkedPort = validPort(port);
+  return SHELL_PROXY_VARS.filter(name => pointsAtLoopback(env[name], checkedPort)).map(name => `unset ${name}`);
+}
+
 // Build the shell `export` lines that point Claude Code — or any tool that
 // spawns it, e.g. an agent multiplexer — at the proxy. This is the same
 // environment `teamclaude run` sets up, but emitted for `eval "$(teamclaude