@crouter/api 0.3.387 → 0.3.388

package/dist/core/subscription-state.d.ts

@@ -0,0 +1,121 @@
+import { type RateLimitScope } from './rate-limit-scope.js';
+export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
+export declare const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+/** pi's built-in `openai` provider signed in with a ChatGPT account (dynamic OAuth client). Distinct from Codex: its own pool, credential file and sign-in. */
+export declare const OPENAI_CHATGPT_PROVIDER_ID = "openai";
+export declare const INVALID_REFRESH_TOKEN_BACKOFF_MS: number;
+export type ManagedProviderId = typeof ANTHROPIC_PROVIDER_ID | typeof OPENAI_CODEX_PROVIDER_ID | typeof OPENAI_CHATGPT_PROVIDER_ID;
+export declare const MANAGED_PROVIDER_IDS: readonly ManagedProviderId[];
+export type ModelStrength = 'ultra' | 'strong' | 'medium' | 'light';
+export type RotationConfig = {
+    defaultFallbackStrength?: ModelStrength;
+    revertWhenAvailable?: boolean;
+};
+/** `rateLimitedUntil` cools the whole account; `modelCooldowns` cools one model family on it (family → epoch ms, stored rows including expired ones). Read both through `coolingUntilFor`. */
+export type SubscriptionCredential = {
+    label: string;
+    refresh: string;
+    access: string;
+    expires: number;
+    rateLimitedUntil: number;
+    lastAttemptAt: number;
+    lastRateLimitedAt: number;
+    authFailure?: 'invalid_grant';
+    accountId?: string;
+    clientId?: string;
+    modelCooldowns?: Record<string, number>;
+};
+export type ProviderCandidate = {
+    providerId: string;
+    modelId: string;
+    thinkingLevel?: string;
+    registered: boolean;
+    authenticated: boolean;
+    coolingUntil?: number;
+    automaticFallback?: boolean;
+    routeId?: string;
+    credentialSource?: string;
+    family?: string;
+    strength?: ModelStrength;
+    rank?: number;
+};
+export type ProviderCandidateRejection = 'unregistered' | 'non-managed-fallback' | 'unauthenticated' | 'cooling';
+/** Refreshed tokens; `clientId` is set when the vendor rotated the issued OAuth client id. */
+export type RefreshedTokens = {
+    refresh: string;
+    access: string;
+    expires: number;
+    clientId?: string;
+};
+/** When this account can next serve `modelId`: the later of its account-wide cooldown and the cooldown on that model's family. Without a model only the account-wide cooldown applies. 0 or a past time means ready. */
+export declare function coolingUntilFor(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'modelCooldowns'>, modelId?: string): number;
+/** Every cooldown on an account still in force at `now`: `scope` is `account` or the model family. */
+export declare function activeCooldowns(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'modelCooldowns'>, now?: number): Array<{
+    scope: string;
+    until: number;
+}>;
+/** Human text for an account's active cooldowns (`cooldown 12m`, `opus cooldown 3d 4h`), or undefined when it is ready. */
+export declare function formatCooldowns(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'modelCooldowns'>, now?: number): string | undefined;
+/** Whether a successful call on `modelId` has stored cooldown or auth health to clear; callers skip the write otherwise (every provider write bumps provider_revision). */
+export declare function subscriptionNeedsSuccessWrite(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'authFailure' | 'modelCooldowns'>, modelId?: string): boolean;
+export declare function isManagedProvider(providerId: string | undefined): providerId is ManagedProviderId;
+/** Stable per-install UUID sent to OpenAI as `ext_agent_host_id=urn:uuid:<id>` during ChatGPT sign-in. The install id is not a UUID, so this is its own get-or-create secret. */
+export declare function openAIDeviceId(): string;
+export declare function getProviderLabel(providerId: ManagedProviderId): string;
+export declare function resolveProviderCandidates(candidates: readonly ProviderCandidate[], now?: number, options?: {
+    pinnedToFirst?: boolean;
+}): {
+    candidates: ProviderCandidate[];
+    rejected: Array<{
+        candidate: ProviderCandidate;
+        reason: ProviderCandidateRejection;
+    }>;
+};
+export declare class DuplicateSubscriptionError extends Error {
+    constructor(message: string);
+}
+export declare function readSubscriptionPool(provider: ManagedProviderId): SubscriptionCredential[];
+export declare function writeSubscriptionPool(provider: ManagedProviderId, next: SubscriptionCredential[]): Promise<SubscriptionCredential[]>;
+export declare function addSubscription(provider: ManagedProviderId, entry: SubscriptionCredential): Promise<SubscriptionCredential[]>;
+export declare function upsertSubscription(provider: ManagedProviderId, entry: SubscriptionCredential): Promise<SubscriptionCredential[]>;
+export declare function upsertSubscriptionWithUniqueAccount(provider: ManagedProviderId, entry: SubscriptionCredential): Promise<SubscriptionCredential[]>;
+export declare function renameSubscription(provider: ManagedProviderId, ref: string, nextLabel: string): Promise<SubscriptionCredential[]>;
+export declare function removeManagedAccount(provider: ManagedProviderId, ref: string): Promise<SubscriptionCredential[]>;
+export declare function removeSubscription(provider: ManagedProviderId, ref: string): Promise<SubscriptionCredential[]>;
+export declare function removeAllManagedAccounts(provider: ManagedProviderId): Promise<number>;
+export declare function removeManagedProvider(provider: ManagedProviderId, label?: string): Promise<SubscriptionCredential[]>;
+export declare function promoteSubscription(provider: ManagedProviderId, ref: string): Promise<SubscriptionCredential[]>;
+export declare function markSubscriptionAttempt(provider: ManagedProviderId, ref: string, attemptAt?: number): Promise<SubscriptionCredential[]>;
+export declare function markSubscriptionAuthenticationFailed(provider: ManagedProviderId, ref: string, attempted: Pick<SubscriptionCredential, 'refresh' | 'access'>, retryAfterMs: number, attemptAt?: number): Promise<SubscriptionCredential[]>;
+/** Record a 429 on an account. `scope` defaults to the whole account; a model scope cools only that family on this account, and a 429 older than the newest one already recorded for the same scope is ignored. */
+export declare function markSubscriptionRateLimited(provider: ManagedProviderId, ref: string, retryAfterMs: number, attemptAt?: number, rateLimitedAt?: number, scope?: RateLimitScope): Promise<SubscriptionCredential[]>;
+/** A call on `modelId` succeeded: clear the account-wide cooldown and auth failure, and that model family's cooldown, unless a newer 429 for the same scope landed after `attemptAt` began. */
+export declare function markSubscriptionSuccess(provider: ManagedProviderId, ref: string, attemptAt?: number, modelId?: string): Promise<SubscriptionCredential[]>;
+export declare function refreshSubscriptionCredential(provider: ManagedProviderId, label: string, exchange: (refreshToken: string, clientId?: string) => Promise<RefreshedTokens>): Promise<SubscriptionCredential>;
+export declare function isInvalidRefreshTokenError(error: unknown): boolean;
+export declare function modifyElectedSubscription(provider: ManagedProviderId, elect: (pool: SubscriptionCredential[]) => SubscriptionCredential | undefined, apply: (current: SubscriptionCredential) => Promise<RefreshedTokens | undefined>): Promise<SubscriptionCredential | undefined>;
+export type ManagedLoginIdentity = {
+    accountId?: string;
+    email?: string;
+};
+export declare function enrichManagedLoginIdentity(provider: ManagedProviderId, value: {
+    access: string;
+    accountId?: string;
+    email?: string;
+}): Promise<ManagedLoginIdentity>;
+export declare function commitManagedLogin(provider: ManagedProviderId, label: string | undefined, value: {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    clientId?: string;
+    email?: string;
+    lastRateLimitedAt: number;
+    autoLabel?: boolean;
+}): Promise<SubscriptionCredential[]>;
+export declare function parseRetryAfterHeader(value: string | undefined, now?: number): number | undefined;
+export declare function retryAfterMsFromHeaders(headers: Headers | Record<string, string> | undefined): number | undefined;
+export declare function retryAfterMsFromError(error: unknown): number | undefined;
+export declare function readRotationConfig(): RotationConfig;
+export declare function writeRotationConfig(next: RotationConfig): RotationConfig;
+export declare function formatStatusLine(provider: ManagedProviderId, now?: number, modelId?: string): string;

package/dist/core/subscription-state.js

@@ -0,0 +1,287 @@
+import { prepared as cachedStatement } from './sqlite-statements.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { brokerConfigSnapshot } from './config.js';
+import { LockedJsonFile } from './locked-file.js';
+import { secretsDir } from './layout.js';
+import { openScopedStore } from './scoped-state/db.js';
+import { providerStore } from './scoped-state/paths.js';
+import { providerModelCooldowns, providerModelCooldownsFor, providerRowByReference, providerRows, providerWrite } from './scoped-state/providers.js';
+import { modelCooldownFamily } from './rate-limit-scope.js';
+export const ANTHROPIC_PROVIDER_ID = 'anthropic';
+export const OPENAI_CODEX_PROVIDER_ID = 'openai-codex';
+/** pi's built-in `openai` provider signed in with a ChatGPT account (dynamic OAuth client). Distinct from Codex: its own pool, credential file and sign-in. */
+export const OPENAI_CHATGPT_PROVIDER_ID = 'openai';
+export const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
+export const MANAGED_PROVIDER_IDS = [ANTHROPIC_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID, OPENAI_CHATGPT_PROVIDER_ID];
+const DEFAULT_FALLBACK_STRENGTH = 'strong';
+const PROVIDERS = { anthropic: { label: 'Claude', credentials: 'anthropic-credentials.json' }, 'openai-codex': { label: 'OpenAI Codex', credentials: 'openai-codex-credentials.json' }, openai: { label: 'ChatGPT', credentials: 'openai-credentials.json' } };
+function stored(entry) { return { refresh: entry.refresh, access: entry.access, expires: entry.expires, ...(entry.accountId ? { accountId: entry.accountId } : {}), ...(entry.clientId ? { clientId: entry.clientId } : {}) }; }
+function optionalString(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+function agentDir() { return secretsDir(); }
+function credentialFile(provider) { return join(agentDir(), PROVIDERS[provider].credentials); }
+function normalizeStrength(value) { return value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light' ? value : undefined; }
+function key(label) { return label.toLowerCase(); }
+function credential(input) { const label = typeof input.label === 'string' ? input.label.trim() : ''; const refresh = typeof input.refresh === 'string' ? input.refresh.trim() : ''; const access = typeof input.access === 'string' ? input.access.trim() : ''; const expires = Number(input.expires); if (!label || !refresh || !access || !Number.isFinite(expires))
+    return undefined; const accountId = optionalString(input.accountId); const clientId = optionalString(input.clientId); return { label, refresh, access, expires, rateLimitedUntil: Number.isFinite(Number(input.rateLimitedUntil)) ? Number(input.rateLimitedUntil) : 0, lastAttemptAt: Number.isFinite(Number(input.lastAttemptAt)) ? Number(input.lastAttemptAt) : 0, lastRateLimitedAt: Number.isFinite(Number(input.lastRateLimitedAt)) ? Number(input.lastRateLimitedAt) : 0, ...(input.authFailure === 'invalid_grant' ? { authFailure: 'invalid_grant' } : {}), ...(accountId ? { accountId } : {}), ...(clientId ? { clientId } : {}), ...(modelCooldowns(input.modelCooldowns) ? { modelCooldowns: modelCooldowns(input.modelCooldowns) } : {}) }; }
+function modelCooldowns(value) { if (!value || typeof value !== 'object' || Array.isArray(value))
+    return undefined; const entries = Object.entries(value).filter(([family, until]) => family.trim() !== '' && Number.isFinite(Number(until))).map(([family, until]) => [family, Number(until)]); return entries.length ? Object.fromEntries(entries) : undefined; }
+function assertCredential(provider, entry) { if (!entry.label?.trim())
+    throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`); const result = credential(entry); if (!result)
+    throw new Error(`Refusing to persist incomplete ${getProviderLabel(provider)} subscription "${entry.label.trim()}"; pool rows require both OAuth tokens.`); return result; }
+function parseCredentials(path, current) { if (!current || current.trim() === '')
+    return { version: 1, accounts: {} }; let parsed; try {
+    parsed = JSON.parse(current);
+}
+catch (error) {
+    throw new Error(`managed credential file ${path} is corrupt: ${error instanceof Error ? error.message : String(error)}`);
+} if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) || parsed.version !== 1 || typeof parsed.accounts !== 'object' || parsed.accounts === null || Array.isArray(parsed.accounts))
+    throw new Error(`managed credential file ${path} is corrupt`); return parsed; }
+function toPublic(row, file, cooldowns = []) { const stored = file.accounts[row.id]; if (!stored || typeof stored.refresh !== 'string' || typeof stored.access !== 'string' || !Number.isFinite(stored.expires))
+    throw new Error(`managed ${row.providerId} account ${row.id} has no credential record`); return { label: row.label, refresh: stored.refresh, access: stored.access, expires: stored.expires, rateLimitedUntil: row.rateLimitedUntil, lastAttemptAt: row.lastAttemptAt, lastRateLimitedAt: row.lastRateLimitedAt, ...(row.authFailure ? { authFailure: row.authFailure } : {}), ...(stored.accountId ? { accountId: stored.accountId } : {}), ...(stored.clientId ? { clientId: stored.clientId } : {}), ...(cooldowns.length ? { modelCooldowns: Object.fromEntries(cooldowns.map((cooldown) => [cooldown.family, cooldown.rateLimitedUntil])) } : {}) }; }
+function rowsWithCredentials(provider, file) { const cooldowns = providerModelCooldownsFor(agentDir(), provider); return providerRows(agentDir(), provider).map((row) => ({ row, entry: toPublic(row, file, cooldowns.get(row.id)) })); }
+function managedCredentialFile(provider) { return new LockedJsonFile(credentialFile(provider), true, '{"version":1,"accounts":{}}\n'); }
+function readFile(provider) { return parseCredentials(credentialFile(provider), managedCredentialFile(provider).readUnlocked()); }
+/** A slot re-signed into a provably different account (both account ids known and unequal): its model-family cooldowns were the old account's server quota windows, not this one's. Unknown or matching ids keep them. */
+function differentAccount(previous, next) { const a = previous.accountId?.trim(); const b = next.accountId?.trim(); return Boolean(a && b && a !== b); }
+function identity(entry) { return entry.accountId?.trim() || (entry.refresh.trim() ? `refresh:${createHash('sha256').update(entry.refresh.trim()).digest('hex')}` : undefined); }
+function withClientId(tokens, clientId) { const id = optionalString(clientId); return id ? { ...tokens, clientId: id } : tokens; }
+function assertTokens(provider, label, value) { const refresh = value.refresh?.trim() ?? ''; const access = value.access?.trim() ?? ''; const expires = Number(value.expires); if (!refresh || !access || !Number.isFinite(expires))
+    throw new Error(`${getProviderLabel(provider)} subscription "${label}" returned an incomplete credential; the stored credential was left unchanged.`); return { refresh, access, expires }; }
+/** When this account can next serve `modelId`: the later of its account-wide cooldown and the cooldown on that model's family. Without a model only the account-wide cooldown applies. 0 or a past time means ready. */
+export function coolingUntilFor(entry, modelId) { const family = modelCooldownFamily(modelId); return Math.max(entry.rateLimitedUntil || 0, family === undefined ? 0 : entry.modelCooldowns?.[family] ?? 0); }
+/** Every cooldown on an account still in force at `now`: `scope` is `account` or the model family. */
+export function activeCooldowns(entry, now = Date.now()) { return [...((entry.rateLimitedUntil || 0) > now ? [{ scope: 'account', until: entry.rateLimitedUntil }] : []), ...Object.entries(entry.modelCooldowns ?? {}).filter(([, until]) => until > now).map(([scope, until]) => ({ scope, until }))]; }
+/** Human text for an account's active cooldowns (`cooldown 12m`, `opus cooldown 3d 4h`), or undefined when it is ready. */
+export function formatCooldowns(entry, now = Date.now()) { const parts = activeCooldowns(entry, now).map(({ scope, until }) => `${scope === 'account' ? '' : `${scope} `}cooldown ${formatWait(until - now)}`); return parts.length ? parts.join(', ') : undefined; }
+function formatWait(ms) { const minutes = Math.max(1, Math.ceil(ms / 60_000)); if (minutes < 60)
+    return `${minutes}m`; const hours = Math.floor(minutes / 60); if (hours < 24)
+    return `${hours}h${minutes % 60 ? ` ${minutes % 60}m` : ''}`; return `${Math.floor(hours / 24)}d${hours % 24 ? ` ${hours % 24}h` : ''}`; }
+function hasModelCooldownRow(entry, modelId) { const family = modelCooldownFamily(modelId); return family !== undefined && entry.modelCooldowns?.[family] !== undefined; }
+/** Whether a successful call on `modelId` has stored cooldown or auth health to clear; callers skip the write otherwise (every provider write bumps provider_revision). */
+export function subscriptionNeedsSuccessWrite(entry, modelId) { return Boolean(entry.rateLimitedUntil || entry.authFailure) || hasModelCooldownRow(entry, modelId); }
+export function isManagedProvider(providerId) { return providerId === ANTHROPIC_PROVIDER_ID || providerId === OPENAI_CODEX_PROVIDER_ID || providerId === OPENAI_CHATGPT_PROVIDER_ID; }
+/** Stable per-install UUID sent to OpenAI as `ext_agent_host_id=urn:uuid:<id>` during ChatGPT sign-in. The install id is not a UUID, so this is its own get-or-create secret. */
+export function openAIDeviceId() { const path = join(agentDir(), 'openai-device-id'); try {
+    const existing = readFileSync(path, 'utf8').trim();
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(existing))
+        return existing.toLowerCase();
+}
+catch { /* create below */ } const id = randomUUID(); mkdirSync(agentDir(), { recursive: true, mode: 0o700 }); writeFileSync(path, `${id}\n`, { mode: 0o600 }); return id; }
+export function getProviderLabel(providerId) { return PROVIDERS[providerId].label; }
+export function resolveProviderCandidates(candidates, now = Date.now(), options = {}) { const viable = []; const rejected = []; for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    const reason = !candidate.registered ? 'unregistered' : candidate.automaticFallback === false ? 'non-managed-fallback' : !candidate.authenticated ? 'unauthenticated' : (candidate.coolingUntil ?? 0) > now ? 'cooling' : undefined;
+    if (!reason)
+        viable.push(candidate);
+    else {
+        rejected.push({ candidate, reason });
+        if (options.pinnedToFirst && i === 0 && reason !== 'cooling')
+            break;
+    }
+} return { candidates: viable, rejected }; }
+export class DuplicateSubscriptionError extends Error {
+    constructor(message) { super(message); this.name = 'DuplicateSubscriptionError'; }
+}
+export function readSubscriptionPool(provider) { return rowsWithCredentials(provider, readFile(provider)).map(({ entry }) => entry); }
+async function locked(provider, run) { const path = credentialFile(provider); return managedCredentialFile(provider).withLockAsync(async (current, _held, publish) => { const file = parseCredentials(path, current); return { result: await run(file, rowsWithCredentials(provider, file), (next) => publish(`${JSON.stringify(next)}\n`)) }; }); }
+function insert(db, provider, row) { cachedStatement(db, 'INSERT INTO managed_accounts(provider_id,id,label,label_key,position,last_attempt_at,last_rate_limited_at,rate_limited_until,auth_failure) VALUES(?,?,?,?,?,?,?,?,?)').run(provider, row.id, row.label, row.labelKey, row.position, row.lastAttemptAt, row.lastRateLimitedAt, row.rateLimitedUntil, row.authFailure ?? null); }
+function update(db, row) { cachedStatement(db, 'UPDATE managed_accounts SET label=?,label_key=?,position=?,last_attempt_at=?,last_rate_limited_at=?,rate_limited_until=?,auth_failure=? WHERE provider_id=? AND id=?').run(row.label, row.labelKey, row.position, row.lastAttemptAt, row.lastRateLimitedAt, row.rateLimitedUntil, row.authFailure ?? null, row.providerId, row.id); }
+function upsertModelCooldown(db, provider, accountId, family, until, rateLimitedAt) { cachedStatement(db, 'INSERT INTO managed_account_model_cooldowns(provider_id,account_id,family,rate_limited_until,last_rate_limited_at) VALUES(?,?,?,?,?) ON CONFLICT(provider_id,account_id,family) DO UPDATE SET rate_limited_until=excluded.rate_limited_until,last_rate_limited_at=excluded.last_rate_limited_at').run(provider, accountId, family, until, rateLimitedAt); }
+function deleteModelCooldowns(db, provider, accountId) { if (accountId === undefined)
+    cachedStatement(db, 'DELETE FROM managed_account_model_cooldowns WHERE provider_id=?').run(provider);
+else
+    cachedStatement(db, 'DELETE FROM managed_account_model_cooldowns WHERE provider_id=? AND account_id=?').run(provider, accountId); }
+function publicPool(provider, file) { return rowsWithCredentials(provider, file).map(({ entry }) => entry); }
+function writeMembershipAfterCredentialPublish(provider, write) { try {
+    write();
+}
+catch (error) {
+    throw new Error(`managed ${getProviderLabel(provider)} credential file was published, but its SQL membership update failed; SQL membership remains authoritative: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+} }
+export async function writeSubscriptionPool(provider, next) { return locked(provider, async (file, rows, publish) => { const normalized = next.map((entry) => assertCredential(provider, entry)); const ids = normalized.map((entry, index) => ({ entry, id: rows[index]?.row.id ?? randomUUID() })); const accounts = {}; for (const { entry, id } of ids)
+    accounts[id] = stored(entry); publish({ version: 1, accounts }); writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => { const priorFamilies = providerModelCooldowns(db, provider); cachedStatement(db, 'DELETE FROM managed_accounts WHERE provider_id=?').run(provider); cachedStatement(db, 'DELETE FROM managed_account_model_cooldowns WHERE provider_id=?').run(provider); ids.forEach(({ entry, id }, position) => { insert(db, provider, { providerId: provider, id, label: entry.label, labelKey: key(entry.label), position, lastAttemptAt: entry.lastAttemptAt, lastRateLimitedAt: entry.lastRateLimitedAt, rateLimitedUntil: entry.rateLimitedUntil, ...(entry.authFailure ? { authFailure: entry.authFailure } : {}) }); for (const [family, until] of Object.entries(entry.modelCooldowns ?? {}))
+    upsertModelCooldown(db, provider, id, family, until, priorFamilies.get(id)?.find((prior) => prior.family === family)?.lastRateLimitedAt ?? entry.lastRateLimitedAt); }); })); return normalized; }); }
+function resolve(rows, ref) { const needle = ref.trim().toLowerCase(); const number = Number.parseInt(needle, 10); if (Number.isFinite(number) && String(number) === needle && number >= 1 && number <= rows.length)
+    return number - 1; return rows.findIndex(({ entry }) => key(entry.label) === needle); }
+export async function addSubscription(provider, entry) { const checked = assertCredential(provider, entry); return locked(provider, async (file, rows, publish) => { if (rows.some(({ entry: existing }) => key(existing.label) === key(checked.label)))
+    throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${checked.label}`); const same = identity(checked); const collision = rows.find(({ entry: existing }) => identity(existing) === same); if (same && collision)
+    throw new DuplicateSubscriptionError(`This ${getProviderLabel(provider)} account is already added as “${collision.entry.label}” — it shares the same quota, so a second slot adds no redundancy.`); const id = randomUUID(); file.accounts[id] = stored(checked); publish(file); writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => insert(db, provider, { providerId: provider, id, label: checked.label, labelKey: key(checked.label), position: rows.length, lastAttemptAt: checked.lastAttemptAt, lastRateLimitedAt: checked.lastRateLimitedAt, rateLimitedUntil: checked.rateLimitedUntil, ...(checked.authFailure ? { authFailure: checked.authFailure } : {}) }))); return publicPool(provider, file); }); }
+export async function upsertSubscription(provider, entry) { const checked = assertCredential(provider, entry); const existing = readSubscriptionPool(provider).find((x) => key(x.label) === key(checked.label)); return existing ? upsertSubscriptionWithUniqueAccount(provider, checked) : addSubscription(provider, checked); }
+export async function upsertSubscriptionWithUniqueAccount(provider, entry) {
+    const checked = assertCredential(provider, entry);
+    return locked(provider, async (file, rows, publish) => {
+        const index = rows.findIndex(({ entry: existing }) => key(existing.label) === key(checked.label));
+        const existing = rows[index];
+        const duplicate = rows.find(({ entry: other }, i) => i !== index && identity(other) === identity(checked));
+        if (identity(checked) && duplicate)
+            throw new DuplicateSubscriptionError(`This ${getProviderLabel(provider)} account is already added as “${duplicate.entry.label}” — it shares the same quota, so a second slot adds no redundancy.`);
+        if (!existing) {
+            const id = randomUUID();
+            file.accounts[id] = stored(checked);
+            publish(file);
+            writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => insert(db, provider, { providerId: provider, id, label: checked.label, labelKey: key(checked.label), position: rows.length, lastAttemptAt: checked.lastAttemptAt, lastRateLimitedAt: checked.lastRateLimitedAt, rateLimitedUntil: checked.rateLimitedUntil })));
+            return publicPool(provider, file);
+        }
+        const row = existing.row;
+        const cooldownIncoming = checked.lastRateLimitedAt >= row.lastRateLimitedAt;
+        file.accounts[row.id] = stored(checked);
+        publish(file);
+        writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => { update(db, { ...row, label: checked.label, labelKey: key(checked.label), lastAttemptAt: Math.max(row.lastAttemptAt, checked.lastAttemptAt), lastRateLimitedAt: cooldownIncoming ? checked.lastRateLimitedAt : row.lastRateLimitedAt, rateLimitedUntil: cooldownIncoming ? checked.rateLimitedUntil : row.rateLimitedUntil }); if (differentAccount(existing.entry, checked))
+            deleteModelCooldowns(db, provider, row.id); }));
+        return publicPool(provider, file);
+    });
+}
+export async function renameSubscription(provider, ref, nextLabel) { return locked(provider, async (file, rows) => { const index = resolve(rows, ref); if (index < 0)
+    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); const label = nextLabel.trim(); if (!label)
+    throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`); if (rows.some((value, i) => i !== index && key(value.entry.label) === key(label)))
+    throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${label}`); providerWrite(agentDir(), (db) => update(db, { ...rows[index].row, label, labelKey: key(label) })); return publicPool(provider, file); }); }
+async function remove(provider, ref) { return locked(provider, async (file, rows, publish) => { const index = resolve(rows, ref); if (index < 0)
+    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); const removed = rows[index].row; providerWrite(agentDir(), (db) => { cachedStatement(db, 'DELETE FROM managed_accounts WHERE provider_id=? AND id=?').run(provider, removed.id); deleteModelCooldowns(db, provider, removed.id); }); delete file.accounts[removed.id]; publish(file); return publicPool(provider, file); }); }
+export async function removeManagedAccount(provider, ref) { return remove(provider, ref); }
+export async function removeSubscription(provider, ref) { return remove(provider, ref); }
+export async function removeAllManagedAccounts(provider) { return locked(provider, async (file, rows, publish) => { providerWrite(agentDir(), (db) => { cachedStatement(db, 'DELETE FROM managed_accounts WHERE provider_id=?').run(provider); deleteModelCooldowns(db, provider); }); for (const { row } of rows)
+    delete file.accounts[row.id]; publish(file); return rows.length; }); }
+export async function removeManagedProvider(provider, label) { if (label === undefined) {
+    await removeAllManagedAccounts(provider);
+    return [];
+} return remove(provider, label); }
+export async function promoteSubscription(provider, ref) { return locked(provider, async (file, rows) => { const index = resolve(rows, ref); if (index < 0)
+    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); providerWrite(agentDir(), (db) => { const reordered = [rows[index], ...rows.filter((_, i) => i !== index)]; reordered.forEach((item, position) => update(db, { ...item.row, position })); }); return publicPool(provider, file); }); }
+async function mutateHealth(provider, ref, mutate) { providerWrite(agentDir(), (db) => { const row = providerRowByReference(db, provider, ref); if (!row)
+    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); const next = mutate(row); if (next)
+    update(db, next); }); return readSubscriptionPool(provider); }
+export async function markSubscriptionAttempt(provider, ref, attemptAt = Date.now()) { return mutateHealth(provider, ref, (row) => ({ ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt) })); }
+export async function markSubscriptionAuthenticationFailed(provider, ref, attempted, retryAfterMs, attemptAt = Date.now()) { return locked(provider, async (file, rows) => { const current = rows.find(({ entry }) => key(entry.label) === key(ref)); if (!current)
+    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); if (current.entry.refresh !== attempted.refresh || current.entry.access !== attempted.access)
+    return publicPool(provider, file); providerWrite(agentDir(), (db) => update(db, { ...current.row, authFailure: 'invalid_grant', lastAttemptAt: Math.max(current.row.lastAttemptAt, attemptAt), rateLimitedUntil: Math.max(current.row.rateLimitedUntil, attemptAt + Math.max(0, retryAfterMs)) })); return publicPool(provider, file); }); }
+/** Record a 429 on an account. `scope` defaults to the whole account; a model scope cools only that family on this account, and a 429 older than the newest one already recorded for the same scope is ignored. */
+export async function markSubscriptionRateLimited(provider, ref, retryAfterMs, attemptAt = Date.now(), rateLimitedAt = Date.now(), scope = { kind: 'account' }) {
+    if (scope.kind === 'account')
+        return mutateHealth(provider, ref, (row) => rateLimitedAt < row.lastRateLimitedAt ? null : { ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt), lastRateLimitedAt: rateLimitedAt, rateLimitedUntil: rateLimitedAt + Math.max(0, retryAfterMs) });
+    providerWrite(agentDir(), (db) => {
+        const row = providerRowByReference(db, provider, ref);
+        if (!row)
+            throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`);
+        update(db, { ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt) });
+        const current = providerModelCooldowns(db, provider).get(row.id)?.find((cooldown) => cooldown.family === scope.family);
+        if (current && rateLimitedAt < current.lastRateLimitedAt)
+            return;
+        upsertModelCooldown(db, provider, row.id, scope.family, rateLimitedAt + Math.max(0, retryAfterMs), rateLimitedAt);
+    });
+    return readSubscriptionPool(provider);
+}
+/** A call on `modelId` succeeded: clear the account-wide cooldown and auth failure, and that model family's cooldown, unless a newer 429 for the same scope landed after `attemptAt` began. */
+export async function markSubscriptionSuccess(provider, ref, attemptAt = Date.now(), modelId) {
+    const family = modelCooldownFamily(modelId);
+    providerWrite(agentDir(), (db) => {
+        const row = providerRowByReference(db, provider, ref);
+        if (!row)
+            throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`);
+        if (attemptAt >= row.lastRateLimitedAt)
+            update(db, { ...row, authFailure: undefined, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt), rateLimitedUntil: 0 });
+        if (family === undefined)
+            return;
+        const current = providerModelCooldowns(db, provider).get(row.id)?.find((cooldown) => cooldown.family === family);
+        if (current && attemptAt >= current.lastRateLimitedAt)
+            cachedStatement(db, 'DELETE FROM managed_account_model_cooldowns WHERE provider_id=? AND account_id=? AND family=?').run(provider, row.id, family);
+    });
+    return readSubscriptionPool(provider);
+}
+export async function refreshSubscriptionCredential(provider, label, exchange) { return locked(provider, async (file, rows, publish) => { const index = resolve(rows, label); if (index < 0)
+    throw new Error(`${getProviderLabel(provider)} subscription "${label}" no longer exists`); const current = rows[index]; if (current.entry.expires > Date.now())
+    return current.entry; const next = await exchange(current.entry.refresh, current.entry.clientId); const tokens = withClientId(assertTokens(provider, current.entry.label, next), next.clientId ?? current.entry.clientId); file.accounts[current.row.id] = { ...file.accounts[current.row.id], ...tokens }; publish(file); return { ...current.entry, ...tokens }; }); }
+export function isInvalidRefreshTokenError(error) { const value = error; const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : ''].filter((part) => typeof part === 'string').join(' '); const status = typeof value?.status === 'number' ? value.status : Number(message.match(/\bstatus[=:]\s*(\d+)/i)?.[1]); return status === 400 && /invalid_grant|refresh token .*invalid|refresh token .*not found/i.test(message); }
+export async function modifyElectedSubscription(provider, elect, apply) { return locked(provider, async (file, rows, publish) => { const attempted = new Set(); let lastError; while (attempted.size < rows.length) {
+    const chosen = elect(rows.filter(({ entry }) => !attempted.has(entry.label)).map(({ entry }) => entry));
+    if (!chosen)
+        break;
+    const current = rows.find(({ entry }) => entry.label === chosen.label);
+    attempted.add(current.entry.label);
+    try {
+        const next = await apply(current.entry);
+        if (next) {
+            const tokens = withClientId(assertTokens(provider, current.entry.label, next), next.clientId ?? current.entry.clientId);
+            file.accounts[current.row.id] = { ...file.accounts[current.row.id], ...tokens };
+            publish(file);
+            return { ...current.entry, ...tokens };
+        }
+        return current.entry;
+    }
+    catch (error) {
+        if (!isInvalidRefreshTokenError(error))
+            throw error;
+        lastError = error;
+        const at = Date.now();
+        providerWrite(agentDir(), (db) => update(db, { ...current.row, authFailure: 'invalid_grant', lastAttemptAt: Math.max(current.row.lastAttemptAt, at), rateLimitedUntil: Math.max(current.row.rateLimitedUntil, at + INVALID_REFRESH_TOKEN_BACKOFF_MS) }));
+    }
+} if (lastError)
+    throw lastError; return undefined; }); }
+export async function enrichManagedLoginIdentity(provider, value) { const supplied = value.accountId?.trim(); const suppliedEmail = value.email?.trim(); if (provider !== ANTHROPIC_PROVIDER_ID)
+    return { ...(supplied ? { accountId: supplied } : {}), ...(suppliedEmail ? { email: suppliedEmail } : {}) }; try {
+    const response = await fetch('https://api.anthropic.com/api/oauth/profile', { headers: { Authorization: `Bearer ${value.access}`, Accept: 'application/json' }, signal: AbortSignal.timeout(3_000) });
+    if (!response.ok)
+        return supplied ? { accountId: supplied } : {};
+    const body = await response.json();
+    const accountId = typeof body.account?.uuid === 'string' && body.account.uuid.trim() ? body.account.uuid.trim() : undefined;
+    const email = typeof body.account?.email === 'string' && body.account.email.trim() ? body.account.email.trim() : undefined;
+    return { ...(accountId ? { accountId } : {}), ...(email ? { email } : {}) };
+}
+catch {
+    return supplied ? { accountId: supplied } : {};
+} }
+export async function commitManagedLogin(provider, label, value) { const identityInfo = await enrichManagedLoginIdentity(provider, value); return locked(provider, async (file, rows, publish) => { const selected = value.autoLabel ? undefined : label?.trim(); const incomingIdentity = identity({ refresh: value.refresh, accountId: identityInfo.accountId }); const matching = (selected ? rows.find(({ entry }) => key(entry.label) === key(selected)) : undefined) ?? rows.find(({ entry }) => identity(entry) === incomingIdentity); let resolved = matching?.entry.label ?? selected; if (!resolved && value.autoLabel) {
+    const base = identityInfo.email || label?.trim() || `Account ${rows.length + 1}`;
+    resolved = base;
+    for (let n = 2; rows.some(({ entry }) => key(entry.label) === key(resolved)); n++)
+        resolved = `${base} (${n})`;
+} if (!resolved)
+    throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`); const entry = assertCredential(provider, { label: resolved, refresh: value.refresh, access: value.access, expires: value.expires, ...(identityInfo.accountId ? { accountId: identityInfo.accountId } : {}), ...(value.clientId ? { clientId: value.clientId } : {}), rateLimitedUntil: 0, lastAttemptAt: Date.now(), lastRateLimitedAt: value.lastRateLimitedAt }); if (!matching) {
+    if (rows.some(({ entry: existing }) => key(existing.label) === key(entry.label)))
+        throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${entry.label}`);
+    const duplicate = rows.find(({ entry: existing }) => identity(existing) === identity(entry));
+    if (identity(entry) && duplicate)
+        throw new DuplicateSubscriptionError(`This ${getProviderLabel(provider)} account is already added as “${duplicate.entry.label}” — it shares the same quota, so a second slot adds no redundancy.`);
+    const id = randomUUID();
+    file.accounts[id] = stored(entry);
+    publish(file);
+    writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => insert(db, provider, { providerId: provider, id, label: entry.label, labelKey: key(entry.label), position: rows.length, lastAttemptAt: entry.lastAttemptAt, lastRateLimitedAt: entry.lastRateLimitedAt, rateLimitedUntil: entry.rateLimitedUntil })));
+    return publicPool(provider, file);
+} const row = matching.row; const duplicate = rows.find(({ entry: other }) => other.label !== matching.entry.label && identity(other) === identity(entry)); if (identity(entry) && duplicate)
+    throw new DuplicateSubscriptionError(`This ${getProviderLabel(provider)} account is already added as “${duplicate.entry.label}” — it shares the same quota, so a second slot adds no redundancy.`); file.accounts[row.id] = stored(entry); publish(file); const clear = entry.lastRateLimitedAt >= row.lastRateLimitedAt; writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => { update(db, { ...row, authFailure: undefined, lastAttemptAt: Math.max(row.lastAttemptAt, entry.lastAttemptAt), lastRateLimitedAt: clear ? entry.lastRateLimitedAt : row.lastRateLimitedAt, rateLimitedUntil: clear ? 0 : row.rateLimitedUntil }); if (differentAccount(matching.entry, entry))
+    deleteModelCooldowns(db, provider, row.id); })); return publicPool(provider, file); }); }
+export function parseRetryAfterHeader(value, now = Date.now()) { if (!value?.trim())
+    return undefined; const seconds = Number(value.trim()); if (Number.isFinite(seconds))
+    return Math.max(0, Math.round(seconds * 1000)); const parsed = Date.parse(value); return Number.isFinite(parsed) ? Math.max(0, parsed - now) : undefined; }
+export function retryAfterMsFromHeaders(headers) {
+    if (!headers)
+        return undefined;
+    const get = (name) => headers instanceof Headers ? headers.get(name) ?? undefined : Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+    const millis = get('retry-after-ms');
+    if (millis !== undefined && millis.trim() !== '' && Number.isFinite(Number(millis)))
+        return Math.max(0, Number(millis));
+    return parseRetryAfterHeader(get('retry-after'));
+}
+export function retryAfterMsFromError(error) {
+    if (!error || typeof error !== 'object' || !('headers' in error))
+        return undefined;
+    const headers = error.headers;
+    if (!(headers instanceof Headers) && (!headers || typeof headers !== 'object' || Array.isArray(headers)))
+        return undefined;
+    return retryAfterMsFromHeaders(headers);
+}
+export function readRotationConfig() {
+    const snapshot = brokerConfigSnapshot();
+    if (snapshot)
+        return snapshot.rotation;
+    const row = cachedStatement(openScopedStore(providerStore(agentDir())), 'SELECT default_fallback_strength,revert_when_available FROM rotation_settings WHERE singleton=1').get();
+    return { defaultFallbackStrength: normalizeStrength(row?.default_fallback_strength) ?? DEFAULT_FALLBACK_STRENGTH, revertWhenAvailable: row?.revert_when_available === undefined || row.revert_when_available === null ? true : Boolean(row.revert_when_available) };
+}
+export function writeRotationConfig(next) {
+    const current = readRotationConfig();
+    const merged = { defaultFallbackStrength: normalizeStrength(next.defaultFallbackStrength) ?? current.defaultFallbackStrength ?? DEFAULT_FALLBACK_STRENGTH, revertWhenAvailable: next.revertWhenAvailable ?? current.revertWhenAvailable ?? true };
+    providerWrite(agentDir(), (db) => cachedStatement(db, `INSERT INTO rotation_settings(singleton,default_fallback_strength,revert_when_available) VALUES(1,?,?) ON CONFLICT(singleton) DO UPDATE SET default_fallback_strength=excluded.default_fallback_strength,revert_when_available=excluded.revert_when_available`).run(merged.defaultFallbackStrength, merged.revertWhenAvailable ? 1 : 0));
+    return merged;
+}
+export function formatStatusLine(provider, now = Date.now(), modelId) { const pool = readSubscriptionPool(provider); const ready = pool.filter((entry) => entry.authFailure === undefined && coolingUntilFor(entry, modelId) <= now); const label = getProviderLabel(provider); return ready.length === 0 ? `${label} pool exhausted` : `${label} ${ready[0]?.label ?? provider} (${ready.length}/${pool.length} ready)`; }