@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,063 lines (983 loc) • 39.1 kB
text/typescript
import type {
CodexPreStreamRejection,
CodexResetEligibleExhaustionCode,
} from "./quota-rejection";
import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
export type CodexResetCreditRecoveryGeneration = Readonly<{
accountId: string;
credentialGeneration: number;
exhaustionGeneration: number;
}>;
export type CodexResetCreditRevalidationResult =
| Readonly<{
kind: "eligible";
accountId: string;
credentialGeneration: number;
exhaustionGeneration: number;
availableCredits: number;
}>
| { kind: "stale-generation" }
| { kind: "no-credit" };
export type CodexResetCreditConsumeCode =
| "reset"
| "already_redeemed"
| "nothing_to_reset"
| "no_credit";
declare const CODEX_RESERVED_OPERATION_ID_BRAND: unique symbol;
/** An operation id whose durable reservation was validated by the operation ledger. */
export type CodexReservedOperationId = string & {
readonly [CODEX_RESERVED_OPERATION_ID_BRAND]: true;
};
export const CODEX_RESET_CREDIT_OPERATION_ID_PATTERN =
/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
export function isCodexResetCreditOperationId(value: unknown): value is string {
return typeof value === "string" && CODEX_RESET_CREDIT_OPERATION_ID_PATTERN.test(value);
}
export type CodexResetCreditRecoveryAuthorization = Readonly<{
enabled: boolean;
/**
* Live commitment guard; checked initially, before dispatch, and on completion.
* Once it reports true, the adapter must keep reporting true for this turn.
*/
isOutputExposed: () => boolean;
rejection: CodexPreStreamRejection;
}>;
export type CodexResetCreditDispatchOutcome =
| Readonly<{ kind: "refresh-required"; code: "reset" | "already_redeemed" }>
| Readonly<{ kind: "stopped"; code: "nothing_to_reset" | "no_credit" }>
| Readonly<{
kind: "ambiguous";
reason: "consume-failed" | "consume-timeout" | "invalid-outcome";
operationId: string;
}>;
export type CodexResetCreditRecoveryResult =
| CodexResetCreditDispatchOutcome
| Readonly<{
kind: "not-dispatched";
reason:
| "disabled"
| "output-already-exposed"
| "ineligible-rejection"
| "cancelled-before-dispatch"
| "stale-generation"
| "no-credit-after-revalidate"
| "revalidation-failed"
| "invalid-revalidation"
| "coordination-mismatch"
| "recovery-state-capacity"
| "operation-expired-before-dispatch";
}>
| Readonly<{
kind: "detached";
reason: "cancelled-after-dispatch" | "output-exposed-after-dispatch";
outcome: CodexResetCreditDispatchOutcome;
}>;
export interface CodexResetCreditLogicalTurn {
readonly operationId: string;
}
export type CodexResetCreditRecoveryCapacity = Readonly<{
/** Outstanding adapter executions, including timed-out work that has not settled. */
activeFlights: number;
trackedAccounts: number;
}>;
export type CodexResetCreditRecoveryDependencies = {
/**
* Stable process-wide identity for one adapter contract. Coordinators may
* share a generation flight only when this identity and every executable
* dependency are identical.
*/
coordinationScope: object;
/** Revalidates both the supplied generations and current credit availability. */
revalidate: (
generation: CodexResetCreditRecoveryGeneration,
signal: AbortSignal,
) => Promise<unknown>;
/**
* Dispatches one irreversible consume operation. The normalized result must
* echo the supplied operationId so already_redeemed is generation-bound.
* Revalidation and consume adapters must settle promptly when their signal
* aborts; JavaScript cannot forcibly stop an adapter that ignores it.
*/
consume: (input: {
generation: CodexResetCreditRecoveryGeneration;
operationId: string;
signal: AbortSignal;
}) => Promise<unknown>;
/** Shared shutdown signal; callers may add a request/client signal per turn. */
lifecycleSignal?: AbortSignal;
/** Total revalidation plus consume deadline. Defaults to 10 seconds. */
operationTimeoutMs?: number;
/** Bounded consume transport attempts using the same operationId. Defaults to 2. */
maxConsumeAttempts?: number;
/** Count-only operational signal; account and operation identifiers are omitted. */
onCapacitySaturated?: (capacity: CodexResetCreditRecoveryCapacity) => void;
};
type LogicalTurnState = {
attempt?: Promise<CodexResetCreditRecoveryResult>;
};
type OutputGuardRegistration = Readonly<{
guard: () => boolean;
}>;
type RecoveryFlight = {
generation: CodexResetCreditRecoveryGeneration;
operationId: string;
contract: RecoveryContract;
activeWaiters: number;
dispatchStarted: boolean;
expired: boolean;
finished: boolean;
executionSettled: boolean;
discardedForTests: boolean;
preDispatchAbort: AbortController;
operationAbort: AbortController;
outputGuards: Set<OutputGuardRegistration>;
deadlineTimer?: ReturnType<typeof setTimeout>;
executionPromise?: Promise<Awaited<RecoveryFlight["promise"]>>;
resetForTestsResolve?: (result: Awaited<RecoveryFlight["promise"]>) => void;
promise: Promise<CodexResetCreditDispatchOutcome | Extract<
CodexResetCreditRecoveryResult,
{ kind: "not-dispatched" }
>>;
};
type RecoveryContract = Readonly<{
coordinationScope: object;
revalidate: CodexResetCreditRecoveryDependencies["revalidate"];
consume: CodexResetCreditRecoveryDependencies["consume"];
lifecycleSignal?: AbortSignal;
operationTimeoutMs: number;
maxConsumeAttempts: number;
}>;
type TerminalGeneration = {
generation: CodexResetCreditRecoveryGeneration;
outcome: CodexResetCreditDispatchOutcome;
contract: RecoveryContract;
};
const DEFAULT_OPERATION_TIMEOUT_MS = 10_000;
export const MAX_OPERATION_TIMEOUT_MS = 60_000;
const DEFAULT_MAX_CONSUME_ATTEMPTS = 2;
export const MAX_TRACKED_RECOVERY_ACCOUNTS = 128;
export const MAX_TRACKED_RECOVERY_FLIGHTS = 128;
export const MAX_TRACKED_RECOVERY_WAITERS_PER_FLIGHT = 128;
const RESET_PROCESS_STATE_FOR_TESTS = Symbol("reset-credit-recovery-process-state-for-tests");
const OPERATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
const ADD_EVENT_LISTENER = EventTarget.prototype.addEventListener;
const REMOVE_EVENT_LISTENER = EventTarget.prototype.removeEventListener;
function freezeResult<T extends CodexResetCreditRecoveryResult>(result: T): T {
return Object.freeze(result);
}
const CANCELLED_BEFORE_DISPATCH = freezeResult({
kind: "not-dispatched",
reason: "cancelled-before-dispatch",
} as const);
const CONSUME_CODES: ReadonlySet<string> = new Set([
"reset",
"already_redeemed",
"nothing_to_reset",
"no_credit",
]);
const RESET_ELIGIBLE_CODES = {
usage_limit_exceeded: true,
insufficient_quota: true,
} as const satisfies Record<CodexResetEligibleExhaustionCode, true>;
export function snapshotCodexResetCreditRecoveryGeneration(
input: unknown,
): CodexResetCreditRecoveryGeneration {
if (!input || typeof input !== "object" || Array.isArray(input)) {
throw new TypeError("generation must be an object");
}
const value = input as Record<string, unknown>;
const hasOwn = Object.prototype.hasOwnProperty;
if (!hasOwn.call(value, "accountId")
|| !hasOwn.call(value, "credentialGeneration")
|| !hasOwn.call(value, "exhaustionGeneration")) {
throw new TypeError("generation fields must be own properties");
}
const accountId = value.accountId;
const credentialGeneration = value.credentialGeneration;
const exhaustionGeneration = value.exhaustionGeneration;
if (accountId !== MAIN_CODEX_ACCOUNT_ID && !isValidCodexAccountId(accountId)) {
throw new TypeError("accountId must be the main sentinel or a canonical pool-account id");
}
if (!Number.isSafeInteger(credentialGeneration) || Number(credentialGeneration) < 0) {
throw new TypeError("credentialGeneration must be a non-negative safe integer");
}
if (!Number.isSafeInteger(exhaustionGeneration) || Number(exhaustionGeneration) < 0) {
throw new TypeError("exhaustionGeneration must be a non-negative safe integer");
}
return Object.freeze({
accountId,
credentialGeneration: credentialGeneration as number,
exhaustionGeneration: exhaustionGeneration as number,
});
}
function snapshotRequestSignal(input: unknown): AbortSignal | undefined {
if (!input || typeof input !== "object" || Array.isArray(input)) {
throw new TypeError("options must be an object");
}
const signal = (input as { signal?: unknown }).signal;
if (signal !== undefined && !(signal instanceof AbortSignal)) {
throw new TypeError("options.signal must be an AbortSignal");
}
return signal;
}
function generationKey(generation: CodexResetCreditRecoveryGeneration): string {
return JSON.stringify([
generation.accountId,
generation.credentialGeneration,
generation.exhaustionGeneration,
]);
}
function compareGenerationOrder(
left: CodexResetCreditRecoveryGeneration,
right: CodexResetCreditRecoveryGeneration,
): -1 | 0 | 1 {
if (left.credentialGeneration !== right.credentialGeneration) {
return left.credentialGeneration < right.credentialGeneration ? -1 : 1;
}
if (left.exhaustionGeneration !== right.exhaustionGeneration) {
return left.exhaustionGeneration < right.exhaustionGeneration ? -1 : 1;
}
return 0;
}
export const compareCodexResetCreditRecoveryGenerationOrder = compareGenerationOrder;
function authorizedResetRejection(authorization: CodexResetCreditRecoveryAuthorization): boolean {
const hasOwn = Object.prototype.hasOwnProperty;
if (!hasOwn.call(authorization, "enabled")
|| !hasOwn.call(authorization, "rejection")) {
return false;
}
const rejection = authorization.rejection as unknown;
if (!rejection || typeof rejection !== "object" || Array.isArray(rejection)) return false;
const value = rejection as Record<string, unknown>;
if (!hasOwn.call(value, "status")
|| !hasOwn.call(value, "kind")
|| !hasOwn.call(value, "resetCreditEligible")
|| !hasOwn.call(value, "semanticCode")) {
return false;
}
return authorization.enabled === true
&& (value.status === 429 || value.status === 402)
&& value.kind === "reset-eligible-exhaustion"
&& value.resetCreditEligible === true
&& typeof value.semanticCode === "string"
&& Object.hasOwn(RESET_ELIGIBLE_CODES, value.semanticCode);
}
function ownStringField(input: unknown, field: string): string | undefined {
if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
if (!Object.prototype.hasOwnProperty.call(input, field)) return undefined;
const value = (input as Record<string, unknown>)[field];
return typeof value === "string" ? value : undefined;
}
function revalidationKind(
input: unknown,
expected: CodexResetCreditRecoveryGeneration,
): CodexResetCreditRevalidationResult["kind"] | undefined {
const kind = ownStringField(input, "kind");
if (kind === "stale-generation" || kind === "no-credit") return kind;
if (kind !== "eligible" || !input || typeof input !== "object" || Array.isArray(input)) {
return undefined;
}
const value = input as Record<string, unknown>;
const hasOwn = Object.prototype.hasOwnProperty;
if (!hasOwn.call(value, "accountId")
|| !hasOwn.call(value, "credentialGeneration")
|| !hasOwn.call(value, "exhaustionGeneration")
|| !hasOwn.call(value, "availableCredits")) {
return undefined;
}
const availableCredits = value.availableCredits;
return value.accountId === expected.accountId
&& value.credentialGeneration === expected.credentialGeneration
&& value.exhaustionGeneration === expected.exhaustionGeneration
&& typeof availableCredits === "number"
&& Number.isSafeInteger(availableCredits)
&& availableCredits > 0
? "eligible"
: undefined;
}
function outputIsExposed(guard: () => boolean): boolean {
try {
return guard() !== false;
} catch {
return true;
}
}
function hasLiveUnexposedGuard(flight: RecoveryFlight): boolean {
// Set iteration also visits registrations appended by a re-entrant guard.
// A one-time snapshot could strand a newly joined, still-live waiter.
// Bound those live additions so a guard cannot extend this synchronous loop
// forever. Exhaustion fails closed before the irreversible dispatch.
let remainingVisits = flight.outputGuards.size * 2 + 1;
for (const registration of flight.outputGuards) {
if (remainingVisits <= 0) return false;
remainingVisits -= 1;
if (outputIsExposed(registration.guard)) continue;
// A guard may synchronously abort and unregister its own waiter. Its stale
// return value must not authorize a different, already-exposed waiter.
if (flight.outputGuards.has(registration)) return true;
}
return false;
}
function expireRecoveryFlight(flight: RecoveryFlight): void {
flight.expired = true;
if (flight.dispatchStarted) flight.operationAbort.abort();
else flight.preDispatchAbort.abort();
}
function recoveryDeadlineExpired(flight: RecoveryFlight, deadlineAt: number): boolean {
if (!flight.expired && performance.now() < deadlineAt) return false;
expireRecoveryFlight(flight);
return true;
}
function recoveryContractsMatch(left: RecoveryContract, right: RecoveryContract): boolean {
return left.coordinationScope === right.coordinationScope
&& left.revalidate === right.revalidate
&& left.consume === right.consume
&& left.lifecycleSignal === right.lifecycleSignal
&& left.operationTimeoutMs === right.operationTimeoutMs
&& left.maxConsumeAttempts === right.maxConsumeAttempts;
}
function consumeCode(
input: unknown,
expectedOperationId: string,
): CodexResetCreditConsumeCode | undefined {
const code = ownStringField(input, "code");
const operationId = ownStringField(input, "operationId");
return code && CONSUME_CODES.has(code) && operationId === expectedOperationId
? code as CodexResetCreditConsumeCode
: undefined;
}
function mapConsumeOutcome(
input: unknown,
operationId: string,
): CodexResetCreditDispatchOutcome {
const code = consumeCode(input, operationId);
if (code === "reset" || code === "already_redeemed") {
// Replay is not authorized here. The caller must first refresh authoritative
// quota state and separately prove that its replay capsule is still valid.
return freezeResult({ kind: "refresh-required", code });
}
if (code === "nothing_to_reset" || code === "no_credit") {
return freezeResult({ kind: "stopped", code });
}
return freezeResult({ kind: "ambiguous", reason: "invalid-outcome", operationId });
}
function notDispatched(
reason: Extract<CodexResetCreditRecoveryResult, { kind: "not-dispatched" }>["reason"],
): Extract<CodexResetCreditRecoveryResult, { kind: "not-dispatched" }> {
return freezeResult({ kind: "not-dispatched", reason });
}
function isDispatchOutcome(
result: CodexResetCreditRecoveryResult,
): result is CodexResetCreditDispatchOutcome {
return result.kind === "refresh-required"
|| result.kind === "stopped"
|| result.kind === "ambiguous";
}
/**
* Proves reset-credit trigger, single-flight, idempotency, cancellation, and
* one-per-turn invariants without owning account selection, HTTP, or replay.
*
* Flight and terminal-generation registries are process-shared so independent
* request handlers cannot bypass the account/generation fence. This foundation
* is intentionally process-local; durable crash recovery belongs to the future
* HTTP adapter that persists and reuses the same operation identity. A future
* adapter for the main sentinel must advance or invalidate credentialGeneration
* whenever the physical ChatGPT identity changes.
*
* Terminal fences intentionally remain for the process lifetime. Time- or
* LRU-based eviction could re-authorize an uncertain irreversible consume. A
* runtime adapter must replace this bounded map with a durable generation-aware
* ledger before supporting more accounts; only an authoritative idempotency and
* replay-window contract may define safe retirement. Timed-out adapter work is
* retired from the public flight registry so its waiters settle, but remains in
* the orphan registry until the adapter settles. It still counts toward both
* MAX_TRACKED_RECOVERY_FLIGHTS and MAX_TRACKED_RECOVERY_ACCOUNTS, so an
* abort-ignoring adapter withholds admission instead of allowing unbounded work.
*/
export class CodexResetCreditRecoveryCoordinator {
private static readonly activeFlights = new Map<string, RecoveryFlight>();
/** Public flight promises that still participate in admission capacity. */
private static readonly allFlights = new Set<RecoveryFlight>();
/** Bounded bookkeeping for adapter executions that outlive public deadlines. */
private static readonly orphanedFlights = new Set<RecoveryFlight>();
private static readonly terminalByAccount = new Map<string, TerminalGeneration>();
private readonly logicalTurns = new WeakMap<CodexResetCreditLogicalTurn, LogicalTurnState>();
private readonly operationTimeoutMs: number;
private readonly maxConsumeAttempts: number;
private readonly contract: RecoveryContract;
private readonly onCapacitySaturated?: CodexResetCreditRecoveryDependencies["onCapacitySaturated"];
constructor(dependencies: CodexResetCreditRecoveryDependencies) {
const coordinationScope = dependencies.coordinationScope;
if (coordinationScope === null
|| (typeof coordinationScope !== "object"
&& typeof coordinationScope !== "function")) {
throw new TypeError("coordinationScope must be a stable object identity");
}
const revalidate = dependencies.revalidate;
const consume = dependencies.consume;
if (typeof revalidate !== "function") {
throw new TypeError("revalidate must be a function");
}
if (typeof consume !== "function") {
throw new TypeError("consume must be a function");
}
const lifecycleSignal = dependencies.lifecycleSignal;
if (lifecycleSignal !== undefined && !(lifecycleSignal instanceof AbortSignal)) {
throw new TypeError("lifecycleSignal must be an AbortSignal");
}
this.operationTimeoutMs = dependencies.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS;
this.maxConsumeAttempts = dependencies.maxConsumeAttempts ?? DEFAULT_MAX_CONSUME_ATTEMPTS;
if (!Number.isSafeInteger(this.operationTimeoutMs)
|| this.operationTimeoutMs <= 0
|| this.operationTimeoutMs > MAX_OPERATION_TIMEOUT_MS) {
throw new TypeError("operationTimeoutMs must be an integer from 1 to 60000");
}
if (!Number.isSafeInteger(this.maxConsumeAttempts)
|| this.maxConsumeAttempts < 1
|| this.maxConsumeAttempts > 3) {
throw new TypeError("maxConsumeAttempts must be an integer from 1 to 3");
}
this.contract = Object.freeze({
coordinationScope,
revalidate,
consume,
lifecycleSignal,
operationTimeoutMs: this.operationTimeoutMs,
maxConsumeAttempts: this.maxConsumeAttempts,
});
this.onCapacitySaturated = dependencies.onCapacitySaturated;
}
createLogicalTurn(): CodexResetCreditLogicalTurn {
const operationId = crypto.randomUUID();
if (!OPERATION_ID_PATTERN.test(operationId)) {
throw new TypeError("operationId must be an RFC 4122 version 4 UUID");
}
const turn = Object.freeze({ operationId });
this.logicalTurns.set(turn, {});
return turn;
}
recover(
turn: CodexResetCreditLogicalTurn,
generation: CodexResetCreditRecoveryGeneration,
authorization: CodexResetCreditRecoveryAuthorization,
options: { signal?: AbortSignal } = {},
): Promise<CodexResetCreditRecoveryResult> {
const turnState = this.logicalTurns.get(turn);
if (!turnState) throw new TypeError("logical turn was not created by this coordinator");
if (turnState.attempt) return turnState.attempt;
let resolveAttempt!: (result: CodexResetCreditRecoveryResult) => void;
let rejectAttempt!: (reason?: unknown) => void;
const attempt = new Promise<CodexResetCreditRecoveryResult>((resolve, reject) => {
resolveAttempt = resolve;
rejectAttempt = reject;
});
// Reserve the logical turn before reading caller-supplied option or generation
// accessors or invoking an output guard. A synchronous re-entry must observe this
// exact promise instead of creating a second flight with the same operation identity.
turnState.attempt = attempt;
let generationSnapshot: CodexResetCreditRecoveryGeneration;
let requestSignal: AbortSignal | undefined;
try {
requestSignal = snapshotRequestSignal(options);
generationSnapshot = snapshotCodexResetCreditRecoveryGeneration(generation);
} catch (error) {
rejectAttempt(error);
return attempt;
}
try {
void this.startReservedAttempt(
turn,
generationSnapshot,
authorization,
requestSignal,
).then(resolveAttempt, rejectAttempt);
} catch (error) {
rejectAttempt(error);
}
return attempt;
}
private startReservedAttempt(
turn: CodexResetCreditLogicalTurn,
generationSnapshot: CodexResetCreditRecoveryGeneration,
authorization: CodexResetCreditRecoveryAuthorization,
requestSignal: AbortSignal | undefined,
): Promise<CodexResetCreditRecoveryResult> {
if (authorization.enabled !== true) {
return Promise.resolve(notDispatched("disabled"));
}
if (outputIsExposed(authorization.isOutputExposed)) {
return Promise.resolve(notDispatched("output-already-exposed"));
}
if (!authorizedResetRejection(authorization)) {
return Promise.resolve(notDispatched("ineligible-rejection"));
}
const signals = this.recoverySignals(requestSignal);
if (signals.some(signal => signal.aborted)) {
return Promise.resolve(CANCELLED_BEFORE_DISPATCH);
}
const key = generationKey(generationSnapshot);
const terminal = CodexResetCreditRecoveryCoordinator.terminalByAccount.get(
generationSnapshot.accountId,
);
if (terminal) {
if (!recoveryContractsMatch(terminal.contract, this.contract)) {
return Promise.resolve(notDispatched("coordination-mismatch"));
}
const order = compareGenerationOrder(generationSnapshot, terminal.generation);
if (order === 0) {
return this.resolveTerminalOutcome(
terminal.outcome,
signals,
authorization.isOutputExposed,
);
}
if (order < 0) {
return Promise.resolve(notDispatched("stale-generation"));
}
}
let flight = CodexResetCreditRecoveryCoordinator.activeFlights.get(key);
if (flight && !recoveryContractsMatch(flight.contract, this.contract)) {
return Promise.resolve(notDispatched("coordination-mismatch"));
}
if (flight
&& !flight.dispatchStarted
&& (flight.preDispatchAbort.signal.aborted || flight.activeWaiters === 0)) {
return Promise.resolve(CANCELLED_BEFORE_DISPATCH);
}
if (!flight) {
if (!this.hasFlightCapacity(
generationSnapshot.accountId,
)) {
return Promise.resolve(notDispatched("recovery-state-capacity"));
}
flight = this.createFlight(key, generationSnapshot, turn.operationId);
CodexResetCreditRecoveryCoordinator.activeFlights.set(key, flight);
}
if (flight.activeWaiters >= MAX_TRACKED_RECOVERY_WAITERS_PER_FLIGHT) {
this.reportCapacitySaturated(this.trackedCapacity());
return Promise.resolve(notDispatched("recovery-state-capacity"));
}
return this.joinFlight(flight, signals, authorization.isOutputExposed);
}
/** Exposes no flight contents; intended for deterministic cleanup tests. */
activeFlightCountForTests(): number {
return CodexResetCreditRecoveryCoordinator.allFlights.size;
}
terminalGenerationCountForTests(): number {
return CodexResetCreditRecoveryCoordinator.terminalByAccount.size;
}
async waitForIdleForTests(): Promise<void> {
for (;;) {
const flights = [...new Set([
...CodexResetCreditRecoveryCoordinator.allFlights,
...CodexResetCreditRecoveryCoordinator.orphanedFlights,
])];
if (flights.length === 0) return;
await Promise.allSettled(flights.flatMap(flight => [
flight.promise,
...(flight.executionPromise ? [flight.executionPromise] : []),
]));
}
}
static async [RESET_PROCESS_STATE_FOR_TESTS](): Promise<void> {
if (process.env.OCX_TEST_HOME_GUARD !== "1") {
throw new Error("resetProcessStateForTests is available only under the repository test preload");
}
const flights = [...new Set([...this.allFlights, ...this.orphanedFlights])];
for (const flight of flights) {
flight.discardedForTests = true;
flight.expired = true;
if (flight.deadlineTimer !== undefined) {
clearTimeout(flight.deadlineTimer);
flight.deadlineTimer = undefined;
}
flight.preDispatchAbort.abort();
flight.operationAbort.abort();
flight.resetForTestsResolve?.(flight.dispatchStarted
? freezeResult({
kind: "ambiguous",
reason: "consume-timeout",
operationId: flight.operationId,
})
: CANCELLED_BEFORE_DISPATCH);
}
this.activeFlights.clear();
this.terminalByAccount.clear();
await Promise.allSettled(flights.map(flight => flight.promise));
// An adapter may ignore its abort signal forever. Test reset must detach
// that handled execution after marking it discarded instead of hanging the
// entire suite; waitForIdleForTests drains every retained execution.
await Promise.resolve();
for (const flight of flights) {
this.allFlights.delete(flight);
this.orphanedFlights.delete(flight);
}
this.activeFlights.clear();
this.terminalByAccount.clear();
}
private static retireFlightWhenSettled(flight: RecoveryFlight): void {
if (!flight.finished) return;
this.allFlights.delete(flight);
if (flight.executionSettled) this.orphanedFlights.delete(flight);
else this.orphanedFlights.add(flight);
}
private trackedCapacity(): {
outstandingExecutions: number;
trackedAccounts: Set<string>;
} {
const outstandingFlights = new Set([
...CodexResetCreditRecoveryCoordinator.allFlights,
...CodexResetCreditRecoveryCoordinator.orphanedFlights,
]);
const trackedAccounts = new Set(
CodexResetCreditRecoveryCoordinator.terminalByAccount.keys(),
);
for (const flight of outstandingFlights) {
trackedAccounts.add(flight.generation.accountId);
}
return { outstandingExecutions: outstandingFlights.size, trackedAccounts };
}
private reportCapacitySaturated(capacity: {
outstandingExecutions: number;
trackedAccounts: Set<string>;
}): void {
try {
this.onCapacitySaturated?.(Object.freeze({
activeFlights: capacity.outstandingExecutions,
trackedAccounts: capacity.trackedAccounts.size,
}));
} catch {
// Operational reporting must never weaken the fail-closed capacity result.
}
}
private hasFlightCapacity(accountId: string): boolean {
const capacity = this.trackedCapacity();
const allowed = capacity.outstandingExecutions < MAX_TRACKED_RECOVERY_FLIGHTS
&& (capacity.trackedAccounts.has(accountId)
|| capacity.trackedAccounts.size < MAX_TRACKED_RECOVERY_ACCOUNTS);
if (!allowed) this.reportCapacitySaturated(capacity);
return allowed;
}
private recoverySignals(requestSignal?: AbortSignal): AbortSignal[] {
return [...new Set(
[requestSignal, this.contract.lifecycleSignal]
.filter((signal): signal is AbortSignal => signal !== undefined),
)];
}
private resolveTerminalOutcome(
outcome: CodexResetCreditDispatchOutcome,
signals: readonly AbortSignal[],
outputGuard: () => boolean,
): Promise<CodexResetCreditRecoveryResult> {
return Promise.resolve().then(() => {
if (signals.some(signal => signal.aborted)) {
return freezeResult({
kind: "detached",
reason: "cancelled-after-dispatch",
outcome,
} as const);
}
const outputExposed = outputIsExposed(outputGuard);
if (signals.some(signal => signal.aborted)) {
return freezeResult({
kind: "detached",
reason: "cancelled-after-dispatch",
outcome,
} as const);
}
if (outputExposed) {
return freezeResult({
kind: "detached",
reason: "output-exposed-after-dispatch",
outcome,
} as const);
}
return outcome;
});
}
private createFlight(
key: string,
generation: CodexResetCreditRecoveryGeneration,
operationId: string,
): RecoveryFlight {
const flight: RecoveryFlight = {
generation: Object.freeze({ ...generation }),
operationId,
contract: this.contract,
activeWaiters: 0,
dispatchStarted: false,
expired: false,
finished: false,
executionSettled: false,
discardedForTests: false,
preDispatchAbort: new AbortController(),
operationAbort: new AbortController(),
outputGuards: new Set(),
promise: undefined as unknown as RecoveryFlight["promise"],
};
CodexResetCreditRecoveryCoordinator.allFlights.add(flight);
// Start on the next microtask so the creating caller joins before
// revalidation can observe the active-waiter count.
flight.promise = Promise.resolve()
.then(() => this.runFlightWithDeadline(flight))
.catch(() => (
flight.dispatchStarted
? freezeResult({
kind: "ambiguous",
reason: "consume-failed",
operationId: flight.operationId,
} as const)
: notDispatched("revalidation-failed")
))
.then(result => {
if (!flight.discardedForTests && isDispatchOutcome(result)) {
const current = CodexResetCreditRecoveryCoordinator.terminalByAccount.get(
flight.generation.accountId,
);
if (!current || compareGenerationOrder(flight.generation, current.generation) > 0) {
CodexResetCreditRecoveryCoordinator.terminalByAccount.set(
flight.generation.accountId,
{ generation: flight.generation, outcome: result, contract: flight.contract },
);
}
}
return result;
})
.finally(() => {
flight.finished = true;
CodexResetCreditRecoveryCoordinator.retireFlightWhenSettled(flight);
if (CodexResetCreditRecoveryCoordinator.activeFlights.get(key) === flight) {
CodexResetCreditRecoveryCoordinator.activeFlights.delete(key);
}
});
return flight;
}
private async runFlightWithDeadline(
flight: RecoveryFlight,
): Promise<Awaited<RecoveryFlight["promise"]>> {
if (flight.discardedForTests) {
flight.executionSettled = true;
return CANCELLED_BEFORE_DISPATCH;
}
const deadlineAt = performance.now() + flight.contract.operationTimeoutMs;
const execution = this.runFlight(flight, deadlineAt);
flight.executionPromise = execution;
void execution.then(
() => {
flight.executionSettled = true;
CodexResetCreditRecoveryCoordinator.retireFlightWhenSettled(flight);
},
() => {
flight.executionSettled = true;
CodexResetCreditRecoveryCoordinator.retireFlightWhenSettled(flight);
},
);
const deadline = new Promise<Awaited<RecoveryFlight["promise"]>>(resolve => {
flight.deadlineTimer = setTimeout(() => {
expireRecoveryFlight(flight);
if (!flight.dispatchStarted) {
resolve(notDispatched("operation-expired-before-dispatch"));
return;
}
resolve(freezeResult({
kind: "ambiguous",
reason: "consume-timeout",
operationId: flight.operationId,
}));
}, Math.max(0, deadlineAt - performance.now()));
});
const resetForTests = new Promise<Awaited<RecoveryFlight["promise"]>>(resolve => {
flight.resetForTestsResolve = resolve;
});
try {
return await Promise.race([execution, deadline, resetForTests]);
} finally {
if (flight.deadlineTimer !== undefined) {
clearTimeout(flight.deadlineTimer);
flight.deadlineTimer = undefined;
}
flight.resetForTestsResolve = undefined;
}
}
private async runFlight(
flight: RecoveryFlight,
deadlineAt: number,
): Promise<Awaited<RecoveryFlight["promise"]>> {
if (flight.preDispatchAbort.signal.aborted || flight.activeWaiters === 0) {
return CANCELLED_BEFORE_DISPATCH;
}
let revalidation: unknown;
try {
revalidation = await flight.contract.revalidate(
flight.generation,
flight.preDispatchAbort.signal,
);
} catch {
if (flight.preDispatchAbort.signal.aborted && flight.activeWaiters === 0) {
return CANCELLED_BEFORE_DISPATCH;
}
if (recoveryDeadlineExpired(flight, deadlineAt)) {
return notDispatched("operation-expired-before-dispatch");
}
return notDispatched("revalidation-failed");
}
if (flight.preDispatchAbort.signal.aborted || flight.activeWaiters === 0) {
return CANCELLED_BEFORE_DISPATCH;
}
const kind = revalidationKind(revalidation, flight.generation);
if (kind === "stale-generation") return notDispatched("stale-generation");
if (kind === "no-credit") return notDispatched("no-credit-after-revalidate");
if (kind !== "eligible") return notDispatched("invalid-revalidation");
if (!hasLiveUnexposedGuard(flight)) {
return notDispatched("output-already-exposed");
}
if (recoveryDeadlineExpired(flight, deadlineAt)) {
return notDispatched("operation-expired-before-dispatch");
}
if (flight.preDispatchAbort.signal.aborted || flight.activeWaiters === 0) {
return CANCELLED_BEFORE_DISPATCH;
}
// No await is allowed between this final commitment check and marking the
// irreversible dispatch. That closes the last pre-dispatch cancellation race.
flight.dispatchStarted = true;
for (let attempt = 1; attempt <= flight.contract.maxConsumeAttempts; attempt += 1) {
if (recoveryDeadlineExpired(flight, deadlineAt)) {
return freezeResult({
kind: "ambiguous",
reason: "consume-timeout",
operationId: flight.operationId,
});
}
try {
const outcome = await flight.contract.consume({
generation: flight.generation,
operationId: flight.operationId,
signal: flight.operationAbort.signal,
});
const mappedOutcome = mapConsumeOutcome(outcome, flight.operationId);
if (recoveryDeadlineExpired(flight, deadlineAt)) {
return freezeResult({
kind: "ambiguous",
reason: "consume-timeout",
operationId: flight.operationId,
});
}
return mappedOutcome;
} catch {
if (recoveryDeadlineExpired(flight, deadlineAt)) {
return freezeResult({
kind: "ambiguous",
reason: "consume-timeout",
operationId: flight.operationId,
});
}
if (attempt === flight.contract.maxConsumeAttempts) {
return freezeResult({
kind: "ambiguous",
reason: "consume-failed",
operationId: flight.operationId,
});
}
}
}
return freezeResult({
kind: "ambiguous",
reason: "consume-failed",
operationId: flight.operationId,
});
}
private joinFlight(
flight: RecoveryFlight,
signals: readonly AbortSignal[],
outputGuard: () => boolean,
): Promise<CodexResetCreditRecoveryResult> {
flight.activeWaiters += 1;
const outputGuardRegistration = Object.freeze({ guard: outputGuard });
flight.outputGuards.add(outputGuardRegistration);
return new Promise((resolve, reject) => {
let settled = false;
let counted = true;
let detachedAfterDispatch = false;
const registeredSignals: AbortSignal[] = [];
const releasePreDispatchWaiter = () => {
if (!counted) return;
counted = false;
if (flight.dispatchStarted) return;
flight.activeWaiters = Math.max(0, flight.activeWaiters - 1);
flight.outputGuards.delete(outputGuardRegistration);
if (flight.activeWaiters === 0 && !flight.finished) {
flight.preDispatchAbort.abort();
}
};
const removeAbortListeners = () => {
for (const signal of registeredSignals) {
try {
REMOVE_EVENT_LISTENER.call(signal, "abort", onAbort);
} catch {
// Waiter state still rolls back if a caller overrides EventTarget methods.
}
}
registeredSignals.length = 0;
};
const finish = (result: Awaited<RecoveryFlight["promise"]>) => {
if (settled) return;
settled = true;
if (!flight.dispatchStarted) releasePreDispatchWaiter();
if (isDispatchOutcome(result)) {
const outputExposed = outputIsExposed(outputGuard);
const cancelled = detachedAfterDispatch
|| signals.some(signal => signal.aborted);
removeAbortListeners();
if (!cancelled && !outputExposed) {
resolve(result);
return;
}
resolve(freezeResult({
kind: "detached",
reason: cancelled
? "cancelled-after-dispatch"
: "output-exposed-after-dispatch",
outcome: result,
}));
return;
}
removeAbortListeners();
resolve(result);
};
const onAbort = () => {
if (flight.dispatchStarted) {
detachedAfterDispatch = true;
return;
}
releasePreDispatchWaiter();
finish(CANCELLED_BEFORE_DISPATCH);
};
try {
for (const signal of signals) {
registeredSignals.push(signal);
ADD_EVENT_LISTENER.call(signal, "abort", onAbort, { once: true });
}
} catch (error) {
settled = true;
releasePreDispatchWaiter();
removeAbortListeners();
reject(error);
return;
}
if (signals.some(signal => signal.aborted)) onAbort();
void flight.promise.then(finish, () => {
finish(flight.dispatchStarted
? freezeResult({
kind: "ambiguous",
reason: "consume-failed",
operationId: flight.operationId,
})
: notDispatched("revalidation-failed"));
});
});
}
}
/** @internal Test-support entry point; unavailable without the repository preload. */
export async function resetCodexResetCreditRecoveryProcessStateForTests(): Promise<void> {
await CodexResetCreditRecoveryCoordinator[RESET_PROCESS_STATE_FOR_TESTS]();
}