@ixo/oracle-runtime-workers 0.16.0 → 0.17.1

package/src/do/user-oracle-do.ts

@@ -69,10 +69,10 @@ import {
   langsmithEnvFromWorkerEnv,
   llmEnvFromWorkerEnv,
   resolveLangsmithTracing,
+  streamLivenessFromEnv,
   type LangsmithTracingDecision,
   type OpenRouterLlmAdapter,
   DEFAULT_MODEL_ID,
-  OPENROUTER_MODEL_MAP,
 } from '../core/llm';
 import { renderTurnTimeNote } from '../core/prompt-composer';
 import { TURN_TIME_NOTE_KWARG, withTurnTimeNote } from '../core/turn-time-note';
@@ -97,7 +97,7 @@ import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import type { AmbientServices, LlmAdapter } from '../core/runtime-context';
 import { chatGptBackendFromEnv } from '../llm/byo-client';
 import { createByoLlmAdapter } from '../llm/byo-adapter';
-import { byoModelForRole, isByoModelId } from '../llm/byo-catalog';
+import { isByoModelId } from '../llm/byo-catalog';
 import { handleByoRequest } from '../llm/byo-routes';
 import {
   WorkersByoService,
@@ -192,6 +192,7 @@ import {
   type TurnIdentity,
   type TurnRequest,
   type TurnResult,
+  type DomainContextRouterUpdate,
   type MemorySchemaDebug,
   TURN_INTERRUPTED_MARKER,
   type JsonString,
@@ -275,6 +276,14 @@ import {
 } from '../core/middlewares/context-guard';
 import { fetchOpenRouterContextLengths } from '../core/openrouter-pricing';
 import { ResultStore, resultStoreKnobs } from './result-store';
+import {
+  DomainContextResolver,
+  type DomainContextOptions,
+  type DomainContextPins,
+  type DomainContextProvenance,
+} from '../core/domain-context';
+import { DomainContextStore } from './domain-context-store';
+import { EVENT_NAMES } from '../core/runtime-context';
 import { artifactStorageConfig } from '../artifacts/config';
 import {
   ArtifactStore,
@@ -333,6 +342,8 @@ interface TurnBuildRun {
   resumed: boolean;
   /** The reply text the user already received (resumed attempts). */
   continuation: string | null;
+  /** Domain anchors the run started with (resumed attempts keep them). */
+  domainPins?: DomainContextPins;
 }
 
 /**
@@ -536,6 +547,11 @@ export interface OracleWorkerHooks {
 export interface UserOracleDOOptions {
   core: (env: OracleWorkerEnv) => RuntimeCore;
   hooks?: OracleWorkerHooks;
+  /**
+   * Observe-only domain context (docs/configuration.md). Absent or `off`:
+   * no lookups, no prompt block, no tools.
+   */
+  domainContext?: DomainContextOptions;
 }
 
 interface StoredDelegation {
@@ -619,7 +635,11 @@ function lastAiText(messages: BaseMessage[]): string {
 }
 
 /** Id of the final assistant message (what `POST /messages` reports as `message.id`). */
-/** `turn_runs.usage` for `/debug/runs`; a row written before the column existed, or an unreadable one, is null. */
+/**
+ * `turn_runs.usage` for `/debug/runs`; a row written before the column
+ * existed, or an unreadable one, is null. A `limits.tokens` a row from an
+ * older runtime still carries is ignored: tokens are no longer limited.
+ */
 function parseUsage(raw: string | null): TurnUsage | null {
   if (!raw) return null;
   try {
@@ -642,7 +662,6 @@ function parseUsage(raw: string | null): TurnUsage | null {
       toolAttempts: num('toolAttempts'),
       elapsedMs: num('elapsedMs'),
       limits: {
-        tokens: limit('tokens'),
         tools: limit('tools'),
         durationMs: limit('durationMs'),
       },
@@ -653,7 +672,6 @@ function parseUsage(raw: string | null): TurnUsage | null {
       usage.modelCalls === undefined ||
       usage.toolAttempts === undefined ||
       usage.elapsedMs === undefined ||
-      usage.limits.tokens === undefined ||
       usage.limits.tools === undefined ||
       usage.limits.durationMs === undefined
     )
@@ -665,7 +683,6 @@ function parseUsage(raw: string | null): TurnUsage | null {
       toolAttempts: usage.toolAttempts,
       elapsedMs: usage.elapsedMs,
       limits: {
-        tokens: usage.limits.tokens,
         tools: usage.limits.tools,
         durationMs: usage.limits.durationMs,
       },
@@ -741,6 +758,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
      * bounded lanes. Lives as long as the object.
      */
     private readonly toolScheduler = new ToolScheduler();
+    /**
+     * Domain-context anchors and documents, cached for every session of this
+     * object; `refresh_domain_context` invalidates entries here.
+     */
+    private readonly domainResolver = new DomainContextResolver({
+      logger: console,
+    });
+    /** Per-turn domain-context provenance (`domain_context_runs`). */
+    private domainContextStore: DomainContextStore | null = null;
     private runs: RunCoordinator | null = null;
     private readonly runConfig: RunDurabilityConfig = runDurabilityConfig(
       this.env,
@@ -1641,6 +1667,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       });
       await this.resultStore.setup();
       this.attachmentTextCache = new AttachmentTextCacheStore(liveDb, console);
+      // Constructing it touches no SQL. Only an observe turn records (and so
+      // creates `domain_context_runs`); a session delete never creates it but
+      // still removes rows an earlier observe deployment left behind.
+      this.domainContextStore = new DomainContextStore(liveDb, console);
       // The store exists whenever the bucket is bound, so artefacts made
       // earlier stay readable, revocable and deleted with their session after
       // the public origin is removed; only new ones need it.
@@ -1894,6 +1924,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.resultStore = null;
       this.artifacts = null;
       this.attachmentTextCache = null;
+      this.domainContextStore = null;
       // Its store is bound to the database just dropped: a caller that sees
       // no scheduler boots again instead of reading a closed connection.
       this.taskScheduler = null;
@@ -2760,6 +2791,13 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
               `[user-do] could not delete the artefacts of ${sessionId}; their links expire on schedule: ${err instanceof Error ? err.message : String(err)}`,
             );
           });
+        await this.domainContextStore
+          ?.deleteForSession(sessionId)
+          .catch((err: unknown) => {
+            console.warn(
+              `[domain-context] could not delete the provenance of ${sessionId}: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          });
         await this.ctx.storage.delete(contextStatsKey(sessionId));
         await this.feedbackMarkers!.forgetSession(sessionId);
         this.markDirty();
@@ -4283,6 +4321,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         toolOutputCapChars,
         delivery,
         usage,
+        domainContext,
       } = await this.prepareTurn(
         req,
         {
@@ -4298,9 +4337,28 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           abortController: live.abort,
           resumed: !freshInput,
           continuation: freshInput ? null : live.continuation,
+          ...(stored.domainPins ? { domainPins: stored.domainPins } : {}),
         },
       );
       const sessionId = req.sessionId;
+      // The anchors this run read are pinned on its row, so a resumed
+      // attempt reads the same document revisions.
+      if (
+        domainContext &&
+        JSON.stringify(domainContext.pins) !==
+          JSON.stringify(stored.domainPins ?? {})
+      ) {
+        stored.domainPins = domainContext.pins;
+        const request = JSON.stringify(stored);
+        try {
+          await this.runStore!.update(live.runId, { request });
+          live.record.request = request;
+        } catch (error) {
+          console.warn(
+            `[domain-context] could not pin the anchors of run ${live.runId}: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
       const sink = {
         emit: (eventName: string, payload: Record<string, unknown>) => {
           if (live.buffer.isClosed) return;
@@ -4313,6 +4371,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // (the turn's deadline timer among them) run however the attempt ends.
       try {
         this.events.register(sessionId, sink);
+        if (domainContext)
+          await this.reportDomainContext(req, domainContext.provenance);
         if (byoNotice)
           sink.emit('error', {
             ...byoNotice,
@@ -4641,15 +4701,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const window = await this.contextWindows.resolve(modelId, {
         ...(byoProvider ? { byoProvider } : {}),
       });
-      const budget = contextBudgetFor(
-        window,
-        contextKnobs(this.env, console),
-        await this.contextWindows.resolve(
-          llm && isProviderAdapter(llm)
-            ? llm.modelForRole('routing')
-            : OPENROUTER_MODEL_MAP.routing,
-        ),
-      );
+      const budget = contextBudgetFor(window, contextKnobs(this.env, console));
       const stats = (await this.resultStore?.stats()) ?? {
         rows: 0,
         sqliteBytes: 0,
@@ -5007,27 +5059,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       };
     }
 
-    /**
-     * The model that summarises the turn's history (the `routing` role): its
-     * window bounds what the summariser is handed.
-     */
-    private summaryModelId(
-      platform: LlmAdapter,
-      byoTurn: ByoTurnState | null,
-    ): string {
-      if (byoTurn)
-        return (
-          byoModelForRole(
-            byoTurn.credential.provider,
-            'routing',
-            byoTurn.mainModelId,
-          ) ?? OPENROUTER_MODEL_MAP.routing
-        );
-      return isProviderAdapter(platform)
-        ? platform.modelForRole('routing')
-        : OPENROUTER_MODEL_MAP.routing;
-    }
-
     /**
      * Build one attempt's agent and input (`buildTurn`). A build that fails
      * part-way leaves nothing behind: the cleanups it registered run (the
@@ -5139,6 +5170,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
                 credential: byoTurn.credential,
                 mainModelId: byoTurn.mainModelId,
                 chatGptBackend: byoTurn.chatGptBackend,
+                streamLiveness: streamLivenessFromEnv(core.validatedEnv, 'byo'),
               },
               console,
             ),
@@ -5157,13 +5189,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const windowResolution = await this.contextWindows.resolve(mainModelId, {
         ...(byoTurn ? { byoProvider: byoTurn.provider } : {}),
       });
+      // The summary is written by the main model too (the `summarizer`
+      // role), so the main model's window is the only one that counts.
       const contextBudget = contextBudgetFor(
         windowResolution,
         contextKnobs(this.env, console),
-        await this.contextWindows.resolve(
-          this.summaryModelId(baseAmbient.llm, byoTurn),
-          byoTurn ? { byoProvider: byoTurn.provider } : {},
-        ),
       );
       if (
         req.client === 'matrix' &&
@@ -5393,8 +5423,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         continuation: run.continuation,
         logger: console,
       });
-      // The turn's budget (turn-budget.ts): model calls are charged by the
-      // metered adapter every model of this turn comes from, tool calls by
+      // The turn's budget (turn-budget.ts): model tokens are accounted (for
+      // the usage line below, never limited) by the metered adapter every
+      // model of this turn comes from, tool calls are charged by
       // the execution middleware below, and the deadline aborts the run
       // with the limit as the reason (the stream reports it as a terminal
       // error, not as a user abort).
@@ -5404,6 +5435,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         budget,
         outputReserveTokens: contextBudget.outputReserveTokens,
         signal: abortController.signal,
+        logger: console,
       });
       const deadline = setTimeout(() => {
         if (abortController.signal.aborted) return;
@@ -5420,6 +5452,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       }, turnLimits.durationMs);
       turnDisposables.add(async () => {
         clearTimeout(deadline);
+        // Heartbeats of model calls that never reported an end.
+        meteredLlm.dispose();
         const usage = budget.snapshot();
         console.log(
           `[harness] turn ${req.requestId} usage: ~${usage.tokens} tokens (${usage.reportedTokens} reported over ${usage.modelCalls} model calls), ${usage.toolAttempts} tool attempts, ${usage.elapsedMs} ms`,
@@ -5489,6 +5523,18 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         contextBudget,
         turnBudget: budget,
         delivery,
+        // Observe-only domain context, on the object's shared resolver (the
+        // one `refresh_domain_context` invalidates); a resumed run reads the
+        // anchors it pinned.
+        ...(opts.domainContext
+          ? {
+              domainContext: opts.domainContext,
+              domainResolver: this.domainResolver,
+              onDomainProvenance: (provenance: DomainContextProvenance[]) =>
+                void this.reportDomainContext(req, provenance),
+              ...(run.domainPins ? { domainPins: run.domainPins } : {}),
+            }
+          : {}),
         ambient: {
           ...ambient,
           llm: meteredLlm,
@@ -5657,7 +5703,30 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         /** The budget's usage so far (JSON), stored with the run's end. */
         usage: (): string => JSON.stringify(budget.snapshot()),
         delivery,
+        domainContext: built.domainContext,
+      };
+    }
+
+    /**
+     * A turn's domain-context provenance: a `router_update` frame for the
+     * client and the session's sockets, and a `domain_context_runs` row.
+     * Diagnostics only — nothing here can fail the turn.
+     */
+    private async reportDomainContext(
+      req: TurnRequest,
+      provenance: DomainContextProvenance[],
+    ): Promise<void> {
+      const update: DomainContextRouterUpdate = {
+        sessionId: req.sessionId,
+        requestId: req.requestId,
+        domainContext: provenance,
       };
+      this.events.emit(EVENT_NAMES.router, { ...update });
+      await this.domainContextStore?.record(
+        req.sessionId,
+        req.requestId,
+        provenance,
+      );
     }
 
     /**

package/src/index.ts

@@ -39,6 +39,7 @@ import { artifactSweepIntervalMs } from './artifacts/config';
 import { sweepExpiredArtifacts } from './artifacts/sweep';
 import { feedbackConfigFromEnv } from './feedback/config';
 import { LinearFeedbackSink } from './feedback/linear-sink';
+import type { DomainContextOptions } from './core/domain-context';
 
 export * from './plugin-api';
 export * from './plugins';
@@ -56,6 +57,14 @@ export {
   createUserOracleDO,
   type OracleWorkerHooks,
 } from './do/user-oracle-do';
+export type {
+  DocumentRequest,
+  DomainCapsuleInspection,
+  DomainContextOptions,
+  DomainContextPins,
+  DomainContextProvenance,
+  DomainDocumentRead,
+} from './core/domain-context';
 export { createShell, type ListModelsOptions } from './shell/app';
 export { authenticate } from './shell/auth';
 export {
@@ -265,6 +274,12 @@ export interface CreateOracleWorkerOptions {
    * user object's ambient services.
    */
   hooks?: OracleWorkerHooks;
+  /**
+   * Observe-only domain context: the oracle's and the selected subject's
+   * anchored domain documents, verified by CID and handed to the model as
+   * retrieved data. Default off. See docs/configuration.md.
+   */
+  domainContext?: DomainContextOptions;
 }
 
 export interface OracleWorker {
@@ -341,6 +356,7 @@ export function createOracleWorker(
   const UserOracleDO = createUserOracleDO({
     core: coreFor,
     ...(opts.hooks ? { hooks: opts.hooks } : {}),
+    ...(opts.domainContext ? { domainContext: opts.domainContext } : {}),
   });
 
   return {

package/src/llm/byo-adapter.ts

@@ -28,6 +28,7 @@ import {
   ByoModelFallbackChatModel,
   ByoModelFallbackState,
 } from './byo-model-fallback';
+import type { StreamLivenessSettings } from './stream-liveness';
 
 export interface ByoTurnResolution {
   credential: ByoCredential;
@@ -35,6 +36,8 @@ export interface ByoTurnResolution {
   mainModelId: string;
   /** ChatGPT lane only: backend/proxy the requests go to. */
   chatGptBackend?: ChatGptBackendConfig;
+  /** The BYO lane's liveness budgets (`streamLivenessFromEnv(env, 'byo')`). */
+  streamLiveness?: StreamLivenessSettings;
 }
 
 export function createByoLlmAdapter(
@@ -68,6 +71,9 @@ export function createByoLlmAdapter(
           modelId,
           role,
           chatGptBackend: turn.chatGptBackend,
+          ...(turn.streamLiveness
+            ? { streamLiveness: turn.streamLiveness }
+            : {}),
           params: rest,
           logger,
         }),

package/src/llm/byo-catalog.ts

@@ -382,6 +382,8 @@ export const BYO_DEFAULT_MODEL: Record<ByoProvider, string> = {
  * A role absent here falls back to the platform provider (deliberately:
  * `embedding` everywhere — none of these providers is wired for the runtime's
  * embedding path — and `vision` on DeepSeek, whose chat models are text-only).
+ * `main` and `summarizer` are not listed: both are the turn's selected model
+ * (`byoModelForRole`), so the history is summarized on the user's provider.
  */
 export const BYO_ROLE_MODELS: Record<
   ByoProvider,
@@ -447,6 +449,7 @@ export const BYO_ROLE_MODELS: Record<
  */
 const KNOWN_MODEL_ROLES: ReadonlySet<string> = new Set([
   'main',
+  'summarizer',
   'skills',
   'subagent',
   'vision',
@@ -460,16 +463,16 @@ const KNOWN_MODEL_ROLES: ReadonlySet<string> = new Set([
 
 /**
  * Resolve the provider-native model id for a role on a BYO turn.
- * `main` uses the turn's selected model; other roles use the translation
- * table. `null` → the role is not served by this provider and the caller
- * must fall back to the platform adapter.
+ * `main` and `summarizer` use the turn's selected model; other roles use the
+ * translation table. `null` → the role is not served by this provider and
+ * the caller must fall back to the platform adapter.
  */
 export function byoModelForRole(
   provider: ByoProvider,
   role: ProviderModelRole | string,
   mainModelId: string,
 ): string | null {
-  if (role === 'main') return mainModelId;
+  if (role === 'main' || role === 'summarizer') return mainModelId;
   const map = BYO_ROLE_MODELS[provider];
   const direct = map[role as ProviderModelRole];
   if (direct) return direct;

package/src/llm/byo-client.ts

@@ -17,8 +17,13 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { ChatOpenAI } from '@langchain/openai';
 import type { ChatOpenAIFields, Logger } from '../plugin-api/types';
-import type { ProviderModelRole } from '../core/llm';
+import { streamLivenessFromEnv, type ProviderModelRole } from '../core/llm';
 import type { ByoCredential } from './byo-catalog';
+import {
+  livenessFetchFor,
+  livenessModelFields,
+  type StreamLivenessSettings,
+} from './stream-liveness';
 
 /** OpenAI-compatible base URLs for the API-key providers that need one. */
 export const DEEPSEEK_BASE_URL = 'https://api.deepseek.com/v1';
@@ -133,6 +138,11 @@ export interface CreateByoChatModelArgs {
   logger?: Logger;
   /** ChatGPT lane only: where requests go (default: the real backend). */
   chatGptBackend?: ChatGptBackendConfig;
+  /**
+   * Liveness budgets for this model's calls (default: the BYO lane's
+   * defaults, see `streamLivenessFromEnv`).
+   */
+  streamLiveness?: StreamLivenessSettings;
 }
 
 const NOOP: Logger = {
@@ -164,17 +174,35 @@ export function createByoChatModel(
   // "Thinking..." for a minute before any error surfaces. Two attempts keep
   // transient-blip resilience while failing fast enough to report.
   const maxRetries = 2;
+  // Every call runs behind the stream liveness guard with the BYO lane's
+  // budgets: a direct provider may stay silent while a model reasons, so
+  // its idle budget is longer than the platform lane's.
+  const liveness = args.streamLiveness ?? streamLivenessFromEnv({}, 'byo');
+  const callerConfiguration = asRecord(params?.configuration);
+  const guardedFetch = (base?: typeof fetch): typeof fetch =>
+    livenessFetchFor({
+      settings: liveness,
+      label: `byo:${credential.provider} ${String(role)} ${modelId}`,
+      logger,
+      callerFetch: callerConfiguration.fetch,
+      ...(base ? { base } : {}),
+    });
 
   switch (credential.provider) {
     case 'openai':
       return new ChatOpenAI({
         __includeRawResponse: true,
         maxRetries,
+        ...livenessModelFields(liveness),
         ...params,
         model: modelId,
         apiKey: credential.apiKey,
         temperature: undefined,
         topP: undefined,
+        configuration: {
+          ...callerConfiguration,
+          fetch: guardedFetch(),
+        },
       });
 
     case 'deepseek':
@@ -182,12 +210,14 @@ export function createByoChatModel(
         temperature,
         __includeRawResponse: true,
         maxRetries,
+        ...livenessModelFields(liveness),
         ...params,
         model: modelId,
         apiKey: credential.apiKey,
         configuration: {
           baseURL: DEEPSEEK_BASE_URL,
-          ...asRecord(params?.configuration),
+          ...callerConfiguration,
+          fetch: guardedFetch(),
         },
       });
 
@@ -196,12 +226,14 @@ export function createByoChatModel(
         temperature,
         __includeRawResponse: true,
         maxRetries,
+        ...livenessModelFields(liveness),
         ...params,
         model: modelId,
         apiKey: credential.apiKey,
         configuration: {
           baseURL: GEMINI_OPENAI_COMPAT_BASE_URL,
-          ...asRecord(params?.configuration),
+          ...callerConfiguration,
+          fetch: guardedFetch(),
         },
       });
 
@@ -211,6 +243,7 @@ export function createByoChatModel(
       return new ChatOpenAI({
         __includeRawResponse: true,
         maxRetries,
+        ...livenessModelFields(liveness),
         ...params,
         model: modelId,
         apiKey: credential.apiKey,
@@ -218,7 +251,8 @@ export function createByoChatModel(
         topP: undefined,
         configuration: {
           baseURL: ANTHROPIC_OPENAI_COMPAT_BASE_URL,
-          ...asRecord(params?.configuration),
+          ...callerConfiguration,
+          fetch: guardedFetch(),
         },
       });
 
@@ -232,7 +266,7 @@ export function createByoChatModel(
       // distinct headers upstream — send both. The backend rejects sampling
       // params (`temperature`/`top_p`) the way the standard API does for
       // reasoning models, and reports request errors with an EMPTY body —
-      // hence the diagnostic fetch.
+      // hence the diagnostic fetch, inside the liveness guard.
       const sessionId = crypto.randomUUID();
       return new ChatOpenAI({
         __includeRawResponse: true,
@@ -249,6 +283,7 @@ export function createByoChatModel(
         // Effort + human-readable reasoning summaries, exactly the pair the
         // Codex clients send — summaries feed the portal's thinking stream.
         reasoning: { effort: 'medium', summary: 'auto' },
+        ...livenessModelFields(liveness),
         ...params,
         model: modelId,
         apiKey: credential.oauth.accessToken,
@@ -257,8 +292,8 @@ export function createByoChatModel(
         topP: undefined,
         configuration: {
           baseURL: backend.baseUrl,
-          fetch: chatGptDiagnosticFetch(logger),
-          ...asRecord(params?.configuration),
+          ...callerConfiguration,
+          fetch: guardedFetch(chatGptDiagnosticFetch(logger)),
           defaultHeaders: {
             ...chatGptBackendHeaders(backend),
             'ChatGPT-Account-ID': credential.oauth.accountId,

package/src/llm/provider-error.ts

@@ -14,6 +14,7 @@ import {
   isByoProvider,
   type ByoProvider,
 } from './byo-catalog';
+import { findProviderStall, type ProviderStallError } from './stream-liveness';
 
 /** `kind` value for the BYO degradation notice. */
 export const BYO_FALLBACK_KIND = 'byo_fallback';
@@ -283,12 +284,27 @@ export interface ClassifyLlmErrorContext {
   byoProvider?: ByoProvider | string | null;
 }
 
+/**
+ * What the user is told about a stalled call (`ProviderStallError`): a stall
+ * mid-reply reads differently from a model that never started.
+ */
+function stallMessage(stall: ProviderStallError): string {
+  return stall.phase === 'stream'
+    ? 'The model stopped responding mid-reply. Please try again.'
+    : 'The model did not start responding. Please try again.';
+}
+
 export function classifyLlmError(
   error: unknown,
   ctx?: ClassifyLlmErrorContext,
 ): ClassifiedLlmError {
-  const parts = extractErrorParts(error);
-  const kind = detectKind(parts);
+  // A stall is found through the wrappers (the OpenAI SDK's
+  // `APIConnectionError`, LangChain's middleware errors) by its `cause`.
+  const stall = findProviderStall(error);
+  const parts: ErrorParts = stall
+    ? { text: stall.message }
+    : extractErrorParts(error);
+  const kind: LlmErrorKind = stall ? 'timeout' : detectKind(parts);
   const provider =
     typeof ctx?.byoProvider === 'string' &&
     isByoProvider(ctx.byoProvider) &&
@@ -305,7 +321,9 @@ export function classifyLlmError(
     ...(providerLabel && { providerLabel }),
     ...(parts.status !== undefined && { status: parts.status }),
     retryable: RETRYABLE_KINDS.has(kind),
-    message: fallbackMessage(kind, provider, providerLabel),
+    message: stall
+      ? stallMessage(stall)
+      : fallbackMessage(kind, provider, providerLabel),
     detail: parts.text,
   };
 }