talon-agent 1.3.0 → 1.5.0

package/src/core/tools/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared types for the modular tool system.
+ *
+ * Tool definitions are pure data + execute logic — no MCP imports,
+ * no bridge coupling.  The MCP server consumes these via composeTools().
+ */
+
+import type { ZodRawShape } from "zod";
+
+/** Which frontends a tool is available on.  "all" = every frontend. */
+export type ToolFrontend = "telegram" | "teams" | "terminal" | "all";
+
+/** Domain tags for runtime filtering and grouping. */
+export type ToolTag =
+  | "messaging"
+  | "chat"
+  | "history"
+  | "members"
+  | "media"
+  | "stickers"
+  | "scheduling"
+  | "web"
+  | "admin";
+
+/** The bridge caller signature — injected into execute(). */
+export type BridgeFunction = (
+  action: string,
+  params: Record<string, unknown>,
+) => Promise<unknown>;
+
+/**
+ * A self-contained tool definition.
+ *
+ * Contains everything needed to register it with an MCP server
+ * AND to know which bridge action it maps to.
+ */
+export interface ToolDefinition {
+  /** MCP tool name (e.g. "send", "react", "fetch_url"). */
+  readonly name: string;
+
+  /** Human-readable description shown to the model. */
+  readonly description: string;
+
+  /** Zod schema shape for the tool's input parameters. */
+  readonly schema: ZodRawShape;
+
+  /**
+   * Execute the tool.  Receives validated params and a bridge caller.
+   * Returns the raw bridge result (wrapped by the MCP layer).
+   */
+  readonly execute: (
+    params: Record<string, unknown>,
+    bridge: BridgeFunction,
+  ) => Promise<unknown>;
+
+  /** Which frontends this tool appears on. Omit for all frontends. */
+  readonly frontends?: readonly ToolFrontend[];
+
+  /** Grouping tag. */
+  readonly tag: ToolTag;
+}

package/src/core/tools/web.ts

@@ -0,0 +1,26 @@
+/**
+ * Web tools — URL fetching.
+ *
+ * Platform-agnostic, available on all frontends.
+ * Web search is handled by the Brave Search MCP server (registered in
+ * src/backend/claude-sdk/index.ts) when configured. URL fetching is provided here via
+ * the `fetch_url` tool, so Claude Code's built-in WebSearch / WebFetch are
+ * disabled in favor of these project-specific replacements.
+ * These can be excluded via composeTools({ excludeTags: ["web"] }).
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+export const webTools: ToolDefinition[] = [
+  {
+    name: "fetch_url",
+    description:
+      "Fetch a URL — web pages return text content, image URLs are downloaded to workspace. Use to read articles, download images, or fetch any URL.",
+    schema: {
+      url: z.string().describe("The URL to fetch"),
+    },
+    execute: (params, bridge) => bridge("fetch_url", params),
+    tag: "web",
+  },
+];

package/src/frontend/teams/index.ts

@@ -217,6 +217,9 @@ export function createTeamsFrontend(
               resetSession(talonChatId);
               clearHistory(talonChatId);
               log("teams", `Session reset by ${msg.senderName}`);
+              const { warmSession } =
+                await import("../../backend/claude-sdk/index.js");
+              await warmSession(talonChatId);
               const card = buildAdaptiveCard("Session cleared.");
               await proxyFetch(webhookUrl, {
                 method: "POST",
@@ -246,15 +249,11 @@ export function createTeamsFrontend(
               ).replace("claude-", "");
               const avgMs =
                 info.turns > 0 ? Math.round(u.totalResponseMs / info.turns) : 0;
-              const contextUsed = u.lastPromptTokens;
-              const contextMax = model.includes("opus")
-                ? 1_000_000
-                : model.includes("sonnet")
-                  ? 1_000_000
-                  : 200_000;
-              const contextPct =
-                contextMax > 0
-                  ? Math.round((contextUsed / contextMax) * 100)
+              const ctxUsed = u.contextTokens || u.lastPromptTokens;
+              const ctxMax = u.contextWindow;
+              const ctxPct =
+                ctxMax > 0
+                  ? Math.min(100, Math.round((ctxUsed / ctxMax) * 100))
                   : 0;
               const card = {
                 type: "message",
@@ -282,7 +281,7 @@ export function createTeamsFrontend(
                             { title: "Turns", value: String(info.turns) },
                             {
                               title: "Context",
-                              value: `${(contextUsed / 1000).toFixed(0)}K / ${(contextMax / 1000).toFixed(0)}K (${contextPct}%)`,
+                              value: `${(ctxUsed / 1000).toFixed(0)}K / ${(ctxMax / 1000).toFixed(0)}K (${ctxPct}%)`,
                             },
                             { title: "Cache", value: `${cacheHit}% hit` },
                             {

package/src/frontend/telegram/actions.ts

@@ -278,7 +278,10 @@ export function createTelegramActionHandler(
       case "send_voice":
       case "send_audio": {
         const filePath = String(body.file_path ?? "");
-        const caption = body.caption ? String(body.caption) : undefined;
+        const caption = body.caption
+          ? markdownToTelegramHtml(String(body.caption))
+          : undefined;
+        const captionParseMode = caption ? ("HTML" as const) : undefined;
         gateway.incrementMessages(chatId);
         if (action === "send_file") {
           const stat = statSync(filePath);
@@ -294,6 +297,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendDocument(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -302,6 +306,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendPhoto(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -310,6 +315,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendVideo(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -318,6 +324,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendAnimation(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );
@@ -326,6 +333,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendAudio(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
                 title: body.title as string | undefined,
                 performer: body.performer as string | undefined,
@@ -336,6 +344,7 @@ export function createTelegramActionHandler(
             sent = await withRetry(() =>
               bot.api.sendVoice(chatId, file, {
                 caption,
+                parse_mode: captionParseMode,
                 reply_parameters: rp,
               }),
             );

package/src/frontend/telegram/commands.ts

@@ -38,6 +38,7 @@ import { appendDailyLog } from "../../storage/daily-log.js";
 import { escapeHtml } from "./formatting.js";
 import { handleAdminCommand } from "./admin.js";
 import { getLoadedPlugins } from "../../core/plugin.js";
+import { warmSession } from "../../backend/claude-sdk/index.js";
 import {
   formatDuration,
   formatTokenCount,
@@ -61,7 +62,7 @@ export function registerCommands(bot: Bot, config: TalonConfig): void {
       [
         "<b>\uD83E\uDD85 Talon</b>",
         "",
-        "Claude-powered Telegram assistant with 31 tools.",
+        "Agentic AI harness for Telegram.",
         "",
         "Send a message, photo, doc, or voice note.",
         "In groups, @mention or reply to activate.",
@@ -140,6 +141,8 @@ export function registerCommands(bot: Bot, config: TalonConfig): void {
     resetSession(cid);
     clearHistory(cid);
     resetPulseCheckpoint(cid);
+    // Warm up the new session so /status has context data immediately
+    await warmSession(cid);
     await ctx.reply("Session cleared.");
   });
 
@@ -424,17 +427,15 @@ export function registerCommands(bot: Bot, config: TalonConfig): void {
     const effortName = chatSets.effort ?? "adaptive";
     const pulseOn = isPulseEnabled(cid);
 
-    const contextMax = activeModel.includes("haiku") ? 200_000 : 1_000_000;
-    const contextUsed = u.lastPromptTokens;
-    const contextPct =
-      contextMax > 0
-        ? Math.min(100, Math.round((contextUsed / contextMax) * 100))
-        : 0;
+    const ctxUsed = u.contextTokens || u.lastPromptTokens;
+    const ctxMax = u.contextWindow; // from SDK modelUsage, preserved across turns
+    const ctxPct =
+      ctxMax > 0 ? Math.min(100, Math.round((ctxUsed / ctxMax) * 100)) : 0;
     const barLen = 20;
-    const filled = Math.round((contextPct / 100) * barLen);
+    const filled = Math.round((ctxPct / 100) * barLen);
     const contextBar =
       "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
-    const contextWarn = contextPct >= 80 ? " \u26A0\uFE0F consider /reset" : "";
+    const contextWarn = ctxPct >= 80 ? " \u26A0\uFE0F consider /reset" : "";
 
     const totalPrompt =
       u.totalInputTokens + u.totalCacheRead + u.totalCacheWrite;
@@ -455,7 +456,7 @@ export function registerCommands(bot: Bot, config: TalonConfig): void {
     const lines = [
       `<b>\uD83E\uDD85 Talon</b> \u00B7 <code>${escapeHtml(activeModel)}</code> \u00B7 effort: ${effortName}`,
       "",
-      `<b>Context</b>  ${formatTokenCount(contextUsed)} / ${formatTokenCount(contextMax)} (${contextPct}%)${contextWarn}`,
+      `<b>Context</b>  ${formatTokenCount(ctxUsed)} / ${formatTokenCount(ctxMax)} (${ctxPct}%)${contextWarn}`,
       `<code>${contextBar}</code>`,
       "",
       `<b>Session Stats</b>`,

package/src/plugins/github/index.ts

@@ -0,0 +1,106 @@
+/**
+ * GitHub plugin — GitHub API access via the official GitHub MCP server.
+ *
+ * Registers the GitHub MCP server (Docker image: ghcr.io/github/github-mcp-server),
+ * giving the agent access to repository management, issues, PRs, code search, etc.
+ *
+ * Configuration in ~/.talon/config.json:
+ *   "github": {
+ *     "enabled": true,
+ *     "token": "ghp_..."      // optional, defaults to `gh auth token` output
+ *   }
+ */
+
+import { execFileSync } from "node:child_process";
+import type { TalonPlugin } from "../../core/plugin.js";
+import { log, logWarn } from "../../util/log.js";
+
+/**
+ * Resolve a GitHub personal access token.
+ * Priority: explicit config > `gh auth token` CLI.
+ */
+function resolveToken(configToken?: string): string | undefined {
+  const trimmed = configToken?.trim();
+  if (trimmed) return trimmed;
+  try {
+    return execFileSync("gh", ["auth", "token"], {
+      timeout: 5_000,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+      .toString("utf-8")
+      .trim();
+  } catch {
+    return undefined;
+  }
+}
+
+export function createGitHubPlugin(config: { token?: string }): TalonPlugin {
+  const token = resolveToken(config.token);
+
+  return {
+    name: "github",
+    description: "GitHub API access via the official GitHub MCP server",
+    version: "1.0.0",
+
+    mcpServer: {
+      command: "docker",
+      args: [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server",
+      ],
+    },
+
+    validateConfig() {
+      const errors: string[] = [];
+
+      if (!token) {
+        errors.push(
+          'No GitHub token found. Set "token" in github config or run `gh auth login`.',
+        );
+      }
+
+      // Check Docker is available
+      try {
+        execFileSync("docker", ["info"], {
+          timeout: 10_000,
+          stdio: "pipe",
+        });
+      } catch {
+        errors.push(
+          "Docker is not available or not running. The GitHub MCP server requires Docker.",
+        );
+      }
+
+      return errors.length > 0 ? errors : undefined;
+    },
+
+    async init() {
+      // Verify the Docker image exists locally
+      try {
+        execFileSync(
+          "docker",
+          ["image", "inspect", "ghcr.io/github/github-mcp-server"],
+          { timeout: 10_000, stdio: "pipe" },
+        );
+        log("github", "Docker image verified");
+      } catch {
+        logWarn(
+          "github",
+          "Docker image not found locally — will pull on first use (may be slow)",
+        );
+      }
+
+      log("github", "Ready");
+    },
+
+    getEnvVars() {
+      return {
+        ...(token ? { GITHUB_PERSONAL_ACCESS_TOKEN: token } : {}),
+      };
+    },
+  };
+}

package/src/plugins/playwright/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Playwright plugin — browser automation via the official Playwright MCP server.
+ *
+ * Gives the agent headless Chromium for web scraping, screenshots, PDF generation,
+ * and general browser automation.
+ *
+ * Configuration in ~/.talon/config.json:
+ *   "playwright": {
+ *     "enabled": true,
+ *     "browser": "chromium",     // optional, default "chromium"
+ *     "headless": true           // optional, default true
+ *   }
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { TalonPlugin } from "../../core/plugin.js";
+import { log } from "../../util/log.js";
+
+export function createPlaywrightPlugin(config: {
+  browser?: string;
+  headless?: boolean;
+}): TalonPlugin {
+  const browser = config.browser ?? "chromium";
+  const headless = config.headless !== false; // default true
+
+  // Resolve path from Talon's node_modules
+  const mcpBin = resolve(
+    import.meta.dirname ?? ".",
+    "../../../node_modules/@playwright/mcp/cli.js",
+  );
+
+  const args = ["--no-sandbox"];
+
+  if (headless) {
+    args.push("--headless");
+  }
+
+  if (browser !== "chromium") {
+    args.push("--browser", browser);
+  }
+
+  return {
+    name: "playwright",
+    description: "Browser automation via Playwright MCP (headless Chromium)",
+    version: "1.0.0",
+
+    mcpServer: {
+      command: "node",
+      args: [mcpBin, ...args],
+    },
+
+    validateConfig() {
+      const errors: string[] = [];
+
+      const validBrowsers = [
+        "chromium",
+        "chrome",
+        "firefox",
+        "webkit",
+        "msedge",
+      ];
+      if (!validBrowsers.includes(browser)) {
+        errors.push(
+          `Invalid browser "${browser}". Valid options: ${validBrowsers.join(", ")}`,
+        );
+      }
+
+      if (!existsSync(mcpBin)) {
+        errors.push(
+          `@playwright/mcp not found at ${mcpBin} — run "npm install @playwright/mcp"`,
+        );
+      }
+
+      return errors.length > 0 ? errors : undefined;
+    },
+
+    async init() {
+      log("playwright", `Ready (${browser}, headless=${headless})`);
+    },
+  };
+}

package/src/storage/sessions.ts

@@ -18,8 +18,14 @@ type SessionUsage = {
   totalOutputTokens: number;
   totalCacheRead: number;
   totalCacheWrite: number;
-  /** Last turn's prompt tokens (context size snapshot). */
+  /** Last turn's total prompt tokens (cumulative across all API calls in the turn, including tool-use loops). */
   lastPromptTokens: number;
+  /** Actual context window fill from the last API call (last iteration's prompt tokens). */
+  contextTokens: number;
+  /** Model's context window size in tokens (from SDK modelUsage). */
+  contextWindow: number;
+  /** Number of API round-trips in the last turn (tool-use steps). */
+  numApiCalls: number;
   /** Estimated cost in USD. */
   estimatedCostUsd: number;
   /** Total response time in ms (for averaging). */
@@ -82,16 +88,6 @@ export function loadSessions(): void {
     );
     store = {};
   }
-  // SDK sessions don't survive process restarts — the embedded Claude Code
-  // subprocess is gone.  Clear stale session IDs so we don't try to resume
-  // a dead session (which causes the SDK to hang silently on Windows).
-  // Keep turns/usage intact — they're historical data used by /resume.
-  for (const session of Object.values(store)) {
-    if (session.sessionId) {
-      session.sessionId = undefined;
-      dirty = true;
-    }
-  }
 }
 
 function saveSessions(): void {
@@ -129,6 +125,9 @@ const emptyUsage = (): SessionUsage => ({
   totalCacheRead: 0,
   totalCacheWrite: 0,
   lastPromptTokens: 0,
+  contextTokens: 0,
+  contextWindow: 0,
+  numApiCalls: 0,
   estimatedCostUsd: 0,
   totalResponseMs: 0,
   lastResponseMs: 0,
@@ -160,6 +159,12 @@ export function getSession(chatId: string): SessionState {
     session.usage.fastestResponseMs === 0
   )
     session.usage.fastestResponseMs = Infinity;
+  // Migrate sessions from before context tracking was added
+  if (session.usage.contextTokens === undefined)
+    session.usage.contextTokens = 0;
+  if (session.usage.contextWindow === undefined)
+    session.usage.contextWindow = 0;
+  if (session.usage.numApiCalls === undefined) session.usage.numApiCalls = 0;
   return session;
 }
 
@@ -176,24 +181,6 @@ export function incrementTurns(chatId: string): void {
   dirty = true;
 }
 
-/** Model-specific pricing ($ per million tokens). */
-const MODEL_PRICING: Record<
-  string,
-  { input: number; output: number; cacheRead: number; cacheWrite: number }
-> = {
-  haiku: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
-  sonnet: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  opus: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-};
-
-function getPricing(model?: string): (typeof MODEL_PRICING)["sonnet"] {
-  if (!model) return MODEL_PRICING.sonnet;
-  const lower = model.toLowerCase();
-  if (lower.includes("haiku")) return MODEL_PRICING.haiku;
-  if (lower.includes("opus")) return MODEL_PRICING.opus;
-  return MODEL_PRICING.sonnet;
-}
-
 export function recordUsage(
   chatId: string,
   turn: {
@@ -203,25 +190,32 @@ export function recordUsage(
     cacheWrite: number;
     durationMs?: number;
     model?: string;
+    /** Actual context fill from the last API call (last iteration's prompt tokens). */
+    contextTokens?: number;
+    /** Model context window size from SDK modelUsage. */
+    contextWindow?: number;
+    /** Number of agentic turns / API round-trips in this turn. */
+    numApiCalls?: number;
   },
 ): void {
   const session = getSession(chatId);
+  // Token counts from SDK modelUsage (accumulated per-turn)
   session.usage.totalInputTokens += turn.inputTokens;
   session.usage.totalOutputTokens += turn.outputTokens;
   session.usage.totalCacheRead += turn.cacheRead;
   session.usage.totalCacheWrite += turn.cacheWrite;
-  // Snapshot: prompt tokens = input + cache_read + cache_write for this turn
   session.usage.lastPromptTokens =
     turn.inputTokens + turn.cacheRead + turn.cacheWrite;
-  // Model-aware cost estimate
-  const pricing = getPricing(turn.model);
-  session.usage.estimatedCostUsd +=
-    (turn.inputTokens * pricing.input +
-      turn.cacheWrite * pricing.cacheWrite +
-      turn.cacheRead * pricing.cacheRead +
-      turn.outputTokens * pricing.output) /
-    1_000_000;
-  // Track which model was last used
+  // Context info from SDK
+  session.usage.contextTokens = turn.contextTokens ?? 0;
+  if (
+    turn.contextWindow !== undefined &&
+    Number.isFinite(turn.contextWindow) &&
+    turn.contextWindow > 0
+  ) {
+    session.usage.contextWindow = turn.contextWindow;
+  }
+  session.usage.numApiCalls = turn.numApiCalls ?? 0;
   if (turn.model) session.lastModel = turn.model;
   // Response time tracking
   if (turn.durationMs && turn.durationMs > 0) {
@@ -301,17 +295,7 @@ export function getAllSessions(): Array<{ chatId: string; info: SessionInfo }> {
       turns: session.turns,
       lastActive: session.lastActive,
       createdAt: session.createdAt,
-      usage: session.usage ?? {
-        totalInputTokens: 0,
-        totalOutputTokens: 0,
-        totalCacheRead: 0,
-        totalCacheWrite: 0,
-        lastPromptTokens: 0,
-        estimatedCostUsd: 0,
-        totalResponseMs: 0,
-        lastResponseMs: 0,
-        fastestResponseMs: Infinity,
-      },
+      usage: session.usage ?? emptyUsage(),
       sessionName: session.sessionName,
       lastModel: session.lastModel,
     },

package/src/util/config.ts

@@ -40,10 +40,18 @@ const configSchema = z.object({
   heartbeatIntervalMinutes: z.number().int().min(5).default(60),
   heartbeatModel: z.string().optional(), // Model for heartbeat agent (defaults to main model)
   braveApiKey: z.string().optional(),
-  searxngUrl: z.string().default("http://localhost:8080"),
   timezone: z.string().optional(),
   plugins: z.array(pluginEntrySchema).default([]),
 
+  // GitHub — GitHub API access via official MCP server
+  github: z
+    .object({
+      enabled: z.boolean().default(false),
+      /** GitHub personal access token (default: from `gh auth token`) */
+      token: z.string().min(1).optional(),
+    })
+    .optional(),
+
   // MemPalace — structured long-term memory with vector search
   mempalace: z
     .object({
@@ -55,6 +63,17 @@ const configSchema = z.object({
     })
     .optional(),
 
+  // Playwright — headless browser automation via MCP
+  playwright: z
+    .object({
+      enabled: z.boolean().default(false),
+      /** Browser engine: chromium (default), chrome, firefox, webkit, msedge */
+      browser: z.string().optional(),
+      /** Run headless (default: true) */
+      headless: z.boolean().default(true),
+    })
+    .optional(),
+
   // Display name shown in terminal UI (defaults to "Talon")
   botDisplayName: z.string().default("Talon"),
 

package/src/util/log.ts

@@ -42,7 +42,9 @@ export type LogComponent =
   | "teams"
   | "config"
   | "access"
-  | "mempalace";
+  | "github"
+  | "mempalace"
+  | "playwright";
 
 const LOG_FILE = files.log;