@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/images/loop.ts

@@ -615,7 +615,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
                   signal: headerDeadline.signal,
                 }, retryRecovery));
               },
-              { abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
+              { replaySafe: true, abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
             );
           }
         } finally {

package/src/lib/errors.ts

@@ -7,6 +7,15 @@ export interface OcxErrorPayload {
 export const ENCRYPTED_FUNCTION_OUTPUT_REJECTION =
   "Encrypted function output content could not be decrypted or decoded.";
 
+/**
+ * The error identity for a send this proxy declined to make (#4708).
+ *
+ * Declared here rather than only on the error class because the classifier is what decides
+ * whether the identity survives serialization, and every dispatch path has to name the same
+ * string for a client to be able to tell this apart from a provider rate limit.
+ */
+export const SEND_BUDGET_EXHAUSTED_CODE = "request_send_budget_exhausted";
+
 /** Canonical human-readable message paths used by Responses upstream failures. */
 export function upstreamErrorMessageFromPayload(payload: unknown): string | undefined {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
@@ -253,6 +262,14 @@ export function classifyError(status: number, type: string, message: string): Oc
   ) {
     return { message, type: "insufficient_quota", code: "insufficient_quota" };
   }
+  // A refusal this proxy made itself, kept apart from the provider rate limits below. The HTTP
+  // semantics are identical -- 429, do not send this again now -- but the code is the only thing
+  // that tells an operator reading a log whether the provider throttled the request or whether
+  // this process declined to send it. Folding it into the generic rate-limit code sent them to
+  // the provider's dashboard to explain a decision that was never made there.
+  if (type === SEND_BUDGET_EXHAUSTED_CODE) {
+    return { message, type: "rate_limit_error", code: SEND_BUDGET_EXHAUSTED_CODE };
+  }
   if (
     status === 429 ||
     text.includes("rate limit") ||

package/src/lib/request-execution-budget.ts

@@ -56,6 +56,7 @@ export type BudgetDenial =
   | "final-recovery-spent"
   | "alternate-target-exhausted"
   | "target-transition-exhausted"
+  | "spend-exhausted"
   | "not-replay-safe";
 
 export interface DispatchIntent {
@@ -72,23 +73,67 @@ export interface DispatchIntent {
   readonly replaySafe?: boolean;
   /**
    * True when the physical send is already reported through another counter -- the retry
-   * helpers' `onSendsConsumed` hook. The permit then books the reserve, alternate-target and
-   * transition ledgers but leaves `used` to that reporter, because charging both is how a
-   * four-send cap silently becomes a two-send cap.
+   * helpers' `onSendsConsumed` hook. The send is still booked at reservation time, because an
+   * advisory reservation cannot stop a concurrent leg; what changes is that the booking is
+   * PENDING, and the first send the external reporter names settles it instead of adding a
+   * second charge. Charging both is how a four-send cap silently becomes a two-send cap.
    */
   readonly countedExternally?: boolean;
 }
 
 export interface SingleUseDispatchPermit {
   readonly sendClass: SendClass;
-  /** Consume exactly once. A second call returns false and charges nothing. */
+  /**
+   * Confirm the dispatch this permit already paid for. The reservation is the charge, so this
+   * charges nothing; it is how a leg proves it is the one that sent. A second call returns
+   * false, which is what keeps a retry thunk from sending twice on one permit.
+   */
   use(): boolean;
+  /**
+   * Hand back a reservation that never dispatched -- a credential move that found no alternate,
+   * a rebuild abandoned before the send. Idempotent, and a no-op once the permit was used or
+   * once an external send reporter already settled it.
+   */
+  release(): void;
+  /**
+   * Take over an externally counted booking, because the layer holding this permit is the one
+   * that physically sends.
+   *
+   * `countedExternally` promises that a retry helper will name this send through
+   * `onSendsConsumed`. An adapter that owns its own dispatch ladder -- Kiro's reset loop,
+   * Cursor's transport loop -- reserves per physical send instead, so no reporter ever arrives
+   * and the pending booking would sit there until it silently swallowed an unrelated later
+   * report. Confirming through this method settles the permit AND closes the booking, so the
+   * send stays charged exactly once (#4709). Returns false once the permit is settled, which is
+   * what keeps one permit from admitting two sends.
+   */
+  assumeCharge(): boolean;
 }
 
 export type DispatchDecision =
   | { allowed: true; permit: SingleUseDispatchPermit }
   | { allowed: false; reason: BudgetDenial };
 
+/**
+ * Notified when this request's physical-send count moves.
+ *
+ * `spent` is the only number here that counts SENDS rather than intentions: a reservation
+ * increments it, a refund decrements it, and an externally reported send settles against a
+ * booking that was already counted. Anything that books one entry per increment therefore
+ * books exactly one entry per physical send -- which is what lets the durable spend ledger
+ * have a production caller without every dispatch site in the tree remembering to call it.
+ *
+ * `charge` may refuse, and a refusal denies the dispatch. That is deliberate: the ledger is
+ * the only bound here that survives a restart, so a limit it enforces has to be able to stop a
+ * send rather than merely describe one.
+ */
+export interface RequestSendObserver {
+  /** Book one physical send. False refuses the dispatch before the budget charges it. */
+  charge(): boolean;
+  /** Give back a booking whose send never happened. */
+  refund(): void;
+}
+
 /**
  * Carried on HandleResponsesOptions so a combo child, a rebuild and an alternate-account leg
  * all decrement the same holder. `used` is the existing #4605 counter and still counts every
@@ -103,6 +148,9 @@ export interface RequestExecutionBudget extends TransientSendBudget {
    * Sends still available from the base allowance, capped by a layer's own maximum.
    * Returns 0 when the allowance is gone -- it never floors to 1, because a floor of 1 is
    * what let every recovery leg send one more time forever.
+   *
+   * A reserved-but-unconfirmed send is spent for this purpose. The alternative -- counting only
+   * confirmed sends -- is what let two legs read the same remainder and both dispatch.
    */
   remainingBaseSends(cap: number): number;
   readonly reserveSpent: boolean;
@@ -120,17 +168,58 @@ const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
 
 let logicalRequestSeq = 0;
 
-export function createRequestExecutionBudget(
-  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
-  logicalRequestId?: string,
+/**
+ * One request's physical-send ledger, held apart from the budget object so a derived policy
+ * scope can share the exact same one.
+ *
+ * `spent` and `pendingExternalSends` belong together: a pending booking is a send that is
+ * already counted in `spent` and awaiting its reporter, so a scope that shared one without the
+ * other would either charge that send twice or never charge it at all.
+ *
+ * The durable-spend observer belongs here for the same reason. It books one entry per physical
+ * send by watching this counter move, so a derived scope that spent the counter without
+ * carrying the observer would move it without booking, and a combo child's sends would go
+ * missing from the ledger (#4707).
+ */
+interface SharedSendLedger {
+  spent: number;
+  pendingExternalSends: number;
+  readonly observer?: RequestSendObserver;
+}
+
+const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>();
+
+function createRequestExecutionBudgetWithLedger(
+  policy: RequestExecutionBudgetPolicy,
+  logicalRequestId: string | undefined,
+  counter: SharedSendLedger,
 ): RequestExecutionBudget {
+  const observer = counter.observer;
   let reserveSpent = false;
   let alternateTargetSends = 0;
   let targetTransitions = 0;
   let lastTargetKey: string | undefined;
 
   const budget: RequestExecutionBudget = {
-    used: 0,
+    get used(): number { return counter.spent; },
+    set used(next: number) {
+      // The retry helpers report their real send count by assigning through this field. A
+      // reservation taken with `countedExternally` has already booked one of those sends, so
+      // the report settles the pending booking first and only the surplus is charged.
+      const delta = next - counter.spent;
+      if (delta <= 0) {
+        counter.spent = Math.max(0, next);
+        return;
+      }
+      const settled = Math.min(delta, counter.pendingExternalSends);
+      counter.pendingExternalSends -= settled;
+      const charged = delta - settled;
+      counter.spent += charged;
+      // These sends have already left. The ledger records them even past a ceiling it would
+      // have refused, because refusing after the fact only hides spend that was really
+      // incurred -- the refusal has to happen at the reservation below, or not at all.
+      for (let index = 0; index < charged; index += 1) observer?.charge();
+    },
     logicalRequestId: logicalRequestId ?? `lr-${Date.now().toString(36)}-${(logicalRequestSeq += 1).toString(36)}`,
     policyVersion: REQUEST_BUDGET_POLICY_VERSION,
     policy,
@@ -140,11 +229,11 @@ export function createRequestExecutionBudget(
     get lastTargetKey() { return lastTargetKey; },
     remainingBaseSends(cap: number): number {
       const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
-      return Math.max(0, Math.min(capped, policy.baseSendAllowance - budget.used));
+      return Math.max(0, Math.min(capped, policy.baseSendAllowance - counter.spent));
     },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
-      if (budget.used >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
+      if (counter.spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
 
       const changesTarget = lastTargetKey !== undefined && lastTargetKey !== intent.targetKey;
       const isAlternateTarget = changesTarget || intent.sendClass === "account-failover"
@@ -159,7 +248,7 @@ export function createRequestExecutionBudget(
       // The base allowance is spent first. Only once it is gone does a recovery class reach
       // for the single shared reserve -- an account move and a validated rebuild cannot each
       // take one.
-      const drawsReserve = budget.remainingBaseSends(policy.baseSendAllowance) === 0;
+      const drawsReserve = policy.baseSendAllowance - counter.spent <= 0;
       if (drawsReserve) {
         if (!RESERVE_FUNDED_CLASSES.has(intent.sendClass)) {
           return { allowed: false, reason: "base-allowance-exhausted" };
@@ -169,32 +258,118 @@ export function createRequestExecutionBudget(
         }
       }
 
-      let consumed = false;
+      // Consulted last, because it is the only bound here that WRITES. A ledger entry booked
+      // for a dispatch a cheaper check above would have refused is spend this request never
+      // makes, and it would hold those tokens against the scope until retention expired.
+      if (observer && !observer.charge()) return { allowed: false, reason: "spend-exhausted" };
+
+      // THE RESERVATION IS THE CHARGE. Deciding here and charging in `use()` left a window in
+      // which two legs read the same remainder, both received a permit, and both dispatched:
+      // one remaining send admitted two physical sends, which is the per-request multiplication
+      // this budget exists to stop. Everything is booked now; `release()` is the way back.
+      const previousTargetKey = lastTargetKey;
+      counter.spent += 1;
+      if (intent.countedExternally === true) counter.pendingExternalSends += 1;
+      if (drawsReserve) reserveSpent = true;
+      if (isAlternateTarget) alternateTargetSends += 1;
+      if (changesTarget) targetTransitions += 1;
+      lastTargetKey = intent.targetKey;
+
+      let settled: "open" | "used" | "released" = "open";
       return {
         allowed: true,
         permit: {
           sendClass: intent.sendClass,
           use(): boolean {
-            if (consumed) return false;
-            consumed = true;
-            // Charged here, immediately before the physical send, rather than reported after
-            // the helper returns: a counter that is only reconciled afterwards cannot stop two
-            // concurrent legs that both read the same remainder.
-            if (intent.countedExternally !== true) budget.used += 1;
-            if (drawsReserve) reserveSpent = true;
-            if (isAlternateTarget) alternateTargetSends += 1;
-            if (changesTarget) targetTransitions += 1;
-            lastTargetKey = intent.targetKey;
+            if (settled !== "open") return false;
+            settled = "used";
             return true;
           },
+          assumeCharge(): boolean {
+            if (settled !== "open") return false;
+            settled = "used";
+            // The booking this reservation made for an external reporter is now owned by the
+            // caller. Leaving it pending is not harmless: the next `used` report of this request
+            // would settle against it and one real send would go uncharged.
+            if (intent.countedExternally === true && counter.pendingExternalSends > 0) {
+              counter.pendingExternalSends -= 1;
+            }
+            return true;
+          },
+          release(): void {
+            if (settled !== "open") return;
+            settled = "released";
+            // An externally counted reservation the reporter already settled paid for a send
+            // that physically happened. Refunding it would hand the request a free send back.
+            if (intent.countedExternally === true) {
+              if (counter.pendingExternalSends === 0) return;
+              counter.pendingExternalSends -= 1;
+            }
+            counter.spent -= 1;
+            observer?.refund();
+            if (drawsReserve) reserveSpent = false;
+            if (isAlternateTarget) alternateTargetSends -= 1;
+            if (changesTarget) targetTransitions -= 1;
+            lastTargetKey = previousTargetKey;
+          },
         },
       };
     },
   };
-  if (lastTargetKey === undefined) lastTargetKey = undefined;
+  sharedSendLedgers.set(budget, counter);
   return budget;
 }
 
+export function createRequestExecutionBudget(
+  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
+  logicalRequestId?: string,
+  observer?: RequestSendObserver,
+): RequestExecutionBudget {
+  return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
+    spent: 0,
+    pendingExternalSends: 0,
+    ...(observer ? { observer } : {}),
+  });
+}
+
+/**
+ * A budget that applies its own policy and keeps its own recovery ledgers while spending the
+ * parent's exact physical-send ledger.
+ *
+ * Aliasing the public `used` property was not enough, and that is the whole defect. The factory
+ * reads its own private counter back in `remainingBaseSends`, in the total check, and in the
+ * reserve test, so an aliased scope answered every admission question from a counter that only
+ * ever saw its own reservations. A combo's per-target holdback is computed from
+ * `maxTotalModelSends` and is therefore unenforceable unless the scope actually observes what
+ * the request has already spent.
+ */
+export function deriveRequestExecutionBudget(
+  parent: RequestExecutionBudget,
+  policy: RequestExecutionBudgetPolicy,
+): RequestExecutionBudget {
+  return createRequestExecutionBudgetWithLedger(policy, parent.logicalRequestId, ledgerFor(parent));
+}
+
+/**
+ * A budget that did not come from this factory still honors the public `used` contract, so
+ * bridge onto it rather than failing the request. `isRequestExecutionBudget` is a shape test,
+ * so a stub can reach here; turning that into a thrown error would convert a routing request
+ * into a 500 to report a condition production never produces. Only a factory-backed parent can
+ * share pending external bookings and a durable-spend observer, which are private by
+ * construction; a bridged scope keeps the parent's spend accurate and books nothing of its own.
+ */
+function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
+  const existing = sharedSendLedgers.get(parent);
+  if (existing) return existing;
+  let pendingExternalSends = 0;
+  return {
+    get spent(): number { return parent.used; },
+    set spent(next: number) { parent.used = next; },
+    get pendingExternalSends(): number { return pendingExternalSends; },
+    set pendingExternalSends(next: number) { pendingExternalSends = next; },
+  };
+}
+
 export function isRequestExecutionBudget(
   value: TransientSendBudget | undefined,
 ): value is RequestExecutionBudget {