@rikcodes/teamclaude 1.1.20-rik.15 → 1.1.20-rik.17

package/README.md

@@ -65,6 +65,7 @@ Already logged into Claude Code? `teamclaude import` takes its credentials inste
 - Pools OpenAI Codex subscriptions alongside Claude accounts (experimental): the Codex CLI is routed through the same proxy, by config or transparently through the MITM proxy, and rotates on its own quota.
 - Takes any Anthropic-compatible API (DeepSeek, GLM) as a low-priority fallback for when the Claude accounts are done.
 - Serves OpenAI models next to Claude ones — a supervised local sidecar translates `gpt-*` requests onto a ChatGPT subscription, with real model names in `/model` and GPT subagents dispatchable from a Claude parent (`sidecars` + `customModels`, this fork).
+- Ships those subagents as a Claude Code plugin: one named agent per model **and effort level**, which the Agent tool's `model` parameter cannot express (`/plugin install rikclaude-agents@rikclaude`, this fork).
 - No dependencies. Node built-ins only.
 
 ## Everyday commands
@@ -152,10 +153,10 @@ At launch, `teamclaude run` — and the `claude` alias, which passes through `ru
 | Row field | Where it ends up |
 | --- | --- |
 | `model`, `label`, `description` | A `/model` picker row under the **real** model id (`--settings`), so `/model gpt-5.6-sol` works picked or typed |
-| `model` | A dispatchable subagent named after the model (`--agents`), so "dispatch a `gpt-5.6-terra` subagent" works from a Claude parent. Set `"customModelAgents": false` to skip these if you define your own agents in `~/.claude/agents/` |
+| `model` | Nothing by default. Set `"customModelAgents": true` and each row also becomes a plain subagent named after the model (`--agents`), so "dispatch a `gpt-5.6-terra` subagent" works from a Claude parent. Off because those agents pin no effort and outrank every agent file on disk — prefer the effort-pinned [plugin agents](docs/agents.md) |
 | `contextTokens` | `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, set to the largest value across rows, so Claude Code compacts at the real window instead of assuming 200k |
 
-For tools that spawn `claude` themselves, `teamclaude env` can set only environment variables. It carries the window and `ANTHROPIC_CUSTOM_MODEL_OPTION` for the **first** row. For GPT subagents under `env`, create `~/.claude/agents/<name>.md` with `model: gpt-5.6-terra` in its frontmatter.
+For tools that spawn `claude` themselves, `teamclaude env` can set only environment variables. It carries the window and `ANTHROPIC_CUSTOM_MODEL_OPTION` for the **first** row. Agents do not depend on either mode: they are read from disk, whether they come from the [`rikclaude-agents` plugin](docs/agents.md) or from a `~/.claude/agents/<name>.md` you write with `model: gpt-5.6-terra` in its frontmatter.
 
 Each request is routed by the model name in its body, so one session can freely mix models: use `claude --model gpt-5.6-sol` for a whole session, `/model gpt-5.6-sol` during a session, or a Claude parent that dispatches a GPT subagent.
 
@@ -240,8 +241,10 @@ This feature is on by default. Each account row shows which window binds first:
 | [Routing](docs/routing.md) | Rotation, the two kinds of 429, storm control, model routes, session spreading, pinning, prompt cache |
 | [Quota](docs/quota.md) | Quota probe, keep-warm, holding on exhaustion |
 | [OpenAI models](docs/openai.md) | Codex sidecar setup, custom model registration, GPT subagents, limitations |
+| [Subagents](docs/agents.md) | The `rikclaude-agents` plugin: effort-pinned agents per model, installing it, seeding it for a team |
 | [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.15",
+  "version": "1.1.20-rik.17",
   "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
@@ -339,6 +383,7 @@ export class AccountManager {
     // `distributeSessions` gates the behavioural change: keep each session on its
     // account for cache reuse, but spread NEW sessions across equal-priority
     // accounts by load instead of funnelling them all onto the current one.
+    /** @type {SessionTracker} */
     this.sessionTracker = sessionTracker || new SessionTracker();
     // 'off' | 'even' | 'adaptive'. `distributeSessions` stays a boolean beside
     // it ("is distribution on at all") because the status readout, the TUI
@@ -726,6 +771,12 @@ export class AccountManager {
    * bucket, so the account must be eligible for both models. When no account
    * satisfies both, selection degrades to executor-only routing so the main
    * request keeps flowing (upstream then fails just the advisor call).
+   *
+   * `sessionId` is a PIN KEY throughout this class and the session tracker: a
+   * client session narrowed to the conversation within it, since one client
+   * session fans out across many (see conversation.js). It is spelled
+   * `sessionId` because it is one for every request that names no conversation,
+   * and because the affinity it drives is the same affinity it always was.
    */
   getActiveAccount(exclude = null, model = null, advisorModel = null, sessionId = null, provider = DEFAULT_PROVIDER, decision = null) {
     // Selection reads this.currentIndex as "where the fleet is". With more than
@@ -852,11 +903,15 @@ export class AccountManager {
     // The empty set marks this call as a request's, since a poll hands none.
     // Allocated fresh: a set handed out once is one a later reader could add to.
     this.refreshExpiredQuotas(model, this.expiryRouting.enabled ? (exclude ?? new Set()) : exclude, advisorModel);
-    // Session-affinity distribution (opt-in): keep a session on its pinned
-    // account for cache reuse, and route a new session to the least-loaded
-    // account. Only when enabled, only for a real session, and only outside a
-    // manual route pin (which must still win). Falls through to the normal walk
-    // if nothing session-eligible is found (e.g. the whole tier is exhausted).
+    // Session-affinity distribution (opt-in): keep a conversation on its pinned
+    // account for cache reuse, and route a new one to the least-loaded account.
+    // The unit is the conversation rather than the client session because one
+    // session fans out — a Claude Code session and every subagent it launches
+    // share its id, and holding them together pinned a whole fan-out to one
+    // account for a cache none of them shared (see conversation.js). Only when
+    // enabled, only for a request that named one, and only outside a manual
+    // route pin (which must still win). Falls through to the normal walk if
+    // nothing eligible is found (e.g. the whole tier is exhausted).
     if (sessionId && !this._pinnedAccountForModel(model, advisorModel)) {
       if (this.distributeSessions) {
         const acc = this._selectForSession(sessionId, exclude, model, advisorModel);
@@ -1010,13 +1065,18 @@ export class AccountManager {
     // (_isAvailable, below) rather than a second key.
     const bucket = this._weeklyBucketFor(model);
     const pinIdx = this.sessionTracker.pinnedAccount(sessionId, bucket);
-    // The bucket's own pin first. Failing that, any account the session already
-    // sits on for another family: one session stays on one account unless that
-    // account cannot serve the request (the README's "pins it there"). Without
-    // this, a session's first request of a second family would go to
-    // _pickLeastLoaded, which counts the session's own pin as load and pushes
-    // the new family onto a sibling — splitting every mixed-model session
-    // across two accounts by construction, not only on a real diversion.
+    // The bucket's own pin first. Failing that, any account this conversation
+    // already sits on for another family: one conversation stays on one account
+    // unless that account cannot serve the request (the README's "pins it
+    // there"). Without this, its first request of a second family would go to
+    // _pickLeastLoaded, which counts the conversation's own pin as load and
+    // pushes the new family onto a sibling — splitting every mixed-model
+    // conversation across two accounts by construction, not only on a real
+    // diversion.
+    //
+    // Scoped to the one conversation, not to everything sharing its session id:
+    // two agents of one fan-out are not each other's affinity, and treating
+    // them as one is what funnelled them onto a single account.
     const candidates = [];
     if (pinIdx != null) candidates.push(pinIdx);
     for (const idx of this.sessionTracker.pinnedAccounts(sessionId)) {
@@ -1310,6 +1370,18 @@ export class AccountManager {
     this.sessionTracker.recordOutcome(sessionId, usable);
   }
 
+  /**
+   * The same, for an exit that can name only the client session — every live
+   * conversation of it takes the outcome (see SessionTracker).
+   *
+   * @param {string|null} sessionId
+   * @param {boolean|null} usable
+   */
+  recordOutcomeForSession(sessionId, usable) {
+    if (!sessionId || usable === null) return;
+    this.sessionTracker.recordOutcomeForSession(sessionId, usable);
+  }
+
   /**
    * Per-account diagnostics for adaptive distribution: the profile plan tier,
    * relative score weight, and actual next target.
@@ -3602,6 +3674,19 @@ export class AccountManager {
       && 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.
    */
@@ -3796,6 +3881,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;
@@ -3806,6 +3894,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)
@@ -4132,6 +4224,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/codex-quota.js

@@ -110,6 +110,18 @@ function classify(windows) {
   return out;
 }
 
+/**
+ * A parsed reading: the fields `account.quota` already uses, each present only
+ * when the headers stated it.
+ *
+ * @typedef {object} CodexQuota
+ * @property {number} [unified5h] Session-window utilization, 0-1.
+ * @property {number} [unified5hReset] When that window resets, ms epoch.
+ * @property {number} [unified7d] Weekly-window utilization, 0-1.
+ * @property {number} [unified7dReset] When that window resets, ms epoch.
+ * @property {{slug: string, name: string, utilization: number, resetAt: number|null}[]} [modelBuckets] Model-scoped weekly buckets.
+ */
+
 /**
  * Parse Codex rate-limit headers into the fields `account.quota` already uses.
  *
@@ -117,9 +129,12 @@ function classify(windows) {
  * an existing quota without blanking readings this response did not mention.
  * An empty object means "this response carried no quota", which is normal:
  * the catalog fetch (`/models`) has none.
+ *
+ * @returns {CodexQuota}
  */
 export function parseCodexQuota(headers) {
   const families = collectFamilies(headers);
+  /** @type {CodexQuota} */
   const quota = {};
 
   const account = classify(families.get('')?.windows || {});
@@ -172,6 +187,52 @@ export function parseCodexQuota(headers) {
   return quota;
 }
 
+/**
+ * Is a window at or past its limit?
+ *
+ * Readings are 0-1 fractions here, and the comparison is `>=` because upstream
+ * keeps counting once a window is past its limit: 104% arrives as 1.04. A
+ * window the headers did not state is not spent — `classify` has already
+ * dropped the unparseable and the zeroed.
+ *
+ * @param {number} [utilization]
+ */
+const isSpent = (utilization) => utilization != null && utilization >= 1;
+
+/**
+ * Which windows these headers report as spent — at or past their limit. Empty
+ * when none are, including when the response carried no Codex quota at all.
+ *
+ * Anthropic names a spent bucket outright, as `…-status: rejected`. This API
+ * publishes no status at all: it reports how much of each window is gone, and a
+ * window at its limit is the same fact in the other spelling. That distinction
+ * is what a 429 handler needs, because a spent window is durable — the account
+ * cannot serve again until the window resets, so waiting out `retry-after` and
+ * asking the SAME account again is futile, however momentary the 429 looked.
+ *
+ * Every family is read, not just the account-wide one. A subscription states
+ * its only 5-hour window inside a NAMED family (see parseCodexQuota), so the
+ * account-wide percentages alone would never show a spent session window; and a
+ * model-scoped weekly bucket is spent on its own terms, whatever the
+ * account-wide reading says.
+ *
+ * The labels name what is spent, for the log line that follows. A caller that
+ * only wants the verdict tests the length.
+ *
+ * @param {Record<string, string>} headers Rate-limit headers from the response.
+ * @returns {string[]} One label per spent window, e.g. `['weekly']`.
+ */
+export function codexSpentWindows(headers) {
+  const quota = parseCodexQuota(headers);
+  const spent = [];
+  if (isSpent(quota.unified5h)) spent.push('5h');
+  if (isSpent(quota.unified7d)) spent.push('weekly');
+  for (const bucket of quota.modelBuckets ?? []) {
+    if (isSpent(bucket.utilization)) spent.push(`${bucket.name} weekly`);
+  }
+  return spent;
+}
+
 /** The subscription plan upstream reports, for status output. Null when absent. */
 export function parseCodexPlanType(headers) {
   const value = headers?.['x-codex-plan-type'];