talon-agent 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -30,7 +30,16 @@
   },
   "files": [
     "bin/",
-    "src/",
+    "src/backend/",
+    "src/core/",
+    "src/frontend/",
+    "src/plugins/",
+    "src/storage/",
+    "src/util/",
+    "src/bootstrap.ts",
+    "src/cli.ts",
+    "src/index.ts",
+    "src/login.ts",
     "prompts/",
     "README.md",
     "tsconfig.json"
@@ -41,13 +50,20 @@
     "setup": "tsx src/cli.ts setup",
     "dev": "tsx --watch src/index.ts",
     "test": "vitest run",
+    "test:ci": "vitest run --reporter=verbose --reporter=json --outputFile=test-results.json",
+    "test:functional": "vitest run --reporter=verbose --reporter=json --outputFile=functional-results.json src/__tests__/package.functional.test.ts src/__tests__/tool-functional.test.ts src/__tests__/mcp-launcher.test.ts src/__tests__/mcp-launcher-functional.test.ts src/__tests__/integration/sdk-stub.test.ts src/__tests__/integration/talon-functional.test.ts",
+    "test:integration": "vitest run --reporter=verbose --reporter=json --outputFile=integration-results.json src/__tests__/integration/talon-mcp-functional.test.ts",
+    "test:integration:all": "vitest run --reporter=verbose src/__tests__/integration/",
+    "tarball:check": "node .github/scripts/tarball-check.mjs",
+    "build:stub-sea": "node src/__tests__/integration/stub-claude/build-sea.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint src/",
     "knip": "knip",
     "format": "prettier --write src/ prompts/",
-    "format:check": "prettier --check src/ prompts/"
+    "format:check": "prettier --check src/ prompts/",
+    "ci:protect": "node .github/scripts/enforce-ci-gate.mjs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.108",
@@ -58,7 +74,7 @@
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "^1.4.0",
-    "@playwright/mcp": "^0.0.74",
+    "@playwright/mcp": "^0.0.75",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
     "croner": "^10.0.1",
@@ -71,7 +87,7 @@
     "telegram": "^2.26.22",
     "tsx": "^4.21.0",
     "undici": "^8.0.2",
-    "write-file-atomic": "^7.0.1",
+    "write-file-atomic": "^8.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -86,6 +102,8 @@
     "vitest": "^4.1.3"
   },
   "overrides": {
-    "@anthropic-ai/sdk": "^0.95.0"
+    "@anthropic-ai/sdk": "^0.95.0",
+    "ip-address": "^10.1.1",
+    "fast-uri": "^3.1.2"
   }
 }

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

@@ -24,7 +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 } from "../../core/tools/index.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";
@@ -99,15 +99,20 @@ export async function handleMessage(
   // 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 (toolName === "end_turn" && typeof input.text === "string") {
+    if (bareName === "end_turn" && typeof input.text === "string") {
       deliveredText = input.text;
     } else if (
-      toolName === "send" &&
+      bareName === "send" &&
       input.type === "text" &&
       typeof input.text === "string"
     ) {
@@ -169,25 +174,24 @@ export async function handleMessage(
           }
         }
 
-        // Turn-terminator tool was called (e.g. `end_turn`). Abort the SDK
-        // loop cleanly so the model can't keep producing trailing scratchpad
-        // after declaring "I'm done". Without this, the model is free to
-        // think more, call more tools, or write more prose — and any prose
-        // afterwards trips the flow-violation re-prompt path. Calling
-        // qi.interrupt() lets the SDK yield its terminal result and exit
-        // the for-await loop on the next iteration.
-        if (state.turnTerminated) {
-          try {
-            await qi.interrupt();
-          } catch (err) {
-            // Non-fatal: interrupt failures shouldn't break the turn,
-            // they just mean the natural end-of-stream path will run.
-            logWarn(
-              "agent",
-              `[${chatId}] qi.interrupt() after turn terminator failed: ${(err as Error)?.message ?? err}`,
-            );
-          }
-        }
+        // 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;
       }
 

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

@@ -6,12 +6,20 @@
  */
 
 import { resolve } from "node:path";
-import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import { pathToFileURL } from "node:url";
+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";
 
@@ -38,10 +46,17 @@ export function buildMcpServers(
   const config = getConfig();
   const bridgeUrl = `http://127.0.0.1:${getBridgePort()}`;
 
-  const tsxImport = resolve(
-    import.meta.dirname ?? ".",
-    "../../../node_modules/tsx/dist/esm/index.mjs",
-  );
+  // tsx as a Node loader is passed via `--import <url>`. Node accepts URLs
+  // or absolute paths, but on Windows a raw backslash path (`D:\…\tsx`) is
+  // ambiguous between path and URL — the loader hook fails to register and
+  // every subsequent `import` of a .ts file throws. `pathToFileURL` produces
+  // a cross-platform `file://` URL that Node always treats as a loader URL.
+  const tsxImport = pathToFileURL(
+    resolve(
+      import.meta.dirname ?? ".",
+      "../../../node_modules/tsx/dist/esm/index.mjs",
+    ),
+  ).href;
   const mcpServerPath = resolve(
     import.meta.dirname ?? ".",
     "../../core/tools/mcp-server.ts",
@@ -65,12 +80,14 @@ export function buildMcpServers(
       TALON_CHAT_ID: chatId,
       TALON_FRONTEND: frontend,
     };
+    // `node --import <tsx-loader>` everywhere — tsx as a Node loader works
+    // identically on Windows and POSIX, and avoids spawning `npx.cmd` (which
+    // Node 20.19+ refuses to execute via child_process.spawn without
+    // shell:true; CVE-2024-27980 mitigation). The wrapping launcher would
+    // hit the same .cmd ban when calling its child.
     servers[serverName] = wrapMcpServer({
-      command: process.platform === "win32" ? "npx" : "node",
-      args:
-        process.platform === "win32"
-          ? ["tsx", mcpServerPath]
-          : ["--import", tsxImport, mcpServerPath],
+      command: "node",
+      args: ["--import", tsxImport, mcpServerPath],
       env: mcpEnv,
     });
   }
@@ -90,6 +107,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 +185,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/core/gateway.ts

@@ -298,9 +298,16 @@ export class Gateway {
         });
         httpServer.listen(p, "127.0.0.1", () => {
           this.server = httpServer;
-          this.port = p;
-          log("gateway", `Action gateway on :${p}`);
-          resolve(p);
+          // When the caller asks for port 0 the OS assigns a random free
+          // port — read the actual port off the listening socket instead
+          // of saving the requested 0.
+          const addr = httpServer.address();
+          this.port =
+            typeof addr === "object" && addr !== null
+              ? (addr as { port: number }).port
+              : p;
+          log("gateway", `Action gateway on :${this.port}`);
+          resolve(this.port);
         });
       };
       tryPort(port);

package/src/core/tools/index.ts

@@ -43,9 +43,32 @@ const TURN_TERMINATOR_NAMES: ReadonlySet<string> = new Set(
   ALL_TOOLS.filter((t) => t.endsTurn).map((t) => t.name),
 );
 
-/** Whether a tool call by this name should terminate the model's turn. */
+/**
+ * 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 {
-  return TURN_TERMINATOR_NAMES.has(toolName);
+  if (TURN_TERMINATOR_NAMES.has(toolName)) return true;
+  return TURN_TERMINATOR_NAMES.has(stripMcpPrefix(toolName));
 }
 
 /** Filter options for composing a tool set. */

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";
@@ -158,11 +159,117 @@ export async function isAccessAllowed(
   return false;
 }
 
+/**
+ * Maximum length of an unauthorized message body to retain in logs.
+ * Keeps abusive payloads (large pastes, attachment captions etc.) bounded
+ * while still preserving enough context to understand what was sent.
+ */
+const UNAUTHORIZED_BODY_MAX_LEN = 1024;
+
+/**
+ * Best-effort preview of an unauthorized message for forensics.
+ *
+ * Returns the visible text payload (text or caption), a short tag for
+ * media-only messages (`[sticker: 🤖]`, `[photo]`, `[voice 14s]`, etc.),
+ * or `undefined` if there's nothing meaningful to capture (e.g. a service
+ * message or empty content).
+ *
+ * Truncated to UNAUTHORIZED_BODY_MAX_LEN to keep log lines bounded.
+ */
+export function extractUnauthorizedPreview(
+  message:
+    | {
+        text?: string;
+        caption?: string;
+        sticker?: { emoji?: string; set_name?: string };
+        photo?: unknown;
+        voice?: { duration?: number };
+        video?: unknown;
+        video_note?: unknown;
+        audio?: unknown;
+        animation?: unknown;
+        document?: { file_name?: string };
+        contact?: unknown;
+        location?: unknown;
+        poll?: { question?: string };
+        dice?: { emoji?: string };
+      }
+    | undefined,
+): string | undefined {
+  if (!message) return undefined;
+
+  const text = message.text ?? message.caption;
+  if (typeof text === "string" && text.trim().length > 0) {
+    return text.length > UNAUTHORIZED_BODY_MAX_LEN
+      ? `${text.slice(0, UNAUTHORIZED_BODY_MAX_LEN)}… [truncated]`
+      : text;
+  }
+
+  if (message.sticker) {
+    const emoji = message.sticker.emoji ?? "?";
+    const set = message.sticker.set_name
+      ? ` from ${message.sticker.set_name}`
+      : "";
+    return `[sticker: ${emoji}${set}]`;
+  }
+  if (message.photo) return "[photo]";
+  if (message.voice) {
+    const dur = message.voice.duration;
+    return dur ? `[voice ${dur}s]` : "[voice]";
+  }
+  if (message.video_note) return "[video note]";
+  if (message.video) return "[video]";
+  if (message.audio) return "[audio]";
+  if (message.animation) return "[animation]";
+  if (message.document) {
+    return message.document.file_name
+      ? `[document: ${message.document.file_name}]`
+      : "[document]";
+  }
+  if (message.contact) return "[contact]";
+  if (message.location) return "[location]";
+  if (message.poll) {
+    return message.poll.question
+      ? `[poll: ${message.poll.question}]`
+      : "[poll]";
+  }
+  if (message.dice) return `[dice: ${message.dice.emoji ?? "🎲"}]`;
+
+  return undefined;
+}
+
 async function notifyUnauthorized(
   bot: Bot,
   ctx: Context,
   type: "dm" | "group",
 ): Promise<void> {
+  const sender = getSenderName(ctx.from);
+  const username = ctx.from?.username ? ` (@${ctx.from.username})` : "";
+  const userId = ctx.from?.id ?? "unknown";
+
+  // Capture message body BEFORE the cooldown check — every unauthorized
+  // attempt should be recorded for forensics, even if the user-facing
+  // warning + admin notification are suppressed by cooldown. Without
+  // this, follow-up DMs from a known social-engineering account vanish
+  // entirely from logs.
+  const body = extractUnauthorizedPreview(
+    ctx.message as Parameters<typeof extractUnauthorizedPreview>[0],
+  );
+  if (body) {
+    try {
+      appendDailyLog(
+        `⚠️ UNAUTHORIZED ${sender}${username} [id:${userId}]`,
+        body,
+      );
+    } catch {
+      /* daily log unavailable — fall through to talon.log */
+    }
+    logWarn(
+      "access",
+      `Unauthorized ${type} body from ${sender}${username} [id:${userId}]: ${body.slice(0, 200)}`,
+    );
+  }
+
   const key = type === "dm" ? `dm:${ctx.from?.id}` : `group:${ctx.chat?.id}`;
   const now = Date.now();
   const lastWarned = unauthorizedCooldown.get(key);
@@ -172,10 +279,6 @@ async function notifyUnauthorized(
   }
   unauthorizedCooldown.set(key, now);
 
-  const sender = getSenderName(ctx.from);
-  const username = ctx.from?.username ? ` (@${ctx.from.username})` : "";
-  const userId = ctx.from?.id ?? "unknown";
-
   // Warn the user
   try {
     await bot.api.sendMessage(
@@ -192,8 +295,9 @@ async function notifyUnauthorized(
       type === "dm"
         ? `🚨 Unauthorized DM from ${sender}${username} [id:${userId}]`
         : `🚨 Unauthorized group access: "${(ctx.chat as { title?: string })?.title ?? ctx.chat!.id}" [id:${ctx.chat!.id}] by ${sender}${username}`;
+    const detailWithBody = body ? `${detail}\n\n${body.slice(0, 400)}` : detail;
     try {
-      await bot.api.sendMessage(adminId, detail);
+      await bot.api.sendMessage(adminId, detailWithBody);
     } catch {
       /* admin unreachable — ignore */
     }
@@ -771,8 +875,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"
         ) {

package/src/__tests__/chat-id.test.ts

@@ -1,91 +0,0 @@
-import { describe, it, expect } from "vitest";
-
-import {
-  deriveNumericChatId,
-  generateTerminalChatId,
-  isTerminalChatId,
-} from "../util/chat-id.js";
-
-describe("deriveNumericChatId", () => {
-  it("returns a positive number", () => {
-    const id = deriveNumericChatId("test-chat");
-    expect(id).toBeGreaterThan(0);
-    expect(Number.isInteger(id)).toBe(true);
-  });
-
-  it("returns the same value for the same input", () => {
-    const a = deriveNumericChatId("stable-id");
-    const b = deriveNumericChatId("stable-id");
-    expect(a).toBe(b);
-  });
-
-  it("returns different values for different inputs", () => {
-    const a = deriveNumericChatId("chat-alpha");
-    const b = deriveNumericChatId("chat-beta");
-    expect(a).not.toBe(b);
-  });
-
-  it("handles terminal-style IDs", () => {
-    const id = deriveNumericChatId("t_1711360000000");
-    expect(id).toBeGreaterThan(0);
-  });
-
-  it("handles empty string", () => {
-    const id = deriveNumericChatId("");
-    expect(id).toBeGreaterThanOrEqual(0);
-    expect(Number.isInteger(id)).toBe(true);
-  });
-});
-
-describe("generateTerminalChatId", () => {
-  it("returns a string starting with t_", () => {
-    const id = generateTerminalChatId();
-    expect(id).toMatch(/^t_\d+$/);
-  });
-
-  it("returns a string with numeric timestamp portion", () => {
-    const id = generateTerminalChatId();
-    const ts = Number(id.slice(2));
-    expect(Number.isNaN(ts)).toBe(false);
-    expect(ts).toBeGreaterThan(0);
-  });
-
-  it("uses a recent timestamp", () => {
-    const before = Date.now();
-    const id = generateTerminalChatId();
-    const after = Date.now();
-    const ts = Number(id.slice(2));
-    expect(ts).toBeGreaterThanOrEqual(before);
-    expect(ts).toBeLessThanOrEqual(after);
-  });
-});
-
-describe("isTerminalChatId", () => {
-  it('returns true for "1" (legacy ID)', () => {
-    expect(isTerminalChatId("1")).toBe(true);
-  });
-
-  it("returns true for t_ prefixed IDs", () => {
-    expect(isTerminalChatId("t_1711360000000")).toBe(true);
-    expect(isTerminalChatId("t_0")).toBe(true);
-    expect(isTerminalChatId("t_abc")).toBe(true);
-  });
-
-  it("returns false for Telegram numeric IDs", () => {
-    expect(isTerminalChatId("123456789")).toBe(false);
-    expect(isTerminalChatId("-100123456")).toBe(false);
-  });
-
-  it("returns false for Teams IDs", () => {
-    expect(isTerminalChatId("teams_chat_abc123")).toBe(false);
-  });
-
-  it("returns false for empty string", () => {
-    expect(isTerminalChatId("")).toBe(false);
-  });
-
-  it('returns false for "10" and other strings starting with 1', () => {
-    expect(isTerminalChatId("10")).toBe(false);
-    expect(isTerminalChatId("100")).toBe(false);
-  });
-});