@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/server/responses/request-send-budget.ts

@@ -0,0 +1,259 @@
+import type { ResponsesRequestContext } from "./core-options";
+import { createRequestExecutionBudget, isRequestExecutionBudget } from "../../lib/request-execution-budget";
+import { chargeWorkflowSends, workflowSendCeilingReached } from "../../lib/workflow-budget";
+import { workflowRefusalResponse } from "../workflow-refusal";
+import type { AttemptRecoveryKind } from "../../usage/log";
+import { noteAttemptSend } from "../request-log";
+import { TRANSIENT_RETRY_MAX_ATTEMPTS } from "../../lib/upstream-retry";
+import type {
+  DispatchDecision,
+  DispatchIntent,
+  RequestExecutionBudget,
+  SendClass,
+  SingleUseDispatchPermit,
+} from "../../lib/request-execution-budget";
+
+/** Owns the shared request send counter and recovery permits. */
+export function createResponsesSendBudget(
+  requestContext: Pick<ResponsesRequestContext, "options" | "req" | "logCtx">,
+) {
+  const { options, req, logCtx } = requestContext;
+
+
+  // One transient-retry budget for the whole LOGICAL request, read ABOVE the passthrough branch
+  // so that branch shares it too. It used to be a local declared below, which put it in the
+  // temporal dead zone for the passthrough sends and left each recovery leg taking the helper's
+  // fresh default of 3. It is now a holder carried on options, so a combo child inherits the
+  // parent's spend instead of starting over per target -- both halves of the measured
+  // amplification in #4546.
+  const sendBudget = options.sendBudget ?? createRequestExecutionBudget();
+  // The root workflow is the user-visible task. A per-request cap cannot bound a fan-out that
+  // sends once per child seven hundred times, so every send charged to the request is charged
+  // to the root as well (#4546).
+  const workflowRootId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const noteTransientSends = (used: number): void => {
+    const charged = Math.max(0, used);
+    sendBudget.used += charged;
+    chargeWorkflowSends(workflowRootId, charged);
+  };
+  // Refused before any dispatch, and deliberately not by evicting the root's ledger entry:
+  // dropping the record to make room would hand the fan-out a fresh allowance, which is the
+  // laundering this ceiling exists to stop. The client is told the task needs a new grant
+  // rather than being given a synthetic upstream error.
+  if (workflowSendCeilingReached(workflowRootId)) {
+    // A log context exists here, unlike at HTTP admission, so the row this request writes is
+    // marked synthetic rather than reading as a request that vanished with zero sends.
+    return workflowRefusalResponse("workflow-sends-exhausted", logCtx, undefined, workflowRootId);
+  }
+  // No floor. Math.max(1, ...) meant an exhausted request still funded one send on every
+  // recovery leg, so a bounded per-leg allowance never became a bounded per-request one.
+  const remainingTransientSendBudget = (budget: number): number =>
+    isRequestExecutionBudget(sendBudget)
+      ? sendBudget.remainingBaseSends(budget)
+      : Math.max(0, budget - sendBudget.used);
+  // The adapter contract needs the full budget, not just the counter. options.sendBudget is
+  // typed as the narrow holder so a caller that predates this can still pass one, so narrow it
+  // once here rather than asserting at each adapter call site.
+  const adapterSendBudget = isRequestExecutionBudget(sendBudget) ? sendBudget : undefined;
+  /**
+   * Records an adapter's OWN inner retries against this attempt.
+   *
+   * Ordinal 1 is the send each call site already recorded through `noteRoutedAttemptSend`, so only
+   * the extra physical sends are added here and an adapter that does not retry internally
+   * leaves its log byte-for-byte as it was. Kiro reaches roughly eighteen sends per call and
+   * Cursor re-sends a whole turn, and both reported one; a count that cannot be observed
+   * cannot be pinned by a regression, which is why the instrumentation precedes the cap.
+   */
+  const noteAdapterPhysicalSend = (
+    inputTokens: number | undefined,
+    send: { ordinal: number; recovery?: AttemptRecoveryKind },
+  ): void => {
+    if (send.ordinal <= 1) return;
+    noteAttemptSend(logCtx.activeAttempt, inputTokens, send.recovery);
+  };
+  const sendBudgetExhausted = (): boolean =>
+    remainingTransientSendBudget(TRANSIENT_RETRY_MAX_ATTEMPTS) === 0;
+  /**
+   * A credential hop reserves the send its own replay will make, and that replay is a recovery
+   * leg. The leg must SPEND the hop's reservation instead of taking a second one: the
+   * final-recovery reserve is single, so a rebuild that reserved on top of a hop would be
+   * refused and the request would answer with a synthetic 502 in place of the real 429 the hop
+   * was recovering from.
+   */
+  let pendingHopPermit: SingleUseDispatchPermit | undefined;
+  /**
+   * The budget an adapter's OWN dispatch ladder reserves against.
+   *
+   * Kiro and Cursor reserve once per physical send, and that is right: their ladders are the
+   * layer that actually sends, and counting one adapter call as one send hid up to eighteen
+   * upstream requests. But a credential hop has already booked the replay it is about to make,
+   * and a reservation IS the charge, so an adapter that reserves again turns one physical send
+   * into two charges -- and once the base allowance is spent, into a refusal that answers with
+   * a synthetic error in place of the 429 the hop was recovering from (#4709).
+   *
+   * The hop hands its reservation down through `pendingHopPermit`, the same seam the
+   * passthrough ladder already uses, and this view spends it on the adapter's FIRST
+   * reservation. Every later send in that ladder is a new physical send and is charged
+   * normally. A permit the adapter takes but never sends under is released through the same
+   * call it would have used for a reservation of its own, so an abandoned replay is refunded
+   * rather than left charged.
+   */
+  const adapterDispatchBudget: RequestExecutionBudget | undefined = adapterSendBudget === undefined
+    ? undefined
+    : adapterDispatchBudgetView(adapterSendBudget, {
+      claimHopPermit: () => {
+        const permit = pendingHopPermit;
+        pendingHopPermit = undefined;
+        return permit;
+      },
+    });
+  /**
+   * How many sends a recovery leg may make, and the permit that authorises the last one.
+   *
+   * The base allowance is spent first. Once it is gone a recovery class may still draw the
+   * single shared final-recovery reserve -- which is what keeps the validated sanitized rebuild
+   * after a 5xx streak alive at four total sends -- but an account move and a rebuild cannot
+   * each take one. `countedExternally` is set because these legs run through the retry helper,
+   * which reports the same send again through `onSendsConsumed`.
+   */
+  const recoverySendAllowance = (
+    cap: number,
+    sendClass: SendClass,
+    targetKey: string,
+  ): { attempts: number; permit?: SingleUseDispatchPermit } => {
+    const base = remainingTransientSendBudget(cap);
+    if (base > 0) return { attempts: base };
+    if (pendingHopPermit) {
+      const hopPermit = pendingHopPermit;
+      pendingHopPermit = undefined;
+      return { attempts: 1, permit: hopPermit };
+    }
+    if (!isRequestExecutionBudget(sendBudget)) return { attempts: 0 };
+    const decision = sendBudget.reserveDispatch({ sendClass, targetKey, countedExternally: true });
+    return decision.allowed ? { attempts: 1, permit: decision.permit } : { attempts: 0 };
+  };
+  /**
+   * One credential hop of this logical request, admitted by the INTERSECTION of two bounds.
+   *
+   * `GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST` and `ANTHROPIC_POOL_MAX_FAILOVERS_PER_REQUEST`
+   * stay exactly as they are: they bound rotation within one credential roster. What neither
+   * can see is everything else this request already sent, so three hops layered on a spent
+   * budget still reached upstream three more times. A hop now happens only when its own layer
+   * cap AND the shared budget both permit it, and the smaller of the two wins.
+   *
+   * `countedExternally` is for the hops whose replay goes out through the retry helper, which
+   * reports the same physical send through `onSendsConsumed`; the others are charged here and
+   * nowhere else. A refusal is not an error: the caller keeps the real upstream response --
+   * status, `Retry-After`, quota body -- because return-the-last-answer is the exhaustion
+   * contract this unit settled on.
+   */
+  /**
+   * A credential rotation inside ONE provider's roster is "auth-recovery", not
+   * "account-failover". The distinction is load-bearing: "account-failover" sets
+   * `isAlternateTarget` unconditionally, so under `maxAlternateTargetSends: 1` the first
+   * rotation would refuse every later one AND consume the single slot a genuine cross-pool
+   * move needs -- a roster whose first two accounts are both 429'd would return the 429
+   * while a free third account sat unused. The roster cap bounds how far rotation walks;
+   * the shared total bounds how many sends the request makes. Reserve "account-failover"
+   * for a real move between pools.
+   */
+  const reserveCredentialHop = (
+    sendClass: SendClass,
+    targetKey: string,
+    countedExternally = false,
+  ): { allowed: boolean; permit?: SingleUseDispatchPermit } => {
+    if (!isRequestExecutionBudget(sendBudget)) return { allowed: true };
+    const decision = sendBudget.reserveDispatch({ sendClass, targetKey, countedExternally });
+    return decision.allowed ? { allowed: true, permit: decision.permit } : { allowed: false };
+  };
+  /**
+   * Both classes share the one reserve, so this only changes what the decision is called --
+   * but a recovery event that says "repair" when a credential refresh drove it is the kind of
+   * mislabelled evidence #4592 existed to stop.
+   */
+  const recoveryClassFor = (recovery: AttemptRecoveryKind): SendClass =>
+    /401|429|oauth|rate-limit|key/.test(recovery) ? "auth-recovery" : "repair";
+
+  return {
+    workflowRootId,
+    noteTransientSends,
+    remainingTransientSendBudget,
+    adapterSendBudget,
+    adapterDispatchBudget,
+    noteAdapterPhysicalSend,
+    sendBudgetExhausted,
+    get pendingHopPermit(): SingleUseDispatchPermit | undefined {
+      return pendingHopPermit;
+    },
+    set pendingHopPermit(value: SingleUseDispatchPermit | undefined) {
+      pendingHopPermit = value;
+    },
+    recoverySendAllowance,
+    reserveCredentialHop,
+    recoveryClassFor,
+  };
+}
+
+export type ResponsesSendBudget = Exclude<ReturnType<typeof createResponsesSendBudget>, Response>;
+
+/**
+ * A LIVE delegating view of one request's execution budget, with a credential hop's
+ * reservation spendable through it.
+ *
+ * Every member forwards rather than copying. A spread of the budget would freeze `used`,
+ * `reserveSpent` and the target counters at construction time, handing the adapter a budget
+ * that can never read as exhausted -- the same class of defect as the fresh per-layer
+ * allowances #4546 removed.
+ */
+function adapterDispatchBudgetView(
+  budget: RequestExecutionBudget,
+  hop: { claimHopPermit: () => SingleUseDispatchPermit | undefined },
+): RequestExecutionBudget {
+  return {
+    get used(): number { return budget.used; },
+    set used(next: number) { budget.used = next; },
+    logicalRequestId: budget.logicalRequestId,
+    policyVersion: budget.policyVersion,
+    policy: budget.policy,
+    get reserveSpent(): boolean { return budget.reserveSpent; },
+    get alternateTargetSends(): number { return budget.alternateTargetSends; },
+    get targetTransitions(): number { return budget.targetTransitions; },
+    get lastTargetKey(): string | undefined { return budget.lastTargetKey; },
+    remainingBaseSends: (cap: number): number => budget.remainingBaseSends(cap),
+    reserveDispatch(intent: DispatchIntent): DispatchDecision {
+      // A dispatch whose upstream state is unknown is refused on its own merits. A hop that
+      // already paid does not make an unsafe replay safe, so that check stays with the budget.
+      if (intent.replaySafe !== false) {
+        const hopPermit = hop.claimHopPermit();
+        // Confirmed here rather than in `use()`: the adapter reserves immediately before it
+        // opens the transport, which is the same boundary the hop's own confirmation uses.
+        // A permit some other leg already settled returns false, and this falls through to a
+        // real reservation rather than handing the adapter a dead permit -- an adapter whose
+        // `use()` fails treats the request as exhausted and stops sending entirely.
+        if (hopPermit !== undefined && hopPermit.assumeCharge()) {
+          let spent = false;
+          return {
+            allowed: true,
+            permit: {
+              sendClass: hopPermit.sendClass,
+              use: (): boolean => {
+                if (spent) return false;
+                spent = true;
+                return true;
+              },
+              assumeCharge: (): boolean => {
+                if (spent) return false;
+                spent = true;
+                return true;
+              },
+              // The hop's charge is already settled and belongs to the leg that asked for it,
+              // so there is nothing here to refund.
+              release: (): void => {},
+            },
+          };
+        }
+      }
+      return budget.reserveDispatch(intent);
+    },
+  };
+}

package/src/server/responses/request-sidecar-auth.ts

@@ -0,0 +1,149 @@
+import type { ResponsesRequestContext } from "./core-options";
+import type { PreparedResponsesRequest } from "./request-prepare";
+import type { ResponsesTransport } from "./request-transport";
+import type { ResolvedOpenAiForwardSidecar } from "../../providers/openai-sidecar";
+import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import {
+  shouldResolveOpenAiVisionSidecar,
+  resolveOpenAiVisionModel,
+  planVisionSidecar,
+  describeImagesInPlace,
+  requiresVisionPreprocessing,
+  stripImagesInPlace,
+} from "../../vision";
+import { shouldResolveOpenAiWebSearchSidecar } from "../../web-search";
+import { shouldResolveOpenAiPassthroughWebSearchBridge } from "../../web-search/passthrough-bridge";
+import {
+  listOpenAiForwardSidecarCandidates,
+  captureExplicitOpenAiCallerAuth,
+  resolveFirstUsableOpenAiSidecar,
+} from "../../providers/openai-sidecar";
+import {
+  tryClaimNativeMainProfileForTurn as tryClaimStoredSidecarMainProfile,
+} from "../../codex/native-main-admission";
+import { codexAccountSelectionForTurn } from "../lifecycle";
+import {
+  CodexPoolAuthenticationError,
+  CodexAuthContextError,
+  CodexAccountCooldownError,
+  CodexThreadAffinityExpiredError,
+  CodexMainProfileDrainingError,
+} from "../../codex/auth-context";
+
+/** One responsibility of the Responses request pipeline; state owners are explicit. */
+export async function prepareResponsesSidecarAuth(
+  requestContext: Pick<ResponsesRequestContext, "options" | "config" | "req">,
+  requestState: Pick<
+    PreparedResponsesRequest,
+    | "parsed"
+    | "route"
+    | "selectedForwardHeaders"
+    | "translatorBudget"
+  >,
+  transportState: Pick<ResponsesTransport, "adapter" | "isPassthrough">,
+) {
+  const { options, config, req } = requestContext;
+  const { parsed, route, translatorBudget } = requestState;
+  const { isPassthrough } = transportState;
+
+
+  let openAiSidecar: ResolvedOpenAiForwardSidecar | undefined;
+  const visionDescribeTerminal = options.visionDescribeTerminal === true;
+  const routedCompaction = parsed._compactionRequest === true
+    && !isCanonicalOpenAiForwardProvider(route.provider);
+  const needsOpenAiVision = !visionDescribeTerminal
+    && shouldResolveOpenAiVisionSidecar(config, route.provider, route.modelId, parsed, route.providerName);
+  const needsOpenAiSearch = !routedCompaction && !transportState.adapter.runTurn
+    && (shouldResolveOpenAiWebSearchSidecar(config, parsed, isPassthrough)
+      || shouldResolveOpenAiPassthroughWebSearchBridge(route.provider, parsed, isPassthrough));
+  if (needsOpenAiVision || needsOpenAiSearch) {
+    try {
+      const candidates = listOpenAiForwardSidecarCandidates(config);
+      let sidecarAuth = options.openAiSidecarAuth;
+      if (!sidecarAuth && options.allowStoredOpenAiSidecarAuth === true
+        && route.codexAccountId === undefined
+        && candidates.some(candidate => candidate.accountMode === "direct")
+        && tryClaimStoredSidecarMainProfile(options.turnAdmissionLease)) {
+        // Request-local helper authority only: never promote this pair to caller, primary,
+        // or retry credentials. Claim before reading so profile switches remain fenced.
+        try {
+          const { getMainAccountToken } = await import("../../codex/main-account");
+          const token = getMainAccountToken();
+          if (token) sidecarAuth = captureExplicitOpenAiCallerAuth(new Headers({
+            authorization: `Bearer ${token.accessToken}`, "chatgpt-account-id": token.chatgptAccountId,
+          }), config);
+        } catch { /* stored enrichment is optional */ }
+      }
+      // Preserve explicit OpenAI helper auth across route changes without returning it to
+      // primary-provider headers or alternate-main retry. The resolver revalidates scope.
+      const sidecarHeaders = new Headers(req.headers);
+      sidecarHeaders.delete("authorization");
+      sidecarHeaders.delete("chatgpt-account-id");
+      if (sidecarAuth) {
+        sidecarHeaders.set("authorization", sidecarAuth.authorization);
+        sidecarHeaders.set("chatgpt-account-id", sidecarAuth.chatgptAccountId);
+      }
+      openAiSidecar = await resolveFirstUsableOpenAiSidecar(
+        candidates,
+        sidecarHeaders,
+        config,
+        {
+          admission: options.admission,
+          codexAuthPolicy: options.codexAuthPolicy,
+          // Account-qualified native routes are passthrough, so their in-turn helper is vision.
+          // Scope its cooldown and outcome to the helper model, not the routed text model.
+          ...(route.codexAccountId !== undefined
+            ? { exactAccount: { accountId: route.codexAccountId, modelId: resolveOpenAiVisionModel(config) } }
+            : {}),
+          beginCodexAccountSelection: codexAccountSelectionForTurn(options.turnAdmissionLease),
+        },
+      );
+    } catch (err) {
+      // Sidecars are optional helpers for an otherwise independent routed turn.
+      // An unavailable/cooling/expired Multi credential disables the helper; it
+      // must not turn a valid routed-provider request into a Codex-auth failure.
+      if (
+        !(err instanceof CodexPoolAuthenticationError)
+        && !(err instanceof CodexAuthContextError)
+        && !(err instanceof CodexAccountCooldownError)
+        && !(err instanceof CodexThreadAffinityExpiredError)
+        && !(err instanceof CodexMainProfileDrainingError)
+      ) throw err;
+    }
+  }
+
+  // Vision sidecar: the routed model can't see images (provider.noVisionModels). Describe each
+  // attached image through the selected sidecar backend and replace it with text BEFORE the main
+  // call, so the text-only model can reason about it.
+  // Terminal describe fence (roadmap 180): the sidecar's OWN loopback describe
+  // call must never plan another describe. The flag arrives from the Chat
+  // surface (whose bridge rebuilds headers) or as the raw header for native
+  // Responses callers. Marked + text-only routed model → strip, depth cap 1.
+  const visionPlan = visionDescribeTerminal
+    ? undefined
+    : planVisionSidecar(config, route.provider, route.modelId, parsed, openAiSidecar, {
+      admission: options.admission, codexAuthPolicy: options.codexAuthPolicy, providerName: route.providerName,
+    });
+  const recordSidecarOutcome = openAiSidecar?.recordOutcome;
+  if (visionPlan) {
+    await describeImagesInPlace(
+      parsed,
+      visionPlan,
+      openAiSidecar?.headers ?? requestState.selectedForwardHeaders,
+      options.abortSignal,
+      recordSidecarOutcome,
+      translatorBudget,
+    );
+  } else if (requiresVisionPreprocessing(config, route.provider, route.modelId, route.providerName)) {
+    // Image capability is not positively proven but no sidecar plan is dispatchable: fail closed.
+    // Never forward raw image bytes to an unverified upstream.
+    stripImagesInPlace(parsed, translatorBudget);
+  }
+
+  return {
+    openAiSidecar,
+    routedCompaction,
+  };
+}
+
+export type ResponsesSidecarAuth = Exclude<Awaited<ReturnType<typeof prepareResponsesSidecarAuth>>, Response>;

package/src/server/responses/request-spend.ts

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import type { RequestSendObserver } from "../../lib/request-execution-budget";
+import { sharedSpendLedger, type SpendReservationLedger } from "../../lib/spend-reservation-ledger";
+import type { RequestLogContext } from "../request-log";
+
+/** The terminal usage a request reported, in the only two fields the ledger books. */
+export interface TerminalSpendUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+/** Settles one request's durable spend entries once its terminal usage is known. */
+export interface RequestSpendSettlement {
+  settle(usage: TerminalSpendUsage | undefined): void;
+}
+
+export interface RequestSpendTracker extends RequestSendObserver, RequestSpendSettlement {
+  /** Dispatches this request lost to a ledger ceiling. Zero on every ordinary request. */
+  readonly refusals: number;
+}
+
+/**
+ * One request's entries in the durable spend ledger (#4707).
+ *
+ * The ledger has had the whole reserve/dispatch/settle vocabulary since #4546 and no production
+ * caller: `spend-ledger.jsonl` was never created by ordinary traffic, and the ceilings the
+ * feature advertised stayed process-local and count-only, resetting on restart. This is the
+ * caller.
+ *
+ * It books one entry per physical send by observing the request's own send counter rather than
+ * by being called from each dispatch site. That counter moves exactly once per physical send,
+ * so one entry per increment is one entry per send -- and a dispatch path added later cannot
+ * forget to book, which is how the previous wiring attempt ended up with no caller at all.
+ *
+ * Settlement follows what the request actually learned. The terminal usage belongs to the LAST
+ * send that left, so that one settles with the real figure. Every earlier send failed without
+ * reporting usage of its own and may still have been billed, so it becomes unresolved spend
+ * rather than free. A request that ends with no usage at all -- a cancel, a lost stream --
+ * leaves all of them unresolved, which is the conservative answer this ledger exists to give.
+ */
+export function createRequestSpendTracker(
+  logCtx: Pick<
+    RequestLogContext,
+    "provider" | "accountLogLabel" | "usageLogInputTokens" | "spendOutputCeilingTokens"
+  >,
+  rootId: string | undefined,
+  injected?: SpendReservationLedger,
+): RequestSpendTracker {
+  // Resolved on the first CHARGE, not when the request is built. The shared ledger opens a
+  // journal under the OpenCodex home, and a request that never dispatches -- refused at
+  // admission, answered locally, cancelled before its first send -- has no business creating
+  // one. It also means the home in effect at dispatch is the one that gets written.
+  let ledgerRef: SpendReservationLedger | undefined = injected;
+  const ledger = (): SpendReservationLedger => (ledgerRef ??= sharedSpendLedger());
+  // Every send this request still owes the ledger an answer for, oldest first.
+  const live: string[] = [];
+  let refusals = 0;
+  let resolved = false;
+  /**
+   * Confirm the sends this request has already moved past.
+   *
+   * A booking is only marked dispatched once a LATER send exists, because that later send
+   * proves the earlier one left. The newest booking stays open until it is settled, so a
+   * reservation the budget hands back -- a rotation that found no alternate, a rebuild
+   * abandoned before the wire -- can still be released for free while this process is alive.
+   * A crash resolves every surviving reservation as unresolved spend regardless of this mark,
+   * because a journal that lost its tail cannot prove a send never left.
+   */
+  const confirmOlderSends = (): void => {
+    for (let index = 0; index < live.length - 1; index += 1) ledger().markDispatched(live[index] as string);
+  };
+  return {
+    charge(): boolean {
+      const sendId = randomUUID();
+      const decision = ledger().reserve({
+        sendId,
+        scopes: {
+          ...(rootId !== undefined ? { rootId } : {}),
+          // Already the privacy-safe label the request log uses, and the ledger aliases it
+          // again on the way to disk. A raw credential never reaches either.
+          ...(logCtx.accountLogLabel !== undefined ? { identityId: logCtx.accountLogLabel } : {}),
+          ...(logCtx.provider !== undefined ? { poolId: logCtx.provider } : {}),
+        },
+        inputTokens: logCtx.usageLogInputTokens ?? 0,
+        outputCeilingTokens: logCtx.spendOutputCeilingTokens ?? 0,
+      });
+      if (!decision.reserved) {
+        refusals += 1;
+        // Only an operator's configured ceiling refuses a dispatch. Every other denial --
+        // capacity, durability, a journal this process could not prove complete -- means the
+        // ledger cannot ACCOUNT for this send, which is not a reason to refuse one. An
+        // unconfigured install keeps the count caps it already had and is not newly refused,
+        // and a degraded ledger must not become an outage.
+        return decision.denial.reason !== "spend-limit-exceeded";
+      }
+      live.push(sendId);
+      confirmOlderSends();
+      return true;
+    },
+    refund(): void {
+      const sendId = live.pop();
+      if (sendId === undefined) return;
+      // Undispatched, so this returns the tokens. If the send was already confirmed by a later
+      // one, `abandon` refuses and unresolved is the only honest outcome left.
+      if (!ledger().abandon(sendId)) ledger().markLost(sendId);
+    },
+    settle(usage: TerminalSpendUsage | undefined): void {
+      if (resolved) return;
+      resolved = true;
+      const terminal = live.pop();
+      if (terminal !== undefined) {
+        const reported = typeof usage?.inputTokens === "number" || typeof usage?.outputTokens === "number";
+        if (reported) {
+          ledger().settle(terminal, {
+            inputTokens: usage?.inputTokens ?? 0,
+            outputTokens: usage?.outputTokens ?? 0,
+          });
+        } else {
+          // The response never reported usage. It may still have been billed.
+          ledger().markLost(terminal);
+        }
+      }
+      for (const sendId of live.splice(0)) ledger().markLost(sendId);
+    },
+    get refusals(): number { return refusals; },
+  };
+}
+
+/**
+ * Give a request a spend tracker and hand back the observer its budget reports through.
+ *
+ * The tracker is parked on the log context because `addFinalRequestLog` is the one seam every
+ * request passes exactly once, whatever transport served it and however it ended, and it is
+ * where the terminal usage is already known.
+ */
+export function attachRequestSpendTracker(
+  req: Pick<Request, "headers">,
+  logCtx: RequestLogContext,
+  ledger?: SpendReservationLedger,
+): RequestSendObserver {
+  const rootId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const tracker = ledger === undefined
+    ? createRequestSpendTracker(logCtx, rootId)
+    : createRequestSpendTracker(logCtx, rootId, ledger);
+  logCtx.spendTracker = tracker;
+  return tracker;
+}