dsh-subscriptions 0.1.2 → 0.1.4

package/lib/providers/account-preferences.js

@@ -1,5 +1,6 @@
 import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
 import { DISCOVERY_TIMEOUT_MS, withTimeout } from './common.js';
+import { streamAccountWithReplay } from './replay.js';
 /** Reserved namespace, recognized even when malformed or no longer enabled. */
 export const ACCOUNT_MODEL_PREFIX = '~account:';
 export function accountModelId(account, model) {
@@ -140,7 +141,7 @@ export class AccountPreferencesAdapter extends LlmAdapter {
         const independent = parseAccountModelId(options.model);
         if (independent) {
             await this.requireAccount(independent.account, independent.model, true);
-            yield* this.options.adapter.streamAccount({ ...options, model: independent.model }, independent.account);
+            yield* streamAccountWithReplay(this.options.adapter, options, independent.account, independent.model);
             return;
         }
         const pool = this.options.pool();
@@ -148,6 +149,6 @@ export class AccountPreferencesAdapter extends LlmAdapter {
             yield* pool.stream(options);
             return;
         }
-        yield* this.options.adapter.streamAccount(options, await this.fallback(options.model));
+        yield* streamAccountWithReplay(this.options.adapter, options, await this.fallback(options.model));
     }
 }

package/lib/providers/catalog-store.d.ts

@@ -28,8 +28,8 @@ export declare function modelsFilePath(): string;
 export declare function sanitizeSnapshot(value: unknown): CatalogSnapshot | undefined;
 /**
  * Build the durable half of one provider's catalog cache over the shared
- * models.json file (concurrent writers are last-writer-wins, acceptable for
- * a cache).
+ * models.json file. Saves and clears serialize with all accounts at this path
+ * in this process; readers see a complete file before or after an atomic rename.
  * @param provider - the provider route keying the file entry.
  * @param path - store file path; defaults to {@link modelsFilePath}.
  * @returns the persistence hooks for {@link ModelCatalogCache}.
@@ -40,6 +40,7 @@ export declare function catalogStore(provider: ProviderId, path?: string): Catal
  * entry belongs to the default account; every other account keeps its own
  * snapshot under `accounts[provider][account]`, so a working secondary login
  * survives restarts and network failures even when the default login is dead.
+ * Saves and clears share {@link catalogStore}'s in-process write chain.
  * @param provider - the provider route.
  * @param account - the canonical account key.
  * @param path - store file path; defaults to {@link modelsFilePath}.

package/lib/providers/catalog-store.js

@@ -12,7 +12,7 @@
  * throw on every call, which is worse than having no fallback at all.
  */
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 /**
@@ -177,10 +177,32 @@ async function writeCatalogFile(store, path) {
         throw error;
     }
 }
+/**
+ * Like the auth store, mutations of one resolved path share an in-process
+ * write chain in call order. Each reads after the preceding mutation settles;
+ * a failure rejects its caller without blocking later mutations. Idle chains
+ * are removed. Separate processes (or filesystem aliases of a path) are not
+ * locked and remain last-writer-wins.
+ */
+const writeChains = new Map();
+async function serialize(path, action) {
+    const key = resolve(path);
+    const previous = writeChains.get(key) ?? Promise.resolve();
+    const next = previous.then(action, action);
+    const tail = next.then(() => undefined, () => undefined);
+    writeChains.set(key, tail);
+    try {
+        return await next;
+    }
+    finally {
+        if (writeChains.get(key) === tail)
+            writeChains.delete(key);
+    }
+}
 /**
  * Build the durable half of one provider's catalog cache over the shared
- * models.json file (concurrent writers are last-writer-wins, acceptable for
- * a cache).
+ * models.json file. Saves and clears serialize with all accounts at this path
+ * in this process; readers see a complete file before or after an atomic rename.
  * @param provider - the provider route keying the file entry.
  * @param path - store file path; defaults to {@link modelsFilePath}.
  * @returns the persistence hooks for {@link ModelCatalogCache}.
@@ -191,16 +213,20 @@ export function catalogStore(provider, path = modelsFilePath()) {
             return sanitizeSnapshot((await readCatalogFile(path))[provider]);
         },
         async save(snapshot) {
-            const store = await readCatalogFile(path);
-            store[provider] = snapshot;
-            await writeCatalogFile(store, path);
+            return serialize(path, async () => {
+                const store = await readCatalogFile(path);
+                store[provider] = snapshot;
+                await writeCatalogFile(store, path);
+            });
         },
         async clear() {
-            const store = await readCatalogFile(path);
-            if (store[provider] === undefined)
-                return;
-            delete store[provider];
-            await writeCatalogFile(store, path);
+            return serialize(path, async () => {
+                const store = await readCatalogFile(path);
+                if (store[provider] === undefined)
+                    return;
+                delete store[provider];
+                await writeCatalogFile(store, path);
+            });
         },
     };
 }
@@ -209,6 +235,7 @@ export function catalogStore(provider, path = modelsFilePath()) {
  * entry belongs to the default account; every other account keeps its own
  * snapshot under `accounts[provider][account]`, so a working secondary login
  * survives restarts and network failures even when the default login is dead.
+ * Saves and clears share {@link catalogStore}'s in-process write chain.
  * @param provider - the provider route.
  * @param account - the canonical account key.
  * @param path - store file path; defaults to {@link modelsFilePath}.
@@ -221,23 +248,27 @@ export function accountCatalogStore(provider, account, path = modelsFilePath())
             return section !== undefined && Object.hasOwn(section, account) ? sanitizeSnapshot(section[account]) : undefined;
         },
         async save(snapshot) {
-            const store = await readCatalogFile(path);
-            const accounts = typeof store.accounts === 'object' && store.accounts !== null && !Array.isArray(store.accounts)
-                ? store.accounts
-                : {};
-            const section = { ...accountSection(store, provider) ?? {}, [account]: snapshot };
-            store.accounts = { ...accounts, [provider]: section };
-            await writeCatalogFile(store, path);
+            return serialize(path, async () => {
+                const store = await readCatalogFile(path);
+                const accounts = typeof store.accounts === 'object' && store.accounts !== null && !Array.isArray(store.accounts)
+                    ? store.accounts
+                    : {};
+                const section = { ...accountSection(store, provider) ?? {}, [account]: snapshot };
+                store.accounts = { ...accounts, [provider]: section };
+                await writeCatalogFile(store, path);
+            });
         },
         async clear() {
-            const store = await readCatalogFile(path);
-            const section = accountSection(store, provider);
-            if (section === undefined || !Object.hasOwn(section, account))
-                return;
-            const rest = { ...section };
-            delete rest[account];
-            store.accounts = { ...store.accounts, [provider]: rest };
-            await writeCatalogFile(store, path);
+            return serialize(path, async () => {
+                const store = await readCatalogFile(path);
+                const section = accountSection(store, provider);
+                if (section === undefined || !Object.hasOwn(section, account))
+                    return;
+                const rest = { ...section };
+                delete rest[account];
+                store.accounts = { ...store.accounts, [provider]: rest };
+                await writeCatalogFile(store, path);
+            });
         },
     };
 }

package/lib/providers/claude.d.ts

@@ -10,6 +10,7 @@ import type { ClaudeSession } from '../auth/store.js';
 import type { PoolAdapter } from './pool.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { TranslatableMessage } from '../translate/resolved.js';
+import type { PromptCacheTtl } from '../translate/anthropic.js';
 import { AccountTokenManager } from './accounts.js';
 import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 import type { CliVersion } from './npm-cli-version.js';
@@ -34,8 +35,8 @@ export declare const CLAUDE_PREEMPT_MS: number;
  * headers are deliberately not read: they are rollover snapshots attached to
  * every response, so on a 429 they cannot say which bucket refused, and the
  * earliest of them is typically the bucket that still had room — a wait that
- * lands straight back in the closed window. They reach the operator through
- * `rateLimitDiagnostics` instead.
+ * lands straight back in the closed window. The parsed reset supplies the retry
+ * hint; diagnostics omit raw provider headers and body text.
  */
 export declare const claudeRateLimitReset: RateLimitResetReader;
 /**
@@ -86,6 +87,10 @@ export declare const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usa
  * source of Claude Code's `/usage` screen). Newer responses carry a
  * structured `limits` array; older ones the flat `five_hour`/`seven_day*`
  * buckets — both shapes are read, the array winning when it has entries.
+ * Requests the optional cedar_ember banked-reset block with the existing CLI
+ * identity. A 400/403 retries once without that parameter; ordinary windows
+ * remain available and resetCreditsError records the optional lookup failure.
+ * Missing/ineligible blocks and empty or unusable grants expose no credits.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param signal - caller cancellation from the RPC transport.
@@ -124,7 +129,17 @@ export interface ClaudeAdapterOptions {
     defaultEffortOf?: (model: string) => string | undefined;
     /** Resolves the Claude Code version to present (npm-backed); absent means the local floor. */
     resolveCliVersion?: () => Promise<string>;
+    /** Cache breakpoint lifetime; absent means the API's five-minute default. */
+    promptCacheTtl?: PromptCacheTtl;
 }
+/**
+ * Inline image data a Claude request may carry, in base64 bytes. Every turn
+ * resends the history, so screenshots accumulate until the request passes the
+ * API's 32MB body limit and every later turn and compaction fails with HTTP
+ * 413 `request_too_large`. Past this budget the host offloads the oldest
+ * images to text and retries; the remaining 12MB holds prompts, tools, and text.
+ */
+export declare const CLAUDE_REQUEST_IMAGE_BUDGET: number;
 /**
  * Assemble the Anthropic request body.
  *
@@ -138,9 +153,13 @@ export interface ClaudeAdapterOptions {
  * @param maxTokens - the resolved output cap.
  * @param thinking - the thinking parameter, when the model takes one.
  * @param effort - the reasoning effort, when the model advertises efforts.
+ * @param cacheTtl - lifetime of every cache breakpoint; defaults to five minutes.
+ * Requests that carry a `purpose` (compaction, session titles) always use five
+ * minutes to preserve their existing auxiliary-request behavior. A five-minute
+ * mark can still read an entry a one-hour mark wrote.
  * @returns the JSON body to POST.
  */
-export declare function claudeRequestBody(options: GenerateOptions, messages: readonly TranslatableMessage[], maxTokens: number, thinking?: Record<string, unknown>, effort?: string): Record<string, unknown>;
+export declare function claudeRequestBody(options: GenerateOptions, messages: readonly TranslatableMessage[], maxTokens: number, thinking?: Record<string, unknown>, effort?: string, cacheTtl?: PromptCacheTtl): Record<string, unknown>;
 /** Claude wire adapter: one instance serves the `claude` provider route. */
 export declare class ClaudeAdapter extends LlmAdapter {
     private readonly options;

package/lib/providers/claude.js

@@ -5,7 +5,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
-import { resolveImages } from '../translate/resolved.js';
+import { hostSupportsImageOffload, IMAGE_OFFLOAD_REQUIRED, requiredImageOffloadCount, resolveImages } from '../translate/resolved.js';
 import { markMessageCache, streamAnthropic, toAnthropicMessages, toAnthropicSystem, toAnthropicTools, } from '../translate/anthropic.js';
 import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
@@ -40,8 +40,8 @@ const CLAUDE_RESET_FIELDS = ['resets_at', 'resetsAt', 'reset_at', 'retry_after']
  * headers are deliberately not read: they are rollover snapshots attached to
  * every response, so on a 429 they cannot say which bucket refused, and the
  * earliest of them is typically the bucket that still had room — a wait that
- * lands straight back in the closed window. They reach the operator through
- * `rateLimitDiagnostics` instead.
+ * lands straight back in the closed window. The parsed reset supplies the retry
+ * hint; diagnostics omit raw provider headers and body text.
  */
 export const claudeRateLimitReset = (response, body, now) => {
     const unified = earliestReset(resetInstantFromHeader(response, 'anthropic-ratelimit-unified-reset', now), resetInstantFromHeader(response, 'anthropic-ratelimit-unified-fallback-reset', now));
@@ -249,12 +249,70 @@ export function isClaudePermanentRefreshError(error) {
         && (error.oauthCode === 'invalid_grant' || error.oauthCode === 'invalid_token');
 }
 export const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
-/** RFC3339 `resets_at` value → epoch ms, or undefined when absent/unparsable. */
+/** ISO-8601 or numeric epoch (seconds below 1e10 in magnitude, otherwise ms). */
 function claudeResetsAt(value) {
-    if (typeof value !== 'string' || value.length === 0)
+    let parsed;
+    if (typeof value === 'number') {
+        parsed = Math.trunc(Math.abs(value) < 1e10 ? value * 1000 : value);
+    }
+    else if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        parsed = Date.parse(value);
+    }
+    else {
         return undefined;
-    const parsed = Date.parse(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return Number.isFinite(parsed) && Number.isFinite(new Date(parsed).getTime()) ? parsed : undefined;
+}
+/**
+ * Read the observed cedar_ember shape from ItsJazii/pane, not an official
+ * contract. Each entry retains its grant id and counts; claimable is only
+ * read-only server-selection metadata, never an implemented redemption path.
+ */
+function claudeResetCredits(value, now) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const ember = value;
+    if (ember.eligible !== true || !Array.isArray(ember.grants))
+        return undefined;
+    const cooldownUntil = claudeResetsAt(ember.cooldown_until);
+    // An unparseable disclosed cooldown must not assert that claims are available.
+    const cooling = cooldownUntil === undefined
+        ? ember.cooldown_until !== undefined && ember.cooldown_until !== null
+        : cooldownUntil > now;
+    const credits = [];
+    let selected = false;
+    for (const raw of ember.grants) {
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+            continue;
+        const grant = raw;
+        const { id, resets_total: total, resets_left: left, usable_now: usable, paused } = grant;
+        const expiresAt = claudeResetsAt(grant.ends_at);
+        if (typeof id !== 'string' || id.trim().length === 0
+            || typeof total !== 'number' || !Number.isSafeInteger(total) || total < 1
+            || typeof left !== 'number' || !Number.isSafeInteger(left)
+            || expiresAt === undefined
+            || (usable !== undefined && typeof usable !== 'boolean')
+            || (paused !== undefined && typeof paused !== 'boolean'))
+            continue;
+        const resetsLeft = Math.max(0, Math.min(left, total));
+        if (resetsLeft === 0)
+            continue;
+        const claimable = !selected && id === ember.next_grant_id && usable === true
+            && paused !== true && !cooling && expiresAt > now;
+        if (claimable)
+            selected = true;
+        credits.push({
+            id,
+            expiresAt,
+            resetsTotal: total,
+            resetsLeft,
+            ...usable === undefined ? {} : { usableNow: usable },
+            ...paused === undefined ? {} : { paused },
+            claimable,
+            ...cooldownUntil === undefined ? {} : { cooldownUntil },
+        });
+    }
+    return credits.length > 0 ? credits : undefined;
 }
 /** Claude session and weekly buckets reset as whole five-hour/seven-day windows. */
 function claudeWindowTiming(kind) {
@@ -308,6 +366,10 @@ function claudeLimitsWindows(value) {
  * source of Claude Code's `/usage` screen). Newer responses carry a
  * structured `limits` array; older ones the flat `five_hour`/`seven_day*`
  * buckets — both shapes are read, the array winning when it has entries.
+ * Requests the optional cedar_ember banked-reset block with the existing CLI
+ * identity. A 400/403 retries once without that parameter; ordinary windows
+ * remain available and resetCreditsError records the optional lookup failure.
+ * Missing/ineligible blocks and empty or unusable grants expose no credits.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param signal - caller cancellation from the RPC transport.
@@ -316,7 +378,7 @@ function claudeLimitsWindows(value) {
  */
 export async function fetchClaudeUsage(session, fetchFn = hostFetch, signal, cliVersion = localClaudeCliVersion) {
     const userAgent = claudeCliUserAgent(await cliVersion());
-    const response = await fetchFn(CLAUDE_USAGE_URL, {
+    const init = {
         headers: {
             'authorization': `Bearer ${session.accessToken}`,
             'anthropic-beta': 'oauth-2025-04-20',
@@ -326,13 +388,25 @@ export async function fetchClaudeUsage(session, fetchFn = hostFetch, signal, cli
             'accept': 'application/json',
         },
         ...signal === undefined ? {} : { signal },
-    });
+    };
+    let response = await fetchFn(`${CLAUDE_USAGE_URL}?cedar_ember=1`, init);
+    let resetCreditsError;
+    if (response.status === 400 || response.status === 403) {
+        resetCreditsError = `Claude banked resets lookup failed (HTTP ${response.status}); using plain usage.`;
+        // Optional program support must not turn a working usage endpoint into an error.
+        response = await fetchFn(CLAUDE_USAGE_URL, init);
+    }
     if (!response.ok)
         throw await oauthEndpointError(response, 'claude usage');
     const payload = await response.json();
+    const resetCredits = resetCreditsError === undefined ? claudeResetCredits(payload.cedar_ember, Date.now()) : undefined;
+    const resets = {
+        ...resetCredits === undefined ? {} : { resetCredits },
+        ...resetCreditsError === undefined ? {} : { resetCreditsError },
+    };
     const modern = claudeLimitsWindows(payload.limits);
     if (modern.length > 0)
-        return { supported: true, windows: modern };
+        return { supported: true, windows: modern, ...resets };
     const windows = [];
     const legacy = [
         claudeLegacyWindow(payload.five_hour, 'session'),
@@ -344,7 +418,7 @@ export async function fetchClaudeUsage(session, fetchFn = hostFetch, signal, cli
         if (window !== undefined)
             windows.push(window);
     }
-    return { supported: true, windows };
+    return { supported: true, windows, ...resets };
 }
 function claudeThinkingType(capabilities) {
     const types = capabilities?.thinking?.types;
@@ -431,6 +505,14 @@ function claudeMaxTokens(configured, disc) {
  * this cap; 3.75MB encoded stays under the 5MB base64 per-image limit.
  */
 const CLAUDE_IMAGE_LIMIT = { maxEdge: 2000, maxBytes: 3_750_000 };
+/**
+ * Inline image data a Claude request may carry, in base64 bytes. Every turn
+ * resends the history, so screenshots accumulate until the request passes the
+ * API's 32MB body limit and every later turn and compaction fails with HTTP
+ * 413 `request_too_large`. Past this budget the host offloads the oldest
+ * images to text and retries; the remaining 12MB holds prompts, tools, and text.
+ */
+export const CLAUDE_REQUEST_IMAGE_BUDGET = 20 * 1024 * 1024;
 /** The Claude 4.5 family accepts image input. */
 const CLAUDE_MODALITIES = ['text', 'image'];
 /**
@@ -446,15 +528,23 @@ const CLAUDE_MODALITIES = ['text', 'image'];
  * @param maxTokens - the resolved output cap.
  * @param thinking - the thinking parameter, when the model takes one.
  * @param effort - the reasoning effort, when the model advertises efforts.
+ * @param cacheTtl - lifetime of every cache breakpoint; defaults to five minutes.
+ * Requests that carry a `purpose` (compaction, session titles) always use five
+ * minutes to preserve their existing auxiliary-request behavior. A five-minute
+ * mark can still read an entry a one-hour mark wrote.
  * @returns the JSON body to POST.
  */
-export function claudeRequestBody(options, messages, maxTokens, thinking, effort) {
+export function claudeRequestBody(options, messages, maxTokens, thinking, effort, cacheTtl) {
+    // Read structurally so older host types need not declare `purpose`. Hosts
+    // that do not classify auxiliary calls follow the configured TTL.
+    const purpose = options.purpose;
+    const ttl = purpose === undefined ? cacheTtl : undefined;
     const anthropicMessages = toAnthropicMessages(messages);
-    markMessageCache(anthropicMessages);
+    markMessageCache(anthropicMessages, ttl);
     return {
         model: options.model,
         max_tokens: maxTokens,
-        system: toAnthropicSystem(options.system, messages),
+        system: toAnthropicSystem(options.system, messages, ttl),
         messages: anthropicMessages,
         ...options.tools !== undefined && options.tools.length > 0
             ? { tools: toAnthropicTools(options.tools) }
@@ -659,6 +749,14 @@ export class ClaudeAdapter extends LlmAdapter {
     }
     async request(options, session, signal) {
         const messages = await resolveImages(options.messages, this.options.resolveAttachments?.(), signal, CLAUDE_IMAGE_LIMIT);
+        if (hostSupportsImageOffload()) {
+            const offloadImages = requiredImageOffloadCount(messages, CLAUDE_REQUEST_IMAGE_BUDGET);
+            if (offloadImages > 0) {
+                // Older dsh-llm option types lack `offloadImages`; 0.2+ hosts read it.
+                throw new LlmError(`claude request images exceed the ${CLAUDE_REQUEST_IMAGE_BUDGET}-byte base64 budget; `
+                    + `${offloadImages} more oldest image(s) must be offloaded`, IMAGE_OFFLOAD_REQUIRED, { offloadImages });
+            }
+        }
         const disc = await this.discovered(options.model);
         const maxTokens = options.maxTokens
             ?? claudeMaxTokens(this.options.models.find(entry => entry.id === options.model), disc);
@@ -666,7 +764,7 @@ export class ClaudeAdapter extends LlmAdapter {
         const effort = options.reasoningEffort !== undefined && disc?.reasoning !== undefined
             ? String(options.reasoningEffort)
             : undefined;
-        const body = claudeRequestBody(options, messages, maxTokens, thinking, effort);
+        const body = claudeRequestBody(options, messages, maxTokens, thinking, effort, this.options.promptCacheTtl);
         const cliVersion = await (this.options.resolveCliVersion ?? localClaudeCliVersion)();
         return hostFetch(CLAUDE_API_URL, {
             method: 'POST',

package/lib/providers/codex.d.ts

@@ -26,8 +26,8 @@ export declare const CODEX_PREEMPT_MS: number;
  * rollover snapshots the backend attaches to every response, one per window,
  * so they say nothing about which window refused: a burst 429 that would clear
  * in seconds still carries a primary rollover hours out, and reading it would
- * park the turn for those hours. They reach the operator through
- * `rateLimitDiagnostics` instead.
+ * park the turn for those hours. The parsed body reset supplies the retry hint;
+ * diagnostics omit raw provider headers and body text.
  */
 export declare const codexRateLimitReset: RateLimitResetReader;
 /**
@@ -77,6 +77,11 @@ export declare function refreshCodex(session: CodexSession): Promise<CodexSessio
  */
 export declare function isCodexPermanentRefreshError(error: unknown): boolean;
 export declare const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+export declare const CODEX_RESET_CREDITS_URL = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits";
+/** Read banked resets without spending them; consumption uses a separate explicit POST. */
+export declare function fetchCodexResetCredits(session: CodexSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<NonNullable<ProviderUsage['resetCredits']>>;
+/** Submit one explicit reset; ambiguous or unconfirmed responses throw without retry. */
+export declare function consumeCodexResetCredit(session: CodexSession, creditId: string, requestId: string, fetchFn?: FetchFn, signal?: AbortSignal): Promise<void>;
 /**
  * Fetch the codex subscription usage from the ChatGPT backend wham/usage
  * endpoint (the source of the codex CLI `/status` rate-limit lines). The
@@ -164,6 +169,14 @@ export declare const CODEX_UNKNOWN_TOOL_OUTCOME = "The tool call has no recorded
  * @returns the same array when already balanced, otherwise a repaired array.
  */
 export declare function reconcileResponsesToolCalls(input: ResponsesRequestInput['input']): ResponsesRequestInput['input'];
+/**
+ * The `reasoning.effort` wire value for a selected effort. Codex's "ultra" is
+ * a client-side selection (max reasoning plus proactive sub-agent delegation)
+ * that the Codex CLI itself lowers to `max` at the Responses API boundary;
+ * the backend answers HTTP 400 to a literal `ultra`. Discovery no longer
+ * lists it, but an effort saved before that change may still arrive here.
+ */
+export declare function codexWireEffort(effort: string): string;
 /**
  * The Responses request body for one generation. A fast-tier request (the
  * composer Speed toggle, the codex CLI's fast mode) carries

package/lib/providers/codex.js

@@ -35,8 +35,8 @@ const CODEX_RESET_FIELDS = ['resets_in_seconds', 'reset_after_seconds', 'resets_
  * rollover snapshots the backend attaches to every response, one per window,
  * so they say nothing about which window refused: a burst 429 that would clear
  * in seconds still carries a primary rollover hours out, and reading it would
- * park the turn for those hours. They reach the operator through
- * `rateLimitDiagnostics` instead.
+ * park the turn for those hours. The parsed body reset supplies the retry hint;
+ * diagnostics omit raw provider headers and body text.
  */
 export const codexRateLimitReset = (_response, body, now) => resetFromFields(jsonBody(body), CODEX_RESET_FIELDS, now);
 /** Default instruction when the request carries no system prompt. */
@@ -217,6 +217,62 @@ export function isCodexPermanentRefreshError(error) {
         && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
 export const CODEX_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+export const CODEX_RESET_CREDITS_URL = 'https://chatgpt.com/backend-api/wham/rate-limit-reset-credits';
+function parseResetDate(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+/** Read banked resets without spending them; consumption uses a separate explicit POST. */
+export async function fetchCodexResetCredits(session, fetchFn = hostFetch, signal) {
+    const response = await fetchFn(CODEX_RESET_CREDITS_URL, {
+        headers: {
+            authorization: `Bearer ${session.accessToken}`,
+            'chatgpt-account-id': session.accountId,
+            originator: 'Codex Desktop',
+            'openai-beta': 'codex-1',
+            accept: 'application/json',
+            ...attributionHeaders(),
+        },
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'codex reset credits');
+    const payload = await response.json();
+    if (!Array.isArray(payload?.credits))
+        throw new Error('codex reset credits: unexpected response (missing credits array)');
+    return payload.credits.flatMap((value) => {
+        if (typeof value !== 'object' || value === null)
+            return [];
+        const credit = value;
+        if (credit.status !== 'available' || credit.reset_type !== 'codex_rate_limits')
+            return [];
+        const grantedAt = parseResetDate(credit.granted_at);
+        const expiresAt = parseResetDate(credit.expires_at);
+        return [{ ...(typeof credit.id === 'string' ? { id: credit.id } : {}), ...(grantedAt === undefined ? {} : { grantedAt }), ...(expiresAt === undefined ? {} : { expiresAt }) }];
+    });
+}
+/** Submit one explicit reset; ambiguous or unconfirmed responses throw without retry. */
+export async function consumeCodexResetCredit(session, creditId, requestId, fetchFn = hostFetch, signal) {
+    const response = await fetchFn(CODEX_RESET_CREDITS_URL + '/consume', {
+        method: 'POST',
+        headers: {
+            authorization: 'Bearer ' + session.accessToken,
+            'chatgpt-account-id': session.accountId,
+            originator: 'Codex Desktop', 'openai-beta': 'codex-1',
+            'content-type': 'application/json', accept: 'application/json',
+            ...attributionHeaders(),
+        },
+        body: JSON.stringify({ redeem_request_id: requestId, credit_id: creditId }),
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'codex consume reset');
+    const payload = await response.json();
+    if (payload?.code !== 'reset')
+        throw new Error('Reset was not confirmed. Verify the account in Codex before retrying.');
+}
 /** Seconds of the canonical 5-hour session and 7-day weekly windows. */
 const SESSION_WINDOW_SECONDS = 5 * 60 * 60;
 const WEEKLY_WINDOW_SECONDS = 7 * 24 * 60 * 60;
@@ -365,8 +421,10 @@ export async function fetchCodexModels(session, fetchFn = hostFetch, signal, cli
         // dropped, and an absent or unknown value is included (in doubt, include).
         if (entry.visibility === 'hide' || entry.visibility === 'none')
             continue;
+        // "ultra" is a Codex-client mode (max reasoning + automatic sub-agent
+        // delegation), not a wire value: the Responses API rejects it with HTTP 400.
         const efforts = (entry.supported_reasoning_levels ?? [])
-            .filter(level => typeof level.effort === 'string' && level.effort.length > 0)
+            .filter(level => typeof level.effort === 'string' && level.effort.length > 0 && level.effort !== 'ultra')
             .map(level => ({
             id: ReasoningEffortId(level.effort),
             name: effortDisplayName(level.effort),
@@ -491,6 +549,16 @@ export function reconcileResponsesToolCalls(input) {
     }
     return balanced;
 }
+/**
+ * The `reasoning.effort` wire value for a selected effort. Codex's "ultra" is
+ * a client-side selection (max reasoning plus proactive sub-agent delegation)
+ * that the Codex CLI itself lowers to `max` at the Responses API boundary;
+ * the backend answers HTTP 400 to a literal `ultra`. Discovery no longer
+ * lists it, but an effort saved before that change may still arrive here.
+ */
+export function codexWireEffort(effort) {
+    return effort === 'ultra' ? 'max' : effort;
+}
 /**
  * The Responses request body for one generation. A fast-tier request (the
  * composer Speed toggle, the codex CLI's fast mode) carries
@@ -509,7 +577,7 @@ export function codexRequestBody(options, resolved, fast) {
             ? { tools: toResponsesTools(options.tools, { strict: false }), tool_choice: 'auto', parallel_tool_calls: true }
             : {},
         ...options.reasoningEffort !== undefined
-            ? { reasoning: { effort: String(options.reasoningEffort), summary: 'auto' } }
+            ? { reasoning: { effort: codexWireEffort(String(options.reasoningEffort)), summary: 'auto' } }
             : {},
         store: false,
         stream: true,

package/lib/providers/common.d.ts

@@ -200,6 +200,27 @@ export interface UsageWindow {
     /** Provider-verified fixed interval; permits deriving start from end and duration. */
     fixedWindow?: boolean;
 }
+/** One banked reset credit (Codex), or one grant containing resets (Claude). */
+export interface ResetCredit {
+    id?: string;
+    grantedAt?: number;
+    /** Expiration in epoch ms; never a recurring usage-window reset. */
+    expiresAt?: number;
+    /** Claude grant counts; one array entry per grant, not per remaining reset. */
+    resetsTotal?: number;
+    resetsLeft?: number;
+    /** Claude's disclosed grant state, absent when the server omits it. */
+    usableNow?: boolean;
+    paused?: boolean;
+    /**
+     * Claude server-selected grant is currently usable. Read-only metadata, not
+     * permission to redeem; no Claude redemption endpoint is implemented.
+     * Codex entries omit this field and retain their existing semantics.
+     */
+    claimable?: boolean;
+    /** Claude program cooldown in epoch ms, repeated on each grant when disclosed. */
+    cooldownUntil?: number;
+}
 /** Subscription usage of one provider, as served by the `usage` RPC endpoint. */
 export interface ProviderUsage {
     /** Original successful observation time, preserved across cache reads. */
@@ -212,6 +233,10 @@ export interface ProviderUsage {
     windows?: UsageWindow[];
     /** Plan name the usage endpoint reported, when present. */
     plan?: string;
+    /** Banked Codex resets or Claude grants, when the provider discloses them. */
+    resetCredits?: ResetCredit[];
+    /** Optional reset lookup failure; ordinary usage remains usable. */
+    resetCreditsError?: string;
 }
 /** One model discovered from a provider's live model-list endpoint. */
 export interface DiscoveredModel {