@pellux/goodvibes-tui 0.20.3 → 0.21.0

package/src/core/conversation-rendering.ts

@@ -1,5 +1,6 @@
 import { UIFactory } from '../renderer/ui-factory.ts';
 import { renderMarkdownTracked } from '../renderer/markdown.ts';
+import { DARK_THEME } from '../renderer/theme.ts';
 import { renderToolCallBlock } from '../renderer/tool-call.ts';
 import { renderThinkingBlock } from '../renderer/thinking.ts';
 import { renderSystemMessage } from '../renderer/system-message.ts';
@@ -13,6 +14,23 @@ import { GLYPHS } from '../renderer/ui-primitives.ts';
 import type { BlockMeta, ConversationMessageSnapshot } from './conversation';
 import { parseDiffForApply } from '@pellux/goodvibes-sdk/platform/core';
 import { extractUserDisplayText } from '@pellux/goodvibes-sdk/platform/core';
+import type { SystemMessageKind } from './system-message-router.ts';
+
+const T = DARK_THEME;
+
+/**
+ * Navigable system message kinds for error-navigation (nextErrorLine/prevErrorLine).
+ *
+ * Kind → navigable mapping:
+ *   - 'system'      YES — generic/catch-all messages (provider failures, session
+ *                         events, user-visible errors). Default for un-prefixed messages.
+ *   - 'wrfc'        YES — WRFC chain events are important and worth navigating to.
+ *   - 'operational' NO  — tool/scan/plugin/MCP status noise; not useful to jump to.
+ *
+ * When a message has no recorded kind (added via bare addSystemMessage), it
+ * defaults to 'system' and is therefore navigable.
+ */
+const NAVIGABLE_KINDS: ReadonlySet<SystemMessageKind> = new Set(['system', 'wrfc']);
 
 type Message = ConversationMessageSnapshot;
 
@@ -29,6 +47,8 @@ interface ConversationRenderContext {
   readonly blockRegistry: BlockMeta[];
   readonly collapseState: Map<string, boolean>;
   readonly errorLineRegistry: number[];
+  /** Maps message index → SystemMessageKind for typed system messages. */
+  readonly messageKindRegistry: ReadonlyMap<number, SystemMessageKind>;
   readonly configManager: ConfigManager | null;
   readonly splashOptions: SplashOptions;
 }
@@ -40,7 +60,7 @@ export function renderConversationUserMessage(
 ): void {
   const displayText = extractUserDisplayText(message.content);
   if (message.cancelled) {
-    context.history.addLines(UIFactory.createMessageBar(width, displayText, '#3a1a1a', '196', ' x ', true));
+    context.history.addLines(UIFactory.createMessageBar(width, displayText, T.errorBarBg, '196', ' x ', true));
     return;
   }
   context.history.addLines(UIFactory.createMessageBar(width, displayText));
@@ -56,20 +76,20 @@ export function renderConversationAssistantMessage(
 ): void {
   const assistantHeaderDetails = [];
   if (message.model) {
-    assistantHeaderDetails.push({ text: ` ${message.model}${message.provider ? ` (${message.provider})` : ''} `, fg: '#94a3b8', dim: true });
+    assistantHeaderDetails.push({ text: ` ${message.model}${message.provider ? ` (${message.provider})` : ''} `, fg: T.modelNameDim, dim: true });
   }
   if (message.toolCalls && message.toolCalls.length > 0) {
-    assistantHeaderDetails.push({ text: ` ${GLYPHS.status.pending} tools:${message.toolCalls.length} `, fg: '#38bdf8' });
+    assistantHeaderDetails.push({ text: ` ${GLYPHS.status.pending} tools:${message.toolCalls.length} `, fg: T.toolAccent });
   }
   if (message.reasoningContent || message.reasoningSummary) {
-    assistantHeaderDetails.push({ text: ` ${GLYPHS.status.active} reasoning `, fg: '#a855f7', dim: true });
+    assistantHeaderDetails.push({ text: ` ${GLYPHS.status.active} reasoning `, fg: T.reasoningAccent, dim: true });
   }
   if (assistantHeaderDetails.length > 0) {
     context.history.addLine(renderConversationEventLine(width, {
       marker: GLYPHS.status.active,
-      markerFg: '#22d3ee',
+      markerFg: T.assistantHeader,
       label: 'assistant',
-      labelFg: '#22d3ee',
+      labelFg: T.assistantHeader,
       detailFg: '244',
     }, assistantHeaderDetails));
   }
@@ -180,11 +200,15 @@ export function renderConversationSystemMessage(
   context: ConversationRenderContext,
   message: Extract<Message, { role: 'system' }>,
   width: number,
+  msgIdx: number,
 ): void {
   const sysStartLine = context.history.getLineCount();
   const sysLines = renderSystemMessage(message.content, width);
   context.history.addLines(sysLines);
-  if (/error/i.test(message.content)) {
+  // Resolve navigability from the stored kind, defaulting to 'system'
+  // (navigable) for messages added without an explicit kind tag.
+  const kind: SystemMessageKind = context.messageKindRegistry.get(msgIdx) ?? 'system';
+  if (NAVIGABLE_KINDS.has(kind)) {
     context.errorLineRegistry.push(sysStartLine);
   }
 }
@@ -218,13 +242,13 @@ export function renderConversationToolMessage(
 
   context.history.addLine(renderConversationEventLine(width, {
     marker: blockType === 'diff' ? GLYPHS.status.dualPane : GLYPHS.status.active,
-    markerFg: blockType === 'diff' ? '#f59e0b' : '#38bdf8',
+    markerFg: blockType === 'diff' ? T.diffAccent : T.toolAccent,
     label: blockType === 'diff' ? 'diff' : 'tool result',
-    labelFg: blockType === 'diff' ? '#f59e0b' : '#38bdf8',
+    labelFg: blockType === 'diff' ? T.diffAccent : T.toolAccent,
     detailFg: '244',
   }, [
     ...(message.toolName
-      ? [{ text: ` ${message.toolName} `, fg: '#e2e8f0' as const }]
+      ? [{ text: ` ${message.toolName} `, fg: T.toolNameFg }]
       : [{ text: ` ${summarizeCallId(message.callId || 'standalone')} `, fg: '244' as const, dim: true }]),
     { text: ` ${isCollapsed ? GLYPHS.navigation.collapsed : GLYPHS.navigation.expanded} ${lineCount} line${lineCount === 1 ? '' : 's'} `, fg: '244', dim: true },
   ]));
@@ -238,9 +262,9 @@ export function renderConversationToolMessage(
       : preview;
     const rendered = renderConversationCollapsedFragment(collapsedText, width, {
       prefix: blockType === 'diff' ? ` ${GLYPHS.status.dualPane} ` : ` ${GLYPHS.navigation.collapsed} `,
-      prefixFg: blockType === 'diff' ? '#f59e0b' : '#38bdf8',
+      prefixFg: blockType === 'diff' ? T.diffAccent : T.toolAccent,
       text: '244',
-      bodyBg: '#1a1a1a',
+      bodyBg: T.collapsedBodyBg,
       dim: true,
     });
     context.history.addLines(rendered);
@@ -280,6 +304,13 @@ export function appendConversationMessages(
   messages: Message[],
   width: number,
   messageLineRegistry: number[],
+  /**
+   * Absolute index of messages[0] in the full (unsliced) conversation snapshot.
+   * Required to align slice-relative loop indices with the absolute keys stored
+   * in messageKindRegistry, which is keyed at add-time (before any slice).
+   * Defaults to 0 when the full snapshot is rendered (no clearDisplay in effect).
+   */
+  msgIndexOffset = 0,
 ): void {
   const lineNumberMode = context.configManager?.get('display.lineNumbers') ?? 'off';
   const collapseThreshold = context.configManager?.get('display.collapseThreshold') ?? 30;
@@ -287,14 +318,17 @@ export function appendConversationMessages(
   for (let msgIdx = 0; msgIdx < messages.length; msgIdx++) {
     const message = messages[msgIdx];
     messageLineRegistry[msgIdx] = context.history.getLineCount();
+    // absoluteIdx aligns the slice-relative loop counter with the absolute
+    // message index used as the key in messageKindRegistry.
+    const absoluteIdx = msgIndexOffset + msgIdx;
     if (message.role === 'user') {
       renderConversationUserMessage(context, message, width);
     } else if (message.role === 'assistant') {
-      renderConversationAssistantMessage(context, message, width, lineNumberMode, collapseThreshold, msgIdx);
+      renderConversationAssistantMessage(context, message, width, lineNumberMode, collapseThreshold, absoluteIdx);
     } else if (message.role === 'system') {
-      renderConversationSystemMessage(context, message, width);
+      renderConversationSystemMessage(context, message, width, absoluteIdx);
     } else if (message.role === 'tool') {
-      renderConversationToolMessage(context, message, width, msgIdx);
+      renderConversationToolMessage(context, message, width, absoluteIdx);
     }
     context.history.addLine(createEmptyLine(width));
   }

package/src/core/conversation.ts

@@ -5,6 +5,7 @@ import type { ToolCall, ToolResult } from '@pellux/goodvibes-sdk/platform/types'
 import type { ProviderMessage, ContentPart } from '@pellux/goodvibes-sdk/platform/providers';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { TranscriptEventKind } from '@pellux/goodvibes-sdk/platform/core';
+import type { SystemMessageKind } from './system-message-router.ts';
 import {
   ConversationManager as SdkConversationManager,
   type BlockMeta as SdkBlockMeta,
@@ -70,10 +71,31 @@ export class ConversationManager extends SdkConversationManager {
   protected blockRegistry: BlockMeta[] = [];
   /** Message index -> first rendered line index in the history buffer. */
   private messageLineRegistry: number[] = [];
-  /** Registry of rendered line indices for system messages matching /error/i. */
+  /**
+   * Registry of rendered line indices for system messages whose kind is
+   * navigable (error-navigation worthy).
+   *
+   * Kind → navigable mapping:
+   *   - 'system'      YES — generic/catch-all messages (failures, provider errors,
+   *                         session events); the default for any un-prefixed message
+   *   - 'wrfc'        YES — WRFC chain events (failures matter for navigation)
+   *   - 'operational' NO  — noisy tool/scan/plugin/MCP status; not worth jumping to
+   *
+   * This replaces the old /error/i substring test, which missed failure phrases
+   * like "request failed" / "rate limited" and false-positived on benign info
+   * text that happened to contain the word "error".
+   */
   private errorLineRegistry: number[] = [];
+  /** Maps message index → SystemMessageKind for system-role messages. */
+  private messageKindRegistry: Map<number, SystemMessageKind> = new Map();
   /** Streaming block start line in history buffer (for incremental streaming update). */
   private streamingStartLine = -1;
+  /**
+   * Timestamp of the last renderMarkdown call during streaming.
+   * Used to throttle full re-parses to the 16ms render coalescer cadence.
+   * Reset to 0 on startStreamingBlock and finalizeStreamingBlock.
+   */
+  private _lastStreamRenderMs = 0;
   /**
    * Message index at the time of the last clearDisplay() call.
    * rebuildHistory() renders only messages at or after this index, so the
@@ -135,13 +157,49 @@ export class ConversationManager extends SdkConversationManager {
   }
 
   public override addSystemMessage(content: string): void {
+    // Clear any stale kind entry at the index this message will occupy.
+    // undo() splices the tail of this.messages, freeing indices that ARE reused
+    // by subsequent adds. Without this delete, a recycled index could carry a
+    // stale kind (e.g. 'operational') and silently mis-classify the new message.
+    const nextIndex = this.getMessageSnapshot().length;
+    this.messageKindRegistry.delete(nextIndex);
+    super.addSystemMessage(content);
+    this.markDirty();
+  }
+
+  /**
+   * addTypedSystemMessage - Add a system message with an explicit kind tag.
+   * The kind is stored in messageKindRegistry (keyed by the message index that
+   * will be assigned after the push) so that renderConversationSystemMessage
+   * can use it instead of text-based pattern matching.
+   *
+   * Called by SystemMessageRouter.routeTypedSystemMessage when routing to the
+   * conversation surface. Falls back to addSystemMessage for callers that do
+   * not have kind information.
+   */
+  public addTypedSystemMessage(content: string, kind: SystemMessageKind): void {
+    // getMessageSnapshot().length is the index this message will receive after
+    // addSystemMessage appends it to the messages array.
+    const nextIndex = this.getMessageSnapshot().length;
+    this.messageKindRegistry.set(nextIndex, kind);
     super.addSystemMessage(content);
     this.markDirty();
   }
 
   public override undo(): boolean {
     const result = super.undo();
-    if (result) this.markDirty();
+    if (result) {
+      // undo() splices the messages tail at the last user-message index, meaning
+      // freed indices CAN be reused by subsequent adds. Purge all registry entries
+      // at or after the new message count so a recycled index cannot carry a stale
+      // kind from the evicted turn (e.g. 'operational' mis-classifying a bare add
+      // as non-navigable, or 'wrfc' wrongly making an operational message navigable).
+      const postUndoCount = this.getMessageSnapshot().length;
+      for (const key of this.messageKindRegistry.keys()) {
+        if (key >= postUndoCount) this.messageKindRegistry.delete(key);
+      }
+      this.markDirty();
+    }
     return result;
   }
 
@@ -172,9 +230,11 @@ export class ConversationManager extends SdkConversationManager {
   public override startStreamingBlock(): void {
     super.startStreamingBlock();
     this.markDirty();
-    // Record the line where the streaming block starts so updates can be incremental
+    // Record the line where the streaming block starts so updates can be incremental.
+    // Reset the render throttle so the first delta always renders immediately.
     this.flushHistory();
     this.streamingStartLine = this.history.getLineCount();
+    this._lastStreamRenderMs = 0;
   }
 
   /**
@@ -184,12 +244,18 @@ export class ConversationManager extends SdkConversationManager {
    */
   public override updateStreamingBlock(content: string): void {
     super.updateStreamingBlock(content);
-    // Incrementally update the history buffer instead of full rebuild
+    // Incrementally update the history buffer instead of full rebuild.
+    // Throttle renderMarkdown to the 16ms render-coalescer cadence to avoid
+    // O(n) parse overhead on every delta token during streaming.
     if (this.streamingStartLine >= 0) {
-      const width = this._getWidth();
-      this.history.truncateToLine(this.streamingStartLine);
-      const rendered = renderMarkdown(content, width);
-      this.history.addLines(rendered);
+      const now = Date.now();
+      if (now - this._lastStreamRenderMs >= 16) {
+        this._lastStreamRenderMs = now;
+        const width = this._getWidth();
+        this.history.truncateToLine(this.streamingStartLine);
+        const rendered = renderMarkdown(content, width, { isStreaming: true });
+        this.history.addLines(rendered);
+      }
     }
   }
 
@@ -200,6 +266,7 @@ export class ConversationManager extends SdkConversationManager {
   public override finalizeStreamingBlock(): void {
     super.finalizeStreamingBlock();
     this.streamingStartLine = -1;
+    this._lastStreamRenderMs = 0;
     this.markDirty();
   }
 
@@ -221,6 +288,7 @@ export class ConversationManager extends SdkConversationManager {
     this.blockRegistry = [];
     this.messageLineRegistry = [];
     this.errorLineRegistry = [];
+    this.messageKindRegistry = new Map();
     this.streamingStartLine = -1;
     this._displayFromMessageIndex = 0; // full reset — show everything on next render
   }
@@ -297,6 +365,8 @@ export class ConversationManager extends SdkConversationManager {
     this.blockRegistry = [];
     this.messageLineRegistry = [];
     this.errorLineRegistry = [];
+    // messageKindRegistry is NOT cleared here: kind info is set at add-time
+    // and must survive width-change rebuilds.
     const width = this._getWidth();
     this.lastRenderedWidth = width;
     this.dirty = false;
@@ -321,7 +391,7 @@ export class ConversationManager extends SdkConversationManager {
       return;
     }
 
-    this.appendMessages(visibleSnapshot, width);
+    this.appendMessages(visibleSnapshot, width, displayStart);
     this.appendedUpTo = snapshot.length;
   }
 
@@ -345,6 +415,7 @@ export class ConversationManager extends SdkConversationManager {
       blockRegistry: this.blockRegistry,
       collapseState: this.collapseState,
       errorLineRegistry: this.errorLineRegistry,
+      messageKindRegistry: this.messageKindRegistry as ReadonlyMap<number, SystemMessageKind>,
       configManager: this._configManager,
       splashOptions: this.splashOptions,
     };
@@ -364,17 +435,24 @@ export class ConversationManager extends SdkConversationManager {
     renderConversationAssistantMessage(this.renderingContext(), message, width, lineNumberMode, collapseThreshold, msgIdx);
   }
 
-  private renderSystemMessage(message: Extract<Message, { role: 'system' }>, width: number): void {
-    renderConversationSystemMessage(this.renderingContext(), message, width);
+  private renderSystemMessage(message: Extract<Message, { role: 'system' }>, width: number, msgIdx: number): void {
+    renderConversationSystemMessage(this.renderingContext(), message, width, msgIdx);
   }
 
   private renderToolMessage(message: Extract<Message, { role: 'tool' }>, width: number, msgIdx: number): void {
     renderConversationToolMessage(this.renderingContext(), message, width, msgIdx);
   }
 
-  /** Render a slice of messages into the history buffer. */
-  private appendMessages(messages: Message[], width: number): void {
-    appendConversationMessages(this.renderingContext(), messages, width, this.messageLineRegistry);
+  /**
+   * Render a slice of messages into the history buffer.
+   *
+   * @param msgIndexOffset - Absolute index of messages[0] in the full snapshot.
+   *   Must equal displayStart when rendering a post-clearDisplay slice so that
+   *   the renderer can resolve messageKindRegistry keys (which are absolute)
+   *   from its slice-relative loop counter.
+   */
+  private appendMessages(messages: Message[], width: number, msgIndexOffset = 0): void {
+    appendConversationMessages(this.renderingContext(), messages, width, this.messageLineRegistry, msgIndexOffset);
   }
 
   /** Find the nearest block to a given line index, optionally filtered by type. */
@@ -446,8 +524,9 @@ export class ConversationManager extends SdkConversationManager {
 
   /**
    * getErrorLines - Returns line indices in the rendered history buffer for
-   * system messages that contain 'error' (case-insensitive).
-   * Triggers a history flush if dirty.
+   * system messages whose kind is navigable (see NAVIGABLE_KINDS in
+   * conversation-rendering.ts: 'system' and 'wrfc'). Operational messages
+   * are excluded regardless of message text. Triggers a history flush if dirty.
    */
   public getErrorLines(): number[] {
     this.flushHistory();
@@ -538,6 +617,12 @@ export class ConversationManager extends SdkConversationManager {
     this.blockRegistry = [];
     this.messageLineRegistry = [];
     this.errorLineRegistry = [];
+    // messageKindRegistry is NOT cleared here. The underlying messages array is
+    // preserved by clearDisplay(); kind entries for pre-clear messages are harmless
+    // because those messages are hidden by _displayFromMessageIndex and never rendered.
+    // Clearing the registry would cause kind loss for pre-clear messages that become
+    // visible again after a subsequent width-change rebuild (which resets displayStart
+    // to 0), incorrectly making operational messages navigable.
     // Advance _displayFromMessageIndex to exclude all current messages from display.
     // rebuildHistory() will only render messages added AFTER this point.
     this._displayFromMessageIndex = this.getMessageSnapshot().length;

package/src/core/format-user-error.ts

@@ -0,0 +1,192 @@
+/**
+ * formatUserFacingError — classifies provider/network errors into plain-language
+ * one-liners with a suggested action.
+ *
+ * Classification order (most-specific first):
+ *   auth           → 401, 'invalid' + 'key'/'token', 'Unauthorized', 'forbidden'
+ *   rate-limit     → 429, 'rate limit', 'rate_limit', 'too many requests', 'quota'
+ *   context-overflow → 'context length', 'maximum context', 'too many tokens',
+ *                     'context window'
+ *   network        → ECONNREFUSED, ETIMEDOUT, 'fetch failed', 'socket hang up',
+ *                     'network', ENOTFOUND
+ *   generic        → summarizeError fallback
+ *
+ * @module
+ */
+
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ErrorClass =
+  | 'auth'
+  | 'rate-limit'
+  | 'context-overflow'
+  | 'network'
+  | 'generic';
+
+export interface UserFacingError {
+  /** Short, plain-language description of what went wrong. */
+  message: string;
+  /** Suggested recovery action (slash-command or brief instruction). */
+  action: string;
+  /** Which classifier matched. */
+  kind: ErrorClass;
+}
+
+// ---------------------------------------------------------------------------
+// Classifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a canonical string probe from an unknown error value.
+ * Concatenates status code (if present), error name, and message so that a
+ * single regex can match across all shapes.
+ */
+function probeString(err: unknown): string {
+  if (err == null) return '';
+  const parts: string[] = [];
+
+  if (typeof err === 'object') {
+    // HTTP-style status fields
+    const asRecord = err as Record<string, unknown>;
+    const status = asRecord['status'] ?? asRecord['statusCode'] ?? asRecord['code'];
+    if (status != null) parts.push(String(status));
+
+    // name and message
+    if ('name' in asRecord && typeof asRecord['name'] === 'string') parts.push(asRecord['name']);
+    if ('message' in asRecord && typeof asRecord['message'] === 'string') parts.push(asRecord['message']);
+
+    // cause chain (one level)
+    if ('cause' in asRecord && asRecord['cause'] != null) {
+      const cause = asRecord['cause'] as Record<string, unknown>;
+      if (typeof cause['message'] === 'string') parts.push(cause['message']);
+      if (typeof cause['code'] === 'string') parts.push(cause['code']);
+    }
+  } else if (typeof err === 'string') {
+    parts.push(err);
+  } else {
+    parts.push(String(err));
+  }
+
+  return parts.join(' ').toLowerCase();
+}
+
+export function classifyError(err: unknown): ErrorClass {
+  const probe = probeString(err);
+
+  // Auth: 401 status, key/token invalidity, Unauthorized
+  if (
+    /\b401\b/.test(probe) ||
+    /invalid.{0,10}(api.?key|key|token)/i.test(probe) ||
+    /unauthorized/i.test(probe) ||
+    /authentication/i.test(probe) ||
+    /api.?key.{0,20}(missing|not.?set|required|invalid)/i.test(probe)
+  ) {
+    return 'auth';
+  }
+
+  // Rate-limit: 429 status, quota exceeded
+  if (
+    /\b429\b/.test(probe) ||
+    /rate.?limit/i.test(probe) ||
+    /too many requests/i.test(probe) ||
+    /quota.{0,20}exceeded/i.test(probe) ||
+    /request.{0,20}limit/i.test(probe)
+  ) {
+    return 'rate-limit';
+  }
+
+  // Context overflow: provider context-window exceeded messages
+  if (
+    /context.{0,10}(length|window|limit)/i.test(probe) ||
+    /maximum context/i.test(probe) ||
+    /too many tokens/i.test(probe) ||
+    /token.{0,10}limit/i.test(probe) ||
+    /context.{0,20}exceeded/i.test(probe) ||
+    /input.{0,10}too.{0,10}long/i.test(probe)
+  ) {
+    return 'context-overflow';
+  }
+
+  // Network: connection/transport errors
+  if (
+    /econnrefused/i.test(probe) ||
+    /etimedout/i.test(probe) ||
+    /enotfound/i.test(probe) ||
+    /fetch failed/i.test(probe) ||
+    /socket hang up/i.test(probe) ||
+    /network.{0,20}(error|failure|timeout)/i.test(probe) ||
+    /connection.{0,20}(refused|reset|timeout|closed)/i.test(probe) ||
+    /timeout/i.test(probe)
+  ) {
+    return 'network';
+  }
+
+  return 'generic';
+}
+
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Classifies `err` and returns a plain-language one-liner with a suggested
+ * recovery action.
+ *
+ * Uses `summarizeError` from the SDK as the detail fallback for generic errors
+ * so stack traces never leak into the UI.
+ */
+export function formatUserFacingError(err: unknown): UserFacingError {
+  const kind = classifyError(err);
+
+  switch (kind) {
+    case 'auth':
+      return {
+        kind,
+        message: 'Authentication failed — the provider rejected your API key.',
+        action: 'Run /login to re-authenticate or check your API key.',
+      };
+
+    case 'rate-limit':
+      return {
+        kind,
+        message: 'Rate limit reached — the provider is throttling requests.',
+        action: 'Wait a moment and retry, or switch models with /model.',
+      };
+
+    case 'context-overflow':
+      return {
+        kind,
+        message: 'Context window exceeded — the conversation is too long for this model.',
+        action: 'Run /compact to summarise the conversation and free context.',
+      };
+
+    case 'network':
+      return {
+        kind,
+        message: 'Network error — could not reach the provider.',
+        action: 'Check your connection and retry, or switch models with /model.',
+      };
+
+    default: {
+      const detail = summarizeError(err);
+      return {
+        kind: 'generic',
+        message: `Provider error: ${detail}`,
+        action: 'Retry your last message, or switch models with /model.',
+      };
+    }
+  }
+}
+
+/**
+ * Convenience helper: returns the full formatted string for use in a single
+ * system message. Formats as "<message> <action>"
+ */
+export function formatUserFacingErrorLine(err: unknown): string {
+  const { message, action } = formatUserFacingError(err);
+  return `${message} ${action}`;
+}