UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

628 lines (618 loc) • 34.9 kB
import { createInferenceSendBudget } from "../inference/context"; import { responsesSpendTarget } from "./request-spend-target"; import type { ResponsesRequestContext } from "./core-options"; import { claimDispatchSpendProof, createPhysicalSendReporter, createRequestExecutionBudget, isRequestExecutionBudget, hasWorkflowSendObserver, reportDispatchSends, requestHasCapturedSpendCeiling } from "../../lib/request-execution-budget"; import { chargeWorkflowSends, reserveWorkflowSend, workflowSendCeilingReached, workflowSpendCeilingReached, } from "../../lib/workflow-budget"; import { currentWorkflowBudgetPolicy } from "../../lib/workflow-budget-config"; import { poolContinuityRefusalReason, workflowRefusalResponse } from "../workflow-refusal"; import type { AttemptRecoveryKind, AttemptRecoveryWithheld } from "../../usage/log"; import { noteAttemptRecoveryWithheld, noteAttemptSend, type RequestLogContext } from "../request-log"; import { TRANSIENT_RETRY_MAX_ATTEMPTS, SendBudgetExhaustedError, type TransientSendBudget } from "../../lib/upstream-retry"; import type { ErrorDestinationLabel } from "../../lib/error-destination"; import type { SpendScopes } from "../../lib/spend-reservation-ledger"; import { estimateTokens } from "../../lib/token-estimate"; import type { DispatchDecision, DispatchIntent, RequestExecutionBudget, SendClass, SingleUseDispatchPermit, AuxiliaryModelSend, } from "../../lib/request-execution-budget"; /** * The transient-5xx ladder cap for ONE leg, given the provider's configured request total. * * `remainingTransientSendBudget(cap)` treats `cap` as a ceiling on what REMAINS, which is the * right shape for the fixed constant: every leg may ask for up to three, and the request-wide * base allowance is what actually bounds the total. A configured `transientRetryOn5xx.attempts` * is documented as the total for one request including the first send, so it has to be reduced * by what the request already sent before it is intersected with that allowance. Passing it * straight through would make it a per-leg ceiling instead, and a request configured at one send * could still reach upstream again on a recovery leg (#4893). * * An absent policy returns the constant unchanged, so a provider that configures nothing behaves * exactly as it does today at every call site. */ export function transientSendCapFor( configuredAttempts: number | undefined, sendsUsed: number, ): number { if (configuredAttempts === undefined) return TRANSIENT_RETRY_MAX_ATTEMPTS; return Math.max(0, configuredAttempts - Math.max(0, sendsUsed)); } /** A native compact credential recovery spends one send from the shared request budget. */ export async function sendSingleCompactRecovery( budget: RequestExecutionBudget, target: () => SpendScopes, targetKey: string, destination: ErrorDestinationLabel, dispatch: () => Promise<Response>, ): Promise<Response> { const freshRetrySpend = budget.explicitSendCeiling !== undefined; const exhausted = () => new SendBudgetExhaustedError(destination); if (budget.remainingBaseSends(TRANSIENT_RETRY_MAX_ATTEMPTS) > 0) { const report = createPhysicalSendReporter(budget, target); let started = false; try { if (report.beforeSend?.(freshRetrySpend) === false) throw exhausted(); started = true; return await (report.execute ? report.execute(dispatch) : dispatch()); } finally { try { if (started) report(1); } finally { report.close?.(); } } } const decision = budget.reserveDispatch({ sendClass: "auth-recovery", targetKey, freshRetrySpend }); if (!decision.allowed) throw exhausted(); const { permit } = decision; const run = () => { if (!permit.use()) { permit.release(); throw exhausted(); } return dispatch(); }; return permit.execute ? permit.execute(run) : run(); } /** Read the admitted target's ceilings without claiming a send or a prepaid proof. */ export function responsesHasCapturedSpendCeiling( sendBudget: TransientSendBudget, req: Pick<Request, "headers">, logCtx: RequestLogContext, target: SpendScopes, ): boolean { return requestHasCapturedSpendCeiling(sendBudget, { rootId: req.headers.get("x-codex-parent-thread-id")?.trim() || undefined, identityId: target.identityId ?? logCtx.accountLogLabel, poolId: target.poolId ?? logCtx.spendPoolId ?? logCtx.provider, }); } /** 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 ?? createInferenceSendBudget(req, logCtx, options.hostedAdvisorSpendScope?.ceilings); // 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 physicalWorkflowAccounting = hasWorkflowSendObserver(sendBudget); // A child that owns its Combo booking settles that exact permit through the reporter, even // when its caller handed ownership over only as `comboInitialSend`. const inheritedPermit = options.compactionRecoveryPermit ?? options.comboDispatchPermit ?? options.comboInitialSend?.permit; let pendingHopPermit: SingleUseDispatchPermit | undefined = options.compactionRecoveryPermit; let initialPermit = options.comboInitialSend?.permit; const compactHandoffSendCeiling = options.compactionRecoveryKind === "compaction-v1" && isRequestExecutionBudget(sendBudget) && sendBudget.used > 0 ? sendBudget.explicitSendCeiling : undefined; // Count this owner's physical sends, not later bookings made by other shared-ledger owners. // Direct callers retain sends reported before this owner was constructed. let targetSendsUsed = initialPermit ? 0 : Math.max(0, sendBudget.used - (options.compactionRecoveryPermit ? 1 : 0)); /** Attribute reported physical sends to this owner; the prepaid booking is spent once reported. */ const noteTargetSends = (charged: number): void => { targetSendsUsed += charged; if (charged > 0) initialPermit = undefined; }; const recordTransientSends = (used: number, permit?: SingleUseDispatchPermit, workflowAlreadyCounted = false): void => { const charged = Math.max(0, used); noteTargetSends(charged); reportDispatchSends(sendBudget, charged, permit, workflowAlreadyCounted); options.onCompactionRecoverySendsReported?.(charged); if (!physicalWorkflowAccounting && !workflowAlreadyCounted) chargeWorkflowSends(workflowRootId, charged); }; const noteTransientSends = (used: number): void => recordTransientSends(used, pendingHopPermit ?? inheritedPermit); const physicalSendReporter = (permit?: SingleUseDispatchPermit, explicitContinuation = false, wireEstimate?: { inputTokens: number; outputCeilingTokens: number }, receiptOwned = false, targetKey = explicitContinuation ? `native-continuation:${crypto.randomUUID()}` : undefined) => { let unreportedWorkflowStarts = 0; const reporter = createPhysicalSendReporter(sendBudget, () => ({ ...responsesSpendTarget(logCtx), ...(targetKey ? { targetKey } : {}), ...(wireEstimate ? { estimate: wireEstimate, explicitEstimate: true } : {}) }), permit, charged => { noteTargetSends(Math.max(0, charged)); options.onCompactionRecoverySendsReported?.(charged); const prepaid = Math.min(unreportedWorkflowStarts, Math.max(0, charged)); unreportedWorkflowStarts -= prepaid; if (!physicalWorkflowAccounting) chargeWorkflowSends(workflowRootId, charged - prepaid); }, { explicitContinuation, receiptOwned }); if (compactHandoffSendCeiling !== undefined && !explicitContinuation && reporter.beforeSend) { const beforeSend = reporter.beforeSend; let prepaid = permit !== undefined; reporter.beforeSend = freshRetry => { if (!beforeSend(freshRetry || !prepaid)) return false; prepaid = false; return true; }; } if (!receiptOwned && workflowRootId && !physicalWorkflowAccounting) { const beforeSend = reporter.beforeSend, close = reporter.close; let closed = false; reporter.beforeSend = reserveRetrySpend => { const policy = currentWorkflowBudgetPolicy(); // Check before a legacy permit's admission can spend it. No await separates this // read from the atomic claim, and the reporter owns the later accounting receipt. if (closed || workflowSendCeilingReached(workflowRootId, policy) || beforeSend?.(reserveRetrySpend) === false || !reserveWorkflowSend(workflowRootId, policy)) return false; unreportedWorkflowStarts++; return true; }; reporter.close = () => { closed = true; close?.(); }; } return reporter; }; // Capture at helper creation, before another leg can replace the pending handoff. const transientSendReporter = (permit = pendingHopPermit ?? inheritedPermit, receiptOwned = false) => physicalSendReporter(permit, false, undefined, receiptOwned); // A helper owns a fresh booking, never a routed leg's permit or target-local retry counter. const dispatchSidecarSend: AuxiliaryModelSend = async (target, dispatch) => { if (!isRequestExecutionBudget(sendBudget)) { if (!reserveWorkflowSend(workflowRootId, currentWorkflowBudgetPolicy())) throw new SendBudgetExhaustedError(); sendBudget.used++; return dispatch(); } const decision = sendBudget.reserveDispatch({ sendClass: "auxiliary", targetKey: target.targetKey, spendScopes: { poolId: target.poolId, identityId: target.identityId ?? "" }, spendEstimate: target.estimate, }); if (!decision.allowed) throw new SendBudgetExhaustedError(); const permit = decision.permit; const run = () => { const policy = currentWorkflowBudgetPolicy(); // No await separates this precheck, synchronous permit admission and the root claim. // Refuse before use() so the finally path can return an unused reservation. if (!physicalWorkflowAccounting && workflowSendCeilingReached(workflowRootId, policy)) throw new SendBudgetExhaustedError(); if (!permit.use()) throw new SendBudgetExhaustedError(); if (!physicalWorkflowAccounting && !reserveWorkflowSend(workflowRootId, policy)) throw new SendBudgetExhaustedError(); return dispatch(); }; try { return await (permit.execute ? permit.execute(run) : run()); } finally { permit.release(); } }; // 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, currentWorkflowBudgetPolicy())) { // 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); } // The token ceiling asked at the same seam, for the same reason the count one is asked here. // Without it a spent root reaches the dispatch ladder, is refused by the ledger at the first // physical send, and answers with the generic send-budget error every exhausted request // returns -- a refusal an operator cannot tell from an ordinary budget exhaustion, on a // ceiling they configured themselves. Asked before dispatch, it names the scope and the // number instead. Returns undefined and touches no ledger when no ceiling is configured. // Passthrough reports sends after they leave. Invalid or conflicting identity evidence // still refuses here as well as in reserve(), including requests with no workflow root. // Positive unbound balances alone are instead overlaid on each candidate pool below. const continuityRefusal = poolContinuityRefusalReason(); if (continuityRefusal) { return workflowRefusalResponse(continuityRefusal, logCtx, undefined, workflowRootId); } const prepaid = isRequestExecutionBudget(sendBudget) ? claimDispatchSpendProof(sendBudget, options.compactionRecoveryPermit ?? options.comboDispatchPermit) : undefined; const admissionPolicy = isRequestExecutionBudget(sendBudget) ? sendBudget.spendAdmissionPolicy : undefined; const spentCeiling = workflowSpendCeilingReached(workflowRootId, undefined, logCtx.spendPoolId ?? logCtx.provider, prepaid, admissionPolicy); if (spentCeiling) { return workflowRefusalResponse( "workflow-spend-exhausted", logCtx, undefined, workflowRootId, spentCeiling, ); } // 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; const hasCapturedSpendCeiling = (target: SpendScopes = {}): boolean => responsesHasCapturedSpendCeiling(sendBudget, req, logCtx, target); /** * Records an adapter's OWN inner retries against this attempt. * * The first receipt binds the attempt's identity. The budget counts every receipt, and * subsequent sends add to the active attempt without rebinding the credential. */ const noteAdapterPhysicalSend = ( inputTokens: number | undefined, send: { ordinal: number; recovery?: AttemptRecoveryKind }, ): void => { targetSendsUsed += 1; if (send.ordinal > 1) noteAttemptSend(logCtx.activeAttempt, inputTokens, send.recovery); }; /** * Records a recovery an adapter was ready to make and the budget refused. * * No send happened, so this deliberately does not touch `sendCount`. It is the other half of * the pair that makes a one-send log readable: no recovery kind AND no withheld reason means * nothing was eligible; a withheld reason means something was (#5044). */ const noteAdapterRecoveryWithheld = (withheld: { reason: AttemptRecoveryWithheld }): void => { noteAttemptRecoveryWithheld(logCtx.activeAttempt, withheld.reason); }; /** * Whether this request has any base send left under `cap`. * * The cap is a parameter because a lane that reads a provider's configured * `transientRetryOn5xx` ladder has to ask this question at the SAME cap its sends use. * Asking at the constant while dispatching at a configured value lets a provider with * headroom be told it is exhausted, and lets one configured below the constant pass this * check and then be refused at the send (#4893). Defaulted, so every existing caller keeps * the constant it already used. */ const sendBudgetExhausted = (cap: number = TRANSIENT_RETRY_MAX_ATTEMPTS): boolean => remainingTransientSendBudget(cap) === 0; /** * Spend one operator-granted replacement for an ambiguous failure of THIS logical request. * * The counter is the execution budget's, so a combo child that derives its own scope draws on * the same grant. A budget that predates it -- a stub, or a caller that passed the narrow * holder -- cannot grant anything, and refusing is the fail-closed answer for a send whose * upstream state is unknown. */ const claimAmbiguousResend = (limit: number): boolean => isRequestExecutionBudget(sendBudget) && sendBudget.claimAmbiguousResend?.(limit) === true; /** * 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. */ /** * 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. Claiming preserves the refundable single-use booking until physical dispatch; * an abandoned replay releases only that exact booking. */ const permits = { /** Transfer the initial booking once to the adapter dispatch owner. */ claimInitialPermit: () => { const permit = initialPermit; initialPermit = undefined; return permit; }, /** Transfer a pending recovery booking once, without creating a new allowance. */ claimHopPermit: () => { const permit = pendingHopPermit; pendingHopPermit = undefined; return permit; }, }; const adapterDispatchBudget = adapterSendBudget === undefined ? undefined : adapterDispatchBudgetView(adapterSendBudget, permits); // Preserve the existing opted-in view for direct callers, including its admitted replacement // of an already-settled hop. Exact-owned Combo and sidecar handoffs use the ordinary view. const refundableAdapterDispatchBudget = adapterSendBudget === undefined ? undefined : adapterDispatchBudgetView(adapterSendBudget, permits, true); /** * 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. A caller with an exact provider total can suppress that reserve. The * `countedExternally` flag exists because these legs run through the retry helper, which reports * the same send again through `onSendsConsumed`. */ const recoverySendAllowance = ( cap: number, sendClass: SendClass, targetKey: string, options: { allowFinalRecoveryReserve?: boolean } = {}, ): { attempts: number; permit?: SingleUseDispatchPermit } => { const base = remainingTransientSendBudget(cap); // The hop already paid for this leg's first send. Include it in the helper's total // attempts without charging it again, or the final account loses one transient attempt. if (base > 0) return { attempts: Math.min(cap, base + (pendingHopPermit ? 1 : 0)) }; // A provider-configured transient total is an exact physical-send ceiling. Once it is // exhausted, the request-wide recovery reserve must not silently widen it. The default stays // permissive so unconfigured providers retain the guarded profile's fourth recovery send. if (options.allowFinalRecoveryReserve === false) return { attempts: 0 }; 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. * * The snapshotted generic OAuth and Anthropic roster caps * 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, // A same-provider credential hop is not a model/endpoint transition. Its diagnostic // label must not replace the physical target used by the adapter's next retry. targetKey: sendClass === "auth-recovery" ? sendBudget.lastTargetKey ?? targetKey : 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 { imageRecoverySendReporter: (body: string, maxOutputTokens: number) => { // Each leg needs its own seed at normal capacity, on the ordinary physical-send counter. const reporter = physicalSendReporter(undefined, false, { inputTokens: estimateTokens(body, logCtx.model), outputCeilingTokens: maxOutputTokens }, false, `image-413:${crypto.randomUUID()}`); const beforeSend = reporter.beforeSend; reporter.beforeSend = () => { const target = responsesSpendTarget(logCtx); // A legacy or observe-only holder may know the ceiling without being able to reserve. if (adapterSendBudget?.spendEnforced !== true && hasCapturedSpendCeiling(target)) return false; return beforeSend?.() !== false; }; return reporter; }, workflowRootId, noteTransientSends, transientSendReporter, /** * A new native continuation cannot consume an initial or recovery booking. Its * reservation is priced on the exact successor frame about to leave — the * production dispatch path always supplies it. The merged outgoing body's * max_output_tokens replaces the output reservation when present, including null. * When the wire omits it, retain the caller's local output reservation: the * canonical backend strips unsupported output caps. Input is always remeasured. */ continuationSendReporter: (frame: { body: Record<string, unknown>; text: string }) => physicalSendReporter(undefined, true, { inputTokens: Math.max(1, estimateTokens(frame.text, logCtx.model)), outputCeilingTokens: typeof frame.body.max_output_tokens === "number" && Number.isFinite(frame.body.max_output_tokens) && frame.body.max_output_tokens > 0 ? Math.trunc(frame.body.max_output_tokens) : Object.hasOwn(frame.body, "max_output_tokens") ? 0 : logCtx.spendOutputCeilingTokens ?? 0, }), remainingTransientSendBudget, /** Only this child's prepaid send, not every pending external booking, is spendable here. */ initialSendAllowance: (cap: number): number => Math.min(cap, remainingTransientSendBudget(cap) + (initialPermit ? 1 : 0)), /** At final executor admission, settle only the owning booking or reserve this send. */ noteInitialDispatch: (prepaid = initialPermit, reserveUnbookedSend = false): void => { const policy = currentWorkflowBudgetPolicy(); if (!physicalWorkflowAccounting && workflowSendCeilingReached(workflowRootId, policy)) { prepaid?.release(); throw new SendBudgetExhaustedError(); } if (prepaid) { if (!prepaid.assumeCharge()) { prepaid.release(); throw new SendBudgetExhaustedError(); } if (prepaid === initialPermit) initialPermit = undefined; } else if (adapterSendBudget && (reserveUnbookedSend || options.comboInitialSend || options.compactionRecoveryPermit)) { const decision = adapterSendBudget.reserveDispatch({ sendClass: "transient", targetKey: adapterSendBudget.lastTargetKey ?? `${logCtx.provider}/${logCtx.model}` }); if (!decision.allowed) throw new SendBudgetExhaustedError(); if (!decision.permit.use()) { decision.permit.release(); throw new SendBudgetExhaustedError(); } } else { // Legacy direct callers can prebook without handing over a permit; keep their reporter. if (reserveUnbookedSend && sendBudgetExhausted()) throw new SendBudgetExhaustedError(); if (adapterSendBudget?.claimWorkflowSend && !adapterSendBudget.claimWorkflowSend()) throw new SendBudgetExhaustedError(); if (!physicalWorkflowAccounting && !reserveWorkflowSend(workflowRootId, policy)) throw new SendBudgetExhaustedError(); recordTransientSends(1, pendingHopPermit ?? inheritedPermit, true); return; } if (!physicalWorkflowAccounting && !reserveWorkflowSend(workflowRootId, policy)) throw new SendBudgetExhaustedError(); targetSendsUsed += 1; options.onCompactionRecoverySendsReported?.(1); }, /** Physical sends reported by this owner; unrelated shared reservations cannot consume it. */ get targetSendsUsed(): number { return targetSendsUsed; }, /** Attribute sends charged by a separate recovery permit to this target. */ noteTargetSends, /** * Charged sends, including open prepaid reservations, across this logical request. * * A live getter, not a completed-send snapshot. Initial ladders use the child's own * prepaid allowance and target-local count; shared admission keeps every booking spent. */ get sendsUsed(): number { return sendBudget.used; }, adapterSendBudget, compactHandoffSendCeiling, hasCapturedSpendCeiling, dispatchSidecarSend, adapterDispatchBudget, refundableAdapterDispatchBudget, noteAdapterPhysicalSend, noteAdapterRecoveryWithheld, sendBudgetExhausted, claimAmbiguousResend, get ambiguousResendSpent(): boolean { return isRequestExecutionBudget(sendBudget) && sendBudget.ambiguousResendSpent === true; }, 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: { claimInitialPermit: () => SingleUseDispatchPermit | undefined; claimHopPermit: () => SingleUseDispatchPermit | undefined; }, legacyHopReplacement = false, ): RequestExecutionBudget { return { get physicalStarted() { return budget.physicalStarted; }, get physicalLimit() { return budget.physicalLimit; }, get workflowCountObserved() { return budget.workflowCountObserved; }, get spendEnforced() { return budget.spendEnforced; }, get spendPolicyStarted() { return budget.spendPolicyStarted; }, get spendAdmissionPolicy() { return budget.spendAdmissionPolicy; }, hasCapturedSpendCeiling: target => requestHasCapturedSpendCeiling(budget, target), startRequest: target => budget.startRequest?.(target), claimPhysicalSend: auxiliary => auxiliary ? budget.claimPhysicalSend?.(true) : budget.claimPhysicalSend?.(), claimContinuationPhysicalSend: () => budget.claimContinuationPhysicalSend?.(), claimWorkflowSend: auxiliary => (auxiliary ? budget.claimWorkflowSend?.(true) : budget.claimWorkflowSend?.()) ?? true, beginSpendProducer: () => budget.beginSpendProducer?.(), 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), claimAmbiguousResend: (limit: number): boolean => budget.claimAmbiguousResend?.(limit) === true, get ambiguousResendSpent(): boolean { return budget.ambiguousResendSpent === true; }, 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) { // The Combo reserves a logical provider/model identity. The child's first actual // endpoint is not a recovery transition; retain the original refundable permit. const initialPermit = hop.claimInitialPermit(); if (initialPermit) { budget.bindPrepaidTarget?.(intent.targetKey); return { allowed: true, permit: { sendClass: initialPermit.sendClass, execute: run => initialPermit.execute ? initialPermit.execute(run) : run(), use: () => initialPermit.assumeCharge(), assumeCharge: () => initialPermit.assumeCharge(), release: () => initialPermit.release(), } }; } const hopPermit = hop.claimHopPermit(); if (hopPermit && intent.targetKey !== budget.lastTargetKey) { // The rotated credential can select a different regional endpoint. Replace the // provisional booking synchronously so the actual destination obeys transition // limits, while the physical send is still charged only once. hopPermit.release(); return budget.reserveDispatch({ ...intent, sendClass: hopPermit.sendClass }); } // Reservation precedes pacing and beforeDispatch. Transfer the exact open booking; // only physical consumption closes external reporting and makes it non-refundable. // The underlying permit enforces single use, including settlement by another owner. if (hopPermit !== undefined) { if (legacyHopReplacement) { let settled = false; let executionPermit = hopPermit; const confirm = (): boolean => { if (settled) return false; settled = true; if (hopPermit.assumeCharge()) return true; // Preserve the old fallback for a permit another leg already settled. const fresh = budget.reserveDispatch(intent); if (!fresh.allowed) return false; executionPermit = fresh.permit; return fresh.permit.assumeCharge(); }; return { allowed: true, permit: { sendClass: hopPermit.sendClass, execute: run => executionPermit.execute ? executionPermit.execute(run) : run(), use: confirm, assumeCharge: confirm, release: () => { if (!settled) { settled = true; hopPermit.release(); } }, } }; } return { allowed: true, permit: { sendClass: hopPermit.sendClass, execute: run => hopPermit.execute ? hopPermit.execute(run) : run(), use: () => hopPermit.assumeCharge(), assumeCharge: () => hopPermit.assumeCharge(), release: () => hopPermit.release(), } }; } } return budget.reserveDispatch(intent); }, }; }