codex-multi-auth 2.9.2 → 2.11.0

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

@@ -0,0 +1,130 @@
+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",
+    // GPT-6 Astra published two different numbers on day one: 1.05M for the API
+    // surface and 272K as the Codex context. This wrapper talks to the Codex
+    // backend, and the same split is what the v2.5.0 notes warn about — so no
+    // estimate is entered here. `gpt-daybreak-red-latest` is the one model whose
+    // upstream catalog entry pins `context_window` and `max_context_window` to
+    // the same 372000, but that is the Codex picker's number rather than a
+    // measured ceiling for this transport, so it stays unestimated too. Set
+    // `contextBudgetGuardModelWindowOverrides` once you know your real ceiling.
+    "gpt-6-astra",
+    "gpt-6-astra-aeon",
+    "gpt-daybreak-blue-latest",
+    "gpt-daybreak-red-latest",
+];
+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"}

package/dist/lib/context-overflow.js

@@ -6,6 +6,7 @@
  * This prevents the host session from getting locked on 400 errors.
  */
 import { logDebug } from "./logger.js";
+import { createSyntheticSseResponse } from "./synthetic-response.js";
 /**
  * Error patterns that indicate context overflow
  */
@@ -54,67 +55,11 @@ Alternatively, you can switch to a model with a larger context window.`;
  * (recovery-01). Returns 200 OK so the host session does not lock on the 400.
  */
 export function createContextOverflowResponse(model = "unknown") {
-    const messageId = `msg_synthetic_overflow_${Date.now()}_${Math.random()
-        .toString(36)
-        .slice(2, 8)}`;
-    const responseId = `resp_synthetic_overflow_${Date.now()}_${Math.random()
-        .toString(36)
-        .slice(2, 8)}`;
-    const events = [];
-    const push = (type, payload) => {
-        events.push(`event: ${type}\ndata: ${JSON.stringify({ type, ...payload })}\n\n`);
-    };
-    const baseResponse = {
-        id: responseId,
-        object: "response",
+    return createSyntheticSseResponse({
         model,
-    };
-    // response.created
-    push("response.created", { response: { ...baseResponse, status: "in_progress" } });
-    // output item (assistant message) added
-    push("response.output_item.added", {
-        output_index: 0,
-        item: {
-            id: messageId,
-            type: "message",
-            role: "assistant",
-            content: [],
-        },
-    });
-    // streamed text + its terminal "done" carrying the final canonical text
-    push("response.output_text.delta", {
-        output_index: 0,
-        content_index: 0,
-        delta: CONTEXT_OVERFLOW_MESSAGE,
-    });
-    push("response.output_text.done", {
-        output_index: 0,
-        content_index: 0,
-        text: CONTEXT_OVERFLOW_MESSAGE,
-    });
-    // terminal response.completed with the full output array
-    push("response.completed", {
-        response: {
-            ...baseResponse,
-            status: "completed",
-            output: [
-                {
-                    id: messageId,
-                    type: "message",
-                    role: "assistant",
-                    content: [{ type: "output_text", text: CONTEXT_OVERFLOW_MESSAGE }],
-                },
-            ],
-            usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
-        },
-    });
-    return new Response(events.join(""), {
-        status: 200,
-        headers: {
-            "Content-Type": "text/event-stream",
-            "X-Codex-Plugin-Synthetic": "true",
-            "X-Codex-Plugin-Error-Type": "context_overflow",
-        },
+        message: CONTEXT_OVERFLOW_MESSAGE,
+        idPrefix: "synthetic_overflow",
+        errorType: "context_overflow",
     });
 }
 /**

package/dist/lib/model-capability-matrix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-capability-matrix.d.ts","sourceRoot":"","sources":["../../lib/model-capability-matrix.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAGN,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAEN,KAAK,wBAAwB,EAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACX,wBAAwB,EACxB,qBAAqB,EACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxE,MAAM,WAAW,0BAA0B;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,iBAAiB,CAAC;IAChC,sBAAsB,EAAE,oBAAoB,CAAC;IAC7C,yBAAyB,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3D,YAAY,EAAE,iBAAiB,CAAC;IAChC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,0BAA0B,EAAE,CAAC;CACtC;AAsBD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC/C,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,qBAAqB,CAiFxB"}
+{"version":3,"file":"model-capability-matrix.d.ts","sourceRoot":"","sources":["../../lib/model-capability-matrix.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAGN,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAEN,KAAK,wBAAwB,EAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACX,wBAAwB,EACxB,qBAAqB,EACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxE,MAAM,WAAW,0BAA0B;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,iBAAiB,CAAC;IAChC,sBAAsB,EAAE,oBAAoB,CAAC;IAC7C,yBAAyB,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3D,YAAY,EAAE,iBAAiB,CAAC;IAChC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,0BAA0B,EAAE,CAAC;CACtC;AAsBD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC/C,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,qBAAqB,CAyFxB"}

package/dist/lib/model-capability-matrix.js

@@ -35,7 +35,15 @@ export function buildModelCapabilityMatrix(input) {
         });
         const entitlementKeys = [accountKey, entitlementKey];
         for (const model of models) {
-            const profile = MODEL_PROFILES[model] ?? MODEL_PROFILES[resolveNormalizedModel(model)];
+            // `Object.hasOwn` before the index: `models` comes from `--model` on
+            // the CLI, so `constructor` and friends reach this lookup and a bare
+            // index returns the matching `Object.prototype` member. It is truthy,
+            // so the `!profile` guard passes it through and the matrix emits a row
+            // whose normalizedModel, promptFamily and capabilities are all
+            // undefined.
+            const profile = Object.hasOwn(MODEL_PROFILES, model)
+                ? MODEL_PROFILES[model]
+                : MODEL_PROFILES[resolveNormalizedModel(model)];
             if (!profile)
                 continue;
             const entitlement = getEntitlementBlock(input.entitlements, entitlementKeys, profile.normalizedModel, now);

package/dist/lib/request/error-classification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-classification.d.ts","sourceRoot":"","sources":["../../../lib/request/error-classification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,gBAAgB;IACzB,aAAa,EAAE,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACvB;AAED,sGAAsG;AACtG,eAAO,MAAM,oCAAoC,6CAA6C,CAAC;AAQ/F,eAAO,MAAM,wCAAwC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAoB7E,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACzC,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sCAAsC;IACtD,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,+BAA+B,EAAE,OAAO,CAAC;IACzC,iCAAiC,EAAE,OAAO,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACvC;AA0CD,wBAAgB,oCAAoC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBzF;AAED,sGAAsG;AACtG,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQ3F;AAED,wBAAgB,4BAA4B,CAC3C,SAAS,EAAE,OAAO,GAChB,yBAAyB,CAqD3B;AAED,wBAAgB,oCAAoC,CACnD,OAAO,EAAE,sCAAsC,GAC7C,MAAM,GAAG,SAAS,CAgCpB;AAED;;GAEG;AACH,wBAAgB,uCAAuC,CACtD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,OAAO,GAChB,OAAO,CAgBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACrB,OAAO,CAoDT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAmB1E"}
+{"version":3,"file":"error-classification.d.ts","sourceRoot":"","sources":["../../../lib/request/error-classification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,gBAAgB;IACzB,aAAa,EAAE,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACvB;AAED,sGAAsG;AACtG,eAAO,MAAM,oCAAoC,6CAA6C,CAAC;AAQ/F,eAAO,MAAM,wCAAwC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAoD7E,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACzC,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sCAAsC;IACtD,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,+BAA+B,EAAE,OAAO,CAAC;IACzC,iCAAiC,EAAE,OAAO,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACvC;AAiDD,wBAAgB,oCAAoC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBzF;AAED,sGAAsG;AACtG,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQ3F;AAED,wBAAgB,4BAA4B,CAC3C,SAAS,EAAE,OAAO,GAChB,yBAAyB,CAqD3B;AAED,wBAAgB,oCAAoC,CACnD,OAAO,EAAE,sCAAsC,GAC7C,MAAM,GAAG,SAAS,CAkCpB;AAED;;GAEG;AACH,wBAAgB,uCAAuC,CACtD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,OAAO,GAChB,OAAO,CAgBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACrB,OAAO,CAoDT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAmB1E"}