talon-agent 3.28.1 → 3.29.0

package/README.md

@@ -297,6 +297,8 @@ GitHub API access via the official GitHub MCP server. Gives the agent access to
 
 The token is optional --- defaults to the output of `gh auth token` if the GitHub CLI is authenticated.
 
+The server image is pinned to a known-good tag and pulled in the background at boot when absent (docker still pulls on first use as the fallback). Override with `"imageTag"` (`"latest"` opts out of pinning); `"autoProvision": false` disables the pre-pull.
+
 ### Long-term Memory
 
 Talon supports two long-term memory backends, selected via the unified `memory` section:
@@ -316,14 +318,9 @@ Set `"backend"` to `"mempalace"` (local, vector search + knowledge graph) or `"m
 
 Structured long-term memory with vector search. The agent can store, search, and retrieve memories semantically. Integrates with Dream mode for automatic memory consolidation and personal diary entries.
 
-**Requirements:** Python 3.10+ with the `mempalace` package.
+**Requirements:** Python 3.10+ on PATH. Nothing else — Talon provisions its own environment.
 
-```bash
-# Set up a Python environment
-python -m venv ~/.talon/mempalace-venv
-~/.talon/mempalace-venv/bin/pip install mempalace    # Unix
-# or: ~/.talon/mempalace-venv/Scripts/pip install mempalace   # Windows
-```
+On first boot Talon creates a venv at `~/.talon/mempalace-venv` and installs the pinned `mempalace` version into it. From then on the venv is **self-maintaining**: version drift against the pin reconciles automatically in the background, a broken install (half-written site-packages, a gutted venv) self-heals at the next start, and one-time palace data migrations (e.g. the ≥3.4 wing-name normalization) are applied exactly once, safely and idempotently. Failed upgrades never take the working install down — the current version keeps serving and the retry backs off.
 
 ```json
 {
@@ -332,13 +329,17 @@ python -m venv ~/.talon/mempalace-venv
     "backend": "mempalace",
     "mempalace": {
       "palacePath": "~/.talon/workspace/palace",
-      "pythonPath": "~/.talon/mempalace-venv/bin/python"
+      "version": "3.8.0",
+      "autoUpdate": true,
+      "autoProvision": true
     }
   }
 }
 ```
 
-Both paths are optional --- defaults to `~/.talon/workspace/palace/` and the venv Python respectively.
+Everything is optional --- `palacePath` defaults to `~/.talon/workspace/palace/`, `version` defaults to the built-in pin, and both `auto*` flags default to `true`. Leave `pythonPath` unset to use the managed venv --- its interpreter is `~/.talon/mempalace-venv/bin/python` on Linux/macOS and `~/.talon/mempalace-venv/Scripts/python.exe` on Windows; any other value is treated as operator-managed (see below). `autoProvision` governs creating and healing the venv; `autoUpdate` governs reconciling a working venv to the pin --- they are independent.
+
+**Bring your own environment:** point `pythonPath` at any interpreter — a `uv tool` install, pipx, conda, or your own venv — and Talon treats it as operator-managed: it is probed and reported on (`talon doctor` shows the exact upgrade command for your install flavor) but never mutated.
 
 #### mem0 backend
 
@@ -379,6 +380,8 @@ Headless browser automation via the Playwright MCP server. The agent can browse
 
 Supported browsers: `chromium` (default), `chrome`, `firefox`, `webkit`, `msedge`.
 
+For Playwright-managed engines (`chromium`, `firefox`, `webkit`) the browser build is downloaded automatically at boot when missing — version-matched to the bundled `@playwright/mcp`. System channels (`chrome`, `msedge`) and endpoint mode are never touched. `"autoProvision": false` disables the download.
+
 ### Brave Search
 
 Web search via the Brave Search MCP server. Replaces the built-in WebSearch/WebFetch tools with higher-quality search results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.28.1",
+  "version": "3.29.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/bootstrap.ts

@@ -479,11 +479,9 @@ export async function initBackendAndDispatcher(
   if (config.mempalace?.enabled) {
     const { getPlugin } = await import("./core/plugin/index.js");
     if (getPlugin("mempalace")) {
-      const { dirs, files: pathFiles } = await import("./util/paths.js");
-      mempalaceCfg = {
-        pythonPath: config.mempalace.pythonPath ?? pathFiles.mempalacePython,
-        palacePath: config.mempalace.palacePath ?? dirs.palace,
-      };
+      const { resolveMempalacePaths } =
+        await import("./plugins/mempalace/provision.js");
+      mempalaceCfg = resolveMempalacePaths(config.mempalace);
     } else {
       log(
         "mempalace",
@@ -529,5 +527,24 @@ export async function initBackendAndDispatcher(
     mempalace: Boolean(mempalaceCfg),
   });
 
+  // Post-/update provisioning report — if the previous process armed one
+  // before respawning, tell the chat that asked for the update what the
+  // provisioners changed during this boot. Fire-and-forget; the delivery
+  // helper retries while frontends finish registering on the cross-send
+  // broker and gives up quietly.
+  {
+    const { deliverPendingProvisionReport } =
+      await import("./core/plugin/provision-journal.js");
+    const { crossSendHandlers } =
+      await import("./core/engine/gateway-actions/cross-send.js");
+    void deliverPendingProvisionReport(async (frontend, target, text) => {
+      const result = await crossSendHandlers.send_via(
+        { frontend, target, text },
+        0,
+      );
+      return Boolean(result && (result as { ok?: unknown }).ok === true);
+    });
+  }
+
   return { backend };
 }

package/src/core/doctor.ts

@@ -78,6 +78,18 @@ export interface DoctorConfigSlice {
   codexApiKey?: string;
   openaiApiKey?: string;
   openaiBaseUrl?: string;
+  mempalace?: {
+    enabled?: boolean;
+    pythonPath?: string;
+    version?: string;
+  };
+  playwright?: {
+    enabled?: boolean;
+    browser?: string;
+    endpoint?: string;
+    endpointFile?: string;
+  };
+  github?: { enabled?: boolean; imageTag?: string };
 }
 
 function errorNote(err: unknown): string {
@@ -297,6 +309,34 @@ async function checkClaudeConfiguredModels(
   return checks;
 }
 
+/**
+ * Native plugin runtimes (MemPalace's venv, Playwright's browser build,
+ * GitHub's Docker image) — the artifacts the provisioners own. The
+ * runtime list and each inspection live in the native-runtimes registry
+ * (src/core/plugin/native-runtimes.ts); a new native plugin shows up
+ * here by registering there. Doctor reads, never mutates: a drifted or
+ * missing runtime reports what will fix it (usually "next talon start").
+ */
+async function checkPluginRuntimes(
+  config: DoctorConfigSlice | undefined,
+): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+  const { NATIVE_RUNTIMES } = await import("./plugin/native-runtimes.js");
+  for (const runtime of NATIVE_RUNTIMES) {
+    if (!runtime.enabled(config)) continue;
+    try {
+      checks.push(...(await runtime.inspect(config!)));
+    } catch (err) {
+      checks.push({
+        label: `${runtime.id} runtime check errored`,
+        status: "warn",
+        detail: errorNote(err),
+      });
+    }
+  }
+  return checks;
+}
+
 /** Every backend id doctor knows how to inspect. */
 const KNOWN_BACKENDS = [
   "claude",
@@ -632,6 +672,7 @@ export async function collectDoctorReport(opts: {
   }
 
   const native = await checkNativeModules();
+  checks.push(...(await checkPluginRuntimes(opts.config)));
   checks.push(...(await checkBackend(opts.config)));
 
   const issues =

package/src/core/plugin/builtins.ts

@@ -3,26 +3,101 @@
  * path that re-reads config, tears down, and re-loads everything.
  */
 
-import { log, logError } from "../../util/log.js";
+import { log, logError, logWarn } from "../../util/log.js";
 import type { TalonConfig } from "../../util/config.js";
 import { registry, reloadState } from "./registry.js";
+import type { ProvisionOutcome } from "./provision.js";
+import { NATIVE_RUNTIMES, type NativePluginId } from "./native-runtimes.js";
+import {
+  recordProvisionEvents,
+  trackBackgroundProvision,
+} from "./provision-journal.js";
 import {
   initPluginWithTimeout,
   loadPlugins,
   registerPlugin,
 } from "./loader.js";
 
+/**
+ * Surface a provisioning outcome in the logs and the journal, and fire
+ * its background reconcile task (fire-and-forget: the plugin is already
+ * serving on whatever the outcome declared usable).
+ */
+function reportProvision(
+  pluginName: NativePluginId,
+  outcome: ProvisionOutcome,
+): void {
+  recordProvisionEvents(pluginName, outcome.actions);
+  for (const action of outcome.actions) {
+    log(pluginName, `provision: ${action}`);
+  }
+  for (const warning of outcome.warnings) {
+    logWarn(pluginName, `provision: ${warning}`);
+  }
+  if (outcome.status === "failed" && outcome.error) {
+    logError(pluginName, `provision failed: ${outcome.error}`);
+  }
+  const background = outcome.background;
+  if (background) {
+    // Tracked so the post-update report waits for it to settle (its
+    // actions are the changes worth reporting).
+    void trackBackgroundProvision(
+      background()
+        .then((result) =>
+          reportProvision(pluginName, { ...result, background: undefined }),
+        )
+        .catch((err) =>
+          logError(
+            pluginName,
+            `background provision: ${err instanceof Error ? err.message : err}`,
+          ),
+        ),
+    );
+  }
+}
+
+/**
+ * Provision every enabled native runtime (see native-runtimes.ts) and
+ * return the outcomes so plugin construction can read what it got
+ * (e.g. the installed version). A provisioner that throws is treated
+ * as a failed pass, never a failed boot.
+ */
+async function provisionNativeRuntimes(
+  config: TalonConfig,
+): Promise<Map<NativePluginId, ProvisionOutcome>> {
+  const outcomes = new Map<NativePluginId, ProvisionOutcome>();
+  for (const runtime of NATIVE_RUNTIMES) {
+    if (!runtime.enabled(config)) continue;
+    try {
+      const outcome = await runtime.provision(config);
+      outcomes.set(runtime.id, outcome);
+      reportProvision(runtime.id, outcome);
+    } catch (err) {
+      logError(
+        runtime.id,
+        `provision: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+  return outcomes;
+}
+
 /**
  * Load built-in plugins (GitHub, MemPalace, mem0, Playwright) based on config flags.
  * Shared by both bootstrap and hot-reload to avoid duplication.
  */
 export async function loadBuiltinPlugins(config: TalonConfig): Promise<void> {
+  const provisioned = await provisionNativeRuntimes(config);
+
   const github = config.github;
   if (github?.enabled) {
     try {
       const { createGitHubPlugin } =
         await import("../../plugins/github/index.js");
-      const gh = createGitHubPlugin({ token: github.token });
+      const gh = createGitHubPlugin({
+        token: github.token,
+        imageTag: github.imageTag,
+      });
       const ghConfig = github as unknown as Record<string, unknown>;
       const loaded = registerPlugin(gh, ghConfig);
       if (loaded) {
@@ -47,14 +122,15 @@ export async function loadBuiltinPlugins(config: TalonConfig): Promise<void> {
     try {
       const { createMempalacePlugin } =
         await import("../../plugins/mempalace/index.js");
-      const { dirs, files: pf } = await import("../../util/paths.js");
-      const pythonPath = mempalace.pythonPath ?? pf.mempalacePython;
-      const palacePath = mempalace.palacePath ?? dirs.palace;
+      const { resolveMempalacePaths } =
+        await import("../../plugins/mempalace/provision.js");
+      const { pythonPath, palacePath } = resolveMempalacePaths(mempalace);
       const mp = createMempalacePlugin({
         pythonPath,
         palacePath,
         entityLanguages: mempalace.entityLanguages,
         verbose: mempalace.verbose,
+        installedVersion: provisioned.get("mempalace")?.version,
       });
       const mpConfig = mempalace as unknown as Record<string, unknown>;
       const loaded = registerPlugin(mp, mpConfig);

package/src/core/plugin/native-runtimes.ts

@@ -0,0 +1,87 @@
+/**
+ * Single source of truth for native plugin runtimes — the built-in
+ * plugins whose MCP servers depend on an artifact Talon doesn't ship
+ * (MemPalace's Python venv, Playwright's browser build, GitHub's Docker
+ * image).
+ *
+ * Everything that iterates "the native plugins" — boot provisioning
+ * (builtins.ts), doctor inspection (doctor.ts), the provisioning CI —
+ * walks this list. Adding a native runtime is one descriptor here plus
+ * its provision module; no other call site changes.
+ *
+ * Plugin modules load lazily inside each method so this module stays
+ * import-cheap for consumers that only need the id list.
+ */
+
+import type { DoctorCheck } from "../doctor.js";
+import type { ProvisionOutcome } from "./provision.js";
+import type { MempalaceSection } from "../../plugins/mempalace/provision.js";
+import type { PlaywrightSection } from "../../plugins/playwright/provision.js";
+import type { GithubSection } from "../../plugins/github/provision.js";
+
+const NATIVE_PLUGIN_IDS = ["mempalace", "playwright", "github"] as const;
+export type NativePluginId = (typeof NATIVE_PLUGIN_IDS)[number];
+
+/**
+ * The config slice native runtimes read. Both TalonConfig and doctor's
+ * DoctorConfigSlice satisfy it structurally.
+ */
+interface NativeRuntimeConfig {
+  mempalace?: ({ enabled?: boolean } & MempalaceSection) | undefined;
+  playwright?: ({ enabled?: boolean } & PlaywrightSection) | undefined;
+  github?: ({ enabled?: boolean } & GithubSection) | undefined;
+}
+
+export interface NativeRuntime {
+  id: NativePluginId;
+  enabled(config: NativeRuntimeConfig | undefined): boolean;
+  /** Install/heal/reconcile the runtime. Only called when enabled. */
+  provision(config: NativeRuntimeConfig): Promise<ProvisionOutcome>;
+  /** Read-only health report for doctor. Only called when enabled. */
+  inspect(config: NativeRuntimeConfig): Promise<DoctorCheck[]>;
+}
+
+export const NATIVE_RUNTIMES: readonly NativeRuntime[] = [
+  {
+    id: "mempalace",
+    enabled: (config) => config?.mempalace?.enabled === true,
+    provision: async (config) => {
+      const { provisionMempalace } =
+        await import("../../plugins/mempalace/provision.js");
+      return provisionMempalace(config.mempalace ?? {});
+    },
+    inspect: async (config) => {
+      const { inspectMempalace } =
+        await import("../../plugins/mempalace/provision.js");
+      return inspectMempalace(config.mempalace ?? {});
+    },
+  },
+  {
+    id: "playwright",
+    enabled: (config) => config?.playwright?.enabled === true,
+    provision: async (config) => {
+      const { provisionPlaywright } =
+        await import("../../plugins/playwright/provision.js");
+      return provisionPlaywright(config.playwright ?? {});
+    },
+    inspect: async (config) => {
+      const { inspectPlaywright } =
+        await import("../../plugins/playwright/provision.js");
+      return inspectPlaywright(config.playwright ?? {});
+    },
+  },
+  {
+    id: "github",
+    enabled: (config) => config?.github?.enabled === true,
+    provision: async (config) => {
+      const { provisionGithubMcp } =
+        await import("../../plugins/github/provision.js");
+      return provisionGithubMcp(config.github ?? {});
+    },
+    inspect: async (config) => {
+      const { inspectGithub } =
+        await import("../../plugins/github/provision.js");
+      return inspectGithub(config.github ?? {});
+    },
+  },
+];

package/src/core/plugin/provision-journal.ts

@@ -0,0 +1,172 @@
+/**
+ * Provision journal — what the provisioners changed, and the post-restart
+ * report that documents it.
+ *
+ * Two small persisted pieces under ~/.talon/data/:
+ *
+ *  - provision-events.json — a capped rolling log of provisioning
+ *    mutations ("upgraded mempalace 3.3.5 → 3.8.0", "palace wing-name
+ *    migration: Migrated 3 drawer(s)."). Every action a provisioner
+ *    reports lands here, whichever boot or background pass produced it.
+ *
+ *  - provision-report-pending.json — armed by a frontend's /update
+ *    command just before the respawn. The successor process, once its
+ *    frontends are serving, reads the marker and messages the chat that
+ *    asked for the update with whatever provisioning changed during the
+ *    new boot — closing the loop that the pre-restart reply can't see.
+ */
+
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dirs } from "../../util/paths.js";
+import { log, logWarn } from "../../util/log.js";
+import type { NativePluginId } from "./native-runtimes.js";
+
+interface ProvisionEvent {
+  at: string;
+  plugin: NativePluginId;
+  action: string;
+}
+
+interface PendingReport {
+  frontend: string;
+  target: string;
+  since: string;
+}
+
+const EVENT_CAP = 50;
+const eventsPath = (): string => join(dirs.data, "provision-events.json");
+const pendingPath = (): string =>
+  join(dirs.data, "provision-report-pending.json");
+
+function readJson<T>(path: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Append provisioning mutations to the rolling event log. */
+export function recordProvisionEvents(
+  plugin: NativePluginId,
+  actions: readonly string[],
+): void {
+  if (actions.length === 0) return;
+  const existing = readJson<ProvisionEvent[]>(eventsPath());
+  const at = new Date().toISOString();
+  const events = [
+    ...(Array.isArray(existing) ? existing : []),
+    ...actions.map((action) => ({ at, plugin, action })),
+  ].slice(-EVENT_CAP);
+  try {
+    writeFileSync(eventsPath(), JSON.stringify(events, null, 2));
+  } catch {
+    /* the journal is reporting, never load-bearing */
+  }
+}
+
+/** Events recorded at or after the given ISO timestamp. */
+function provisionEventsSince(sinceIso: string): ProvisionEvent[] {
+  const events = readJson<ProvisionEvent[]>(eventsPath());
+  if (!Array.isArray(events)) return [];
+  return events.filter((e) => e.at >= sinceIso);
+}
+
+/**
+ * Arm the post-restart report. Called by a frontend's /update handler
+ * right before the respawn, with the chat that asked for the update.
+ */
+export function armProvisionReport(frontend: string, target: string): void {
+  try {
+    writeFileSync(
+      pendingPath(),
+      JSON.stringify({
+        frontend,
+        target,
+        since: new Date().toISOString(),
+      } satisfies PendingReport),
+    );
+  } catch {
+    /* losing the report loses a courtesy message, nothing more */
+  }
+}
+
+const DELIVER_ATTEMPTS = 60;
+const DELIVER_DELAY_MS = 15_000;
+
+/**
+ * Background reconcile tasks still running (a version upgrade, a docker
+ * pull). The post-update report waits for them: their actions are the
+ * changes worth reporting, and they settle minutes after boot.
+ */
+let backgroundInFlight = 0;
+
+/** Track a background provisioning task until it settles (including its journaling). */
+export function trackBackgroundProvision<T>(task: Promise<T>): Promise<T> {
+  backgroundInFlight++;
+  return task.finally(() => {
+    backgroundInFlight--;
+  });
+}
+
+export function backgroundProvisionInFlight(): number {
+  return backgroundInFlight;
+}
+
+/**
+ * Deliver the pending report, if one is armed and this boot's
+ * provisioning changed something. Waits for the boot's background
+ * reconcile tasks to settle before reading the journal, so the report
+ * covers what they did rather than a snapshot taken while pip was still
+ * running, and retries the send because it races frontend registration
+ * on the cross-send broker. Bounded (~15 minutes, matching the longest
+ * provisioner timeout), then gives up quietly — this is a courtesy
+ * message, not state. Returns immediately when nothing is pending and
+ * nothing changed.
+ */
+export async function deliverPendingProvisionReport(
+  send: (frontend: string, target: string, text: string) => Promise<boolean>,
+  sleep: (ms: number) => Promise<void> = (ms) =>
+    new Promise((r) => setTimeout(r, ms).unref?.()),
+): Promise<void> {
+  const pending = readJson<PendingReport>(pendingPath());
+  if (!pending?.frontend || !pending.target || !pending.since) return;
+  // Consume the marker up front so a crashy boot can't replay a stale
+  // report later; the wait loop below keeps it alive in memory.
+  try {
+    rmSync(pendingPath(), { force: true });
+  } catch {
+    /* already gone is fine */
+  }
+
+  for (let attempt = 1; attempt <= DELIVER_ATTEMPTS; attempt++) {
+    // Report only once the background work is done — or, on the last
+    // attempt, whatever has landed so far rather than nothing.
+    const settled = backgroundInFlight === 0 || attempt === DELIVER_ATTEMPTS;
+    if (settled) {
+      const events = provisionEventsSince(pending.since);
+      if (events.length === 0 && backgroundInFlight === 0) return;
+      if (events.length > 0) {
+        const lines = events.map((e) => `• ${e.plugin}: ${e.action}`);
+        const text = `♻️ Back online. Provisioning changes during the update:\n${lines.join("\n")}`;
+        try {
+          if (await send(pending.frontend, pending.target, text)) {
+            log(
+              "plugin",
+              `Post-update provision report delivered (${events.length} change${events.length === 1 ? "" : "s"})`,
+            );
+            return;
+          }
+        } catch {
+          /* fall through to retry */
+        }
+      }
+    }
+    if (attempt < DELIVER_ATTEMPTS) await sleep(DELIVER_DELAY_MS);
+  }
+  logWarn(
+    "plugin",
+    `Post-update provision report not delivered (${pending.frontend} unavailable or provisioning still running)`,
+  );
+}