talon-agent 1.0.0

package/src/core/gateway.ts

@@ -0,0 +1,258 @@
+/**
+ * Gateway — generic HTTP bridge between MCP tool subprocess and the active frontend.
+ *
+ * The MCP subprocess (tools.ts) calls POST /action with action bodies.
+ * The gateway tries shared actions first (cron, fetch_url, history),
+ * then delegates to the active frontend's action handler.
+ *
+ * No platform-specific imports — frontends register their handler at startup.
+ */
+
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import { classify } from "./errors.js";
+import { getActiveCount } from "./dispatcher.js";
+import { getHealthStatus } from "../util/watchdog.js";
+import { getActiveSessionCount } from "../storage/sessions.js";
+import { log, logError, logDebug } from "../util/log.js";
+import { handleSharedAction } from "./gateway-actions.js";
+import { handlePluginAction } from "./plugin.js";
+import type { FrontendActionHandler } from "./types.js";
+
+// ── Per-chat context state ───────────────────────────────────────────────────
+
+type ChatContext = { refCount: number; messagesSent: number; stringId?: string };
+
+// ── Retry helper (stateless — standalone export) ─────────────────────────────
+
+export async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      const classified = classify(err);
+      if (!classified.retryable) throw err;
+      if (attempt < 2) {
+        const delayMs = classified.retryAfterMs ?? 1000 * Math.pow(2, attempt);
+        log("gateway", `Retry ${attempt + 1}/3 (${classified.reason}) after ${delayMs}ms`);
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+    }
+  }
+  throw lastError;
+}
+
+// ── Gateway class ────────────────────────────────────────────────────────────
+
+export class Gateway {
+  private chatContexts = new Map<number, ChatContext>();
+  private frontendHandler: FrontendActionHandler | null = null;
+  private server: ReturnType<typeof createServer> | null = null;
+  private port = 0;
+
+  // ── Frontend handler registration ────────────────────────────────────────
+
+  setFrontendHandler(handler: FrontendActionHandler): void {
+    this.frontendHandler = handler;
+  }
+
+  // ── Per-chat context management ──────────────────────────────────────────
+
+  setContext(chatId: number, stringId?: string): void {
+    const ctx = this.chatContexts.get(chatId);
+    if (ctx) {
+      ctx.refCount++;
+      log("gateway", `Context ref++ for chat ${chatId} (refCount=${ctx.refCount})`);
+    } else {
+      this.chatContexts.set(chatId, { refCount: 1, messagesSent: 0, stringId });
+      log("gateway", `Context acquired for chat ${chatId}${stringId ? ` (${stringId})` : ""}`);
+    }
+  }
+
+  /** Find a numeric chatId by its string ID (used for Teams-style non-numeric chat IDs). */
+  private findContextByStringId(stringId: string): number | null {
+    if (!stringId) return null;
+    for (const [numId, ctx] of this.chatContexts) {
+      if (ctx.stringId === stringId) return numId;
+    }
+    return null;
+  }
+
+  clearContext(chatId?: number | string): void {
+    if (chatId === undefined) return;
+    const parsed = typeof chatId === "number" ? chatId : Number(chatId);
+    // For non-numeric IDs (e.g. Teams "19:abc..."), Number() returns NaN — look up by string
+    const numId = !isNaN(parsed) ? parsed : this.findContextByStringId(String(chatId));
+    if (numId === null) return;
+    const ctx = this.chatContexts.get(numId);
+    if (!ctx) return;
+    ctx.refCount = Math.max(0, ctx.refCount - 1);
+    if (ctx.refCount <= 0) {
+      this.chatContexts.delete(numId);
+      log("gateway", `Context released for chat ${numId}`);
+    }
+  }
+
+  isChatBusy(chatId: number): boolean {
+    return this.chatContexts.has(chatId);
+  }
+
+  getMessageCount(chatId: number): number {
+    return this.chatContexts.get(chatId)?.messagesSent ?? 0;
+  }
+
+  incrementMessages(chatId: number): void {
+    const ctx = this.chatContexts.get(chatId);
+    if (ctx) ctx.messagesSent++;
+  }
+
+  getPort(): number {
+    return this.port;
+  }
+
+  getActiveChats(): number {
+    return this.chatContexts.size;
+  }
+
+  // ── Action dispatch ────────────────────────────────────────────────────────
+
+  private async handleAction(body: Record<string, unknown>): Promise<unknown> {
+    // Route by _chatId from the MCP subprocess request.
+    // _chatId may be a string (Teams: "teams_chat_19:...") or numeric string (Telegram: "123456").
+    // The context map is keyed by numeric chatId, so try direct parse first,
+    // then fall back to searching active contexts.
+    const rawChatId = body._chatId ? String(body._chatId) : "";
+    const numericId = Number(rawChatId);
+    const chatId = !isNaN(numericId) && this.chatContexts.has(numericId)
+      ? numericId
+      : this.findContextByStringId(rawChatId);
+    if (!chatId) {
+      return { ok: false, error: "No active chat context" };
+    }
+
+    const action = typeof body.action === "string" ? body.action : "";
+    if (!action) return { ok: false, error: "Missing action" };
+    const t0 = Date.now();
+
+    try {
+      // Try frontend first — it has richer implementations (e.g. userbot history)
+      // and falls back to null when it can't handle the action.
+      if (this.frontendHandler) {
+        const result = await this.frontendHandler(body, chatId);
+        if (result) {
+          logDebug("gateway", `${action} chat=${chatId} ${Date.now() - t0}ms`);
+          return result;
+        }
+      }
+
+      // Try plugin actions (loaded from external plugin packages)
+      const pluginResult = await handlePluginAction(body, String(chatId));
+      if (pluginResult) {
+        logDebug("gateway", `${action} chat=${chatId} ${Date.now() - t0}ms (plugin)`);
+        return pluginResult;
+      }
+
+      // Shared actions last — provides in-memory fallbacks for history, cron, etc.
+      const shared = await handleSharedAction(body, chatId);
+      if (shared) {
+        logDebug("gateway", `${action} chat=${chatId} ${Date.now() - t0}ms (shared)`);
+        return shared;
+      }
+
+      return { ok: false, error: `Unknown action: ${action}` };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("gateway", `${action} chat=${chatId} failed: ${msg}`);
+      return { ok: false, error: `${action}: ${msg}` };
+    }
+  }
+
+  // ── HTTP server ──────────────────────────────────────────────────────────
+
+  async start(port = 19876): Promise<number> {
+    if (this.server) return this.port;
+
+    const httpServer = createServer(
+      async (req: IncomingMessage, res: ServerResponse) => {
+        if (req.method === "GET" && req.url === "/health") {
+          const w = getHealthStatus();
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            ok: w.healthy,
+            uptime: Math.round(process.uptime()),
+            memory: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+            bridge: { activeChats: this.chatContexts.size },
+            queue: getActiveCount(),
+            sessions: getActiveSessionCount(),
+            messages: w.totalMessagesProcessed,
+            errors: w.recentErrorCount,
+            lastActivity: w.msSinceLastMessage < 60000
+              ? "just now"
+              : `${Math.round(w.msSinceLastMessage / 60000)}m ago`,
+          }));
+          return;
+        }
+
+        if (req.method !== "POST" || req.url !== "/action") {
+          res.writeHead(404);
+          res.end("Not found");
+          return;
+        }
+
+        try {
+          const chunks: Buffer[] = [];
+          for await (const chunk of req) chunks.push(chunk as Buffer);
+          let body: Record<string, unknown>;
+          try {
+            body = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+          } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: false, error: "Invalid JSON" }));
+            return;
+          }
+          const result = await this.handleAction(body);
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: false, error: msg }));
+        }
+      },
+    );
+
+    return new Promise<number>((resolve, reject) => {
+      let attempt = 0;
+      const tryPort = (p: number) => {
+        httpServer.once("error", (err: NodeJS.ErrnoException) => {
+          if (err.code === "EADDRINUSE" && attempt < 5) {
+            attempt++;
+            httpServer.removeAllListeners("error");
+            tryPort(p + 1);
+          } else {
+            reject(err);
+          }
+        });
+        httpServer.listen(p, "127.0.0.1", () => {
+          this.server = httpServer;
+          this.port = p;
+          log("gateway", `Action gateway on :${p}`);
+          resolve(p);
+        });
+      };
+      tryPort(port);
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.server) { resolve(); return; }
+      this.server.close(() => { this.server = null; this.port = 0; resolve(); });
+    });
+  }
+}

package/src/core/plugin.ts

@@ -0,0 +1,432 @@
+/**
+ * Plugin system — extensible tool integration for Talon.
+ *
+ * Design principles:
+ *   - Interface Segregation: plugins implement only what they need
+ *   - Open/Closed: lifecycle hooks allow extension without core changes
+ *   - Dependency Inversion: plugins receive config, don't depend on globals
+ *   - Single Responsibility: loader, registry, and routing are separated
+ *   - Error Isolation: one plugin failing doesn't take down others
+ *
+ * Plugin config in talon.json:
+ *   "plugins": [
+ *     { "path": "/path/to/plugin", "config": { ... } }
+ *   ]
+ */
+
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { log, logError, logWarn } from "../util/log.js";
+import type { ActionResult } from "./types.js";
+
+// ── Plugin interfaces ──────────────────────────────────────────────────────
+
+/** Configuration entry for a plugin in talon.json. */
+export interface PluginEntry {
+  path: string;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Core plugin interface — only `name` is required.
+ * All other capabilities are optional (Interface Segregation).
+ */
+export interface TalonPlugin {
+  /** Unique plugin identifier. Used as MCP server name prefix. */
+  readonly name: string;
+
+  /** Human-readable description for status/diagnostics. */
+  readonly description?: string;
+
+  /** Semver version string. */
+  readonly version?: string;
+
+  /**
+   * Frontend whitelist — which frontends this plugin is active for.
+   * If unset, the plugin is available on all frontends.
+   * Example: ["telegram"] — only loads when Telegram frontend is active.
+   */
+  readonly frontends?: readonly string[];
+
+  /**
+   * Called once after the plugin is loaded and validated.
+   * Use for one-time setup (connections, caches, etc).
+   * Receives the resolved plugin config.
+   */
+  init?(config: Record<string, unknown>): Promise<void> | void;
+
+  /**
+   * Called during graceful shutdown. Clean up resources.
+   */
+  destroy?(): Promise<void> | void;
+
+  /**
+   * Absolute path to the MCP server script (spawned as subprocess).
+   * Omit if the plugin only provides action handlers without MCP tools.
+   */
+  mcpServerPath?: string;
+
+  /**
+   * Map plugin config to env vars for the MCP subprocess and action handlers.
+   * Called once at load time. Values are set on process.env for the main
+   * process and passed to the MCP subprocess.
+   */
+  getEnvVars?(config: Record<string, unknown>): Record<string, string>;
+
+  /**
+   * Handle a gateway action. Return null if not recognized.
+   * Actions are tried in plugin load order, first non-null wins.
+   */
+  handleAction?(
+    body: Record<string, unknown>,
+    chatId: string,
+  ): Promise<ActionResult | null>;
+
+  /**
+   * Contribute additional context to the system prompt.
+   * Called during config loading. Return text to append.
+   */
+  getSystemPromptAddition?(config: Record<string, unknown>): string;
+
+  /**
+   * Validate plugin config at load time.
+   * Return an array of error messages, or empty/undefined if valid.
+   */
+  validateConfig?(config: Record<string, unknown>): string[] | undefined;
+}
+
+// ── Plugin registry ────────────────────────────────────────────────────────
+
+/** A loaded and validated plugin instance with its resolved config. */
+export interface LoadedPlugin {
+  readonly plugin: TalonPlugin;
+  readonly config: Record<string, unknown>;
+  readonly envVars: Record<string, string>;
+  readonly path: string;
+}
+
+class PluginRegistry {
+  private readonly plugins: LoadedPlugin[] = [];
+
+  get all(): readonly LoadedPlugin[] {
+    return this.plugins;
+  }
+
+  get count(): number {
+    return this.plugins.length;
+  }
+
+  register(loaded: LoadedPlugin): void {
+    // Guard against duplicate names
+    const existing = this.plugins.find(
+      (p) => p.plugin.name === loaded.plugin.name,
+    );
+    if (existing) {
+      logWarn(
+        "plugin",
+        `Duplicate plugin name "${loaded.plugin.name}" — skipping (already loaded from ${existing.path})`,
+      );
+      return;
+    }
+    this.plugins.push(loaded);
+  }
+
+  getByName(name: string): LoadedPlugin | undefined {
+    return this.plugins.find((p) => p.plugin.name === name);
+  }
+
+  async destroyAll(): Promise<void> {
+    for (const { plugin } of this.plugins) {
+      try {
+        await plugin.destroy?.();
+      } catch (err) {
+        logError(
+          "plugin",
+          `${plugin.name} destroy error: ${err instanceof Error ? err.message : err}`,
+        );
+      }
+    }
+  }
+}
+
+// Module-level singleton
+const registry = new PluginRegistry();
+
+/** Internal deps — exposed as an object so tests can replace properties.
+ *  Direct function exports can't be mocked for internal callers in ESM. */
+export const _deps = {
+  importModule: async (path: string): Promise<Record<string, unknown>> =>
+    import(path),
+};
+
+// ── Loader ─────────────────────────────────────────────────────────────────
+
+/** Candidate entry point paths, checked in order. */
+const ENTRY_CANDIDATES = [
+  "src/index.ts",
+  "dist/index.js",
+  "index.ts",
+  "index.js",
+];
+
+/**
+ * Load and validate plugins from config entries.
+ * Plugins that fail to load are logged and skipped — they don't block others.
+ * @param activeFrontends — currently active frontends (e.g. ["terminal"]). Plugins
+ *   with a `frontends` whitelist are skipped if none match.
+ */
+export async function loadPlugins(
+  pluginConfigs: PluginEntry[],
+  activeFrontends?: string[],
+): Promise<void> {
+  for (const entry of pluginConfigs) {
+    try {
+      await loadSinglePlugin(entry, activeFrontends);
+    } catch (err) {
+      logError(
+        "plugin",
+        `Failed to load plugin at ${entry.path}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
+async function loadSinglePlugin(
+  entry: PluginEntry,
+  activeFrontends?: string[],
+): Promise<void> {
+  const pluginDir = resolve(entry.path);
+
+  // Resolve entry point
+  const entryPoint = resolveEntryPoint(pluginDir);
+  if (!entryPoint) {
+    logError(
+      "plugin",
+      `No entry point found in ${pluginDir} (tried: ${ENTRY_CANDIDATES.join(", ")})`,
+    );
+    return;
+  }
+
+  // Import and extract plugin module
+  const mod = await _deps.importModule(entryPoint);
+  const plugin = extractPlugin(mod);
+  if (!plugin) {
+    logError(
+      "plugin",
+      `Invalid plugin at ${pluginDir}: must export an object with a "name" property`,
+    );
+    return;
+  }
+
+  // Check frontend whitelist — skip if plugin specifies frontends and none match
+  if (plugin.frontends && plugin.frontends.length > 0 && activeFrontends) {
+    const match = activeFrontends.some((fe) => plugin.frontends!.includes(fe));
+    if (!match) {
+      log(
+        "plugin",
+        `Skipped: ${plugin.name} (requires ${plugin.frontends.join("/")} frontend)`,
+      );
+      return;
+    }
+  }
+
+  const config = entry.config ?? {};
+
+  // Validate config if the plugin provides validation
+  const errors = plugin.validateConfig?.(config);
+  if (errors && errors.length > 0) {
+    logError(
+      "plugin",
+      `Plugin "${plugin.name}" config validation failed:\n  ${errors.join("\n  ")}`,
+    );
+    return;
+  }
+
+  // Resolve env vars
+  const envVars = plugin.getEnvVars?.(config) ?? {};
+
+  // Set env vars on main process for action handlers
+  for (const [k, v] of Object.entries(envVars)) {
+    process.env[k] = v;
+  }
+
+  // Register before init (so other plugins can discover it)
+  const loaded: LoadedPlugin = { plugin, config, envVars, path: pluginDir };
+  registry.register(loaded);
+
+  // Run init hook
+  const INIT_TIMEOUT = 30_000;
+  try {
+    await Promise.race([
+      plugin.init?.(config),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error("init timeout (30s)")), INIT_TIMEOUT),
+      ),
+    ]);
+  } catch (err) {
+    logError(
+      "plugin",
+      `Plugin "${plugin.name}" init failed: ${err instanceof Error ? err.message : err}`,
+    );
+    // Still registered — tools may work even if init partially failed
+  }
+
+  const version = plugin.version ? ` v${plugin.version}` : "";
+  const desc = plugin.description ? ` — ${plugin.description}` : "";
+  log("plugin", `Loaded: ${plugin.name}${version}${desc}`);
+}
+
+function resolveEntryPoint(pluginDir: string): string | null {
+  for (const candidate of ENTRY_CANDIDATES) {
+    const full = resolve(pluginDir, candidate);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+
+function extractPlugin(mod: Record<string, unknown>): TalonPlugin | null {
+  // Support: export default { ... } or module.exports = { ... }
+  const candidate = mod.default ?? mod;
+  if (!candidate || typeof candidate !== "object") return null;
+  const plugin = candidate as Record<string, unknown>;
+  // Validate required field types
+  if (typeof plugin.name !== "string" || !plugin.name) return null;
+  // Validate optional fields are the right types if present
+  if (
+    plugin.handleAction !== undefined &&
+    typeof plugin.handleAction !== "function"
+  )
+    return null;
+  if (plugin.init !== undefined && typeof plugin.init !== "function")
+    return null;
+  if (
+    plugin.getSystemPromptAddition !== undefined &&
+    typeof plugin.getSystemPromptAddition !== "function"
+  )
+    return null;
+  if (
+    plugin.mcpServerPath !== undefined &&
+    typeof plugin.mcpServerPath !== "string"
+  )
+    return null;
+  if (plugin.frontends !== undefined && !Array.isArray(plugin.frontends))
+    return null;
+  return candidate as TalonPlugin;
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/** Get all loaded plugins. */
+export function getLoadedPlugins(): readonly LoadedPlugin[] {
+  return registry.all;
+}
+
+/** Get a plugin by name. */
+export function getPlugin(name: string): LoadedPlugin | undefined {
+  return registry.getByName(name);
+}
+
+/** Number of loaded plugins. */
+export function getPluginCount(): number {
+  return registry.count;
+}
+
+/** Destroy all plugins (called during shutdown). */
+export async function destroyPlugins(): Promise<void> {
+  await registry.destroyAll();
+}
+
+/**
+ * Collect system prompt additions from all plugins.
+ * Called during config/prompt assembly.
+ */
+export function getPluginPromptAdditions(): string[] {
+  const additions: string[] = [];
+  for (const { plugin, config } of registry.all) {
+    try {
+      const addition = plugin.getSystemPromptAddition?.(config);
+      if (addition?.trim()) additions.push(addition.trim());
+    } catch (err) {
+      logError(
+        "plugin",
+        `${plugin.name} prompt addition error: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+  return additions;
+}
+
+// ── Action routing ─────────────────────────────────────────────────────────
+
+/**
+ * Route an action through all loaded plugins.
+ * Returns the first non-null result. Errors from individual plugins
+ * are caught and returned as error results — they don't cascade.
+ */
+export async function handlePluginAction(
+  body: Record<string, unknown>,
+  chatId: string,
+): Promise<ActionResult | null> {
+  for (const { plugin } of registry.all) {
+    if (!plugin.handleAction) continue;
+    try {
+      const result = await plugin.handleAction(body, chatId);
+      if (result) return result;
+    } catch (err) {
+      logError(
+        "plugin",
+        `${plugin.name} action error: ${err instanceof Error ? err.message : err}`,
+      );
+      return {
+        ok: false,
+        error: `Plugin ${plugin.name}: ${err instanceof Error ? err.message : err}`,
+      };
+    }
+  }
+  return null;
+}
+
+// ── MCP server config ──────────────────────────────────────────────────────
+
+/** MCP server configuration for the Claude Agent SDK. */
+export interface McpServerConfig {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+/**
+ * Build MCP server entries for all plugins that provide an MCP server.
+ * Plugins without `mcpServerPath` are skipped.
+ */
+export function getPluginMcpServers(
+  bridgeUrl: string,
+  chatId: string,
+): Record<string, McpServerConfig> {
+  const servers: Record<string, McpServerConfig> = {};
+
+  // Resolve tsx from Talon's own node_modules (not cwd which may be ~/.talon/workspace/)
+  const tsxPath = resolve(
+    import.meta.dirname ?? ".",
+    "../../node_modules/tsx/dist/esm/index.mjs",
+  );
+
+  for (const { plugin, envVars } of registry.all) {
+    if (!plugin.mcpServerPath) continue;
+
+    servers[`${plugin.name}-tools`] = {
+      command: process.platform === "win32" ? "npx" : "node",
+      args:
+        process.platform === "win32"
+          ? ["tsx", plugin.mcpServerPath]
+          : ["--import", tsxPath, plugin.mcpServerPath],
+      env: {
+        TALON_BRIDGE_URL: bridgeUrl,
+        TALON_CHAT_ID: chatId,
+        ...envVars,
+      },
+    };
+  }
+
+  return servers;
+}