dsh-subscriptions 0.1.3 → 0.1.5

package/lib/providers/codex-search.js

@@ -86,8 +86,11 @@ export class CodexWebSearchProvider {
             try {
                 return JSON.parse(text);
             }
-            catch (cause) {
-                throw new WebError('Codex Web Search returned invalid JSON', 'CODEX_SEARCH_RESPONSE', { cause });
+            catch {
+                // No cause: the host expands causes recursively, and Node's parse error
+                // quotes a bounded excerpt of the body, so attaching it would relocate
+                // the leak rather than remove it.
+                throw new WebError('Codex Web Search returned invalid JSON', 'CODEX_SEARCH_RESPONSE');
             }
         }
         throw new WebError('Codex Web Search exhausted its retry policy', 'CODEX_SEARCH_UPSTREAM');

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

@@ -8,7 +8,7 @@ import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmErr
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { deterministicSessionId, effortDisplayName, httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isDiscoveryAuthFailure, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
+import { deterministicSessionId, effortDisplayName, httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isDiscoveryAuthFailure, isMissingOrInvalidCredential, parseProviderJson, oauthEndpointError, OAuthEndpointError, } from './common.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
 import { hostFetch } from '../http.js';
 import { DEFAULT_RATE_LIMIT_WAIT, DEFAULT_RETRY, jsonBody, resetFromFields, subscriptionRetryPolicy, } from './rate-limit.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. */
@@ -185,7 +185,7 @@ export async function exchangeCodexCode(code, verifier, redirectUri) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'codex');
-    return codexSession(await response.json());
+    return codexSession(await parseProviderJson(response, 'codex token exchange'));
 }
 /**
  * Refresh a codex session (JSON grant — unlike the code exchange).
@@ -204,7 +204,7 @@ export async function refreshCodex(session) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'codex');
-    return codexSession(await response.json(), session);
+    return codexSession(await parseProviderJson(response, 'codex token refresh'), session);
 }
 /**
  * Whether a codex refresh failure means the login is permanently gone.
@@ -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 parseProviderJson(response, 'codex reset credits');
+    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 parseProviderJson(response, 'codex consume reset');
+    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;
@@ -291,7 +347,7 @@ export async function fetchCodexUsage(session, fetchFn = hostFetch, signal) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'codex usage');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'codex usage');
     const windows = [];
     const primary = codexUsageWindow(payload.rate_limit?.primary_window, 'session');
     const secondary = codexUsageWindow(payload.rate_limit?.secondary_window, 'weekly');
@@ -354,7 +410,7 @@ export async function fetchCodexModels(session, fetchFn = hostFetch, signal, cli
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'codex models');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'codex models');
     if (!Array.isArray(payload.models))
         throw new Error('codex models endpoint returned no models array');
     const discovered = [];
@@ -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

@@ -33,6 +33,19 @@ export interface ModelEntry {
  * @returns the validated entries.
  */
 export declare function validateModels(models: readonly ModelEntry[], label: string): ModelEntry[];
+/**
+ * Parse a provider response or stored JSON string without exposing input excerpts.
+ * Success returns the same JSON value; only SyntaxError is replaced, preserving
+ * parse-failure type checks and leaving body-read/abort failures unchanged.
+ * Node's Unexpected token errors include a bounded input excerpt. Do not retain
+ * the original error as cause: the host displays causes recursively.
+ * @param input - response to consume once, or JSON text to parse.
+ * @param origin - local endpoint/operation label; never response.url, a discovered
+ *   URL, a credential, or any other provider-controlled text.
+ * @returns the parsed value, without validation or credential filtering.
+ * @throws SyntaxError with the local origin and a fixed omission marker.
+ */
+export declare function parseProviderJson<T = unknown>(input: Response | string, origin: string): Promise<T>;
 /** Optional per-call hooks {@link httpLlmError} uses to read a rate-limit window. */
 export interface HttpLlmErrorOptions {
     /**
@@ -200,6 +213,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 +246,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 {

package/lib/providers/common.js

@@ -7,7 +7,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
-import { durationMs, rateLimitDiagnostics, retryAfterInstant, waitFromReset } from './rate-limit.js';
+import { durationMs, retryAfterInstant, waitFromReset } from './rate-limit.js';
 /**
  * Validate a configured model catalog (mirrors llm-deepseek's resolveModels).
  * @param models - raw configured entries.
@@ -50,6 +50,39 @@ export function validateModels(models, label) {
         };
     });
 }
+/**
+ * Provider failures can echo credentials or customer input in any format.
+ * Shape-based filtering cannot make arbitrary response text safe to display.
+ * Here, safe means this diagnostic carries no provider-controlled free text,
+ * not that secrets cannot exist elsewhere in the system. Keep raw responses
+ * internal for classification and reset parsing; display only local summaries.
+ * This deliberately loses model, parameter and plan details useful to support.
+ */
+function providerDiagnostic(summary, hasBody) {
+    return hasBody ? `${summary}: [provider response body omitted]` : summary;
+}
+/**
+ * Parse a provider response or stored JSON string without exposing input excerpts.
+ * Success returns the same JSON value; only SyntaxError is replaced, preserving
+ * parse-failure type checks and leaving body-read/abort failures unchanged.
+ * Node's Unexpected token errors include a bounded input excerpt. Do not retain
+ * the original error as cause: the host displays causes recursively.
+ * @param input - response to consume once, or JSON text to parse.
+ * @param origin - local endpoint/operation label; never response.url, a discovered
+ *   URL, a credential, or any other provider-controlled text.
+ * @returns the parsed value, without validation or credential filtering.
+ * @throws SyntaxError with the local origin and a fixed omission marker.
+ */
+export async function parseProviderJson(input, origin) {
+    try {
+        return (typeof input === 'string' ? JSON.parse(input) : await input.json());
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        throw new SyntaxError(providerDiagnostic(`${origin}: invalid JSON`, true));
+    }
+}
 /**
  * Build an LlmError from a non-2xx provider response, mapping the status to a
  * stable code and, for a rate-limited request, the disclosed reset instant to
@@ -73,11 +106,8 @@ export async function httpLlmError(response, label, options = {}) {
     catch {
         // Only swallow error-body reading: the HTTP status still identifies the failure.
     }
-    // Truncated for display only; the readers below need the whole body to parse it.
+    // Preserve the existing classification window; reset readers need the full body.
     const shown = body.slice(0, 500);
-    const message = shown.length > 0
-        ? `${label} error (HTTP ${String(response.status)}): ${shown}`
-        : `${label} error (HTTP ${String(response.status)})`;
     let code;
     if (response.status === 401 || response.status === 403)
         code = 'AUTH';
@@ -93,6 +123,7 @@ export async function httpLlmError(response, label, options = {}) {
         code = 'SERVER';
     else
         code = `HTTP_${String(response.status)}`;
+    const message = providerDiagnostic(`${label} error (HTTP ${String(response.status)}, ${code})`, body.length > 0);
     const now = Date.now();
     // The provider's reader runs on a 429 and nowhere else. Providers attach
     // their rate-limit headers to every response, so reading them on a transient
@@ -111,7 +142,8 @@ export async function httpLlmError(response, label, options = {}) {
         ? options.rateLimitReset?.(response, body, now) ?? googleQuotaReset(body, now) ?? retryAfterInstant(response, now)
         : retryAfterInstant(response, now);
     if (reset === undefined && rateLimited) {
-        options.onWarn?.(`${label}: ${rateLimitDiagnostics(response, body)}`);
+        // Header names and values are provider-controlled too; none are displayed.
+        options.onWarn?.(providerDiagnostic(`${label}: 429 disclosed no reset time; [provider response headers omitted]`, body.length > 0));
     }
     return new LlmError(message, code, {
         status: response.status,
@@ -246,9 +278,10 @@ export class OAuthEndpointError extends Error {
  */
 export async function oauthEndpointError(response, label) {
     let oauthCode;
-    let detail = '';
+    let body = '';
     try {
-        const parsed = await response.json();
+        body = await response.text();
+        const parsed = JSON.parse(body);
         if (typeof parsed.error === 'string') {
             oauthCode = parsed.error;
         }
@@ -256,20 +289,13 @@ export async function oauthEndpointError(response, label) {
             const nested = parsed.error;
             if (typeof nested.code === 'string' && nested.code.length > 0)
                 oauthCode = nested.code;
-            if (typeof nested.message === 'string')
-                detail = nested.message;
         }
-        if (typeof parsed.error_description === 'string')
-            detail = parsed.error_description;
-        if (detail.length === 0)
-            detail = oauthCode ?? '';
     }
     catch {
-        // Only swallow error-body parsing: the HTTP status still identifies the failure.
+        // Only swallow error-body reading/parsing: HTTP status still identifies the failure.
     }
-    const message = detail.length > 0
-        ? `${label} token endpoint error (HTTP ${String(response.status)}): ${detail}`
-        : `${label} token endpoint error (HTTP ${String(response.status)})`;
+    // oauthCode remains structural for auth classification, never display text.
+    const message = providerDiagnostic(`${label} token endpoint error (HTTP ${String(response.status)})`, body.length > 0);
     return new OAuthEndpointError(message, response.status, oauthCode, parseRetryAfterMs(response));
 }
 /**

package/lib/providers/copilot.d.ts

@@ -297,7 +297,8 @@ export declare class CopilotAdapter extends LlmAdapter {
      * account identity is the session's long-lived GitHub token (stable across
      * Copilot-token refreshes, different per GitHub login); the conversation is
      * the loop-stamped `sessionId`, falling back to the first message's id
-     * when a hand-built request carries no session stamp; the model separates
+     * when a hand-built request carries no session stamp. Identity-free
+     * requests have no replay scope; the model separates
      * wire families. A call id captured in one scope is invisible to every
      * other scope, so reused ids cannot leak reasoning across accounts,
      * conversations, or models.

package/lib/providers/copilot.js

@@ -17,7 +17,7 @@ import { EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortI
 import { resolveImages } from '../translate/resolved.js';
 import { streamChatCompletions, toChatMessages, toChatTools, } from '../translate/chat-completions.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.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 { DEFAULT_RATE_LIMIT_WAIT, DEFAULT_RETRY, subscriptionRetryPolicy, } from './rate-limit.js';
@@ -144,7 +144,7 @@ export async function exchangeCopilotToken(githubToken, fetchFn = hostFetch) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'copilot');
-    const wire = await response.json();
+    const wire = await parseProviderJson(response, 'copilot token exchange');
     if (typeof wire.token !== 'string' || wire.token.length === 0) {
         throw new Error('copilot token endpoint returned no token');
     }
@@ -268,7 +268,7 @@ export async function fetchCopilotModels(session, fetchFn = hostFetch, signal) {
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'copilot models');
-    const payload = await response.json();
+    const payload = await parseProviderJson(response, 'copilot models');
     if (!Array.isArray(payload.data))
         throw new Error('copilot models endpoint returned no data array');
     const seen = new Set();
@@ -677,7 +677,8 @@ export class CopilotAdapter extends LlmAdapter {
      * account identity is the session's long-lived GitHub token (stable across
      * Copilot-token refreshes, different per GitHub login); the conversation is
      * the loop-stamped `sessionId`, falling back to the first message's id
-     * when a hand-built request carries no session stamp; the model separates
+     * when a hand-built request carries no session stamp. Identity-free
+     * requests have no replay scope; the model separates
      * wire families. A call id captured in one scope is invisible to every
      * other scope, so reused ids cannot leak reasoning across accounts,
      * conversations, or models.
@@ -685,9 +686,11 @@ export class CopilotAdapter extends LlmAdapter {
     replayScope(tokenKey, options) {
         const conversation = options.sessionId !== undefined
             ? `session:${String(options.sessionId)}`
-            : options.messages[0] !== undefined
+            : options.messages[0]?.id !== undefined
                 ? `anchor:${String(options.messages[0].id)}`
-                : 'conversation:none';
+                : undefined;
+        if (conversation === undefined)
+            return undefined;
         return `${tokenKey}\u0000${conversation}\u0000${options.model}`;
     }
     /**
@@ -701,6 +704,8 @@ export class CopilotAdapter extends LlmAdapter {
      * per call.
      */
     captureReasoning(scope, callIds, items) {
+        if (scope === undefined)
+            return;
         let entries = this.replayByScope.get(scope);
         if (entries === undefined) {
             entries = new Map();
@@ -745,6 +750,8 @@ export class CopilotAdapter extends LlmAdapter {
      * degradation, never an error.
      */
     replayFor(scope, callId) {
+        if (scope === undefined)
+            return undefined;
         const entries = this.replayByScope.get(scope);
         const entry = entries?.get(callId);
         if (entries === undefined || entry === undefined)

package/lib/providers/cursor-adapter.d.ts

@@ -5,8 +5,43 @@ import { CursorAdapter } from 'dsh-subscriptions/cursor-transport';
  * blocks. DSH 0.1.7 carries them as first-class role=tool messages instead.
  */
 export declare function projectCursorMessages(messages: GenerateOptions['messages']): unknown[];
+/**
+ * Cursor adapter for the DSH host.
+ *
+ * Failure text contract: `finish/error` messages that originate from the
+ * vendor stream and can quote provider-controlled text (the response content
+ * type, trailers, end-stream errors, a frame-reader or other error whose message
+ * is not one of the literals below, and a transport-coded failure that is not a
+ * socket-layer error) are replaced by `<code> [provider response text omitted]`. Failures that are
+ * wholly local keep their own message and code:
+ *
+ * - anything the auth service threw (not signed in, sign-in expired, token
+ *   refresh status), and a host attachment read failure;
+ * - the vendor's own request validation, by code (`UNSUPPORTED_OPTION`,
+ *   `UNSUPPORTED_CONTENT`, `TOOL_LIMIT`);
+ * - the vendor's fixed-literal plain errors, by exact message: the HTTP status
+ *   (`Cursor agent returned HTTP 429`), the response, idle and progress
+ *   timeouts, a closed bridge or stream, an unreadable compressed frame, and
+ *   an invalid Cursor setting;
+ * - a network error raised by the operating system (`ECONNREFUSED`,
+ *   `ENOTFOUND`, ...), recognised from the thrown error's own code, not from
+ *   the vendor's classification.
+ *
+ * Not a provider-origin class: a network error such as `ECONNREFUSED` is a
+ * local failure (no network, daemon down, DNS), and is kept. What is still
+ * replaced although it is probably local is a transport failure with no
+ * socket-layer errno: a TLS or certificate failure and an HTTP/2 protocol
+ * error. The vendor's `TRANSPORT` code cannot decide those, because
+ * `classifyCursorError` derives it from message text (`network`, `connection`,
+ * `socket`, `fetch`, `ECONN`, `http2`) and a provider's end-stream message or
+ * `grpc-message` can contain any of them; so the code is never trusted alone.
+ * Telling these apart would need a check on the thrown error object, as the
+ * errno check above does, extended to the TLS and HTTP/2 error codes. That is
+ * not done here and is not verified.
+ */
 export declare class CursorCompatAdapter extends CursorAdapter {
     private readonly visibleModels;
+    private readonly localFailures;
     constructor(options: ConstructorParameters<typeof CursorAdapter>[0] & {
         visibleModels?: () => readonly string[] | undefined;
     });