@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
311 lines (285 loc) • 14.8 kB
text/typescript
import { createHash, randomUUID } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { ConfigMutationLockError, withConfigMutationLockSync } from "../config";
import { atomicWriteFile } from "../config/atomic-write";
import { getConfigDir } from "../config/paths";
import { registerOptionalShutdownHook } from "../lib/optional-shutdown-hooks";
import type { OcxConfig } from "../types";
/**
* Opt-in auto-redemption of a Codex reset credit shortly before it expires (#822).
*
* Default off. When enabled, the nearest unexpired credit for the main Codex account is
* redeemed `leadTimeMinutes` before its `expires_at`. Every fire re-reads the upstream credit
* list first and dispatches only when the same credit (granted_at + expires_at) is still
* present, so a credit the operator already spent by hand is never redeemed twice. The
* `redeem_request_id` for a credit identity is minted once and journaled to disk before the
* consume call, so a crash between dispatch and settle replays the same idempotent request
* instead of spending a second credit. Logs carry a hashed account key only.
*/
export interface ResetCreditAutoRedeemSettings {
enabled: boolean;
leadTimeMinutes: number;
}
export const DEFAULT_LEAD_TIME_MINUTES = 10;
export const MIN_LEAD_TIME_MINUTES = 1;
export const MAX_LEAD_TIME_MINUTES = 60;
export function resolveResetCreditAutoRedeemSettings(config: Pick<OcxConfig, "resetCreditAutoRedeem">): ResetCreditAutoRedeemSettings {
const raw = config.resetCreditAutoRedeem;
if (!raw || raw.enabled !== true) return { enabled: false, leadTimeMinutes: DEFAULT_LEAD_TIME_MINUTES };
const lead = typeof raw.leadTimeMinutes === "number" && Number.isInteger(raw.leadTimeMinutes)
? Math.min(Math.max(raw.leadTimeMinutes, MIN_LEAD_TIME_MINUTES), MAX_LEAD_TIME_MINUTES)
: DEFAULT_LEAD_TIME_MINUTES;
return { enabled: true, leadTimeMinutes: lead };
}
export interface ResetCredit {
granted_at: string;
/** Null for a credit that does not expire; never planned, but it can still be consumed first. */
expires_at: string | null;
}
export interface AutoRedeemPlan {
/** Stable identity of the credit being protected. */
grantedAt: string;
expiresAt: string;
/** Epoch ms at which the redeem should be attempted. */
dueAt: number;
}
/** Pick the credit that expires soonest and is still in the future; null when nothing qualifies. */
export function planAutoRedeem(now: number, credits: readonly ResetCredit[], settings: ResetCreditAutoRedeemSettings): AutoRedeemPlan | null {
if (!settings.enabled) return null;
let best: AutoRedeemPlan | null = null;
for (const credit of credits) {
if (credit.expires_at === null) continue;
// A credit without a usable grant time has no identity to protect: never plan it. It still
// blocks other plans through olderCreditPrecedes.
if (!Number.isFinite(Date.parse(credit.granted_at))) continue;
const expires = Date.parse(credit.expires_at);
if (!Number.isFinite(expires) || expires <= now) continue;
const dueAt = expires - settings.leadTimeMinutes * 60_000;
const expiresAt = credit.expires_at;
if (!best || expires < Date.parse(best.expiresAt)) best = { grantedAt: credit.granted_at, expiresAt, dueAt };
}
return best;
}
export function creditStillPresent(credits: readonly ResetCredit[], plan: Pick<AutoRedeemPlan, "grantedAt" | "expiresAt">): boolean {
return credits.some(c => c.granted_at === plan.grantedAt && c.expires_at === plan.expiresAt);
}
/**
* Consume names no credit, and the dashboard tells operators the oldest is used first. A credit
* granted before the planned one (a non-expiring one, or any with a later expiry) could be spent
* in its place while the planned credit still expires, so the redeemer stands down instead.
*/
export function olderCreditPrecedes(credits: readonly ResetCredit[], plan: Pick<AutoRedeemPlan, "grantedAt" | "expiresAt">): boolean {
const planned = Date.parse(plan.grantedAt);
if (!Number.isFinite(planned)) return true;
// Fail closed: an equal grant time has no known tie-breaker, and a grant time that does not
// parse cannot be ordered at all, so either blocks dispatch just like an older credit.
// Exactly one row is the planned credit; a second identical row is a distinct credit and a tie.
let plannedSeen = false;
return credits.some(c => {
if (!plannedSeen && c.granted_at === plan.grantedAt && c.expires_at === plan.expiresAt) {
plannedSeen = true;
return false;
}
return !(Date.parse(c.granted_at) > planned);
});
}
interface JournalEntry {
accountKey: string;
grantedAt: string;
expiresAt: string;
redeemRequestId: string;
state: "dispatched" | "settled";
updatedAt: number;
}
interface Journal { version: 1; entries: JournalEntry[] }
export function journalPath(): string {
return join(getConfigDir(), "reset-credit-auto-redeem.json");
}
function readJournal(path: string): Journal {
if (!existsSync(path)) return { version: 1, entries: [] };
try {
const parsed = JSON.parse(readFileSync(path, "utf8")) as Journal;
return parsed && parsed.version === 1 && Array.isArray(parsed.entries) ? parsed : { version: 1, entries: [] };
} catch {
return { version: 1, entries: [] };
}
}
function writeJournal(path: string, journal: Journal, now: number): void {
// Keep only entries whose credit could still matter: settled ones older than a week are noise.
const cutoff = now - 7 * 24 * 60 * 60_000;
journal.entries = journal.entries.filter(e => e.state !== "settled" || e.updatedAt > cutoff);
atomicWriteFile(path, JSON.stringify(journal, null, 2));
}
export function hashAccountKey(accountId: string): string {
return createHash("sha256").update(accountId).digest("hex").slice(0, 12);
}
export interface AutoRedeemDeps {
accountId: string;
settings: () => ResetCreditAutoRedeemSettings;
/** Fresh upstream read of the credit list; throws on auth/transport failure. */
inspect: () => Promise<{ credits: ResetCredit[] }>;
/** Consume with a caller-owned idempotency key. Returns the upstream code. */
consume: (redeemRequestId: string) => Promise<{ code: string }>;
now?: () => number;
setTimer?: (fn: () => void, ms: number) => unknown;
clearTimer?: (handle: unknown) => void;
/** Callers sharing an overridden journal must also share the OPENCODEX_HOME mutation coordinator. */
journalFile?: string;
log?: (line: string) => void;
/** Upper bound on one sleep so a laptop sleep or clock jump re-checks rather than trusting a stale plan. */
maxSleepMs?: number;
/** Interval to re-inspect when no credit is due yet (default 30 min). */
idleRecheckMs?: number;
}
export type AutoRedeemOutcome =
| { kind: "disabled" }
| { kind: "nothing-to-protect" }
| { kind: "scheduled"; dueAt: number }
| { kind: "skipped"; reason: "credit-gone" | "disabled-before-dispatch" | "order-not-guaranteed" }
| { kind: "dispatched"; code: string; redeemRequestId: string }
| { kind: "ambiguous"; redeemRequestId: string }
| { kind: "error"; message: string };
export interface ResetCreditAutoRedeemer {
/** Inspect, and either dispatch (if due) or schedule the next check. */
tick(): Promise<AutoRedeemOutcome>;
start(): void;
stop(): void;
}
export function createResetCreditAutoRedeemer(deps: AutoRedeemDeps): ResetCreditAutoRedeemer {
const now = deps.now ?? (() => Date.now());
const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
const clearTimer = deps.clearTimer ?? (handle => clearTimeout(handle as ReturnType<typeof setTimeout>));
const log = deps.log ?? ((line: string) => console.log(line));
const path = deps.journalFile ?? journalPath();
const accountKey = hashAccountKey(deps.accountId);
const maxSleepMs = deps.maxSleepMs ?? 15 * 60_000;
const idleRecheckMs = deps.idleRecheckMs ?? 30 * 60_000;
let handle: unknown = null;
let stopped = false;
let inFlight: Promise<AutoRedeemOutcome> | null = null;
const schedule = (ms: number): void => {
if (stopped) return;
if (handle !== null) clearTimer(handle);
handle = setTimer(() => { handle = null; void tick(); }, Math.max(0, Math.min(ms, maxSleepMs)));
};
const retryJournal = (error: unknown): void => {
const cause = error instanceof ConfigMutationLockError ? error.cause : error;
const code = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
const busy = code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
|| (cause instanceof Error && /database (?:is|table is) locked/i.test(cause.message));
schedule(busy ? 1_000 : idleRecheckMs);
};
const dispatch = async (plan: AutoRedeemPlan): Promise<AutoRedeemOutcome> => {
// Reserve under the shared config-mutation lock. `inFlight` only serializes ticks inside
// ONE process; two servers on the same config dir would otherwise both read a journal with
// no entry, each mint a different `redeem_request_id`, and spend two credits for one plan.
let entry: JournalEntry;
try {
entry = withConfigMutationLockSync(() => {
const journal = readJournal(path);
const existing = journal.entries.find(e => e.accountKey === accountKey && e.grantedAt === plan.grantedAt && e.expiresAt === plan.expiresAt);
if (existing) return existing;
const created: JournalEntry = { accountKey, grantedAt: plan.grantedAt, expiresAt: plan.expiresAt, redeemRequestId: randomUUID(), state: "dispatched", updatedAt: now() };
journal.entries.push(created);
// Journal BEFORE the network call: a crash after this line replays the same request id.
writeJournal(path, journal, created.updatedAt);
return created;
});
} catch (error) {
// Only contention gets a short retry; persistent storage failures must not spin.
retryJournal(error);
return { kind: "error", message: error instanceof Error ? error.message : "journal reservation failed" };
}
if (entry.state === "settled") {
schedule(idleRecheckMs);
return { kind: "skipped", reason: "credit-gone" };
}
log(`[opencodex] reset-credit auto-redeem: dispatching for account ${accountKey} (credit expires ${plan.expiresAt})`);
let result: { code: string };
try {
result = await deps.consume(entry.redeemRequestId);
} catch (error) {
log(`[opencodex] reset-credit auto-redeem: consume uncertain for account ${accountKey}; will retry with the same request id`);
schedule(60_000);
return { kind: "ambiguous", redeemRequestId: entry.redeemRequestId };
}
// Re-read under the lock: a peer may have appended its own entries since the reservation,
// and writing a stale in-memory journal would drop them.
try {
withConfigMutationLockSync(() => {
const journal = readJournal(path);
const current = journal.entries.find(e => e.accountKey === accountKey && e.grantedAt === plan.grantedAt && e.expiresAt === plan.expiresAt);
if (!current || current.redeemRequestId !== entry.redeemRequestId) {
throw new Error("auto-redeem journal reservation changed before settlement");
}
current.state = "settled";
current.updatedAt = now();
writeJournal(path, journal, current.updatedAt);
});
} catch (error) {
// Upstream answered, but settlement could not be committed. Preserve any reservation;
// a later dispatch must reuse its request id. A vanished credit may never dispatch again.
retryJournal(error);
return { kind: "error", message: error instanceof Error ? error.message : "journal settlement failed" };
}
log(`[opencodex] reset-credit auto-redeem: upstream answered ${result.code} for account ${accountKey}`);
schedule(idleRecheckMs);
return { kind: "dispatched", code: result.code, redeemRequestId: entry.redeemRequestId };
};
const tick = async (): Promise<AutoRedeemOutcome> => {
if (inFlight) return inFlight;
inFlight = (async () => {
const settings = deps.settings();
if (!settings.enabled) return { kind: "disabled" } as AutoRedeemOutcome;
let credits: ResetCredit[];
try {
({ credits } = await deps.inspect());
} catch (error) {
schedule(idleRecheckMs);
return { kind: "error", message: error instanceof Error ? error.message : "inspect failed" } as AutoRedeemOutcome;
}
const plan = planAutoRedeem(now(), credits, settings);
if (!plan) { schedule(idleRecheckMs); return { kind: "nothing-to-protect" } as AutoRedeemOutcome; }
if (plan.dueAt > now()) { schedule(plan.dueAt - now()); return { kind: "scheduled", dueAt: plan.dueAt } as AutoRedeemOutcome; }
// Due: re-read right before spending. The plan above came from this same inspect, but
// the settings may have flipped and a manual consume may have raced; check both again.
if (!deps.settings().enabled) return { kind: "skipped", reason: "disabled-before-dispatch" } as AutoRedeemOutcome;
let fresh: ResetCredit[];
try { ({ credits: fresh } = await deps.inspect()); } catch (error) {
schedule(60_000);
return { kind: "error", message: error instanceof Error ? error.message : "inspect failed" } as AutoRedeemOutcome;
}
if (!creditStillPresent(fresh, plan)) { schedule(idleRecheckMs); return { kind: "skipped", reason: "credit-gone" } as AutoRedeemOutcome; }
if (olderCreditPrecedes(fresh, plan)) {
log(`[opencodex] reset-credit auto-redeem: an older credit would be consumed first for account ${hashAccountKey(deps.accountId)}; not redeeming automatically`);
schedule(idleRecheckMs);
return { kind: "skipped", reason: "order-not-guaranteed" } as AutoRedeemOutcome;
}
return dispatch(plan);
})().finally(() => { inFlight = null; });
return inFlight;
};
return {
tick,
start() { stopped = false; void tick(); },
stop() { stopped = true; if (handle !== null) { clearTimer(handle); handle = null; } },
};
}
/**
* Composition-root activation. Returns the redeemer only when the opt-in is on; the caller
* (src/server/index.ts) must not await this and must gate on `enabled` itself so a default
* install never constructs the timer.
*/
export function activateResetCreditAutoRedeem(
config: OcxConfig,
wham: Pick<AutoRedeemDeps, "inspect" | "consume" | "accountId">,
): ResetCreditAutoRedeemer {
const redeemer = createResetCreditAutoRedeemer({
...wham,
settings: () => resolveResetCreditAutoRedeemSettings(config),
});
const unregister = registerOptionalShutdownHook("reset-credit-auto-redeem", () => { redeemer.stop(); unregister(); });
redeemer.start();
return redeemer;
}