talon-agent 3.33.4 → 3.34.1

package/src/core/engine/gateway-routes.ts

@@ -0,0 +1,239 @@
+/**
+ * The action gateway's HTTP routes — declared once, in order, rather than
+ * implied by where an `if` sits in `Gateway.start`. Every route shares the
+ * 127.0.0.1 trust boundary; the table is the list a reviewer reads.
+ */
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import { bus } from "../bus/index.js";
+import { taskTable } from "../tasks/index.js";
+import { handleHubRequest, HUB_PATH_PREFIX } from "../mcp-hub/index.js";
+import { log, logError } from "../../util/log.js";
+
+/** What the routes need from the Gateway that owns them. */
+export type GatewayRouteHost = {
+  /** The /health body — identity fields plus live counters. */
+  healthSnapshot: () => Record<string, unknown>;
+  /** Schedule a graceful stop; false when this process cannot be stopped this way. */
+  requestShutdown: () => boolean;
+  /** Hot-reload plugins from config; resolves to the loaded plugin names. */
+  reloadPlugins: () => Promise<string[]>;
+  /** Origin the MCP hub advertises for its own endpoints. */
+  hubOrigin: () => string;
+  /** The /action body handler. */
+  handleAction: (body: Record<string, unknown>) => Promise<unknown>;
+};
+
+type RouteContext = {
+  req: IncomingMessage;
+  res: ServerResponse;
+  url: URL;
+  host: GatewayRouteHost;
+};
+
+type GatewayRoute = {
+  method: "GET" | "POST" | "ANY";
+  path: string;
+  /** `prefix` matches `path` as a leading segment; default is an exact match. */
+  match?: "prefix";
+  handle: (ctx: RouteContext) => void | Promise<void>;
+};
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  // Serialise before writing headers: a body that cannot be stringified
+  // must surface as a 500, not as a half-sent 200 that never ends.
+  const json = JSON.stringify(body);
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(json);
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  return JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+}
+
+const ROUTES: readonly GatewayRoute[] = [
+  {
+    method: "GET",
+    path: "/health",
+    handle: ({ res, host }) => sendJson(res, 200, host.healthSnapshot()),
+  },
+  {
+    // Graceful stop for `talon stop`/`talon restart`. Respond before
+    // triggering so the client isn't cut off mid-request; the shutdown
+    // path takes seconds, so the reply flushes safely.
+    method: "POST",
+    path: "/shutdown",
+    handle: ({ res, host }) => {
+      if (!host.requestShutdown()) {
+        sendJson(res, 501, {
+          ok: false,
+          error: "Shutdown not supported by this process",
+        });
+        return;
+      }
+      sendJson(res, 200, { ok: true });
+    },
+  },
+  {
+    // Bus tail — recent events, optionally after a cursor. Read by `talon events`.
+    method: "GET",
+    path: "/events/recent",
+    match: "prefix",
+    handle: ({ res, url }) => {
+      const since = Number(url.searchParams.get("since") ?? "0");
+      sendJson(res, 200, {
+        ok: true,
+        events: bus.recent(Number.isInteger(since) && since > 0 ? since : 0),
+      });
+    },
+  },
+  {
+    // The task table — every live/recent unit of agent work. Read by `talon ps`.
+    method: "GET",
+    path: "/tasks",
+    handle: ({ res }) =>
+      sendJson(res, 200, { ok: true, tasks: taskTable.list() }),
+  },
+  {
+    // Abort one killable task by id — the transport for `talon kill`.
+    method: "POST",
+    path: "/tasks/kill",
+    handle: async ({ req, res }) => {
+      let id: unknown;
+      try {
+        id = ((await readJsonBody(req)) as { id?: unknown }).id;
+      } catch {
+        sendJson(res, 400, { ok: false, error: "Invalid JSON" });
+        return;
+      }
+      if (typeof id !== "number" || !Number.isInteger(id)) {
+        sendJson(res, 400, { ok: false, error: "id must be an integer" });
+        return;
+      }
+      sendJson(res, 200, taskTable.kill(id));
+    },
+  },
+  {
+    // Hot-reload plugins from config — the transport for `talon plugin
+    // install/enable/disable`, which has no chat context and so cannot use
+    // the reload_plugins action.
+    method: "POST",
+    path: "/plugins/reload",
+    handle: async ({ res, host }) => {
+      try {
+        const loaded = await host.reloadPlugins();
+        log("gateway", `/plugins/reload: ${loaded.length} plugins loaded`);
+        sendJson(res, 200, { ok: true, loaded });
+      } catch (err) {
+        sendJson(res, 200, {
+          ok: false,
+          error: `Plugin reload failed: ${err instanceof Error ? err.message : err}`,
+        });
+      }
+    },
+  },
+  {
+    // MCP hub — daemon-hosted MCP-over-HTTP endpoints for every backend
+    // (see core/mcp-hub).
+    method: "ANY",
+    path: HUB_PATH_PREFIX,
+    match: "prefix",
+    handle: ({ req, res, host }) =>
+      handleHubRequest(req, res, host.hubOrigin()),
+  },
+  {
+    method: "POST",
+    path: "/action",
+    handle: async ({ req, res, host }) => {
+      let body: Record<string, unknown>;
+      try {
+        body = (await readJsonBody(req)) as Record<string, unknown>;
+      } catch {
+        sendJson(res, 400, { ok: false, error: "Invalid JSON" });
+        return;
+      }
+      sendJson(res, 200, await host.handleAction(body));
+    },
+  },
+];
+
+function matches(route: GatewayRoute, req: IncomingMessage): boolean {
+  if (route.method !== "ANY" && req.method !== route.method) return false;
+  const url = req.url ?? "";
+  return route.match === "prefix"
+    ? url.startsWith(route.path)
+    : url === route.path;
+}
+
+/** Serve one request: first matching route wins; nothing matches → 404. */
+export async function dispatchGatewayRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  host: GatewayRouteHost,
+): Promise<void> {
+  const route = ROUTES.find((candidate) => matches(candidate, req));
+  if (!route) {
+    res.writeHead(404);
+    res.end("Not found");
+    return;
+  }
+  try {
+    await route.handle({
+      req,
+      res,
+      url: new URL(req.url ?? "/", "http://gateway"),
+      host,
+    });
+  } catch (err) {
+    if (res.headersSent) return;
+    // Log full error (incl. stack via logError's structured `stack` field)
+    // on the server; return a generic message to the client so we don't
+    // leak implementation details. CodeQL: js/stack-trace-exposure.
+    logError("gateway", `Unhandled error on ${req.method} ${req.url}`, err);
+    sendJson(res, 500, { ok: false, error: "Internal server error" });
+  }
+}
+
+const PORT_RETRIES = 5;
+
+/**
+ * Bind to 127.0.0.1, walking up from `port` on EADDRINUSE (at most
+ * `PORT_RETRIES` times). Resolves with the port actually bound — `port`
+ * 0 asks the OS for a free one — and leaves a persistent error handler
+ * on the server, so a later server-level error is logged instead of
+ * crashing the process via an unhandled 'error' event.
+ */
+export function listenWithRetry(server: Server, port: number): Promise<number> {
+  return new Promise<number>((resolve, reject) => {
+    let attempt = 0;
+    const tryPort = (candidate: number): void => {
+      server.once("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "EADDRINUSE" && attempt < PORT_RETRIES) {
+          attempt++;
+          server.removeAllListeners("error");
+          // The failed listen() left its one-shot 'listening' callback
+          // registered; drop it or every stale callback fires when a later
+          // port finally binds.
+          server.removeAllListeners("listening");
+          tryPort(candidate + 1);
+        } else {
+          reject(err);
+        }
+      });
+      server.listen(candidate, "127.0.0.1", () => {
+        const addr = server.address();
+        const bound =
+          typeof addr === "object" && addr !== null
+            ? (addr as { port: number }).port
+            : candidate;
+        server.removeAllListeners("error");
+        server.on("error", (err) =>
+          logError("gateway", "HTTP server error", err),
+        );
+        resolve(bound);
+      });
+    };
+    tryPort(port);
+  });
+}

package/src/core/engine/gateway.ts

@@ -8,11 +8,7 @@
  * No platform-specific imports — frontends register their handler at startup.
  */
 
-import {
-  createServer,
-  type IncomingMessage,
-  type ServerResponse,
-} from "node:http";
+import { createServer } from "node:http";
 import pRetry, { AbortError } from "p-retry";
 import { classify } from "../errors.js";
 import { getActiveCount } from "./dispatcher.js";
@@ -26,14 +22,13 @@ import {
   isChatFreeAction,
 } from "./gateway-actions/index.js";
 import { registerCrossSendTarget } from "./gateway-actions/cross-send.js";
+import { getHubSessionCount } from "../mcp-hub/index.js";
 import {
-  handleHubRequest,
-  getHubSessionCount,
-  HUB_PATH_PREFIX,
-} from "../mcp-hub/index.js";
+  dispatchGatewayRoute,
+  listenWithRetry,
+  type GatewayRouteHost,
+} from "./gateway-routes.js";
 import { handlePluginAction } from "../plugin/index.js";
-import { bus } from "../bus/index.js";
-import { taskTable } from "../tasks/index.js";
 import type { FrontendActionHandler } from "../types.js";
 import { BOT_MESSAGE_ACTIONS, noteBotMessage } from "../soul/taps.js";
 import type { Backend } from "../agent-runtime/capabilities.js";
@@ -362,236 +357,69 @@ export class Gateway {
 
   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({
-              // Identity fields — daemon discovery matches on these to
-              // distinguish a Talon daemon from chat sessions and
-              // unrelated localhost services.
-              app: "talon",
-              mode: this.mode,
-              pid: process.pid,
-              port: this.port,
-              startedAt: this.startedAt,
-              ok: w.healthy,
-              uptime: Math.round(process.uptime()),
-              memory: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
-              bridge: {
-                activeChats: this.loom.activeContextCount(),
-                threads: this.loom.size(),
-                hubSessions: getHubSessionCount(),
-              },
-              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 === "/shutdown") {
-          // Graceful stop for `talon stop`/`talon restart`. Bound to
-          // 127.0.0.1 like everything else here. Respond before
-          // triggering so the client isn't cut off mid-request; the
-          // shutdown path takes seconds, so the reply flushes safely.
-          if (!this.shutdownHandler) {
-            res.writeHead(501, { "Content-Type": "application/json" });
-            res.end(
-              JSON.stringify({
-                ok: false,
-                error: "Shutdown not supported by this process",
-              }),
-            );
-            return;
-          }
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true }));
-          const handler = this.shutdownHandler;
-          setImmediate(() => handler("gateway /shutdown"));
-          return;
-        }
-
-        if (req.method === "GET" && req.url?.startsWith("/events/recent")) {
-          // Bus tail — recent events, optionally after a cursor. Read by
-          // `talon events`. Same 127.0.0.1 trust boundary as /action.
-          const url = new URL(req.url, "http://gateway");
-          const since = Number(url.searchParams.get("since") ?? "0");
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(
-            JSON.stringify({
-              ok: true,
-              events: bus.recent(
-                Number.isInteger(since) && since > 0 ? since : 0,
-              ),
-            }),
-          );
-          return;
-        }
-
-        if (req.method === "GET" && req.url === "/tasks") {
-          // The task table — every live/recent unit of agent work. Read by
-          // `talon ps`. Same 127.0.0.1 trust boundary as /action.
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ ok: true, tasks: taskTable.list() }));
-          return;
-        }
-
-        if (req.method === "POST" && req.url === "/tasks/kill") {
-          // Abort one killable task by id — the transport for `talon kill`.
-          const chunks: Buffer[] = [];
-          for await (const chunk of req) chunks.push(chunk as Buffer);
-          let id: unknown;
-          try {
-            const body = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
-            id = (body as { id?: unknown }).id;
-          } catch {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ ok: false, error: "Invalid JSON" }));
-            return;
-          }
-          if (typeof id !== "number" || !Number.isInteger(id)) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(
-              JSON.stringify({ ok: false, error: "id must be an integer" }),
-            );
-            return;
-          }
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify(taskTable.kill(id)));
-          return;
-        }
-
-        if (req.method === "POST" && req.url === "/plugins/reload") {
-          // Hot-reload plugins from config — the transport for
-          // `talon plugin install/enable/disable`, which has no chat
-          // context and so cannot use the reload_plugins action. Same
-          // 127.0.0.1 trust boundary as /action.
-          try {
-            const { performPluginReload } =
-              await import("./gateway-actions/plugins.js");
-            const { names } = await performPluginReload(this.backend);
-            log("gateway", `/plugins/reload: ${names.length} plugins loaded`);
-            res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ ok: true, loaded: names }));
-          } catch (err) {
-            res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(
-              JSON.stringify({
-                ok: false,
-                error: `Plugin reload failed: ${err instanceof Error ? err.message : err}`,
-              }),
-            );
-          }
-          return;
-        }
-
-        if (req.url?.startsWith(HUB_PATH_PREFIX)) {
-          // MCP hub — daemon-hosted MCP-over-HTTP endpoints for every
-          // backend (see core/mcp-hub). Same 127.0.0.1 trust boundary
-          // as /action.
-          await handleHubRequest(req, res, `http://127.0.0.1:${this.port}`);
-          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);
-          const json = JSON.stringify(result);
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(json);
-        } catch (err) {
-          if (res.headersSent) return;
-          // Log full error (incl. stack via logError's structured `stack`
-          // field) on the server; return a generic message to the client so
-          // we don't leak implementation details.
-          // CodeQL: js/stack-trace-exposure (alert #4).
-          logError(
-            "gateway",
-            `Unhandled error on ${req.method} ${req.url}`,
-            err,
-          );
-          res.writeHead(500, { "Content-Type": "application/json" });
-          res.end(
-            JSON.stringify({ ok: false, error: "Internal server error" }),
-          );
-        }
+    const host: GatewayRouteHost = {
+      healthSnapshot: () => this.healthSnapshot(),
+      requestShutdown: () => {
+        const handler = this.shutdownHandler;
+        if (!handler) return false;
+        setImmediate(() => handler("gateway /shutdown"));
+        return true;
       },
+      reloadPlugins: async () => {
+        const { performPluginReload } =
+          await import("./gateway-actions/plugins.js");
+        return (await performPluginReload(this.backend)).names;
+      },
+      hubOrigin: () => `http://127.0.0.1:${this.port}`,
+      handleAction: (body) => this.handleAction(body),
+    };
+    const httpServer = createServer(
+      (req, res) => void dispatchGatewayRoute(req, res, host),
     );
+    const bound = await listenWithRetry(httpServer, port);
+    this.server = httpServer;
+    this.port = bound;
+    log("gateway", `Action gateway on :${this.port}`);
+    for (const cb of this.startedListeners.splice(0)) {
+      try {
+        cb(this.port);
+      } catch (err) {
+        logError("gateway", "onStarted listener failed", err);
+      }
+    }
+    return this.port;
+  }
 
-    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");
-            // The failed listen() left its one-shot 'listening' success
-            // callback registered (Node attaches it via once('listening')).
-            // Drop it before retrying — otherwise every stale callback also
-            // fires when a later port finally binds, running the startup body
-            // (and logging "Action gateway on :…") once per attempted port.
-            httpServer.removeAllListeners("listening");
-            tryPort(p + 1);
-          } else {
-            reject(err);
-          }
-        });
-        httpServer.listen(p, "127.0.0.1", () => {
-          this.server = httpServer;
-          // When the caller asks for port 0 the OS assigns a random free
-          // port — read the actual port off the listening socket instead
-          // of saving the requested 0.
-          const addr = httpServer.address();
-          this.port =
-            typeof addr === "object" && addr !== null
-              ? (addr as { port: number }).port
-              : p;
-          log("gateway", `Action gateway on :${this.port}`);
-          // Replace the one-shot startup error listener with a persistent
-          // handler. Without this, once the `once("error")` from port-binding
-          // fires (and auto-removes itself), any subsequent server-level error
-          // has no listener and crashes the process via uncaught 'error' event.
-          httpServer.removeAllListeners("error");
-          httpServer.on("error", (err) =>
-            logError("gateway", "HTTP server error", err),
-          );
-          for (const cb of this.startedListeners.splice(0)) {
-            try {
-              cb(this.port);
-            } catch (err) {
-              logError("gateway", "onStarted listener failed", err);
-            }
-          }
-          resolve(this.port);
-        });
-      };
-      tryPort(port);
-    });
+  /**
+   * The /health body. Identity fields first — daemon discovery matches on
+   * them to tell a Talon daemon from chat sessions and unrelated localhost
+   * services — then live counters.
+   */
+  private healthSnapshot(): Record<string, unknown> {
+    const w = getHealthStatus();
+    return {
+      app: "talon",
+      mode: this.mode,
+      pid: process.pid,
+      port: this.port,
+      startedAt: this.startedAt,
+      ok: w.healthy,
+      uptime: Math.round(process.uptime()),
+      memory: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+      bridge: {
+        activeChats: this.loom.activeContextCount(),
+        threads: this.loom.size(),
+        hubSessions: getHubSessionCount(),
+      },
+      queue: getActiveCount(),
+      sessions: getActiveSessionCount(),
+      messages: w.totalMessagesProcessed,
+      errors: w.recentErrorCount,
+      lastActivity:
+        w.msSinceLastMessage < 60000
+          ? "just now"
+          : `${Math.round(w.msSinceLastMessage / 60000)}m ago`,
+    };
   }
 
   async stop(): Promise<void> {