talon-agent 3.28.0 → 3.29.0

package/src/core/plugin/provision.ts

@@ -0,0 +1,276 @@
+/**
+ * Shared provisioning seam for built-in plugins with native runtimes.
+ *
+ * A "native" plugin (MemPalace's Python venv, Playwright's browser
+ * binaries, GitHub's Docker image) depends on an artifact Talon does not
+ * ship in its npm tarball. This module is the common ground those
+ * provisioners stand on: a persisted state file with failure backoff so
+ * a broken network can't turn boot into a retry storm, a never-throws
+ * exec runner with hard timeouts, cross-OS Python discovery, and a
+ * dependency-free semver compare.
+ *
+ * The contract every provisioner honors: an existing working install is
+ * NEVER made worse. Upgrades that fail keep the current version running;
+ * destructive healing (recreating a venv) is reserved for environments
+ * that are already broken AND owned by Talon.
+ */
+
+import { execFile as execFileCb } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/** What a provisioning pass concluded — pure data, renderers decide presentation. */
+export interface ProvisionOutcome {
+  /**
+   * ready    — the runtime is usable right now (possibly with warnings).
+   * degraded — usable, but not at the pinned version (upgrade failed or deferred).
+   * failed   — not usable; the plugin will not come up until resolved.
+   * skipped  — provisioning disabled or not applicable (e.g. endpoint mode).
+   */
+  status: "ready" | "degraded" | "failed" | "skipped";
+  /** Installed runtime version, when it could be determined. */
+  version?: string;
+  /** Install flavor (e.g. "managed-venv", "uv-tool", "pipx", "system"). */
+  kind?: string;
+  /** Mutations performed this pass ("created venv", "installed 3.8.0", …). */
+  actions: string[];
+  /** Advisory messages for the operator (upgrade hints, backoff notices). */
+  warnings: string[];
+  /** Terminal error detail when status is "failed". */
+  error?: string;
+  /**
+   * A reconcile task the caller may run without blocking boot (e.g. a
+   * version upgrade while a working older install keeps serving). The
+   * caller decides whether to await it or fire-and-forget with logging.
+   */
+  background?: () => Promise<ProvisionOutcome>;
+}
+
+/** Persisted per-provisioner state (one small JSON file under ~/.talon/data/). */
+export interface ProvisionState {
+  /** The version target of the last attempt — a pin change resets backoff. */
+  pin?: string;
+  installedVersion?: string;
+  lastSuccessAt?: string;
+  lastFailureAt?: string;
+  failureCount?: number;
+  lastError?: string;
+  /** One-time data migrations already applied, by name. */
+  migrations?: Record<string, string>;
+}
+
+export function loadProvisionState(path: string): ProvisionState {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return parsed && typeof parsed === "object"
+      ? (parsed as ProvisionState)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveProvisionState(path: string, state: ProvisionState): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2));
+  } catch {
+    /* state is an optimization (backoff, migration ledger) — never fatal */
+  }
+}
+
+/** Base retry delay after the first failure. */
+const BACKOFF_BASE_MS = 5 * 60_000;
+/** Retry delay ceiling. */
+const BACKOFF_MAX_MS = 6 * 60 * 60_000;
+
+/** Exponential backoff: 5min, 10min, 20min … capped at 6h. */
+export function provisionBackoffMs(failureCount: number): number {
+  const exp = Math.max(0, Math.min(failureCount - 1, 30));
+  return Math.min(BACKOFF_BASE_MS * 2 ** exp, BACKOFF_MAX_MS);
+}
+
+/**
+ * Whether a new install/upgrade attempt is due. A changed pin always
+ * re-arms immediately — the operator (or a Talon upgrade) asked for a
+ * different version, so stale failures shouldn't gate it.
+ */
+export function shouldAttempt(
+  state: ProvisionState,
+  pin: string,
+  nowMs: number,
+): boolean {
+  if (!state.lastFailureAt) return true;
+  if (state.pin !== pin) return true;
+  const last = Date.parse(state.lastFailureAt);
+  if (Number.isNaN(last)) return true;
+  return nowMs - last >= provisionBackoffMs(state.failureCount ?? 1);
+}
+
+export interface ExecResult {
+  ok: boolean;
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  /** Spawn-level failure (ENOENT, EACCES, timeout kill), when there was one. */
+  error?: string;
+}
+
+export type ExecFn = (
+  cmd: string,
+  args: readonly string[],
+  opts: { timeoutMs: number; env?: Record<string, string> },
+) => Promise<ExecResult>;
+
+/** Default exec: never throws, hard-kills on timeout, captures both streams. */
+export const runStep: ExecFn = (cmd, args, opts) =>
+  new Promise((resolvePromise) => {
+    execFileCb(
+      cmd,
+      [...args],
+      {
+        timeout: opts.timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: 16 * 1024 * 1024,
+        env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        windowsHide: true,
+      },
+      (err, stdout, stderr) => {
+        const out = stdout?.toString() ?? "";
+        const errOut = stderr?.toString() ?? "";
+        if (!err) {
+          resolvePromise({ ok: true, code: 0, stdout: out, stderr: errOut });
+          return;
+        }
+        const spawnErr = err as NodeJS.ErrnoException & {
+          killed?: boolean;
+          code?: number | string;
+        };
+        const code = typeof spawnErr.code === "number" ? spawnErr.code : null;
+        const error =
+          typeof spawnErr.code === "string"
+            ? spawnErr.code
+            : spawnErr.killed
+              ? `timed out after ${Math.round(opts.timeoutMs / 1000)}s`
+              : undefined;
+        resolvePromise({ ok: false, code, stdout: out, stderr: errOut, error });
+      },
+    );
+  });
+
+/**
+ * Numeric dotted-version compare ("3.8.0" vs "3.10.1"): negative when a < b,
+ * 0 when equal, positive when a > b. Non-numeric segments compare as 0,
+ * which is the safe reading for pre-release suffixes here — a fuzzy match
+ * triggers at worst a no-op reinstall, never a skipped one.
+ */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map((s) => parseInt(s, 10) || 0);
+  const pb = b.split(".").map((s) => parseInt(s, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/** Venv interpreter path for a venv root (bin/python vs Scripts/python.exe). */
+export function venvPython(venvDir: string, platform: NodeJS.Platform): string {
+  return platform === "win32"
+    ? resolve(venvDir, "Scripts", "python.exe")
+    : resolve(venvDir, "bin", "python");
+}
+
+export interface BasePython {
+  command: string;
+  args: string[];
+  version: string;
+}
+
+/**
+ * Find a base interpreter able to seed a venv. Order matters per OS: the
+ * `py` launcher is the canonical entry on Windows (PATH pythons there are
+ * often the Store stub), python3 the canonical one elsewhere.
+ */
+export async function findBasePython(
+  exec: ExecFn,
+  platform: NodeJS.Platform,
+  min: { major: number; minor: number },
+): Promise<BasePython | undefined> {
+  const candidates: Array<[string, string[]]> =
+    platform === "win32"
+      ? [
+          ["py", ["-3"]],
+          ["python", []],
+          ["python3", []],
+        ]
+      : [
+          ["python3", []],
+          ["python", []],
+        ];
+  for (const [command, args] of candidates) {
+    const probe = await exec(
+      command,
+      [...args, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"],
+      { timeoutMs: 20_000 },
+    );
+    if (!probe.ok) continue;
+    const version = probe.stdout.trim();
+    const [major, minor] = version.split(".").map((s) => parseInt(s, 10));
+    if (
+      Number.isFinite(major) &&
+      (major > min.major || (major === min.major && (minor ?? 0) >= min.minor))
+    ) {
+      return { command, args, version };
+    }
+  }
+  return undefined;
+}
+
+/** Expand a leading `~/` (or bare `~`) to the home directory. */
+export function expandHome(path: string, home: string): string {
+  if (path === "~") return home;
+  if (path.startsWith("~/") || path.startsWith("~\\")) {
+    return resolve(home, path.slice(2));
+  }
+  return path;
+}
+
+/** Human-readable failure detail from an exec result (spawn error, last stderr line, or exit code). */
+export function failDetail(result: ExecResult): string {
+  // An empty stderr yields "" from pop(), which is not nullish — treat
+  // it as absent so the exit-code fallback actually fires.
+  const tail = result.stderr.trim().split("\n").pop()?.slice(0, 300);
+  return result.error ?? (tail || `exit ${result.code ?? "?"}`);
+}
+
+/** Record a successful pass: clears the failure streak, persists. */
+export function markProvisionSuccess(
+  statePath: string,
+  state: ProvisionState,
+  pin: string,
+  nowMs: number,
+): void {
+  state.pin = pin;
+  state.lastSuccessAt = new Date(nowMs).toISOString();
+  state.failureCount = 0;
+  state.lastFailureAt = undefined;
+  state.lastError = undefined;
+  saveProvisionState(statePath, state);
+}
+
+/** Record a failed pass: bumps the failure streak for backoff, persists. */
+export function markProvisionFailure(
+  statePath: string,
+  state: ProvisionState,
+  pin: string,
+  error: string,
+  nowMs: number,
+): void {
+  state.pin = pin;
+  state.lastFailureAt = new Date(nowMs).toISOString();
+  state.failureCount = (state.failureCount ?? 0) + 1;
+  state.lastError = error;
+  saveProvisionState(statePath, state);
+}

package/src/frontend/discord/commands/admin.ts

@@ -237,6 +237,11 @@ export async function handleUpdate(
       await edit(
         `✅ Updated \`${res.before ?? "?"}\` → \`${res.after ?? "?"}\`. ♻️ Restarting…`,
       );
+      // The successor documents any provisioning changes (plugin runtime
+      // upgrades, migrations) back to this channel once it's up.
+      const { armProvisionReport } =
+        await import("../../../core/plugin/provision-journal.js");
+      armProvisionReport("discord", String(i.channelId));
       respawnSelf("discord /update");
     })
     .catch(async (err: unknown) => {

package/src/frontend/telegram/commands/admin.ts

@@ -214,6 +214,11 @@ export function registerAdminCommands(
           await edit(
             `✅ Updated <code>${escapeHtml(res.before ?? "?")}</code> → <code>${escapeHtml(res.after ?? "?")}</code>. ♻️ Restarting…`,
           );
+          // The successor documents any provisioning changes (plugin
+          // runtime upgrades, migrations) back to this chat once it's up.
+          const { armProvisionReport } =
+            await import("../../../core/plugin/provision-journal.js");
+          armProvisionReport("telegram", String(ctx.chat.id));
           respawnSelf("telegram /update");
         })
         .catch(async (err: unknown) => {

package/src/plugins/github/index.ts

@@ -14,6 +14,7 @@
 import { execFileSync } from "node:child_process";
 import type { TalonPlugin } from "../../core/plugin/types.js";
 import { log, logWarn } from "../../util/log.js";
+import { githubMcpImageRef } from "./provision.js";
 
 /**
  * Resolve a GitHub personal access token.
@@ -34,8 +35,12 @@ function resolveToken(configToken?: string): string | undefined {
   }
 }
 
-export function createGitHubPlugin(config: { token?: string }): TalonPlugin {
+export function createGitHubPlugin(config: {
+  token?: string;
+  imageTag?: string;
+}): TalonPlugin {
   const token = resolveToken(config.token);
+  const image = githubMcpImageRef(config.imageTag);
 
   return {
     name: "github",
@@ -44,14 +49,7 @@ export function createGitHubPlugin(config: { token?: string }): TalonPlugin {
 
     mcpServer: {
       command: "docker",
-      args: [
-        "run",
-        "--rm",
-        "-i",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN",
-        "ghcr.io/github/github-mcp-server",
-      ],
+      args: ["run", "--rm", "-i", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", image],
     },
 
     validateConfig() {
@@ -79,18 +77,18 @@ export function createGitHubPlugin(config: { token?: string }): TalonPlugin {
     },
 
     async init() {
-      // Verify the Docker image exists locally
+      // Verify the pinned Docker image exists locally (the provisioner
+      // pulls it in the background when absent).
       try {
-        execFileSync(
-          "docker",
-          ["image", "inspect", "ghcr.io/github/github-mcp-server"],
-          { timeout: 10_000, stdio: "pipe" },
-        );
-        log("github", "Docker image verified");
+        execFileSync("docker", ["image", "inspect", image], {
+          timeout: 10_000,
+          stdio: "pipe",
+        });
+        log("github", `Docker image verified (${image})`);
       } catch {
         logWarn(
           "github",
-          "Docker image not found locally — will pull on first use (may be slow)",
+          `Docker image ${image} not present yet — pulling in background; docker pulls on first use as fallback`,
         );
       }
 

package/src/plugins/github/provision.ts

@@ -0,0 +1,172 @@
+/**
+ * GitHub MCP provisioner — pinned Docker image, pulled ahead of use.
+ *
+ * `docker run` on an absent image blocks the first tool call on a
+ * network pull; a floating `latest` means the server silently changes
+ * under a deployment. Pin a known-good tag and front-load the pull at
+ * boot (in the background — docker itself remains the fallback path,
+ * so a slow or failed pull degrades to today's behavior, never worse).
+ */
+
+import { join } from "node:path";
+import type { DoctorCheck } from "../../core/doctor.js";
+import {
+  failDetail,
+  loadProvisionState,
+  markProvisionFailure,
+  markProvisionSuccess,
+  runStep,
+  shouldAttempt,
+  type ExecFn,
+  type ProvisionOutcome,
+} from "../../core/plugin/provision.js";
+import { dirs } from "../../util/paths.js";
+
+/**
+ * The github-mcp-server image tag Talon runs. Bump deliberately, with
+ * the canary workflow green — see .github/workflows/native-provision.yml.
+ */
+export const GITHUB_MCP_PINNED_TAG = "v1.11.0";
+
+const GITHUB_MCP_IMAGE = "ghcr.io/github/github-mcp-server";
+
+const PULL_TIMEOUT_MS = 600_000;
+const INSPECT_TIMEOUT_MS = 20_000;
+
+export function githubMcpImageRef(imageTag?: string): string {
+  return `${GITHUB_MCP_IMAGE}:${imageTag ?? GITHUB_MCP_PINNED_TAG}`;
+}
+
+/** The `github` config section this module reads. */
+export interface GithubSection {
+  imageTag?: string;
+  autoProvision?: boolean;
+}
+
+export interface GithubProvisionDeps {
+  exec?: ExecFn;
+  now?: () => number;
+  statePath?: string;
+}
+
+export async function provisionGithubMcp(
+  section: GithubSection,
+  deps: GithubProvisionDeps = {},
+): Promise<ProvisionOutcome> {
+  const exec = deps.exec ?? runStep;
+  const now = deps.now ?? Date.now;
+  const image = githubMcpImageRef(section.imageTag);
+
+  if (section.autoProvision === false) {
+    return { status: "skipped", kind: "docker", actions: [], warnings: [] };
+  }
+
+  const inspected = await exec("docker", ["image", "inspect", image], {
+    timeoutMs: INSPECT_TIMEOUT_MS,
+  });
+  if (inspected.ok) {
+    return {
+      status: "ready",
+      version: image,
+      kind: "docker",
+      actions: [],
+      warnings: [],
+    };
+  }
+  if (inspected.error === "ENOENT") {
+    // No docker at all — validateConfig already reports this as the
+    // blocking error; provisioning has nothing to add.
+    return {
+      status: "failed",
+      kind: "docker",
+      actions: [],
+      warnings: [],
+      error: "docker not found",
+    };
+  }
+
+  const statePath = deps.statePath ?? join(dirs.data, "github-provision.json");
+  const state = loadProvisionState(statePath);
+  if (!shouldAttempt(state, image, now())) {
+    return {
+      status: "degraded",
+      version: image,
+      kind: "docker",
+      actions: [],
+      warnings: [
+        `image pull previously failed (${state.lastError ?? "unknown"}); docker will pull on first use — retrying with backoff`,
+      ],
+    };
+  }
+
+  return {
+    status: "degraded",
+    version: image,
+    kind: "docker",
+    actions: [],
+    warnings: [`pulling ${image} in the background`],
+    background: async () => {
+      const pulled = await exec("docker", ["pull", image], {
+        timeoutMs: PULL_TIMEOUT_MS,
+      });
+      if (pulled.ok) {
+        markProvisionSuccess(statePath, state, image, now());
+        return {
+          status: "ready",
+          version: image,
+          kind: "docker",
+          actions: [`pulled ${image}`],
+          warnings: [],
+        };
+      }
+      const detail = failDetail(pulled);
+      markProvisionFailure(statePath, state, image, detail, now());
+      return {
+        status: "degraded",
+        version: image,
+        kind: "docker",
+        actions: [],
+        warnings: [
+          `image pull failed (${detail}) — docker will pull on first use`,
+        ],
+        error: detail,
+      };
+    },
+  };
+}
+
+/** Read-only doctor inspection: docker reachable, pinned image present. */
+export async function inspectGithub(
+  section: GithubSection,
+  deps: GithubProvisionDeps = {},
+): Promise<DoctorCheck[]> {
+  const exec = deps.exec ?? runStep;
+  const image = githubMcpImageRef(section.imageTag);
+  const inspected = await exec("docker", ["image", "inspect", image], {
+    timeoutMs: INSPECT_TIMEOUT_MS,
+  });
+  if (inspected.ok) {
+    return [{ label: `GitHub MCP image ${image}`, status: "ok" }];
+  }
+  if (inspected.error === "ENOENT") {
+    return [
+      {
+        label: "GitHub MCP: docker not found",
+        status: "fail",
+        detail: "the GitHub MCP server runs as a Docker image",
+        issue: true,
+      },
+    ];
+  }
+  return [
+    {
+      label: `GitHub MCP image not pulled (${image})`,
+      status: "warn",
+      detail:
+        section.autoProvision === false
+          ? `automatic pull disabled (github.autoProvision: false) — run: docker pull ${image}`
+          : "pulls in the background at next talon start",
+      issue: true,
+    },
+  ];
+}

package/src/plugins/mempalace/index.ts

@@ -10,8 +10,15 @@
  *     "palacePath": "/path/to/palace",         // optional, defaults to ~/.talon/workspace/palace/
  *     "pythonPath": "/path/to/python",         // optional, defaults to mempalace venv python (bin/python on Unix, Scripts/python.exe on Windows)
  *     "entityLanguages": ["en", "ja"],         // optional, BCP 47 codes (mempalace >= 3.3)
- *     "verbose": false                          // optional, enables MEMPAL_VERBOSE diagnostics
+ *     "verbose": false,                         // optional, enables MEMPAL_VERBOSE diagnostics
+ *     "version": "3.8.0",                       // optional, overrides the built-in pin (managed venv only)
+ *     "autoUpdate": true,                       // optional, reconcile managed venv to the pin
+ *     "autoProvision": true                     // optional, create/heal the managed venv
  *   }
+ *
+ * The default venv is provisioned automatically at boot (see
+ * ./provision.ts); a custom pythonPath is operator-managed and never
+ * mutated.
  */
 
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
@@ -38,8 +45,11 @@ export function createMempalacePlugin(config: {
   entityLanguages?: readonly string[];
   /** When true, sets MEMPAL_VERBOSE=1 so the MCP server logs diagnostic diaries. */
   verbose?: boolean;
+  /** Version the provisioner found/installed — logging only. */
+  installedVersion?: string;
 }): TalonPlugin {
-  const { pythonPath, palacePath, entityLanguages, verbose } = config;
+  const { pythonPath, palacePath, entityLanguages, verbose, installedVersion } =
+    config;
 
   const envVars: Record<string, string> = {
     MEMPALACE_PALACE_PATH: palacePath,
@@ -142,7 +152,11 @@ export function createMempalacePlugin(config: {
         entityLanguages && entityLanguages.length > 0
           ? ` (languages: ${entityLanguages.join(",")})`
           : "";
-      log("mempalace", `Ready (palace: ${palacePath})${langSuffix}`);
+      const versionSuffix = installedVersion ? ` v${installedVersion}` : "";
+      log(
+        "mempalace",
+        `Ready${versionSuffix} (palace: ${palacePath})${langSuffix}`,
+      );
     },
 
     getEnvVars() {