talon-agent 1.12.0 → 1.34.0

package/src/frontend/discord/handlers/queue.ts

@@ -0,0 +1,135 @@
+/**
+ * Message queue — debounces rapid-fire messages per chat (concatenating them
+ * into a single agent turn) with one transient retry, then best-effort error
+ * notification.
+ */
+
+import { classify, friendlyMessage } from "../../../core/errors.js";
+import { recordMessageProcessed, recordError } from "../../../util/watchdog.js";
+import { appendDailyLog } from "../../../storage/daily-log.js";
+import { log, logError } from "../../../util/log.js";
+import { processAndReply } from "./delivery.js";
+import { sendChunked } from "./context.js";
+import {
+  messageQueues,
+  DEBOUNCE_MS,
+  MAX_QUEUED_PER_CHAT,
+  type QueuedMessage,
+} from "./state.js";
+import type { TalonConfig } from "../../../util/config.js";
+
+export function enqueueMessage(
+  config: TalonConfig,
+  chatId: string,
+  numericChatId: number,
+  msg: QueuedMessage,
+): void {
+  const existing = messageQueues.get(chatId);
+  if (existing) {
+    if (existing.messages.length >= MAX_QUEUED_PER_CHAT) return;
+    existing.messages.push(msg);
+    clearTimeout(existing.timer);
+    existing.timer = setTimeout(() => flushQueue(chatId), DEBOUNCE_MS);
+    return;
+  }
+  messageQueues.set(chatId, {
+    messages: [msg],
+    timer: setTimeout(() => flushQueue(chatId), DEBOUNCE_MS),
+    config,
+    chatId,
+    numericChatId,
+  });
+}
+
+async function flushQueue(chatId: string): Promise<void> {
+  const entry = messageQueues.get(chatId);
+  if (!entry) return;
+  messageQueues.delete(chatId);
+
+  const { messages, config, numericChatId } = entry;
+  const last = messages[messages.length - 1];
+  const combinedPrompt =
+    messages.length === 1
+      ? messages[0].prompt
+      : messages.map((m) => m.prompt).join("\n\n");
+
+  appendDailyLog(last.senderName, combinedPrompt, {
+    chatTitle: last.chatTitle,
+    username: last.senderUsername,
+  });
+
+  const runTurn = () =>
+    processAndReply({
+      config,
+      chatId,
+      numericChatId,
+      replyToId: last.replyToId,
+      messageId: last.messageId,
+      numericMessageId: last.numericMessageId,
+      prompt: combinedPrompt,
+      senderName: last.senderName,
+      isGroup: last.isGroup,
+      senderUsername: last.senderUsername,
+      senderId: last.senderId,
+      channel: last.channel,
+      chatTitle: last.chatTitle,
+    });
+
+  try {
+    await runTurn();
+    recordMessageProcessed();
+  } catch (err) {
+    const classified = classify(err);
+    const promptPreview = combinedPrompt.slice(0, 100).replace(/\n/g, " ");
+    logError(
+      "bot",
+      `[${chatId}] [${last.isGroup ? "guild" : "DM"}] [${last.senderName}] ${classified.reason}: ${classified.message} | prompt: "${promptPreview}"`,
+    );
+    recordError(classified.message);
+
+    if (classified.retryable) {
+      const delayMs = classified.retryAfterMs ?? 2000;
+      log(
+        "bot",
+        `[${chatId}] Retrying after ${classified.reason} (${delayMs}ms)...`,
+      );
+      try {
+        await new Promise((r) => setTimeout(r, delayMs));
+        await runTurn();
+        recordMessageProcessed();
+        return;
+      } catch (retryErr) {
+        const retryClassified = classify(retryErr);
+        logError("bot", `[${chatId}] Retry failed: ${retryClassified.message}`);
+        // Error-recovery send must never throw — if the network is fully down
+        // the queue handler would otherwise propagate up and stall future
+        // messages. Best-effort: notify if we can, log + move on otherwise.
+        try {
+          await sendChunked(
+            last.channel,
+            friendlyMessage(retryClassified),
+            last.replyToId,
+          );
+        } catch (notifyErr) {
+          logError(
+            "bot",
+            `[${chatId}] Could not notify user about retry failure: ${notifyErr instanceof Error ? notifyErr.message : notifyErr}`,
+          );
+        }
+        return;
+      }
+    }
+    try {
+      await sendChunked(
+        last.channel,
+        friendlyMessage(classified),
+        last.replyToId,
+      );
+    } catch (notifyErr) {
+      logError(
+        "bot",
+        `[${chatId}] Could not notify user about error: ${notifyErr instanceof Error ? notifyErr.message : notifyErr}`,
+      );
+    }
+  }
+}

package/src/frontend/discord/handlers/registry.ts

@@ -0,0 +1,29 @@
+/**
+ * Chat-registry accessors — map between numeric/string chat ids and the
+ * Discord channel info the action handler needs to post back.
+ */
+
+import {
+  chatRegistry,
+  chatRegistryByString,
+  type DiscordChatInfo,
+} from "./state.js";
+
+export type { DiscordChatInfo } from "./state.js";
+
+export function registerDiscordChat(info: DiscordChatInfo): void {
+  chatRegistry.set(info.numericChatId, info);
+  chatRegistryByString.set(info.chatId, info);
+}
+
+export function lookupDiscordChat(
+  numericChatId: number,
+): DiscordChatInfo | undefined {
+  return chatRegistry.get(numericChatId);
+}
+
+export function lookupDiscordChatByString(
+  chatId: string,
+): DiscordChatInfo | undefined {
+  return chatRegistryByString.get(chatId);
+}

package/src/frontend/discord/handlers/state.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared module-level state for the Discord message-handling pipeline:
+ * the chat registry, access config, DM-user tracking, unauthorized cooldown,
+ * per-user rate-limit windows, and the debounce queue. Created once here and
+ * imported by the handler submodules so all state stays coherent across files.
+ */
+
+import type { TextBasedChannel } from "discord.js";
+import type { TalonConfig } from "../../../util/config.js";
+
+// ── Chat registry: numericChatId → Discord channel info ─────────────────────
+// The gateway/dispatcher uses numeric chatIds. Action handlers need to map
+// back to the Discord channel they should post to.
+
+export type DiscordChatInfo = {
+  channelId: string;
+  guildId: string | null;
+  userId: string | null; // for DM contexts
+  numericChatId: number;
+  chatId: string;
+};
+
+export const chatRegistry = new Map<number, DiscordChatInfo>();
+export const chatRegistryByString = new Map<string, DiscordChatInfo>();
+
+// ── Access control state ─────────────────────────────────────────────────────
+
+export type AccessConfig = {
+  allowedUsers: Set<string>;
+  allowedGuilds: Set<string>;
+  allowedChannels: Set<string>; // empty = all channels in allowedGuilds
+  adminUserIds: Set<string>;
+  respondMode: "mention" | "channel";
+};
+
+/**
+ * Reassignable access config on a holder object so `setAccessControl` can
+ * swap it and every reader sees the update through the import.
+ */
+export const accessState: { access: AccessConfig } = {
+  access: {
+    allowedUsers: new Set(),
+    allowedGuilds: new Set(),
+    allowedChannels: new Set(),
+    adminUserIds: new Set(),
+    respondMode: "mention",
+  },
+};
+
+// ── First-time DM user tracking ──────────────────────────────────────────────
+
+export const knownDmUsers = new Set<string>();
+export const KNOWN_DM_USERS_CAP = 10_000;
+
+// ── Unauthorized notification cooldown (10 min) ──────────────────────────────
+
+export const unauthorizedCooldown = new Map<string, number>();
+export const UNAUTHORIZED_COOLDOWN_MS = 10 * 60 * 1000;
+export const MAX_UNAUTHORIZED_COOLDOWNS = 5000;
+
+// ── Per-user rate limiting ───────────────────────────────────────────────────
+
+export const userMessageTimestamps = new Map<string, number[]>();
+export const RATE_LIMIT_WINDOW_MS = 60_000;
+export const RATE_LIMIT_MAX_MESSAGES = 15;
+
+// ── Message queue (debounce rapid-fire messages per chat) ────────────────────
+
+export type QueuedMessage = {
+  prompt: string;
+  replyToId: string;
+  messageId: string;
+  numericMessageId: number;
+  senderName: string;
+  senderUsername?: string;
+  senderId: string;
+  isGroup: boolean;
+  channel: TextBasedChannel;
+  chatTitle?: string;
+};
+
+export const messageQueues = new Map<
+  string,
+  {
+    messages: QueuedMessage[];
+    timer: ReturnType<typeof setTimeout>;
+    config: TalonConfig;
+    chatId: string;
+    numericChatId: number;
+  }
+>();
+
+export const DEBOUNCE_MS = 500;
+export const MAX_QUEUED_PER_CHAT = 20;

package/src/frontend/discord/helpers.ts

@@ -7,21 +7,28 @@
  *  - chat IDs are Discord snowflakes (strings), not numbers.
  */
 
-import { resolveModel } from "../../core/models.js";
+import { REASONING_LEVEL_DESCRIPTIONS } from "../../core/models/reasoning-levels.js";
 import { DISCORD_MAX_TEXT, DISCORD_SAFE_RESERVE } from "./formatting.js";
+import {
+  DEFAULT_PULSE_INTERVAL_MS,
+  formatDuration,
+  formatModelLabel,
+} from "../shared/format.js";
+
+export {
+  parseInterval,
+  formatDuration,
+  formatTokenCount,
+  formatBytes,
+  formatModelLabel,
+} from "../shared/format.js";
 
-const DEFAULT_PULSE_INTERVAL_MS = 5 * 60 * 1000;
 /** Per-message length budget for metrics output. */
 const DEFAULT_METRICS_MESSAGE_MAX = DISCORD_MAX_TEXT - DISCORD_SAFE_RESERVE;
 
 /** Effort level descriptions shown next to each option in select menus. */
 export const EFFORT_DESCRIPTIONS: Record<string, string> = {
-  off: "no extra thinking — fastest",
-  low: "short reasoning pass",
-  medium: "balanced reasoning",
-  high: "deeper reasoning, slower",
-  max: "most thorough — slowest",
-  adaptive: "model decides when to think",
+  ...REASONING_LEVEL_DESCRIPTIONS,
 };
 
 type MetricsSnapshot = {
@@ -32,45 +39,6 @@ type MetricsSnapshot = {
   >;
 };
 
-/** Parse a duration string like "30m", "2h", "1d", "1h30m", "1d6h" into ms. */
-export function parseInterval(input: string): number | null {
-  const match = input.match(/^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?$/);
-  if (!match || (!match[1] && !match[2] && !match[3])) return null;
-  const days = parseInt(match[1] || "0", 10);
-  const hours = parseInt(match[2] || "0", 10);
-  const minutes = parseInt(match[3] || "0", 10);
-  const ms = (days * 24 * 60 + hours * 60 + minutes) * 60 * 1000;
-  return ms > 0 ? ms : null;
-}
-
-export function formatDuration(ms: number): string {
-  const safeMs = Math.max(0, Math.round(ms));
-  if (safeMs < 1000) return `${safeMs}ms`;
-  const s = Math.floor(safeMs / 1000);
-  if (s < 60) return `${s}s`;
-  const m = Math.floor(s / 60);
-  if (m < 60) return `${m}m ${s % 60}s`;
-  const h = Math.floor(m / 60);
-  return `${h}h ${m % 60}m`;
-}
-
-export function formatTokenCount(n: number): string {
-  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
-  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
-  return String(n);
-}
-
-export function formatBytes(bytes: number): string {
-  if (bytes >= 1_073_741_824) return `${(bytes / 1_073_741_824).toFixed(1)} GB`;
-  if (bytes >= 1_048_576) return `${(bytes / 1_048_576).toFixed(1)} MB`;
-  if (bytes >= 1_024) return `${(bytes / 1_024).toFixed(1)} KB`;
-  return `${bytes} B`;
-}
-
-export function formatModelLabel(modelId: string): string {
-  return resolveModel(modelId)?.displayName ?? modelId;
-}
-
 function truncateMetricLabel(label: string, max = 60): string {
   return label.length <= max ? label : `${label.slice(0, max - 3)}...`;
 }
@@ -87,18 +55,30 @@ export function renderMetricsMessages(
   const continuationHeader = "**📊 Metrics (cont.)**";
   const sections: string[][] = [];
 
+  // Histograms come in two flavours: durations (keys ending in `_ms`,
+  // rendered as human times) and plain counts like `tool_calls_per_turn`
+  // (rendered as bare numbers — "p50=1ms" for a count is nonsense).
   const histKeys = Object.keys(metrics.histograms).sort();
-  if (histKeys.length > 0) {
+  const durationKeys = histKeys.filter((key) => key.endsWith("_ms"));
+  const countKeys = histKeys.filter((key) => !key.endsWith("_ms"));
+  const histLine = (key: string, fmt: (v: number) => string): string => {
+    const h = metrics.histograms[key];
+    return (
+      `  \`${truncateMetricLabel(key)}\`  n=${h.count} ` +
+      `p50=${fmt(h.p50)}  p95=${fmt(h.p95)} ` +
+      `p99=${fmt(h.p99)}  avg=${fmt(h.avg)}`
+    );
+  };
+  if (durationKeys.length > 0) {
     sections.push([
       "**Latency**",
-      ...histKeys.map((key) => {
-        const h = metrics.histograms[key];
-        return (
-          `  \`${truncateMetricLabel(key)}\`  n=${h.count} ` +
-          `p50=${formatDuration(h.p50)}  p95=${formatDuration(h.p95)} ` +
-          `p99=${formatDuration(h.p99)}  avg=${formatDuration(h.avg)}`
-        );
-      }),
+      ...durationKeys.map((key) => histLine(key, formatDuration)),
+    ]);
+  }
+  if (countKeys.length > 0) {
+    sections.push([
+      "**Distributions**",
+      ...countKeys.map((key) => histLine(key, String)),
     ]);
   }
 
@@ -111,7 +91,16 @@ export function renderMetricsMessages(
       groups.get(prefix)!.push(key);
     }
     for (const prefix of [...groups.keys()].sort()) {
-      const keys = groups.get(prefix)!;
+      // tool_calls reads best as a leaderboard — busiest tools first.
+      // Other groups keep alphabetical order (stable lookup by name).
+      const keys =
+        prefix === "tool_calls"
+          ? [...groups.get(prefix)!].sort(
+              (a, b) =>
+                metrics.counters[b]! - metrics.counters[a]! ||
+                a.localeCompare(b),
+            )
+          : groups.get(prefix)!;
       sections.push([
         `**${prefix}**`,
         ...keys.map((key) => {

package/src/frontend/discord/index.ts

@@ -23,20 +23,20 @@ import {
 import { once } from "node:events";
 import type { TalonConfig } from "../../util/config.js";
 import type { ContextManager } from "../../core/types.js";
-import type { Gateway } from "../../core/gateway.js";
+import type { Gateway } from "../../core/engine/gateway.js";
 import { log, logError, logWarn } from "../../util/log.js";
-import { createDiscordActionHandler } from "./actions.js";
+import { createDiscordActionHandler } from "./actions/index.js";
 import {
   registerCommandsForGuilds,
   registerInteractionRouter,
-} from "./commands.js";
+} from "./commands/index.js";
 import { registerMiddleware } from "./middleware.js";
 import {
   setAccessControl,
   lookupDiscordChat,
   registerDiscordChat,
-} from "./handlers.js";
-import { sendChunked } from "./handlers.js";
+} from "./handlers/index.js";
+import { sendChunked } from "./handlers/index.js";
 import { deriveNumericChatId } from "../../util/chat-id.js";
 
 // ── Frontend type ───────────────────────────────────────────────────────────
@@ -89,7 +89,7 @@ export function createDiscordFrontend(
 
   const context: ContextManager = {
     acquire: (chatId: number, stringId?: string) =>
-      gateway.setContext(chatId, stringId),
+      gateway.setContext(chatId, stringId, "discord"),
     release: (chatId: number) => gateway.clearContext(chatId),
     getMessageCount: (chatId: number) => gateway.getMessageCount(chatId),
   };
@@ -147,7 +147,10 @@ export function createDiscordFrontend(
 
     async init() {
       // Register Discord action handler with the gateway
-      gateway.setFrontendHandler(createDiscordActionHandler(client, gateway));
+      gateway.registerFrontendHandler(
+        "discord",
+        createDiscordActionHandler(client, gateway),
+      );
 
       const port = await gateway.start(19876);
       log("discord", `Gateway started on port ${port}`);

package/src/frontend/discord/middleware.ts

@@ -18,9 +18,9 @@ import type { Client, Message } from "discord.js";
 import { ChannelType } from "discord.js";
 import type { TalonConfig } from "../../util/config.js";
 import { pushMessage } from "../../storage/history.js";
-import { registerChat } from "../../core/pulse.js";
+import { registerChat } from "../../core/background/pulse.js";
 import { deriveNumericChatId } from "../../util/chat-id.js";
-import { handleMessage, getSenderName } from "./handlers.js";
+import { handleMessage, getSenderName } from "./handlers/index.js";
 
 export function registerMiddleware(client: Client, config: TalonConfig): void {
   client.on("messageCreate", (msg: Message) => {

package/src/frontend/native/actions.ts

@@ -0,0 +1,133 @@
+/**
+ * Native action handler — the gateway-side bridge for the agent's delivery
+ * tools. When the model calls `end_turn` / `send_message` / `react` / edit /
+ * delete, the MCP tool POSTs an action to the gateway, which routes it here
+ * by the active chat's numeric id. We translate each action into a Bridge
+ * event the connected clients render, persist assistant messages to history,
+ * and count deliveries on the gateway (so the dispatcher's trailing-prose
+ * fallback knows the turn already produced output).
+ */
+
+import type { FrontendActionHandler, ActionResult } from "../../core/types.js";
+import type { Gateway } from "../../core/engine/gateway.js";
+import type { NativeChats, ChatEntry } from "./chats.js";
+import type { BridgeEvent, ClientButton } from "./protocol.js";
+
+export type NativeActionDeps = {
+  chats: NativeChats;
+  gateway: Gateway;
+  /** Persist + broadcast an assistant message; returns its numeric id. */
+  emitAssistant: (
+    entry: ChatEntry,
+    text: string,
+    buttons?: ClientButton[][],
+  ) => number;
+  /** Persist + broadcast an assistant photo message; returns its numeric id. */
+  emitPhoto: (entry: ChatEntry, filePath: string, caption?: string) => number;
+  broadcast: (event: BridgeEvent) => void;
+};
+
+/** Coerce gateway button rows (`[[{text,url,callback_data}]]`) to wire buttons. */
+function toButtons(rows: unknown): ClientButton[][] | undefined {
+  if (!Array.isArray(rows)) return undefined;
+  const mapped: ClientButton[][] = [];
+  for (const row of rows) {
+    if (!Array.isArray(row)) continue;
+    const cells: ClientButton[] = [];
+    for (const cell of row) {
+      if (cell && typeof cell === "object") {
+        const c = cell as Record<string, unknown>;
+        const text = typeof c.text === "string" ? c.text : "";
+        if (!text) continue;
+        cells.push({
+          text,
+          url: typeof c.url === "string" ? c.url : undefined,
+          data:
+            typeof c.callback_data === "string" ? c.callback_data : undefined,
+        });
+      }
+    }
+    if (cells.length) mapped.push(cells);
+  }
+  return mapped.length ? mapped : undefined;
+}
+
+export function createNativeActionHandler(
+  deps: NativeActionDeps,
+): FrontendActionHandler {
+  const { chats, gateway, emitAssistant, emitPhoto, broadcast } = deps;
+
+  return async (body, chatId): Promise<ActionResult | null> => {
+    const action = typeof body.action === "string" ? body.action : "";
+    const entry = chats.byNumeric(chatId);
+    if (!entry) return { ok: false, error: "No active native chat" };
+
+    switch (action) {
+      case "send_message": {
+        const text = String(body.text ?? "");
+        const id = emitAssistant(entry, text);
+        gateway.incrementMessages(chatId);
+        return { ok: true, message_id: id };
+      }
+
+      case "send_message_with_buttons": {
+        const text = String(body.text ?? "");
+        const id = emitAssistant(entry, text, toButtons(body.rows));
+        gateway.incrementMessages(chatId);
+        return { ok: true, message_id: id };
+      }
+
+      case "send_photo": {
+        const filePath = String(body.file_path ?? "");
+        if (!filePath) return { ok: false, error: "file_path required" };
+        const caption =
+          typeof body.caption === "string" ? body.caption : undefined;
+        const id = emitPhoto(entry, filePath, caption);
+        gateway.incrementMessages(chatId);
+        return { ok: true, message_id: id };
+      }
+
+      case "react": {
+        const messageId = String(body.message_id ?? "");
+        const emoji = String(body.emoji ?? "👍");
+        broadcast({ kind: "reaction", chatId: entry.id, messageId, emoji });
+        gateway.incrementMessages(chatId);
+        return { ok: true };
+      }
+
+      case "edit_message": {
+        const messageId = String(body.message_id ?? "");
+        const text = String(body.text ?? "");
+        broadcast({
+          kind: "message_edited",
+          chatId: entry.id,
+          messageId,
+          text,
+        });
+        return { ok: true };
+      }
+
+      case "delete_message": {
+        const messageId = String(body.message_id ?? "");
+        broadcast({ kind: "message_deleted", chatId: entry.id, messageId });
+        return { ok: true };
+      }
+
+      case "get_chat_info":
+        return {
+          ok: true,
+          id: entry.numericId,
+          type: "private",
+          title: entry.title,
+        };
+
+      // Typing is driven by the dispatcher via sendTyping → no-op ack here.
+      case "send_chat_action":
+        return { ok: true };
+
+      default:
+        // Let the gateway try plugin + shared actions (history, web, cron…).
+        return null;
+    }
+  };
+}