feat: implement bounded LLM request recovery

packages/llm/llm-deepseek/src/adapter.ts

@@ -5,8 +5,9 @@
  * @module dsh-llm-deepseek/adapter
  */
 
-import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
+import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { serializeRequest } from './serialize.ts'
 import type { RequestDefaults } from './serialize.ts'
 import { parseSse } from './sse.ts'
@@ -33,6 +34,31 @@ export interface DeepSeekAdapterOptions {
   defaults?: RequestDefaults
   /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
   models?: readonly DeepSeekCatalogModel[]
+  /** Maximum provider idle time while one stream read is outstanding. */
+  streamIdleTimeoutMs?: number
+}
+
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000
+const STREAM_IDLE_TIMEOUT_CODE = 'LLM_STREAM_IDLE_TIMEOUT'
+
+function retryAfterMs(value: string | null): number | undefined {
+  if (value === null) return undefined
+  if (/^\d+$/.test(value)) {
+    const delay = Number(value) * 1_000
+    return Number.isFinite(delay) && delay > 0 ? delay : undefined
+  }
+  const delay = Date.parse(value) - Date.now()
+  return Number.isFinite(delay) && delay > 0 ? delay : undefined
+}
+
+function requestId(headers: Headers): ReturnType<typeof ProviderRequestId> | undefined {
+  const value = headers.get('x-request-id') ?? headers.get('x-deepseek-request-id')
+  return value === null || value.length === 0 ? undefined : ProviderRequestId(value)
+}
+
+function errorMessage(value: unknown): string {
+  return value instanceof Error ? value.message : String(value)
 }
 
 /**
@@ -43,9 +69,10 @@ export interface DeepSeekAdapterOptions {
  */
 export function httpErrorCode(status: number, error?: WireError['error']): string {
   if (status === 401 || status === 403) return 'AUTH'
+  const detail = [error?.code, error?.type, error?.message].filter(Boolean).join(' ')
+  if (isQuotaExceededError(detail)) return QUOTA_EXCEEDED_CODE
   if (status === 429) return 'RATE_LIMIT'
   if (status === 400) {
-    const detail = [error?.code, error?.type, error?.message].filter(Boolean).join(' ')
     if (isContextWindowExceededError(detail)) return CONTEXT_WINDOW_EXCEEDED_CODE
     return 'INVALID_REQUEST'
   }
@@ -57,13 +84,22 @@ export function httpErrorCode(status: number, error?: WireError['error']): strin
  * The first real `LlmAdapter`. One instance serves every model name it was
  * registered under (the harness model name IS the wire model name).
  *
- * Abort: `options.signal` is handed to fetch — both the initial request and
- * the body stream reject on abort, which surfaces to the loop as a rejected
- * step (the loop already contains step errors).
+ * One stable signal reaches both initial fetch and body reads. Caller aborts
+ * map to `ABORTED`; the configured per-read idle watchdog maps to `TIMEOUT`.
  */
 export class DeepSeekAdapter extends LlmAdapter {
+  private readonly streamIdleTimeoutMs: number
+
   constructor(private readonly options: DeepSeekAdapterOptions) {
     super()
+    this.streamIdleTimeoutMs = options.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
+    if (!Number.isFinite(this.streamIdleTimeoutMs)
+      || this.streamIdleTimeoutMs <= 0
+      || this.streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
+      throw new Error(
+        `llm-deepseek: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`,
+      )
+    }
   }
 
   override providerInfo(provider: string): LlmProviderInfo {
@@ -80,6 +116,48 @@ export class DeepSeekAdapter extends LlmAdapter {
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const consumer = new AbortController()
+    const upstream = options.signal === undefined
+      ? consumer.signal
+      : AbortSignal.any([options.signal, consumer.signal])
+    using watchdog = idleWatchdog(upstream, this.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
+    const iterator = this.request(options, watchdog.signal)[Symbol.asyncIterator]()
+    let exhausted = false
+    try {
+      while (true) {
+        const result = await watchdog.next(iterator)
+        if (result.done) {
+          exhausted = true
+          return
+        }
+        yield result.value
+      }
+    } catch (error: unknown) {
+      if (timeoutOf(watchdog.signal, STREAM_IDLE_TIMEOUT_CODE) !== undefined) {
+        throw new LlmError(
+          `DeepSeek stream idle timeout after ${this.streamIdleTimeoutMs}ms`,
+          'TIMEOUT',
+          { cause: error },
+        )
+      }
+      if (options.signal?.aborted) {
+        throw new LlmError('DeepSeek request aborted by caller', 'ABORTED', { cause: error })
+      }
+      if (error instanceof LlmError) throw error
+      throw new LlmError(`DeepSeek transport failed: ${errorMessage(error)}`, 'TRANSPORT', { cause: error })
+    } finally {
+      consumer.abort('DeepSeek stream consumer stopped')
+      if (!exhausted && iterator.return !== undefined) {
+        try {
+          await iterator.return()
+        } catch (_abortedTransportTeardown) {
+          // The consumer controller already owns termination; a return-time abort cannot add a second outcome.
+        }
+      }
+    }
+  }
+
+  private async * request(options: GenerateOptions, signal: AbortSignal): AsyncIterable<StreamChunk> {
     const body = serializeRequest(options, this.options.defaults ?? {})
 
     // TODO(http): adopt the Cordis HTTP service when shared transport configuration
@@ -96,7 +174,7 @@ export class DeepSeekAdapter extends LlmAdapter {
           : {},
       },
       body: JSON.stringify(body),
-      ...options.signal ? { signal: options.signal } : {},
+      signal,
     })
 
     if (!response.ok) {
@@ -110,7 +188,13 @@ export class DeepSeekAdapter extends LlmAdapter {
         // Only swallow error-body parsing: the HTTP status still identifies the
         // failure, so malformed gateway JSON must not mask it.
       }
-      throw new LlmError(message, httpErrorCode(response.status, providerError))
+      const delay = retryAfterMs(response.headers.get('retry-after'))
+      const id = requestId(response.headers)
+      throw new LlmError(message, httpErrorCode(response.status, providerError), {
+        status: response.status,
+        ...delay === undefined ? {} : { retryAfterMs: delay },
+        ...id === undefined ? {} : { requestId: id },
+      })
     }
     if (!response.body) {
       throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')

packages/llm/llm-deepseek/src/index.ts

@@ -8,7 +8,8 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-llm'
-import { DeepSeekAdapter } from './adapter.ts'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter } from './adapter.ts'
 import type { DeepSeekCatalogModel } from './adapter.ts'
 
 export { DeepSeekAdapter } from './adapter.ts'
@@ -41,6 +42,8 @@ export interface Config {
   reasoningEffort?: 'high' | 'max'
   /** Advisory models shown by discovery consumers; defaults to V4 Flash and V4 Pro. */
   models?: DeepSeekCatalogModel[]
+  /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
+  streamIdleTimeoutMs?: number
 }
 
 const catalogModel: z<DeepSeekCatalogModel> = z.object({
@@ -55,6 +58,7 @@ export const Config: z<Config> = z.object({
   thinking: z.union(['enabled', 'disabled']),
   reasoningEffort: z.union(['high', 'max']),
   models: z.array(catalogModel).default(DEFAULT_MODELS),
+  streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
 })
 
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
@@ -92,5 +96,6 @@ export function apply(ctx: Context, config: Config): void {
       reasoningEffort: config.reasoningEffort,
     },
     models: resolveModels(config.models),
+    streamIdleTimeoutMs: config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   }))
 }

packages/llm/llm-deepseek/src/translate.ts

@@ -35,7 +35,10 @@ export function mapFinishReason(reason: string): FinishReason {
     case 'length': return { kind: 'max-tokens' }
     default:
       // content_filter, insufficient_system_resource, future additions.
-      return { kind: 'error', message: `model stopped: ${reason}`, code: reason.toUpperCase() }
+      return {
+        kind: 'error',
+        failure: { message: `model stopped: ${reason}`, code: reason.toUpperCase() },
+      }
   }
 }