talon-agent 1.50.0 → 1.52.0

package/src/core/plugin/manage.ts

@@ -0,0 +1,99 @@
+/**
+ * Plugin management over the live config — list and toggle, outcomes as
+ * data. The client bridge's plugin endpoints run through here in-process;
+ * the CLI edits config.json out-of-process with the same `entries.ts`
+ * helpers and converges through `POST /plugins/reload`. Rendering (and
+ * persisting/hot-applying, which are surface concerns) stay with the
+ * caller: a toggle returns the exact partial document to merge into
+ * talon.json so the surface owns its own write path.
+ */
+
+import type { TalonConfig } from "../../util/config.js";
+import { isPathPlugin, type PluginEntry } from "./types.js";
+import {
+  BUILTIN_PLUGINS,
+  entryDisplayName,
+  findEntryIndex,
+  isBuiltinPlugin,
+  withEnabled,
+} from "./entries.js";
+
+/** One plugin as every management surface lists it. */
+export type PluginItem = {
+  readonly name: string;
+  readonly kind: "builtin" | "module" | "mcp";
+  readonly enabled: boolean;
+  /** Where it comes from: a config section, module path, or MCP command. */
+  readonly source: string;
+};
+
+export type PluginToggleOutcome =
+  | {
+      readonly ok: true;
+      readonly name: string;
+      /** Partial talon.json document the surface must persist. */
+      readonly persist: Record<string, unknown>;
+    }
+  | { readonly ok: false; readonly error: string };
+
+function builtinSection(
+  config: TalonConfig,
+  name: string,
+): { enabled?: boolean } | undefined {
+  return (config as unknown as Record<string, { enabled?: boolean }>)[name];
+}
+
+/** Every plugin: built-ins first, then configured entries, config order. */
+export function listPluginItems(config: TalonConfig): PluginItem[] {
+  const builtins: PluginItem[] = BUILTIN_PLUGINS.map((name) => ({
+    name,
+    kind: "builtin" as const,
+    enabled: builtinSection(config, name)?.enabled === true,
+    source: `config.${name}`,
+  }));
+  const configured: PluginItem[] = (config.plugins ?? []).map((entry) => ({
+    name: entryDisplayName(entry),
+    kind: isPathPlugin(entry) ? ("module" as const) : ("mcp" as const),
+    enabled: entry.enabled !== false,
+    source: isPathPlugin(entry)
+      ? entry.path
+      : `${entry.command}${entry.args ? ` ${entry.args.join(" ")}` : ""}`,
+  }));
+  return [...builtins, ...configured];
+}
+
+/**
+ * Toggle a plugin on the LIVE config object (so in-process readers see the
+ * change immediately) and report what to persist. Hot-applying (plugin
+ * reload, prompt rebuild) is the caller's follow-up — this function only
+ * decides and mutates state.
+ */
+export function setPluginEnabled(
+  config: TalonConfig,
+  rawName: string,
+  enabled: boolean,
+): PluginToggleOutcome {
+  const name = rawName.trim();
+  if (!name) return { ok: false, error: "A plugin name is required." };
+
+  if (isBuiltinPlugin(name)) {
+    const section = { ...(builtinSection(config, name) ?? {}), enabled };
+    (config as unknown as Record<string, unknown>)[name] = section;
+    return { ok: true, name, persist: { [name]: section } };
+  }
+
+  const list: PluginEntry[] = config.plugins ?? [];
+  const index = findEntryIndex(list, name);
+  if (index < 0) {
+    return { ok: false, error: `No plugin named "${name}".` };
+  }
+  // withEnabled only adds/drops the `enabled` key, so the entry keeps its
+  // (validated) format — safe to narrow back from the JSON helper shape.
+  list[index] = withEnabled(list[index]!, enabled) as PluginEntry;
+  config.plugins = list;
+  return {
+    ok: true,
+    name: entryDisplayName(list[index]!),
+    persist: { plugins: list },
+  };
+}

package/src/core/plugin/types.ts

@@ -8,6 +8,8 @@ import type { ActionResult } from "../types.js";
 export interface PluginPathEntry {
   path: string;
   config?: Record<string, unknown>;
+  /** `false` keeps the entry in config but skips loading it. Default true. */
+  enabled?: boolean;
 }
 
 /** Standalone MCP server entry (command + args, not a loadable module). */
@@ -16,6 +18,8 @@ export interface PluginMcpEntry {
   command: string;
   args?: string[];
   env?: Record<string, string>;
+  /** `false` keeps the entry in config but skips registering it. Default true. */
+  enabled?: boolean;
 }
 
 /** Configuration entry for a plugin in config.json. */

package/src/core/types.ts

@@ -120,6 +120,18 @@ export interface ModelPickerResult {
  * fire-and-forget agent invocation: spawn an agent with a prompt, let it run
  * tools, log everything to a file, return when it finishes (or when aborted).
  */
+/**
+ * Token usage a one-shot run reports at settlement, when the backend's SDK
+ * surfaces it. Shape-compatible with the task table's `TaskUsage`, so the
+ * background callers can hand it straight to `TaskHandle.succeed`.
+ */
+export type OneShotUsage = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheRead: number;
+  cacheWrite: number;
+};
+
 export type OneShotAgentParams = {
   /** The user prompt the agent should execute. */
   prompt: string;

package/src/frontend/native/extensions.ts

@@ -0,0 +1,93 @@
+/**
+ * Extensions over the bridge — plugins and skills, list + toggle.
+ *
+ * This is what backs the companion app's Plugins and Skills settings
+ * sub-menus. Listing is a pure read (core/plugin/manage.ts for plugins,
+ * the skill store for skills); a toggle mutates the live state, persists
+ * it, and hot-applies so the change is real on the very next turn:
+ *
+ *   - plugin toggle → merge into talon.json + full plugin reload (same
+ *     path as `POST /plugins/reload`), so tools appear/disappear live;
+ *   - skill toggle → `.disabled` marker via the skill store + system
+ *     prompt rebuild (skills render into the prompt; no plugin reload
+ *     needed).
+ *
+ * Toggles hide capability from the model's default view — they never
+ * restrict it. That contract lives in the stores; nothing here adds
+ * gating on top.
+ */
+
+import type { Backend } from "../../core/agent-runtime/capabilities.js";
+import { performPluginReload } from "../../core/engine/gateway-actions/plugins.js";
+import { getPluginPromptAdditions } from "../../core/plugin/index.js";
+import { listPluginItems, setPluginEnabled } from "../../core/plugin/manage.js";
+import { clearSystemPromptSnapshots } from "../../backend/shared/system-prompt.js";
+import { listSkills, setSkillEnabled } from "../../storage/skill-store.js";
+import { rebuildSystemPrompt, type TalonConfig } from "../../util/config.js";
+import { log } from "../../util/log.js";
+import type { PluginItem, SkillItem, ToggleResult } from "./protocol.js";
+import { persistConfigPatch } from "./settings.js";
+
+export function pluginItems(config: TalonConfig): PluginItem[] {
+  return listPluginItems(config);
+}
+
+export function skillItems(): SkillItem[] {
+  return listSkills().map(({ name, description, enabled }) => ({
+    name,
+    description,
+    enabled,
+  }));
+}
+
+/**
+ * Toggle a plugin: mutate the live config, persist the change, then
+ * hot-reload plugins (rebuilds the system prompt and drops per-session
+ * prompt snapshots on the way). A reload failure after a successful save
+ * is reported as an error — the state is on disk, but the caller must
+ * know the daemon hasn't applied it.
+ */
+export async function togglePlugin(
+  config: TalonConfig,
+  backend: Backend | null,
+  name: string,
+  enabled: boolean,
+): Promise<ToggleResult> {
+  const outcome = setPluginEnabled(config, name, enabled);
+  if (!outcome.ok) return { ok: false, error: outcome.error };
+  persistConfigPatch(outcome.persist);
+  log(
+    "native",
+    `Plugin ${outcome.name} ${enabled ? "enabled" : "disabled"} via bridge`,
+  );
+  try {
+    await performPluginReload(backend);
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Saved, but the hot reload failed: ${err instanceof Error ? err.message : String(err)} — restart Talon to apply.`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Toggle a skill: the store drops/creates the `.disabled` marker, then the
+ * system prompt is rebuilt so the skill index reflects the change on every
+ * chat's next turn. No plugin reload — skills don't carry tools.
+ */
+export function toggleSkill(
+  config: TalonConfig,
+  backend: Backend | null,
+  name: string,
+  enabled: boolean,
+): ToggleResult {
+  if (!setSkillEnabled(name, enabled)) {
+    return { ok: false, error: `No skill named "${name}".` };
+  }
+  log("native", `Skill ${name} ${enabled ? "enabled" : "disabled"} via bridge`);
+  rebuildSystemPrompt(config, getPluginPromptAdditions());
+  backend?.control?.updateSystemPrompt?.(config.systemPrompt);
+  clearSystemPromptSnapshots();
+  return { ok: true };
+}

package/src/frontend/native/index.ts

@@ -52,6 +52,12 @@ import {
 import { resetSession } from "../../storage/sessions.js";
 import { resetPulseCheckpoint } from "../../core/background/pulse.js";
 import { configSnapshot, applyConfigUpdate } from "./settings.js";
+import {
+  pluginItems,
+  skillItems,
+  togglePlugin,
+  toggleSkill,
+} from "./extensions.js";
 import { resolveModel } from "../../core/models/catalog.js";
 import {
   getBackendForChat,
@@ -743,7 +749,7 @@ export function createNativeFrontend(
     return {
       app: "talon-bridge",
       protocol: BRIDGE_PROTOCOL_VERSION,
-      capabilities: ["mesh", "mesh-commands"],
+      capabilities: ["mesh", "mesh-commands", "plugins-skills"],
       botName,
       backend: config.backend,
       model: resolveModel(config.model)?.displayName ?? config.model,
@@ -1168,6 +1174,12 @@ export function createNativeFrontend(
       broadcast({ kind: "status", status: status() });
       return snap;
     },
+    listPlugins: () => pluginItems(config),
+    setPluginEnabled: (name, enabled) =>
+      togglePlugin(config, getPooledBackend(config.backend), name, enabled),
+    listSkills: () => skillItems(),
+    setSkillEnabled: (name, enabled) =>
+      toggleSkill(config, getPooledBackend(config.backend), name, enabled),
     control,
     logs: ({ lines, minLevel, component }) =>
       readLogEntries(files.log, { limit: lines, minLevel, component }),

package/src/frontend/native/protocol.ts

@@ -197,6 +197,39 @@ export type BackendOption = {
   label: string;
 };
 
+/**
+ * One installed plugin, as `GET /plugins` lists it. Toggled via
+ * `POST /plugins/toggle` (`{ name, enabled }` → `ToggleResult`). Additive
+ * in v1 behind the `plugins-skills` capability — older clients never call
+ * these endpoints.
+ */
+export type PluginItem = {
+  name: string;
+  /** Built-in (config-section) plugin, module plugin, or MCP server. */
+  kind: "builtin" | "module" | "mcp";
+  enabled: boolean;
+  /** Where it comes from: a config section, module path, or MCP command. */
+  source: string;
+};
+
+/**
+ * One installed skill, as `GET /skills` lists it. Toggled via
+ * `POST /skills/toggle` — a disabled skill drops out of the model's
+ * prompt index but stays installed.
+ */
+export type SkillItem = {
+  name: string;
+  description: string;
+  enabled: boolean;
+};
+
+/**
+ * Application-level outcome of a toggle, always carried in an HTTP 200
+ * body (mirrors `/backend`: the client renders ok/error, HTTP-level
+ * failures stay transport errors).
+ */
+export type ToggleResult = { ok: boolean; error?: string };
+
 // Mesh device shapes are canonical in core (the mesh is daemon-wide state,
 // readable from every frontend); re-exported here so bridge clients keep
 // depending on the protocol module alone.

package/src/frontend/native/server.ts

@@ -40,7 +40,10 @@ import {
   type LogEntry,
   type LogLevel,
   type ModelOption,
+  type PluginItem,
   type SearchResult,
+  type SkillItem,
+  type ToggleResult,
 } from "./protocol.js";
 import type { ConfigSnapshot } from "./settings.js";
 
@@ -100,6 +103,14 @@ export type BridgeServerHandlers = {
   getConfig(): ConfigSnapshot;
   /** Change daemon settings; returns the fresh snapshot. */
   setConfig(update: Record<string, unknown>): ConfigSnapshot;
+  /** Installed plugins (built-ins + configured entries) with state. */
+  listPlugins(): PluginItem[];
+  /** Enable/disable a plugin; persists + hot-reloads. */
+  setPluginEnabled(name: string, enabled: boolean): Promise<ToggleResult>;
+  /** Installed skills with state. */
+  listSkills(): SkillItem[];
+  /** Enable/disable a skill; rebuilds the prompt index. */
+  setSkillEnabled(name: string, enabled: boolean): ToggleResult;
   /** Fire a daemon-level control action (e.g. "restart", "dream"). */
   control(action: string): Promise<{ ok: boolean; message: string }>;
   /** Newest daemon log entries (for the client's log viewer). */
@@ -552,6 +563,32 @@ export class BridgeServer {
         });
       }
 
+      if (method === "GET" && path === "/plugins")
+        return this.json(res, 200, { plugins: this.handlers.listPlugins() });
+
+      if (method === "POST" && path === "/plugins/toggle") {
+        const body = await this.readJson(req);
+        // Always 200: ok/error is an application result the client renders,
+        // not an HTTP-level failure (mirrors /backend).
+        const result = await this.handlers.setPluginEnabled(
+          asString(body.name) ?? "",
+          body.enabled === true,
+        );
+        return this.json(res, 200, result);
+      }
+
+      if (method === "GET" && path === "/skills")
+        return this.json(res, 200, { skills: this.handlers.listSkills() });
+
+      if (method === "POST" && path === "/skills/toggle") {
+        const body = await this.readJson(req);
+        const result = this.handlers.setSkillEnabled(
+          asString(body.name) ?? "",
+          body.enabled === true,
+        );
+        return this.json(res, 200, result);
+      }
+
       if (method === "GET" && path === "/config")
         return this.json(res, 200, this.handlers.getConfig());
 

package/src/frontend/native/settings.ts

@@ -175,15 +175,19 @@ export function applyConfigUpdate(
   }
 
   if (Object.keys(persist).length > 0) {
-    persistToFile(persist);
+    persistConfigPatch(persist);
     log("native", `Config updated: ${Object.keys(persist).join(", ")}`);
   }
 
   return configSnapshot(config);
 }
 
-/** Merge a partial update into talon.json on disk, preserving everything else. */
-function persistToFile(update: Record<string, unknown>): void {
+/**
+ * Merge a partial update into talon.json on disk, preserving everything
+ * else. Shared by every bridge surface that persists config changes
+ * (settings sync here, plugin toggles in extensions.ts).
+ */
+export function persistConfigPatch(update: Record<string, unknown>): void {
   const file = pathFiles.config;
   let current: Record<string, unknown> = {};
   try {

package/src/storage/skill-store.ts

@@ -15,12 +15,14 @@
  */
 
 import {
+  cpSync,
   existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
   rmSync,
   statSync,
+  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { basename, resolve } from "node:path";
@@ -33,6 +35,12 @@ export type Skill = {
   body: string;
   path: string;
   updatedAt: number;
+  /**
+   * Disabled skills (a `.disabled` marker file in the folder) drop out of
+   * the prompt index and `find_skills`, but stay listable and readable —
+   * the toggle hides, it never restricts.
+   */
+  enabled: boolean;
   /** Relative filenames bundled in the skill folder (excludes SKILL.md). */
   resources: string[];
   /** Frontmatter keys beyond name/description, preserved on read. */
@@ -46,6 +54,12 @@ export type SkillSearchResult = {
 };
 
 const SKILL_FILE = "SKILL.md";
+/**
+ * Marker file for `talon skill disable`. Lives beside SKILL.md rather than
+ * in frontmatter because `save_skill` rewrites SKILL.md wholesale — a
+ * sibling file survives every update, and is visible in the filesystem.
+ */
+const DISABLED_FILE = ".disabled";
 const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 const DESCRIPTION_MAX_CHARS = 300;
 const BODY_MAX_BYTES = 128 * 1024;
@@ -109,7 +123,10 @@ function serializeSkill(input: {
   return ["---", yaml, "---", "", input.body.trimEnd(), ""].join("\n");
 }
 
-function parseSkill(path: string, raw: string): Omit<Skill, "resources"> {
+function parseSkill(
+  path: string,
+  raw: string,
+): Omit<Skill, "resources" | "enabled"> {
   const fallbackName = basename(resolve(path, ".."));
   if (!raw.startsWith("---\n")) {
     return {
@@ -174,7 +191,12 @@ function parseSkill(path: string, raw: string): Omit<Skill, "resources"> {
 function listResources(dir: string): string[] {
   try {
     return readdirSync(dir, { withFileTypes: true })
-      .filter((entry) => entry.isFile() && entry.name !== SKILL_FILE)
+      .filter(
+        (entry) =>
+          entry.isFile() &&
+          entry.name !== SKILL_FILE &&
+          entry.name !== DISABLED_FILE,
+      )
       .map((entry) => entry.name)
       .sort((a, b) => a.localeCompare(b));
   } catch {
@@ -207,7 +229,11 @@ export function readSkill(name: string): Skill | undefined {
   if (!existsSync(path)) return undefined;
   const raw = readFileSync(path, "utf-8");
   const parsed = parseSkill(path, raw);
-  const skill: Skill = { ...parsed, resources: listResources(dir) };
+  const skill: Skill = {
+    ...parsed,
+    enabled: !existsSync(resolve(dir, DISABLED_FILE)),
+    resources: listResources(dir),
+  };
   try {
     skill.updatedAt = Math.floor(statSync(path).mtimeMs);
   } catch {
@@ -271,6 +297,7 @@ export function searchSkills(
   const tokens = tokenizeQuery(query);
   if (tokens.length === 0) return [];
   return listSkills()
+    .filter((skill) => skill.enabled)
     .map((skill) => ({
       skill,
       score: scoreSkill(skill, tokens),
@@ -283,6 +310,90 @@ export function searchSkills(
     .slice(0, Math.max(1, Math.min(50, limit)));
 }
 
+/**
+ * Toggle a skill's enabled state via the `.disabled` marker. Idempotent.
+ * Returns false when the skill doesn't exist (or the name is invalid).
+ */
+export function setSkillEnabled(name: string, enabled: boolean): boolean {
+  if (validateSkillName(name)) return false;
+  if (!existsSync(skillFilePath(name))) return false;
+  const marker = resolve(skillDir(name), DISABLED_FILE);
+  if (enabled) {
+    if (existsSync(marker)) unlinkSync(marker);
+  } else {
+    writeFileSync(marker, "", { encoding: "utf-8", mode: 0o600 });
+  }
+  return true;
+}
+
+export type SkillInstallResult =
+  { ok: true; skill: Skill } | { ok: false; error: string };
+
+/**
+ * Install a skill from a folder containing SKILL.md (plus any bundled
+ * resources) — the store half of `talon skill install`. The target folder
+ * name is the frontmatter `name`, so a checkout's directory name never
+ * leaks into the store. Refuses to overwrite an existing skill unless
+ * `force`, in which case the old folder (including its `.disabled` marker)
+ * is replaced wholesale.
+ */
+export function installSkillFromDir(
+  sourceDir: string,
+  options: { force?: boolean } = {},
+): SkillInstallResult {
+  const sourceFile = resolve(sourceDir, SKILL_FILE);
+  if (!existsSync(sourceFile)) {
+    return { ok: false, error: `No ${SKILL_FILE} in ${sourceDir}` };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(sourceFile, "utf-8");
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Could not read ${sourceFile}: ${err instanceof Error ? err.message : err}`,
+    };
+  }
+
+  const parsed = parseSkill(sourceFile, raw);
+  const invalid =
+    validateSkillName(parsed.name) ??
+    validateSkillDescription(parsed.description) ??
+    validateSkillBody(parsed.body);
+  if (invalid) return { ok: false, error: `Invalid skill: ${invalid}` };
+
+  const target = skillDir(parsed.name);
+  // Installing the store's own folder onto itself would delete the source
+  // before the copy (rmSync + cpSync) — refuse rather than lose the skill.
+  if (resolve(sourceDir) === target) {
+    return {
+      ok: false,
+      error: `"${parsed.name}" is already the installed copy (${target})`,
+    };
+  }
+  if (existsSync(target)) {
+    if (!options.force) {
+      return {
+        ok: false,
+        error: `Skill "${parsed.name}" already exists (use --force to replace)`,
+      };
+    }
+    rmSync(target, { recursive: true, force: true });
+  }
+
+  mkdirSync(skillsDir(), { recursive: true });
+  cpSync(sourceDir, target, { recursive: true });
+  const skill = readSkill(parsed.name);
+  if (!skill) {
+    return {
+      ok: false,
+      error: `Install of "${parsed.name}" failed to read back`,
+    };
+  }
+  return { ok: true, skill };
+}
+
 export function deleteSkill(name: string): boolean {
   // Reject names that fail validation (e.g. "../escape") before they
   // are turned into a filesystem path — guards against path traversal.
@@ -297,7 +408,8 @@ export function formatSkill(skill: Skill): string {
   const updated = skill.updatedAt
     ? new Date(skill.updatedAt).toISOString().slice(0, 10)
     : "unknown";
-  return `- ${skill.name} (updated ${updated}) — ${skill.description}`;
+  const state = skill.enabled ? "" : " [disabled]";
+  return `- ${skill.name} (updated ${updated})${state} — ${skill.description}`;
 }
 
 export function formatSkillSearchResult(result: SkillSearchResult): string {
@@ -307,7 +419,8 @@ export function formatSkillSearchResult(result: SkillSearchResult): string {
 }
 
 export function renderSkillsPrompt(): string {
-  const skills = listSkills();
+  // Disabled skills stay out of the index; `list_skills` still shows them.
+  const skills = listSkills().filter((skill) => skill.enabled);
   if (skills.length === 0) return "";
   const visible = skills.slice(0, PROMPT_LIST_LIMIT);
   const hidden = skills.length - visible.length;

package/src/util/config.ts

@@ -34,6 +34,7 @@ const pluginPathSchema = z
   .object({
     path: z.string(),
     config: z.record(z.string(), z.unknown()).optional(),
+    enabled: z.boolean().optional(),
   })
   .strict();
 
@@ -44,6 +45,7 @@ const pluginMcpSchema = z
     command: z.string(),
     args: z.array(z.string()).optional(),
     env: z.record(z.string(), z.string()).optional(),
+    enabled: z.boolean().optional(),
   })
   .strict();
 
@@ -55,6 +57,11 @@ const pluginEntrySchema = z
     command: z.string().optional(),
     args: z.array(z.string()).optional(),
     env: z.record(z.string(), z.string()).optional(),
+    /**
+     * `false` keeps the entry in config but skips loading it — the state
+     * behind `talon plugin enable/disable`. Valid on both entry formats.
+     */
+    enabled: z.boolean().optional(),
   })
   .strict()
   .superRefine((value, ctx) => {

package/src/util/paths.ts

@@ -7,6 +7,7 @@
  * Layout:
  *   ~/.talon/
  *     config.json              Main configuration
+ *     plugins/                 CLI-installed plugins (npm prefix / git clones)
  *     data/                    Internal state
  *       talon.db               SQLite — all structured state (sessions,
  *                              history, settings, media, goals, scripts,
@@ -71,6 +72,8 @@ export const dirs = {
   skills: resolve(TALON_ROOT, "workspace", "skills"),
   /** Key material (bridge TLS identity, release keys): ~/.talon/keys/ */
   keys: resolve(TALON_ROOT, "keys"),
+  /** CLI-installed plugins (`talon plugin install`): ~/.talon/plugins/ */
+  plugins: resolve(TALON_ROOT, "plugins"),
 } as const;
 
 // ── Files ──────────────────────────────────────────────────────────────────