talon-agent 1.10.0 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -41,13 +41,17 @@
     "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",
+    "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 +62,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 +75,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 +90,7 @@
     "vitest": "^4.1.3"
   },
   "overrides": {
-    "@anthropic-ai/sdk": "^0.95.0"
+    "@anthropic-ai/sdk": "^0.95.0",
+    "ip-address": "^10.1.1"
   }
 }

package/src/__tests__/claude-sdk-options.test.ts

@@ -107,4 +107,99 @@ describe("buildSdkOptions", () => {
     expect(activeModel).toBe("claude-sonnet-4-6[1m]");
     expect(options.model).toBe("sonnet[1m]");
   });
+
+  describe("PostToolBatch turn-terminator hook", () => {
+    type HookCallback = (
+      input: unknown,
+      toolUseID?: string,
+      ctx?: { signal: AbortSignal },
+    ) => Promise<{ continue?: boolean; stopReason?: string }>;
+
+    const callHook = async (toolNames: string[]): Promise<unknown> => {
+      const { buildSdkOptions } =
+        await import("../backend/claude-sdk/options.js");
+      const { options } = buildSdkOptions("chat-hook-test");
+
+      const matchers = options.hooks?.PostToolBatch;
+      expect(matchers).toBeDefined();
+      expect(matchers!.length).toBe(1);
+      const hook = matchers![0]!.hooks[0] as unknown as HookCallback;
+
+      return hook(
+        {
+          hook_event_name: "PostToolBatch",
+          tool_calls: toolNames.map((name, i) => ({
+            tool_name: name,
+            tool_input: {},
+            tool_use_id: `tu_${i}`,
+          })),
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+    };
+
+    it("registers a PostToolBatch hook on the options object", async () => {
+      const { buildSdkOptions } =
+        await import("../backend/claude-sdk/options.js");
+      const { options } = buildSdkOptions("chat-hook-1");
+      expect(options.hooks?.PostToolBatch).toBeDefined();
+      expect(options.hooks!.PostToolBatch!.length).toBe(1);
+      expect(options.hooks!.PostToolBatch![0]!.hooks.length).toBe(1);
+    });
+
+    it("returns continue:false when an MCP-prefixed end_turn is in the batch", async () => {
+      const result = (await callHook([
+        "mcp__telegram-tools__send",
+        "mcp__telegram-tools__end_turn",
+      ])) as { continue: boolean; stopReason?: string };
+      expect(result.continue).toBe(false);
+      expect(result.stopReason).toMatch(/end_turn/i);
+    });
+
+    it("returns continue:false when a bare end_turn is in the batch", async () => {
+      const result = (await callHook(["end_turn"])) as {
+        continue: boolean;
+      };
+      expect(result.continue).toBe(false);
+    });
+
+    it("returns continue:true when no terminator is in the batch", async () => {
+      const result = (await callHook([
+        "mcp__telegram-tools__send",
+        "Read",
+        "Bash",
+      ])) as { continue: boolean };
+      expect(result.continue).toBe(true);
+    });
+
+    it("returns continue:true on an empty batch", async () => {
+      const result = (await callHook([])) as { continue: boolean };
+      expect(result.continue).toBe(true);
+    });
+
+    it("ignores non-PostToolBatch events defensively", async () => {
+      const { buildSdkOptions } =
+        await import("../backend/claude-sdk/options.js");
+      const { options } = buildSdkOptions("chat-hook-defensive");
+      const hook = options.hooks!.PostToolBatch![0]!.hooks[0] as unknown as (
+        input: unknown,
+        id?: string,
+        ctx?: { signal: AbortSignal },
+      ) => Promise<{ continue: boolean }>;
+
+      const result = await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "mcp__telegram-tools__end_turn",
+          tool_input: {},
+          tool_response: {},
+          tool_use_id: "tu_0",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+      expect(result.continue).toBe(true);
+    });
+  });
 });

package/src/__tests__/end-turn.test.ts

@@ -14,9 +14,15 @@ import {
   normalizeForDedupe,
   isDuplicateOfDelivered,
   createStreamState,
+  processAssistantMessage,
 } from "../backend/claude-sdk/stream.js";
+import type { SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
 import { messagingTools } from "../core/tools/messaging.js";
-import { isTurnTerminator, ALL_TOOLS } from "../core/tools/index.js";
+import {
+  isTurnTerminator,
+  stripMcpPrefix,
+  ALL_TOOLS,
+} from "../core/tools/index.js";
 
 describe("normalizeForDedupe", () => {
   it("trims, lowercases, and collapses whitespace", () => {
@@ -120,6 +126,42 @@ describe("turn-terminator declaration", () => {
     expect(isTurnTerminator("nonexistent_tool")).toBe(false);
   });
 
+  it("isTurnTerminator handles MCP-prefixed names", () => {
+    // Tools served through MCP arrive with a `mcp__<server>__` prefix.
+    // The check must normalize the prefix so the SDK's actual tool names
+    // match the registry. Without this, downstream branches gated on
+    // `state.turnTerminated` silently never fire — the flow-violation
+    // re-prompt skip and trailing-prose dedup both break.
+    expect(isTurnTerminator("mcp__telegram-tools__end_turn")).toBe(true);
+    expect(isTurnTerminator("mcp__teams-tools__end_turn")).toBe(true);
+    // Non-terminators with the same prefix shape still return false
+    expect(isTurnTerminator("mcp__telegram-tools__send")).toBe(false);
+    expect(isTurnTerminator("mcp__telegram-tools__react")).toBe(false);
+    // Server name with hyphen + underscore must still match the boundary
+    expect(isTurnTerminator("mcp__some-server-name__end_turn")).toBe(true);
+  });
+
+  it("stripMcpPrefix strips the mcp__<server>__ prefix when present", () => {
+    expect(stripMcpPrefix("mcp__telegram-tools__end_turn")).toBe("end_turn");
+    expect(stripMcpPrefix("mcp__brave-search__brave_web_search")).toBe(
+      "brave_web_search",
+    );
+    // Non-greedy match takes the FIRST `__` after `mcp__` as the boundary
+    expect(stripMcpPrefix("mcp__a__b__c")).toBe("b__c");
+  });
+
+  it("stripMcpPrefix returns input unchanged when no prefix matches", () => {
+    expect(stripMcpPrefix("end_turn")).toBe("end_turn");
+    expect(stripMcpPrefix("send")).toBe("send");
+    expect(stripMcpPrefix("Read")).toBe("Read");
+    // Looks like a prefix but missing the trailing `__`
+    expect(stripMcpPrefix("mcp__incomplete")).toBe("mcp__incomplete");
+    // Different prefix shape
+    expect(stripMcpPrefix("not_mcp__server__tool")).toBe(
+      "not_mcp__server__tool",
+    );
+  });
+
   it("only one turn terminator currently exists (end_turn)", () => {
     // If a future change adds a second terminator, this test should fail
     // and the author should document why a new terminator is necessary.
@@ -187,3 +229,79 @@ describe("end_turn tool definition", () => {
     expect(result).toEqual({ ok: true, silent: true });
   });
 });
+
+// ── Production wire-shape contract ──────────────────────────────────────────
+//
+// These tests pin the integration between the SDK's actual emitted tool
+// names (always MCP-prefixed when served via MCP) and the registry checks
+// the handler runs against them. They are the tests that would have caught
+// the bug fixed in this PR — strict-equality `isTurnTerminator("end_turn")`
+// passed in unit tests but the production code path called
+// `isTurnTerminator("mcp__telegram-tools__end_turn")` and silently failed.
+//
+// Auto-derived from ALL_TOOLS so adding a new endsTurn tool or a new MCP
+// frontend stays covered without manually adding cases.
+
+describe("turn-terminator integration with SDK production tool name shapes", () => {
+  // Built-in MCP server names that the SDK is known to wire Talon's tools
+  // through. Keep this list in sync with the actual MCP server registration
+  // in src/core/tools/mcp-server.ts and frontend wiring.
+  const KNOWN_MCP_SERVERS = ["telegram-tools", "teams-tools"];
+
+  for (const tool of ALL_TOOLS.filter((t) => t.endsTurn)) {
+    for (const server of KNOWN_MCP_SERVERS) {
+      const sdkName = `mcp__${server}__${tool.name}`;
+
+      it(`isTurnTerminator(${sdkName}) === true`, () => {
+        // The SDK never emits bare names for MCP-served tools — it always
+        // includes the `mcp__<server>__` prefix. Strict equality against the
+        // registry's bare name was the production bug.
+        expect(isTurnTerminator(sdkName)).toBe(true);
+      });
+
+      it(`processAssistantMessage + isTurnTerminator: ${sdkName} flips state.turnTerminated`, () => {
+        // End-to-end check of the exact two-step the handler does:
+        //   block.name -> tools[].name (via processAssistantMessage)
+        //   tools[].name -> isTurnTerminator
+        // If either step normalizes inconsistently, this breaks.
+        const state = createStreamState();
+        const msg = {
+          type: "assistant",
+          message: {
+            content: [
+              {
+                type: "tool_use",
+                id: "tool_1",
+                name: sdkName,
+                input: { text: "Hello sur" },
+              },
+            ],
+          },
+        } as unknown as SDKAssistantMessage;
+
+        const result = processAssistantMessage(msg, state);
+        expect(result.tools).toHaveLength(1);
+        expect(result.tools[0].name).toBe(sdkName);
+
+        // This is the exact line in handler.ts:
+        //     if (isTurnTerminator(tool.name)) state.turnTerminated = true;
+        if (isTurnTerminator(result.tools[0].name)) {
+          state.turnTerminated = true;
+        }
+        expect(state.turnTerminated).toBe(true);
+      });
+    }
+  }
+
+  it("non-terminator tools stay non-terminator under MCP prefixing", () => {
+    // Make sure prefix-stripping doesn't accidentally promote arbitrary
+    // tools to terminators.
+    const nonTerminators = ALL_TOOLS.filter((t) => !t.endsTurn);
+    expect(nonTerminators.length).toBeGreaterThan(0);
+    for (const tool of nonTerminators.slice(0, 5)) {
+      for (const server of KNOWN_MCP_SERVERS) {
+        expect(isTurnTerminator(`mcp__${server}__${tool.name}`)).toBe(false);
+      }
+    }
+  });
+});

package/src/__tests__/handlers.test.ts

@@ -1731,45 +1731,103 @@ describe("handleAnimationMessage — downloads and enqueues", () => {
 });
 
 describe("processAndReply — onToolUse callback triggers appendDailyLogResponse", () => {
-  it("calls appendDailyLogResponse when execute invokes onToolUse with send tool", async () => {
-    const { appendDailyLogResponse } = await import("../storage/daily-log.js");
-
-    executeMock.mockImplementationOnce(
-      async (params: Record<string, unknown>) => {
-        // Simulate execute calling onToolUse with a "send" tool
-        const onToolUse = params.onToolUse as (
-          toolName: string,
-          input: Record<string, unknown>,
-        ) => void;
-        onToolUse?.("send", { type: "text", text: "Hello from Claude!" });
-        return {
-          text: "",
-          durationMs: 5,
-          inputTokens: 1,
-          outputTokens: 2,
-          cacheRead: 0,
-          cacheWrite: 0,
-          bridgeMessageCount: 1,
-        };
-      },
-    );
-
-    const ctx = {
-      chat: { id: 96001, type: "private" },
-      message: { text: "hi", message_id: 950, reply_to_message: null },
-      me: { id: 999, username: "testbot" },
-      from: { id: 93, first_name: "Yuki" },
-    } as any;
-
-    await handleTextMessage(ctx, mockBot, mockConfig);
-    await new Promise((r) => setTimeout(r, 700));
+  // The SDK emits MCP-prefixed tool names in production
+  // (`mcp__telegram-tools__send` etc.). Bare names like `send` are how the
+  // tool is registered but NOT what the handler actually receives. This
+  // test matrix exercises both shapes — the prefixed forms are what would
+  // catch a regression where the strip-prefix logic gets dropped.
+  const cases = [
+    {
+      label: "MCP-prefixed send (production shape)",
+      toolName: "mcp__telegram-tools__send",
+      input: { type: "text", text: "Production send text" },
+      expectedText: "Production send text",
+      shouldCapture: true,
+    },
+    {
+      label: "MCP-prefixed end_turn (production shape)",
+      toolName: "mcp__telegram-tools__end_turn",
+      input: { text: "Production end_turn text" },
+      expectedText: "Production end_turn text",
+      shouldCapture: true,
+    },
+    {
+      label: "bare send (defensive — registry-shape compat)",
+      toolName: "send",
+      input: { type: "text", text: "Bare send text" },
+      expectedText: "Bare send text",
+      shouldCapture: true,
+    },
+    {
+      label: "bare end_turn (defensive — registry-shape compat)",
+      toolName: "end_turn",
+      input: { text: "Bare end_turn text" },
+      expectedText: "Bare end_turn text",
+      shouldCapture: true,
+    },
+    {
+      label: "non-text send (photo) — should NOT capture",
+      toolName: "mcp__telegram-tools__send",
+      input: { type: "photo", file_path: "/x.jpg", caption: "ignored" },
+      expectedText: "",
+      shouldCapture: false,
+    },
+    {
+      label: "react tool — should NOT capture",
+      toolName: "mcp__telegram-tools__react",
+      input: { message_id: 1, emoji: "👍" },
+      expectedText: "",
+      shouldCapture: false,
+    },
+  ];
+
+  for (const c of cases) {
+    it(`${c.shouldCapture ? "captures" : "ignores"} ${c.label}`, async () => {
+      const { appendDailyLogResponse } =
+        await import("../storage/daily-log.js");
+      const mockedFn = vi.mocked(appendDailyLogResponse);
+      const before = mockedFn.mock.calls.length;
+
+      executeMock.mockImplementationOnce(
+        async (params: Record<string, unknown>) => {
+          const onToolUse = params.onToolUse as (
+            toolName: string,
+            input: Record<string, unknown>,
+          ) => void;
+          onToolUse?.(c.toolName, c.input);
+          return {
+            text: "",
+            durationMs: 5,
+            inputTokens: 1,
+            outputTokens: 2,
+            cacheRead: 0,
+            cacheWrite: 0,
+            bridgeMessageCount: 1,
+          };
+        },
+      );
 
-    expect(appendDailyLogResponse).toHaveBeenCalledWith(
-      "Talon",
-      "Hello from Claude!",
-      expect.anything(),
-    );
-  }, 3000);
+      const ctx = {
+        chat: { id: 96001, type: "private" },
+        message: { text: "hi", message_id: 950, reply_to_message: null },
+        me: { id: 999, username: "testbot" },
+        from: { id: 93, first_name: "Yuki" },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      await handleTextMessage(ctx, mockBot, mockConfig);
+      await new Promise((r) => setTimeout(r, 700));
+
+      const newCalls = mockedFn.mock.calls.slice(before);
+      if (c.shouldCapture) {
+        expect(newCalls).toHaveLength(1);
+        expect(newCalls[0][0]).toBe("Talon");
+        expect(newCalls[0][1]).toBe(c.expectedText);
+      } else {
+        expect(newCalls).toHaveLength(0);
+      }
+    }, 3000);
+  }
 });
 
 describe("createStreamCallbacks — onTextBlock delivers message via sendHtml", () => {

package/src/__tests__/integration/sdk-stub.test.ts

@@ -0,0 +1,208 @@
+/**
+ * End-to-end integration tests against the real Claude Agent SDK driving a
+ * stub `claude` binary (see `stub-claude/`).
+ *
+ * Unlike the unit tests in `src/__tests__/`, these don't `vi.mock` the SDK —
+ * the real `query()` runs, real subprocess spawn, real hook dispatcher, real
+ * stream-json protocol. The binary is replaced with a scripted stub so we
+ * can assert on what the SDK produces given known inputs.
+ *
+ * What this catches that unit tests can't:
+ *  - Bugs in our integration with the SDK's protocol shapes (e.g. the
+ *    MCP-prefix bug in `isTurnTerminator` would have surfaced here).
+ *  - Hook wiring — confirms options.hooks actually gets invoked by the SDK.
+ *  - Stream sequence handling against authentic message ordering.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  runWithStub,
+  cleanup,
+  assistantText,
+  assistantToolUse,
+  successResult,
+  fireHook,
+} from "./stub-claude/helpers.js";
+
+// On Windows the stub binary is a SEA-compiled `.exe` (built via
+// `npm run build:stub-sea`). On POSIX it's the `.mjs` source with shebang.
+// If the .exe isn't present (build step skipped), we skip the suite cleanly
+// rather than fail with `ENOENT`.
+import { existsSync } from "node:fs";
+import { resolve as resolvePath, dirname as dirnamePath } from "node:path";
+import { fileURLToPath as fileUrl } from "node:url";
+const __testDir = dirnamePath(fileUrl(import.meta.url));
+const stubBinaryPath = resolvePath(
+  __testDir,
+  process.platform === "win32"
+    ? "stub-claude/fake-claude.exe"
+    : "stub-claude/fake-claude.mjs",
+);
+const stubReady = existsSync(stubBinaryPath);
+
+describe.skipIf(!stubReady)("SDK integration (stub binary)", () => {
+  it("completes a simple text-only turn", async () => {
+    const result = await runWithStub({
+      prompt: "say hi",
+      script: {
+        turns: [
+          {
+            emit: [assistantText("hello from stub"), successResult("hello")],
+          },
+        ],
+      },
+    });
+
+    // Should have system init, assistant message, and result
+    const types = result.messages.map((m) => (m as { type: string }).type);
+    expect(types).toContain("system");
+    expect(types).toContain("assistant");
+    expect(types).toContain("result");
+
+    cleanup(result);
+  }, 15000);
+
+  it("yields assistant content blocks intact", async () => {
+    const result = await runWithStub({
+      prompt: "test",
+      script: {
+        turns: [
+          {
+            emit: [assistantText("specific text payload"), successResult()],
+          },
+        ],
+      },
+    });
+
+    const assistant = result.messages.find(
+      (m) => (m as { type: string }).type === "assistant",
+    ) as
+      | { message: { content: { type: string; text?: string }[] } }
+      | undefined;
+
+    expect(assistant).toBeDefined();
+    const text = assistant?.message.content.find((b) => b.type === "text");
+    expect(text?.text).toBe("specific text payload");
+
+    cleanup(result);
+  }, 15000);
+
+  it("invokes registered PostToolBatch hooks", async () => {
+    // The stub emits an assistant message with a tool_use, then synthesizes a
+    // PostToolBatch hook fire (via fireHook). The SDK should look up the
+    // callback id we registered during init and invoke our hook function.
+    const result = await runWithStub({
+      prompt: "trigger end_turn",
+      script: {
+        turns: [
+          {
+            emit: [
+              assistantToolUse("mcp__telegram-tools__end_turn", {
+                text: "delivered",
+              }),
+              fireHook("PostToolBatch", {
+                tool_calls: [
+                  {
+                    tool_name: "mcp__telegram-tools__end_turn",
+                    tool_input: { text: "delivered" },
+                    tool_use_id: "tu_1",
+                  },
+                ],
+              }),
+              successResult("delivered"),
+            ],
+          },
+        ],
+      },
+      sdkOptions: {
+        hooks: {
+          PostToolBatch: [
+            {
+              hooks: [
+                async () => ({
+                  continue: false,
+                  stopReason: "test: end_turn fired",
+                }),
+              ],
+            },
+          ],
+        },
+      },
+    });
+
+    expect(result.hookFires.PostToolBatch ?? 0).toBeGreaterThanOrEqual(1);
+
+    const calls = result.hookInputs.PostToolBatch ?? [];
+    const firstInput = calls[0] as
+      | { tool_calls: { tool_name: string }[] }
+      | undefined;
+    expect(firstInput?.tool_calls.map((tc) => tc.tool_name)).toContain(
+      "mcp__telegram-tools__end_turn",
+    );
+
+    cleanup(result);
+  }, 15000);
+
+  it("runs the production turn-terminator hook (PostToolBatch + isTurnTerminator)", async () => {
+    // This test composes the actual hook from `src/backend/claude-sdk/options.ts`
+    // — we reach into the module to grab it. If the hook implementation drifts
+    // from what the SDK calls, this test fails.
+    const { isTurnTerminator } = await import("../../core/tools/index.js");
+
+    const result = await runWithStub({
+      prompt: "drive end_turn through the real isTurnTerminator helper",
+      script: {
+        turns: [
+          {
+            emit: [
+              assistantToolUse("mcp__telegram-tools__end_turn", {
+                text: "ok",
+              }),
+              fireHook("PostToolBatch", {
+                tool_calls: [
+                  {
+                    tool_name: "mcp__telegram-tools__end_turn",
+                    tool_input: { text: "ok" },
+                    tool_use_id: "tu_1",
+                  },
+                ],
+              }),
+              successResult(),
+            ],
+          },
+        ],
+      },
+      sdkOptions: {
+        hooks: {
+          PostToolBatch: [
+            {
+              hooks: [
+                async (input) => {
+                  type Batch = {
+                    hook_event_name: string;
+                    tool_calls: { tool_name: string }[];
+                  };
+                  if ((input as Batch).hook_event_name !== "PostToolBatch") {
+                    return { continue: true };
+                  }
+                  const batch = input as Batch;
+                  const ended = batch.tool_calls.some((tc) =>
+                    isTurnTerminator(tc.tool_name),
+                  );
+                  return ended
+                    ? { continue: false, stopReason: "turn terminated" }
+                    : { continue: true };
+                },
+              ],
+            },
+          ],
+        },
+      },
+    });
+
+    // Hook should have fired exactly once and matched the MCP-prefixed name.
+    expect(result.hookFires.PostToolBatch).toBe(1);
+
+    cleanup(result);
+  }, 15000);
+});