talon-agent 1.12.0 → 1.34.0

package/src/backend/shared/delivery-contract.ts

@@ -0,0 +1,161 @@
+/**
+ * Delivery-contract text — single source of truth for "how a reply
+ * reaches the user" documentation.
+ *
+ * The response-flow contract is a property of the BACKEND (claude-sdk
+ * and openai-agents enforce strict tool-only delivery; codex / kilo /
+ * opencode accept plain assistant text), while the delivery TOOL NAMES
+ * are a property of the FRONTEND (telegram/discord ship `end_turn` /
+ * `send` / `react`; native ships `end_turn` / `send_message` /
+ * `react`; teams ships `end_turn` / `send_message`). Before
+ * this module, the strict contract was hardcoded into the frontend
+ * prompt files (prompts/telegram.md etc.) — buried mid-prompt where
+ * models routinely missed it on the first turn of a session, and
+ * contradicted by the text-mode backends' own suffixes.
+ *
+ * Backends now build their suffix from here and append it via
+ * `prepareSystemPrompt({ backendSuffix })`, which places the contract
+ * at the END of the static prompt — the highest-salience position —
+ * without touching the prompt-cache-friendly static/dynamic split.
+ *
+ * Also here:
+ *   - `buildFlowViolationReminder` — frontend-aware [FLOW VIOLATION]
+ *     re-prompt text (the shared constant used to hardcode telegram's
+ *     tool names, which made the reminder wrong on Teams).
+ *   - `buildFirstTurnReminder` — a one-line nudge appended to the
+ *     formatted user prompt on the FIRST turn of a session. First
+ *     turns are where flow violations cluster: the model hasn't seen
+ *     the contract in action yet. One short line on turn 0 is far
+ *     cheaper than the 2x-token violation retry it prevents.
+ *
+ * The contract bodies live in `prompts/system/contract-*.md`
+ * (package-owned templates, see core/prompt/templates.ts). The
+ * one-line runtime reminders below stay in code: they are
+ * logic-adjacent strings, like log messages.
+ */
+
+import { loadSystemTemplate } from "../../core/prompt/templates.js";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/**
+ * How a backend delivers replies to the user.
+ *
+ *   - `tool-only` — output stream is private scratchpad; replies MUST
+ *     go through a delivery tool (claude-sdk, openai-agents).
+ *   - `text-or-tools` — plain assistant text is delivered as the
+ *     reply; delivery tools add rich content / targeting (codex, kilo).
+ *   - `text-preferred` — plain text is the normal route; tools only
+ *     for genuine side effects (opencode).
+ */
+export type DeliveryMode = "tool-only" | "text-or-tools" | "text-preferred";
+
+/** Frontend-specific delivery tool names. */
+export type DeliveryToolNames = {
+  /** Turn-closing final-reply tool. */
+  endTurn: string;
+  /** Mid-turn / rich-content send tool. */
+  send: string;
+  /** Emoji-reaction tool, when the frontend supports reactions. */
+  react?: string;
+};
+
+// ── Frontend tool-name registry ─────────────────────────────────────────────
+
+const FRONTEND_TOOLS: Record<string, DeliveryToolNames> = {
+  telegram: { endTurn: "end_turn", send: "send", react: "react" },
+  discord: { endTurn: "end_turn", send: "send", react: "react" },
+  teams: { endTurn: "end_turn", send: "send_message" },
+  native: { endTurn: "end_turn", send: "send_message", react: "react" },
+};
+
+const DEFAULT_TOOLS: DeliveryToolNames = {
+  endTurn: "end_turn",
+  send: "send",
+  react: "react",
+};
+
+/**
+ * Delivery tool names for a frontend. Unknown frontends (and
+ * `terminal`, which has no outbound messaging surface) fall back to
+ * the telegram-shaped defaults — harmless, since backends only enforce
+ * the contract when a frontend MCP server is actually wired.
+ */
+export function deliveryToolsForFrontend(frontend: string): DeliveryToolNames {
+  return FRONTEND_TOOLS[frontend] ?? DEFAULT_TOOLS;
+}
+
+/**
+ * Register (or override) the delivery tool names for a frontend.
+ * Extension seam: a new frontend declares its tool names here at
+ * registration time and every backend's contract, flow-violation
+ * reminder, and first-turn nudge pick them up — no edits to this
+ * module or to any backend.
+ */
+export function registerFrontendDeliveryTools(
+  frontend: string,
+  tools: DeliveryToolNames,
+): void {
+  FRONTEND_TOOLS[frontend] = tools;
+}
+
+// ── Contract suffix ─────────────────────────────────────────────────────────
+
+/**
+ * Build the response-flow contract section a backend appends to the
+ * static system prompt. The prose lives in package-owned templates
+ * (`prompts/system/contract-*.md`) — kept deliberately tight: this is
+ * read on every session, so every sentence must earn its tokens. The
+ * per-tool details (parameter shapes, examples) live in the MCP tool
+ * descriptions, which the model also has in context.
+ */
+export function buildDeliveryContract(
+  mode: DeliveryMode,
+  frontend: string,
+): string {
+  const t = deliveryToolsForFrontend(frontend);
+  return loadSystemTemplate(`contract-${mode}`, {
+    end_turn: t.endTurn,
+    send: t.send,
+    react: t.react,
+  });
+}
+
+// ── Flow-violation reminder ─────────────────────────────────────────────────
+
+/**
+ * Frontend-aware [FLOW VIOLATION] reminder. Same shape as the legacy
+ * shared `FLOW_VIOLATION_REMINDER`, but with the frontend's actual
+ * tool names (the constant hardcoded \`send\`/\`react\`, which don't
+ * exist on Teams).
+ */
+export function buildFlowViolationReminder(frontend: string): string {
+  const t = deliveryToolsForFrontend(frontend);
+  const reactPart = t.react
+    ? `, or \`${t.react}(emoji=...)\` for an emoji acknowledgement`
+    : "";
+  return (
+    "[FLOW VIOLATION] Your previous turn ended without a delivery tool, so the " +
+    "user saw nothing. Replies must go through a tool call: " +
+    `\`${t.endTurn}(text=...)\` for a final reply, ` +
+    `\`${t.endTurn}()\` (no args) to close silently, ` +
+    `\`${t.send}(...)\` for mid-turn rich content${reactPart}. ` +
+    "Tool calls alone do not close the turn. Retry now using the correct tool call."
+  );
+}
+
+// ── First-turn nudge ────────────────────────────────────────────────────────
+
+/**
+ * One-line reminder appended to the formatted user prompt on the first
+ * turn of a session (strict backends only). Lives in the user message,
+ * not the system prompt, so it costs nothing on later turns and never
+ * perturbs the cached static prefix.
+ */
+export function buildFirstTurnReminder(frontend: string): string {
+  const t = deliveryToolsForFrontend(frontend);
+  return (
+    `[New session — reminder: your prose output is never shown to the user. ` +
+    `Deliver your reply via ${t.endTurn}(text=...), or ${t.endTurn}() to stay silent.]`
+  );
+}

package/src/backend/shared/delivery.ts

@@ -35,6 +35,32 @@ import { incrementCounter } from "../../util/metrics.js";
 /** Route the delivery decision selected. */
 export type DeliveryRoute = "tool" | "text-part" | "synthetic-error" | "empty";
 
+export class TextBlockDeliveryError extends Error {
+  readonly route: DeliveryRoute;
+  readonly chars: number;
+
+  constructor(route: DeliveryRoute, chars: number, cause: unknown) {
+    super(
+      `text-block delivery failed (${route}, ${chars} chars): ${errMsg(cause)}`,
+    );
+    this.name = "TextBlockDeliveryError";
+    this.route = route;
+    this.chars = chars;
+    this.cause = cause;
+  }
+}
+
+export function buildDeliveryFailureReminder(error: TextBlockDeliveryError) {
+  return (
+    "[DELIVERY FAILURE] Your previous reply was not shown to the user because " +
+    `Talon failed while delivering a ${error.route} response (${error.chars} chars): ${errMsg(error.cause)}. ` +
+    "Retry now using delivery tools. If the answer is long, split it across " +
+    'multiple `send(type="text", text=...)` calls and then call `end_turn()`; ' +
+    "or shorten the answer and call `end_turn(text=...)`. Do not write the final " +
+    "answer as plain assistant text."
+  );
+}
+
 /** Outcome of `routeDelivery` — `route` + char count for the log line. */
 export interface DeliveryDecision {
   route: DeliveryRoute;
@@ -58,6 +84,11 @@ export interface RouteDeliveryInputs {
    * `kilo.synthetic_error`). Defaults to a lower-cased backendLabel.
    */
   metricNamespace?: string;
+  /**
+   * When true, failed `onTextBlock` delivery is thrown back to the backend so
+   * it can re-prompt the model. Default preserves older non-fatal behaviour.
+   */
+  propagateDeliveryFailure?: boolean;
 }
 
 /**
@@ -78,6 +109,7 @@ export async function routeDelivery(
     responseText,
     onTextBlock,
     metricNamespace = backendLabel.toLowerCase(),
+    propagateDeliveryFailure = false,
   } = inputs;
 
   // Route 1 — bridge delivery already happened.
@@ -116,6 +148,13 @@ export async function routeDelivery(
           "agent",
           `[${chatId}] onTextBlock (synthetic-error) failed: ${errMsg(err)}`,
         );
+        if (propagateDeliveryFailure) {
+          throw new TextBlockDeliveryError(
+            "synthetic-error",
+            state.syntheticError.length,
+            err,
+          );
+        }
       }
     }
     return {
@@ -131,6 +170,13 @@ export async function routeDelivery(
         await onTextBlock(responseText);
       } catch (err) {
         logWarn("agent", `[${chatId}] onTextBlock failed: ${errMsg(err)}`);
+        if (propagateDeliveryFailure) {
+          throw new TextBlockDeliveryError(
+            "text-part",
+            responseText.length,
+            err,
+          );
+        }
       }
     }
     return { route: "text-part", chars: responseText.length };
@@ -155,6 +201,9 @@ export async function routeDelivery(
           "agent",
           `[${chatId}] onTextBlock (empty-turn error) failed: ${errMsg(err)}`,
         );
+        if (propagateDeliveryFailure) {
+          throw new TextBlockDeliveryError("empty", 0, err);
+        }
       }
     }
     return { route: "empty", chars: 0 };

package/src/backend/shared/flow-violation.ts

@@ -29,7 +29,9 @@ export const FLOW_VIOLATION_REMINDER =
   "`end_turn()` (no args) to close silently, " +
   "`send(...)` for mid-turn rich content (photos, polls, etc.), or " +
   "`react(emoji=...)` for an emoji acknowledgement. " +
-  "Retry now using the correct tool call.";
+  "Tool calls alone do not close the turn. Retry now using the correct tool call.";
+
+export const FLOW_VIOLATION_MAX_RETRIES = 3;
 
 // ── Public API ──────────────────────────────────────────────────────────────
 
@@ -41,8 +43,21 @@ export type FlowViolationInputs = {
   turnTerminated: boolean;
   /** Already-delivered text norms used for dedup. */
   deliveredTextNorms: readonly string[];
+  /** Number of tool calls observed in this turn. */
+  toolCalls?: number;
   /** Whether this is already a retry (prevents looping). */
   retried: boolean;
+  /** Number of synthetic flow-violation retries already attempted. */
+  retryCount?: number;
+  /** Maximum synthetic flow-violation retries before accepting the drop. */
+  maxRetries?: number;
+  /**
+   * Reminder text to ship on retry. Defaults to the legacy
+   * telegram-shaped `FLOW_VIOLATION_REMINDER`; backends should pass
+   * `buildFlowViolationReminder(frontend)` so the tool names match
+   * what's actually registered (Teams has `send_message`, not `send`).
+   */
+  reminder?: string;
 };
 
 /** Outcome of the flow-violation check. */
@@ -52,6 +67,8 @@ export type FlowViolationResult =
       violated: true;
       /** Trimmed scratchpad prose that would be dropped. */
       trailing: string;
+      /** Human-readable reason logged by handlers. */
+      reason: string;
       /** Whether the handler should re-prompt with `reminder`. False when retried. */
       shouldRetry: boolean;
       /** Reminder string to send as the next user prompt (when retrying). */
@@ -65,9 +82,9 @@ export type FlowViolationResult =
  * Classify a stream-loop outcome against the delivery contract.
  *
  * A turn is in violation when ALL of the following hold:
- *   - The trailing text (after trim) is non-empty.
  *   - No turn-terminator tool fired (e.g. `end_turn`).
- *   - The trailing text isn't a duplicate of content already delivered
+ *   - The model produced either trailing prose or tool calls.
+ *   - Any trailing text isn't a duplicate of content already delivered
  *     through a tool call in the same turn.
  *
  * The third condition handles the legitimate "model wrote text AND called
@@ -79,14 +96,28 @@ export function detectFlowViolation(
   inputs: FlowViolationInputs,
 ): FlowViolationResult {
   const trailing = inputs.trailingText.trim();
-  if (trailing.length === 0) return { violated: false };
   if (inputs.turnTerminated) return { violated: false };
-  if (isDuplicateOfDelivered(trailing, inputs.deliveredTextNorms))
+  const toolCalls = inputs.toolCalls ?? 0;
+  if (trailing.length === 0 && toolCalls === 0) return { violated: false };
+  if (
+    trailing.length > 0 &&
+    isDuplicateOfDelivered(trailing, inputs.deliveredTextNorms)
+  ) {
     return { violated: false };
+  }
+
+  const retryCount = inputs.retryCount ?? (inputs.retried ? 1 : 0);
+  const maxRetries = inputs.maxRetries ?? FLOW_VIOLATION_MAX_RETRIES;
+  const reason =
+    trailing.length > 0
+      ? `trailing prose (${trailing.length} chars)`
+      : `${toolCalls} tool call${toolCalls === 1 ? "" : "s"} with no terminator`;
+
   return {
     violated: true,
     trailing,
-    shouldRetry: !inputs.retried,
-    reminder: FLOW_VIOLATION_REMINDER,
+    reason,
+    shouldRetry: retryCount < maxRetries,
+    reminder: inputs.reminder ?? FLOW_VIOLATION_REMINDER,
   };
 }

package/src/backend/shared/frontends.ts

@@ -0,0 +1,66 @@
+/**
+ * Frontend-list helpers shared across backends.
+ *
+ * Every backend needs "which frontends get an MCP tool server?" at
+ * spawn time; before this helper, claude-sdk, openai-agents, and codex
+ * each carried their own copy of the same normalise-and-filter logic.
+ */
+
+import {
+  isNativeChatId,
+  isTeamsChatId,
+  isDiscordChatId,
+  isTelegramChatId,
+} from "../../util/chat-id.js";
+
+/**
+ * Normalise a config `frontend` value (string or array, possibly
+ * undefined) to the list of messaging frontends — i.e. those that
+ * need an MCP tool server spawned. `terminal` is excluded: it has no
+ * outbound messaging surface (the agent runs to stdout).
+ */
+export function nonTerminalFrontends(
+  frontend: string | readonly string[] | undefined,
+): readonly string[] {
+  if (!frontend) return [];
+  const all = Array.isArray(frontend) ? frontend : [frontend as string];
+  return all.filter((f) => f !== "terminal");
+}
+
+/**
+ * The messaging frontend that owns a chat, inferred from the chat-id
+ * shape (the same convention the gateway uses to route actions):
+ * native `d_*`, teams `teams_chat_*`, discord `discord_*`, telegram
+ * numeric. Returns null for cross-surface contexts — the heartbeat
+ * sentinel, isolated one-shots, terminal sessions.
+ */
+export function frontendForChatId(chatId: string): string | null {
+  if (isNativeChatId(chatId)) return "native";
+  if (isTeamsChatId(chatId)) return "teams";
+  if (isDiscordChatId(chatId)) return "discord";
+  if (isTelegramChatId(chatId)) return "telegram";
+  return null;
+}
+
+/**
+ * Which frontends' tool servers a chat's turn should register.
+ *
+ * A chat owned by one messaging frontend gets exactly that frontend's
+ * tools: a native-app conversation must see `native-tools`, not a
+ * `telegram-tools` server that happens to share the daemon — the
+ * model reads surface identity out of tool names, and stray
+ * `mcp__telegram-tools__*` entries in a native chat are both confusing
+ * UI and an invitation to deliver the reply to the wrong surface.
+ *
+ * Chats with no owning frontend (heartbeat sentinel, one-shot cron,
+ * terminal sessions) keep every configured messaging frontend: those
+ * contexts legitimately reach across surfaces via explicit chat_id.
+ */
+export function frontendsForChat(
+  chatId: string,
+  configured: readonly string[],
+): readonly string[] {
+  const owner = frontendForChatId(chatId);
+  if (owner && configured.includes(owner)) return [owner];
+  return configured;
+}

package/src/backend/shared/handle-retry.ts

@@ -0,0 +1,244 @@
+/**
+ * Shared error-recovery dispatcher.
+ *
+ * Every backend's handler ends its `try { ... } catch (err) { ... }`
+ * block with the same `classifyRetry` decision tree:
+ *
+ *   1. `reset_and_retry` (session_expired / context_length) — reset
+ *      the session and recurse.
+ *   2. `fallback_model` (retryable + fallback configured) — recurse
+ *      with the fallback model threaded through the retry's params.
+ *   3. `propagate` — let the caller throw.
+ *
+ * The four backends each duplicated ~30 lines of this — same logic,
+ * different log-line prefix. Centralising it here means a future
+ * tweak (e.g. adding a third decision kind, changing the
+ * transient-model-flip semantics) lands once instead of four times,
+ * and the per-backend handlers reduce to a single function call.
+ *
+ * Caveat: this is the GENERIC recovery path. Backend-specific
+ * fallbacks (e.g. `maybeFallbackForChatGptMismatch` in codex) still
+ * live in the backend handler — they're a different decision and run
+ * BEFORE this one.
+ */
+
+import type { QueryParams, QueryResult } from "./handler-types.js";
+import { classify, type TalonError } from "../../core/errors.js";
+import { logWarn } from "../../util/log.js";
+import { incrementCounter } from "../../util/metrics.js";
+import { resetSession } from "../../storage/sessions.js";
+import { classifyRetry } from "./model-retry.js";
+import type { AgentEvent } from "../../core/agent-runtime/events.js";
+
+/** Inputs for `applyRetryDecision`. */
+export interface ApplyRetryDecisionInputs {
+  /** The error caught by the backend's handler. */
+  err: unknown;
+  /** Active chat id (for log lines + session reset). */
+  chatId: string;
+  /** Model that was active when the error fired. */
+  activeModel: string;
+  /** True when the current call is already a retry (short-circuits). */
+  retried: boolean;
+  /** Original `handleMessage` params — used for the recursive retry. */
+  params: QueryParams;
+  /**
+   * Backend's recursive entry — passed as a callback so we don't have
+   * to depend on each backend module. Each backend calls this with its
+   * own `handleMessage`.
+   */
+  recurseWithRetried: (params: QueryParams) => Promise<QueryResult>;
+  /**
+   * Backend label for log-line prefixes (`"Kilo"`, `"OpenCode"`,
+   * `"Codex"`, `"Claude"`). When omitted or empty the prefix is
+   * dropped — matches the claude-sdk historical behaviour.
+   */
+  backendLabel?: string;
+  /**
+   * Word used in the reset_and_retry log line. Codex resets a "thread"
+   * while the remote-server / claude backends reset a "session"; the
+   * helper takes whatever the backend prefers.
+   */
+  resetNoun?: "session" | "thread";
+}
+
+/** Outcome — undefined means the caller should propagate the classified error. */
+export interface ApplyRetryDecisionResult {
+  /**
+   * Set when the helper retried — caller `return retry`s this value
+   * directly from its handler.
+   */
+  retry?: QueryResult;
+  /**
+   * Set when the helper decided NOT to retry — caller should
+   * `throw classified` to propagate.
+   */
+  classified: TalonError;
+}
+
+/**
+ * Run the shared retry-decision logic.
+ *
+ * Side effects (when a retry fires):
+ *   - `incrementCounter('errors.<reason>')` exactly once per call.
+ *   - `resetSession(chatId)` before recursion.
+ *   - For `fallback_model`: the fallback model id is spread into the
+ *     recursion's params (`params.model` outranks chat settings).
+ *
+ * When the decision is `propagate`, returns `{classified}` only — the
+ * caller throws.
+ */
+export async function applyRetryDecision(
+  inputs: ApplyRetryDecisionInputs,
+): Promise<ApplyRetryDecisionResult> {
+  const {
+    err,
+    chatId,
+    activeModel,
+    retried,
+    params,
+    recurseWithRetried,
+    backendLabel,
+    resetNoun = "session",
+  } = inputs;
+
+  const classified = classify(err);
+  incrementCounter(`errors.${classified.reason ?? "unknown"}`);
+
+  const decision = classifyRetry({
+    error: classified,
+    activeModel,
+    retried,
+  });
+
+  const prefix = backendLabel ? `${backendLabel} ` : "";
+
+  if (decision.kind === "reset_and_retry") {
+    logWarn(
+      "agent",
+      `[${chatId}] ${prefix}${decision.reason}, resetting ${resetNoun} and retrying`,
+    );
+    resetSession(chatId);
+    return { retry: await recurseWithRetried(params), classified };
+  }
+
+  if (decision.kind === "fallback_model") {
+    logWarn(
+      "agent",
+      `[${chatId}] ${classified.reason}, falling back to ${decision.fallbackModelId}`,
+    );
+    resetSession(chatId);
+    return {
+      retry: await recurseWithRetried({
+        ...params,
+        model: decision.fallbackModelId,
+      }),
+      classified,
+    };
+  }
+
+  // `propagate` — caller throws `classified`.
+  return { classified };
+}
+
+// ── Generator-shaped variant ────────────────────────────────────────────────
+
+/** Inputs for `applyRetryDecisionStream`. */
+export interface StreamRetryInputs {
+  /** Error caught inside the caller's generator. */
+  err: unknown;
+  /** Active chat id (for log lines + session reset). */
+  chatId: string;
+  /** Model that was active when the error fired. */
+  activeModel: string;
+  /** True when the current call is already a retry (short-circuits). */
+  retried: boolean;
+  /**
+   * Builds the recursive event stream. Called once when the helper
+   * decides to retry — yielded via `yield*` so the caller's generator
+   * transparently delegates to it. For `fallback_model` decisions the
+   * fallback model id is passed through; the builder must thread it
+   * into the retry's params (`params.model` outranks chat settings,
+   * so a transient `setChatModel` flip would be a silent no-op).
+   */
+  buildRetryStream: (fallbackModelId?: string) => AsyncIterable<AgentEvent>;
+  /** Backend label for log-line prefixes (`"Kilo"`, `"Codex"` …). */
+  backendLabel?: string;
+  /**
+   * Word used in the reset_and_retry log line. Codex resets a "thread"
+   * while remote-server / claude backends reset a "session".
+   */
+  resetNoun?: "session" | "thread";
+}
+
+/** Outcome `applyRetryDecisionStream` returns from its generator. */
+export interface StreamRetryResult {
+  /**
+   * True when the helper recursed (the recursive stream was already
+   * yielded into the caller). Caller may finish its generator.
+   */
+  retried: boolean;
+  /**
+   * The classified error. When `retried` is false the caller should
+   * yield an `error` event derived from this and return.
+   */
+  classified: TalonError;
+}
+
+/**
+ * Generator-shaped equivalent of `applyRetryDecision`. The caller
+ * uses `yield* applyRetryDecisionStream({...})` so the recursive
+ * retry's events flow into the outer stream transparently. Side
+ * effects (counter increment, session reset, fallback model threaded
+ * through the retry) match the callback-shaped helper exactly.
+ *
+ * The terminating value (`AsyncGenerator` 2nd type param) tells the
+ * caller whether to emit a final `error` event or just return.
+ */
+export async function* applyRetryDecisionStream(
+  inputs: StreamRetryInputs,
+): AsyncGenerator<AgentEvent, StreamRetryResult, void> {
+  const {
+    err,
+    chatId,
+    activeModel,
+    retried,
+    buildRetryStream,
+    backendLabel,
+    resetNoun = "session",
+  } = inputs;
+
+  const classified = classify(err);
+  incrementCounter(`errors.${classified.reason ?? "unknown"}`);
+
+  const decision = classifyRetry({
+    error: classified,
+    activeModel,
+    retried,
+  });
+
+  const prefix = backendLabel ? `${backendLabel} ` : "";
+
+  if (decision.kind === "reset_and_retry") {
+    logWarn(
+      "agent",
+      `[${chatId}] ${prefix}${decision.reason}, resetting ${resetNoun} and retrying`,
+    );
+    resetSession(chatId);
+    yield* buildRetryStream();
+    return { retried: true, classified };
+  }
+
+  if (decision.kind === "fallback_model") {
+    logWarn(
+      "agent",
+      `[${chatId}] ${classified.reason}, falling back to ${decision.fallbackModelId}`,
+    );
+    resetSession(chatId);
+    yield* buildRetryStream(decision.fallbackModelId);
+    return { retried: true, classified };
+  }
+
+  // `propagate` — caller should yield an `error` event and return.
+  return { retried: false, classified };
+}