talon-agent 3.34.0 → 3.34.1

package/src/backend/openai-agents/handler/message.ts

@@ -2,26 +2,19 @@
  * OpenAI Agents backend message handler.
  *
  * Drives a single-agent run on top of `@openai/agents`'s `run()` in streaming
- * mode. Shares the non-SDK-specific primitives with the other backends via
- * `../../shared/`. OpenAI-Agents-specific bits: building the `Agent` with the
- * per-chat MCP bundle, iterating the `StreamedRunResult` (see `events.ts`),
- * `.cancel()` on terminator, and the trailing-prose flow-violation retry.
+ * mode. OpenAI-Agents-specific bits: building the `Agent` with the per-chat
+ * MCP bundle, iterating the `StreamedRunResult` (see `events.ts`), and
+ * `.cancel()` on terminator. The post-stream phases — accounting, the
+ * trailing-prose flow-violation retry, the result — are the shared ones in
+ * `backend/shared/turn-phases.ts`.
  */
 
 import { Agent, run } from "@openai/agents";
 import type { QueryParams, QueryResult } from "../../shared/handler-types.js";
-import {
-  getSession,
-  incrementTurns,
-  recordUsage,
-  setSessionName,
-  resetSession,
-} from "../../../storage/sessions.js";
+import { getSession, incrementTurns } from "../../../storage/sessions.js";
 import { getChatSettings } from "../../../storage/chat-settings.js";
-import { classify } from "../../../core/errors.js";
 import { log, logError, logWarn } from "../../../util/log.js";
 import { traceMessage } from "../../../util/trace.js";
-import { incrementCounter } from "../../../storage/metrics.js";
 
 import {
   createStreamState,
@@ -29,21 +22,18 @@ import {
   finalizeResponseText,
   formatUserPrompt,
   prepareSystemPrompt,
-  extractSessionName,
-  classifyRetry,
-  summarizeUsage,
   routeDelivery,
   buildFirstTurnReminder,
   buildFlowViolationReminder,
-  recordTurnMetrics,
-  recordFailedTurnAccounting,
-  recordFlowViolation,
+  applyRetryDecision,
   registerTurnInterrupt,
+  accountTurn,
+  accountFailedTurn,
+  nameSessionFromFirstMessage,
+  enforceTrailingProse,
+  finishCallbackTurn,
+  type StreamState,
 } from "../../shared/index.js";
-import {
-  detectFlowViolation,
-  FLOW_VIOLATION_MAX_RETRIES,
-} from "../../shared/flow-violation.js";
 
 import {
   buildOpenAiAgentsSuffix,
@@ -64,32 +54,232 @@ import { handleRunItem } from "./events.js";
 const errMsg = (e: unknown): string =>
   e instanceof Error ? e.message : String(e);
 
+/** The expected close on `end_turn` / a user interrupt: abort after the terminator. */
+const isTerminatorAbort = (state: StreamState, err: unknown): boolean =>
+  state.turnTerminated &&
+  (errMsg(err) === "AbortError" || /abort/i.test(errMsg(err)));
+
+type McpBundle = Awaited<ReturnType<typeof getOrCreateBundle>>;
+
+type RunUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  inputTokensDetails?: { cachedTokens?: number };
+};
+
 /**
  * Read the aggregated usage off a run's state. `_context` is named with
  * an underscore in the SDK type but is structurally public; the SDK
  * updates it as each model call in the agentic loop completes, so this
  * is valid both mid-stream (live stats) and after `stream.completed`.
  */
-function readRunUsage(runState: unknown):
-  | {
-      inputTokens?: number;
-      outputTokens?: number;
-      inputTokensDetails?: { cachedTokens?: number };
+function readRunUsage(runState: unknown): RunUsage | undefined {
+  return (runState as { _context?: { usage?: RunUsage } })._context?.usage;
+}
+
+function recordRunUsage(state: StreamState, usage: RunUsage): void {
+  recordTokens(state, {
+    inputTokens: usage.inputTokens ?? 0,
+    outputTokens: usage.outputTokens ?? 0,
+    cacheRead: usage.inputTokensDetails?.cachedTokens ?? 0,
+    cacheWrite: 0, // OpenAI Responses API doesn't report cache writes.
+  });
+}
+
+// ── Setup ───────────────────────────────────────────────────────────────────
+
+/**
+ * First-turn nudge — turn 0 is where flow violations cluster, and one
+ * line in the user message costs nothing on later turns and never
+ * touches the cached prefix.
+ */
+function buildTurnPrompt(
+  params: QueryParams,
+  frontend: string | undefined,
+  previousTurns: number,
+  isRetry: boolean,
+): string {
+  let prompt = formatUserPrompt({
+    text: params.text,
+    senderName: params.senderName ?? "user",
+    senderHandle: params.senderHandle,
+    isGroup: params.isGroup,
+    messageId: params.messageId,
+  });
+  if (frontend && previousTurns === 0 && !isRetry) {
+    prompt += `\n\n${buildFirstTurnReminder(frontend)}`;
+  }
+  return prompt;
+}
+
+/**
+ * Acquire the per-chat MCP bundle. Persistent across turns — built on
+ * first use, kept alive until `releaseBundle(chatId)`. Avoids the
+ * ~15-subprocess re-spawn the original per-turn build caused.
+ */
+async function acquireMcpBundle(
+  chatId: string,
+  frontends: readonly string[],
+): Promise<McpBundle> {
+  const state = getState();
+  const config = state.config;
+  if (!config) throw new Error("OpenAI Agents backend not initialized");
+  try {
+    return await getOrCreateBundle({
+      chatId,
+      bridgeUrl: `http://127.0.0.1:${state.gatewayPortFn()}`,
+      frontends,
+      braveApiKey: config.braveApiKey,
+      toolExclusions: config,
+    });
+  } catch (err) {
+    logError(
+      "agent",
+      `[${chatId}] OpenAI Agents: MCP setup failed: ${errMsg(err)}`,
+    );
+    throw err;
+  }
+}
+
+/**
+ * Diagnostic — enumerate every tool the model will see this turn.
+ * Critical for tracking down "model never calls end_turn": if it
+ * isn't in this list, the problem is MCP registration, not the model.
+ */
+async function logRegisteredTools(
+  chatId: string,
+  mcpBundle: McpBundle,
+): Promise<void> {
+  try {
+    const builtinNames = OPENAI_AGENTS_BUILTIN_TOOLS.map((t) => t.name);
+    const mcpToolLists = await Promise.all(
+      mcpBundle.servers.map((s) =>
+        s
+          .listTools()
+          .then((ts: Array<{ name?: string }>) => ts.map((t) => t.name ?? "?"))
+          .catch(() => [] as string[]),
+      ),
+    );
+    const mcpNames = mcpToolLists.flat();
+    log(
+      "agent",
+      `[${chatId}] tools registered: builtins=[${builtinNames.join(", ")}] mcp=[${mcpNames.join(", ")}]`,
+    );
+  } catch {
+    /* best-effort diagnostic */
+  }
+}
+
+// ── Stream loop ─────────────────────────────────────────────────────────────
+
+async function driveAgentRun(inputs: {
+  chatId: string;
+  prompt: string;
+  systemPrompt: string;
+  activeModel: string;
+  mcpBundle: McpBundle;
+  abortController: AbortController;
+  state: StreamState;
+  onToolUse: QueryParams["onToolUse"];
+}): Promise<void> {
+  const { chatId, mcpBundle, abortController, state } = inputs;
+  await logRegisteredTools(chatId, mcpBundle);
+
+  // Build the agent. `tools` carries the filesystem + shell built-ins
+  // for parity with the Claude SDK backend; `mcpServers` carries the
+  // Talon frontend + plugin MCP servers. Single agent, no handoffs.
+  // `mcpConfig.includeServerInToolNames` namespaces MCP tools as
+  // `mcp_<serverName>__<toolName>` so colliding names across plugins
+  // both stay available. Built-in tools stay unprefixed.
+  const agent = new Agent({
+    name: OPENAI_AGENTS_AGENT_NAME,
+    instructions: inputs.systemPrompt,
+    model: inputs.activeModel,
+    tools: [...OPENAI_AGENTS_BUILTIN_TOOLS],
+    mcpServers: mcpBundle.servers,
+    mcpConfig: { includeServerInToolNames: true },
+  });
+
+  // Per-chat MemorySession so the SDK preserves the full multi-turn
+  // record (model outputs, tool calls + results, reasoning items).
+  // Without this, every turn starts blind to prior context.
+  const stream = await run(agent, inputs.prompt, {
+    stream: true,
+    maxTurns: OPENAI_AGENTS_MAX_TURNS,
+    signal: abortController.signal,
+    session: getOrCreateSession(chatId),
+  });
+
+  // The Agents SDK aggregates usage on the run context as each model
+  // call completes — sample it (throttled) so the live-turn overlay
+  // tracks the agentic loop instead of jumping from 0 to final.
+  let lastLiveUsagePushAt = 0;
+  const pushRunUsageLive = (): void => {
+    const now = Date.now();
+    if (now - lastLiveUsagePushAt < 1000) return;
+    lastLiveUsagePushAt = now;
+    const u = readRunUsage(stream.state);
+    if (u) recordRunUsage(state, u);
+  };
+
+  const seenToolCallIds = new Set<string>();
+  for await (const event of stream) {
+    if (abortController.signal.aborted && !state.turnTerminated) break;
+
+    if (event.type === "run_item_stream_event") {
+      handleRunItem(event, {
+        state,
+        seenToolCallIds,
+        onToolUse: inputs.onToolUse,
+        chatId,
+      });
+      pushRunUsageLive();
     }
-  | undefined {
-  return (
-    runState as {
-      _context?: {
-        usage?: {
-          inputTokens?: number;
-          outputTokens?: number;
-          inputTokensDetails?: { cachedTokens?: number };
-        };
-      };
+    // `raw_model_stream_event` and `agent_updated_stream_event`
+    // events are intentionally not surfaced — token-by-token streaming
+    // would expose private chain-of-thought; the final-message event
+    // is enough.
+
+    // Terminator-driven abort. The SDK emits TWO events for each tool
+    // call: `tool_called` (RPC about to run) and `tool_output` (RPC
+    // completed; message reached the frontend). We must NOT abort on
+    // `tool_called` — that cancels the in-flight RPC and the message
+    // never ships. Aborting on `tool_output` after we've flagged the
+    // turn terminated means delivery happened AND we skip the SDK's
+    // wrap-up round-trip (otherwise 5–10s of lingering typing).
+    if (
+      state.turnTerminated &&
+      event.type === "run_item_stream_event" &&
+      (event as { name?: string }).name === "tool_output" &&
+      !abortController.signal.aborted
+    ) {
+      log(
+        "agent",
+        `[${chatId}] terminator tool result received — aborting wrap-up`,
+      );
+      try {
+        abortController.abort();
+      } catch (err) {
+        logWarn("agent", `[${chatId}] abort failed: ${errMsg(err)}`);
+      }
     }
-  )._context?.usage;
+  }
+
+  // Await the final completion so usage + final state are populated.
+  // Safe to call even when we aborted via the terminator (resolves to
+  // the partial state).
+  await stream.completed.catch(() => {
+    /* swallow — aborted-by-terminator path */
+  });
+
+  // Token usage from the underlying RunResult. The SDK aggregates
+  // `usage` across all turns in the loop.
+  const usage = readRunUsage(stream.state);
+  if (usage) recordRunUsage(state, usage);
 }
 
+// ── Main handler ────────────────────────────────────────────────────────────
+
 export async function handleMessage(
   params: QueryParams,
   _retried = false,
@@ -101,19 +291,11 @@ export async function handleMessage(
     throw new Error("OpenAI Agents backend not initialized");
   }
 
-  const {
-    chatId,
-    text,
-    senderName,
-    senderHandle,
-    isGroup,
-    messageId,
-    onTextBlock,
-    onToolUse,
-  } = params;
+  const { chatId, text, senderName, isGroup, onTextBlock } = params;
   const t0 = Date.now();
   const session = getSession(chatId);
   const previousTurns = session.turns;
+  const isRetry = _retried || _flowRetries > 0;
 
   // Resolve the active model — chat-settings → config → default.
   const chatSettings = getChatSettings(chatId);
@@ -140,49 +322,16 @@ export async function handleMessage(
     chatId,
     sessionEpoch: session.createdAt,
   });
-
-  let prompt = formatUserPrompt({
-    text,
-    senderName: senderName ?? "user",
-    senderHandle,
-    isGroup,
-    messageId,
-  });
-  // First-turn nudge — turn 0 is where flow violations cluster, and one
-  // line in the user message costs nothing on later turns and never
-  // touches the cached prefix.
-  if (frontend && previousTurns === 0 && !_retried && _flowRetries === 0) {
-    prompt += `\n\n${buildFirstTurnReminder(frontend)}`;
-  }
+  const prompt = buildTurnPrompt(params, frontend, previousTurns, isRetry);
 
   log("agent", `[${chatId}] <- (${text.length} chars)`);
   traceMessage(chatId, "in", text, { senderName, isGroup });
 
-  // Acquire the per-chat MCP bundle. Persistent across turns — built on
-  // first use, kept alive until `releaseBundle(chatId)`. Avoids the
-  // ~15-subprocess re-spawn the original per-turn build caused.
-  const bridgeUrl = `http://127.0.0.1:${state.gatewayPortFn()}`;
-  let mcpBundle: Awaited<ReturnType<typeof getOrCreateBundle>>;
-  try {
-    mcpBundle = await getOrCreateBundle({
-      chatId,
-      bridgeUrl,
-      frontends,
-      braveApiKey: config.braveApiKey,
-      toolExclusions: config,
-    });
-  } catch (err) {
-    logError(
-      "agent",
-      `[${chatId}] OpenAI Agents: MCP setup failed: ${errMsg(err)}`,
-    );
-    throw err;
-  }
+  const mcpBundle = await acquireMcpBundle(chatId, frontends);
 
   // Bind the stream state to the chat so token mutators mirror counts
   // into the live-turn overlay — /status updates while the turn runs.
   const streamState = createStreamState(chatId);
-  const seenToolCallIds = new Set<string>();
   const abortController = new AbortController();
   activeAborts.set(chatId, abortController);
   // A user interrupt is a synthetic turn terminator: marking the flag
@@ -199,201 +348,47 @@ export async function handleMessage(
 
   try {
     const turnStart = Date.now();
-
-    // Build the agent. `tools` carries the filesystem + shell built-ins
-    // for parity with the Claude SDK backend; `mcpServers` carries the
-    // Talon frontend + plugin MCP servers. Single agent, no handoffs.
-    // `mcpConfig.includeServerInToolNames` namespaces MCP tools as
-    // `mcp_<serverName>__<toolName>` so colliding names across plugins
-    // both stay available. Built-in tools stay unprefixed.
-
-    // Diagnostic — enumerate every tool the model will see this turn.
-    // Critical for tracking down "model never calls end_turn": if it
-    // isn't in this list, the problem is MCP registration, not the model.
-    try {
-      const builtinNames = OPENAI_AGENTS_BUILTIN_TOOLS.map((t) => t.name);
-      const mcpToolLists = await Promise.all(
-        mcpBundle.servers.map((s) =>
-          s
-            .listTools()
-            .then((ts: Array<{ name?: string }>) =>
-              ts.map((t) => t.name ?? "?"),
-            )
-            .catch(() => [] as string[]),
-        ),
-      );
-      const mcpNames = mcpToolLists.flat();
-      log(
-        "agent",
-        `[${chatId}] tools registered: builtins=[${builtinNames.join(", ")}] mcp=[${mcpNames.join(", ")}]`,
-      );
-    } catch {
-      /* best-effort diagnostic */
-    }
-
-    const agent = new Agent({
-      name: OPENAI_AGENTS_AGENT_NAME,
-      instructions: systemPrompt,
-      model: activeModel,
-      tools: [...OPENAI_AGENTS_BUILTIN_TOOLS],
-      mcpServers: mcpBundle.servers,
-      mcpConfig: { includeServerInToolNames: true },
-    });
-
-    // Per-chat MemorySession so the SDK preserves the full multi-turn
-    // record (model outputs, tool calls + results, reasoning items).
-    // Without this, every turn starts blind to prior context.
-    const stream = await run(agent, prompt, {
-      stream: true,
-      maxTurns: OPENAI_AGENTS_MAX_TURNS,
-      signal: abortController.signal,
-      session: getOrCreateSession(chatId),
-    });
-
-    // The Agents SDK aggregates usage on the run context as each model
-    // call completes — sample it (throttled) so the live-turn overlay
-    // tracks the agentic loop instead of jumping from 0 to final.
-    let lastLiveUsagePushAt = 0;
-    const pushRunUsageLive = (): void => {
-      const now = Date.now();
-      if (now - lastLiveUsagePushAt < 1000) return;
-      lastLiveUsagePushAt = now;
-      const u = readRunUsage(stream.state);
-      if (!u) return;
-      recordTokens(streamState, {
-        inputTokens: u.inputTokens ?? 0,
-        outputTokens: u.outputTokens ?? 0,
-        cacheRead: u.inputTokensDetails?.cachedTokens ?? 0,
-        cacheWrite: 0, // OpenAI Responses API doesn't report cache writes.
-      });
-    };
-
-    for await (const event of stream) {
-      if (abortController.signal.aborted && !streamState.turnTerminated) break;
-
-      if (event.type === "run_item_stream_event") {
-        handleRunItem(event, {
-          state: streamState,
-          seenToolCallIds,
-          onToolUse,
-          chatId,
-        });
-        pushRunUsageLive();
-      }
-      // `raw_model_stream_event` and `agent_updated_stream_event`
-      // events are intentionally not surfaced — token-by-token streaming
-      // would expose private chain-of-thought; the final-message event
-      // is enough.
-
-      // Terminator-driven abort. The SDK emits TWO events for each tool
-      // call: `tool_called` (RPC about to run) and `tool_output` (RPC
-      // completed; message reached the frontend). We must NOT abort on
-      // `tool_called` — that cancels the in-flight RPC and the message
-      // never ships. Aborting on `tool_output` after we've flagged the
-      // turn terminated means delivery happened AND we skip the SDK's
-      // wrap-up round-trip (otherwise 5–10s of lingering typing).
-      if (
-        streamState.turnTerminated &&
-        event.type === "run_item_stream_event" &&
-        (event as { name?: string }).name === "tool_output" &&
-        !abortController.signal.aborted
-      ) {
-        log(
-          "agent",
-          `[${chatId}] terminator tool result received — aborting wrap-up`,
-        );
-        try {
-          abortController.abort();
-        } catch (err) {
-          logWarn("agent", `[${chatId}] abort failed: ${errMsg(err)}`);
-        }
-      }
-    }
-
-    // Await the final completion so usage + final state are populated.
-    // Safe to call even when we aborted via the terminator (resolves to
-    // the partial state).
-    await stream.completed.catch(() => {
-      /* swallow — aborted-by-terminator path */
+    await driveAgentRun({
+      chatId,
+      prompt,
+      systemPrompt,
+      activeModel,
+      mcpBundle,
+      abortController,
+      state: streamState,
+      onToolUse: params.onToolUse,
     });
-
-    // Token usage from the underlying RunResult. The SDK aggregates
-    // `usage` across all turns in the loop.
-    const usage = readRunUsage(stream.state);
-    if (usage) {
-      recordTokens(streamState, {
-        inputTokens: usage.inputTokens ?? 0,
-        outputTokens: usage.outputTokens ?? 0,
-        cacheRead: usage.inputTokensDetails?.cachedTokens ?? 0,
-        cacheWrite: 0, // OpenAI Responses API doesn't report cache writes.
-      });
-    }
-
     turnMs = Date.now() - turnStart;
   } catch (err) {
-    if (
-      streamState.turnTerminated &&
-      (errMsg(err) === "AbortError" || /abort/i.test(errMsg(err)))
-    ) {
-      // Swallow — turn completed via terminator tool.
-    } else {
-      const classified = classify(err);
-      incrementCounter(`errors.${classified.reason ?? "unknown"}`);
-
-      const decision = classifyRetry({
-        error: classified,
+    // Swallow the terminator abort — the turn completed via a delivery tool.
+    if (!isTerminatorAbort(streamState, err)) {
+      // MCP bundle is retained across a retry — subprocesses are
+      // stateless wrt the model conversation. See `mcp-pool.ts`.
+      const outcome = await applyRetryDecision({
+        err,
+        chatId,
         activeModel,
         retried: _retried,
+        params,
+        recurseWithRetried: (p) => handleMessage(p, true),
+        backendLabel: "OpenAI Agents",
       });
-
-      if (decision.kind === "reset_and_retry") {
-        logWarn(
-          "agent",
-          `[${chatId}] OpenAI Agents ${decision.reason}, resetting session and retrying`,
-        );
-        resetSession(chatId);
-        // MCP bundle is retained across the retry — subprocesses are
-        // stateless wrt the model conversation. See `mcp-pool.ts`.
-        return handleMessage(params, true);
-      }
-
-      if (decision.kind === "fallback_model") {
-        logWarn(
-          "agent",
-          `[${chatId}] ${classified.reason}, falling back to ${decision.fallbackModelId}`,
-        );
-        resetSession(chatId);
-        return await handleMessage(
-          { ...params, model: decision.fallbackModelId },
-          true,
-        );
-      }
+      if (outcome.retry) return outcome.retry;
 
       // Terminal failure — account for whatever the turn consumed before
-      // dying and drop the live overlay (the retry branches above re-enter
-      // handleMessage, which does its own accounting).
-      recordFailedTurnAccounting({
+      // dying (the retry above did its own accounting).
+      accountFailedTurn({
         backend: "openai-agents",
         chatId,
+        state: streamState,
         durationMs: Date.now() - t0,
-        toolCalls: streamState.toolCalls,
-        apiCalls: streamState.numApiCalls,
         model: activeModel,
-        usage: {
-          inputTokens: streamState.sdkInputTokens,
-          outputTokens: streamState.sdkOutputTokens,
-          cacheRead: streamState.sdkCacheRead,
-          cacheWrite: streamState.sdkCacheWrite,
-        },
-        contextTokens: streamState.contextTokens,
-        contextWindow: streamState.contextWindow,
       });
-
       logError(
         "agent",
-        `[${chatId}] OpenAI Agents error: ${classified.message}`,
+        `[${chatId}] OpenAI Agents error: ${outcome.classified.message}`,
       );
-      throw classified;
+      throw outcome.classified;
     }
   } finally {
     unregisterInterrupt();
@@ -409,86 +404,41 @@ export async function handleMessage(
 
   const responseText = finalizeResponseText(streamState);
   const durationMs = Date.now() - t0;
-  recordTurnMetrics({
+  accountTurn({
     chatId,
     backend: "openai-agents",
-    durationMs,
-    toolCalls: streamState.toolCalls,
-    apiCalls: streamState.numApiCalls,
-    usage: {
-      inputTokens: streamState.sdkInputTokens,
-      outputTokens: streamState.sdkOutputTokens,
-      cacheRead: streamState.sdkCacheRead,
-      cacheWrite: streamState.sdkCacheWrite,
-    },
-  });
-
-  recordUsage(chatId, {
-    inputTokens: streamState.sdkInputTokens,
-    outputTokens: streamState.sdkOutputTokens,
-    cacheRead: streamState.sdkCacheRead,
-    cacheWrite: streamState.sdkCacheWrite,
+    state: streamState,
     durationMs,
     model: activeModel,
   });
 
-  // ── Trailing-prose contract + flow-violation retry ──────────────────────
   // Replies MUST go through `end_turn` (canonical) or `send` (mid-turn).
-  // If the model wrote prose without calling either, the user would see
-  // nothing — re-prompt once with a synthetic reminder. A second violation
-  // accepts a silent drop. Only enforced when delivery tools are registered
-  // (non-empty mcpBundle.servers). `incrementTurns` is deferred until AFTER
-  // the check so the retry path doesn't double-count.
+  // Only enforced when delivery tools are registered (non-empty
+  // mcpBundle.servers). `incrementTurns` is deferred until AFTER the
+  // check so the retry path doesn't double-count.
   const violation =
     mcpBundle.servers.length > 0
-      ? detectFlowViolation({
-          trailingText: streamState.lastTrailingText,
-          turnTerminated: streamState.turnTerminated,
-          deliveredTextNorms: streamState.deliveredTextNorms,
-          toolCalls: streamState.toolCalls,
-          retried: _flowRetries > 0,
-          retryCount: _flowRetries,
-          maxRetries: FLOW_VIOLATION_MAX_RETRIES,
+      ? enforceTrailingProse({
+          chatId,
+          state: streamState,
+          flowRetries: _flowRetries,
           ...(frontend
             ? { reminder: buildFlowViolationReminder(frontend) }
             : {}),
         })
-      : ({ violated: false } as const);
-
-  if (violation.violated) {
-    recordFlowViolation(
-      chatId,
-      violation.shouldRetry ? "retried" : "cap_exhausted",
-    );
-    log(
-      "agent",
-      `[${chatId}] flow violation: trailing prose (${violation.trailing.length} chars) without end_turn/send. ${
-        violation.shouldRetry
-          ? "Re-prompting with reminder."
-          : "Already retried — accepting silent drop."
-      }`,
+      : undefined;
+  if (violation?.violated && violation.shouldRetry) {
+    // Recursive call owns the `incrementTurns` for this user message.
+    return handleMessage(
+      { ...params, text: violation.reminder },
+      _retried,
+      _flowRetries + 1,
     );
-
-    if (violation.shouldRetry) {
-      // Recursive call owns the `incrementTurns` for this user message.
-      return handleMessage(
-        { ...params, text: violation.reminder },
-        _retried,
-        _flowRetries + 1,
-      );
-    }
   }
 
   // Reached the non-retry path — this turn counts as one user-visible turn.
   incrementTurns(chatId);
-
-  // Set a descriptive session name from the user's *first* message.
-  // Guarded by `!_retried` so the reminder doesn't get captured as the
-  // session name when the retry recurses with `params.text = reminder`.
-  if (previousTurns === 0 && !_retried && _flowRetries === 0) {
-    const name = extractSessionName(text);
-    if (name) setSessionName(chatId, name);
-  }
+  nameSessionFromFirstMessage({ chatId, text, previousTurns, isRetry });
 
   // ── Delivery — strict tool-only ──────────────────────────────────────────
   // Replies must reach the user via a delivery tool. Trailing prose is
@@ -507,37 +457,13 @@ export async function handleMessage(
       })
     : { route: "silent" as const, chars: 0 };
 
-  log(
-    "agent",
-    `[${chatId}] delivery: ${delivery.route} (${delivery.chars} chars)`,
-  );
-
-  log(
-    "agent",
-    `[${chatId}] -> (${summarizeUsage(
-      {
-        inputTokens: streamState.sdkInputTokens,
-        outputTokens: streamState.sdkOutputTokens,
-        cacheRead: streamState.sdkCacheRead,
-        cacheWrite: streamState.sdkCacheWrite,
-      },
-      { durationMs, toolCalls: streamState.toolCalls },
-    )} terminator=${streamState.turnTerminated ? "yes" : "no"} ` +
-      `delivered=${streamState.deliveredTextNorms.length} ` +
-      `respLen=${responseText.length} ` +
-      `setup=${setupMs}ms turn=${turnMs}ms)`,
-  );
-  traceMessage(chatId, "out", responseText, {
+  return finishCallbackTurn({
+    chatId,
+    state: streamState,
+    responseText,
     durationMs,
-    toolCalls: streamState.toolCalls,
+    setupMs,
+    turnMs,
+    delivery,
   });
-
-  return {
-    text: responseText,
-    durationMs,
-    inputTokens: streamState.sdkInputTokens,
-    outputTokens: streamState.sdkOutputTokens,
-    cacheRead: streamState.sdkCacheRead,
-    cacheWrite: streamState.sdkCacheWrite,
-  };
 }