@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
text/typescript
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);
},
};
}