talon-agent 1.50.0 → 1.52.0

package/src/cli/skill.ts

@@ -0,0 +1,252 @@
+/**
+ * `talon skill` — install / list / enable / disable / remove SKILL.md
+ * workflow bundles.
+ *
+ * All lifecycle logic lives in storage/skill-store.ts; this module only
+ * resolves install sources and renders outcomes. Installs accept a local
+ * folder, a git URL, or `owner/repo[/subpath]` (so `talon skill install
+ * anthropics/skills/skills/pdf` works). A source folder either IS a skill
+ * (has SKILL.md) or is a collection whose immediate children are skills —
+ * collections install every child.
+ *
+ * No daemon round-trip needed: the prompt index re-reads the store on the
+ * next prompt assembly, so changes apply to new sessions automatically.
+ */
+
+import pc from "picocolors";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  deleteSkill,
+  installSkillFromDir,
+  listSkills,
+  setSkillEnabled,
+  type Skill,
+} from "../storage/skill-store.js";
+import { cloneShallow, resolveSource } from "./install-sources.js";
+
+const USAGE = [
+  `  Usage: ${pc.cyan("talon skill <command>")}`,
+  "",
+  "  Commands:",
+  `    ${pc.cyan("list")}                       Show installed skills`,
+  `    ${pc.cyan("install <source> [--force]")} Add skills from a local folder,`,
+  "                               git URL, or owner/repo[/subpath]",
+  `    ${pc.cyan("enable <name>")}              Restore a skill to the prompt index`,
+  `    ${pc.cyan("disable <name>")}             Hide a skill from the prompt index`,
+  `    ${pc.cyan("remove <name>")}              Delete a skill folder`,
+  "",
+].join("\n");
+
+function ok(message: string): void {
+  console.log(`  ${pc.green("●")} ${message}`);
+}
+
+function fail(message: string): void {
+  console.log(`  ${pc.red("✖")} ${message}`);
+}
+
+// ── list ────────────────────────────────────────────────────────────────────
+
+function cmdList(): void {
+  const skills = listSkills();
+  if (skills.length === 0) {
+    console.log(
+      `  ${pc.dim("No skills installed — try")} ${pc.cyan("talon skill install <source>")}\n`,
+    );
+    return;
+  }
+
+  const header = ["NAME", "STATE", "UPDATED", "DESCRIPTION"];
+  const cells = skills.map((skill) => [
+    skill.name,
+    skill.enabled ? "enabled" : "disabled",
+    skill.updatedAt
+      ? new Date(skill.updatedAt).toISOString().slice(0, 10)
+      : "unknown",
+    skill.description,
+  ]);
+  const widths = header.map((h, col) =>
+    Math.max(h.length, ...cells.map((r) => r[col]!.length)),
+  );
+  const pad = (row: string[]) =>
+    row.map((cell, col) => cell.padEnd(widths[col]!));
+
+  console.log(`  ${pc.dim(pad(header).join("  "))}`);
+  skills.forEach((skill, i) => {
+    const padded = pad(cells[i]!);
+    const state = cells[i]![1]!;
+    padded[1] =
+      (skill.enabled ? pc.green(state) : pc.dim(state)) +
+      " ".repeat(widths[1]! - state.length);
+    console.log(`  ${padded.join("  ")}`);
+  });
+  console.log();
+}
+
+// ── install ─────────────────────────────────────────────────────────────────
+
+/**
+ * The folders to install from a source dir: itself when it is a skill,
+ * else every immediate child that is one.
+ */
+function collectSkillDirs(dir: string): string[] {
+  if (existsSync(resolve(dir, "SKILL.md"))) return [dir];
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => resolve(dir, entry.name))
+      .filter((child) => existsSync(resolve(child, "SKILL.md")))
+      .sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+function installAll(dirs: string[], force: boolean): Skill[] {
+  const installed: Skill[] = [];
+  for (const dir of dirs) {
+    const outcome = installSkillFromDir(dir, { force });
+    if (outcome.ok) {
+      installed.push(outcome.skill);
+      ok(
+        `Installed ${pc.bold(outcome.skill.name)} — ${outcome.skill.description}`,
+      );
+    } else {
+      fail(outcome.error);
+    }
+  }
+  return installed;
+}
+
+async function cmdInstall(args: string[]): Promise<void> {
+  const force = args.includes("--force");
+  const source = args.find((arg) => !arg.startsWith("-"));
+  if (!source) {
+    console.log(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolved = resolveSource(source);
+  if (resolved.kind === "other") {
+    fail(
+      `"${source}" is not a folder, git URL, or owner/repo — skills install from SKILL.md folders.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let installed: Skill[];
+  if (resolved.kind === "local") {
+    const dirs = collectSkillDirs(resolved.dir);
+    if (dirs.length === 0) {
+      fail(`No SKILL.md found in ${resolved.dir} (or its immediate children).`);
+      process.exitCode = 1;
+      return;
+    }
+    installed = installAll(dirs, force);
+  } else {
+    const clone = cloneShallow(resolved.url);
+    if (!clone.ok) {
+      fail(clone.error);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const root = resolved.subpath
+        ? resolve(clone.dir, resolved.subpath)
+        : clone.dir;
+      if (!existsSync(root)) {
+        fail(`Path "${resolved.subpath}" not found in ${resolved.url}`);
+        process.exitCode = 1;
+        return;
+      }
+      const dirs = collectSkillDirs(root);
+      if (dirs.length === 0) {
+        fail(
+          `No SKILL.md found under ${resolved.subpath ?? "the repository root"} (or its immediate children).`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      installed = installAll(dirs, force);
+    } finally {
+      clone.cleanup();
+    }
+  }
+
+  if (installed.length === 0) {
+    process.exitCode = 1;
+  } else {
+    console.log(
+      `  ${pc.dim("Skills appear in the prompt index from the next session.")}`,
+    );
+  }
+  console.log();
+}
+
+// ── enable / disable / remove ───────────────────────────────────────────────
+
+function cmdSetEnabled(name: string | undefined, enabled: boolean): void {
+  const verb = enabled ? "enable" : "disable";
+  if (!name) {
+    fail(`Usage: ${pc.cyan(`talon skill ${verb} <name>`)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!setSkillEnabled(name, enabled)) {
+    fail(`No skill named "${name}" — see ${pc.cyan("talon skill list")}.`);
+    process.exitCode = 1;
+    return;
+  }
+  ok(
+    enabled
+      ? `Skill ${pc.bold(name)} enabled — back in the prompt index next session.`
+      : `Skill ${pc.bold(name)} disabled — hidden from the prompt index (still readable via read_skill).`,
+  );
+  console.log();
+}
+
+function cmdRemove(name: string | undefined): void {
+  if (!name) {
+    fail(`Usage: ${pc.cyan("talon skill remove <name>")}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!deleteSkill(name)) {
+    fail(`No skill named "${name}" — see ${pc.cyan("talon skill list")}.`);
+    process.exitCode = 1;
+    return;
+  }
+  ok(`Removed skill ${pc.bold(name)} (folder deleted).`);
+  console.log();
+}
+
+// ── dispatch ────────────────────────────────────────────────────────────────
+
+export async function runSkillCommand(args: string[]): Promise<void> {
+  console.log();
+  const [subcommand, ...rest] = args;
+  switch (subcommand) {
+    case "list":
+    case undefined:
+      cmdList();
+      break;
+    case "install":
+      await cmdInstall(rest);
+      break;
+    case "enable":
+      cmdSetEnabled(rest[0], true);
+      break;
+    case "disable":
+      cmdSetEnabled(rest[0], false);
+      break;
+    case "remove":
+      cmdRemove(rest[0]);
+      break;
+    default:
+      console.log(USAGE);
+      process.exitCode = 1;
+  }
+}

package/src/core/agent-runtime/capabilities.ts

@@ -27,6 +27,7 @@ import type {
   ModelPickerOptions,
   ModelPickerResult,
   OneShotAgentParams,
+  OneShotUsage,
   UnifiedModelInfo,
   UnifiedModelResolution,
   UnifiedProviderInfo,
@@ -131,12 +132,14 @@ export interface ChatBackend {
  *   - `runOneShotAgent(params)` — accepts `OneShotAgentParams`
  *     (with its `appendLog` callback) so the heartbeat / dream /
  *     trigger log-file producers keep their direct write path.
+ *     Resolves with the run's token usage when the SDK reports it
+ *     (the task table records it at settlement); void otherwise.
  *   - `evictOrphanSubprocesses(label)` — backends that spawn
  *     per-run subprocesses (Claude SDK) implement this so a hung
  *     run can be force-cleaned after the abort grace window.
  */
 export interface BackgroundRunner {
-  runOneShotAgent(params: OneShotAgentParams): Promise<void>;
+  runOneShotAgent(params: OneShotAgentParams): Promise<OneShotUsage | void>;
   evictOrphanSubprocesses?(contextLabel: string): Promise<{
     found: number;
     termed: number;

package/src/core/background/dream.ts

@@ -296,15 +296,17 @@ If commands fail, log the error and continue — this stage is optional.`
   });
 
   const agentPromise = (async () => {
-    await background.runOneShotAgent(oneShotParams);
+    const usage = await background.runOneShotAgent(oneShotParams);
     appendDreamLog(
       dreamLogFile,
       `\n---\n**Dream completed at ${new Date().toISOString()}**\n`,
     );
+    return usage;
   })();
 
+  let usage: Awaited<typeof agentPromise>;
   try {
-    await Promise.race([agentPromise, timeoutPromise]);
+    usage = await Promise.race([agentPromise, timeoutPromise]);
   } catch (err) {
     task.fail(err);
     appendDreamLog(
@@ -332,7 +334,7 @@ If commands fail, log the error and continue — this stage is optional.`
     if (timeoutHandle) clearTimeout(timeoutHandle);
   }
 
-  task.succeed();
+  task.succeed(usage ?? undefined);
   return dreamLogFile;
 }
 

package/src/core/background/heartbeat/agent.ts

@@ -220,15 +220,17 @@ export async function runHeartbeatAgent(
   });
 
   const agentPromise = (async () => {
-    await background.runOneShotAgent(oneShotParams);
+    const usage = await background.runOneShotAgent(oneShotParams);
     await appendHeartbeatLog(
       heartbeatLogFile,
       `\n---\n**Heartbeat #${runCount} completed at ${new Date().toISOString()}**\n`,
     );
+    return usage;
   })();
 
+  let usage: Awaited<typeof agentPromise>;
   try {
-    await Promise.race([agentPromise, timeoutPromise]);
+    usage = await Promise.race([agentPromise, timeoutPromise]);
   } catch (err) {
     // Snapshot timeout state and clear the timer immediately, BEFORE any awaits
     // in the error-handling path. Otherwise the timer can fire during the async
@@ -278,7 +280,7 @@ export async function runHeartbeatAgent(
     if (timeoutHandle) clearTimeout(timeoutHandle);
   }
 
-  task.succeed();
+  task.succeed(usage ?? undefined);
   return heartbeatLogFile;
 }
 

package/src/core/background/isolated-agent.ts

@@ -15,7 +15,7 @@
  */
 
 import type { BackgroundRunner } from "../agent-runtime/capabilities.js";
-import type { OneShotAgentParams } from "../types.js";
+import type { OneShotAgentParams, OneShotUsage } from "../types.js";
 import { logWarn, logError } from "../../util/log.js";
 
 /** Default bounded grace after an abort before giving up on the backend. */
@@ -55,11 +55,12 @@ async function raceWithTimeout<T>(
 
 /**
  * Run the one-shot under a hard timeout. Throws on timeout (after the grace
- * window) and re-throws any agent error.
+ * window) and re-throws any agent error. Resolves with the run's token
+ * usage when the backend reports it.
  */
 export async function runIsolatedAgent(
   opts: IsolatedRunOptions,
-): Promise<void> {
+): Promise<OneShotUsage | void> {
   const { background, params, timeoutMs } = opts;
   const graceMs = opts.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
 
@@ -81,7 +82,7 @@ export async function runIsolatedAgent(
   });
 
   try {
-    await Promise.race([agentPromise, timeoutPromise]);
+    return await Promise.race([agentPromise, timeoutPromise]);
   } catch (err) {
     // Snapshot + clear before any await so a late timer can't reclassify a
     // non-timeout failure as a timeout (heartbeat learned this the hard way).

package/src/core/background/job-oneshot.ts

@@ -157,7 +157,7 @@ export async function runJobOneShot(
     };
 
     try {
-      await runIsolatedAgent({
+      const usage = await runIsolatedAgent({
         background,
         params: oneShot,
         timeoutMs: params.timeoutMs ?? DEFAULT_JOB_TIMEOUT_MS,
@@ -165,7 +165,7 @@ export async function runJobOneShot(
         // sweep here could kill a concurrent heartbeat's subprocess. Bounded
         // abort-grace is enough.
       });
-      task.succeed();
+      task.succeed(usage ?? undefined);
     } catch (err) {
       task.fail(err);
       throw err;

package/src/core/engine/gateway-actions/plugins.ts

@@ -5,30 +5,47 @@
  */
 
 import { log, logWarn } from "../../../util/log.js";
+import type { Backend } from "../../agent-runtime/capabilities.js";
 import type { SharedActionHandlers } from "./types.js";
 
-export const pluginHandlers: SharedActionHandlers = {
-  reload_plugins: async (body, chatId, backend) => {
-    try {
-      const { reloadPlugins, getPluginPromptAdditions } =
-        await import("../../plugin/index.js");
-      const { rebuildSystemPrompt } = await import("../../../util/config.js");
-      const { clearSystemPromptSnapshots } =
-        await import("../../../backend/shared/system-prompt.js");
+/**
+ * The chat-independent half of a plugin reload: re-read config, reload
+ * plugins, rebuild the system prompt, and drop per-session prompt
+ * snapshots. Shared by the `reload_plugins` action (which additionally
+ * hot-swaps MCP servers on the caller's chat) and the gateway's
+ * `POST /plugins/reload` endpoint, which has no chat context. Throws on
+ * failure — each caller renders errors its own way.
+ */
+export async function performPluginReload(
+  backend?: Backend | null,
+): Promise<{ names: string[] }> {
+  const { reloadPlugins, getPluginPromptAdditions } =
+    await import("../../plugin/index.js");
+  const { rebuildSystemPrompt } = await import("../../../util/config.js");
+  const { clearSystemPromptSnapshots } =
+    await import("../../../backend/shared/system-prompt.js");
 
-      // reloadPlugins reads + validates config internally — no double read.
-      // Frontends are derived from config if not explicitly provided.
-      const { names, config: freshConfig } = await reloadPlugins();
+  // reloadPlugins reads + validates config internally — no double read.
+  // Frontends are derived from config if not explicitly provided.
+  const { names, config: freshConfig } = await reloadPlugins();
 
-      // Rebuild system prompt on the freshConfig, then update the backend's
-      // live config reference so subsequent messages use the new prompt
-      rebuildSystemPrompt(freshConfig, getPluginPromptAdditions());
-      backend?.control?.updateSystemPrompt?.(freshConfig.systemPrompt);
+  // Rebuild system prompt on the freshConfig, then update the backend's
+  // live config reference so subsequent messages use the new prompt
+  rebuildSystemPrompt(freshConfig, getPluginPromptAdditions());
+  backend?.control?.updateSystemPrompt?.(freshConfig.systemPrompt);
 
-      // Plugin prompt additions changed — drop per-session prompt
-      // snapshots so every chat's next turn picks up the new prompt
-      // (deliberate one-time cache re-write per live session).
-      clearSystemPromptSnapshots();
+  // Plugin prompt additions changed — drop per-session prompt
+  // snapshots so every chat's next turn picks up the new prompt
+  // (deliberate one-time cache re-write per live session).
+  clearSystemPromptSnapshots();
+
+  return { names };
+}
+
+export const pluginHandlers: SharedActionHandlers = {
+  reload_plugins: async (body, chatId, backend) => {
+    try {
+      const { names } = await performPluginReload(backend);
 
       // Hot-swap MCP servers on the active query so new plugin tools
       // are available immediately (not just on the next message)

package/src/core/engine/gateway.ts

@@ -475,6 +475,30 @@ export class Gateway {
           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

package/src/core/plugin/entries.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure helpers over the config `plugins` array, shared by every surface
+ * that lists or toggles plugins (the `talon plugin` command group, the
+ * client bridge's plugin endpoints). Entries here are the on-disk shape
+ * (`core/plugin/types.ts` PluginEntry), not loaded plugins. No filesystem
+ * or process access — everything is testable data-in/data-out.
+ */
+
+/** On-disk plugin entry — path-based module or standalone MCP server. */
+export type PluginEntryJson = {
+  path?: string;
+  config?: Record<string, unknown>;
+  name?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  enabled?: boolean;
+};
+
+/**
+ * Built-in plugins toggled by their own config sections (`github.enabled`,
+ * …) rather than `plugins[]` entries — see core/plugin/builtins.ts.
+ */
+export const BUILTIN_PLUGINS = [
+  "github",
+  "mempalace",
+  "mem0",
+  "playwright",
+] as const;
+
+export function isBuiltinPlugin(name: string): boolean {
+  return (BUILTIN_PLUGINS as readonly string[]).includes(name);
+}
+
+/** Split a config path on either separator — Windows configs carry `\`. */
+function pathSegments(path: string): string[] {
+  return path.split(/[\\/]+/).filter(Boolean);
+}
+
+/**
+ * Display name for an entry: the MCP name, or for path entries the package
+ * name — segments after the last `node_modules` (preserving `@scope/pkg`),
+ * else the folder basename.
+ */
+export function entryDisplayName(entry: PluginEntryJson): string {
+  if (entry.name) return entry.name;
+  if (!entry.path) return "(invalid entry)";
+  const segments = pathSegments(entry.path);
+  const nm = segments.lastIndexOf("node_modules");
+  if (nm >= 0 && nm < segments.length - 1) {
+    return segments.slice(nm + 1).join("/");
+  }
+  return segments[segments.length - 1] ?? entry.path;
+}
+
+/** Does `token` identify this entry? Display name, basename, or full path. */
+export function entryMatches(entry: PluginEntryJson, token: string): boolean {
+  if (entryDisplayName(entry) === token) return true;
+  if (!entry.path) return false;
+  const segments = pathSegments(entry.path);
+  return entry.path === token || segments[segments.length - 1] === token;
+}
+
+export function findEntryIndex(
+  entries: readonly PluginEntryJson[],
+  token: string,
+): number {
+  return entries.findIndex((entry) => entryMatches(entry, token));
+}
+
+/**
+ * Index of an entry with the same identity as `candidate` (same module
+ * path or same MCP name) — the duplicate an install must replace.
+ */
+export function findConflictIndex(
+  entries: PluginEntryJson[],
+  candidate: PluginEntryJson,
+): number {
+  return entries.findIndex((entry) =>
+    candidate.path !== undefined
+      ? entry.path === candidate.path
+      : entry.name !== undefined && entry.name === candidate.name,
+  );
+}
+
+/**
+ * Copy of `entry` with the enabled state applied. Enabled is the default,
+ * so enabling removes the key rather than writing `enabled: true`.
+ */
+export function withEnabled(
+  entry: PluginEntryJson,
+  enabled: boolean,
+): PluginEntryJson {
+  const { enabled: _drop, ...rest } = entry;
+  return enabled ? rest : { ...rest, enabled: false };
+}
+
+/**
+ * Package name of an npm spec, version stripped: `pkg@1.2` → `pkg`,
+ * `@scope/pkg@^1` → `@scope/pkg`. A leading `@` is the scope, not a version.
+ */
+export function npmSpecName(spec: string): string {
+  const at = spec.lastIndexOf("@");
+  return at > 0 ? spec.slice(0, at) : spec;
+}

package/src/core/plugin/loader.ts

@@ -16,8 +16,11 @@ import type {
 import { isMcpPlugin } from "./types.js";
 import { registry, _deps } from "./registry.js";
 
-/** Candidate entry point paths, checked in order. */
-const ENTRY_CANDIDATES = [
+/**
+ * Candidate entry point paths, checked in order. Exported for
+ * `talon plugin install`, which verifies a module before adding it.
+ */
+export const ENTRY_CANDIDATES = [
   "src/index.ts",
   "dist/index.js",
   "index.ts",
@@ -35,6 +38,15 @@ export async function loadPlugins(
   activeFrontends?: string[],
 ): Promise<void> {
   for (const entry of pluginConfigs) {
+    // Disabled entries stay in config (so `talon plugin enable` can restore
+    // them) but are never loaded or registered.
+    if (entry.enabled === false) {
+      log(
+        "plugin",
+        `Skipped disabled plugin: ${isMcpPlugin(entry) ? entry.name : entry.path}`,
+      );
+      continue;
+    }
     // Standalone MCP servers are registered for getPluginMcpServers, not loaded as modules
     if (isMcpPlugin(entry)) {
       if (registry.registerMcpEntry(entry)) {