dsh-subscriptions 0.1.3 → 0.1.5

package/lib/providers/pool.js

@@ -10,6 +10,7 @@
 import { EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, } from '@deepseek-ai/dsh-llm';
 import { poolKey } from './pool-family.js';
 import { accountKey, classifyPoolFailure, memberKey, PoolHealthRegistry } from './pool-health.js';
+import { streamAccountWithReplay } from './replay.js';
 /** Bound on sticky-session memory; oldest entries evict past it. */
 const STICKY_SESSION_LIMIT = 1000;
 /** Display form of one member (account shown when pinned). */
@@ -200,6 +201,12 @@ export class PoolAdapter extends LlmAdapter {
             ...modalities === undefined ? {} : { inputModalities: modalities },
         };
     }
+    /**
+     * Fail over before output. A single non-quota failure keeps its identity
+     * and shared provider message, with scoped pool recovery or its own hint as fallback.
+     * Multiple failures carry a bounded summary and all attempts in an AggregateError cause.
+     * Pure quota/rate exhaustion retains RATE_LIMIT and this pool's earliest recovery hint.
+     */
     async *stream(options) {
         const definition = (await this.pools()).get(poolKey(options.provider, options.model));
         if (definition === undefined)
@@ -208,12 +215,12 @@ export class PoolAdapter extends LlmAdapter {
         const candidates = await this.select(options.model, members, options.sessionId);
         if (candidates.length === 0)
             throw this.exhausted(options.model, members);
-        let lastError;
+        const failures = [];
         for (const member of candidates) {
             const adapter = this.options.adapters[member.provider];
             if (adapter === undefined)
                 continue;
-            const iterator = adapter.streamAccount({ ...options, provider: member.provider, model: member.model }, member.account)[Symbol.asyncIterator]();
+            const iterator = streamAccountWithReplay(adapter, { ...options, provider: member.provider }, member.account, member.model)[Symbol.asyncIterator]();
             let first;
             try {
                 first = await iterator.next();
@@ -223,7 +230,7 @@ export class PoolAdapter extends LlmAdapter {
             }
             catch (error) {
                 const classification = classifyPoolFailure(error, member.provider);
-                if (classification.action === 'throw')
+                if (classification.action === 'throw' || !(error instanceof LlmError))
                     throw error;
                 if ('cooldownMs' in classification) {
                     this.options.health.markUnavailable(classification.scope === 'account'
@@ -238,7 +245,7 @@ export class PoolAdapter extends LlmAdapter {
                 }
                 this.options.onWarn(`pool "${options.model}": ${memberLabel(member)} failed before any output`
                     + ` (${error instanceof Error ? error.message : String(error)}); trying the next member`);
-                lastError = error;
+                failures.push(error);
                 continue;
             }
             this.remember(options.model, options.sessionId, member);
@@ -264,7 +271,7 @@ export class PoolAdapter extends LlmAdapter {
             }
             return;
         }
-        throw this.exhausted(options.model, members, lastError);
+        throw this.exhausted(options.model, members, failures);
     }
     /**
      * Order the candidates for one request. Health filters both strategies;
@@ -316,12 +323,11 @@ export class PoolAdapter extends LlmAdapter {
         }
         this.sticky.set(key, memberKey(member.provider, member.account, member.model));
     }
-    /**
-     * The error for an exhausted pool, carrying the earliest recovery hint of
-     * THIS pool's members (the health registry is shared across pools, so the
-     * hint is scoped to the keys this pool can actually recover through).
-     */
-    exhausted(model, pool, cause) {
+    /** Report attempt failures or this pool's active cooldowns, never unrelated health records. */
+    exhausted(model, pool, failures = []) {
+        if (pool.length === 0) {
+            return new LlmError(`pool "${model}" has no usable member: no account could be resolved`, 'NO_ADAPTER');
+        }
         const keys = new Set();
         for (const member of pool) {
             keys.add(memberKey(member.provider, member.account, member.model));
@@ -329,12 +335,83 @@ export class PoolAdapter extends LlmAdapter {
         }
         const recovery = this.options.health.earliestRecovery(keys);
         const retryAfterMs = recovery === undefined ? undefined : Math.max(recovery - Date.now(), 1);
-        return new LlmError(`pool "${model}" exhausted: every member is unavailable or failed`, 'RATE_LIMIT', {
+        const coolingReasons = this.options.health.unavailableReasons(keys);
+        const codes = [...failures.map(error => error.code), ...coolingReasons];
+        if (codes.length === 0)
+            return new LlmError(`pool "${model}" has no usable member`, 'NO_ADAPTER');
+        const quotaOnly = codes.every(isQuotaFailure);
+        if (failures.length === 1 && !isQuotaFailure(failures[0].code)) {
+            const failure = failures[0];
+            // Keep the same error, code, status and cause. The message arrives already
+            // free of provider text: the shared converter in common.ts owns that, and
+            // non-pooled callers receive the same text, so the pool adds no sanitizer
+            // of its own and cannot make the two paths disagree.
+            // The pool's earliest scoped recovery wins even if the member's hint is
+            // later: another member may recover sooner. Without scoped recovery,
+            // keep the member hint; with neither, leave it absent.
+            // Keep the error object itself. LlmError freezes its facts snapshot, so
+            // replace that snapshot to correct only providerRetryAfterMs for pool
+            // routing; this is not permission to rewrite other frozen failure facts.
+            if (retryAfterMs !== undefined && retryAfterMs !== failure.failure.providerRetryAfterMs) {
+                Object.defineProperty(failure, 'failure', {
+                    value: Object.freeze({ ...failure.failure, providerRetryAfterMs: retryAfterMs }),
+                });
+            }
+            return failure;
+        }
+        const attemptedCodes = failures.map(error => error.code);
+        const details = [...attemptedCodes, ...coolingReasons.filter(code => !attemptedCodes.includes(code))];
+        const summary = failureSummary(details);
+        const cause = failures.length === 0
+            ? undefined
+            : failures.length === 1
+                ? failures[0]
+                : new AggregateError(failures, `${failures.length} pool members failed: ${summary}`);
+        // Subscription quotas reopen: preserve the existing retry classification and text.
+        const message = quotaOnly
+            ? `pool "${model}" exhausted: every member is unavailable or failed`
+            : failures.length > 0
+                ? `pool "${model}" exhausted: ${failures.length} ${failures.length === 1 ? 'member' : 'members'} failed (${summary})`
+                : `pool "${model}" unavailable: ${pool.length} members are cooling down (${summary})`;
+        // For mixed failures, a real non-quota failure must not become a rate limit
+        // merely because the last member hit its quota. No new aggregate error code.
+        const code = quotaOnly
+            ? 'RATE_LIMIT'
+            : attemptedCodes.filter(code => !isQuotaFailure(code)).at(-1)
+                ?? coolingReasons.filter(code => !isQuotaFailure(code)).at(-1);
+        return new LlmError(message, code, {
             ...retryAfterMs === undefined ? {} : { providerRetryAfterMs: retryAfterMs },
             ...cause === undefined ? {} : { cause },
         });
     }
 }
+function isQuotaFailure(code) {
+    return code === QUOTA_EXCEEDED_CODE || code === 'RATE_LIMIT';
+}
+/** Summaries use stable codes only: adapter messages and nested causes can contain raw payloads. */
+function failureSummary(codes) {
+    const descriptions = {
+        AUTH: 'authentication failed',
+        INVALID_CREDENTIAL: 'credential is invalid',
+        MISSING_CREDENTIAL: 'credential is missing',
+        SERVER: 'provider server failed',
+        TIMEOUT: 'provider request timed out',
+        EMPTY_RESPONSE: 'provider returned no output',
+        TRANSPORT: 'provider connection failed',
+        HTTP_402: 'provider plan unavailable',
+        HTTP_404: 'provider model unavailable',
+        QUOTA: 'provider quota exhausted',
+        RATE_LIMIT: 'provider rate limit reached',
+    };
+    const limit = 5;
+    const shown = codes.slice(0, limit).map(code => {
+        const description = descriptions[code];
+        return description === undefined ? 'member unavailable' : `${code}: ${description}`;
+    });
+    if (codes.length > limit)
+        shown.push(`${codes.length - limit} more`);
+    return shown.join('; ');
+}
 function stickyKey(poolId, sessionId) {
     return `${String(sessionId)}|${poolId}`;
 }

package/lib/providers/rate-limit.d.ts

@@ -110,20 +110,6 @@ export declare function earliestReset(...candidates: (number | undefined)[]): nu
  * @returns the wait in milliseconds, never below {@link MIN_WAIT_MS}.
  */
 export declare function waitFromReset(instant: number, now: number): number;
-/**
- * Render the rate-limit-shaped headers and the head of the body of a 429 whose
- * reset instant nothing parsed. Emitted through the adapter's `onWarn`, this is
- * how an unrecognized provider field gets named from live traffic instead of
- * being guessed at.
- *
- * It is also where the per-bucket rollover snapshots land by design — no reader
- * parks a turn on one, because on a 429 they cannot say which bucket refused —
- * so the operator still sees what the provider disclosed.
- * @param response - the failed response.
- * @param body - the complete response body.
- * @returns a one-line diagnostic.
- */
-export declare function rateLimitDiagnostics(response: Response, body: string): string;
 /** Per-route retry shape a subscription adapter starts from. */
 export interface RetryDefaults {
     /** Retries after the first attempt. */

package/lib/providers/rate-limit.js

@@ -238,32 +238,6 @@ export function earliestReset(...candidates) {
 export function waitFromReset(instant, now) {
     return Math.max(MIN_WAIT_MS, instant - now + RESET_GRACE_MS);
 }
-/** Header names worth showing when a 429 disclosed no reset this code recognizes. */
-const DIAGNOSTIC_HEADER = /rate-?limit|retry|reset|^x-codex-/i;
-/**
- * Render the rate-limit-shaped headers and the head of the body of a 429 whose
- * reset instant nothing parsed. Emitted through the adapter's `onWarn`, this is
- * how an unrecognized provider field gets named from live traffic instead of
- * being guessed at.
- *
- * It is also where the per-bucket rollover snapshots land by design — no reader
- * parks a turn on one, because on a 429 they cannot say which bucket refused —
- * so the operator still sees what the provider disclosed.
- * @param response - the failed response.
- * @param body - the complete response body.
- * @returns a one-line diagnostic.
- */
-export function rateLimitDiagnostics(response, body) {
-    const headers = [];
-    response.headers.forEach((value, key) => {
-        if (DIAGNOSTIC_HEADER.test(key))
-            headers.push(`${key}: ${value}`);
-    });
-    headers.sort();
-    const rendered = headers.length > 0 ? headers.join('; ') : '(none)';
-    const head = body.slice(0, 200);
-    return `429 disclosed no reset time; headers [${rendered}]; body ${head.length > 0 ? head : '(empty)'}`;
-}
 /**
  * The retry shape every subscription route starts from: Claude Code's own SDK
  * numbers — ten retries after the first attempt, exponential backoff from 1s

package/lib/providers/replay.d.ts

@@ -0,0 +1,4 @@
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AccountAwareAdapter } from './accounts.js';
+/** Bind opaque replay to the concrete account/model behind a route alias. */
+export declare function streamAccountWithReplay(adapter: AccountAwareAdapter, options: GenerateOptions, account: string, model?: string): AsyncIterable<StreamChunk>;

package/lib/providers/replay.js

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+const REPLAY_KIND = 'subscriptions-account-replay';
+/** Bind opaque replay to the concrete account/model behind a route alias. */
+export async function* streamAccountWithReplay(adapter, options, account, model = options.model) {
+    const key = createHash('sha256')
+        .update(JSON.stringify([options.provider, account, model])).digest('hex');
+    const messages = options.messages.map(message => {
+        if (message.role !== 'assistant'
+            || message.source?.replayState === undefined)
+            return message;
+        const source = message.source;
+        if (source.replayState === null || typeof source.replayState !== 'object'
+            || !('response' in source.replayState))
+            return message;
+        const replay = source.replayState;
+        const response = replay.response;
+        if (response !== null && typeof response === 'object'
+            && 'kind' in response && response.kind === REPLAY_KIND) {
+            if ('version' in response && response.version === 1
+                && 'key' in response && response.key === key && 'state' in response) {
+                return { ...message, source: {
+                        ...source, provider: options.provider, model,
+                        replayState: { ...replay, response: response.state },
+                    } };
+            }
+            const { replayState: _discarded, ...withoutReplay } = source;
+            return { ...message, source: withoutReplay };
+        }
+        // Legacy replay has no originating-account identity. Preserve direct
+        // histories when provider/model match, as upstream does; switching
+        // accounts mid-session can therefore reuse the previous account's signed
+        // request prefix. An alias cannot identify the legacy concrete member.
+        if (source.provider === options.provider && source.model === model) {
+            return message;
+        }
+        const { replayState: _discarded, ...withoutReplay } = source;
+        return { ...message, source: withoutReplay };
+    });
+    for await (const chunk of adapter.streamAccount({
+        ...options, model, messages,
+    }, account)) {
+        if (chunk.type === 'finish' && chunk.replayState !== undefined) {
+            yield { ...chunk, replayState: { ...chunk.replayState, response: {
+                        kind: REPLAY_KIND, version: 1, key, state: chunk.replayState.response,
+                    } } };
+        }
+        else
+            yield chunk;
+    }
+}

package/lib/providers/reset-redemption.d.ts

@@ -0,0 +1,51 @@
+import type { ProviderUsage } from './common.js';
+export interface ResetConfirmation {
+    ticket: string;
+    expiresAt: number;
+    creditExpiresAt?: number;
+    weeklyUsedPercent: number;
+}
+/**
+ * Manual-only redemption with single-use tickets. An ambiguous submission parks
+ * the account to prevent an immediate blind retry. This block is process-local,
+ * not a durable rate limit: restarting the host clears it. Re-check credits and
+ * limits in Codex before retrying; a lost success response may have spent a
+ * credit already, and another submission can spend another credit.
+ * Rationale: [manual reset note](../../.agents/notes/implemented/provider/2026-10-04-codex-manual-reset.md).
+ */
+export declare class ResetRedemption {
+    private readonly read;
+    private readonly consume;
+    private readonly invalidate;
+    /**
+     * Stable identity for one real account: the same key the usage cache uses,
+     * so the guards and the cache invalidate together. The RPC carries whatever
+     * reference the browser holds — a canonical id, a legacy key, an email, a
+     * workspace id — and all of them resolve to one stored account.
+     *
+     * It must not fall back to the raw reference on failure. A fallback would
+     * re-key the state by whatever happened to arrive, so a transient lookup
+     * error could let a later alias past an uncertain park. Resolution here
+     * reads the local credential store only, so failing is safe and honest.
+     */
+    private readonly canonical;
+    private tickets;
+    private busy;
+    private uncertain;
+    constructor(read: (account: string, signal: AbortSignal) => Promise<ProviderUsage>, consume: (account: string, creditId: string, requestId: string, signal: AbortSignal) => Promise<void>, invalidate: (account: string) => void, 
+    /**
+     * Stable identity for one real account: the same key the usage cache uses,
+     * so the guards and the cache invalidate together. The RPC carries whatever
+     * reference the browser holds — a canonical id, a legacy key, an email, a
+     * workspace id — and all of them resolve to one stored account.
+     *
+     * It must not fall back to the raw reference on failure. A fallback would
+     * re-key the state by whatever happened to arrive, so a transient lookup
+     * error could let a later alias past an uncertain park. Resolution here
+     * reads the local credential store only, so failing is safe and honest.
+     */
+    canonical: (account: string, signal: AbortSignal) => Promise<string>);
+    private eligible;
+    prepare(account: string, signal: AbortSignal): Promise<ResetConfirmation>;
+    redeem(account: string, ticket: string, signal: AbortSignal): Promise<void>;
+}

package/lib/providers/reset-redemption.js

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Manual-only redemption with single-use tickets. An ambiguous submission parks
+ * the account to prevent an immediate blind retry. This block is process-local,
+ * not a durable rate limit: restarting the host clears it. Re-check credits and
+ * limits in Codex before retrying; a lost success response may have spent a
+ * credit already, and another submission can spend another credit.
+ * Rationale: [manual reset note](../../.agents/notes/implemented/provider/2026-10-04-codex-manual-reset.md).
+ */
+export class ResetRedemption {
+    read;
+    consume;
+    invalidate;
+    canonical;
+    tickets = new Map();
+    busy = new Set();
+    uncertain = new Set();
+    constructor(read, consume, invalidate, 
+    /**
+     * Stable identity for one real account: the same key the usage cache uses,
+     * so the guards and the cache invalidate together. The RPC carries whatever
+     * reference the browser holds — a canonical id, a legacy key, an email, a
+     * workspace id — and all of them resolve to one stored account.
+     *
+     * It must not fall back to the raw reference on failure. A fallback would
+     * re-key the state by whatever happened to arrive, so a transient lookup
+     * error could let a later alias past an uncertain park. Resolution here
+     * reads the local credential store only, so failing is safe and honest.
+     */
+    canonical) {
+        this.read = read;
+        this.consume = consume;
+        this.invalidate = invalidate;
+        this.canonical = canonical;
+    }
+    eligible(usage) {
+        const weekly = usage.windows?.find(w => w.kind === 'weekly' && w.scope === undefined);
+        if (!weekly || !Number.isFinite(weekly.usedPercent) || weekly.usedPercent < 80
+            || weekly.resetsAt === undefined || weekly.resetsAt <= Date.now()) {
+            throw new Error('Reset blocked: fresh weekly usage must be at least 80%.');
+        }
+        if (usage.resetCreditsError)
+            throw new Error('Reset credits could not be verified.');
+        return weekly.usedPercent;
+    }
+    async prepare(account, signal) {
+        const who = await this.canonical(account, signal);
+        if (this.busy.has(who) || this.uncertain.has(who))
+            throw new Error('Reset blocked: an operation is pending or its outcome is uncertain. Check Codex before retrying.');
+        const usage = await this.read(account, signal);
+        // Re-check after the read. A confirmation prepared while another client was
+        // redeeming would otherwise be minted against a park that has since been
+        // cleared, letting the next click spend a second credit.
+        if (this.busy.has(who) || this.uncertain.has(who))
+            throw new Error('Reset blocked: an operation is pending or its outcome is uncertain. Check Codex before retrying.');
+        const weeklyUsedPercent = this.eligible(usage);
+        const credit = usage.resetCredits?.filter(c => c.id && (c.expiresAt === undefined || c.expiresAt > Date.now()))
+            .sort((a, b) => (a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity))[0];
+        if (!credit?.id)
+            throw new Error('No available reset credit.');
+        for (const [key, value] of this.tickets)
+            if (value.account === who || value.expiresAt <= Date.now())
+                this.tickets.delete(key);
+        const ticket = randomUUID();
+        const expiresAt = Date.now() + 60_000;
+        this.tickets.set(ticket, { account: who, creditId: credit.id, expiresAt });
+        return { ticket, expiresAt, weeklyUsedPercent, ...(credit.expiresAt === undefined ? {} : { creditExpiresAt: credit.expiresAt }) };
+    }
+    async redeem(account, ticket, signal) {
+        const who = await this.canonical(account, signal);
+        const pending = this.tickets.get(ticket);
+        this.tickets.delete(ticket);
+        if (!pending || pending.account !== who || pending.expiresAt <= Date.now())
+            throw new Error('Confirmation expired. Start again.');
+        if (this.busy.has(who) || this.uncertain.has(who))
+            throw new Error('Reset blocked: operation pending or uncertain.');
+        this.busy.add(who);
+        try {
+            const usage = await this.read(account, signal);
+            // The ticket bounds how long the confirmation counts. A read that
+            // outlives it must not go on to submit, so this comes first.
+            if (pending.expiresAt <= Date.now())
+                throw new Error('Confirmation expired. Start again.');
+            this.eligible(usage);
+            if (!usage.resetCredits?.some(c => c.id === pending.creditId && (c.expiresAt === undefined || c.expiresAt > Date.now())))
+                throw new Error('The selected reset is no longer available.');
+            // Mark before submission: no blind retry after transport or response ambiguity.
+            this.uncertain.add(who);
+            try {
+                await this.consume(account, pending.creditId, randomUUID(), signal);
+            }
+            catch {
+                throw new Error('Reset outcome could not be confirmed. Do not retry or restart to bypass this block; verify credits and limits in Codex first.');
+            }
+            this.uncertain.delete(who);
+        }
+        finally {
+            this.invalidate(who);
+            this.busy.delete(who);
+        }
+    }
+}

package/lib/tools/image-generate.js

@@ -21,6 +21,7 @@ import { AccountTokenManager } from '../providers/accounts.js';
 import { ImageAccountPool } from '../providers/image-pool.js';
 import { codexRateLimitReset } from '../providers/codex.js';
 import { grokRateLimitReset } from '../providers/grok.js';
+import { parseProviderJson } from '../providers/common.js';
 import { hostFetch } from '../http.js';
 /** Endpoint the codex generation request is posted to. */
 export const IMAGE_GENERATE_URL = 'https://chatgpt.com/backend-api/codex/images/generations';
@@ -387,7 +388,7 @@ export function createImageGenerateTool(options) {
                 await manager.session(); // logged out: throws the provider's log-in hint
                 throw new Error('image_generate: no image provider is logged in');
             }
-            const images = parseImageGenerateResponse(await response.json());
+            const images = parseImageGenerateResponse(await parseProviderJson(response, 'image generate'));
             const directory = options.imagesDir ?? imagesDirectory();
             await mkdir(directory, { recursive: true });
             const paths = [];

package/lib/tools/video-generate.d.ts

@@ -57,10 +57,6 @@ export declare function buildVideoGenerateBody(args: {
     resolution?: '480p' | '720p' | '1080p';
     image_url?: string;
 }): VideoGenerateRequestBody;
-/**
- * Extract the request id from the submit response. Throws when the payload
- * carries none.
- */
 export declare function parseVideoStartResponse(payload: unknown): string;
 /** One decoded poll response. */
 export type VideoStatus = {
@@ -71,7 +67,6 @@ export type VideoStatus = {
     duration?: number;
 } | {
     status: 'failed' | 'expired';
-    detail?: string;
 };
 /**
  * Decode one poll response. A `done` payload without a video URL and an

package/lib/tools/video-generate.js

@@ -12,7 +12,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { httpLlmError } from '../providers/common.js';
+import { httpLlmError, parseProviderJson } from '../providers/common.js';
 import { AccountTokenManager } from '../providers/accounts.js';
 import { hostFetch } from '../http.js';
 /** Endpoint the generation request is posted to. */
@@ -60,10 +60,20 @@ function isRecord(value) {
  * Extract the request id from the submit response. Throws when the payload
  * carries none.
  */
+/**
+ * A provider-assigned request id, accepted only in a bounded identifier shape.
+ * The value reaches a user-visible failure message, so an unchecked one would
+ * let a provider put arbitrary text there. The shape rules out prose, spaces
+ * and message excerpts; it does NOT prove the value is harmless, because a
+ * credential-shaped string such as `SHORT_SECRET` matches it. Treat this as a
+ * bounded, format-constrained provider value that is displayed for support
+ * correlation — not as the absence of provider-supplied content.
+ */
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
 export function parseVideoStartResponse(payload) {
     const body = isRecord(payload) ? payload : {};
-    if (typeof body.request_id !== 'string' || body.request_id.length === 0) {
-        throw new Error('video_generate: the response carried no request_id');
+    if (typeof body.request_id !== 'string' || !REQUEST_ID_PATTERN.test(body.request_id)) {
+        throw new Error('video_generate: the response carried no usable request_id');
     }
     return body.request_id;
 }
@@ -89,15 +99,13 @@ export function parseVideoStatusResponse(payload) {
             };
         }
         case 'failed':
-        case 'expired': {
-            const error = isRecord(body.error) ? body.error : {};
-            const detail = typeof error.message === 'string' && error.message.length > 0
-                ? error.message
-                : typeof body.error === 'string' && body.error.length > 0 ? body.error : undefined;
-            return { status: body.status, ...detail === undefined ? {} : { detail } };
-        }
+        case 'expired':
+            // Safe means this failure path carries no provider-controlled free text,
+            // not that no secret can exist elsewhere in the system.
+            return { status: body.status };
         default:
-            throw new Error(`video_generate: unexpected status ${JSON.stringify(body.status)}`);
+            // Safe here also excludes provider-controlled free text, not all system secrets.
+            throw new Error('video_generate: unexpected status: [provider response body omitted]');
     }
 }
 /** Directory the downloaded MP4 files are written to. */
@@ -212,7 +220,7 @@ export function createVideoGenerateTool(options) {
             });
             if (!submit.ok)
                 throw await httpLlmError(submit, 'video_generate');
-            const requestId = parseVideoStartResponse(await submit.json());
+            const requestId = parseVideoStartResponse(await parseProviderJson(submit, 'video generate start'));
             const deadline = Date.now() + maxWaitMs;
             let done;
             for (;;) {
@@ -224,14 +232,17 @@ export function createVideoGenerateTool(options) {
                 });
                 if (!poll.ok)
                     throw await httpLlmError(poll, 'video_generate');
-                const status = parseVideoStatusResponse(await poll.json());
+                const status = parseVideoStatusResponse(await parseProviderJson(poll, 'video generate status poll'));
                 if (status.status === 'done') {
                     done = status;
                     break;
                 }
                 if (status.status === 'failed' || status.status === 'expired') {
+                    // No provider response text on this path. The request id is shaped like an
+                    // opaque id before it is stored (see REQUEST_ID_PATTERN), so it is an
+                    // identifier rather than provider prose; anything else was refused at parse.
                     throw new Error(`video_generate: generation ${status.status} (request ${requestId})`
-                        + (status.detail === undefined ? '' : `: ${status.detail}`));
+                        + ': [provider response body omitted]');
                 }
                 if (Date.now() >= deadline) {
                     throw new Error(`video_generate: timed out after ${String(maxWaitMs)}ms waiting for request ${requestId}`);

package/lib/tools/x-search.js

@@ -5,7 +5,7 @@
  * output is `{ answer, citations }`.
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { httpLlmError } from '../providers/common.js';
+import { httpLlmError, parseProviderJson } from '../providers/common.js';
 import { AccountTokenManager } from '../providers/accounts.js';
 import { hostFetch } from '../http.js';
 /** Endpoint the search request is posted to. */
@@ -191,7 +191,7 @@ export function createXSearchTool(options) {
             });
             if (!response.ok)
                 throw await httpLlmError(response, 'x_search');
-            return parseXSearchResponse(await response.json());
+            return parseXSearchResponse(await parseProviderJson(response, 'x search'));
         },
     });
 }

package/lib/translate/anthropic.d.ts

@@ -32,6 +32,23 @@ export declare const CACHE_BLOCK_STRIDE = 15;
  * blocks before a read is lost.
  */
 export declare const MESSAGE_CACHE_BREAKPOINTS = 3;
+/**
+ * How long Anthropic keeps a cache entry after its last use: five minutes
+ * (the API default) or one hour. A one-hour entry is written at twice the base
+ * input price instead of 1.25×, and reads cost the same either way.
+ */
+export type PromptCacheTtl = '5m' | '1h';
+/** The API default; a marker at this TTL carries no `ttl` field at all. */
+export declare const DEFAULT_PROMPT_CACHE_TTL: PromptCacheTtl;
+/**
+ * Build one `cache_control` marker.
+ *
+ * Five minutes is spelled by omitting `ttl`, so a request that does not opt in
+ * stays byte-identical to what earlier releases sent.
+ * @param ttl - cache lifetime; defaults to five minutes.
+ * @returns a fresh marker object (callers attach it to one block each).
+ */
+export declare function cacheControl(ttl?: PromptCacheTtl): Record<string, unknown>;
 /** One Anthropic request message. */
 export interface AnthropicMessage {
     role: 'user' | 'assistant';
@@ -62,17 +79,19 @@ export declare function toAnthropicMessages(messages: readonly TranslatableMessa
  * Marks are counted across the flattened block sequence, not per message,
  * because the lookback window Anthropic walks counts blocks the same way.
  * @param messages - assembled Anthropic messages, marked in place.
+ * @param ttl - cache lifetime for every mark; defaults to five minutes.
  */
-export declare function markMessageCache(messages: readonly AnthropicMessage[]): void;
+export declare function markMessageCache(messages: readonly AnthropicMessage[], ttl?: PromptCacheTtl): void;
 /**
  * Build the Anthropic `system` array: the mandatory Claude Code identity
  * block, then the explicit system prompt, then any system-role messages.
  * @param system - explicit system prompt, when set.
  * @param messages - conversation messages; the system-role text preceding the
  * conversation is appended, and a later one is left to {@link toAnthropicMessages}.
+ * @param ttl - cache lifetime for the tools+system mark; defaults to five minutes.
  * @returns the system content blocks.
  */
-export declare function toAnthropicSystem(system?: string, messages?: readonly TranslatableMessage[]): Record<string, unknown>[];
+export declare function toAnthropicSystem(system?: string, messages?: readonly TranslatableMessage[], ttl?: PromptCacheTtl): Record<string, unknown>[];
 /**
  * Map harness tool schemas to Anthropic tools, in name order.
  *