UNPKG

@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
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; }