talon-agent 1.50.0 → 1.52.0

package/README.md

@@ -17,10 +17,10 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility, and a **Desktop/Mobile app** (Flutter) over a local/remote bridge |
 | **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex, OpenAI Agents — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
 | **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, triggers, goals, stickers, file system, admin controls                              |
-| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                                                          |
+| **Plugins**           | Hot-reloadable plugin system with `talon plugin install/enable/disable` (npm, git, or local sources). Built-in: GitHub, MemPalace, Playwright, Brave Search |
 | **Background agents** | Heartbeat (hourly by default — advances goals, proactively messages when something matters) and Dream (memory consolidation + diary)         |
 | **Goals**             | Persistent multi-day objectives the agent commits to in chat; every heartbeat run re-reads them, makes progress, and records what it did     |
-| **Skills**            | Agent-authored reusable scripts (bash/python/node) — procedures worked out once get saved and replayed locally at zero token cost            |
+| **Skills**            | SKILL.md workflow bundles the agent authors and reuses, with `talon skill install/enable/disable` (local folders, git, or `owner/repo` — the Anthropic skills ecosystem installs directly) |
 | **Triggers**          | Self-authored watcher scripts (bash/python/node) that wake the bot when conditions are met                                                   |
 | **Task table**        | Every unit of agent work — chat turns, heartbeat, dream, isolated cron/trigger jobs — registered live; `talon ps` / `talon kill`             |
 | **Event bus**         | Typed internal pub-sub spine (task + turn lifecycle events); subsystems subscribe instead of importing each other; `talon events -f`         |
@@ -169,6 +169,32 @@ The app provides multi-chat history, live streaming with reasoning + tool-call v
 
 ---
 
+## Managing plugins & skills
+
+Both stores are managed from the CLI; changes hot-reload into a running
+daemon (plugins) or apply on the next session (skills):
+
+```bash
+# Plugins — npm specs, git repos, or local paths
+talon plugin install @scope/my-talon-plugin        # npm → module plugin
+talon plugin install some-mcp-server --mcp         # npm → standalone MCP server (npx)
+talon plugin install owner/repo                    # git → module plugin
+talon plugin list                                  # built-ins + configured entries
+talon plugin disable github                        # also toggles built-ins
+talon plugin remove my-talon-plugin
+
+# Skills — SKILL.md folders from local paths, git URLs, or owner/repo[/subpath]
+talon skill install anthropics/skills/document-skills/pdf
+talon skill install ./my-skill --force
+talon skill list
+talon skill disable pdf                            # hidden from the prompt index, still readable
+talon skill remove pdf
+```
+
+Module plugins install under `~/.talon/plugins/`; standalone MCP servers are
+registered as `npx` entries in `config.json`. Disabling keeps the entry (or a
+`.disabled` marker in the skill folder) so enabling restores it unchanged.
+
 ## Built-in Plugins
 
 ### GitHub

package/package.json

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

package/src/backend/claude-sdk/one-shot.ts

@@ -14,7 +14,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
-import type { OneShotAgentParams } from "../../core/types.js";
+import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log } from "../../util/log.js";
 import { ALLOWED_TOOLS_BACKGROUND } from "../../core/constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
@@ -53,7 +53,7 @@ export function initClaudeOneShot(cfg: OneShotConfig): void {
 
 export async function runOneShotAgent(
   params: OneShotAgentParams,
-): Promise<void> {
+): Promise<OneShotUsage | void> {
   const {
     prompt,
     systemPrompt,
@@ -86,9 +86,22 @@ export async function runOneShotAgent(
     options: options as Parameters<typeof query>[0]["options"],
   });
 
+  // The final `result` message carries the run's total token usage — the
+  // settlement figure the task table records.
+  let usage: OneShotUsage | undefined;
   for await (const msg of qi) {
     await formatAndAppendMessage(appendLog, msg);
+    if (msg.type === "result") {
+      const u = msg.usage;
+      usage = {
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+        cacheRead: u.cache_read_input_tokens ?? 0,
+        cacheWrite: u.cache_creation_input_tokens ?? 0,
+      };
+    }
   }
+  return usage;
 }
 
 /**

package/src/backend/codex/one-shot.ts

@@ -17,7 +17,7 @@
  * fires — no orphan process handling needed.
  */
 
-import type { OneShotAgentParams } from "../../core/types.js";
+import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log, logWarn } from "../../util/log.js";
 import { appendBackendSuffix } from "../shared/index.js";
 import { ensureCodex, getCodexAuthInfo } from "./init.js";
@@ -69,7 +69,7 @@ function resolveOneShotModel(requested: string): {
 
 export async function runOneShotAgent(
   params: OneShotAgentParams,
-): Promise<void> {
+): Promise<OneShotUsage | void> {
   const {
     prompt,
     systemPrompt,
@@ -118,10 +118,25 @@ export async function runOneShotAgent(
       signal: abortController.signal,
     });
 
+    // `turn.completed.usage` is cumulative across the run — the last one
+    // seen is the settlement figure the task table records.
+    let usage: OneShotUsage | undefined;
     for await (const event of events) {
       if (abortController.signal.aborted) break;
       await appendCodexEvent(appendLog, event);
+      if (event.type === "turn.completed") {
+        const u = (event as { usage?: Record<string, number> }).usage;
+        if (u) {
+          usage = {
+            inputTokens: u.input_tokens ?? 0,
+            outputTokens: u.output_tokens ?? 0,
+            cacheRead: u.cached_input_tokens ?? 0,
+            cacheWrite: 0, // Codex doesn't report cache writes
+          };
+        }
+      }
     }
+    return usage;
   } catch (err) {
     if (
       abortController.signal.aborted ||

package/src/backend/kilo/one-shot.ts

@@ -7,7 +7,7 @@
  * suffix; everything else is the shared lifecycle.
  */
 
-import type { OneShotAgentParams } from "../../core/types.js";
+import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { runRemoteOneShotAgent } from "../remote-server/one-shot.js";
 import {
   ensureServer,
@@ -21,7 +21,9 @@ import {
   errMsg,
 } from "./server.js";
 
-export function runOneShotAgent(params: OneShotAgentParams): Promise<void> {
+export function runOneShotAgent(
+  params: OneShotAgentParams,
+): Promise<OneShotUsage | void> {
   return runRemoteOneShotAgent(
     {
       label: "Kilo",

package/src/backend/opencode/one-shot.ts

@@ -7,7 +7,7 @@
  * suffix; everything else is the shared lifecycle.
  */
 
-import type { OneShotAgentParams } from "../../core/types.js";
+import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { runRemoteOneShotAgent } from "../remote-server/one-shot.js";
 import {
   ensureServer,
@@ -21,7 +21,9 @@ import {
   errMsg,
 } from "./server.js";
 
-export function runOneShotAgent(params: OneShotAgentParams): Promise<void> {
+export function runOneShotAgent(
+  params: OneShotAgentParams,
+): Promise<OneShotUsage | void> {
   return runRemoteOneShotAgent(
     {
       label: "OpenCode",

package/src/backend/remote-server/one-shot.ts

@@ -26,8 +26,12 @@
  * model stops spending tokens once the timeout fires.
  */
 
-import type { OneShotAgentParams } from "../../core/types.js";
+import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { logWarn } from "../../util/log.js";
+import {
+  extractAssistantUsage,
+  type RemoteAssistantInfo,
+} from "./session-helpers.js";
 import { appendBackendSuffix } from "../shared/index.js";
 
 // ── Client surface ──────────────────────────────────────────────────────────
@@ -86,7 +90,7 @@ export async function runRemoteOneShotAgent<
 >(
   bindings: RemoteOneShotBindings<TClient>,
   params: OneShotAgentParams,
-): Promise<void> {
+): Promise<OneShotUsage | void> {
   const {
     prompt,
     systemPrompt,
@@ -162,6 +166,21 @@ export async function runRemoteOneShotAgent<
     for (const part of parts) {
       await appendResponsePart(appendLog, part);
     }
+
+    // The prompt response's assistant info carries the run's token usage —
+    // the settlement figure the task table records.
+    const info = data?.info as RemoteAssistantInfo | undefined;
+    if (info) {
+      const u = extractAssistantUsage(info);
+      if (u.inputTokens > 0 || u.outputTokens > 0) {
+        return {
+          inputTokens: u.inputTokens,
+          outputTokens: u.outputTokens,
+          cacheRead: u.cacheRead,
+          cacheWrite: u.cacheWrite,
+        };
+      }
+    }
   } finally {
     abortController.signal.removeEventListener("abort", onAbort);
     await bindings.disconnectChatMcpServer(oc, chatMcpServerName);

package/src/cli/daemon-api.ts

@@ -13,10 +13,11 @@ export async function fetchGateway(
   port: number,
   path: string,
   init?: RequestInit,
+  timeoutMs: number = REQUEST_TIMEOUT_MS,
 ): Promise<unknown> {
   const response = await fetch(`http://127.0.0.1:${port}${path}`, {
     ...init,
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    signal: AbortSignal.timeout(timeoutMs),
   });
   if (!response.ok) throw new Error(`gateway answered ${response.status}`);
   return response.json();

package/src/cli/index.ts

@@ -33,6 +33,8 @@ import { daemonStart, daemonStop, daemonRestart } from "./daemon.js";
 import { showTasks, killTask } from "./tasks.js";
 import { showEvents } from "./events.js";
 import { showLs, showCat } from "./fs.js";
+import { runPluginCommand } from "./plugin.js";
+import { runSkillCommand } from "./skill.js";
 import { mainMenu } from "./menu.js";
 
 export * from "./context.js";
@@ -63,6 +65,8 @@ const CLI_COMMANDS = [
   "events",
   "ls",
   "cat",
+  "plugin",
+  "skill",
 ];
 
 /** Route a `talon <command>` invocation. Called by the entry point. */
@@ -128,6 +132,12 @@ export async function runCli(): Promise<void> {
     case "cat":
       await showCat(process.argv[3]);
       break;
+    case "plugin":
+      await runPluginCommand(process.argv.slice(3));
+      break;
+    case "skill":
+      await runSkillCommand(process.argv.slice(3));
+      break;
     case "--version":
     case "-v": {
       console.log(pkg.version);
@@ -158,6 +168,12 @@ export async function runCli(): Promise<void> {
       console.log(
         `    ${pc.cyan("cat")}        Read a talon:// file (cat proc/events)`,
       );
+      console.log(
+        `    ${pc.cyan("plugin")}     Manage plugins (install/enable/disable)`,
+      );
+      console.log(
+        `    ${pc.cyan("skill")}      Manage skills (install/enable/disable)`,
+      );
       console.log(`    ${pc.cyan("config")}     View/edit configuration`);
       console.log(`    ${pc.cyan("logs")}       Tail log file`);
       console.log(`    ${pc.cyan("doctor")}     Validate environment`);

package/src/cli/install-sources.ts

@@ -0,0 +1,106 @@
+/**
+ * Install-source resolution shared by `talon plugin install` and
+ * `talon skill install`.
+ *
+ * One grammar for both commands, checked in order:
+ *
+ *   1. an existing local path                → { kind: "local" }
+ *   2. a git URL (scheme, `git@`, or `.git`) → { kind: "git" }
+ *   3. `owner/repo[/subpath]` shorthand      → { kind: "git" } on github.com
+ *   4. anything else                         → { kind: "other" } — the caller
+ *      decides (plugins treat it as an npm spec, skills reject it)
+ *
+ * Cloning always uses `--depth=1` (installs never need history) and spawns
+ * `git`/`npm` via cross-spawn, which resolves the `.cmd`/`.exe` shims on
+ * Windows — never assume a POSIX shell here.
+ */
+
+import crossSpawn from "cross-spawn";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+export type ResolvedSource =
+  | { kind: "local"; dir: string }
+  | { kind: "git"; url: string; subpath?: string }
+  | { kind: "other"; raw: string };
+
+const GIT_URL_RE = /^(https?|git|ssh):\/\//;
+/** `owner/repo` or `owner/repo/sub/path` — never an npm scope (`@…`). */
+const GITHUB_SHORTHAND_RE =
+  /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)((?:\/[^\s/]+)*)$/;
+
+export function resolveSource(raw: string): ResolvedSource {
+  const trimmed = raw.trim();
+  if (existsSync(resolve(trimmed))) {
+    return { kind: "local", dir: resolve(trimmed) };
+  }
+  if (
+    GIT_URL_RE.test(trimmed) ||
+    trimmed.startsWith("git@") ||
+    trimmed.endsWith(".git")
+  ) {
+    return { kind: "git", url: trimmed };
+  }
+  if (!trimmed.startsWith("@")) {
+    const match = GITHUB_SHORTHAND_RE.exec(trimmed);
+    if (match) {
+      const [, owner, repo, rest] = match;
+      return {
+        kind: "git",
+        url: `https://github.com/${owner}/${repo}.git`,
+        ...(rest ? { subpath: rest.slice(1) } : {}),
+      };
+    }
+  }
+  return { kind: "other", raw: trimmed };
+}
+
+export type CommandOutcome = { ok: true } | { ok: false; error: string };
+
+/**
+ * Run a tool from PATH synchronously. `inherit` streams output to the
+ * terminal (npm installs); otherwise stderr is captured for the error.
+ */
+export function runTool(
+  tool: string,
+  args: string[],
+  options: { cwd?: string; inherit?: boolean } = {},
+): CommandOutcome {
+  const result = crossSpawn.sync(tool, args, {
+    cwd: options.cwd,
+    stdio: options.inherit ? "inherit" : ["ignore", "ignore", "pipe"],
+  });
+  if (result.error) {
+    const missing = (result.error as NodeJS.ErrnoException).code === "ENOENT";
+    return {
+      ok: false,
+      error: missing
+        ? `${tool} is not installed or not on PATH`
+        : result.error.message,
+    };
+  }
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString().trim();
+    return {
+      ok: false,
+      error: stderr || `${tool} ${args[0]} exited with ${result.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+export type CloneOutcome =
+  { ok: true; dir: string; cleanup: () => void } | { ok: false; error: string };
+
+/** Shallow-clone into a fresh temp directory. Caller must run `cleanup`. */
+export function cloneShallow(url: string): CloneOutcome {
+  const dir = mkdtempSync(join(tmpdir(), "talon-install-"));
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  const outcome = runTool("git", ["clone", "--depth=1", url, dir]);
+  if (!outcome.ok) {
+    cleanup();
+    return { ok: false, error: `Clone failed: ${outcome.error}` };
+  }
+  return { ok: true, dir, cleanup };
+}

package/src/cli/plugin-entries.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure helpers over the config `plugins` array for the `talon plugin`
+ * command group. The CLI edits config.json as JSON — 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: 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;
+}