talon-agent 5.24.0 → 5.25.0

package/src/core/mcp-hub/child-guard.ts

@@ -0,0 +1,215 @@
+/**
+ * MCP child guard — orphan protection for hub children without a
+ * supervisor process per child.
+ *
+ * The hub used to spawn every MCP child through its own `_mcp-launch`
+ * supervisor (a full Talon runtime re-invocation, ~20 MB private memory
+ * each). With one child per plugin per chat that was dozens of idle
+ * supervisors whose only jobs were stdout filtering and killing the child
+ * if Talon died. The hub now does the filtering in-process
+ * (child-transport.ts) and spawns children directly; the kill-on-death
+ * guarantee moves to ONE reaper process per daemon:
+ *
+ *   daemon ──stdin pipe──▶ reaper (`_mcp-reaper`)
+ *     "+<pid>\n"  a child was spawned — kill it if the daemon dies
+ *     "-<pid>\n"  that child exited (or was closed) — forget it
+ *
+ * When the reaper's stdin closes — the daemon exited, INCLUDING SIGKILL,
+ * because the kernel closes the pipe — or the bridge watchdog trips, it
+ * SIGTERMs every registered pid, SIGKILLs survivors after a grace period,
+ * and exits. Same shutdown signals, same SIGTERM→SIGKILL escalation and
+ * same tolerant BridgeWatchdog as the per-child supervisor (launcher.ts);
+ * pipe EOF and `process.kill` behave identically on Linux, macOS and
+ * Windows, so no platform-specific mechanism is involved. The reaper is
+ * launched through `selfInvocation`, the same re-invocation path the
+ * supervisor uses, so it works for tsx/node and bun source runs,
+ * bun-compiled binaries and npm installs alike.
+ *
+ * Fallback: if the reaper cannot be started, or keeps dying right after
+ * start, the guard switches to "supervisor" mode and new children are
+ * wrapped in the per-child supervisor exactly as before.
+ * `TALON_MCP_SUPERVISOR=per-child` forces that mode.
+ *
+ * The guard is off until the daemon enables it (initHub). Embedders and
+ * unit tests that drive the hub directly spawn children unguarded rather
+ * than re-invoking an entrypoint that does not dispatch `_mcp-reaper`.
+ */
+
+import crossSpawn from "cross-spawn";
+import type { ChildProcess } from "node:child_process";
+import { logWarn } from "../../util/log.js";
+import { selfInvocation, wrapMcpServer } from "./launcher.js";
+import { MCP_REAPER_SUBCOMMAND } from "./reaper.js";
+
+/** Opt-out env var: `per-child` restores one supervisor per MCP child. */
+const SUPERVISOR_MODE_ENV = "TALON_MCP_SUPERVISOR";
+
+// ── Daemon side ─────────────────────────────────────────────────────────────
+
+/**
+ * - off: children spawn unguarded (guard never enabled — tests, embedders).
+ * - reaper: children spawn directly and are registered with the reaper.
+ * - supervisor: children are wrapped in the per-child supervisor.
+ */
+export type ChildGuardMode = "off" | "reaper" | "supervisor";
+
+let mode: ChildGuardMode = "off";
+let reaper: ChildProcess | null = null;
+let reaperStartedAt = 0;
+let reaperBridgeUrl: string | undefined;
+let stopping = false;
+/** Consecutive reapers that died within REAPER_EARLY_DEATH_MS of start. */
+let earlyDeaths = 0;
+/** Children currently registered — replayed into a respawned reaper. */
+const guarded = new Set<number>();
+
+const REAPER_EARLY_DEATH_MS = 5_000;
+const REAPER_EARLY_DEATHS_BEFORE_FALLBACK = 3;
+
+/** Turn the guard on (daemon bootstrap). Idempotent. */
+export function enableChildGuard(): void {
+  stopping = false;
+  if (mode !== "off") return;
+  mode =
+    process.env[SUPERVISOR_MODE_ENV] === "per-child" ? "supervisor" : "reaper";
+}
+
+export function childGuardMode(): ChildGuardMode {
+  return mode;
+}
+
+function fallBackToSupervisor(reason: string): void {
+  if (mode !== "reaper") return;
+  mode = "supervisor";
+  logWarn(
+    "gateway",
+    `mcp reaper unavailable (${reason}); new MCP children fall back to one supervisor each`,
+  );
+}
+
+function writeLine(line: string): void {
+  const stdin = reaper?.stdin;
+  if (!stdin || stdin.destroyed) return;
+  try {
+    stdin.write(`${line}\n`);
+  } catch {
+    /* reaper gone — its exit handler respawns and replays */
+  }
+}
+
+function onReaperExit(proc: ChildProcess): void {
+  if (reaper !== proc) return;
+  reaper = null;
+  if (stopping || mode !== "reaper") return;
+  const early = Date.now() - reaperStartedAt < REAPER_EARLY_DEATH_MS;
+  earlyDeaths = early ? earlyDeaths + 1 : 0;
+  if (earlyDeaths >= REAPER_EARLY_DEATHS_BEFORE_FALLBACK) {
+    fallBackToSupervisor(`exited ${earlyDeaths} times right after start`);
+    return;
+  }
+  logWarn(
+    "gateway",
+    `mcp reaper exited (code=${proc.exitCode} signal=${proc.signalCode}); restarting`,
+  );
+  // Live children must not go unguarded until the next spawn.
+  if (guarded.size > 0) ensureReaper();
+}
+
+function ensureReaper(): void {
+  if (reaper || mode !== "reaper") return;
+  let proc: ChildProcess;
+  try {
+    const inv = selfInvocation(MCP_REAPER_SUBCOMMAND);
+    const env: Record<string, string | undefined> = { ...process.env };
+    if (reaperBridgeUrl) env.TALON_BRIDGE_URL = reaperBridgeUrl;
+    else delete env.TALON_BRIDGE_URL;
+    proc = crossSpawn(inv.command, inv.args, {
+      stdio: ["pipe", "ignore", "pipe"],
+      env,
+      windowsHide: true,
+    });
+  } catch (err) {
+    fallBackToSupervisor(err instanceof Error ? err.message : String(err));
+    return;
+  }
+  reaper = proc;
+  reaperStartedAt = Date.now();
+  proc.stdin?.on("error", () => {});
+  proc.stderr?.setEncoding("utf-8");
+  proc.stderr?.on("data", (chunk: string) => {
+    const text = chunk.trim();
+    if (text) logWarn("gateway", `mcp reaper: ${text}`);
+  });
+  proc.once("error", (err) => {
+    // Spawn failure (ENOENT/EACCES): no reaper can ever start this way.
+    fallBackToSupervisor(err.message);
+    onReaperExit(proc);
+  });
+  proc.once("exit", () => onReaperExit(proc));
+  // Don't keep the daemon's event loop alive just for the reaper.
+  proc.unref();
+  (proc.stdin as { unref?: () => void } | null)?.unref?.();
+  (proc.stderr as { unref?: () => void } | null)?.unref?.();
+  for (const pid of guarded) writeLine(`+${pid}`);
+}
+
+/**
+ * The spawn spec to actually run for `spec`: unchanged when the reaper
+ * guards children (or the guard is off), supervisor-wrapped in
+ * supervisor mode.
+ */
+export function guardedSpec<
+  T extends { command: string; args: string[]; env?: Record<string, string> },
+>(spec: T): T {
+  return mode === "supervisor" ? wrapMcpServer(spec) : spec;
+}
+
+/**
+ * Register a freshly spawned child with the reaper. `bridgeUrl` arms the
+ * reaper's bridge watchdog (first one seen wins; it is the daemon's own
+ * gateway, identical for every child).
+ */
+export function guardChild(pid: number, bridgeUrl?: string): void {
+  if (mode !== "reaper") return;
+  reaperBridgeUrl ??= bridgeUrl;
+  guarded.add(pid);
+  if (reaper) writeLine(`+${pid}`);
+  else ensureReaper(); // replays `guarded`, including this pid
+}
+
+/** Forget a child that has exited or been closed. */
+export function releaseChild(pid: number): void {
+  if (!guarded.delete(pid)) return;
+  writeLine(`-${pid}`);
+}
+
+/**
+ * Daemon shutdown, after the hub closed its children: close the reaper's
+ * stdin so it reaps anything still registered and exits.
+ */
+export function stopChildGuard(): void {
+  stopping = true;
+  const proc = reaper;
+  reaper = null;
+  proc?.stdin?.end();
+}
+
+/** Test-only: reset module state. */
+export function _resetChildGuardForTesting(): void {
+  stopChildGuard();
+  guarded.clear();
+  mode = "off";
+  earlyDeaths = 0;
+  reaperBridgeUrl = undefined;
+  stopping = false;
+}
+
+/**
+ * Diagnostic: pid of the live reaper, if any.
+ *
+ * @public — read by the reaper functional test's harness (a separate
+ * process knip can't see), not by Talon's own graph.
+ */
+export function reaperPid(): number | null {
+  return reaper?.pid ?? null;
+}

package/src/core/mcp-hub/child-transport.ts

@@ -11,21 +11,28 @@
  *
  * This transport owns the spawn so the hub can record the cause: exit
  * code + signal, and the last few stderr lines in a bounded ring
- * buffer. Wire behaviour matches the SDK transport exactly —
- * newline-delimited JSON-RPC over stdin/stdout; `close()` ends stdin,
- * then escalates SIGTERM → SIGKILL. Children still run under the
- * supervisor wrap (the spec's command IS the supervisor), so orphan
- * cleanup and stdout filtering are untouched.
+ * buffer. Wire behaviour matches the SDK transport —
+ * newline-delimited JSON-RPC over stdin/stdout; `close()` ends stdin and
+ * sends SIGTERM, then SIGKILL after a grace period.
+ *
+ * It also applies the MCP stdout filter in-process (the rule the
+ * per-child supervisor used to apply, shared via parseJsonRpcLine):
+ * only lines that are JSON objects reach the MCP client; banners and log
+ * lines some servers print on stdout are re-routed into the stderr tail,
+ * tagged, instead of surfacing as protocol parse errors. Orphan cleanup
+ * is the child guard's job (child-guard.ts), fed by onSpawned/onExited.
  */
 
 import crossSpawn from "cross-spawn";
 import type { ChildProcess } from "node:child_process";
-import {
-  ReadBuffer,
-  serializeMessage,
-} from "@modelcontextprotocol/sdk/shared/stdio.js";
+import { StringDecoder } from "node:string_decoder";
+import { serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import {
+  JSONRPCMessageSchema,
+  type JSONRPCMessage,
+} from "@modelcontextprotocol/sdk/types.js";
+import { parseJsonRpcLine, STDOUT_REROUTE_TAG } from "./launcher.js";
 
 /** How many trailing stderr lines a child keeps for its exit report. */
 export const STDERR_TAIL_LINES = 20;
@@ -78,8 +85,51 @@ export type HubChildTransportOptions = {
   command: string;
   args: string[];
   env: Record<string, string>;
+  /** Called with the pid once the process has spawned (orphan guard). */
+  onSpawned?: (pid: number) => void;
+  /** Called with the pid once the process has exited (orphan guard). */
+  onExited?: (pid: number) => void;
 };
 
+/**
+ * Splits child stdout into lines and applies the MCP stdout filter:
+ * JSON-object lines go to `onLine` (already parsed, so each line is
+ * parsed once), everything else non-blank to `onReject`. A trailing
+ * fragment without a newline is held until more data arrives or
+ * `flush()` runs at end of stream.
+ */
+export class StdoutLineFilter {
+  private buf = "";
+  private readonly decoder = new StringDecoder("utf8");
+
+  constructor(
+    private readonly onLine: (parsed: object) => void,
+    private readonly onReject: (line: string) => void,
+  ) {}
+
+  push(chunk: Buffer | string): void {
+    this.buf += typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+    let nl;
+    while ((nl = this.buf.indexOf("\n")) !== -1) {
+      const line = this.buf.slice(0, nl);
+      this.buf = this.buf.slice(nl + 1);
+      this.emit(line);
+    }
+  }
+
+  flush(): void {
+    const rest = this.buf + this.decoder.end();
+    this.buf = "";
+    if (rest.length > 0) this.emit(rest);
+  }
+
+  private emit(line: string): void {
+    const parsed = parseJsonRpcLine(line);
+    if (parsed !== null) this.onLine(parsed);
+    else if (line.trim().length > 0) this.onReject(line.replace(/\r$/, ""));
+  }
+}
+
 const CLOSE_GRACE_MS = 2_000;
 
 function delay(ms: number): Promise<void> {
@@ -94,8 +144,12 @@ export class HubChildTransport implements Transport {
   private child: ChildProcess | null = null;
   /** Kept past exit so the exit report can name the process. */
   private spawnedPid: number | null = null;
-  private readonly readBuffer = new ReadBuffer();
   private readonly stderrTail = new StderrTail();
+  private readonly stdoutFilter = new StdoutLineFilter(
+    (parsed) => this.deliver(parsed),
+    // Not protocol: keep it visible where a failure report will look.
+    (line) => this.stderrTail.push(`${STDOUT_REROUTE_TAG}${line}\n`),
+  );
   private exitInfo: ChildExit | null = null;
   private closeRequested = false;
 
@@ -133,11 +187,18 @@ export class HubChildTransport implements Transport {
       });
       this.child = child;
       this.spawnedPid = child.pid ?? null;
+      const pid = child.pid;
+      if (pid !== undefined) this.opts.onSpawned?.(pid);
       child.once("spawn", () => resolve());
       child.on("error", (err) => {
         reject(err);
         this.onerror?.(err);
       });
+      // The guard forgets the pid as soon as the process is gone, so a
+      // recycled pid is never reaped on the daemon's behalf.
+      if (pid !== undefined) {
+        child.once("exit", () => this.opts.onExited?.(pid));
+      }
       // `close` (not `exit`) so the stderr tail is complete when the
       // exit report is read.
       child.on("close", (code, signal) => {
@@ -147,35 +208,24 @@ export class HubChildTransport implements Transport {
       });
       child.stdin?.on("error", (err) => this.onerror?.(err));
       child.stdout?.on("error", (err) => this.onerror?.(err));
-      child.stdout?.on("data", (chunk: Buffer) => {
-        try {
-          this.readBuffer.append(chunk);
-          this.drainMessages();
-        } catch (err) {
-          this.onerror?.(err as Error);
-          void this.close();
-        }
-      });
+      child.stdout?.on("data", (chunk: Buffer) =>
+        this.stdoutFilter.push(chunk),
+      );
+      child.stdout?.on("end", () => this.stdoutFilter.flush());
       child.stderr?.setEncoding("utf-8");
       child.stderr?.on("data", (chunk: string) => this.stderrTail.push(chunk));
       child.stderr?.on("error", () => {});
     });
   }
 
-  private drainMessages(): void {
-    for (;;) {
-      let message: JSONRPCMessage | null;
-      try {
-        // readMessage consumes the line before parsing, so a malformed
-        // line is skipped rather than re-read forever.
-        message = this.readBuffer.readMessage();
-      } catch (err) {
-        this.onerror?.(err as Error);
-        continue;
-      }
-      if (message === null) return;
-      this.onmessage?.(message);
-    }
+  /** Validate one parsed stdout line as JSON-RPC and hand it on. */
+  private deliver(parsed: object): void {
+    const result = JSONRPCMessageSchema.safeParse(parsed);
+    if (result.success) this.onmessage?.(result.data);
+    else
+      this.onerror?.(
+        new Error(`Invalid JSON-RPC message: ${result.error.message}`),
+      );
   }
 
   async close(): Promise<void> {
@@ -187,15 +237,15 @@ export class HubChildTransport implements Transport {
         child.once("close", () => resolve());
       });
       const alive = () => child.exitCode === null && child.signalCode === null;
+      // EOF and SIGTERM together, SIGKILL after the grace — what the
+      // per-child supervisor did when its stdin closed, so a child sees
+      // the same shutdown whether or not a supervisor sits in between
+      // (with one, it escalates within its own 1s, inside our grace).
       child.stdin?.end();
+      if (alive()) child.kill("SIGTERM");
       await Promise.race([closed, delay(CLOSE_GRACE_MS)]);
-      if (alive()) {
-        child.kill("SIGTERM");
-        await Promise.race([closed, delay(CLOSE_GRACE_MS)]);
-      }
       if (alive()) child.kill("SIGKILL");
     }
-    this.readBuffer.clear();
   }
 
   send(message: JSONRPCMessage): Promise<void> {

package/src/core/mcp-hub/children.ts

@@ -11,11 +11,20 @@
  * use a shared key. Either way the spec factory decides — this module
  * only manages lifecycles.
  *
- * Each child is spawned through the supervisor wrap (stdout JSON
- * filtering + orphan cleanup if the daemon is SIGKILLed),
- * connected once over stdio, and shared by every hub session that
- * proxies to it. The tools list is cached per child lifetime — plugin
- * reload restarts children, which naturally invalidates the cache.
+ * Each child is spawned directly by the daemon — stdout JSON filtering
+ * happens in-process (child-transport.ts) and orphan cleanup if the
+ * daemon is SIGKILLed is the child guard's job (one reaper per daemon,
+ * child-guard.ts; per-child supervisor wrap as the fallback) — then
+ * connected once over stdio and shared by every hub session that
+ * proxies to it.
+ *
+ * Tool lists are cached per SERVER, not just per child: a chat-scoped
+ * plugin serves the same tools to every chat, so a new session's
+ * tools/list is answered from the cache and the chat's own child is only
+ * spawned when a tool is actually called. Without this every session —
+ * each chat, sub-agent and isolated cron/heartbeat run — spawned the
+ * whole plugin fleet just to enumerate tools at session start. Plugin
+ * reload restarts children and clears the cache.
  *
  * Every exit is accounted for: the child's exit code, signal and
  * stderr tail are logged when it goes away unasked (handshake death,
@@ -29,11 +38,14 @@ import { log, logError, logWarn } from "../../util/log.js";
 import { HubChildTransport, type ChildExit } from "./child-transport.js";
 import { raiseAlert, resolveAlert } from "../frontend-runtime/alerts.js";
 import { faultText } from "../engine/fault-text.js";
+import { guardChild, guardedSpec, releaseChild } from "./child-guard.js";
 
 export type ChildSpec = {
   command: string;
   args: string[];
   env?: Record<string, string>;
+  /** The daemon gateway's base URL — arms the reaper's bridge watchdog. */
+  bridgeUrl?: string;
 };
 
 export type ChildHandle = {
@@ -69,6 +81,11 @@ type ChildEntry = {
 const children = new Map<string, ChildEntry>();
 const inflight = new Map<string, Promise<ChildHandle>>();
 
+/** Server name → its tools, as last listed by any of its children. */
+const toolListCache = new Map<string, Tool[]>();
+/** Bumped on reload/shutdown so an old child can't refill the cache. */
+let toolListGeneration = 0;
+
 /**
  * Most recent exit per key, whether the child died during the
  * handshake (never registered) or later. Consulted by the backends'
@@ -216,12 +233,16 @@ const CHILD_CALL_TIMEOUT_MS = 65 * 60_000;
 let reaper: ReturnType<typeof setInterval> | null = null;
 
 async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
+  const run = guardedSpec(spec);
+  const generation = toolListGeneration;
   const transport = new HubChildTransport({
-    command: spec.command,
-    args: spec.args,
+    command: run.command,
+    args: run.args,
     // Merge over the daemon env — same visibility the SDK-spawned
     // subprocesses had (PATH, HOME, proxy vars, …).
-    env: { ...(process.env as Record<string, string>), ...spec.env },
+    env: { ...(process.env as Record<string, string>), ...run.env },
+    onSpawned: (pid) => guardChild(pid, spec.bridgeUrl),
+    onExited: releaseChild,
   });
   transport.onclose = () => onChildClosed(key, transport);
   const client = new Client(
@@ -269,6 +290,9 @@ async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
           if (toolsCache) return toolsCache;
           const result = await client.listTools();
           toolsCache = result.tools;
+          if (generation === toolListGeneration) {
+            toolListCache.set(serverOf(key), result.tools);
+          }
           return toolsCache;
         }),
       callTool: (name, args, signal) =>
@@ -308,7 +332,7 @@ export function acquireChild(
   if (pending) return pending;
 
   const failure = spawnFailures.get(key);
-  if (failure && Date.now() - failure.at < failureBackoffMs(failure.count)) {
+  if (failure && inSpawnBackoff(key)) {
     return Promise.reject(
       failure.error instanceof Error
         ? failure.error
@@ -340,10 +364,39 @@ export function acquireChild(
   return promise;
 }
 
+/**
+ * tools/list for `key` without spawning when avoidable: served from the
+ * per-server cache once any child of that server has listed its tools
+ * (see header). Falls through to the chat's own child when nothing is
+ * cached yet, or when this key is inside its spawn-failure backoff —
+ * a server that cannot start keeps failing its listing, as before,
+ * rather than advertising tools every call to which would fail.
+ */
+export async function listChildTools(
+  key: string,
+  spec: () => ChildSpec,
+): Promise<Tool[]> {
+  const live = children.get(key);
+  const cached = toolListCache.get(serverOf(key));
+  if (!live && cached && !inSpawnBackoff(key)) return cached;
+  const child = await acquireChild(key, spec);
+  return child.listTools();
+}
+
+function inSpawnBackoff(key: string): boolean {
+  const failure = spawnFailures.get(key);
+  return (
+    failure !== undefined &&
+    Date.now() - failure.at < failureBackoffMs(failure.count)
+  );
+}
+
 /** Close every child immediately. Daemon shutdown path. */
 export async function closeAllChildren(): Promise<void> {
   const entries = [...children.values()];
   children.clear();
+  toolListCache.clear();
+  toolListGeneration++;
   await Promise.allSettled(entries.map((entry) => entry.close()));
   if (entries.length > 0) {
     log("gateway", `hub: closed ${entries.length} MCP child(ren)`);
@@ -366,6 +419,9 @@ const RETIRE_GRACE_MS = 60_000;
 export function retireAllChildren(): void {
   const entries = [...children.values()];
   children.clear();
+  // Reloaded plugin code may expose different tools.
+  toolListCache.clear();
+  toolListGeneration++;
   for (const entry of entries) {
     entry.retired = true;
     if (entry.pending === 0) {

package/src/core/mcp-hub/guest-scope.ts

@@ -82,12 +82,13 @@ export const GUEST_TOOL_ALLOWLIST: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Tools whose output is a live credential (an install command embedding
- * the bridge bearer token). Operator-only, and their output is delivered
+ * Tools whose output is a live credential (an install command or pairing
+ * link embedding a bridge bearer token). Operator-only, and their output is delivered
  * to the operator's private chat, never into a shared one.
  */
 export const OPERATOR_PRIVATE_OUTPUT_TOOLS: ReadonlySet<string> = new Set([
   "make_node_install_link",
+  "make_companion_pair_link",
 ]);
 
 /** Parameters that name another chat. A guest may only name its own. */