talon-agent 1.9.1 → 1.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -51,13 +51,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.108",
+    "@anthropic-ai/sdk": "^0.95.0",
     "@brave/brave-search-mcp-server": "^2.0.75",
     "@clack/prompts": "^1.2.0",
     "@grammyjs/auto-retry": "^2.0.2",
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "^1.4.0",
-    "@playwright/mcp": "^0.0.70",
+    "@playwright/mcp": "^0.0.74",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
     "croner": "^10.0.1",
@@ -85,6 +86,6 @@
     "vitest": "^4.1.3"
   },
   "overrides": {
-    "@anthropic-ai/sdk": "^0.86.1"
+    "@anthropic-ai/sdk": "^0.95.0"
   }
 }

package/prompts/mempalace.md

@@ -7,6 +7,7 @@ You have access to a local memory palace via MCP tools. The palace stores verbat
 - **Wings** = top-level categories (people, projects, topics)
 - **Rooms** = specific subjects within a wing
 - **Drawers** = individual memory chunks (verbatim text)
+- **Tunnels** = cross-wing links between related rooms (auto-created in mempalace 3.3.4+ when topics overlap, plus manual)
 - **Knowledge Graph** = entity-relationship facts with temporal validity
 
 ### Protocol — FOLLOW EVERY SESSION
@@ -25,6 +26,7 @@ You have access to a local memory palace via MCP tools. The palace stores verbat
 - `mempalace_status` — Palace overview: total drawers, wings, rooms.
 - `mempalace_list_wings` / `mempalace_list_rooms` — Browse structure.
 - `mempalace_get_taxonomy` — Full wing/room/count tree.
+- `mempalace_get_aaak_spec` — Get the AAAK closet/compression spec. Only needed when reading/writing AAAK-compressed memories directly.
 
 **Knowledge Graph (Temporal Facts):**
 
@@ -34,24 +36,42 @@ You have access to a local memory palace via MCP tools. The palace stores verbat
 - `mempalace_kg_timeline` — Chronological story of an entity.
 - `mempalace_kg_stats` — Graph overview: entities, triples, relationship types.
 
-**Palace Graph (Cross-Domain Connections):**
+**Palace Graph & Cross-Wing Tunnels:**
 
 - `mempalace_traverse` — Walk from a room, find connected ideas across wings.
 - `mempalace_find_tunnels` — Find rooms that bridge two wings.
+- `mempalace_follow_tunnels` — From a specific (wing, room) pair, walk the outbound tunnels and see connected rooms with drawer previews.
+- `mempalace_create_tunnel` — Manually create a cross-wing tunnel between two (wing, room) pairs. Use when you spot a connection the auto-detector missed.
+- `mempalace_list_tunnels` — List tunnels (optionally filtered by wing).
+- `mempalace_delete_tunnel` — Remove a tunnel by ID when it's wrong or noisy.
 - `mempalace_graph_stats` — Graph connectivity overview.
 
-**Write:**
+**Drawers:**
 
 - `mempalace_add_drawer` — Store verbatim content into a wing/room. Auto-checks duplicates.
+- `mempalace_get_drawer` — Fetch a single drawer by ID. Returns full content + metadata. Use after a search hit when you need the verbatim text.
+- `mempalace_list_drawers` — Browse drawers in a wing/room with pagination (`limit`, `offset`). Use for inventory/cleanup, not search.
+- `mempalace_update_drawer` — Edit an existing drawer's content, wing, or room in place. Use to refine misfiled or stale entries instead of delete + re-add.
 - `mempalace_delete_drawer` — Remove a drawer by ID.
-- `mempalace_diary_write` — Write a session diary entry (agent_name, entry, topic).
-- `mempalace_diary_read` — Read recent diary entries.
+
+**Diary:**
+
+- `mempalace_diary_write` — Write a session diary entry (`agent_name`, `entry`, `topic`, optional `wing`).
+- `mempalace_diary_read` — Read recent diary entries. Optional `wing` filter scopes by project.
+
+**Maintenance:**
+
+- `mempalace_memories_filed_away` — Check whether a recent checkpoint was saved (message count, timestamp). Useful for confirming a stop-hook flush happened.
+- `mempalace_reconnect` — Force reconnect to the palace database. Run after external CLI/scripts modify the palace directly (the in-memory HNSW index can otherwise go stale).
+- `mempalace_hook_settings` — Toggle silent-save / desktop-toast for the auto-save hooks.
 
 ### Tips
 
 - Search is **semantic** (meaning-based), not keyword. "What did we discuss about database performance?" works better than "database".
 - The knowledge graph stores typed relationships with **time windows**. It knows WHEN things were true.
 - Use `mempalace_check_duplicate` before storing new content to avoid clutter.
+- **Tunnels auto-form** when drawers across different wings share topics (mempalace 3.3.4+). You don't have to wire connections by hand most of the time — but `mempalace_create_tunnel` is there when the auto-detector misses something obvious, and `mempalace_delete_tunnel` is there when it overreaches.
+- After updating facts via the CLI / external scripts, call `mempalace_reconnect` so the live MCP server picks up the changes.
 - Diary entries accumulate across sessions. Write them to build continuity of self.
 - Entity detection runs per-language; results include `created_at` timestamps you can surface when the user asks "when did I last…".
 

package/src/__tests__/log.test.ts

@@ -71,10 +71,11 @@ describe("log", () => {
       );
     });
 
-    it("includes Error message in context", () => {
-      logError("bridge", "request failed", new Error("timeout"));
+    it("includes Error message and stack in context", () => {
+      const err = new Error("timeout");
+      logError("bridge", "request failed", err);
       expect(mockError).toHaveBeenCalledWith(
-        { component: "bridge", err: "timeout" },
+        { component: "bridge", err: "timeout", stack: err.stack },
         "request failed",
       );
     });

package/src/__tests__/tool-functional.test.ts

@@ -0,0 +1,615 @@
+/**
+ * Functional tests for tool schemas + the Telegram action handler.
+ *
+ * Covers two wiring layers that have historically broken silently:
+ *
+ *   1. Tool definition → bridge call
+ *      `tool.execute(parsedParams, bridge)` must call the bridge
+ *      with the correct action name and the correct params shape.
+ *      Catches: action-name typos, missing param forwarding, and
+ *      multiplexed dispatch (e.g. `send` → 13 different bridge
+ *      actions depending on `type`).
+ *
+ *   2. Bridge → Telegram Bot API
+ *      `createTelegramActionHandler(...)` translates a bridge
+ *      action body into the right grammy `bot.api.*` call with
+ *      the right arguments. Catches: drift between the bridge
+ *      action name produced by a tool and the case label in the
+ *      handler switch, or wrong arg ordering.
+ *
+ * No real bot, no real network, no spawned processes. Pure
+ * in-process round trips with vi.fn() spies.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { z } from "zod";
+import { ALL_TOOLS } from "../core/tools/index.js";
+import type { ToolDefinition } from "../core/tools/types.js";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function getTool(name: string): ToolDefinition {
+  const tool = ALL_TOOLS.find((t) => t.name === name);
+  if (!tool) throw new Error(`tool ${name} not found in ALL_TOOLS`);
+  return tool;
+}
+
+/** Run the tool's zod schema over `raw` and return the parsed/coerced output. */
+function parseSchema(
+  tool: ToolDefinition,
+  raw: Record<string, unknown>,
+): Record<string, unknown> {
+  const obj = z.object(tool.schema as Record<string, z.ZodTypeAny>);
+  return obj.parse(raw) as Record<string, unknown>;
+}
+
+/** Build a vi-mocked bridge that records every call and returns ok. */
+function makeBridge() {
+  return vi.fn(async (_action: string, _params: Record<string, unknown>) => ({
+    ok: true,
+  }));
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Part A — Tool definition → bridge call
+// ════════════════════════════════════════════════════════════════════════════
+
+describe("Tool → bridge round-trip", () => {
+  // ── Single-action tools (1:1 with a bridge action name) ──────────────────
+  describe("single-action telegram tools", () => {
+    const cases: Array<{
+      tool: string;
+      params: Record<string, unknown>;
+      bridgeAction: string;
+      expectedParams?: Record<string, unknown>;
+    }> = [
+      {
+        tool: "react",
+        params: { message_id: 2081, emoji: "❤️" },
+        bridgeAction: "react",
+        expectedParams: { message_id: 2081, emoji: "❤️" },
+      },
+      {
+        tool: "edit_message",
+        params: { message_id: 2081, text: "edited" },
+        bridgeAction: "edit_message",
+        expectedParams: { message_id: 2081, text: "edited" },
+      },
+      {
+        tool: "delete_message",
+        params: { message_id: 2081 },
+        bridgeAction: "delete_message",
+        expectedParams: { message_id: 2081 },
+      },
+      {
+        tool: "forward_message",
+        params: { message_id: 2081 },
+        bridgeAction: "forward_message",
+      },
+      {
+        tool: "pin_message",
+        params: { message_id: 2081 },
+        bridgeAction: "pin_message",
+      },
+      {
+        tool: "unpin_message",
+        params: { message_id: 2081 },
+        bridgeAction: "unpin_message",
+      },
+      {
+        tool: "stop_poll",
+        params: { message_id: 2081 },
+        bridgeAction: "stop_poll",
+      },
+      {
+        tool: "get_member_info",
+        params: { user_id: 352042062 },
+        bridgeAction: "get_member_info",
+      },
+      {
+        tool: "get_message_by_id",
+        params: { message_id: 2081 },
+        bridgeAction: "get_message_by_id",
+      },
+      {
+        tool: "download_media",
+        params: { message_id: 2081 },
+        bridgeAction: "download_media",
+      },
+    ];
+
+    for (const c of cases) {
+      it(`${c.tool} → bridge("${c.bridgeAction}")`, async () => {
+        const tool = getTool(c.tool);
+        const bridge = makeBridge();
+        const parsed = parseSchema(tool, c.params);
+
+        await tool.execute(parsed, bridge);
+
+        expect(bridge).toHaveBeenCalledTimes(1);
+        const [action, params] = bridge.mock.calls[0]!;
+        expect(action).toBe(c.bridgeAction);
+        if (c.expectedParams) {
+          expect(params).toEqual(c.expectedParams);
+        }
+      });
+    }
+  });
+
+  // ── send tool dispatches to many bridge actions ──────────────────────────
+  describe("send tool dispatches by type", () => {
+    const cases: Array<{
+      label: string;
+      params: Record<string, unknown>;
+      bridgeAction: string;
+      paramShape?: (p: Record<string, unknown>) => void;
+    }> = [
+      {
+        label: "text",
+        params: { type: "text", text: "hello" },
+        bridgeAction: "send_message",
+        paramShape: (p) => {
+          expect(p.text).toBe("hello");
+        },
+      },
+      {
+        label: "text with reply_to",
+        params: { type: "text", text: "ok", reply_to: 2081 },
+        bridgeAction: "send_message",
+        paramShape: (p) => {
+          expect(p.reply_to_message_id).toBe(2081);
+        },
+      },
+      {
+        label: "text with buttons",
+        params: {
+          type: "text",
+          text: "choose",
+          buttons: [[{ text: "A", callback_data: "a" }]],
+        },
+        bridgeAction: "send_message_with_buttons",
+        paramShape: (p) => {
+          expect((p.rows as unknown[]).length).toBe(1);
+        },
+      },
+      {
+        label: "delayed text → schedule_message",
+        params: { type: "text", text: "later", delay_seconds: 60 },
+        bridgeAction: "schedule_message",
+        paramShape: (p) => {
+          expect(p.delay_seconds).toBe(60);
+        },
+      },
+      {
+        label: "photo",
+        params: { type: "photo", file_path: "/tmp/x.jpg", caption: "hi" },
+        bridgeAction: "send_photo",
+      },
+      {
+        label: "file",
+        params: { type: "file", file_path: "/tmp/x.pdf" },
+        bridgeAction: "send_file",
+      },
+      {
+        label: "video",
+        params: { type: "video", file_path: "/tmp/x.mp4" },
+        bridgeAction: "send_video",
+      },
+      {
+        label: "voice",
+        params: { type: "voice", file_path: "/tmp/x.ogg" },
+        bridgeAction: "send_voice",
+      },
+      {
+        label: "audio",
+        params: {
+          type: "audio",
+          file_path: "/tmp/song.mp3",
+          title: "T",
+          performer: "P",
+        },
+        bridgeAction: "send_audio",
+        paramShape: (p) => {
+          expect(p.title).toBe("T");
+          expect(p.performer).toBe("P");
+        },
+      },
+      {
+        label: "animation",
+        params: { type: "animation", file_path: "/tmp/x.gif" },
+        bridgeAction: "send_animation",
+      },
+      {
+        label: "sticker",
+        params: { type: "sticker", file_id: "CAACAgI..." },
+        bridgeAction: "send_sticker",
+      },
+      {
+        label: "poll",
+        params: {
+          type: "poll",
+          question: "Best?",
+          options: ["A", "B"],
+        },
+        bridgeAction: "send_poll",
+        paramShape: (p) => {
+          expect(p.question).toBe("Best?");
+          expect(p.type).toBe("regular");
+        },
+      },
+      {
+        label: "poll with correct_option_id → quiz",
+        params: {
+          type: "poll",
+          question: "Q?",
+          options: ["A", "B"],
+          correct_option_id: 1,
+        },
+        bridgeAction: "send_poll",
+        paramShape: (p) => {
+          expect(p.type).toBe("quiz");
+        },
+      },
+      {
+        label: "location",
+        params: { type: "location", latitude: 53.15, longitude: -6.07 },
+        bridgeAction: "send_location",
+      },
+      {
+        label: "contact",
+        params: {
+          type: "contact",
+          phone_number: "+1234",
+          first_name: "Test",
+        },
+        bridgeAction: "send_contact",
+      },
+      {
+        label: "dice",
+        params: { type: "dice" },
+        bridgeAction: "send_dice",
+      },
+    ];
+
+    for (const c of cases) {
+      it(`send(${c.label}) → bridge("${c.bridgeAction}")`, async () => {
+        const tool = getTool("send");
+        const bridge = makeBridge();
+        const parsed = parseSchema(tool, c.params);
+
+        await tool.execute(parsed, bridge);
+
+        expect(bridge).toHaveBeenCalledTimes(1);
+        const [action, params] = bridge.mock.calls[0]!;
+        expect(action).toBe(c.bridgeAction);
+        if (c.paramShape) c.paramShape(params as Record<string, unknown>);
+      });
+    }
+  });
+
+  // ── Coercion goes end-to-end through execute() ───────────────────────────
+  describe("ID coercion survives the schema → execute pipeline", () => {
+    it("react with stringified message_id arrives at bridge as a number", async () => {
+      const tool = getTool("react");
+      const bridge = makeBridge();
+      const parsed = parseSchema(tool, {
+        message_id: "2081",
+        emoji: "❤️",
+      });
+
+      await tool.execute(parsed, bridge);
+
+      const [, params] = bridge.mock.calls[0]!;
+      expect((params as { message_id: unknown }).message_id).toBe(2081);
+      expect(typeof (params as { message_id: unknown }).message_id).toBe(
+        "number",
+      );
+    });
+
+    it("send.reply_to with stringified value survives to send_message", async () => {
+      const tool = getTool("send");
+      const bridge = makeBridge();
+      const parsed = parseSchema(tool, {
+        type: "text",
+        text: "hi",
+        reply_to: "2081",
+      });
+
+      await tool.execute(parsed, bridge);
+
+      const [, params] = bridge.mock.calls[0]!;
+      expect(
+        (params as { reply_to_message_id: unknown }).reply_to_message_id,
+      ).toBe(2081);
+    });
+
+    it("get_member_info with stringified user_id arrives as number", async () => {
+      const tool = getTool("get_member_info");
+      const bridge = makeBridge();
+      const parsed = parseSchema(tool, { user_id: "352042062" });
+
+      await tool.execute(parsed, bridge);
+
+      const [, params] = bridge.mock.calls[0]!;
+      expect((params as { user_id: unknown }).user_id).toBe(352042062);
+    });
+  });
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+// Part B — Telegram action handler → grammy Bot API
+// ════════════════════════════════════════════════════════════════════════════
+
+import {
+  createTelegramActionHandler,
+  // re-export for test side-only — handler depends on the InputFile constructor
+} from "../frontend/telegram/actions.js";
+import type { Bot } from "grammy";
+import type { Gateway } from "../core/gateway.js";
+
+interface BotApiSpy {
+  setMessageReaction: ReturnType<typeof vi.fn>;
+  editMessageText: ReturnType<typeof vi.fn>;
+  deleteMessage: ReturnType<typeof vi.fn>;
+  pinChatMessage: ReturnType<typeof vi.fn>;
+  unpinChatMessage: ReturnType<typeof vi.fn>;
+  forwardMessage: ReturnType<typeof vi.fn>;
+  copyMessage: ReturnType<typeof vi.fn>;
+  sendMessage: ReturnType<typeof vi.fn>;
+  sendChatAction: ReturnType<typeof vi.fn>;
+}
+
+function makeBotSpy(): { bot: Bot; api: BotApiSpy } {
+  const api: BotApiSpy = {
+    setMessageReaction: vi.fn(async () => true),
+    editMessageText: vi.fn(async () => ({ message_id: 1 })),
+    deleteMessage: vi.fn(async () => true),
+    pinChatMessage: vi.fn(async () => true),
+    unpinChatMessage: vi.fn(async () => true),
+    forwardMessage: vi.fn(async () => ({ message_id: 999 })),
+    copyMessage: vi.fn(async () => ({ message_id: 1000 })),
+    sendMessage: vi.fn(async () => ({ message_id: 1001 })),
+    sendChatAction: vi.fn(async () => true),
+  };
+  const bot = { api } as unknown as Bot;
+  return { bot, api };
+}
+
+function makeGateway(): Gateway {
+  return {
+    incrementMessages: vi.fn(),
+    incrementErrors: vi.fn(),
+    incrementRetries: vi.fn(),
+    incrementSuccess: vi.fn(),
+  } as unknown as Gateway;
+}
+
+class StubInputFile {
+  // Match the grammy InputFile shape just enough for `new InputFileClass(...)`.
+  data: unknown;
+  filename: string;
+  constructor(data: unknown, filename: string) {
+    this.data = data;
+    this.filename = filename;
+  }
+}
+
+describe("createTelegramActionHandler", () => {
+  let bot: Bot;
+  let api: BotApiSpy;
+  let gateway: Gateway;
+  let handler: ReturnType<typeof createTelegramActionHandler>;
+  const chatId = 12345;
+
+  beforeEach(() => {
+    const spy = makeBotSpy();
+    bot = spy.bot;
+    api = spy.api;
+    gateway = makeGateway();
+    handler = createTelegramActionHandler(
+      bot,
+      StubInputFile as unknown as typeof import("grammy").InputFile,
+      "fake-token",
+      gateway,
+    );
+  });
+
+  it("react → bot.api.setMessageReaction with chatId, message_id, emoji", async () => {
+    const result = await handler(
+      { action: "react", message_id: 2081, emoji: "❤️" },
+      chatId,
+    );
+
+    expect(api.setMessageReaction).toHaveBeenCalledTimes(1);
+    expect(api.setMessageReaction).toHaveBeenCalledWith(chatId, 2081, [
+      { type: "emoji", emoji: "❤️" },
+    ]);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("react with stringified message_id (post-coercion) still calls bot.api correctly", async () => {
+    // Even if something upstream skipped coercion and delivered a string,
+    // the handler does Number(body.message_id) and recovers.
+    await handler({ action: "react", message_id: "2081", emoji: "🔥" }, chatId);
+
+    expect(api.setMessageReaction).toHaveBeenCalledWith(chatId, 2081, [
+      { type: "emoji", emoji: "🔥" },
+    ]);
+  });
+
+  it("react falls back to 👍 if custom emoji rejected, and reports ok", async () => {
+    const seen: string[] = [];
+    api.setMessageReaction.mockImplementation(
+      async (
+        _chatId: number,
+        _msgId: number,
+        reactions: Array<{ type: string; emoji: string }>,
+      ) => {
+        seen.push(reactions[0]!.emoji);
+        if (reactions[0]!.emoji === "🦄") {
+          throw new Error("REACTION_INVALID");
+        }
+        return true;
+      },
+    );
+
+    const result = await handler(
+      { action: "react", message_id: 1, emoji: "🦄" },
+      chatId,
+    );
+
+    expect(api.setMessageReaction).toHaveBeenCalledTimes(2);
+    expect(seen).toEqual(["🦄", "👍"]);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("delete_message → bot.api.deleteMessage(chatId, message_id)", async () => {
+    const result = await handler(
+      { action: "delete_message", message_id: 2081 },
+      chatId,
+    );
+
+    expect(api.deleteMessage).toHaveBeenCalledWith(chatId, 2081);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("pin_message → bot.api.pinChatMessage(chatId, message_id)", async () => {
+    await handler({ action: "pin_message", message_id: 2081 }, chatId);
+    expect(api.pinChatMessage).toHaveBeenCalledWith(chatId, 2081);
+  });
+
+  it("unpin_message → bot.api.unpinChatMessage(chatId, message_id?)", async () => {
+    await handler({ action: "unpin_message", message_id: 2081 }, chatId);
+    expect(api.unpinChatMessage).toHaveBeenCalledWith(chatId, 2081);
+
+    api.unpinChatMessage.mockClear();
+    await handler({ action: "unpin_message" }, chatId);
+    expect(api.unpinChatMessage).toHaveBeenCalledWith(chatId, undefined);
+  });
+
+  it("forward_message → bot.api.forwardMessage(chatId, chatId, message_id)", async () => {
+    const result = await handler(
+      { action: "forward_message", message_id: 2081 },
+      chatId,
+    );
+
+    expect(api.forwardMessage).toHaveBeenCalledWith(chatId, chatId, 2081);
+    expect(result).toEqual({ ok: true, message_id: 999 });
+  });
+
+  it("forward_message rejects cross-chat targets", async () => {
+    const result = await handler(
+      { action: "forward_message", message_id: 2081, to_chat_id: 99999 },
+      chatId,
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: "Cross-chat forwarding not allowed.",
+    });
+    expect(api.forwardMessage).not.toHaveBeenCalled();
+  });
+
+  it("copy_message → bot.api.copyMessage(chatId, chatId, message_id)", async () => {
+    const result = await handler(
+      { action: "copy_message", message_id: 2081 },
+      chatId,
+    );
+
+    expect(api.copyMessage).toHaveBeenCalledWith(chatId, chatId, 2081);
+    expect(result).toEqual({ ok: true, message_id: 1000 });
+  });
+
+  it("edit_message → bot.api.editMessageText(chatId, message_id, html, opts)", async () => {
+    await handler(
+      { action: "edit_message", message_id: 2081, text: "**bold**" },
+      chatId,
+    );
+
+    expect(api.editMessageText).toHaveBeenCalledTimes(1);
+    const call = api.editMessageText.mock.calls[0]!;
+    expect(call[0]).toBe(chatId);
+    expect(call[1]).toBe(2081);
+    expect(typeof call[2]).toBe("string");
+    expect(call[3]).toEqual({ parse_mode: "HTML" });
+  });
+
+  it("edit_message rejects text > TELEGRAM_MAX_TEXT (4096)", async () => {
+    const longText = "x".repeat(5000);
+    const result = await handler(
+      { action: "edit_message", message_id: 2081, text: longText },
+      chatId,
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: "Text too long (max 4096)",
+    });
+    expect(api.editMessageText).not.toHaveBeenCalled();
+  });
+
+  it("send_chat_action → bot.api.sendChatAction(chatId, action_str)", async () => {
+    await handler(
+      { action: "send_chat_action", chat_action: "typing" },
+      chatId,
+    );
+    expect(api.sendChatAction).toHaveBeenCalledWith(chatId, "typing");
+  });
+
+  it("send_message → withRetry → bot.api.sendMessage with HTML and reply_to", async () => {
+    const result = await handler(
+      {
+        action: "send_message",
+        text: "hello",
+        reply_to_message_id: 2081,
+      },
+      chatId,
+    );
+
+    expect(api.sendMessage).toHaveBeenCalledTimes(1);
+    expect(gateway.incrementMessages).toHaveBeenCalledWith(chatId);
+    const call = api.sendMessage.mock.calls[0]!;
+    expect(call[0]).toBe(chatId);
+    expect(typeof call[1]).toBe("string");
+    expect(call[2]).toMatchObject({
+      reply_parameters: { message_id: 2081 },
+      parse_mode: "HTML",
+    });
+    expect(result).toEqual({ ok: true, message_id: 1001 });
+  });
+
+  it("schedule_message returns a schedule id and keeps a timer", async () => {
+    vi.useFakeTimers();
+    try {
+      const result = (await handler(
+        {
+          action: "schedule_message",
+          text: "later",
+          delay_seconds: 5,
+        },
+        chatId,
+      )) as { ok: true; schedule_id: string; delay_seconds: number };
+
+      expect(result.ok).toBe(true);
+      expect(result.delay_seconds).toBe(5);
+      expect(typeof result.schedule_id).toBe("string");
+
+      // Cancel before it fires so we don't leak a real send.
+      const cancel = await handler(
+        { action: "cancel_scheduled", schedule_id: result.schedule_id },
+        chatId,
+      );
+      expect(cancel).toEqual({ ok: true, cancelled: true });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("cancel_scheduled with unknown id returns ok:false", async () => {
+    const result = await handler(
+      { action: "cancel_scheduled", schedule_id: "nonexistent" },
+      chatId,
+    );
+    expect(result).toEqual({ ok: false, error: "Schedule not found" });
+  });
+});

package/src/__tests__/tool-id-coercion.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Regression + audit tests — ID-shaped tool params use the strict
+ * shared `idSchema` from `core/tools/schemas.ts`.
+ *
+ * Background: some MCP transport / model paths deliver `message_id`,
+ * `user_id`, `reply_to`, `offset_id` as JSON strings ("2081") rather
+ * than numbers (2081). Plain `z.number()` rejects those with
+ * `expected number, received string`, which manifested as
+ * `react`/`pin_message`/`get_member_info`/`download_media` failing
+ * out of nowhere even when the model formatted the call correctly
+ * for a number-typed JSON Schema field.
+ *
+ * Initial fix used `z.coerce.number().int()`, but per Copilot review
+ * that was too lax — `""`/`null` coerce to 0 and `true` to 1, which
+ * then pass `.int()` and reach the bot API. The current `idSchema` is
+ * a union: `z.number().int().positive()` OR a digit-only string that
+ * gets transformed to a positive integer. Everything else is rejected.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { ALL_TOOLS } from "../core/tools/index.js";
+
+const ID_FIELD_NAMES = new Set([
+  "message_id",
+  "user_id",
+  "reply_to",
+  "offset_id",
+]);
+
+function getIdSchema(toolName: string, field: string): z.ZodTypeAny {
+  const tool = ALL_TOOLS.find((t) => t.name === toolName);
+  if (!tool) throw new Error(`tool ${toolName} not found`);
+  const schema = (tool.schema as Record<string, z.ZodTypeAny>)[field];
+  if (!schema) throw new Error(`field ${field} not found on ${toolName}`);
+  return schema;
+}
+
+describe("ID-shaped tool params accept stringified numbers", () => {
+  // Spot-check a representative set across all four files.
+  const cases: Array<[string, string]> = [
+    ["react", "message_id"],
+    ["edit_message", "message_id"],
+    ["delete_message", "message_id"],
+    ["forward_message", "message_id"],
+    ["pin_message", "message_id"],
+    ["unpin_message", "message_id"],
+    ["stop_poll", "message_id"],
+    ["send", "reply_to"],
+    ["get_member_info", "user_id"],
+    ["create_sticker_set", "user_id"],
+    ["add_sticker_to_set", "user_id"],
+    ["read_chat_history", "offset_id"],
+    ["get_message_by_id", "message_id"],
+    ["download_media", "message_id"],
+  ];
+
+  for (const [tool, field] of cases) {
+    it(`${tool}.${field} accepts a number`, () => {
+      const s = getIdSchema(tool, field);
+      const out = s.parse(2081);
+      expect(out).toBe(2081);
+    });
+
+    it(`${tool}.${field} accepts a numeric string and coerces it`, () => {
+      const s = getIdSchema(tool, field);
+      const out = s.parse("2081");
+      expect(out).toBe(2081);
+    });
+
+    it(`${tool}.${field} rejects a non-numeric string`, () => {
+      const s = getIdSchema(tool, field);
+      expect(() => s.parse("abc")).toThrow();
+    });
+
+    it(`${tool}.${field} rejects a non-integer`, () => {
+      const s = getIdSchema(tool, field);
+      expect(() => s.parse(1.5)).toThrow();
+    });
+  }
+});
+
+describe("Audit: every ID-shaped field in tool schemas is the strict idSchema", () => {
+  /**
+   * For each ID field on every tool, this test asserts the full
+   * accept/reject contract of `idSchema` — not just "accepts a
+   * string." That guards against a future replacement that passes
+   * the loose check (`safeParse("123")` succeeds) but doesn't
+   * actually return a positive integer (e.g. `z.string()` would
+   * accept "123" and return the string "123").
+   */
+  for (const tool of ALL_TOOLS) {
+    const schema = tool.schema as Record<string, unknown>;
+    for (const field of Object.keys(schema)) {
+      if (!ID_FIELD_NAMES.has(field)) continue;
+      const zSchema = schema[field] as z.ZodTypeAny;
+
+      it(`${tool.name}.${field}: accepts a positive integer number`, () => {
+        const r = zSchema.safeParse(2081);
+        expect(r.success).toBe(true);
+        if (r.success) expect(r.data).toBe(2081);
+      });
+
+      it(`${tool.name}.${field}: accepts a digit string and returns a number`, () => {
+        const r = zSchema.safeParse("2081");
+        expect(r.success).toBe(true);
+        if (r.success) {
+          expect(typeof r.data).toBe("number");
+          expect(Number.isInteger(r.data as number)).toBe(true);
+          expect(r.data).toBe(2081);
+        }
+      });
+
+      // Reject the inputs that bare `z.coerce.number().int()` was too
+      // permissive about — empty/whitespace/null/booleans coerce to
+      // 0/0/0/1 and would pass `.int()`. The strict union rejects all.
+      const rejectCases: Array<[unknown, string]> = [
+        ["", "empty string"],
+        ["   ", "whitespace string"],
+        ["abc", "non-numeric string"],
+        ["2081abc", "mixed string"],
+        [null, "null"],
+        [true, "true"],
+        [false, "false"],
+        [0, "zero"],
+        [-1, "negative integer"],
+        [1.5, "non-integer"],
+      ];
+      for (const [bad, label] of rejectCases) {
+        it(`${tool.name}.${field}: rejects ${label}`, () => {
+          const r = zSchema.safeParse(bad);
+          expect(r.success).toBe(false);
+        });
+      }
+    }
+  }
+});

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

@@ -227,10 +227,9 @@ export async function handleMessage(
   // ── Build result ──────────────────────────────────────────────────────────
 
   state.allResponseText += state.currentBlockText;
-  const totalPrompt =
-    state.sdkInputTokens + state.sdkCacheRead + state.sdkCacheWrite;
+  const cacheTotal = state.sdkInputTokens + state.sdkCacheRead;
   const cacheHitPct =
-    totalPrompt > 0 ? Math.round((state.sdkCacheRead / totalPrompt) * 100) : 0;
+    cacheTotal > 0 ? Math.round((state.sdkCacheRead / cacheTotal) * 100) : 0;
 
   log(
     "agent",

package/src/core/gateway.ts

@@ -267,9 +267,19 @@ export class Gateway {
           res.end(json);
         } catch (err) {
           if (res.headersSent) return;
-          const msg = err instanceof Error ? err.message : String(err);
+          // Log full error (incl. stack via logError's structured `stack`
+          // field) on the server; return a generic message to the client so
+          // we don't leak implementation details.
+          // CodeQL: js/stack-trace-exposure (alert #4).
+          logError(
+            "gateway",
+            `Unhandled error on ${req.method} ${req.url}`,
+            err,
+          );
           res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: false, error: msg }));
+          res.end(
+            JSON.stringify({ ok: false, error: "Internal server error" }),
+          );
         }
       },
     );

package/src/core/tools/history.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 import type { ToolDefinition } from "./types.js";
+import { idSchema } from "./schemas.js";
 
 export const historyTools: ToolDefinition[] = [
   {
@@ -19,7 +20,7 @@ export const historyTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe("Fetch messages before this date (ISO format)"),
-      offset_id: z.number().optional().describe("Fetch before this message ID"),
+      offset_id: idSchema.optional().describe("Fetch before this message ID"),
     },
     execute: (params, bridge) =>
       bridge("read_history", {
@@ -58,7 +59,7 @@ export const historyTools: ToolDefinition[] = [
   {
     name: "get_message_by_id",
     description: "Get a specific message by ID.",
-    schema: { message_id: z.number() },
+    schema: { message_id: idSchema },
     execute: (params, bridge) => bridge("get_message_by_id", params),
     frontends: ["telegram"],
     tag: "history",
@@ -69,9 +70,9 @@ export const historyTools: ToolDefinition[] = [
     description:
       "Download a photo, document, or other media from a message by its ID. Saves the file to the workspace and returns the file path so you can read/analyze it. Use this when you see a [photo] or [document] in chat history but don't have the file.",
     schema: {
-      message_id: z
-        .number()
-        .describe("Message ID containing the media to download"),
+      message_id: idSchema.describe(
+        "Message ID containing the media to download",
+      ),
     },
     execute: (params, bridge) => bridge("download_media", params),
     frontends: ["telegram"],

package/src/core/tools/members.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 import type { ToolDefinition } from "./types.js";
+import { idSchema } from "./schemas.js";
 
 export const memberTools: ToolDefinition[] = [
   {
@@ -19,7 +20,7 @@ export const memberTools: ToolDefinition[] = [
   {
     name: "get_member_info",
     description: "Get detailed info about a user by ID.",
-    schema: { user_id: z.number() },
+    schema: { user_id: idSchema },
     execute: (params, bridge) => bridge("get_member_info", params),
     frontends: ["telegram"],
     tag: "members",

package/src/core/tools/messaging.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 import type { ToolDefinition } from "./types.js";
+import { idSchema } from "./schemas.js";
 
 export const messagingTools: ToolDefinition[] = [
   // ── Telegram unified send ─────────────────────────────────────────────
@@ -43,7 +44,7 @@ Examples:
         .string()
         .optional()
         .describe("Message text (for type=text). Supports Markdown."),
-      reply_to: z.number().optional().describe("Message ID to reply to"),
+      reply_to: idSchema.optional().describe("Message ID to reply to"),
       file_path: z
         .string()
         .optional()
@@ -227,7 +228,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
     description:
       "Add an emoji reaction to a message. Valid: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉 🤩 🤮 💩 🙏 👌 🕊 🤡 🥱 🥴 😍 🐳 ❤‍🔥 🌚 🌭 💯 🤣 ⚡ 🍌 🏆 💔 🤨 😐 🍓 🍾 💋 🖕 😈 😴 😭 🤓 👻 👨‍💻 👀 🎃 🙈 😇 😨 🤝 ✍ 🤗 🫡 🎅 🎄 ☃ 💅 🤪 🗿 🆒 💘 🙉 🦄 😘 💊 🙊 😎 👾 🤷 🤷‍♂ 🤷‍♀ 😡",
     schema: {
-      message_id: z.number().describe("Message ID"),
+      message_id: idSchema.describe("Message ID"),
       emoji: z.string().describe("Reaction emoji"),
     },
     execute: (params, bridge) => bridge("react", params),
@@ -239,7 +240,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
   {
     name: "edit_message",
     description: "Edit a previously sent message.",
-    schema: { message_id: z.number(), text: z.string() },
+    schema: { message_id: idSchema, text: z.string() },
     execute: (params, bridge) => bridge("edit_message", params),
     frontends: ["telegram"],
     tag: "messaging",
@@ -249,7 +250,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
   {
     name: "delete_message",
     description: "Delete a message.",
-    schema: { message_id: z.number() },
+    schema: { message_id: idSchema },
     execute: (params, bridge) => bridge("delete_message", params),
     frontends: ["telegram"],
     tag: "messaging",
@@ -259,7 +260,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
   {
     name: "forward_message",
     description: "Forward a message within the chat.",
-    schema: { message_id: z.number() },
+    schema: { message_id: idSchema },
     execute: (params, bridge) => bridge("forward_message", params),
     frontends: ["telegram"],
     tag: "messaging",
@@ -269,7 +270,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
   {
     name: "pin_message",
     description: "Pin a message.",
-    schema: { message_id: z.number() },
+    schema: { message_id: idSchema },
     execute: (params, bridge) => bridge("pin_message", params),
     frontends: ["telegram"],
     tag: "messaging",
@@ -279,7 +280,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
   {
     name: "unpin_message",
     description: "Unpin a message.",
-    schema: { message_id: z.number().optional() },
+    schema: { message_id: idSchema.optional() },
     execute: (params, bridge) => bridge("unpin_message", params),
     frontends: ["telegram"],
     tag: "messaging",
@@ -291,7 +292,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
     description:
       "Stop an active poll and get the final results. Returns vote counts for each option.",
     schema: {
-      message_id: z.number().describe("Message ID of the poll to stop"),
+      message_id: idSchema.describe("Message ID of the poll to stop"),
     },
     execute: (params, bridge) => bridge("stop_poll", params),
     frontends: ["telegram"],

package/src/core/tools/schemas.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared zod schema fragments for tool input definitions.
+ */
+
+import { z } from "zod";
+
+/**
+ * Telegram-style positive integer ID (message_id, user_id, reply_to,
+ * offset_id, etc.).
+ *
+ * Accepts:
+ *   - actual numbers that are positive integers (`2081`)
+ *   - digit-only strings (`"2081"`) which are transformed into numbers
+ *
+ * Rejects:
+ *   - non-numeric strings (`"abc"`, `"2081abc"`, `""`, `"   "`)
+ *   - booleans, `null`, `undefined` (would otherwise coerce to 0/1)
+ *   - non-integer numbers (`1.5`)
+ *   - zero and negatives
+ *
+ * Use this instead of `z.number()` or `z.coerce.number()` for any ID
+ * field on tool input schemas. The plain coercion path was too lax —
+ * `z.coerce.number().int()` happily turns `null`/`""` into `0` and
+ * `true` into `1`, both of which the Telegram bot API would then
+ * dispatch to. The strict union avoids that.
+ */
+export const idSchema = z.union([
+  z.number().int().positive(),
+  z
+    .string()
+    .regex(/^\d+$/, "must be a positive integer")
+    .transform((s) => Number(s))
+    .pipe(z.number().int().positive()),
+]);

package/src/core/tools/stickers.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 import type { ToolDefinition } from "./types.js";
+import { idSchema } from "./schemas.js";
 
 export const stickerTools: ToolDefinition[] = [
   {
@@ -56,7 +57,7 @@ The set name will automatically get "_by_<botname>" appended if needed.
 
 Example: create_sticker_set(user_id=123, name="cool_pack", title="Cool Stickers", file_path="/path/to/sticker.png", emoji_list=["😎"])`,
     schema: {
-      user_id: z.number().describe("Telegram user ID who will own the pack"),
+      user_id: idSchema.describe("Telegram user ID who will own the pack"),
       name: z
         .string()
         .describe(
@@ -85,7 +86,7 @@ Example: create_sticker_set(user_id=123, name="cool_pack", title="Cool Stickers"
     description:
       "Add a new sticker to an existing sticker pack created by the bot.",
     schema: {
-      user_id: z.number().describe("Telegram user ID who owns the pack"),
+      user_id: idSchema.describe("Telegram user ID who owns the pack"),
       name: z.string().describe("Sticker set name (including _by_<botname>)"),
       file_path: z.string().describe("Path to the sticker image file"),
       emoji_list: z

package/src/frontend/telegram/commands.ts

@@ -529,10 +529,9 @@ export function registerCommands(
       "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
     const contextWarn = ctxPct >= 80 ? " \u26A0\uFE0F consider /reset" : "";
 
-    const totalPrompt =
-      displayInputTokens + displayCacheRead + displayCacheWrite;
+    const cacheTotal = displayInputTokens + displayCacheRead;
     const cacheHitPct =
-      totalPrompt > 0 ? Math.round((displayCacheRead / totalPrompt) * 100) : 0;
+      cacheTotal > 0 ? Math.round((displayCacheRead / cacheTotal) * 100) : 0;
 
     const avgResponseMs =
       info.turns > 0 && u.totalResponseMs

package/src/util/log.ts

@@ -128,7 +128,10 @@ export function logError(
   err?: unknown,
 ): void {
   if (err instanceof Error) {
-    logger.error({ component, err: err.message }, message);
+    // Capture both the concise message (for log consumers that look at `err`)
+    // and the full stack (for diagnostics). pino-pretty renders the `stack`
+    // field on its own line; JSON consumers can read either field.
+    logger.error({ component, err: err.message, stack: err.stack }, message);
   } else if (err !== undefined) {
     logger.error({ component, err: String(err) }, message);
   } else {