codex-multi-auth 2.9.1 → 2.10.0

package/dist/lib/config.js

@@ -171,6 +171,10 @@ export const DEFAULT_PLUGIN_CONFIG = {
     preemptiveQuotaRemainingPercent5h: 5,
     preemptiveQuotaRemainingPercent7d: 5,
     preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
+    contextBudgetGuardEnabled: false,
+    contextBudgetGuardSoftPercent: 65,
+    contextBudgetGuardHardPercent: 69,
+    contextBudgetGuardModelWindowOverrides: {},
     routingMutex: "legacy",
     schedulingStrategy: "hybrid",
 };
@@ -834,6 +838,14 @@ function resolveNumberSetting(envName, configValue, defaultValue, options) {
         logConfigWarnOnce(`Ignoring invalid numeric env ${envName}. Expected a finite number.`);
     }
     const candidate = envValue ?? configValue ?? defaultValue;
+    // Math.max/Math.min propagate NaN, so a non-finite candidate would be
+    // returned as-is and every threshold comparison against it reads false --
+    // a setting that silently disables whatever it gates. parseNumberEnv already
+    // rejects non-finite env values and zod rejects NaN on the config field, so
+    // this is a boundary guard for the ~20 settings that share this helper
+    // rather than a reachable path through loadPluginConfig.
+    if (!Number.isFinite(candidate))
+        return defaultValue;
     const min = options?.min ?? Number.NEGATIVE_INFINITY;
     const max = options?.max ?? Number.POSITIVE_INFINITY;
     return Math.max(min, Math.min(max, candidate));
@@ -1295,6 +1307,62 @@ export function getPreemptiveQuotaRemainingPercent7d(pluginConfig) {
 export function getPreemptiveQuotaMaxDeferralMs(pluginConfig) {
     return resolveNumberSetting("CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS", pluginConfig.preemptiveQuotaMaxDeferralMs, 2 * 60 * 60_000, { min: 1_000 });
 }
+/**
+ * Whether the (experimental, opt-in) context budget guard is enabled.
+ *
+ * Ships disabled: pausing a session before it hits the context window is a
+ * staged behavior change, not a default-on safety net like preemptive quota
+ * deferral, so an explicit opt-in is required.
+ */
+export function getContextBudgetGuardEnabled(pluginConfig) {
+    return resolveBooleanSetting("CODEX_AUTH_CONTEXT_BUDGET_GUARD_ENABLED", pluginConfig.contextBudgetGuardEnabled, false);
+}
+/** Percent of the effective context window at which the guard's non-blocking advisory fires. */
+export function getContextBudgetGuardSoftPercent(pluginConfig) {
+    return resolveNumberSetting("CODEX_AUTH_CONTEXT_BUDGET_SOFT_PCT", pluginConfig.contextBudgetGuardSoftPercent, 65, { min: 0, max: 100 });
+}
+/**
+ * Percent of the effective context window at which the guard pauses the next
+ * request.
+ *
+ * Floored at 10, not 0. `resolveNumberSetting` clamps out-of-range values
+ * instead of rejecting them, so a configured (or env-supplied) `0` would be a
+ * legal threshold that every recorded snapshot clears — pausing every session
+ * from its first turn on. The guard applies the same floor in `configure()`
+ * so a directly constructed instance cannot be set below it either.
+ */
+export function getContextBudgetGuardHardPercent(pluginConfig) {
+    return resolveNumberSetting("CODEX_AUTH_CONTEXT_BUDGET_HARD_PCT", pluginConfig.contextBudgetGuardHardPercent, 69, { min: 10, max: 100 });
+}
+/**
+ * User-supplied context-window sizes, keyed by normalized model id, that
+ * always take priority over this package's own best-effort estimates (see
+ * `lib/context-budget/model-context-windows.ts`). Settings-only: there is no
+ * environment override, the same as `unsupportedCodexFallbackChain`, since a
+ * per-model token count is not a reasonable single env var.
+ */
+export function getContextBudgetGuardModelWindowOverrides(pluginConfig) {
+    const overrides = pluginConfig.contextBudgetGuardModelWindowOverrides;
+    if (!overrides || typeof overrides !== "object") {
+        return {};
+    }
+    const normalized = {};
+    for (const [rawModel, rawValue] of Object.entries(overrides)) {
+        const model = rawModel.trim().toLowerCase();
+        if (!model)
+            continue;
+        if (typeof rawValue !== "number" || !Number.isFinite(rawValue))
+            continue;
+        // Floor first: the schema accepts any positive number, so a sub-1 value
+        // passes a `rawValue > 0` check and then floors to 0, which is stored as
+        // a window of zero tokens and silently ignored downstream.
+        const tokens = Math.floor(rawValue);
+        if (tokens <= 0)
+            continue;
+        normalized[model] = tokens;
+    }
+    return normalized;
+}
 const ROUTING_MUTEX_MODES = new Set(["enabled", "legacy"]);
 /**
  * Resolve the routing-mutex mode (PR-N / R4).
@@ -1649,6 +1717,26 @@ const CONFIG_EXPLAIN_ENTRIES = [
         envNames: ["CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS"],
         getValue: getPreemptiveQuotaMaxDeferralMs,
     },
+    {
+        key: "contextBudgetGuardEnabled",
+        envNames: ["CODEX_AUTH_CONTEXT_BUDGET_GUARD_ENABLED"],
+        getValue: getContextBudgetGuardEnabled,
+    },
+    {
+        key: "contextBudgetGuardSoftPercent",
+        envNames: ["CODEX_AUTH_CONTEXT_BUDGET_SOFT_PCT"],
+        getValue: getContextBudgetGuardSoftPercent,
+    },
+    {
+        key: "contextBudgetGuardHardPercent",
+        envNames: ["CODEX_AUTH_CONTEXT_BUDGET_HARD_PCT"],
+        getValue: getContextBudgetGuardHardPercent,
+    },
+    {
+        key: "contextBudgetGuardModelWindowOverrides",
+        envNames: [],
+        getValue: getContextBudgetGuardModelWindowOverrides,
+    },
     // config-01/config-07: these three live settings were missing from the explain
     // report, so `config explain` silently under-reported the effective config. A
     // parity test (test/config-explain.test.ts) now guards this class of drift.

package/dist/lib/context-budget/model-context-windows.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Routable models this guard consciously does not estimate a window for.
+ * `getEffectiveContextWindow` returns `null` for these absent an override,
+ * and the guard treats `null` as "cannot evaluate; skip" — never a guessed
+ * percentage. The 5.6 family ships with materially different per-tier
+ * behavior (see the v2.5.0 release notes) closely enough to launch that no
+ * estimate here has been reviewed for it yet.
+ */
+export declare const UNESTIMATED_ROUTABLE_MODELS: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"];
+export interface EffectiveContextWindow {
+    tokens: number;
+    source: "override" | "estimate";
+}
+/**
+ * Resolve the context-window size to evaluate a session's budget against.
+ *
+ * Precedence: an explicit override always wins, even for a model this file
+ * has never heard of — the whole point of the override setting is to let a
+ * user correct or extend past this file's guesses. Failing that, fall back
+ * to the estimate table. Returns `null` when neither source has a value, so
+ * the guard can no-op rather than evaluate against a fabricated number.
+ */
+export declare function getEffectiveContextWindow(model: string | null | undefined, overrides: Record<string, number> | undefined): EffectiveContextWindow | null;
+export declare function listEstimatedModelContextWindows(): Record<string, number>;
+//# sourceMappingURL=model-context-windows.d.ts.map

package/dist/lib/context-budget/model-context-windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-context-windows.d.ts","sourceRoot":"","sources":["../../../lib/context-budget/model-context-windows.ts"],"names":[],"mappings":"AAyCA;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,2DAI9B,CAAC;AAgCX,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,sBAAsB,GAAG,IAAI,CA0B/B;AAED,wBAAgB,gCAAgC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE"}

package/dist/lib/context-budget/model-context-windows.js

@@ -0,0 +1,118 @@
+import { getNormalizedModel } from "../request/helpers/model-map.js";
+/**
+ * Context-window size estimates for the Context Budget Guard.
+ *
+ * Unlike `lib/usage/pricing.ts`, the numbers below are NOT published,
+ * contractual facts. Per `docs/releases/v2.5.0.md` ("Where the model facts
+ * came from"), the context window OpenAI's published API docs advertise is
+ * for the API surface, not the ChatGPT Codex backend this wrapper actually
+ * talks to — and the docs pages don't even agree with each other. Treating a
+ * hardcoded number here as ground truth would repeat that exact mistake for
+ * a safety feature, which is worse than not shipping the feature at all.
+ *
+ * So this table is a fallback starting point ONLY. `getEffectiveContextWindow`
+ * always prefers a caller-supplied override (from
+ * `contextBudgetGuardModelWindowOverrides`, the setting a user fills in once
+ * they know their real ceiling) over anything listed here.
+ */
+/**
+ * Best-effort estimates, in tokens. Deliberately conservative: an estimate
+ * that is too LOW makes the guard fire early (annoying, safe); an estimate
+ * that is too HIGH makes the guard fire late or never (silent, unsafe). When
+ * in doubt about a model's real ceiling, leave it out of this table and add
+ * it to UNESTIMATED_ROUTABLE_MODELS instead.
+ */
+const ESTIMATED_MODEL_CONTEXT_WINDOWS = {
+    "gpt-5.1": 260_000,
+    "gpt-5.2": 260_000,
+    "gpt-5.2-pro": 260_000,
+    "gpt-5.3-codex": 260_000,
+    "gpt-5.4": 260_000,
+    "gpt-5.4-mini": 260_000,
+    "gpt-5.4-nano": 260_000,
+    "gpt-5.4-pro": 260_000,
+    "gpt-5.5": 260_000,
+    "gpt-5.5-pro": 260_000,
+    "gpt-5-mini": 260_000,
+    "gpt-5-nano": 260_000,
+};
+/**
+ * Routable models this guard consciously does not estimate a window for.
+ * `getEffectiveContextWindow` returns `null` for these absent an override,
+ * and the guard treats `null` as "cannot evaluate; skip" — never a guessed
+ * percentage. The 5.6 family ships with materially different per-tier
+ * behavior (see the v2.5.0 release notes) closely enough to launch that no
+ * estimate here has been reviewed for it yet.
+ */
+export const UNESTIMATED_ROUTABLE_MODELS = [
+    "gpt-5.6-sol",
+    "gpt-5.6-terra",
+    "gpt-5.6-luna",
+];
+function normalizeModelName(model) {
+    const trimmed = model?.trim().toLowerCase();
+    return trimmed && trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Model ids to try, in order, against the override map and the estimate table.
+ *
+ * The guard is fed the model string exactly as the client sent it: the
+ * rotation proxy is a pass-through and `buildResponsesRequestContext` copies
+ * `body.model` verbatim. That raw string is very often NOT a key of this
+ * file's table — Codex CLI's own default is `gpt-5-codex`, and every
+ * reasoning-suffixed alias (`gpt-5.3-codex-high`, …) is an alias-map entry
+ * rather than a catalog model. Looking up only the raw string made the guard
+ * silently return "no window, skip" for the most common model in the product.
+ *
+ * So: try the raw (lowercased) string first, so a user override keyed exactly
+ * the way they type the model still wins, then the catalog's canonical id for
+ * it. `getNormalizedModel` is deliberately the exact/alias-only resolver —
+ * `resolveNormalizedModel` falls back to `DEFAULT_MODEL` for anything it does
+ * not recognize, which would hand an unknown model gpt-5.5's window and
+ * evaluate a real session against a fabricated number.
+ */
+function windowLookupCandidates(model) {
+    const raw = normalizeModelName(model);
+    if (!raw)
+        return [];
+    const canonical = normalizeModelName(getNormalizedModel(raw));
+    return canonical && canonical !== raw ? [raw, canonical] : [raw];
+}
+/**
+ * Resolve the context-window size to evaluate a session's budget against.
+ *
+ * Precedence: an explicit override always wins, even for a model this file
+ * has never heard of — the whole point of the override setting is to let a
+ * user correct or extend past this file's guesses. Failing that, fall back
+ * to the estimate table. Returns `null` when neither source has a value, so
+ * the guard can no-op rather than evaluate against a fabricated number.
+ */
+export function getEffectiveContextWindow(model, overrides) {
+    const candidates = windowLookupCandidates(model);
+    if (candidates.length === 0)
+        return null;
+    for (const candidate of candidates) {
+        const override = overrides?.[candidate];
+        if (typeof override !== "number" || !Number.isFinite(override))
+            continue;
+        // Floor BEFORE the positivity check, not after. Checking `override > 0`
+        // on the raw value admits anything in (0, 1), which then floors to 0 and
+        // returns a zero-token window -- breaking this function's contract that a
+        // window it cannot resolve comes back as null, and handing any caller
+        // that trusts it a division by zero.
+        const tokens = Math.floor(override);
+        if (tokens > 0) {
+            return { tokens, source: "override" };
+        }
+    }
+    for (const candidate of candidates) {
+        const estimate = ESTIMATED_MODEL_CONTEXT_WINDOWS[candidate];
+        if (typeof estimate === "number") {
+            return { tokens: estimate, source: "estimate" };
+        }
+    }
+    return null;
+}
+export function listEstimatedModelContextWindows() {
+    return { ...ESTIMATED_MODEL_CONTEXT_WINDOWS };
+}

package/dist/lib/context-budget-guard.d.ts

@@ -0,0 +1,100 @@
+export interface ContextBudgetSnapshot {
+    model: string;
+    /**
+     * Tokens the NEXT turn on this session is expected to resend as context:
+     * this turn's `input_tokens` plus the part of its output that becomes
+     * conversation history. Deliberately NOT `total_tokens`, which also counts
+     * `reasoning_tokens` that the Responses API drops rather than resends —
+     * charging those against the window inflates every measurement by this
+     * turn's thinking budget and fires the guard early on long-reasoning turns.
+     */
+    contextTokens: number;
+    updatedAt: number;
+}
+export interface ContextBudgetOptions {
+    enabled?: boolean;
+    softPercent?: number;
+    hardPercent?: number;
+    modelWindowOverrides?: Record<string, number>;
+}
+interface ContextBudgetPressure {
+    percent: number;
+    contextTokens: number;
+    windowTokens: number;
+    windowSource: "override" | "estimate";
+    model: string;
+}
+export type ContextBudgetAdvisory = {
+    level: "ok";
+} | ({
+    level: "soft";
+} & ContextBudgetPressure) | ({
+    level: "hard";
+} & ContextBudgetPressure);
+/**
+ * Tracks how full each session's context window is and decides, before the
+ * NEXT request on that session goes out, whether to nudge (soft) or pause
+ * (hard) the caller.
+ *
+ * Deliberately shaped like `PreemptiveQuotaScheduler`
+ * (`lib/preemptive-quota-scheduler.ts`): a per-key `Map` snapshot, a
+ * `configure()`/decision-getter split, and a lazy `prune()` on the same
+ * cadence. Same reason in both places — the decision needs to survive
+ * across the request that observed the usage and the next request that
+ * asks "are we still OK," and a scheduled sweep keeps memory bounded
+ * without a dedicated timer.
+ */
+export declare class ContextBudgetGuard {
+    private readonly snapshots;
+    private enabled;
+    private softPercent;
+    private hardPercent;
+    private modelWindowOverrides;
+    private lastPruneAt;
+    constructor(options?: ContextBudgetOptions);
+    configure(options?: ContextBudgetOptions): void;
+    private maybePrune;
+    /**
+     * Record the latest known context size for a session, from that turn's usage.
+     *
+     * No-ops while disabled. The call sites sit on the hot path of every
+     * forwarded Responses turn, so a default-off install must not pay for a
+     * per-session map it will never read.
+     */
+    update(key: string, snapshot: ContextBudgetSnapshot): void;
+    /**
+     * Evaluate before forwarding the NEXT request on this session key.
+     *
+     * `requestModel` is the model that request will use, and it is what the
+     * window is resolved from -- NOT the model of the last recorded turn. The
+     * two differ whenever a session switches models, and then the snapshot's
+     * model is the wrong denominator: a session carrying 205k tokens is 79% of
+     * a 260k window and a fifth of a 1M one. Using the stale model also let
+     * the guard pause a request for a model it deliberately refuses to
+     * estimate, and print that stale model's name in the notice. Falls back to
+     * the snapshot's model only when the request declares none.
+     */
+    getAdvisory(key: string, now?: number, requestModel?: string | null): ContextBudgetAdvisory;
+    /** Drop sessions untouched for a while so the map does not grow unbounded. */
+    prune(now?: number): number;
+    /** Forget a single session's tracked usage, e.g. once it has visibly compacted. */
+    forget(key: string): void;
+    /**
+     * Call immediately after emitting a hard pause for `key`.
+     *
+     * The pause is synthetic: it short-circuits before the request is forwarded,
+     * so `update()` never runs for it and the recorded usage can never fall on
+     * its own. Left in place, the first crossing of the hard threshold would
+     * block that session forever — including the `/compact` turn the pause
+     * message tells the user to run, which travels on the same session key.
+     *
+     * Dropping the snapshot makes the pause one-shot per measurement: the next
+     * request is forwarded and re-measures. A session that really did compact
+     * comes back under the threshold and stays quiet; one that did not gets
+     * paused again on the turn after, so the warning still repeats while the
+     * session is over budget, without ever becoming a dead end.
+     */
+    noteHardPauseEmitted(key: string): void;
+}
+export {};
+//# sourceMappingURL=context-budget-guard.d.ts.map

package/dist/lib/context-budget-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-guard.d.ts","sourceRoot":"","sources":["../../lib/context-budget-guard.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED,UAAU,qBAAqB;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,qBAAqB,GAC9B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,CAAC,GAC3C,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,CAAC,CAAC;AAuB/C;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,WAAW,CAAK;gBAEZ,OAAO,GAAE,oBAAyB;IAI9C,SAAS,CAAC,OAAO,GAAE,oBAAyB,GAAG,IAAI;IAgCnD,OAAO,CAAC,UAAU;IAMlB;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAmB1D;;;;;;;;;;;OAWG;IACH,WAAW,CACV,GAAG,EAAE,MAAM,EACX,GAAG,SAAa,EAChB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,qBAAqB;IAuCxB,8EAA8E;IAC9E,KAAK,CAAC,GAAG,SAAa,GAAG,MAAM;IAW/B,mFAAmF;IACnF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGvC"}

package/dist/lib/context-budget-guard.js

@@ -0,0 +1,183 @@
+import { getEffectiveContextWindow } from "./context-budget/model-context-windows.js";
+const DEFAULT_SOFT_PERCENT = 65;
+const DEFAULT_HARD_PERCENT = 69;
+/**
+ * Lowest hard threshold that can describe a real budget.
+ *
+ * `getContextBudgetGuardHardPercent` clamps rather than rejects (that is what
+ * every other numeric setting does), so without a floor a configured `0` is a
+ * legal value that makes `percent >= hardPercent` true for every snapshot —
+ * every session pauses from its first recorded turn onward. Anything under
+ * 10% of a window is that same failure in slower motion, so clamp up to a
+ * value that at least can't fire on turn one of a normal session.
+ */
+const MIN_HARD_PERCENT = 10;
+/** Sessions idle longer than this are dropped on the next prune sweep. */
+const SESSION_TTL_MS = 6 * 60 * 60_000;
+const PRUNE_INTERVAL_MS = 60_000;
+function clampInt(value, min, max) {
+    return Math.max(min, Math.min(max, Math.floor(value)));
+}
+/**
+ * Tracks how full each session's context window is and decides, before the
+ * NEXT request on that session goes out, whether to nudge (soft) or pause
+ * (hard) the caller.
+ *
+ * Deliberately shaped like `PreemptiveQuotaScheduler`
+ * (`lib/preemptive-quota-scheduler.ts`): a per-key `Map` snapshot, a
+ * `configure()`/decision-getter split, and a lazy `prune()` on the same
+ * cadence. Same reason in both places — the decision needs to survive
+ * across the request that observed the usage and the next request that
+ * asks "are we still OK," and a scheduled sweep keeps memory bounded
+ * without a dedicated timer.
+ */
+export class ContextBudgetGuard {
+    snapshots = new Map();
+    enabled = false;
+    softPercent = DEFAULT_SOFT_PERCENT;
+    hardPercent = DEFAULT_HARD_PERCENT;
+    modelWindowOverrides;
+    lastPruneAt = 0;
+    constructor(options = {}) {
+        this.configure(options);
+    }
+    configure(options = {}) {
+        if (typeof options.enabled === "boolean") {
+            // Turning the guard off must also drop what it already tracked, or a
+            // disable/re-enable cycle re-evaluates against usage measured under
+            // the old settings and can pause a session on its first request back.
+            if (!options.enabled && this.enabled) {
+                this.snapshots.clear();
+            }
+            this.enabled = options.enabled;
+        }
+        if (typeof options.softPercent === "number" && Number.isFinite(options.softPercent)) {
+            this.softPercent = clampInt(options.softPercent, 0, 100);
+        }
+        if (typeof options.hardPercent === "number" && Number.isFinite(options.hardPercent)) {
+            this.hardPercent = clampInt(options.hardPercent, MIN_HARD_PERCENT, 100);
+        }
+        // A misconfigured soft >= hard must degrade safely (guard fires later
+        // than intended) rather than throw or produce a nonsensical "hard but
+        // not soft" state. Never silently widen hard to fix it — narrowing soft
+        // is the change least likely to surprise whoever set hard deliberately.
+        if (this.softPercent >= this.hardPercent) {
+            this.softPercent = Math.max(0, this.hardPercent - 1);
+        }
+        if (options.modelWindowOverrides) {
+            this.modelWindowOverrides = options.modelWindowOverrides;
+        }
+    }
+    maybePrune(now) {
+        if (now - this.lastPruneAt < PRUNE_INTERVAL_MS)
+            return;
+        this.prune(now);
+        this.lastPruneAt = now;
+    }
+    /**
+     * Record the latest known context size for a session, from that turn's usage.
+     *
+     * No-ops while disabled. The call sites sit on the hot path of every
+     * forwarded Responses turn, so a default-off install must not pay for a
+     * per-session map it will never read.
+     */
+    update(key, snapshot) {
+        if (!this.enabled || !key)
+            return;
+        // Both production call sites source contextTokens from
+        // lib/usage/usage-extraction.ts, whose nonNegativeInteger already returns
+        // 0 for anything non-finite, so this is a boundary guard rather than a
+        // reachable path today. It is here because percent is a division by the
+        // window: a non-finite count would put `Infinity%` in the pause notice a
+        // user reads, and every threshold comparison against NaN is false, which
+        // disables the guard silently.
+        if (!Number.isFinite(snapshot.contextTokens) ||
+            snapshot.contextTokens < 0) {
+            return;
+        }
+        this.maybePrune(snapshot.updatedAt || Date.now());
+        this.snapshots.set(key, snapshot);
+    }
+    /**
+     * Evaluate before forwarding the NEXT request on this session key.
+     *
+     * `requestModel` is the model that request will use, and it is what the
+     * window is resolved from -- NOT the model of the last recorded turn. The
+     * two differ whenever a session switches models, and then the snapshot's
+     * model is the wrong denominator: a session carrying 205k tokens is 79% of
+     * a 260k window and a fifth of a 1M one. Using the stale model also let
+     * the guard pause a request for a model it deliberately refuses to
+     * estimate, and print that stale model's name in the notice. Falls back to
+     * the snapshot's model only when the request declares none.
+     */
+    getAdvisory(key, now = Date.now(), requestModel) {
+        this.maybePrune(now);
+        if (!this.enabled || !key)
+            return { level: "ok" };
+        const snapshot = this.snapshots.get(key);
+        if (!snapshot)
+            return { level: "ok" };
+        const trimmedRequestModel = requestModel?.trim();
+        const evaluatedModel = trimmedRequestModel && trimmedRequestModel.length > 0
+            ? trimmedRequestModel
+            : snapshot.model;
+        const window = getEffectiveContextWindow(evaluatedModel, this.modelWindowOverrides);
+        if (!window || window.tokens <= 0)
+            return { level: "ok" };
+        const percent = (snapshot.contextTokens / window.tokens) * 100;
+        if (percent >= this.hardPercent) {
+            return {
+                level: "hard",
+                percent,
+                contextTokens: snapshot.contextTokens,
+                windowTokens: window.tokens,
+                windowSource: window.source,
+                model: evaluatedModel,
+            };
+        }
+        if (percent >= this.softPercent) {
+            return {
+                level: "soft",
+                percent,
+                contextTokens: snapshot.contextTokens,
+                windowTokens: window.tokens,
+                windowSource: window.source,
+                model: evaluatedModel,
+            };
+        }
+        return { level: "ok" };
+    }
+    /** Drop sessions untouched for a while so the map does not grow unbounded. */
+    prune(now = Date.now()) {
+        let removed = 0;
+        for (const [key, snapshot] of this.snapshots.entries()) {
+            if (now - snapshot.updatedAt > SESSION_TTL_MS) {
+                this.snapshots.delete(key);
+                removed += 1;
+            }
+        }
+        return removed;
+    }
+    /** Forget a single session's tracked usage, e.g. once it has visibly compacted. */
+    forget(key) {
+        this.snapshots.delete(key);
+    }
+    /**
+     * Call immediately after emitting a hard pause for `key`.
+     *
+     * The pause is synthetic: it short-circuits before the request is forwarded,
+     * so `update()` never runs for it and the recorded usage can never fall on
+     * its own. Left in place, the first crossing of the hard threshold would
+     * block that session forever — including the `/compact` turn the pause
+     * message tells the user to run, which travels on the same session key.
+     *
+     * Dropping the snapshot makes the pause one-shot per measurement: the next
+     * request is forwarded and re-measures. A session that really did compact
+     * comes back under the threshold and stays quiet; one that did not gets
+     * paused again on the turn after, so the warning still repeats while the
+     * session is over budget, without ever becoming a dead end.
+     */
+    noteHardPauseEmitted(key) {
+        this.snapshots.delete(key);
+    }
+}

package/dist/lib/context-budget-response.d.ts

@@ -0,0 +1,25 @@
+import type { ContextBudgetAdvisory } from "./context-budget-guard.js";
+/** Response header carrying the soft-threshold advisory, non-blocking. */
+export declare const CONTEXT_BUDGET_PERCENT_HEADER = "x-codex-context-budget-percent";
+/**
+ * Build the synthetic response returned in place of forwarding to upstream
+ * when the context budget guard's hard threshold has been reached.
+ *
+ * Same technique as `createContextOverflowResponse`: a 200 OK synthetic SSE
+ * reply so the host session never locks on an error for a notice the plugin
+ * itself generated — except this fires pre-flight, before the request that
+ * would overflow is ever sent, instead of reacting to the 400 after the
+ * fact.
+ */
+export declare function createContextBudgetPauseResponse(advisory: Extract<ContextBudgetAdvisory, {
+    level: "hard";
+}>): Response;
+/**
+ * Non-blocking header for the soft threshold, added to the real forwarded
+ * response next to the existing `x-codex-*-used-percent` quota headers.
+ * Consumed by `codex-multi-auth status` / the statusline, not by the model.
+ */
+export declare function buildContextBudgetHeaders(advisory: Extract<ContextBudgetAdvisory, {
+    level: "soft" | "hard";
+}>): Record<string, string>;
+//# sourceMappingURL=context-budget-response.d.ts.map

package/dist/lib/context-budget-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-response.d.ts","sourceRoot":"","sources":["../../lib/context-budget-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,mCAAmC,CAAC;AAgC9E;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAC/C,QAAQ,EAAE,OAAO,CAAC,qBAAqB,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GACzD,QAAQ,CAOV;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE,OAAO,CAAC,qBAAqB,EAAE;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC,GAClE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxB"}

package/dist/lib/context-budget-response.js

@@ -0,0 +1,57 @@
+import { createSyntheticSseResponse } from "./synthetic-response.js";
+/** Response header carrying the soft-threshold advisory, non-blocking. */
+export const CONTEXT_BUDGET_PERCENT_HEADER = "x-codex-context-budget-percent";
+function formatPercent(percent) {
+    return percent.toFixed(1);
+}
+/**
+ * The message shown to users when the context budget guard pauses a session
+ * at the hard threshold, before the request that would have pushed it over
+ * the model's window is even sent upstream.
+ *
+ * Deliberately echoes `lib/context-overflow.ts`'s CONTEXT_OVERFLOW_MESSAGE
+ * copy so the two related notices read as one family in a transcript,
+ * rather than as two unexplained different warnings.
+ */
+function buildPauseMessage(advisory) {
+    const windowNote = advisory.windowSource === "override"
+        ? "your configured window size"
+        : "an estimated window size (unverified — set `contextBudgetGuardModelWindowOverrides` if you know the real limit)";
+    return `[Plugin Notice] Context budget guard paused this session at ${formatPercent(advisory.percent)}% of ${windowNote} for \`${advisory.model}\`, before hitting the model's actual limit.
+
+Please use one of these commands to reduce context size:
+
+• **/compact** - Compress conversation history (recommended)
+• **/clear** - Start fresh with empty context
+• **/undo** - Remove recent messages
+
+Then retry your request. This pause clears itself automatically once your context usage drops back below the threshold.`;
+}
+/**
+ * Build the synthetic response returned in place of forwarding to upstream
+ * when the context budget guard's hard threshold has been reached.
+ *
+ * Same technique as `createContextOverflowResponse`: a 200 OK synthetic SSE
+ * reply so the host session never locks on an error for a notice the plugin
+ * itself generated — except this fires pre-flight, before the request that
+ * would overflow is ever sent, instead of reacting to the 400 after the
+ * fact.
+ */
+export function createContextBudgetPauseResponse(advisory) {
+    return createSyntheticSseResponse({
+        model: advisory.model,
+        message: buildPauseMessage(advisory),
+        idPrefix: "context_budget_pause",
+        errorType: "context_budget_pause",
+    });
+}
+/**
+ * Non-blocking header for the soft threshold, added to the real forwarded
+ * response next to the existing `x-codex-*-used-percent` quota headers.
+ * Consumed by `codex-multi-auth status` / the statusline, not by the model.
+ */
+export function buildContextBudgetHeaders(advisory) {
+    return {
+        [CONTEXT_BUDGET_PERCENT_HEADER]: formatPercent(advisory.percent),
+    };
+}

package/dist/lib/context-overflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-overflow.d.ts","sourceRoot":"","sources":["../../lib/context-overflow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiBH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMhF;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,GAAE,MAAkB,GAAG,QAAQ,CAsEjF;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,QAAQ,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAmBrE"}
+{"version":3,"file":"context-overflow.d.ts","sourceRoot":"","sources":["../../lib/context-overflow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMhF;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,GAAE,MAAkB,GAAG,QAAQ,CAOjF;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,QAAQ,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAmBrE"}