codex-multi-auth 2.9.2 → 2.11.0

package/dist/lib/runtime/rotation-server-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rotation-server-types.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-server-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,0BAA0B,CAAC;IAC5C;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,2BAA2B;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GACzB,YAAY,GACZ,cAAc,GACd,eAAe,GACf,cAAc,GACd,QAAQ,GACR,aAAa,GACb,YAAY,CAAC;AAChB,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,8BAA8B;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"rotation-server-types.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-server-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,0BAA0B,CAAC;IAC5C;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,2BAA2B;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GACzB,YAAY,GACZ,cAAc,GACd,eAAe,GACf,cAAc,GACd,QAAQ,GACR,aAAa,GACb,YAAY,CAAC;AAChB,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,8BAA8B;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CAClB"}

package/dist/lib/runtime-rotation-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-rotation-proxy.d.ts","sourceRoot":"","sources":["../../lib/runtime-rotation-proxy.ts"],"names":[],"mappings":"AAGA,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,eAAe,CAAC;AA8BvB,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6CtE,OAAO,KAAK,EAKX,2BAA2B,EAC3B,0BAA0B,EAE1B,MAAM,oCAAoC,CAAC;AAe5C,YAAY,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,GAC1B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACN,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EACN,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AA8DtE,kFAAkF;AAClF,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,OAAO,GAAG,cAAc,CAAC,GAAG;IACvE,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,EACD,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,MAAM,CAmBR;AA8bD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,MAAM,GAAG,IAAI,CAUf;AAED,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA4KrC"}
+{"version":3,"file":"runtime-rotation-proxy.d.ts","sourceRoot":"","sources":["../../lib/runtime-rotation-proxy.ts"],"names":[],"mappings":"AAGA,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,eAAe,CAAC;AAkCvB,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAkDtE,OAAO,KAAK,EAKX,2BAA2B,EAC3B,0BAA0B,EAE1B,MAAM,oCAAoC,CAAC;AAe5C,YAAY,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,GAC1B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACN,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EACN,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AA8DtE,kFAAkF;AAClF,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,OAAO,GAAG,cAAc,CAAC,GAAG;IACvE,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,EACD,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,MAAM,CAmBR;AA8gBD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,MAAM,GAAG,IAAI,CAUf;AAED,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CAmLrC"}

package/dist/lib/runtime-rotation-proxy.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { AccountManager, AUTH_INVALIDATION_MARKER, extractAccountId, } from "./accounts.js";
 import { withRoutingMutex } from "./routing-mutex.js";
-import { getFetchTimeoutMs, getNetworkErrorCooldownMs, getRetryAllAccountsMaxRetries, getServerErrorCooldownMs, getSessionAffinity, getSessionAffinityMaxEntries, getSessionAffinityTtlMs, getStreamStallTimeoutMs, getMinRotationIntervalMs, getTokenInvalidationCooldownMs, getTokenRefreshSkewMs, getPidOffsetEnabled, getPreemptiveQuotaEnabled, getPreemptiveQuotaMaxDeferralMs, getPreemptiveQuotaRemainingPercent5h, getPreemptiveQuotaRemainingPercent7d, getRoutingMutexMode, getSchedulingStrategy, loadPluginConfig, } from "./config.js";
+import { getFetchTimeoutMs, getNetworkErrorCooldownMs, getRetryAllAccountsMaxRetries, getServerErrorCooldownMs, getSessionAffinity, getSessionAffinityMaxEntries, getSessionAffinityTtlMs, getStreamStallTimeoutMs, getMinRotationIntervalMs, getTokenInvalidationCooldownMs, getTokenRefreshSkewMs, getPidOffsetEnabled, getPreemptiveQuotaEnabled, getPreemptiveQuotaMaxDeferralMs, getPreemptiveQuotaRemainingPercent5h, getPreemptiveQuotaRemainingPercent7d, getContextBudgetGuardEnabled, getContextBudgetGuardSoftPercent, getContextBudgetGuardHardPercent, getContextBudgetGuardModelWindowOverrides, getRoutingMutexMode, getSchedulingStrategy, loadPluginConfig, } from "./config.js";
 import { CODEX_BASE_URL, HTTP_STATUS, OPENAI_HEADERS, OPENAI_HEADER_VALUES, URL_PATHS, } from "./constants.js";
 import { getModelFamily } from "./prompts/codex.js";
 import { CURRENT_CODEX_MODEL } from "./request/helpers/model-map.js";
@@ -11,6 +11,8 @@ import { createRuntimeUsageRecorder, evaluateRuntimePolicy, loadRuntimePolicySta
 import { createUsageStreamScanner } from "./usage/usage-extraction.js";
 import { isWorkspaceDisabledError } from "./request/fetch-helpers.js";
 import { PreemptiveQuotaScheduler, readQuotaSchedulerSnapshot, } from "./preemptive-quota-scheduler.js";
+import { ContextBudgetGuard } from "./context-budget-guard.js";
+import { buildContextBudgetHeaders, createContextBudgetPauseResponse, } from "./context-budget-response.js";
 import { createLogger, maskString, runWithCorrelationId } from "./logger.js";
 import { CodexValidationError } from "./errors.js";
 import { normalizeEmailKey } from "./storage/identity.js";
@@ -22,7 +24,7 @@ import { createRotationProxyState, recoverStaleRuntimeState, } from "./runtime/r
 import { readStorageMetaFromDisk } from "./runtime/rotation-storage-meta.js";
 import { applyMonotonicAuthCooldown, DEFAULT_AUTH_FAILURE_COOLDOWN_MS, ensureFreshAccessToken, } from "./runtime/rotation-token-refresh.js";
 import { SessionAffinityStore } from "./session-affinity.js";
-import { isRecord } from "./utils.js";
+import { isRecord, sleep } from "./utils.js";
 export { buildPinnedUnavailableErrorBody, buildTokenInvalidationBody, } from "./request/rate-limit-decision.js";
 export { chooseAccount } from "./runtime/rotation-account-selection.js";
 export { maybeInvalidateAffinityFromDisk, readPinnedAccountIndexFromDisk, readStorageMetaFromDisk, resetPinCacheForTesting, } from "./runtime/rotation-storage-meta.js";
@@ -98,6 +100,39 @@ export function buildQuotaScheduleKey(account, family, model) {
     return `account:${accountIdentity}:${model ?? family}`;
 }
 const DEFAULT_MAX_RUNTIME_ACCOUNT_ATTEMPTS = 4;
+// This is a hard safety ceiling over every pinned selection pass, including
+// branches that do not consume the transient-attempt budget. It deliberately
+// overrides larger retry settings for pinned requests.
+const MAX_PINNED_SELECTION_ITERATIONS = 16;
+/**
+ * Ceiling on same-account re-sends for one pinned request.
+ *
+ * The pool's transient budget is derived from `retryAllAccountsMaxRetries`,
+ * whose documented meaning is "wait and retry when EVERY account is
+ * rate-limited". For an unpinned pool that budget spends across different
+ * accounts; for a pin every unit of it is another copy of the same
+ * (non-idempotent) request to the same upstream, so raising that pool knob
+ * must not silently multiply pinned re-sends. A user who LOWERS the knob
+ * still gets fewer attempts.
+ */
+const MAX_PINNED_TRANSIENT_ATTEMPTS = 4;
+/**
+ * Backoff before each pinned re-attempt: 250ms, 500ms, 1s, capped.
+ *
+ * A pinned retry re-sends the SAME non-idempotent request to the SAME
+ * upstream, and the retry loop has no other delay anywhere in it. The
+ * account's cooldown used to supply that spacing by accident, by blocking
+ * selection outright — which is also why the retry budget could never be
+ * spent. Waiving the cooldown for the retry (see `allowPinnedCooldown`)
+ * removes that accidental spacing, so replace it with a real one that is
+ * short enough not to dominate the request's latency: at most
+ * 250 + 500 + 1000 = 1.75s across the whole request at the default budget.
+ */
+const PINNED_RETRY_BACKOFF_STEPS_MS = [250, 500, 1_000];
+function pinnedRetryBackoffMs(attempt) {
+    const index = Math.min(Math.max(0, attempt - 1), PINNED_RETRY_BACKOFF_STEPS_MS.length - 1);
+    return PINNED_RETRY_BACKOFF_STEPS_MS[index] ?? 0;
+}
 const MAX_REQUEST_BODY_BYTES = 64 * 1024 * 1024;
 const MAX_THREAD_GOAL_FALLBACKS = 512;
 const ALLOWED_RESPONSES_PATHS = new Set([
@@ -317,6 +352,41 @@ function getThreadGoalFallback(fallbacks, key) {
     fallbacks.set(key, goal);
     return goal;
 }
+/**
+ * Session identity that is stable for the life of a conversation.
+ *
+ * Every source here keeps the same value across turns, so state keyed on it
+ * accumulates. `resolveSessionKey` adds `previous_response_id` on top for
+ * callers that only need "requests that belong together right now".
+ */
+function resolveStableSessionKey(headers, parsedBody) {
+    const headerKey = headers.get(OPENAI_HEADERS.SESSION_ID) ??
+        headers.get(OPENAI_HEADERS.CONVERSATION_ID) ??
+        null;
+    if (headerKey && headerKey.trim().length > 0)
+        return headerKey.trim();
+    if (!parsedBody)
+        return null;
+    if (typeof parsedBody.prompt_cache_key === "string") {
+        const key = parsedBody.prompt_cache_key.trim();
+        if (key.length > 0)
+            return key;
+    }
+    const metadata = parsedBody.metadata;
+    if (isRecord(metadata)) {
+        return (readStringRecordValue(metadata, "session_id") ??
+            readStringRecordValue(metadata, "conversation_id") ??
+            readStringRecordValue(metadata, "thread_id"));
+    }
+    return null;
+}
+/**
+ * Session identity for affinity/pinning: the stable sources above, plus
+ * `previous_response_id` as a last resort. Precedence is unchanged from
+ * before `resolveStableSessionKey` was split out — `previous_response_id`
+ * still outranks the `metadata` fallbacks — so which account a request pins
+ * to does not shift.
+ */
 function resolveSessionKey(headers, parsedBody) {
     const headerKey = headers.get(OPENAI_HEADERS.SESSION_ID) ??
         headers.get(OPENAI_HEADERS.CONVERSATION_ID) ??
@@ -362,6 +432,7 @@ function buildResponsesRequestContext(req, body) {
         family: getModelFamily(model ?? CURRENT_CODEX_MODEL),
         stream: parsedBody?.stream === true,
         sessionKey: resolveSessionKey(headers, parsedBody),
+        stableSessionKey: resolveStableSessionKey(headers, parsedBody),
     };
 }
 function buildModelsRequestContext(req) {
@@ -374,6 +445,7 @@ function buildModelsRequestContext(req) {
         family: "codex",
         stream: false,
         sessionKey: null,
+        stableSessionKey: null,
     };
 }
 function buildThreadGoalRequestContext(req, body, pathname) {
@@ -396,6 +468,7 @@ function buildThreadGoalRequestContext(req, body, pathname) {
         family: "codex",
         stream: false,
         sessionKey,
+        stableSessionKey: bodyThreadKey ?? queryThreadKey ?? resolveStableSessionKey(headers, parsedBody),
     };
 }
 function buildUpstreamUrl(req, upstreamBaseUrl, upstreamPath) {
@@ -543,6 +616,12 @@ export async function startRuntimeRotationProxy(options) {
             getPreemptiveQuotaRemainingPercent7d(pluginConfig),
         maxDeferralMs: getPreemptiveQuotaMaxDeferralMs(pluginConfig),
     });
+    const contextBudgetGuard = new ContextBudgetGuard({
+        enabled: getContextBudgetGuardEnabled(pluginConfig),
+        softPercent: getContextBudgetGuardSoftPercent(pluginConfig),
+        hardPercent: getContextBudgetGuardHardPercent(pluginConfig),
+        modelWindowOverrides: getContextBudgetGuardModelWindowOverrides(pluginConfig),
+    });
     const sessionAffinityStore = getSessionAffinity(pluginConfig)
         ? new SessionAffinityStore({
             ttlMs: getSessionAffinityTtlMs(pluginConfig),
@@ -573,6 +652,7 @@ export async function startRuntimeRotationProxy(options) {
         maxRequestBodyBytes,
         quotaRemainingPercentThreshold,
         preemptiveQuotaScheduler,
+        contextBudgetGuard,
         sessionAffinityStore,
         lastObservedAffinityGeneration,
         forcedAccountIndex,
@@ -731,6 +811,40 @@ async function handleRequestInner(state, req, res, traceId) {
             });
             return;
         }
+        // Context budget guard: pause BEFORE spending an upstream round-trip on a
+        // request that the tracked session is already over the hard threshold
+        // for, rather than reacting to the eventual context_length_exceeded 400
+        // (which this rotation-proxy path does not otherwise handle at all — see
+        // lib/context-overflow.ts, wired only into the plugin-loader fetch path).
+        // Runs independent of account selection: which account serves the
+        // request has no bearing on how full its context already is. Hoisted
+        // to function scope (not just this `if`) so the soft-threshold branch
+        // below can attach its non-blocking header to the eventual forwarded
+        // response.
+        let budgetAdvisory = {
+            level: "ok",
+        };
+        if (isResponsesRequest) {
+            budgetAdvisory = state.contextBudgetGuard.getAdvisory(context.stableSessionKey ?? "", requestStartedAt, context.model);
+            if (budgetAdvisory.level === "hard") {
+                // One-shot: the pause returns before the request is forwarded, so
+                // `update()` below never runs for it and the recorded usage cannot
+                // fall on its own. Without dropping the snapshot the first crossing
+                // would wedge the session permanently — including the `/compact`
+                // turn this pause tells the user to run, which carries the same
+                // session key.
+                state.contextBudgetGuard.noteHardPauseEmitted(context.stableSessionKey ?? "");
+                await usageRecorder.record({
+                    outcome: "blocked",
+                    statusCode: HTTP_STATUS.OK,
+                    errorCode: "context_budget_guard_paused",
+                });
+                const pauseResponse = createContextBudgetPauseResponse(budgetAdvisory);
+                res.writeHead(pauseResponse.status, Object.fromEntries(pauseResponse.headers.entries()));
+                res.end(await pauseResponse.text());
+                return;
+            }
+        }
         const upstreamUrl = buildUpstreamUrl(req, state.upstreamBaseUrl, context.upstreamPath);
         const attemptedIndexes = new Set();
         let exhaustionReason = "no-account";
@@ -757,12 +871,51 @@ async function handleRequestInner(state, req, res, traceId) {
         // applies unchanged because it all keys off `pinnedIndex` / `isPinned`.
         const pinnedIndex = state.forcedAccountIndex ?? storageMeta.pinnedAccountIndex;
         const isPinned = typeof pinnedIndex === "number";
+        // The token bucket spreads load across a selectable pool. A pin has no
+        // alternative account, so exhausting that local heuristic can only reject a
+        // request that the pinned account could serve. Keep circuit-breaker admission
+        // inside consumeToken, but do not debit the pool-scoring bucket for a pin.
+        const bypassPoolTokenBucket = isPinned;
+        const refundConsumedPoolToken = (account) => {
+            if (!bypassPoolTokenBucket) {
+                accountManager.refundToken(account, context.family, context.model);
+            }
+        };
+        // `rotations` counts moves to a DIFFERENT account. A pinned request has
+        // nowhere to move: every retry below re-attempts the same one. Counting
+        // those reported several account rotations on a single-account pool whose
+        // pin forbids rotation, in `rotation status` and the persisted counters.
+        const noteRotation = () => {
+            if (!isPinned)
+                state.status.rotations += 1;
+        };
+        // Pool attempts are normally capped by account count because an unpinned
+        // account is selected at most once per request. A pin can only retry the
+        // same account, so use the configured transient-attempt limit instead of
+        // the account-count limit -- capped by MAX_PINNED_TRANSIENT_ATTEMPTS so a
+        // pool knob about rate-limited rotation cannot become a same-account
+        // re-send multiplier. Every pinned pass is still subject to the hard
+        // 16-selection ceiling above.
+        if (isPinned) {
+            transientAttemptLimit = Math.max(1, Math.min(state.maxRuntimeAccountAttempts, MAX_PINNED_TRANSIENT_ATTEMPTS));
+        }
         if (storageMeta.affinityGeneration > state.lastObservedAffinityGeneration) {
             state.sessionAffinityStore?.clearAll();
             state.lastObservedAffinityGeneration = storageMeta.affinityGeneration;
         }
-        while (attemptedIndexes.size < accountCount &&
-            transientAttempts < transientAttemptLimit) {
+        let runtimeSelectionIterations = 0;
+        while ((isPinned || attemptedIndexes.size < accountCount) &&
+            transientAttempts < transientAttemptLimit &&
+            (!isPinned ||
+                runtimeSelectionIterations < MAX_PINNED_SELECTION_ITERATIONS)) {
+            // Space out same-account re-sends. The loop has no other delay in it,
+            // and the pinned retry deliberately waives the account's own cooldown
+            // (below), so without this two copies of the same non-idempotent
+            // request would hit upstream back to back.
+            if (isPinned && transientAttempts > 0) {
+                await sleep(pinnedRetryBackoffMs(transientAttempts));
+            }
+            runtimeSelectionIterations += 1;
             const rotationStickyBoost = state.minRotationIntervalMs > 0 &&
                 state.lastGlobalAccountIndex !== null &&
                 state.now() - state.lastGlobalSwitchAt < state.minRotationIntervalMs
@@ -797,6 +950,12 @@ async function handleRequestInner(state, req, res, traceId) {
                 stickyBoostByAccount: rotationStickyBoost,
                 pidOffsetEnabled: state.pidOffsetEnabled,
                 schedulingStrategy: state.schedulingStrategy,
+                // Only on a RETRY pass. The first pass still honors a cooldown
+                // another request left on the pin, so an already-cooling pinned
+                // account 503s immediately as before; from the second pass on,
+                // this request's own retry budget outranks the cooldown it just
+                // created for itself.
+                allowPinnedCooldown: isPinned && transientAttempts > 0,
             });
             const selected = state.routingMutexMode === "enabled"
                 ? await withRoutingMutex(state.routingMutexMode, async () => {
@@ -856,12 +1015,27 @@ async function handleRequestInner(state, req, res, traceId) {
                 accountManager.markRateLimitedWithReason(selected, preemptiveDeferral.waitMs, context.family, "quota", context.model);
                 accountManager.recordRateLimit(selected, context.family, context.model);
                 accountManager.saveToDiskDebounced();
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
-            if (!accountManager.consumeToken(selected, context.family, context.model)) {
-                accountSkipReasons.set(selected.index, "token-exhausted");
+            // consumeToken also takes the race-safe circuit admission slot, so it
+            // can reject for either gate. Take the reason from the call that
+            // rejected rather than re-deriving it: a second evaluation reports the
+            // first blocker it finds (a live cooldown would mask a drained bucket)
+            // and cannot see a half-open probe slot that was just claimed.
+            const admission = accountManager.consumeTokenWithReason(selected, context.family, context.model, { bypassTokenBucket: bypassPoolTokenBucket });
+            if (!admission.ok) {
+                accountSkipReasons.set(selected.index, admission.reason);
                 exhaustionReason = "rate-limit";
+                // Neither gate can change inside this loop -- nothing here refills the
+                // bucket or closes a circuit -- and a pin has no other account to move
+                // to, so re-selecting would burn the whole 16-iteration ceiling
+                // re-deriving the identical verdict. (For a pin the bucket is bypassed
+                // entirely, so the reason here is always circuit-open.) Unpinned
+                // selection still continues -- there the next pass picks a DIFFERENT
+                // account.
+                if (isPinned)
+                    break;
                 continue;
             }
             const refreshed = await ensureFreshAccessToken({
@@ -874,7 +1048,13 @@ async function handleRequestInner(state, req, res, traceId) {
                 tokenInvalidationCooldownMs: state.tokenInvalidationCooldownMs,
             });
             if (!refreshed.ok) {
-                accountManager.refundToken(selected, context.family, context.model);
+                refundConsumedPoolToken(selected);
+                // No accountSkipReasons write here: ensureFreshAccessToken always
+                // applies an auth cooldown before returning !ok, so the next
+                // selection pass overwrites whatever this set with
+                // cooling-down:auth-failure, the invalidated exit returns a 401
+                // without reading the map at all, and the budget-boundary block
+                // below already records "auth-failure" for a pin out of retries.
                 exhaustionReason = "auth-failure";
                 if (refreshed.invalidated) {
                     // Refresh endpoint explicitly revoked the token. Stop cascade:
@@ -898,12 +1078,12 @@ async function handleRequestInner(state, req, res, traceId) {
                 transientAttempts += 1;
                 transientExhaustionReason = "auth-failure";
                 state.status.retries += 1;
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
             const accountId = resolveAccountId(refreshed.account, refreshed.accessToken);
             if (!accountId) {
-                accountManager.refundToken(refreshed.account, context.family, context.model);
+                refundConsumedPoolToken(refreshed.account);
                 accountManager.recordFailure(refreshed.account, context.family, context.model);
                 accountManager.markAccountCoolingDown(refreshed.account, DEFAULT_AUTH_FAILURE_COOLDOWN_MS, "auth-failure");
                 // Persist the cooldown like every other cooldown branch in this loop
@@ -916,7 +1096,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 transientAttempts += 1;
                 transientExhaustionReason = "auth-failure";
                 state.status.retries += 1;
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
             const accountIdentity = accountIdentityFromAccount(refreshed.account, state.now());
@@ -950,7 +1130,7 @@ async function handleRequestInner(state, req, res, traceId) {
                     code: "codex_runtime_rotation_transport_error",
                     error: transportError,
                 });
-                accountManager.refundToken(refreshed.account, context.family, context.model);
+                refundConsumedPoolToken(refreshed.account);
                 // A pre-header transport exception is a property of the network path,
                 // not of this account's credentials or quota, so it must NOT feed the
                 // account's circuit breaker / health tracker: that is what would
@@ -970,7 +1150,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 transientAttempts += 1;
                 transientExhaustionReason = "network-error";
                 state.status.retries += 1;
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
             const quotaSnapshot = readQuotaSchedulerSnapshot(upstream.headers, upstream.status, state.now());
@@ -992,7 +1172,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 transientAttempts += 1;
                 transientExhaustionReason = "rate-limit";
                 state.status.retries += 1;
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
             if (upstream.status === 402 || upstream.status === HTTP_STATUS.FORBIDDEN) {
@@ -1001,7 +1181,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 if (isWorkspaceDisabledError(upstream.status, errorCode, bodyText)) {
                     const accountWasEnabled = accountManager.getAccountByIndex(refreshed.account.index)?.enabled !==
                         false;
-                    accountManager.refundToken(refreshed.account, context.family, context.model);
+                    refundConsumedPoolToken(refreshed.account);
                     if (accountWasEnabled) {
                         accountManager.recordFailure(refreshed.account, context.family, context.model);
                         accountManager.setAccountEnabled(refreshed.account.index, false);
@@ -1010,7 +1190,7 @@ async function handleRequestInner(state, req, res, traceId) {
                     state.sessionAffinityStore?.forgetSession(context.sessionKey);
                     exhaustionReason = "deactivated";
                     state.status.retries += 1;
-                    state.status.rotations += 1;
+                    noteRotation();
                     continue;
                 }
                 if (isThreadGoalRequest && isThreadGoalFallbackStatus(upstream.status)) {
@@ -1080,7 +1260,7 @@ async function handleRequestInner(state, req, res, traceId) {
             }
             if (upstream.status === HTTP_STATUS.UNAUTHORIZED) {
                 const bodyText = await readErrorBody(upstream, state.streamStallTimeoutMs);
-                accountManager.refundToken(refreshed.account, context.family, context.model);
+                refundConsumedPoolToken(refreshed.account);
                 accountManager.recordFailure(refreshed.account, context.family, context.model);
                 if (isTokenInvalidationError(bodyText)) {
                     // The upstream explicitly revoked this OAuth token. Applying a long
@@ -1116,12 +1296,12 @@ async function handleRequestInner(state, req, res, traceId) {
                 transientAttempts += 1;
                 transientExhaustionReason = "auth-failure";
                 state.status.retries += 1;
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
             if (upstream.status >= 500) {
                 await readErrorBody(upstream, state.streamStallTimeoutMs);
-                accountManager.refundToken(refreshed.account, context.family, context.model);
+                refundConsumedPoolToken(refreshed.account);
                 accountManager.recordFailure(refreshed.account, context.family, context.model);
                 accountManager.markAccountCoolingDown(refreshed.account, state.serverErrorCooldownMs, "server-error");
                 accountManager.saveToDiskDebounced();
@@ -1129,7 +1309,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 transientAttempts += 1;
                 transientExhaustionReason = "server-error";
                 state.status.retries += 1;
-                state.status.rotations += 1;
+                noteRotation();
                 continue;
             }
             if (isThreadGoalRequest && upstream.status >= 400) {
@@ -1196,10 +1376,31 @@ async function handleRequestInner(state, req, res, traceId) {
                 accountManager.markAccountCoolingDown(refreshed.account, state.networkErrorCooldownMs, "network-error");
                 state.sessionAffinityStore?.forgetSession(context.sessionKey);
                 accountManager.saveToDiskDebounced();
-            }, state.streamStallTimeoutMs, usageScanner.push);
+            }, state.streamStallTimeoutMs, usageScanner.push, budgetAdvisory.level === "soft"
+                ? buildContextBudgetHeaders(budgetAdvisory)
+                : undefined);
             // A stream that broke mid-flight still bills for whatever the upstream
             // reported before the break, so record the counts on both outcomes.
             const usageTokens = usageScanner.result();
+            // Responses is mostly stateless (store=false): each successful turn's
+            // input_tokens reflects the full conversation resent this call, so it
+            // doubles as a live read of the session's current context size. Record
+            // it even on a broken stream, matching the ledger's own choice above —
+            // the tokens upstream billed for were still resent as full context.
+            //
+            // input + output, NOT total: `usageTokens.totalTokens` is the
+            // provider's `total_tokens`, which also counts `reasoning_tokens`.
+            // Reasoning is not carried into the next turn's input, so counting
+            // it here inflates the measurement by this turn's thinking budget
+            // against a deliberately tight threshold. `outputTokens` is already
+            // reasoning-stripped (lib/usage/usage-extraction.ts).
+            if (usageTokens && context.stableSessionKey && context.model) {
+                state.contextBudgetGuard.update(context.stableSessionKey, {
+                    model: context.model,
+                    contextTokens: usageTokens.inputTokens + usageTokens.outputTokens,
+                    updatedAt: state.now(),
+                });
+            }
             await usageRecorder.record({
                 outcome: forwarded ? "success" : "failure",
                 statusCode: upstream.status,
@@ -1209,8 +1410,23 @@ async function handleRequestInner(state, req, res, traceId) {
             });
             return;
         }
+        if (isPinned &&
+            typeof pinnedIndex === "number" &&
+            transientAttempts >= transientAttemptLimit) {
+            const pinnedAccount = accountManager.getAccountByIndex(pinnedIndex);
+            const liveReason = pinnedAccount
+                ? accountManager.getManagedAccountRuntimeSkipReason(pinnedAccount, context.family, context.model)
+                : "missing";
+            const finalAttemptReason = transientExhaustionReason === "rate-limit"
+                ? "rate-limited"
+                : transientExhaustionReason;
+            const finalPinnedReason = liveReason ?? finalAttemptReason;
+            if (finalPinnedReason !== null) {
+                accountSkipReasons.set(pinnedIndex, finalPinnedReason);
+            }
+        }
         if (transientAttempts >= transientAttemptLimit &&
-            attemptedIndexes.size < accountCount) {
+            (isPinned || attemptedIndexes.size < accountCount)) {
             exhaustionReason = "budget";
         }
         else if (exhaustionReason === "deactivated" &&
@@ -1237,17 +1453,13 @@ async function handleRequestInner(state, req, res, traceId) {
             // so advertising a record's expiry would invite a retry into another
             // 503.
             //
-            // The recorded reason alone is not enough to detect one. It is the
-            // SELECTION verdict, and this request can make the pin permanently
-            // unselectable after selection already ran: a workspace-disabled
-            // 402/403 calls setAccountEnabled(index, false) above and then
-            // continues, so the next pass records "already-attempted" and the
-            // disable never surfaces. With a breaker tripped by the same failure
-            // the 503 would then advertise the circuit's ~30s reset for an
-            // account no timer will ever re-admit. Re-read the pin's CURRENT
-            // runtime state so a permanent blocker cannot hide behind the
-            // verdict; the recorded reason still covers the selection-only
-            // verdicts ("missing", "policy-blocked") that state cannot express.
+            // The recorded reason alone is not enough to detect every concurrent
+            // state change: it is the most recent selection/attempt verdict, while
+            // this request or another one can make the pin permanently unselectable
+            // after that verdict was recorded. Re-read the pin's CURRENT runtime
+            // state so a permanent blocker cannot hide behind an earlier transient
+            // failure; the recorded reason still covers selection-only verdicts
+            // ("missing", "policy-blocked") that state cannot express.
             const pinnedCurrentSkipReason = pinnedAccount === null
                 ? null
                 : accountManager.getManagedAccountRuntimeSkipReason(pinnedAccount, context.family, context.model);
@@ -1255,13 +1467,10 @@ async function handleRequestInner(state, req, res, traceId) {
                 PINNED_PERMANENT_SKIP_REASONS.has(pinnedSkipReason)) ||
                 (pinnedCurrentSkipReason !== null &&
                     PINNED_PERMANENT_SKIP_REASONS.has(pinnedCurrentSkipReason));
-            // Otherwise recovery comes from the pinned account's persisted state, not the
-            // recorded skip reason: a direct 429/cooldown on the pinned account
-            // reaches this 503 as "already-attempted" (the retry loop's selection
-            // verdict) while the record it just wrote is what actually bounds
-            // recovery — and with several overlapping records the account stays
-            // skipped until the LAST one expires, so the latest bound is the one
-            // worth advertising.
+            // Otherwise recovery comes from the pinned account's persisted state,
+            // not merely the recorded skip token. With several overlapping records
+            // the account stays skipped until the LAST one expires, so the latest
+            // bound is the one worth advertising.
             //
             // One clock for the whole body. The recovery bound and the
             // rate-limit bound are compared against each other below, so
@@ -1296,9 +1505,8 @@ async function handleRequestInner(state, req, res, traceId) {
                 pinSource: typeof state.forcedAccountIndex === "number" ? "forced" : "manual",
                 resetAtMs: pinnedResetAtMs,
                 recoveryBound,
-                // The recorded verdict above is the retry loop's
-                // "already-attempted" on the dominant path; the re-read runtime
-                // state is what the operator-facing sentence should describe.
+                // Re-read runtime state for the operator-facing sentence so a
+                // concurrent or later blocker can refine the recorded verdict.
                 currentSkipReason: pinnedCurrentSkipReason,
                 now: evaluatedAtMs,
             });

package/dist/lib/schemas.d.ts

@@ -71,6 +71,10 @@ export declare const PluginConfigSchema: z.ZodObject<{
     preemptiveQuotaRemainingPercent5h: z.ZodOptional<z.ZodNumber>;
     preemptiveQuotaRemainingPercent7d: z.ZodOptional<z.ZodNumber>;
     preemptiveQuotaMaxDeferralMs: z.ZodOptional<z.ZodNumber>;
+    contextBudgetGuardEnabled: z.ZodOptional<z.ZodBoolean>;
+    contextBudgetGuardSoftPercent: z.ZodOptional<z.ZodNumber>;
+    contextBudgetGuardHardPercent: z.ZodOptional<z.ZodNumber>;
+    contextBudgetGuardModelWindowOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     routingMutex: z.ZodOptional<z.ZodEnum<{
         enabled: "enabled";
         legacy: "legacy";

package/dist/lib/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../lib/schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../lib/schemas.ts"],"names":[],"mappings":"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"}

package/dist/lib/schemas.js

@@ -76,6 +76,16 @@ export const PluginConfigSchema = z.object({
     preemptiveQuotaRemainingPercent5h: z.number().min(0).max(100).optional(),
     preemptiveQuotaRemainingPercent7d: z.number().min(0).max(100).optional(),
     preemptiveQuotaMaxDeferralMs: z.number().min(1_000).optional(),
+    contextBudgetGuardEnabled: z.boolean().optional(),
+    contextBudgetGuardSoftPercent: z.number().min(0).max(100).optional(),
+    // Floor of 10, not 0: a hard threshold at 0 is satisfied by every recorded
+    // snapshot, so it would pause every session from its first turn. A value
+    // below the floor is dropped by the per-field sanitizer and the default (69)
+    // applies.
+    contextBudgetGuardHardPercent: z.number().min(10).max(100).optional(),
+    contextBudgetGuardModelWindowOverrides: z
+        .record(z.string(), z.number().positive())
+        .optional(),
     routingMutex: z.enum(["enabled", "legacy"]).optional(),
     schedulingStrategy: z.enum(["hybrid", "sequential"]).optional(),
 });

package/dist/lib/synthetic-response.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared builder for locally-answered Responses API replies.
+ *
+ * Both the reactive context-overflow handler (`lib/context-overflow.ts`) and
+ * the proactive context budget guard (`lib/context-budget-response.ts`) need
+ * to hand the caller a plugin-authored notice instead of forwarding to
+ * upstream, in the exact SSE dialect the Codex CLI / Responses client
+ * expects. Extracted here so both answer with one audited SSE shape rather
+ * than two independently-maintained copies of it.
+ */
+export interface SyntheticSseResponseOptions {
+    /** Model id to echo back in the synthetic response, or "unknown". */
+    model: string;
+    /** Plain-text notice shown to the user as the assistant's message. */
+    message: string;
+    /** Distinguishes id prefixes across call sites, e.g. "overflow", "context_budget_pause". */
+    idPrefix: string;
+    /** Value for the `X-Codex-Plugin-Error-Type` response header. */
+    errorType: string;
+}
+/**
+ * Build a synthetic OpenAI Responses API SSE stream carrying a single
+ * assistant text message, then a terminal `response.completed`.
+ *
+ * Emits `response.*` events — the dialect the Codex CLI client and this
+ * package's own `convertSseToJson` parser speak, not the Anthropic Messages
+ * API dialect. Returns 200 OK so the host session never locks on a 4xx for a
+ * notice the plugin itself generated.
+ */
+export declare function createSyntheticSseResponse(options: SyntheticSseResponseOptions): Response;
+//# sourceMappingURL=synthetic-response.d.ts.map

package/dist/lib/synthetic-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic-response.d.ts","sourceRoot":"","sources":["../../lib/synthetic-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,2BAA2B;IAC3C,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,2BAA2B,GAClC,QAAQ,CA+DV"}