talon-agent 3.27.0 → 3.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.27.0",
+  "version": "3.28.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "chatbot"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=24.15"
   },
   "type": "module",
   "main": "./src/index.ts",

package/prompts/system/heartbeat-agent.md

@@ -40,7 +40,7 @@ is a primary responsibility, not an optional extra. Goal tools
 (`update_goal`, `list_goals`, …) require an explicit `chat_id` parameter
 in heartbeat mode — use the chat id shown next to each goal.
 
-OUTBOUND MESSAGING: You also have access to the frontend tool servers — {{toolList}} — which expose `send`, `react`, and the rest of the messaging surface. Because there is NO ambient chat in heartbeat mode, every outbound tool call MUST include an explicit `chat_id` parameter. The bridge promotes that chat_id to the routing target, so `send(type="text", text="...", chat_id=N)` from `{{exampleFrontend}}-tools` delivers a message to chat N on that frontend. Known chat IDs live in your memory.md (per-frontend — for Telegram, Dylan's DM ID and group IDs are recorded; other frontends list their own). Without `chat_id`, the gateway returns 'No active chat context and no explicit numeric chat_id'.
+OUTBOUND MESSAGING: You also have access to the frontend tool servers — {{toolList}} — which expose `send`, `react`, and the rest of the messaging surface. Because there is NO ambient chat in heartbeat mode, every outbound tool call MUST include an explicit `chat_id` parameter. The bridge promotes that chat_id to the routing target, so `send(type="text", text="...", chat_id=N)` from `{{exampleFrontend}}-tools` delivers a message to chat N on that frontend. Known chat IDs live in your memory.md (per-frontend — for Telegram, Dylan's DM ID and group IDs are recorded; other frontends list their own). Without `chat_id`, the gateway returns 'No active chat context and no explicit numeric chat_id'. Cross-frontend: every tool server also carries `send_via(frontend=..., target=..., text=...)`, which delivers through ANY enabled frontend — target is the numeric chat id as a string, or for WhatsApp a phone number ("+353871234567") or wa_dm_/wa_group_ id.
 
 Reaching out is part of the job, not an exception: when a run turns up
 something a user would genuinely want to know — a goal completed or

package/src/core/engine/gateway-actions/cross-send.ts

@@ -0,0 +1,91 @@
+/**
+ * Cross-frontend send — the server side of the `send_via` tool.
+ *
+ * A chat-free shared action: any session (an active Telegram chat, the
+ * heartbeat, a dream run) delivers a plain text message through ANY
+ * enabled messaging frontend by naming it explicitly. Explicit is the
+ * point — the gateway's normal chat_id routing infers the owning
+ * frontend from the numeric id's shape, and WhatsApp's hash-derived ids
+ * also match the Telegram matcher, so a cross-frontend send routed that
+ * way lands on the wrong platform once the originating turn's context
+ * is cleared.
+ *
+ * Core never imports src/frontend (dependency-cruiser enforces it), so
+ * dispatch goes through a broker: `Gateway.registerFrontendHandler`
+ * mirrors each frontend's action handler here, and the action calls the
+ * target's own `send_message` — the one send action every messaging
+ * frontend implements. A numeric target doubles as the handler's chatId
+ * key, so id-addressed frontends (telegram, discord, teams, native)
+ * need no changes; non-numeric forms (WhatsApp phone numbers, wa_* ids)
+ * ride in `body.target` for the frontend's adapter to resolve.
+ */
+
+import type { FrontendActionHandler } from "../../types.js";
+import type { SharedActionHandlers } from "./types.js";
+
+const targets = new Map<string, FrontendActionHandler>();
+
+/**
+ * Broker registration — called by `Gateway.registerFrontendHandler` as
+ * each frontend wires up (and with null on deregistration), so the set
+ * of reachable targets is exactly the set of enabled frontends.
+ */
+export function registerCrossSendTarget(
+  name: string,
+  handler: FrontendActionHandler | null,
+): void {
+  if (handler === null) targets.delete(name);
+  else targets.set(name, handler);
+}
+
+export const crossSendHandlers: SharedActionHandlers = {
+  send_via: async (body) => {
+    const frontend = String(body.frontend ?? "")
+      .trim()
+      .toLowerCase();
+    const target = String(body.target ?? "").trim();
+    const text = String(body.text ?? "");
+    if (!frontend) {
+      return { ok: false, error: "send_via: frontend is required" };
+    }
+    if (!target) {
+      return { ok: false, error: "send_via: target is required" };
+    }
+    if (!text.trim()) {
+      return { ok: false, error: "send_via: text is required" };
+    }
+    const handler = targets.get(frontend);
+    if (!handler) {
+      const enabled = [...targets.keys()].sort().join(", ") || "none";
+      return {
+        ok: false,
+        error: `send_via: the ${frontend} frontend is not enabled (enabled: ${enabled})`,
+      };
+    }
+    // A numeric target is the handler's chatId key; other forms travel in
+    // body.target for the frontend's adapter to resolve. 0 is the same
+    // "no chat" sentinel the chat-free dispatch itself uses.
+    const numericTarget = /^-?\d+$/.test(target) ? Number(target) : 0;
+    const result = await handler(
+      { action: "send_message", text, target },
+      numericTarget,
+    );
+    if (!result) {
+      return {
+        ok: false,
+        error: `send_via: the ${frontend} frontend does not implement send_message`,
+      };
+    }
+    return result;
+  },
+};
+
+/**
+ * send_via is chat-free by design: it reads only its own explicit target
+ * and the broker, so it stays reachable from heartbeat/background runs —
+ * and skipping chat resolution is what keeps the wrong-frontend numeric
+ * routing hazard out of the path entirely.
+ */
+export const crossSendChatFreeActions: ReadonlySet<string> = new Set([
+  "send_via",
+]);

package/src/core/engine/gateway-actions/index.ts

@@ -17,6 +17,7 @@
  *   - `plugins`   — plugin hot-reload
  *   - `models`    — model / backend discovery
  *   - `mesh`      — companion device mesh (presence + location)
+ *   - `cross-send` — explicit-target sends through any enabled frontend
  */
 
 import type { ActionResult } from "../../types.js";
@@ -31,7 +32,11 @@ import { scriptHandlers } from "./scripts.js";
 import { skillHandlers } from "./skills.js";
 import { pluginHandlers } from "./plugins.js";
 import { modelHandlers } from "./models.js";
-import { meshHandlers, chatFreeActions } from "./mesh.js";
+import {
+  meshHandlers,
+  chatFreeActions as meshChatFreeActions,
+} from "./mesh.js";
+import { crossSendHandlers, crossSendChatFreeActions } from "./cross-send.js";
 import { nativeHandlers } from "./native.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
@@ -48,9 +53,19 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...pluginHandlers,
   ...modelHandlers,
   ...meshHandlers,
+  ...crossSendHandlers,
   ...nativeHandlers,
 });
 
+/**
+ * All chat-free actions — each domain module declares its own set, merged
+ * here into the one view the gateway (and `isChatFreeAction`) consults.
+ */
+const chatFreeActions: ReadonlySet<string> = new Set([
+  ...meshChatFreeActions,
+  ...crossSendChatFreeActions,
+]);
+
 export async function handleSharedAction(
   body: Record<string, unknown>,
   chatId: number,

package/src/core/engine/gateway.ts

@@ -25,6 +25,7 @@ import {
   handleChatFreeAction,
   isChatFreeAction,
 } from "./gateway-actions/index.js";
+import { registerCrossSendTarget } from "./gateway-actions/cross-send.js";
 import {
   handleHubRequest,
   getHubSessionCount,
@@ -154,6 +155,9 @@ export class Gateway {
     name: string,
     handler: FrontendActionHandler | null,
   ): void {
+    // Mirror into the cross-send broker so the chat-free `send_via`
+    // action can dispatch to any enabled frontend by explicit name.
+    registerCrossSendTarget(name, handler);
     if (handler === null) {
       this.frontendHandlers.delete(name);
       return;

package/src/core/tools/cross-send.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+/**
+ * Cross-frontend send. Deliberately NOT frontend-restricted (the meshTools
+ * pattern): the whole point is reaching a DIFFERENT enabled frontend than
+ * the one the session lives on — a Telegram chat messaging a WhatsApp
+ * number, the heartbeat reaching WhatsApp when only telegram-tools is
+ * mounted. The gateway serves it as a chat-free action (see
+ * engine/gateway-actions/cross-send.ts), so it works from background runs
+ * with no ambient chat, and the target frontend is named EXPLICITLY —
+ * never inferred from the shape of a numeric id.
+ */
+export const crossSendTools: ToolDefinition[] = [
+  {
+    name: "send_via",
+    description: `Send a plain text message through ANY enabled messaging frontend — including one this chat does not live on. Use it to reach someone on another platform (e.g. from Telegram or a heartbeat run, message a WhatsApp number). For the current chat, keep using the normal delivery tools (end_turn / send / send_message).
+
+Target forms:
+- whatsapp: a phone number with country code ("+353871234567" or "353871234567"), a wa_dm_<number>/wa_group_<id> chat id, or a raw JID; a bare numeric chat id works only for chats already seen since startup
+- telegram / discord / teams / native: the numeric chat id, as a string (Telegram supergroups/channels are negative, DMs positive)
+
+Examples:
+  send_via(frontend="whatsapp", target="+353871234567", text="On my way")
+  send_via(frontend="telegram", target="-1001426819337", text="Build is green")
+
+Fails with a clear error when the named frontend is not enabled or not connected.`,
+    schema: {
+      frontend: z
+        .enum(["telegram", "whatsapp", "discord", "teams", "native"])
+        .describe("Messaging frontend to deliver through."),
+      target: z
+        .string()
+        .describe(
+          "Destination chat: numeric chat id as a string; for WhatsApp also a phone number with country code or a wa_dm_/wa_group_ id.",
+        ),
+      text: z
+        .string()
+        .describe(
+          "Message text. Markdown supported where the platform supports it.",
+        ),
+    },
+    execute: (params, bridge) => bridge("send_via", params),
+    tag: "messaging",
+  },
+];

package/src/core/tools/index.ts

@@ -22,6 +22,7 @@ import { webTools } from "./web.js";
 import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
+import { crossSendTools } from "./cross-send.js";
 import { moderationTools } from "./moderation.js";
 import { nativeTools } from "./native.js";
 
@@ -42,6 +43,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
   ...modelTools,
   ...meshTools,
+  ...crossSendTools,
   ...moderationTools,
 ];
 

package/src/frontend/whatsapp/actions/index.ts

@@ -19,7 +19,11 @@
 import type { WASocket } from "baileys";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { ActionResult } from "../../../core/types.js";
-import { lookupWhatsAppChat } from "../registry.js";
+import {
+  lookupWhatsAppChat,
+  resolveWhatsAppTarget,
+  type WhatsAppChatInfo,
+} from "../registry.js";
 import { chatInfoHandlers } from "./chat-info.js";
 import { mediaHandlers } from "./media.js";
 import { messagingHandlers } from "./messaging.js";
@@ -57,7 +61,26 @@ export function createWhatsAppActionHandler(
       return { ok: false, error: "WhatsApp socket is not connected" };
     }
 
-    const chat = lookupWhatsAppChat(chatId) ?? null;
+    // An explicit cross-send target (send_via) names the destination
+    // itself — phone number, wa_* id, or JID — and may be a chat this
+    // process has never seen; resolveWhatsAppTarget registers it so the
+    // usual numeric-id routing works from then on. Without a target,
+    // the gateway's numeric chatId (an active chat) is the destination.
+    let chat: WhatsAppChatInfo | null;
+    if (body.target !== undefined) {
+      chat = resolveWhatsAppTarget(body.target) ?? null;
+      if (!chat) {
+        return {
+          ok: false,
+          error:
+            `Unresolvable WhatsApp target "${String(body.target)}" — use a ` +
+            `phone number with country code, a wa_dm_/wa_group_ id, or a ` +
+            `known chat id.`,
+        };
+      }
+    } else {
+      chat = lookupWhatsAppChat(chatId) ?? null;
+    }
     if (!chat && !CHATLESS_ACTIONS.has(action)) {
       return {
         ok: false,

package/src/frontend/whatsapp/registry.ts

@@ -85,6 +85,45 @@ export function lookupWhatsAppChatByString(
   return byString.get(chatId);
 }
 
+/**
+ * Resolve an explicit send target — the `target` a cross-frontend
+ * `send_via` names — onto chat info, REGISTERING the chat when it's new
+ * so numeric-id routing and replies work from then on. Accepted forms:
+ *
+ *   - a registered Talon id: `wa_dm_*`/`wa_group_*` string, or its
+ *     numeric hash (only resolvable while registered — the hash can't
+ *     be reversed)
+ *   - a raw JID: `<number>@s.whatsapp.net` or `<id>@g.us`
+ *   - a phone number with country code: "+353871234567", "353 87 123 4567"
+ *
+ * Digits with punctuation normalize to a DM JID; an all-digit string is
+ * tried as a registered numeric id first, then treated as a phone number.
+ * Returns undefined when nothing sendable can be derived.
+ */
+export function resolveWhatsAppTarget(
+  raw: unknown,
+): WhatsAppChatInfo | undefined {
+  const target = String(raw ?? "").trim();
+  if (!target) return undefined;
+  const registered = byString.get(target);
+  if (registered) return registered;
+  if (/^\d+$/.test(target)) {
+    const byHash = byNumeric.get(Number(target));
+    if (byHash) return byHash;
+  }
+  if (target.includes("@")) return registerWhatsAppChat(target);
+  if (target.startsWith("wa_group_")) {
+    return registerWhatsAppChat(`${target.slice("wa_group_".length)}@g.us`);
+  }
+  if (target.startsWith("wa_dm_")) {
+    return registerWhatsAppChat(
+      `${target.slice("wa_dm_".length)}@s.whatsapp.net`,
+    );
+  }
+  const digits = target.replace(/[^0-9]/g, "");
+  return digits ? registerWhatsAppChat(`${digits}@s.whatsapp.net`) : undefined;
+}
+
 /** Test seam: forget every registered chat. */
 export function resetWhatsAppRegistry(): void {
   byNumeric.clear();