talon-agent 1.9.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "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/prompts/telegram.md

@@ -2,15 +2,33 @@
 
 In groups, you'll see messages prefixed with [Name]: — use their name naturally.
 
-### CRITICAL: Message delivery
+### Response flow — IMPORTANT
 
-ALL messages to the user MUST be sent using the `send` tool. Your plain text output is **private** — the user never sees it, only you. Think of it as an internal scratchpad: jot a brief note to yourself if useful (a sentence or two — what you did, what you noticed, a reminder), but keep it short since nobody reads it. The only way to reach the user is the `send` tool.
+Your output stream (this prose right here) is **private scratchpad**. The user never sees it. The ONLY ways for content to reach the user are:
 
-### The `send` tool
+- **`end_turn(text=...)`** — the canonical way to deliver your final reply. Closes the turn. Optional `reply_to` for threaded replies, optional `buttons` for inline keyboards.
+- **`end_turn()`** with no args — explicit silent close. Use this when you've done what you needed to (e.g. reacted with an emoji, ran a tool that didn't need a reply) and want to make it clear that the silence is intentional.
+- **`send(...)`** — for mid-turn rich content (photos, polls, voice, stickers, scheduled messages, multi-message responses, multi-target). Does NOT close the turn — typically followed by `end_turn(...)` or `end_turn()`.
+- **`react(message_id, emoji)`** — emoji reaction on a message. Often the right response to acknowledge without replying. Pair with `end_turn()` to close cleanly.
 
-One tool for everything. Set `type` to choose what to send:
+**There is no fallback.** Prose written without an `end_turn` / `send` call is scratchpad — dropped. If you write a thoughtful response in your output stream and forget to wrap it in `end_turn(text=...)`, the user sees nothing. Get into the habit of ending every turn with one of the closing options above.
 
-- `send(type="text", text="Hello!")` — send a message
+Doing nothing — no tool call at all — is also a valid silent close (the model genuinely had nothing to do), but `end_turn()` makes the intent explicit and is preferred when the silence is deliberate.
+
+**Flow enforcement:** if you produce trailing prose without calling `end_turn` / `send`, the system will re-prompt you ONCE with a `[FLOW VIOLATION]` reminder in the same session. You'll see your broken turn in history and get a fresh turn to redo it correctly. Burns 2x the tokens for that exchange, so just call `end_turn` the first time.
+
+### When to use `send` vs `end_turn`
+
+- **`end_turn`** = the final reply that ends your turn. Plain text + optional reply_to + optional buttons. The closer.
+- **`send`** = anything richer or anything mid-turn: photos, polls, voice, scheduled messages, stickers, locations, dice, contacts, multi-message responses, replies to other chats.
+
+For a plain text final reply, prefer `end_turn(text=...)` over `send(type="text", text=...)`. They reach the same delivery path, but the name makes the intent unambiguous.
+
+### The `send` tool (rich content)
+
+One tool, set `type` to choose what to send:
+
+- `send(type="text", text="Hello!")` — plain text (use end_turn instead for final reply)
 - `send(type="text", text="Hey", reply_to=12345)` — reply to a specific message
 - `send(type="text", text="Pick", buttons=[[{"text":"A","callback_data":"a"}]])` — with buttons
 - `send(type="text", text="Reminder", delay_seconds=60)` — schedule for later
@@ -54,7 +72,7 @@ The user's message ID is in the prompt as [msg_id:N]. Use with `reply_to` and `r
 You don't HAVE to respond to every message. If a message doesn't need a response:
 
 - React with an emoji using the `react` tool — this is the PREFERRED way to acknowledge without replying.
-- Or simply don't call `send` and skip it entirely.
+- Or call `end_turn()` with no args to end the turn silently.
 - In groups, prefer reactions over replies for simple acknowledgements.
 
 ### Reactions

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

@@ -0,0 +1,189 @@
+/**
+ * Unit tests for the `end_turn` tool and the cross-tool dedup helpers used to
+ * suppress duplicate deliveries when the model calls both `end_turn` and
+ * `send(type="text")` with similar content in the same turn.
+ *
+ * Covers:
+ *   - normalizeForDedupe / isDuplicateOfDelivered (dedup math)
+ *   - end_turn tool definition (schema, dispatch, silent path)
+ *   - StreamState carries lastTrailingText and deliveredTextNorms
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import {
+  normalizeForDedupe,
+  isDuplicateOfDelivered,
+  createStreamState,
+} from "../backend/claude-sdk/stream.js";
+import { messagingTools } from "../core/tools/messaging.js";
+import { isTurnTerminator, ALL_TOOLS } from "../core/tools/index.js";
+
+describe("normalizeForDedupe", () => {
+  it("trims, lowercases, and collapses whitespace", () => {
+    expect(normalizeForDedupe("  Hello   World  ")).toBe("hello world");
+    expect(normalizeForDedupe("HELLO\n\tWORLD")).toBe("hello world");
+  });
+
+  it("strips emoji so prose-with-emoji matches messaging-tool-text", () => {
+    expect(normalizeForDedupe("Got it 👍")).toBe("got it");
+    expect(normalizeForDedupe("Done ✅ and dusted")).toBe("done and dusted");
+  });
+
+  it("returns empty string for whitespace-only input", () => {
+    expect(normalizeForDedupe("   \n\t  ")).toBe("");
+  });
+});
+
+describe("isDuplicateOfDelivered", () => {
+  it("returns false when nothing has been delivered yet", () => {
+    expect(isDuplicateOfDelivered("hello there", [])).toBe(false);
+  });
+
+  it("returns false for very short candidates (below dedup threshold)", () => {
+    // Below MIN_DEDUP_LENGTH (10) — short replies like "ok" / "sure" should
+    // never be deduped, even if they happened to coincide with a longer
+    // delivered text containing them.
+    expect(isDuplicateOfDelivered("ok", ["ok thanks pal"])).toBe(false);
+  });
+
+  it("matches when normalized candidate is a substring of delivered", () => {
+    const delivered = [normalizeForDedupe("Got it sur, pushing now")];
+    expect(isDuplicateOfDelivered("Got it sur, pushing now", delivered)).toBe(
+      true,
+    );
+  });
+
+  it("matches when normalized delivered is a substring of candidate", () => {
+    // Model called end_turn(text="Pushing now") then wrote prose
+    // "I'm pushing now and back in a sec." — fuzzy match catches this.
+    const delivered = [normalizeForDedupe("Pushing now")];
+    expect(
+      isDuplicateOfDelivered("I'm pushing now and back in a sec.", delivered),
+    ).toBe(true);
+  });
+
+  it("does not match unrelated content", () => {
+    const delivered = [normalizeForDedupe("PR #106 merged")];
+    expect(
+      isDuplicateOfDelivered("Got it, I'll look at the docker logs", delivered),
+    ).toBe(false);
+  });
+
+  it("ignores emoji differences when comparing", () => {
+    // Model wrote "Done 🎉" as prose, also called end_turn(text="Done")
+    const delivered = [normalizeForDedupe("Done")];
+    expect(isDuplicateOfDelivered("Done 🎉", delivered)).toBe(false);
+    // Above is false because "done" (3 chars) < MIN_DEDUP_LENGTH (10).
+    // For a longer match:
+    const longDelivered = [normalizeForDedupe("All set, pushing now")];
+    expect(
+      isDuplicateOfDelivered("All set, pushing now 🚀", longDelivered),
+    ).toBe(true);
+  });
+});
+
+describe("createStreamState", () => {
+  it("initializes lastTrailingText and deliveredTextNorms", () => {
+    const state = createStreamState();
+    expect(state.lastTrailingText).toBe("");
+    expect(state.deliveredTextNorms).toEqual([]);
+  });
+
+  it("initializes turnTerminated to false", () => {
+    const state = createStreamState();
+    expect(state.turnTerminated).toBe(false);
+  });
+});
+
+describe("turn-terminator declaration", () => {
+  it("end_turn is declared with endsTurn: true", () => {
+    const endTurn = messagingTools.find((t) => t.name === "end_turn");
+    expect(endTurn?.endsTurn).toBe(true);
+  });
+
+  it("send is NOT declared as a turn terminator", () => {
+    // `send` is for mid-turn rich content (photos, polls, scheduled messages,
+    // etc.) — calling it does NOT mean the model is done. Only end_turn
+    // declares the turn finished.
+    const send = messagingTools.find((t) => t.name === "send");
+    expect(send?.endsTurn).toBeFalsy();
+  });
+
+  it("isTurnTerminator returns true for end_turn", () => {
+    expect(isTurnTerminator("end_turn")).toBe(true);
+  });
+
+  it("isTurnTerminator returns false for non-terminator tools", () => {
+    expect(isTurnTerminator("send")).toBe(false);
+    expect(isTurnTerminator("react")).toBe(false);
+    expect(isTurnTerminator("fetch_url")).toBe(false);
+    expect(isTurnTerminator("nonexistent_tool")).toBe(false);
+  });
+
+  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.
+    const terminators = ALL_TOOLS.filter((t) => t.endsTurn).map((t) => t.name);
+    expect(terminators).toEqual(["end_turn"]);
+  });
+});
+
+describe("end_turn tool definition", () => {
+  const endTurn = messagingTools.find((t) => t.name === "end_turn");
+
+  it("is registered in messagingTools", () => {
+    expect(endTurn).toBeDefined();
+    expect(endTurn?.tag).toBe("messaging");
+    expect(endTurn?.frontends).toEqual(["telegram", "teams"]);
+  });
+
+  it("has text, reply_to, and buttons schema fields", () => {
+    expect(endTurn?.schema).toBeDefined();
+    expect(endTurn?.schema.text).toBeDefined();
+    expect(endTurn?.schema.reply_to).toBeDefined();
+    expect(endTurn?.schema.buttons).toBeDefined();
+  });
+
+  it("dispatches plain text via send_message bridge", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    await endTurn!.execute({ text: "Hello sur" }, bridge);
+    expect(bridge).toHaveBeenCalledWith("send_message", {
+      text: "Hello sur",
+      reply_to_message_id: undefined,
+    });
+  });
+
+  it("dispatches text + reply_to via send_message bridge", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    await endTurn!.execute({ text: "Yep", reply_to: 12345 }, bridge);
+    expect(bridge).toHaveBeenCalledWith("send_message", {
+      text: "Yep",
+      reply_to_message_id: 12345,
+    });
+  });
+
+  it("dispatches text + buttons via send_message_with_buttons bridge", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    const buttons = [[{ text: "Click", callback_data: "x" }]];
+    await endTurn!.execute({ text: "Pick", buttons }, bridge);
+    expect(bridge).toHaveBeenCalledWith("send_message_with_buttons", {
+      text: "Pick",
+      rows: buttons,
+      reply_to_message_id: undefined,
+    });
+  });
+
+  it("ends silently with no bridge call when text is omitted", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    const result = await endTurn!.execute({}, bridge);
+    expect(bridge).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, silent: true });
+  });
+
+  it("ends silently with no bridge call when text is whitespace-only", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    const result = await endTurn!.execute({ text: "   \n\t  " }, bridge);
+    expect(bridge).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, silent: true });
+  });
+});

package/src/__tests__/handlers.test.ts

@@ -2676,13 +2676,19 @@ describe("processAndReply — group message without senderId", () => {
   }, 3000);
 });
 
-describe("processAndReply — suppressed fallback text logged (L572 TRUE branch)", () => {
-  it("logs when bridgeMessageCount=0 and result.text is non-empty", async () => {
+describe("processAndReply — fallback text no longer suppressed", () => {
+  // Pre-end_turn behavior: when bridgeMessageCount=0 and result.text was
+  // non-empty, the frontend logged "Suppressed fallback text" and dropped
+  // the content (the scratchpad bug). The handler now fires onTextBlock
+  // with trailing text instead, so:
+  //   - the "Suppressed fallback" log is gone entirely
+  //   - the delivery path is exercised by createStreamCallbacks tests above
+  it("does NOT log a 'Suppressed fallback' warning anymore", async () => {
     const { log } = await import("../util/log.js");
     (log as ReturnType<typeof vi.fn>).mockClear();
 
     executeMock.mockResolvedValueOnce({
-      text: "internal reasoning only",
+      text: "trailing prose that used to be suppressed",
       durationMs: 10,
       inputTokens: 1,
       outputTokens: 1,
@@ -2694,7 +2700,7 @@ describe("processAndReply — suppressed fallback text logged (L572 TRUE branch)
     const ctx = {
       chat: { id: 99600, type: "private" },
       message: {
-        text: "test suppressed fallback",
+        text: "test fallback delivery",
         message_id: 1600,
         reply_to_message: null,
       },
@@ -2709,7 +2715,7 @@ describe("processAndReply — suppressed fallback text logged (L572 TRUE branch)
     const suppressedLog = logCalls.find((c: unknown[]) =>
       String(c[1]).includes("Suppressed fallback"),
     );
-    expect(suppressedLog).toBeDefined();
+    expect(suppressedLog).toBeUndefined();
   }, 3000);
 });
 

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",
       );
     });