talon-agent 1.0.0

package/src/core/prompt-builder.ts

@@ -0,0 +1,43 @@
+/**
+ * Prompt enrichment — adds context to raw user messages before sending to the AI.
+ * Platform-agnostic; works with any messaging frontend.
+ */
+
+import { getRecentBySenderId } from "../storage/history.js";
+import { formatSmartTimestamp } from "../util/time.js";
+
+/**
+ * Enrich a DM prompt with sender metadata.
+ */
+export function enrichDMPrompt(
+  prompt: string,
+  senderName: string,
+  senderUsername?: string,
+): string {
+  const userTag = senderUsername ? ` (@${senderUsername})` : "";
+  return `[DM from ${senderName}${userTag}]\n${prompt}`;
+}
+
+/**
+ * Enrich a group prompt with the sender's recent messages for threading context.
+ */
+export function enrichGroupPrompt(
+  prompt: string,
+  chatId: string,
+  senderId: number,
+): string {
+  const recentMsgs = getRecentBySenderId(chatId, senderId, 5);
+  if (recentMsgs.length <= 1) return prompt;
+
+  const priorMsgs = recentMsgs.slice(0, -1);
+  if (priorMsgs.length === 0) return prompt;
+
+  const senderName = priorMsgs[0].senderName;
+  const contextLines = priorMsgs
+    .map(
+      (m) =>
+        `  [${formatSmartTimestamp(m.timestamp)}] ${m.text.slice(0, 200)}`,
+    )
+    .join("\n");
+  return `[${senderName}'s recent messages in this group:\n${contextLines}]\n\n${prompt}`;
+}

package/src/core/pulse.ts

@@ -0,0 +1,175 @@
+/**
+ * Pulse — conversation-aware engagement.
+ *
+ * Every N minutes, checks for new messages in registered chats.
+ * If there are new messages, feeds them to the dispatcher so Claude
+ * can decide whether to respond. Same session, same cache.
+ *
+ * Knows nothing about the backend or frontend — uses the dispatcher.
+ */
+
+import { execute, getActiveCount } from "./dispatcher.js";
+import {
+  setChatPulse,
+  getRegisteredPulseChats,
+  getChatSettings,
+  setPulseLastCheckMsgId,
+} from "../storage/chat-settings.js";
+import { getRecentHistory, getLatestMessageId } from "../storage/history.js";
+import { log, logError } from "../util/log.js";
+import { formatSmartTimestamp } from "../util/time.js";
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+let timer: ReturnType<typeof setInterval> | null = null;
+const registeredChats = new Set<string>();
+const lastCheckMessageId = new Map<string, number>();
+
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+let activeIntervalMs = DEFAULT_INTERVAL_MS;
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export function initPulse(): void {
+  for (const chatId of getRegisteredPulseChats()) {
+    registeredChats.add(chatId);
+    // Restore persisted last-check message ID to avoid reprocessing on restart
+    const settings = getChatSettings(chatId);
+    if (settings.pulseLastCheckMsgId !== undefined) {
+      lastCheckMessageId.set(chatId, settings.pulseLastCheckMsgId);
+    }
+  }
+  if (registeredChats.size > 0) {
+    log("pulse", `Loaded ${registeredChats.size} registered chat(s)`);
+  }
+}
+
+export function registerChat(chatId: string): void {
+  registeredChats.add(chatId);
+}
+
+export function enablePulse(chatId: string): void {
+  setChatPulse(chatId, true);
+  registeredChats.add(chatId);
+}
+
+export function disablePulse(chatId: string): void {
+  setChatPulse(chatId, false);
+}
+
+/** Clear pulse checkpoint for a chat (call on /reset to avoid stale state). */
+export function resetPulseCheckpoint(chatId: string): void {
+  lastCheckMessageId.delete(chatId);
+  setPulseLastCheckMsgId(chatId, undefined);
+}
+
+export function isPulseEnabled(chatId: string): boolean {
+  return getChatSettings(chatId).pulse === true;
+}
+
+export function startPulseTimer(intervalMs?: number): void {
+  if (timer) return;
+  const envMs = parseInt(process.env.TALON_PULSE_INTERVAL_MS ?? "", 10);
+  const ms = intervalMs ?? (envMs > 0 ? envMs : DEFAULT_INTERVAL_MS);
+  if (ms <= 0) return;
+
+  activeIntervalMs = ms;
+  log("pulse", `Started: checking every ${Math.round(ms / 60000)}m`);
+  timer = setInterval(() => {
+    runPulse().catch((err) => logError("pulse", "Check failed", err));
+  }, ms);
+}
+
+/** Reset the pulse timer — call when bot sends a message to avoid
+ *  redundant check-ins during active conversation. */
+export function resetPulseTimer(): void {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = setInterval(() => {
+    runPulse().catch((err) => logError("pulse", "Check failed", err));
+  }, activeIntervalMs);
+}
+
+export function stopPulseTimer(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+}
+
+/** Get pulse status for admin visibility. */
+export function getPulseStatus(): Array<{
+  chatId: string;
+  enabled: boolean;
+  lastChecked: number | undefined;
+}> {
+  return [...registeredChats].map((chatId) => ({
+    chatId,
+    enabled: isPulseEnabled(chatId),
+    lastChecked: lastCheckMessageId.get(chatId),
+  }));
+}
+
+// ── Core ─────────────────────────────────────────────────────────────────────
+
+async function runPulse(): Promise<void> {
+  if (getActiveCount() > 10) return; // safety valve — don't pile on if heavily loaded
+
+  for (const chatId of registeredChats) {
+    if (!isPulseEnabled(chatId)) continue;
+    await pulseChat(chatId);
+  }
+}
+
+async function pulseChat(chatId: string): Promise<void> {
+  const numericChatId = parseInt(chatId, 10);
+  if (isNaN(numericChatId)) {
+    logError("pulse", `Invalid chatId: ${chatId}`);
+    return;
+  }
+
+  // Any new messages since last check?
+  const latestMsgId = getLatestMessageId(chatId);
+  const lastChecked = lastCheckMessageId.get(chatId);
+  if (latestMsgId === undefined) return;
+  if (lastChecked !== undefined && latestMsgId <= lastChecked) return;
+
+  // Get unread messages
+  const recent = getRecentHistory(chatId, 15);
+  const unread = lastChecked !== undefined
+    ? recent.filter((m) => m.msgId > lastChecked)
+    : recent;
+  if (unread.length === 0) return;
+
+  const summary = unread
+    .map((m) => {
+      const time = formatSmartTimestamp(m.timestamp);
+      const media = m.mediaType ? ` [${m.mediaType}]` : "";
+      return `[msg:${m.msgId} ${time}] ${m.senderName}${media}: ${m.text.slice(0, 200)}`;
+    })
+    .join("\n");
+
+  try {
+    const prompt =
+      `[System: Pulse check — ${unread.length} new message(s) since last check. ` +
+      `Read them and decide: respond, react with an emoji, or stay silent. ` +
+      `Don't announce yourself. Reactions are great for simple acknowledgements.]\n\n${summary}`;
+
+    await execute({
+      chatId,
+      numericChatId,
+      prompt,
+      senderName: "System",
+      isGroup: true,
+      source: "pulse",
+    });
+
+    // Mark as checked AFTER successful execution — if it failed, retry next tick
+    lastCheckMessageId.set(chatId, latestMsgId);
+    setPulseLastCheckMsgId(chatId, latestMsgId);
+    log("pulse", `Checked ${chatId} (${unread.length} new msgs)`);
+  } catch (err) {
+    logError("pulse", `Chat ${chatId} failed`, err);
+    // Don't update lastCheckMessageId — messages will be retried next pulse
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Core interfaces — the contract between modules.
+ * Every module depends on these abstractions, never on concrete implementations.
+ *
+ * Dependency rule: core/ imports nothing from frontend/ or backend/.
+ * frontend/ and backend/ depend on core/types, never on each other.
+ */
+
+// ── Query lifecycle ─────────────────────────────────────────────────────────
+
+/** Parameters for a backend AI query. */
+export type QueryParams = {
+  chatId: string;
+  text: string;
+  senderName: string;
+  isGroup?: boolean;
+  messageId?: number;
+  onStreamDelta?: (accumulated: string, phase?: "thinking" | "text") => void;
+  onTextBlock?: (text: string) => Promise<void>;
+  onToolUse?: (toolName: string, input: Record<string, unknown>) => void;
+};
+
+/** Result of a backend AI query. */
+export type QueryResult = {
+  text: string;
+  durationMs: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheRead: number;
+  cacheWrite: number;
+};
+
+/** Backend interface — any AI provider implements this. */
+export interface QueryBackend {
+  query(params: QueryParams): Promise<QueryResult>;
+}
+
+// ── Execution context ───────────────────────────────────────────────────────
+
+/**
+ * Manages the tool-execution context for the active chat.
+ * The frontend provides an implementation so the AI's tool calls
+ * can reach the messaging platform.
+ */
+export interface ContextManager {
+  acquire(chatId: number, stringId?: string): void;
+  release(chatId: number): void;
+  getMessageCount(chatId: number): number;
+}
+
+/** Parameters for the dispatcher. */
+export type ExecuteParams = {
+  chatId: string;
+  numericChatId: number;
+  prompt: string;
+  senderName: string;
+  isGroup: boolean;
+  messageId?: number;
+  source: "message" | "pulse" | "cron";
+  onStreamDelta?: (accumulated: string, phase?: "thinking" | "text") => void;
+  onTextBlock?: (text: string) => Promise<void>;
+  onToolUse?: (toolName: string, input: Record<string, unknown>) => void;
+};
+
+/** What the dispatcher returns after execution. */
+export type ExecuteResult = QueryResult & {
+  bridgeMessageCount: number;
+};
+
+// ── Gateway types ───────────────────────────────────────────────────────────
+
+/** Result from an action handler. */
+export type ActionResult = {
+  ok: boolean;
+  text?: string;
+  error?: string;
+  message_id?: number;
+  [key: string]: unknown;
+};
+
+/** Frontend-specific action handler. Return null if action not recognized. */
+export type FrontendActionHandler = (
+  body: Record<string, unknown>,
+  chatId: number,
+) => Promise<ActionResult | null>;

package/src/frontend/teams/actions.ts

@@ -0,0 +1,101 @@
+/**
+ * Teams action handler — routes MCP tool calls to Teams via Power Automate webhook.
+ */
+
+import type { ActionResult, FrontendActionHandler } from "../../core/types.js";
+import type { Gateway } from "../../core/gateway.js";
+import { buildAdaptiveCard, splitTeamsMessage } from "./formatting.js";
+import { log, logError } from "../../util/log.js";
+import { proxyFetch } from "./proxy-fetch.js";
+
+/**
+ * POST an Adaptive Card to the Power Automate workflow webhook URL.
+ */
+async function postToTeams(webhookUrl: string, text: string): Promise<void> {
+  const chunks = splitTeamsMessage(text);
+  for (const chunk of chunks) {
+    const card = buildAdaptiveCard(chunk);
+    const resp = await proxyFetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(card),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`Teams webhook POST failed: ${resp.status} ${body}`);
+    }
+  }
+}
+
+export function createTeamsActionHandler(
+  webhookUrl: string,
+  gateway: Gateway,
+): FrontendActionHandler {
+  return async (body, chatId): Promise<ActionResult | null> => {
+    const action = body.action as string;
+
+    switch (action) {
+      case "send_message": {
+        const text = String(body.text ?? "");
+        if (!text) return { ok: true, message_id: Date.now() };
+        try {
+          await postToTeams(webhookUrl, text);
+          gateway.incrementMessages(chatId);
+          log("teams", `Sent message to chat ${chatId} (${text.length} chars)`);
+          return { ok: true, message_id: Date.now() };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          logError("teams", `send_message failed: ${msg}`);
+          return { ok: false, error: msg };
+        }
+      }
+
+      case "send_message_with_buttons": {
+        const text = String(body.text ?? "");
+        const rows = body.rows as Array<Array<{ text: string; url?: string }>> | undefined;
+        const buttons = rows?.flat().map((b) => ({ text: b.text, url: b.url }));
+        try {
+          const card = buildAdaptiveCard(text, buttons);
+          const resp = await proxyFetch(webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(card),
+            signal: AbortSignal.timeout(15_000),
+          });
+          if (!resp.ok) throw new Error(`${resp.status}`);
+          gateway.incrementMessages(chatId);
+          return { ok: true, message_id: Date.now() };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          logError("teams", `send_message_with_buttons failed: ${msg}`);
+          return { ok: false, error: msg };
+        }
+      }
+
+      // Graceful no-ops for unsupported actions
+      case "react":
+      case "edit_message":
+      case "delete_message":
+      case "pin_message":
+      case "unpin_message":
+      case "forward_message":
+      case "copy_message":
+      case "send_chat_action":
+        return { ok: true };
+
+      case "get_chat_info":
+        return {
+          ok: true,
+          id: chatId,
+          type: "channel",
+          title: "Teams Channel",
+        };
+
+      default:
+        return null;
+    }
+  };
+}
+
+export { postToTeams };

package/src/frontend/teams/formatting.ts

@@ -0,0 +1,220 @@
+/**
+ * Teams message formatting — markdown to Adaptive Cards + HTML stripping.
+ *
+ * Uses `marked` lexer to parse markdown into tokens, then converts each
+ * token to the appropriate Adaptive Card element:
+ *   - Paragraphs/text → TextBlock (with bold/italic markdown, no backticks)
+ *   - Fenced code blocks → monospace TextBlock in emphasis Container
+ *   - Tables → native Table element (Adaptive Cards v1.5)
+ *   - Lists → TextBlock with bullet/number prefixes
+ *   - Headings → bold TextBlock
+ */
+
+import * as cheerio from "cheerio";
+import { marked } from "marked";
+
+/** Max safe message length for a single Adaptive Card. */
+const MAX_CHUNK = 10_000;
+
+// ── Markdown → Adaptive Card ──────────────────────────────────────────────
+
+type CardElement = Record<string, unknown>;
+
+/**
+ * Convert markdown text to Adaptive Card body elements.
+ */
+function markdownToCardBody(text: string): CardElement[] {
+  const body: CardElement[] = [];
+  const tokens = marked.lexer(text);
+
+  for (const token of tokens) {
+    switch (token.type) {
+      case "heading":
+        body.push({ type: "TextBlock", text: `**${cleanInline(token.text)}**`, wrap: true, size: "Medium", weight: "Bolder" });
+        break;
+
+      case "paragraph":
+        body.push({ type: "TextBlock", text: cleanInline(token.text), wrap: true });
+        break;
+
+      case "code": {
+        // Each line as a separate TextBlock to preserve newlines.
+        // Replace spaces with non-breaking spaces (\u00a0) to preserve alignment —
+        // Teams TextBlock collapses consecutive regular spaces.
+        const lines = (token.text as string).split("\n");
+        body.push({
+          type: "Container",
+          style: "emphasis",
+          items: lines.map((line) => ({
+            type: "TextBlock",
+            text: (line || " ").replace(/ /g, "\u00a0"),
+            wrap: false,
+            fontType: "Monospace",
+            size: "Small",
+            spacing: "None",
+          })),
+        });
+        break;
+      }
+
+      case "list": {
+        const listToken = token as Record<string, unknown>;
+        const items = listToken.items as Array<{ text: string }>;
+        const ordered = listToken.ordered as boolean;
+        const lines = items.map((item, i) => {
+          const prefix = ordered ? `${i + 1}. ` : "- ";
+          return prefix + cleanInline(item.text);
+        });
+        body.push({ type: "TextBlock", text: lines.join("\n"), wrap: true });
+        break;
+      }
+
+      case "table": {
+        const tableToken = token as Record<string, unknown>;
+        const header = tableToken.header as Array<{ text: string }>;
+        const rows = tableToken.rows as Array<Array<{ text: string }>>;
+
+        const headerRow = {
+          type: "TableRow",
+          style: "accent",
+          cells: header.map((cell) => ({
+            type: "TableCell",
+            items: [{ type: "TextBlock", text: cleanInline(cell.text), weight: "Bolder", wrap: true }],
+          })),
+        };
+
+        const dataRows = rows.map((row) => ({
+          type: "TableRow",
+          cells: row.map((cell) => ({
+            type: "TableCell",
+            items: [{ type: "TextBlock", text: cleanInline(cell.text), wrap: true }],
+          })),
+        }));
+
+        body.push({
+          type: "Table",
+          gridStyle: "accent",
+          firstRowAsHeader: true,
+          columns: header.map(() => ({ width: 1 })),
+          rows: [headerRow, ...dataRows],
+        });
+        break;
+      }
+
+      case "blockquote": {
+        const bqToken = token as Record<string, unknown>;
+        body.push({
+          type: "Container",
+          style: "emphasis",
+          items: [{ type: "TextBlock", text: cleanInline(String(bqToken.text ?? "")), wrap: true, isSubtle: true }],
+        });
+        break;
+      }
+
+      case "hr":
+        body.push({ type: "TextBlock", text: "───────────────────────────────", wrap: false, isSubtle: true });
+        break;
+
+      case "space":
+        break; // skip whitespace tokens
+
+      default:
+        // Fallback: render as plain text
+        if ("text" in token && typeof token.text === "string" && token.text.trim()) {
+          body.push({ type: "TextBlock", text: cleanInline(token.text), wrap: true });
+        }
+        break;
+    }
+  }
+
+  if (body.length === 0) {
+    body.push({ type: "TextBlock", text: text || " ", wrap: true });
+  }
+
+  return body;
+}
+
+/**
+ * Clean inline markdown for Teams TextBlock compatibility.
+ * Teams supports **bold** and _italic_ but NOT `inline code`.
+ */
+function cleanInline(text: string): string {
+  // Remove inline backticks — Teams doesn't render them
+  return text.replace(/`([^`]+)`/g, "$1");
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Build an Adaptive Card payload for the Power Automate webhook.
+ */
+export function buildAdaptiveCard(
+  text: string,
+  buttons?: Array<{ text: string; url?: string }>,
+): Record<string, unknown> {
+  const body = markdownToCardBody(text);
+
+  const card: Record<string, unknown> = {
+    type: "AdaptiveCard",
+    $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+    version: "1.5",
+    body,
+  };
+
+  if (buttons && buttons.length > 0) {
+    card.actions = buttons.map((b) =>
+      b.url
+        ? { type: "Action.OpenUrl", title: b.text, url: b.url }
+        : { type: "Action.Submit", title: b.text, data: { choice: b.text } },
+    );
+  }
+
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        contentUrl: null,
+        content: card,
+      },
+    ],
+  };
+}
+
+/**
+ * Split a long message into chunks that each fit within an Adaptive Card.
+ * Splits on paragraph boundaries when possible.
+ */
+export function splitTeamsMessage(text: string, maxLen = MAX_CHUNK): string[] {
+  if (text.length <= maxLen) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > maxLen) {
+    let splitIdx = remaining.lastIndexOf("\n\n", maxLen);
+    if (splitIdx < maxLen * 0.3) {
+      splitIdx = remaining.lastIndexOf("\n", maxLen);
+    }
+    if (splitIdx < maxLen * 0.3) {
+      splitIdx = maxLen;
+    }
+    chunks.push(remaining.slice(0, splitIdx).trimEnd());
+    remaining = remaining.slice(splitIdx).trimStart();
+  }
+  if (remaining) chunks.push(remaining);
+  return chunks;
+}
+
+/**
+ * Strip HTML tags and decode entities from inbound Teams message HTML.
+ */
+export function stripHtml(html: string): string {
+  if (!html || !html.includes("<")) return html;
+  try {
+    const $ = cheerio.load(html, { xml: false });
+    return $.text().trim();
+  } catch {
+    return html.replace(/<[^>]*>/g, "").trim();
+  }
+}