dsh-subscriptions 0.1.3 → 0.1.5

package/lib/model-defaults.d.ts

@@ -6,12 +6,11 @@ export type ModelDefaults = Readonly<Partial<Record<ProviderId, ModelDefaultMap>
 /** Absolute path of the defaults file. */
 export declare function modelDefaultsFilePath(): string;
 /**
- * The last load failure, or a warning about entries that were skipped while
- * loading; consumers only use it for diagnostics.
+ * Ready the defaults store.
+ * index.ts calls it at apply time so every later synchronous read sees the
+ * persisted state; store tests also call it after resetting the singleton.
  */
-export declare function modelDefaultsLoadError(): unknown;
-/** A detached snapshot for the RPC surface (render + diffing). */
-export declare function modelDefaultsSnapshot(): ModelDefaults;
+export declare function loadModelDefaults(): Promise<void>;
 /**
  * Set or clear one model's configured default effort, then persist. The
  * memory snapshot updates only after the atomic write succeeds, so a failed

package/lib/model-defaults.js

@@ -8,10 +8,10 @@
  * chip the model picker shows when the discovered catalog advertises no
  * default at all.
  *
- * Writes are single-process and atomic, but *not* as serialised as the rest
- * of the page: the Settings page disables only the row being saved, so two
- * rows saved back to back can overlap. The write chain below serialises them,
- * so no update is lost to a read-modify-write race. Every read comes from the
+ * Writes are single-process and atomic. The account manager submits effort
+ * edits sequentially and disables its editor while saving, but concurrent RPC
+ * callers can still overlap. The write chain below serialises them, so no
+ * update is lost to a read-modify-write race. Every read comes from the
  * in-memory snapshot, so the on-disk file only needs to survive a restart: a
  * malformed file reads as empty and is rewritten on the next save, never
  * taking the plugin down with it.
@@ -29,21 +29,21 @@ const EMPTY = Object.freeze({});
 let current = EMPTY;
 /** One lazy load of the on-disk file (read once per process). */
 let ready;
-/** Last load failure, surfaced to callers that care; defaults stay empty. */
+/** Last load failure or skipped-entry warning, inspected only by tests. */
 let loadError;
 /**
  * Serialises every write: the read-modify-write sequence must not interleave,
  * or a fast second save would compute its snapshot from the stale `current`
- * and silently drop the first update (the UI disables only the row being
- * saved, so overlaps are reachable).
+ * and silently drop the first update. Concurrent RPC callers can overlap
+ * even though one account-manager dialog submits its edits sequentially.
  */
 let writeChain = Promise.resolve();
 /**
  * Validate one persisted provider section: a string→string map, or undefined.
  * Malformed *entries* are skipped, not the whole section: one bad value (a
  * hand edit losing its quotes) must not silently un-configure every model in
- * that provider. What was dropped is reported so the caller can surface it
- * instead of the loss disappearing.
+ * that provider. Dropped model ids are recorded in a test-only load warning;
+ * production callers do not surface this warning.
  */
 function sanitizeProvider(value, dropped) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
@@ -136,15 +136,16 @@ function sectionOf(defaults, provider) {
 }
 /**
  * Ready the defaults store.
- * @internal Exported for tests; index.ts calls it at apply time so every
- * later synchronous read sees the persisted state.
+ * index.ts calls it at apply time so every later synchronous read sees the
+ * persisted state; store tests also call it after resetting the singleton.
  */
 export async function loadModelDefaults() {
     await ensureReady();
 }
 /**
- * The last load failure, or a warning about entries that were skipped while
- * loading; consumers only use it for diagnostics.
+ * Test-only observation of the last load failure or skipped-entry warning.
+ * No production diagnostic consumer currently reads it.
+ * @internal Exported for tests only.
  */
 export function modelDefaultsLoadError() {
     return loadError;
@@ -164,7 +165,10 @@ export function defaultEffortOf(provider, model) {
     // breaks that model's resolution).
     return Object.prototype.hasOwnProperty.call(section, model) ? section[model] : undefined;
 }
-/** A detached snapshot for the RPC surface (render + diffing). */
+/**
+ * Detached snapshot for store assertions in tests; no production RPC uses it.
+ * @internal Exported for tests only.
+ */
 export function modelDefaultsSnapshot() {
     const result = {};
     for (const provider of PROVIDER_IDS) {

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/antigravity.d.ts

@@ -60,8 +60,6 @@ export declare function isAntigravityPermanentRefreshError(error: unknown): bool
 export declare function fetchAntigravityModels(session: AntigravitySession, runtime?: AntigravityRuntimeConfig, fetchFn?: FetchFn, signal?: AbortSignal): Promise<DiscoveredModel[]>;
 /** Fetch plan and per-model quota windows when the upstream exposes them. */
 export declare function fetchAntigravityUsage(session: AntigravitySession, runtime?: AntigravityRuntimeConfig, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
-/** URL for either v1internal generation transport. */
-export declare function antigravityGenerateURL(baseURL: string | undefined, stream: boolean): string;
 /** Forward one already-built payload to generateContent or streamGenerateContent. */
 export declare function requestAntigravityContent(session: AntigravitySession, payload: AntigravityRequest, stream: boolean, runtime?: AntigravityRuntimeConfig, fetchFn?: FetchFn, signal?: AbortSignal): Promise<Response>;
 export interface AntigravityAdapterOptions {

package/lib/providers/antigravity.js

@@ -7,7 +7,7 @@ import { errorChain, EMPTY_RESPONSE_CODE, LlmAdapter, LlmError } from '@deepseek
 import { resolveImages } from '../translate/resolved.js';
 import { antigravityReasoning } from '../translate/antigravity-thinking.js';
 import { parseAntigravityResponse, streamAntigravity, toAntigravityRequest, } from '../translate/antigravity.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverOrRetryAuth, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, discoverAcrossAccounts, isDiscoveryAborted, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverOrRetryAuth, isMissingOrInvalidCredential, parseProviderJson, oauthEndpointError, OAuthEndpointError, discoverAcrossAccounts, isDiscoveryAborted, } from './common.js';
 import { hostFetch } from '../http.js';
 import { ANTIGRAVITY_DEFAULT_CLIENT_ID, ANTIGRAVITY_DEFAULT_CLIENT_SECRET } from './antigravity-oauth-client.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
@@ -126,7 +126,7 @@ async function callInternal(method, body, accessToken, runtime, fetchFn, signal)
     }, runtime, fetchFn);
     if (!response.ok)
         throw await httpLlmError(response, `Antigravity ${method}`);
-    return response.json();
+    return parseProviderJson(response, `Antigravity ${method}`);
 }
 function projectIdOf(value) {
     if (typeof value === 'string' && value.length > 0)
@@ -217,7 +217,7 @@ export async function exchangeAntigravityCode(code, verifier, redirectUri, oauth
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'Antigravity');
-    const tokens = await response.json();
+    const tokens = await parseProviderJson(response, 'Antigravity token exchange');
     if (typeof tokens.access_token !== 'string')
         throw new Error('Antigravity token endpoint returned no access token');
     const account = await discoverAntigravityAccount(tokens.access_token, runtime, fetchFn);
@@ -238,7 +238,7 @@ export async function refreshAntigravity(session, oauth, fetchFn = hostFetch) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'Antigravity');
-    return sessionFromTokens(await response.json(), {
+    return sessionFromTokens(await parseProviderJson(response, 'Antigravity token refresh'), {
         projectId: session.projectId,
         ...session.account === undefined ? {} : { account: session.account },
         ...session.plan === undefined ? {} : { plan: session.plan },
@@ -313,10 +313,6 @@ export async function fetchAntigravityUsage(session, runtime = {}, fetchFn = hos
         ...displayPlan === undefined ? {} : { plan: displayPlan },
     };
 }
-/** URL for either v1internal generation transport. */
-export function antigravityGenerateURL(baseURL, stream) {
-    return `${antigravityBaseURL(baseURL)}/v1internal:${stream ? 'streamGenerateContent?alt=sse' : 'generateContent'}`;
-}
 /** Forward one already-built payload to generateContent or streamGenerateContent. */
 export async function requestAntigravityContent(session, payload, stream, runtime = {}, fetchFn = hostFetch, signal) {
     return fetchAntigravity(stream ? 'streamGenerateContent?alt=sse' : 'generateContent', {
@@ -511,6 +507,6 @@ export class AntigravityAdapter extends LlmAdapter {
         const response = await requestAntigravityContent(session, toAntigravityRequest(options, messages, session.projectId), false, this.options.runtime, this.options.fetchFn, options.signal);
         if (!response.ok)
             throw await httpLlmError(response, 'Antigravity API');
-        return parseAntigravityResponse(await response.json());
+        return parseAntigravityResponse(await parseProviderJson(response, 'Antigravity generateContent'));
     }
 }

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,9 +5,9 @@
  */
 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 { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, parseProviderJson, oauthEndpointError, OAuthEndpointError, } from './common.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
 import { hostFetch } from '../http.js';
 import { compareVersions } from './npm-cli-version.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));
@@ -212,7 +212,7 @@ export async function exchangeClaudeCode(code, verifier, redirectUri, state) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'claude');
-    return claudeSession(await response.json(), undefined, true);
+    return claudeSession(await parseProviderJson(response, 'claude token exchange'), undefined, true);
 }
 /**
  * Refresh a claude session (JSON grant echoing the issued scope).
@@ -232,7 +232,7 @@ export async function refreshClaude(session) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'claude');
-    const next = await claudeSession(await response.json(), session.refreshToken, false);
+    const next = await claudeSession(await parseProviderJson(response, 'claude token refresh'), session.refreshToken, false);
     return {
         ...next,
         ...session.emailAddress === undefined ? {} : { emailAddress: session.emailAddress },
@@ -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 payload = await parseProviderJson(response, 'claude usage');
+    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;
@@ -388,7 +462,7 @@ export async function fetchClaudeModels(session, fetchFn = hostFetch, signal, cl
     });
     if (!response.ok)
         throw await httpLlmError(response, 'claude models API');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'claude models API');
     if (!Array.isArray(payload.data)) {
         throw new Error('claude models API returned an invalid catalog');
     }
@@ -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) {
+                // The supported 0.1.7-rc.2 floor reads `offloadImages`; older option types lack 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',