talon-agent 1.9.2 → 1.10.1

package/src/backend/claude-sdk/handler.ts

@@ -24,6 +24,7 @@ import { log, logError, logWarn } from "../../util/log.js";
 import { traceMessage } from "../../util/trace.js";
 import { incrementCounter, recordHistogram } from "../../util/metrics.js";
 import { formatFullDatetime } from "../../util/time.js";
+import { isTurnTerminator, stripMcpPrefix } from "../../core/tools/index.js";
 
 import type { Query } from "@anthropic-ai/claude-agent-sdk";
 import type { QueryParams, QueryResult } from "../../core/types.js";
@@ -38,6 +39,8 @@ import {
   processStreamDelta,
   processAssistantMessage,
   processResultMessage,
+  normalizeForDedupe,
+  isDuplicateOfDelivered,
 } from "./stream.js";
 
 // ── Active query store ──────────────────────────────────────────────────────
@@ -92,6 +95,35 @@ export async function handleMessage(
   activeQueries.set(chatId, qi);
   const state = createStreamState();
 
+  // Capture text args from delivery tools (`end_turn`, `send(type="text")`)
+  // so the end-of-turn trailing-text fallback can dedupe against content
+  // already delivered. Without this, a model that writes prose AND calls a
+  // delivery tool with similar text would surface twice in the chat.
+  //
+  // Tool names arrive MCP-prefixed (e.g. `mcp__telegram-tools__end_turn`)
+  // when routed through MCP — strip the prefix so equality checks match
+  // the registry's bare names.
+  const captureDeliveredText = (
+    toolName: string,
+    input: Record<string, unknown>,
+  ): void => {
+    const bareName = stripMcpPrefix(toolName);
+    let deliveredText: string | undefined;
+    if (bareName === "end_turn" && typeof input.text === "string") {
+      deliveredText = input.text;
+    } else if (
+      bareName === "send" &&
+      input.type === "text" &&
+      typeof input.text === "string"
+    ) {
+      deliveredText = input.text;
+    }
+    if (deliveredText) {
+      const norm = normalizeForDedupe(deliveredText);
+      if (norm) state.deliveredTextNorms.push(norm);
+    }
+  };
+
   try {
     for await (const message of qi) {
       // Session ID capture
@@ -110,9 +142,18 @@ export async function handleMessage(
       if (isAssistant(message)) {
         const result = processAssistantMessage(message, state);
 
-        // Notify tool usage
+        // Track the trailing text from this assistant message. Multiple
+        // assistant messages can fire per turn (one per tool-use round-trip);
+        // only the LAST one's trailingText is the user-facing final reply.
+        state.lastTrailingText = result.trailingText;
+
+        // Notify tool usage + capture delivery-tool text for end-of-turn dedup
         for (const tool of result.tools) {
           incrementCounter(`tool_calls.${tool.name}`);
+          captureDeliveredText(tool.name, tool.input);
+          if (isTurnTerminator(tool.name)) {
+            state.turnTerminated = true;
+          }
           if (onToolUse) {
             try {
               onToolUse(tool.name, tool.input);
@@ -132,6 +173,25 @@ export async function handleMessage(
             }
           }
         }
+
+        // Note: we previously called `qi.interrupt()` here when a turn-
+        // terminator tool fired, intending to short-circuit the SDK's
+        // wasted "wrap up after end_turn tool_result" follow-up API call
+        // (~3s of phantom typing while the model says nothing useful).
+        // That interrupt races with in-flight MCP tool dispatches in the
+        // same assistant message — `end_turn` itself is an MCP tool, and
+        // the model frequently emits sibling tool_use blocks in the same
+        // message. interrupt cancels their AbortController mid-flight,
+        // which surfaces as `MCP error -32001: AbortError` in the SDK
+        // result and bubbles up to the user as "Something went wrong".
+        //
+        // The natural-close path is fine: the SDK does one more API call
+        // after end_turn returns (the model has nothing to say so it
+        // returns a stop turn quickly, ~2-3s typing lag), then yields a
+        // result message and exits the iterator cleanly. We accept the
+        // typing lag in exchange for not breaking turns. `state.turnTerminated`
+        // is still tracked so the flow-violation re-prompt path below can
+        // skip its retry when the model explicitly ended its turn.
         continue;
       }
 
@@ -224,6 +284,55 @@ export async function handleMessage(
     }
   }
 
+  // ── Trailing-prose contract + flow-violation retry ──────────────────────
+  // The output stream is private scratchpad by design. Final replies must go
+  // through `end_turn` (canonical) or `send` (mid-turn rich content). When a
+  // turn ends with no tool call AND no trailing prose, that's valid silent
+  // close (model only reacted, or had nothing to do). When the model wrote
+  // prose but didn't route it through a delivery tool, that's a flow
+  // violation — the prose is private scratchpad, dropped from the user's
+  // view. To prevent these from going unnoticed, we re-prompt the model
+  // ONCE with a synthetic system message in the same session: it sees its
+  // broken turn in history + a reminder of the contract, and gets a fresh
+  // turn to deliver via end_turn. If it violates again on the retry, we
+  // give up loudly and accept the silent drop.
+  //
+  // Exception: if a turn-terminator tool (e.g. end_turn) was called, the
+  // model explicitly declared "I'm done" — respect it. Any trailing prose
+  // that slipped in earlier in the same assistant message gets logged but
+  // does NOT re-prompt (would loop endlessly with a model that pairs prose
+  // with end_turn).
+  const trailing = state.lastTrailingText.trim();
+  const flowViolation =
+    trailing.length > 0 &&
+    !state.turnTerminated &&
+    !isDuplicateOfDelivered(trailing, state.deliveredTextNorms);
+
+  if (flowViolation) {
+    incrementCounter("scratchpad.trailing_text_dropped");
+    log(
+      "agent",
+      `[${chatId}] flow violation: trailing prose (${trailing.length} chars) without end_turn/send. ${
+        _retried
+          ? "Already retried — accepting silent drop."
+          : "Re-prompting with reminder."
+      }`,
+    );
+
+    if (!_retried) {
+      incrementCounter("scratchpad.flow_violation_retried");
+      const reminder =
+        "[FLOW VIOLATION] You produced text content but didn't call `end_turn` or `send`. " +
+        "Pure prose in your output stream is private scratchpad — it's dropped, the user " +
+        "never sees it. Please retry with the proper flow: " +
+        "`end_turn(text=...)` to deliver a final reply, " +
+        "`end_turn()` (no args) to close silently, or " +
+        "`send(...)` for mid-turn rich content (photos, polls, etc.). " +
+        "Respond now using the correct tool call.";
+      return handleMessage({ ...params, text: reminder }, true);
+    }
+  }
+
   // ── Build result ──────────────────────────────────────────────────────────
 
   state.allResponseText += state.currentBlockText;

package/src/backend/claude-sdk/options.ts

@@ -6,12 +6,19 @@
  */
 
 import { resolve } from "node:path";
-import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  Options,
+  PostToolBatchHookInput,
+  HookCallback,
+  HookJSONOutput,
+} from "@anthropic-ai/claude-agent-sdk";
 import { getSession } from "../../storage/sessions.js";
 import { getChatSettings } from "../../storage/chat-settings.js";
 import { getPluginMcpServers } from "../../core/plugin.js";
 import { resolveModelId } from "../../core/models.js";
 import { wrapMcpServer } from "../../util/mcp-launcher.js";
+import { isTurnTerminator } from "../../core/tools/index.js";
+import { log } from "../../util/log.js";
 import { getConfig, getBridgePort } from "./state.js";
 import { DISALLOWED_TOOLS_CHAT, EFFORT_MAP } from "./constants.js";
 
@@ -90,6 +97,54 @@ export function buildMcpServers(
   return servers;
 }
 
+// ── Hooks ───────────────────────────────────────────────────────────────────
+
+/**
+ * PostToolBatch hook: terminate the SDK query loop the moment a turn-terminator
+ * tool (e.g. `end_turn`) resolves in the assistant's tool batch.
+ *
+ * Why PostToolBatch and not PostToolUse:
+ *   - PostToolUse fires per-tool and may run concurrently for parallel tool
+ *     calls. Returning `continue: false` from there can race with sibling MCP
+ *     tools whose AbortControllers haven't yet completed — the same race that
+ *     killed the previous `qi.interrupt()` approach (see handler.ts comment
+ *     and commit `d5ce30f`).
+ *   - PostToolBatch fires exactly ONCE after every tool in the batch has
+ *     resolved. By definition there are no in-flight siblings to race with.
+ *
+ * What this saves:
+ *   - The ~2-3s "phantom typing" round-trip the SDK makes after `end_turn`
+ *     returns (the model has nothing to say, generates a stop_turn anyway).
+ *   - Trailing prose that gets generated during that round-trip and was
+ *     previously suppressed only at the delivery layer (real tokens spent).
+ *
+ * Returns `{ continue: false, stopReason: ... }` → SDK exits with TerminalReason
+ * `'hook_stopped'`, no further model generation.
+ */
+const turnTerminatorHook: HookCallback = async (
+  input,
+): Promise<HookJSONOutput> => {
+  if (input.hook_event_name !== "PostToolBatch") {
+    return { continue: true };
+  }
+  const batch = input as PostToolBatchHookInput;
+  const terminator = batch.tool_calls.find((tc) =>
+    isTurnTerminator(tc.tool_name),
+  );
+  if (terminator) {
+    log(
+      "agent",
+      `PostToolBatch: terminating SDK loop on ${terminator.tool_name} ` +
+        `(batch size: ${batch.tool_calls.length})`,
+    );
+    return {
+      continue: false,
+      stopReason: "turn terminated by end_turn / send",
+    };
+  }
+  return { continue: true };
+};
+
 // ── Options builder ─────────────────────────────────────────────────────────
 
 export function buildSdkOptions(chatId: string): BuildSdkOptionsResult {
@@ -120,6 +175,9 @@ export function buildSdkOptions(chatId: string): BuildSdkOptionsResult {
       ...buildMcpServers(chatId),
       ...getPluginMcpServers(`http://127.0.0.1:${getBridgePort()}`, chatId),
     },
+    hooks: {
+      PostToolBatch: [{ hooks: [turnTerminatorHook] }],
+    },
     ...(session.sessionId ? { resume: session.sessionId } : {}),
   };
 

package/src/backend/claude-sdk/stream.ts

@@ -34,6 +34,33 @@ export type StreamState = {
   sdkCacheRead: number;
   sdkCacheWrite: number;
   lastStreamUpdate: number;
+  /**
+   * Trailing text from the most recent assistant message — text after all
+   * tool_use blocks (or the full text when no tools were called). NOT
+   * delivered to the user (the output stream is private scratchpad by
+   * contract). Tracked so the handler can log a diagnostic when the model
+   * wrote prose without routing it through `end_turn` / `send` — surfaces
+   * missed end_turn calls in metrics rather than silently dropping content.
+   */
+  lastTrailingText: string;
+  /**
+   * Normalized text args observed on `end_turn` / `send(type="text")` tool
+   * calls during this turn. Cross-tool dedup: if both fire with similar
+   * content (e.g. model calls both with the same text mid-turn), the
+   * second one can be matched against this list to avoid the user seeing
+   * the same message twice. Also used to silence the trailing-prose
+   * diagnostic when the prose just duplicates what was already delivered.
+   */
+  deliveredTextNorms: string[];
+  /**
+   * Set when a tool with `endsTurn: true` (e.g. `end_turn`) was observed
+   * in this turn. Once true, the handler invokes `qi.interrupt()` to abort
+   * the SDK loop cleanly — the model can't produce more trailing scratchpad
+   * after this point. Also gates the flow-violation re-prompt: if the model
+   * explicitly ended its turn, we don't re-prompt for trailing prose that
+   * may have appeared in the same assistant message before the terminator.
+   */
+  turnTerminated: boolean;
 };
 
 export function createStreamState(): StreamState {
@@ -50,6 +77,9 @@ export function createStreamState(): StreamState {
     sdkCacheRead: 0,
     sdkCacheWrite: 0,
     lastStreamUpdate: 0,
+    lastTrailingText: "",
+    deliveredTextNorms: [],
+    turnTerminated: false,
   };
 }
 
@@ -224,3 +254,40 @@ export function processResultMessage(
     state.currentBlockText = msg.result;
   }
 }
+
+// ── Trailing-text fallback dedup ────────────────────────────────────────────
+
+/**
+ * Normalize text for fuzzy comparison — trim, lowercase, collapse whitespace,
+ * strip emoji. Used to detect whether trailing prose duplicates content
+ * already delivered via `end_turn` / `send(type="text")`.
+ */
+export function normalizeForDedupe(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/\p{Emoji_Presentation}|\p{Extended_Pictographic}/gu, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const MIN_DEDUP_LENGTH = 10;
+
+/**
+ * Returns true if `candidate` is substantively the same as any text in
+ * `deliveredNorms`. "Substantively" = one is a substring of the other after
+ * normalization; both must be at least MIN_DEDUP_LENGTH chars to avoid
+ * dropping short legitimate replies.
+ */
+export function isDuplicateOfDelivered(
+  candidate: string,
+  deliveredNorms: string[],
+): boolean {
+  if (deliveredNorms.length === 0) return false;
+  const norm = normalizeForDedupe(candidate);
+  if (norm.length < MIN_DEDUP_LENGTH) return false;
+  return deliveredNorms.some(
+    (d) =>
+      d.length >= MIN_DEDUP_LENGTH && (norm.includes(d) || d.includes(norm)),
+  );
+}

package/src/core/tools/index.ts

@@ -30,6 +30,47 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
 ];
 
+/**
+ * Names of tools that explicitly terminate the model's turn.
+ *
+ * Backend handlers consume this set to abort their stream loop after
+ * observing one of these tools — without it, the model can keep producing
+ * trailing scratchpad prose after declaring "I'm done", which trips the
+ * flow-violation re-prompt path. Declaration is on the tool definition
+ * (`endsTurn: true`); detection is shared; abort is backend-specific.
+ */
+const TURN_TERMINATOR_NAMES: ReadonlySet<string> = new Set(
+  ALL_TOOLS.filter((t) => t.endsTurn).map((t) => t.name),
+);
+
+/**
+ * Strip an MCP server prefix (`mcp__<server>__`) from a tool name.
+ *
+ * Tools served through MCP arrive at the SDK with the prefix attached
+ * (e.g. `mcp__telegram-tools__end_turn`), while the registry stores them
+ * by their bare name (`end_turn`). Callers that want to compare against
+ * the registry should normalize first.
+ *
+ * Returns the input unchanged if no prefix matches — safe to call on any
+ * tool name. The non-greedy `.+?` matches the FIRST `__` boundary after
+ * `mcp__`, which is the server-name terminator in MCP's naming scheme.
+ */
+export function stripMcpPrefix(toolName: string): string {
+  return toolName.replace(/^mcp__.+?__/, "");
+}
+
+/**
+ * Whether a tool call by this name should terminate the model's turn.
+ *
+ * Accepts both bare names (`end_turn`) and MCP-prefixed names
+ * (`mcp__telegram-tools__end_turn`) — the prefix is stripped before
+ * comparing against the terminator set.
+ */
+export function isTurnTerminator(toolName: string): boolean {
+  if (TURN_TERMINATOR_NAMES.has(toolName)) return true;
+  return TURN_TERMINATOR_NAMES.has(stripMcpPrefix(toolName));
+}
+
 /** Filter options for composing a tool set. */
 export interface ComposeOptions {
   /** Include only tools available on this frontend. */

package/src/core/tools/messaging.ts

@@ -1,5 +1,6 @@
 /**
- * Messaging tools — send, react, edit, delete, forward, pin/unpin, stop poll.
+ * Messaging tools — send, end_turn, react, edit, delete, forward, pin/unpin,
+ * stop poll.
  */
 
 import { z } from "zod";
@@ -7,6 +8,83 @@ import type { ToolDefinition } from "./types.js";
 import { idSchema } from "./schemas.js";
 
 export const messagingTools: ToolDefinition[] = [
+  // ── end_turn — explicit final-reply delivery ──────────────────────────
+  // Schema-typed alternative to relying on a trailing-text fallback. The
+  // model is taught that this is the canonical way to deliver its final
+  // reply. Functionally a thin wrapper over send(type="text") + reply_to +
+  // buttons; the value is in the EXPLICIT semantic ("this ends my turn")
+  // and that the model sees a single tool whose purpose is unambiguous.
+  //
+  // The output stream is private scratchpad by contract. If the model
+  // writes trailing prose without calling end_turn or send, the handler
+  // re-prompts ONCE in the same session with a flow-violation reminder
+  // so the model can retry properly. Persistent violation after retry
+  // results in silent drop + `scratchpad.trailing_text_dropped` counter.
+  // `end_turn` is the documented happy path.
+  {
+    name: "end_turn",
+    description: `End your current turn and deliver your final reply to the user. This is the canonical way to respond.
+
+Call this AT MOST ONCE per turn — it should be the last tool you call. Behaves like send(type="text") with reply_to and buttons support, but the name makes the intent explicit: this is the message that ends the turn.
+
+Examples:
+  end_turn(text="Got it sur") — plain reply
+  end_turn(text="On it", reply_to=12345) — reply to a specific message ID
+  end_turn(text="Pick one", buttons=[[{"text":"A","callback_data":"a"}]]) — with buttons
+  end_turn() — silent end (no message; useful when you already replied via earlier send/react calls)
+
+Notes:
+- For richer message types (photos, polls, voice, scheduled messages, multi-target), use the send tool — those don't fit "final reply" semantics.
+- The output stream is private scratchpad. If you write prose without calling end_turn or send, the handler re-prompts you ONCE with a flow-violation reminder so you can retry properly. Persistent violation drops the prose silently. end_turn is the documented happy path.`,
+    schema: {
+      text: z
+        .string()
+        .optional()
+        .describe(
+          "Final reply text. Supports Markdown. Omit to end the turn silently (no message sent).",
+        ),
+      reply_to: idSchema
+        .optional()
+        .describe("Message ID to reply to (typically the user's [msg_id:N])"),
+      buttons: z
+        .array(
+          z.array(
+            z.object({
+              text: z.string(),
+              url: z.string().optional(),
+              callback_data: z.string().optional(),
+            }),
+          ),
+        )
+        .optional()
+        .describe("Inline keyboard button rows"),
+    },
+    execute: async (params, bridge) => {
+      // Telegram path: routes to the same bridge actions as send(type="text")
+      // so bridgeMessageCount, dedup, and audit logging all stay consistent.
+      if (typeof params.text !== "string" || params.text.trim() === "") {
+        // Silent end — no bridge call. The handler still sees the tool was
+        // invoked (via deliveredTextNorms staying empty), and trailing-text
+        // fallback won't fire because there was no trailing prose.
+        return { ok: true, silent: true };
+      }
+      if (params.buttons) {
+        return bridge("send_message_with_buttons", {
+          text: params.text,
+          rows: params.buttons,
+          reply_to_message_id: params.reply_to,
+        });
+      }
+      return bridge("send_message", {
+        text: params.text,
+        reply_to_message_id: params.reply_to,
+      });
+    },
+    frontends: ["telegram", "teams"],
+    tag: "messaging",
+    endsTurn: true,
+  },
+
   // ── Telegram unified send ─────────────────────────────────────────────
   {
     name: "send",

package/src/core/tools/types.ts

@@ -58,4 +58,18 @@ export interface ToolDefinition {
 
   /** Grouping tag. */
   readonly tag: ToolTag;
+
+  /**
+   * This tool explicitly ends the model's turn. Backend handlers observe
+   * this flag to abort their stream loop cleanly after the tool's bridge
+   * call completes — without it, the model is free to keep producing
+   * trailing prose into private scratchpad after declaring "I'm done",
+   * which then trips the flow-violation re-prompt path. With this flag,
+   * an end_turn call genuinely ends the turn.
+   *
+   * Backend abort mechanism is backend-specific (Claude SDK uses
+   * Query.interrupt(); other backends manage their own loop) — this flag
+   * is the shared declarative signal, not the implementation.
+   */
+  readonly endsTurn?: boolean;
 }

package/src/frontend/teams/index.ts

@@ -14,7 +14,7 @@ import type { Gateway } from "../../core/gateway.js";
 import { log, logError } from "../../util/log.js";
 import { deriveNumericChatId } from "../../util/chat-id.js";
 import { resolveModel } from "../../core/models.js";
-import { createTeamsActionHandler } from "./actions.js";
+import { createTeamsActionHandler, postToTeams } from "./actions.js";
 import { splitTeamsMessage, buildAdaptiveCard } from "./formatting.js";
 import {
   initGraphClient,
@@ -356,18 +356,28 @@ export function createTeamsFrontend(
                   `  tool: ${toolName}${detail ? ` — ${String(detail).slice(0, 100)}` : ""}`,
                 );
               },
-            })
-              .then(async (result) => {
-                // Only deliver messages sent via the send_message tool.
-                // Do NOT send fallback text — if the model chose not to use send_message,
-                // it's either choosing not to respond or outputting internal reasoning
-                // that shouldn't be shown to users.
-                if (result.bridgeMessageCount === 0 && result.text?.trim()) {
-                  log(
+              // Deliver assistant text (progress text before tool calls AND
+              // the end-of-turn trailing-text fallback) to the Teams chat.
+              // Without this, prose-only assistant turns would be silently
+              // dropped — same scratchpad bug Telegram hit.
+              onTextBlock: async (blockText) => {
+                if (!blockText.trim()) return;
+                try {
+                  await postToTeams(webhookUrl, blockText);
+                  gateway.incrementMessages(numericChatId);
+                } catch (err) {
+                  logError(
                     "teams",
-                    `Suppressed fallback text (${result.text.length} chars) — no send_message tool used`,
+                    `onTextBlock postToTeams failed: ${err instanceof Error ? err.message : err}`,
                   );
                 }
+              },
+            })
+              .then(async (_result) => {
+                // No fallback delivery — turns without end_turn / send_message
+                // are intentional silent ends. Trailing prose without a tool
+                // call is scratchpad and dropped; the SDK handler emits a
+                // `scratchpad.trailing_text_dropped` metric on those.
               })
               .catch((err) => {
                 logError(

package/src/frontend/telegram/handlers.ts

@@ -14,6 +14,7 @@ import {
   appendDailyLog,
   appendDailyLogResponse,
 } from "../../storage/daily-log.js";
+import { stripMcpPrefix } from "../../core/tools/index.js";
 import { setMessageFilePath } from "../../storage/history.js";
 import { addMedia } from "../../storage/media-index.js";
 import { recordMessageProcessed, recordError } from "../../util/watchdog.js";
@@ -771,8 +772,17 @@ async function processAndReply(params: ProcessAndReplyParams): Promise<void> {
       onStreamDelta,
       onTextBlock,
       onToolUse: (toolName, input) => {
-        if (
-          toolName === "send" &&
+        // Tool names arrive MCP-prefixed (e.g. `mcp__telegram-tools__end_turn`)
+        // when routed through MCP — strip the prefix so equality checks
+        // match the registry's bare names. Both `end_turn(text=...)` and
+        // `send(type="text")` are user-facing text deliveries; capture
+        // both so the daily log records bot responses regardless of which
+        // delivery tool the model used.
+        const bareName = stripMcpPrefix(toolName);
+        if (bareName === "end_turn" && typeof input.text === "string") {
+          appendDailyLogResponse("Talon", input.text, { chatTitle });
+        } else if (
+          bareName === "send" &&
           input.type === "text" &&
           typeof input.text === "string"
         ) {
@@ -781,16 +791,10 @@ async function processAndReply(params: ProcessAndReplyParams): Promise<void> {
       },
     });
 
-    if (
-      result.bridgeMessageCount === 0 &&
-      !stream.sentTextBlock &&
-      result.text?.trim()
-    ) {
-      log(
-        "bot",
-        `Suppressed fallback text (${result.text.length} chars) — no send tool used`,
-      );
-    }
+    // No fallback delivery — turns that don't call `end_turn` / `send` are
+    // intentional silent ends. Trailing prose written without a tool call is
+    // scratchpad and dropped (the SDK handler logs a `scratchpad.trailing_
+    // text_dropped` metric so missed end_turn calls show up in counters).
   } finally {
     clearTimeout(streamTimer);
   }