talon-agent 1.8.1 → 1.9.1

package/README.md

@@ -12,15 +12,15 @@ Multi-platform agentic AI harness powered by Claude. Runs on **Telegram**, **Tea
 
 ## Features
 
-| | |
-|---|---|
-| **Multi-frontend** | Telegram (Grammy + GramJS userbot), Microsoft Teams (Bot Framework), Terminal with live tool visibility |
-| **Claude Agent SDK** | Streaming responses, extended thinking, adaptive effort, 1M token context, dynamic model discovery |
-| **MCP tools** | Messaging, media, history, search, web fetch, cron jobs, stickers, file system, admin controls |
-| **Plugins** | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search |
-| **Background agents** | Heartbeat (periodic maintenance) and Dream (memory consolidation + diary) |
-| **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard |
-| **Model registry** | Models discovered from the SDK at startup --- new models appear in all pickers automatically |
+|                       |                                                                                                         |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Microsoft Teams (Bot Framework), Terminal with live tool visibility |
+| **Claude Agent SDK**  | Streaming responses, extended thinking, adaptive effort, 1M token context, dynamic model discovery      |
+| **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, stickers, file system, admin controls          |
+| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                     |
+| **Background agents** | Heartbeat (periodic maintenance) and Dream (memory consolidation + diary)                               |
+| **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                              |
+| **Model registry**    | Models discovered from the SDK at startup --- new models appear in all pickers automatically            |
 
 ---
 
@@ -39,8 +39,10 @@ npx talon chat        # terminal chat mode
 ```
 
 **Prerequisites:**
+
 - [Node.js 22+](https://nodejs.org/)
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI on PATH)
+- Talon runs from a normal source or package install; standalone compiled binaries are not supported.
 
 ---
 
@@ -161,9 +163,7 @@ Plugins add MCP tools and gateway actions without modifying core code. SOLID int
 
 ```json
 {
-  "plugins": [
-    { "path": "/path/to/my-plugin", "config": { "apiKey": "..." } }
-  ]
+  "plugins": [{ "path": "/path/to/my-plugin", "config": { "apiKey": "..." } }]
 }
 ```
 
@@ -172,12 +172,24 @@ export default {
   name: "my-plugin",
   version: "1.0.0",
   mcpServerPath: resolve(import.meta.dirname, "tools.ts"),
-  validateConfig(config) { /* return errors or undefined */ },
-  getEnvVars(config) { return { MY_KEY: config.apiKey }; },
-  handleAction(body, chatId) { /* gateway action handler */ },
-  getSystemPromptAddition(config) { return "## My Plugin\n..."; },
-  init(config) { /* one-time setup */ },
-  destroy() { /* cleanup */ },
+  validateConfig(config) {
+    /* return errors or undefined */
+  },
+  getEnvVars(config) {
+    return { MY_KEY: config.apiKey };
+  },
+  handleAction(body, chatId) {
+    /* gateway action handler */
+  },
+  getSystemPromptAddition(config) {
+    return "## My Plugin\n...";
+  },
+  init(config) {
+    /* one-time setup */
+  },
+  destroy() {
+    /* cleanup */
+  },
 };
 ```
 
@@ -204,25 +216,25 @@ talon doctor    Validate environment and dependencies
 
 Config file: `~/.talon/config.json`
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `frontend` | `"telegram"` | `"telegram"`, `"terminal"`, `"teams"`, or an array |
-| `backend` | `"claude"` | `"claude"` or `"opencode"` |
-| `botToken` | --- | Telegram bot token |
-| `model` | `"default"` | Default Claude model. Legacy `claude-*` aliases are still accepted. |
-| `concurrency` | `1` | Max concurrent AI queries (1--20) |
-| `pulse` | `true` | Periodic group engagement |
-| `heartbeat` | `false` | Background maintenance agent |
-| `heartbeatIntervalMinutes` | `60` | Heartbeat interval |
-| `braveApiKey` | --- | Brave Search API key |
-| `timezone` | --- | IANA timezone (e.g. `"Europe/London"`) |
-| `plugins` | `[]` | External plugin packages |
-| `adminUserId` | --- | Telegram user ID for `/admin` commands |
-| `allowedUsers` | --- | Whitelist of Telegram user IDs |
-| `apiId` / `apiHash` | --- | Telegram API credentials for full message history |
-| `github` | --- | GitHub plugin config (see above) |
-| `mempalace` | --- | MemPalace plugin config (see above) |
-| `playwright` | --- | Playwright plugin config (see above) |
+| Field                      | Default      | Description                                                         |
+| -------------------------- | ------------ | ------------------------------------------------------------------- |
+| `frontend`                 | `"telegram"` | `"telegram"`, `"terminal"`, `"teams"`, or an array                  |
+| `backend`                  | `"claude"`   | `"claude"` or `"opencode"`                                          |
+| `botToken`                 | ---          | Telegram bot token                                                  |
+| `model`                    | `"default"`  | Default Claude model. Legacy `claude-*` aliases are still accepted. |
+| `concurrency`              | `1`          | Max concurrent AI queries (1--20)                                   |
+| `pulse`                    | `true`       | Periodic group engagement                                           |
+| `heartbeat`                | `false`      | Background maintenance agent                                        |
+| `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                                  |
+| `braveApiKey`              | ---          | Brave Search API key                                                |
+| `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                              |
+| `plugins`                  | `[]`         | External plugin packages                                            |
+| `adminUserId`              | ---          | Telegram user ID for `/admin` commands                              |
+| `allowedUsers`             | ---          | Whitelist of Telegram user IDs                                      |
+| `apiId` / `apiHash`        | ---          | Telegram API credentials for full message history                   |
+| `github`                   | ---          | GitHub plugin config (see above)                                    |
+| `mempalace`                | ---          | MemPalace plugin config (see above)                                 |
+| `playwright`               | ---          | Playwright plugin config (see above)                                |
 
 ---
 
@@ -241,6 +253,7 @@ Commands: `/model`, `/effort`, `/reset`, `/status`, `/help`
 ## Production
 
 **Docker:**
+
 ```bash
 docker compose up -d
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -36,7 +36,6 @@
     "tsconfig.json"
   ],
   "scripts": {
-    "build:binary": "bun build --compile --minify src/index.ts --outfile talon-bun",
     "start": "tsx src/index.ts",
     "cli": "tsx src/cli.ts",
     "setup": "tsx src/cli.ts setup",

package/prompts/mempalace.md

@@ -53,5 +53,8 @@ You have access to a local memory palace via MCP tools. The palace stores verbat
 - The knowledge graph stores typed relationships with **time windows**. It knows WHEN things were true.
 - Use `mempalace_check_duplicate` before storing new content to avoid clutter.
 - Diary entries accumulate across sessions. Write them to build continuity of self.
+- Entity detection runs per-language; results include `created_at` timestamps you can surface when the user asks "when did I last…".
 
 ### Palace location: `{{palacePath}}`
+
+### Entity-detection languages: `{{entityLanguages}}`

package/src/__tests__/disallowed-tools.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DISALLOWED_TOOLS_BACKGROUND,
+  DISALLOWED_TOOLS_CORE,
+} from "../core/constants.js";
+import { DISALLOWED_TOOLS_CHAT } from "../backend/claude-sdk/constants.js";
+
+describe("disallowed tool lists", () => {
+  describe("DISALLOWED_TOOLS_CORE", () => {
+    it("blocks interactive/planning tools that are nonsensical in headless contexts", () => {
+      const expected = [
+        "EnterPlanMode",
+        "ExitPlanMode",
+        "EnterWorktree",
+        "ExitWorktree",
+        "TodoWrite",
+        "TodoRead",
+        "TaskCreate",
+        "TaskUpdate",
+        "TaskGet",
+        "TaskList",
+        "TaskOutput",
+        "TaskStop",
+        "AskUserQuestion",
+      ];
+      for (const tool of expected) {
+        expect(DISALLOWED_TOOLS_CORE).toContain(tool);
+      }
+    });
+
+    it("blocks ScheduleWakeup — /loop-skill-only tool that wedges the dispatcher when called outside /loop mode", () => {
+      // Confirmed root cause of a 35-minute hang on 2026-04-27.
+      // ScheduleWakeup registers a wakeup the runtime never fires, so the
+      // chat lock is held indefinitely until manual restart.
+      expect(DISALLOWED_TOOLS_CORE).toContain("ScheduleWakeup");
+    });
+  });
+
+  describe("DISALLOWED_TOOLS_BACKGROUND", () => {
+    it("inherits everything from CORE", () => {
+      for (const tool of DISALLOWED_TOOLS_CORE) {
+        expect(DISALLOWED_TOOLS_BACKGROUND).toContain(tool);
+      }
+    });
+
+    it("additionally blocks Agent (no nested agents in dream/heartbeat)", () => {
+      expect(DISALLOWED_TOOLS_BACKGROUND).toContain("Agent");
+    });
+  });
+
+  describe("DISALLOWED_TOOLS_CHAT", () => {
+    it("inherits everything from CORE", () => {
+      for (const tool of DISALLOWED_TOOLS_CORE) {
+        expect(DISALLOWED_TOOLS_CHAT).toContain(tool);
+      }
+    });
+
+    it("additionally blocks Claude's built-in web tools (replaced by Brave MCP)", () => {
+      expect(DISALLOWED_TOOLS_CHAT).toContain("WebSearch");
+      expect(DISALLOWED_TOOLS_CHAT).toContain("WebFetch");
+    });
+  });
+});

package/src/__tests__/handlers-stream.test.ts

@@ -29,11 +29,6 @@ vi.mock("../core/errors.js", () => ({
   TalonError: class TalonError extends Error {},
 }));
 
-vi.mock("../core/prompt-builder.js", () => ({
-  enrichDMPrompt: vi.fn((p: string) => p),
-  enrichGroupPrompt: vi.fn((p: string) => p),
-}));
-
 vi.mock("../storage/daily-log.js", () => ({
   appendDailyLog: vi.fn(),
   appendDailyLogResponse: vi.fn(),

package/src/__tests__/handlers.test.ts

@@ -5,10 +5,6 @@ const executeMock = vi.hoisted(() => vi.fn());
 vi.mock("../core/dispatcher.js", () => ({
   execute: executeMock,
 }));
-vi.mock("../core/prompt-builder.js", () => ({
-  enrichDMPrompt: vi.fn((p: string) => p),
-  enrichGroupPrompt: vi.fn((p: string) => p),
-}));
 vi.mock("../storage/daily-log.js", () => ({
   appendDailyLog: vi.fn(),
   appendDailyLogResponse: vi.fn(),
@@ -2641,11 +2637,8 @@ describe("handleStickerMessage — video sticker branch (L835 TRUE)", () => {
   }, 3000);
 });
 
-describe("processAndReply — group message without senderId (L552 FALSE branch)", () => {
-  it("skips enrichGroupPrompt when senderId is undefined in group", async () => {
-    const { enrichGroupPrompt } = await import("../core/prompt-builder.js");
-    (enrichGroupPrompt as ReturnType<typeof vi.fn>).mockClear();
-
+describe("processAndReply — group message without senderId", () => {
+  it("processes anonymous group messages without mutating the prompt", async () => {
     executeMock.mockResolvedValueOnce({
       text: "",
       durationMs: 10,
@@ -2672,13 +2665,14 @@ describe("processAndReply — group message without senderId (L552 FALSE branch)
     await handleTextMessage(ctx, mockBot, mockConfig);
     await new Promise((r) => setTimeout(r, 700));
 
-    // enrichGroupPrompt should NOT have been called (senderId falsy)
-    expect(enrichGroupPrompt).not.toHaveBeenCalled();
-    // But message was still processed
+    // Message was still processed, and the prompt is passed through verbatim.
     const calls = executeMock.mock.calls
       .slice(before)
       .filter((c) => (c[0] as { chatId: string }).chatId === String(chatId));
     expect(calls.length).toBe(1);
+    expect((calls[0][0] as { prompt: string }).prompt).toBe(
+      "@testbot anonymous message",
+    );
   }, 3000);
 });
 

package/src/__tests__/mcp-launcher-functional.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Functional tests for the MCP launcher supervisor.
+ *
+ * Each test targets a distinct failure mode that would produce an orphaned
+ * MCP subprocess in production. All spawn real Node subprocesses and tear
+ * them down in afterEach — no mocks, no shortcuts. If these pass on Linux
+ * and macOS, the "launcher-wrapped spawns never orphan" claim holds.
+ *
+ * Cases kept:
+ *   1. SIGKILL of parent at scale (headline bug from PR #67).
+ *   2. Graceful stdin-close shutdown (normal Talon exit).
+ *   3. Stubborn child that ignores SIGTERM (validates SIGKILL fallback).
+ *   4. Supervised child exits on its own (launcher doesn't hang).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawn, type ChildProcess } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const LAUNCHER_MODULE = pathToFileURL(
+  resolve(REPO_ROOT, "src/util/mcp-launcher.ts"),
+).href;
+const TSX_IMPORT = pathToFileURL(
+  resolve(REPO_ROOT, "node_modules/tsx/dist/esm/index.mjs"),
+).href;
+const FUNCTIONAL_TIMEOUT_MS = 30_000;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return false;
+    // EPERM: exists but unreachable. Count as alive.
+    return true;
+  }
+}
+
+async function waitForPidGone(
+  pid: number,
+  timeoutMs: number,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!pidAlive(pid)) return true;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return !pidAlive(pid);
+}
+
+async function assertAllGone(pids: number[], timeoutMs: number): Promise<void> {
+  const stuck: number[] = [];
+  for (const pid of pids) {
+    if (!(await waitForPidGone(pid, timeoutMs))) stuck.push(pid);
+  }
+  if (stuck.length > 0) {
+    // Clean up the leak so it doesn't poison sibling tests.
+    for (const pid of stuck) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        /* ok */
+      }
+    }
+    throw new Error(`orphaned pids after teardown: ${stuck.join(", ")}`);
+  }
+}
+
+/** Read the first stdout line matching `match`, with a timeout. */
+async function readMarker(
+  child: ChildProcess,
+  match: RegExp,
+  timeoutMs: number,
+  label: string,
+): Promise<RegExpMatchArray> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`timeout waiting for ${label}`)),
+      timeoutMs,
+    );
+    let buf = "";
+    const onData = (d: Buffer) => {
+      buf += d.toString();
+      const m = buf.match(match);
+      if (m) {
+        clearTimeout(timer);
+        child.stdout!.off("data", onData);
+        resolve(m);
+      }
+    };
+    child.stdout!.on("data", onData);
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      reject(new Error(`process exited before ${label} (code=${code})`));
+    });
+  });
+}
+
+type IdlerOpts = {
+  name?: string;
+  /** If false, the idler keeps running even after its stdin closes. */
+  exitOnStdinClose?: boolean;
+  /** If true, the idler ignores SIGTERM (forces SIGKILL cleanup path). */
+  ignoreSigterm?: boolean;
+  /** If set, the idler exits on its own this many ms after starting. */
+  selfExitAfterMs?: number;
+};
+
+function writeIdler(dir: string, opts: IdlerOpts = {}): string {
+  const path = join(dir, opts.name ?? "idler.mjs");
+  const exitOnStdin = opts.exitOnStdinClose !== false;
+  const ignoreTerm = opts.ignoreSigterm === true;
+  const selfExit = opts.selfExitAfterMs;
+  writeFileSync(
+    path,
+    `
+    process.stderr.write("IDLER_PID=" + process.pid + "\\n");
+    ${exitOnStdin ? 'process.stdin.on("end", () => process.exit(0));' : ""}
+    process.on("SIGTERM", () => { ${
+      ignoreTerm ? "/* stubborn: ignore */" : "process.exit(0);"
+    } });
+    process.on("SIGINT", () => process.exit(0));
+    process.stdin.resume();
+    ${selfExit !== undefined ? `setTimeout(() => process.exit(0), ${selfExit});` : ""}
+    setInterval(() => {}, 1 << 30);
+    `,
+  );
+  return path;
+}
+
+type HarnessResult = { harness: ChildProcess; pids: number[] };
+
+/**
+ * Spawn a harness that uses the real `wrapMcpServer()` to supervise
+ * `count` idlers. Resolves once every idler has reported its PID, returning
+ * [launcher PIDs..., idler PIDs...] (length = count * 2).
+ */
+async function spawnHarness(opts: {
+  workDir: string;
+  count: number;
+  idlerPath: string;
+}): Promise<HarnessResult> {
+  const { workDir, count, idlerPath } = opts;
+  const harnessPath = join(workDir, "harness.mjs");
+  writeFileSync(
+    harnessPath,
+    `
+    import { spawn } from "node:child_process";
+    import { wrapMcpServer } from ${JSON.stringify(LAUNCHER_MODULE)};
+
+    const launchers = [];
+    const idlers = [];
+    const TARGET = ${count};
+
+    for (let i = 0; i < TARGET; i++) {
+      const cfg = wrapMcpServer({
+        command: "node",
+        args: [${JSON.stringify(idlerPath)}],
+        env: {},
+      });
+      const c = spawn(cfg.command, cfg.args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, ...cfg.env },
+      });
+      launchers.push(c);
+
+      let buf = "";
+      c.stderr.on("data", (d) => {
+        buf += d.toString();
+        const m = buf.match(/IDLER_PID=(\\d+)/);
+        if (m) {
+          idlers.push(parseInt(m[1], 10));
+          buf = buf.replace(/IDLER_PID=\\d+\\n?/, "");
+          if (idlers.length === TARGET) {
+            process.stdout.write(
+              "PIDS=" + launchers.map((c) => c.pid).concat(idlers).join(",") + "\\n",
+            );
+          }
+        }
+      });
+    }
+
+    process.stdin.on("end", () => process.exit(0));
+    process.stdin.resume();
+    `,
+  );
+
+  const harness = spawn("node", ["--import", TSX_IMPORT, harnessPath], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, HOME: workDir },
+  });
+  const marker = await readMarker(
+    harness,
+    /PIDS=([\d,]+)/,
+    15_000,
+    "harness PID marker",
+  );
+  const pids = marker[1].split(",").map((s) => parseInt(s, 10));
+  if (pids.length !== count * 2) {
+    throw new Error(
+      `harness reported ${pids.length} pids, expected ${count * 2}`,
+    );
+  }
+  return { harness, pids };
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe("launcher functional: no orphaned MCP processes", () => {
+  let workDir: string;
+  const cleanup: Array<() => void> = [];
+
+  beforeEach(() => {
+    workDir = mkdtempSync(join(tmpdir(), "talon-launcher-fn-"));
+    process.env.HOME = workDir; // paths.ts reads homedir() → this
+  });
+
+  afterEach(() => {
+    for (const fn of cleanup.splice(0)) {
+      try {
+        fn();
+      } catch {
+        /* ok */
+      }
+    }
+    try {
+      rmSync(workDir, { recursive: true, force: true });
+    } catch {
+      /* ok */
+    }
+  });
+
+  function track(child: ChildProcess): void {
+    cleanup.push(() => {
+      if (!child.killed) {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          /* ok */
+        }
+      }
+    });
+  }
+
+  it(
+    "SIGKILL of parent cleans up every descendant (10 wrapped children)",
+    async () => {
+      const idler = writeIdler(workDir);
+      const { harness, pids } = await spawnHarness({
+        workDir,
+        count: 10,
+        idlerPath: idler,
+      });
+      track(harness);
+      expect(pids).toHaveLength(20); // 10 launchers + 10 idlers
+
+      harness.kill("SIGKILL");
+      await assertAllGone(pids, 5_000);
+    },
+    FUNCTIONAL_TIMEOUT_MS,
+  );
+
+  it(
+    "graceful shutdown (stdin close) cleans up every descendant",
+    async () => {
+      const idler = writeIdler(workDir);
+      const { harness, pids } = await spawnHarness({
+        workDir,
+        count: 3,
+        idlerPath: idler,
+      });
+      track(harness);
+
+      harness.stdin!.end();
+      const exitCode = await new Promise<number | null>((r) =>
+        harness.on("exit", (c) => r(c)),
+      );
+      expect(exitCode).toBe(0);
+      await assertAllGone(pids, 5_000);
+    },
+    FUNCTIONAL_TIMEOUT_MS,
+  );
+
+  it(
+    "SIGKILLs stubborn children that ignore SIGTERM",
+    async () => {
+      const stubborn = writeIdler(workDir, {
+        name: "stubborn.mjs",
+        ignoreSigterm: true,
+        exitOnStdinClose: false,
+      });
+      const { harness, pids } = await spawnHarness({
+        workDir,
+        count: 2,
+        idlerPath: stubborn,
+      });
+      track(harness);
+
+      harness.kill("SIGKILL");
+      // Launcher: SIGTERM → 1s grace → SIGKILL. Give 4s headroom.
+      await assertAllGone(pids, 4_000);
+    },
+    FUNCTIONAL_TIMEOUT_MS,
+  );
+
+  it(
+    "launcher exits when its supervised child exits on its own",
+    async () => {
+      const oneShot = writeIdler(workDir, {
+        name: "one-shot.mjs",
+        selfExitAfterMs: 200,
+      });
+      const { harness, pids } = await spawnHarness({
+        workDir,
+        count: 1,
+        idlerPath: oneShot,
+      });
+      track(harness);
+
+      // Both launcher (pids[0]) and idler (pids[1]) must be gone within seconds
+      // even though the harness itself is still running.
+      await assertAllGone(pids, 5_000);
+      expect(pidAlive(harness.pid!)).toBe(true);
+    },
+    FUNCTIONAL_TIMEOUT_MS,
+  );
+});