talon-agent 1.53.0 → 2.0.0

package/README.md

@@ -24,7 +24,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **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`         |
-| **VFS**               | Unified `talon://` namespace over workspace, skills, scripts, logs, plus /proc-style live views of the task table, event bus, and plugin registry; `talon ls` / `talon cat` |
+| **VFS**               | Unified `talon://` namespace over workspace, skills, scripts, logs, plus /proc-style live views of the task table, event bus, and plugin registry — a real filesystem at `~/.talon/ns` (FUSE-backed live views), so plain `ls`/`cat` and every tool just work |
 | **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                                                                   |
 | **Model registry**    | Models discovered from the active backend at startup — new models appear in all pickers automatically                                        |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.53.0",
+  "version": "2.0.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -89,7 +89,8 @@
     "build:driver": "node native/talon-driver/build.mjs",
     "build:driver:all": "node native/talon-driver/build.mjs --all",
     "build:warden": "node native/talon-warden/build.mjs",
-    "build:napi": "node native/blake3-napi/build.mjs"
+    "build:napi": "node native/blake3-napi/build.mjs",
+    "build:fusefs": "node native/talon-fusefs/build.mjs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.197",

package/src/app.ts

@@ -24,6 +24,11 @@ import {
 import { shutdownTriggers } from "./core/background/triggers/index.js";
 import { startWatchdog, stopWatchdog } from "./util/watchdog.js";
 import { log, logError, logWarn } from "./util/log.js";
+import {
+  getVfs,
+  mountNamespaceFs,
+  unmountNamespaceFs,
+} from "./core/vfs/index.js";
 import { bootstrap, initBackendAndDispatcher } from "./bootstrap.js";
 import { Gateway } from "./core/engine/gateway.js";
 import type { Frontend } from "./bootstrap.js";
@@ -179,6 +184,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
       await destroyPlugins();
     });
   }
+  await shutdownStep("fuse layer", unmountNamespaceFs);
   await shutdownStep("pulse timer", stopPulseTimer);
   await shutdownStep("heartbeat", async () => {
     stopHeartbeatTimer();
@@ -230,6 +236,11 @@ process.on("unhandledRejection", (reason) => {
 // ── Start ────────────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
+  // Namespace on disk first: symlink farm always, live views (proc/,
+  // plugins/) via FUSE when the host can. Bounded and never-throwing —
+  // a host without FUSE boots identically, minus live views.
+  await mountNamespaceFs({ mode: config.fuse, vfs: getVfs() });
+
   await Promise.all(frontends.map((frontend) => frontend.init()));
   log("bot", "Starting Talon...");
 

package/src/cli/index.ts

@@ -32,7 +32,6 @@ import { startChat } from "./chat.js";
 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";
@@ -63,8 +62,6 @@ const CLI_COMMANDS = [
   "ps",
   "kill",
   "events",
-  "ls",
-  "cat",
   "plugin",
   "skill",
 ];
@@ -126,12 +123,6 @@ export async function runCli(): Promise<void> {
       });
       break;
     }
-    case "ls":
-      await showLs(process.argv[3]);
-      break;
-    case "cat":
-      await showCat(process.argv[3]);
-      break;
     case "plugin":
       await runPluginCommand(process.argv.slice(3));
       break;
@@ -162,12 +153,6 @@ export async function runCli(): Promise<void> {
       console.log(
         `    ${pc.cyan("events")}     Tail the event bus (-f follows, --history [N] reads the journal)`,
       );
-      console.log(
-        `    ${pc.cyan("ls")}         List the talon:// namespace (ls proc/tasks)`,
-      );
-      console.log(
-        `    ${pc.cyan("cat")}        Read a talon:// file (cat proc/events)`,
-      );
       console.log(
         `    ${pc.cyan("plugin")}     Manage plugins (install/enable/disable)`,
       );

package/src/core/doctor.ts

@@ -395,6 +395,26 @@ export async function collectDoctorReport(opts: {
     );
   }
 
+  // Same optional contract for the namespace FUSE addon: absent means
+  // ~/.talon/ns is the symlink farm only (file mounts fine, no live
+  // proc//plugins views), so it's informational, not an issue.
+  {
+    const { nativeFuseFs } = await import("../native/fusefs.js");
+    const addon = nativeFuseFs();
+    checks.push(
+      addon
+        ? {
+            label: `Namespace FUSE: talon-fusefs addon v${addon.version()}`,
+            status: "ok",
+          }
+        : {
+            label: "Namespace FUSE: symlink farm only (no addon)",
+            status: "info",
+            detail: "npm run build:fusefs",
+          },
+    );
+  }
+
   // Package-owned prompt templates must be loadable. On a standalone
   // `bun build --compile` binary these are embedded file assets (no
   // source tree on disk); a failure here means the embed manifest is

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

@@ -17,7 +17,6 @@
  *   - `plugins`   — plugin hot-reload
  *   - `models`    — model / backend discovery
  *   - `mesh`      — companion device mesh (presence + location)
- *   - `vfs`       — the unified talon:// namespace (list/read/write)
  */
 
 import type { ActionResult } from "../../types.js";
@@ -34,7 +33,6 @@ import { pluginHandlers } from "./plugins.js";
 import { modelHandlers } from "./models.js";
 import { meshHandlers } from "./mesh.js";
 import { nativeHandlers } from "./native.js";
-import { vfsHandlers } from "./vfs.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method — `handlers[action]` only
@@ -51,7 +49,6 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...modelHandlers,
   ...meshHandlers,
   ...nativeHandlers,
-  ...vfsHandlers,
 });
 
 export async function handleSharedAction(

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

@@ -24,7 +24,7 @@ import {
   stat as fsStat,
   writeFile,
 } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, extname, join } from "node:path";
 import { getMeshService } from "../../mesh/index.js";
 import {
@@ -33,7 +33,12 @@ import {
   setTeleport,
   setTeleportCwd,
 } from "../../mesh/teleport.js";
-import { getVfs } from "../../vfs/index.js";
+import {
+  getVfs,
+  isNamespaceFsMounted,
+  resolveNamespacePath,
+  rewriteNamespaceRefs,
+} from "../../vfs/index.js";
 import {
   clampExecOutput,
   createOutputCapture,
@@ -164,24 +169,61 @@ async function bash(
   timeoutSec: unknown,
   background?: unknown,
 ): Promise<Result> {
-  const cmd = typeof command === "string" ? command : "";
+  let cmd = typeof command === "string" ? command : "";
   if (!cmd.trim()) return { ok: false, text: "No command given." };
   const timeoutMs = clampTimeout(timeoutSec);
   const active = await getTeleport(chatId);
-  if (background === true) {
-    if (active) {
-      return {
-        ok: false,
-        text:
-          "background:true runs on the daemon host only. On a teleported device, " +
-          "background it in-shell instead: `cmd > /tmp/out.log 2>&1 &`, then poll " +
-          "the log with read.",
-      };
+
+  // talon:// references in the command translate to real paths before the
+  // shell ever sees them — teleported they can't (wrong address space).
+  let mappings: string[] = [];
+  if (cmd.includes("talon:") && !active) {
+    const rewritten = rewriteNamespaceRefs(
+      cmd,
+      getVfs(),
+      isNamespaceFsMounted(),
+    );
+    if (!rewritten.ok) return { ok: false, text: rewritten.error };
+    cmd = rewritten.command;
+    mappings = rewritten.mappings;
+  }
+  if (cmd.includes(NAMESPACE_SCHEME) && active) {
+    return {
+      ok: false,
+      text:
+        `talon:// names the daemon's namespace, but native tools are ` +
+        `teleported onto ${active.deviceName} — teleport_back first, or use a device path.`,
+    };
+  }
+
+  let dir = typeof cwd === "string" && cwd.trim() ? cwd.trim() : undefined;
+  if (dir !== undefined && !active) {
+    const resolved = resolvePathParam(dir, undefined);
+    if ("error" in resolved) return { ok: false, text: resolved.error };
+    dir = resolved.path;
+  }
+
+  const result = await (async () => {
+    if (background === true) {
+      if (active) {
+        return {
+          ok: false,
+          text:
+            "background:true runs on the daemon host only. On a teleported device, " +
+            "background it in-shell instead: `cmd > /tmp/out.log 2>&1 &`, then poll " +
+            "the log with read.",
+        };
+      }
+      return bashBackground(cmd, dir);
     }
-    return bashBackground(cmd, typeof cwd === "string" ? cwd : undefined);
+    if (active) return bashTeleported(chatId, active.deviceId, cmd, timeoutMs);
+    return bashLocal(cmd, dir, timeoutMs);
+  })();
+  // Surface the translation so it's visible, never silent.
+  if (mappings.length > 0) {
+    return { ...result, text: `↪ ${mappings.join("  ")}\n${result.text}` };
   }
-  if (active) return bashTeleported(chatId, active.deviceId, cmd, timeoutMs);
-  return bashLocal(cmd, typeof cwd === "string" ? cwd : undefined, timeoutMs);
+  return result;
 }
 
 /**
@@ -452,59 +494,63 @@ async function bashTeleported(
 
 const NAMESPACE_SCHEME = "talon://";
 
-type AddressResolution =
-  | { kind: "disk"; path: string }
-  | { kind: "virtual" }
-  | { kind: "error"; text: string };
-
 /**
- * Native fs tools accept talon:// addresses: `Vfs.locate` maps them to the
- * disk location the address names, and the tool then operates on the real
- * file. Synthetic nodes (proc/, plugins/) have no disk location — reads are
- * served straight from the namespace, mutation refuses honestly. Teleport
- * can't cross address spaces: talon:// names daemon state, and a teleported
- * chat's paths belong to the device, so the combination is refused rather
- * than resolved against the wrong filesystem.
+ * talon:// addresses translate to real host paths (core/vfs/rewrite.ts)
+ * and then flow through the exact same fs code as any other path — no
+ * virtual nodes, no special branches. With the FUSE layer mounted even
+ * proc/ and plugins/ are ordinary files; without it they are refused at
+ * resolution. Teleport can't cross address spaces: talon:// names
+ * daemon state, and a teleported chat's paths belong to the device, so
+ * the combination is refused rather than resolved against the wrong
+ * filesystem.
  */
-function resolveNamespaceAddress(
+function resolveAddress(
   address: string,
   teleportedTo: string | undefined,
-): AddressResolution {
+): { path: string } | { error: string } {
   if (teleportedTo !== undefined) {
     return {
-      kind: "error",
-      text:
+      error:
         `${address} names the daemon's namespace, but native tools are ` +
         `teleported onto ${teleportedTo} — teleport_back first, or use a device path.`,
     };
   }
-  const located = getVfs().locate(address);
-  if (!located.ok) {
-    return {
-      kind: "error",
-      text: `Cannot resolve ${address}: ${located.error}${located.detail ? ` — ${located.detail}` : ""}`,
-    };
+  const resolved = resolveNamespacePath(
+    address,
+    getVfs(),
+    isNamespaceFsMounted(),
+  );
+  return resolved.ok ? { path: resolved.path } : { error: resolved.error };
+}
+
+/** Expand a leading `~` — local runs only; a device's home is not ours. */
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+/**
+ * One rule for every path parameter: talon:// translates, `~` expands
+ * (locally), everything else passes through untouched.
+ */
+function resolvePathParam(
+  path: string,
+  teleportedTo: string | undefined,
+): { path: string } | { error: string } {
+  if (path.startsWith(NAMESPACE_SCHEME)) {
+    return resolveAddress(path, teleportedTo);
   }
-  return located.value === undefined
-    ? { kind: "virtual" }
-    : { kind: "disk", path: located.value };
+  return { path: teleportedTo !== undefined ? path : expandHome(path) };
 }
 
-/** glob/search root: a talon:// address must name a disk-backed directory. */
+/** glob/search root — same rule, defaulting to the working directory. */
 function resolveSearchRoot(
   path: string | undefined,
   teleportedTo: string | undefined,
 ): { root: string } | { error: string } {
-  const root = path ?? ".";
-  if (!root.startsWith(NAMESPACE_SCHEME)) return { root };
-  const resolved = resolveNamespaceAddress(root, teleportedTo);
-  if (resolved.kind === "error") return { error: resolved.text };
-  if (resolved.kind === "virtual") {
-    return {
-      error: `${root} is a synthetic view with no files on disk — browse it with vfs_list instead.`,
-    };
-  }
-  return { root: resolved.path };
+  const resolved = resolvePathParam(path ?? ".", teleportedTo);
+  return "error" in resolved ? resolved : { root: resolved.path };
 }
 
 // ── read / write / edit ─────────────────────────────────────────────────────
@@ -520,33 +566,15 @@ async function read(
   const active = await getTeleport(chatId);
   const where = active ? active.deviceName : "local";
 
-  let p = address;
-  let virtualContent: string | undefined;
-  if (address.startsWith(NAMESPACE_SCHEME)) {
-    const resolved = resolveNamespaceAddress(address, active?.deviceName);
-    if (resolved.kind === "error") return { ok: false, text: resolved.text };
-    if (resolved.kind === "disk") {
-      p = resolved.path;
-    } else {
-      const served = getVfs().read(address);
-      if (!served.ok) {
-        return {
-          ok: false,
-          text: `Cannot read ${address}: ${served.error}${served.detail ? ` — ${served.detail}` : ""}`,
-        };
-      }
-      virtualContent = served.value;
-    }
-  }
+  const resolved = resolvePathParam(address, active?.deviceName);
+  if ("error" in resolved) return { ok: false, text: resolved.error };
+  const p = resolved.path;
   const shown = p === address ? p : `${address} → ${p}`;
 
   // Image files: return a viewable image block, not the raw bytes decoded as
   // UTF-8. Without this, `read`ing a photo/screenshot/design hands the model
   // mojibake and it can't see the picture at all.
-  const mime =
-    virtualContent === undefined
-      ? IMAGE_MIME[extname(p).toLowerCase()]
-      : undefined;
+  const mime = IMAGE_MIME[extname(p).toLowerCase()];
   if (mime) {
     let bytes: Buffer;
     if (active) {
@@ -582,9 +610,7 @@ async function read(
   const start = num(offset) ?? 0;
   const max = Math.min(num(limit) ?? MAX_READ_LINES, MAX_READ_LINES);
   let content: string;
-  if (virtualContent !== undefined) {
-    content = virtualContent;
-  } else if (active) {
+  if (active) {
     const res = await getMeshService().readFileBytes(active.deviceId, p);
     if ("error" in res) return { ok: false, text: res.error };
     content = res.data.toString("utf8");
@@ -622,18 +648,9 @@ async function write(
   if (!address) return { ok: false, text: "A file path is required." };
   const body = typeof content === "string" ? content : "";
   const active = await getTeleport(chatId);
-  let p = address;
-  if (address.startsWith(NAMESPACE_SCHEME)) {
-    const resolved = resolveNamespaceAddress(address, active?.deviceName);
-    if (resolved.kind === "error") return { ok: false, text: resolved.text };
-    if (resolved.kind === "virtual") {
-      return {
-        ok: false,
-        text: `${address} is a synthetic view — there is no file on disk to write. Writable mounts: vfs_list "" shows where each lives.`,
-      };
-    }
-    p = resolved.path;
-  }
+  const resolved = resolvePathParam(address, active?.deviceName);
+  if ("error" in resolved) return { ok: false, text: resolved.error };
+  const p = resolved.path;
   const shown = p === address ? p : `${address} → ${p}`;
   if (active) {
     return getMeshService().writeFileToDevice(active.deviceId, p, body);
@@ -664,18 +681,9 @@ async function edit(
   if (from === to)
     return { ok: false, text: "old_string and new_string are identical." };
   const active = await getTeleport(chatId);
-  let p = address;
-  if (address.startsWith(NAMESPACE_SCHEME)) {
-    const resolved = resolveNamespaceAddress(address, active?.deviceName);
-    if (resolved.kind === "error") return { ok: false, text: resolved.text };
-    if (resolved.kind === "virtual") {
-      return {
-        ok: false,
-        text: `${address} is a synthetic view — there is no file on disk to edit. Read it with vfs_read instead.`,
-      };
-    }
-    p = resolved.path;
-  }
+  const resolved = resolvePathParam(address, active?.deviceName);
+  if ("error" in resolved) return { ok: false, text: resolved.error };
+  const p = resolved.path;
   const shown = p === address ? p : `${address} → ${p}`;
   const svc = getMeshService();
 

package/src/core/engine/gateway.ts

@@ -414,34 +414,6 @@ export class Gateway {
           return;
         }
 
-        if (
-          req.method === "GET" &&
-          (req.url?.startsWith("/vfs/list") || req.url?.startsWith("/vfs/read"))
-        ) {
-          // The talon:// namespace — the transport for `talon ls` /
-          // `talon cat`, which need the daemon's live synthetic mounts
-          // (proc, plugins). Same 127.0.0.1 trust boundary as /action.
-          const url = new URL(req.url, "http://gateway");
-          const path = url.searchParams.get("path") ?? "";
-          const { getVfs } = await import("../vfs/index.js");
-          const vfs = getVfs();
-          let result: Record<string, unknown>;
-          if (url.pathname === "/vfs/list") {
-            const listed = vfs.list(path);
-            result = listed.ok
-              ? { ok: true, entries: listed.value }
-              : { ok: false, error: listed.error, detail: listed.detail };
-          } else {
-            const content = vfs.read(path);
-            result = content.ok
-              ? { ok: true, content: content.value }
-              : { ok: false, error: content.error, detail: content.detail };
-          }
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify(result));
-          return;
-        }
-
         if (req.method === "GET" && req.url === "/tasks") {
           // The task table — every live/recent unit of agent work. Read by
           // `talon ps`. Same 127.0.0.1 trust boundary as /action.

package/src/core/tools/index.ts

@@ -23,7 +23,6 @@ import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
 import { nativeTools } from "./native.js";
-import { vfsTools } from "./vfs.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -42,7 +41,6 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
   ...modelTools,
   ...meshTools,
-  ...vfsTools,
 ];
 
 /**

package/src/core/tools/native.ts

@@ -10,7 +10,16 @@ import type { ToolDefinition } from "./types.js";
  * Their extra power over the built-ins: every one honours the active
  * `teleport` target, so with a teleport engaged they run ON a companion
  * device (via the mesh exec/fs channel) instead of on the daemon host.
+ * And every one speaks talon:// — Talon's own namespace, which is a real
+ * filesystem location, so addresses translate to legitimate paths.
  */
+
+/** One shared description of the namespace, stated once. */
+const NAMESPACE_DOC =
+  "talon:// is Talon's namespace, on disk at ~/.talon/ns: home/ (the workspace), " +
+  "skills/, scripts/, logs/, and — while the FUSE layer is mounted — the live views " +
+  "proc/ (task table at proc/tasks/<id>, event ring at proc/events, both JSON) and " +
+  "plugins/ (registry).";
 export const nativeTools: ToolDefinition[] = [
   {
     name: "teleport",
@@ -40,14 +49,14 @@ export const nativeTools: ToolDefinition[] = [
     description:
       "Run a shell command. Runs on the daemon host, or ON the active teleport device if one is engaged. On a teleported device, `cd` persists across calls (a real working-directory session). " +
       "Foreground runs are killed at timeout_sec — for streaming/never-ending commands (adb logcat, tail -f, dev servers, watchers) set background:true instead: the command is launched detached in its own process group with stdout+stderr captured to a log file, and the tool returns immediately with the pid + log path so you can poll the log and kill it when done. " +
-      "talon:// addresses are not OS paths — the shell needs the disk locations the namespace root listing shows (vfs_list).",
+      `${NAMESPACE_DOC} talon:// references in the command are translated to real paths before the shell runs (local only), so \`ls talon://home\` or \`cat talon://proc/events | jq\` just work.`,
     schema: {
       command: z.string().describe("The shell command to run."),
       cwd: z
         .string()
         .optional()
         .describe(
-          "Working directory (local runs only; teleport tracks its own cwd).",
+          "Working directory (local runs only; teleport tracks its own cwd). talon:// accepted.",
         ),
       timeout_sec: z
         .number()
@@ -67,13 +76,12 @@ export const nativeTools: ToolDefinition[] = [
   },
   {
     name: "read",
-    description:
-      "Read a file (with line numbers). Runs on the daemon host or the active teleport device. Supports offset/limit for large files.",
+    description: `Read a file (with line numbers). Runs on the daemon host or the active teleport device. Supports offset/limit for large files. ${NAMESPACE_DOC}`,
     schema: {
       path: z
         .string()
         .describe(
-          "Absolute file path, or a talon:// namespace address (resolved on the daemon host).",
+          "Absolute file path, ~ path, or a talon:// address (translated on the daemon host).",
         ),
       offset: z.number().optional().describe("0-based line to start from."),
       limit: z
@@ -87,12 +95,12 @@ export const nativeTools: ToolDefinition[] = [
   {
     name: "write",
     description:
-      "Write (create/overwrite) a file with the given content. Runs on the daemon host or the active teleport device.",
+      "Write (create/overwrite) a file with the given content. Runs on the daemon host or the active teleport device. Writable talon:// mounts: home/, skills/, scripts/ (live views are read-only).",
     schema: {
       path: z
         .string()
         .describe(
-          "Absolute file path, or a talon:// namespace address (resolved on the daemon host).",
+          "Absolute file path, ~ path, or a talon:// address (translated on the daemon host).",
         ),
       content: z.string().describe("Full file content to write."),
     },
@@ -107,7 +115,7 @@ export const nativeTools: ToolDefinition[] = [
       path: z
         .string()
         .describe(
-          "Absolute file path, or a talon:// namespace address (resolved on the daemon host).",
+          "Absolute file path, ~ path, or a talon:// address (translated on the daemon host).",
         ),
       old_string: z.string().describe("Exact text to replace."),
       new_string: z.string().describe("Replacement text."),

package/src/core/tools/types.ts

@@ -28,8 +28,7 @@ export type ToolTag =
   | "admin"
   | "models"
   | "mesh"
-  | "native"
-  | "vfs";
+  | "native";
 
 /** The bridge caller signature — injected into execute(). */
 export type BridgeFunction = (