talon-agent 1.53.0 → 2.0.0

package/src/native/fusefs.ts

@@ -0,0 +1,97 @@
+/**
+ * talon-fusefs — TypeScript boundary over the FUSE addon
+ * (native/talon-fusefs, `bin/talon-fusefs.node`).
+ *
+ * The addon mounts the talon:// namespace at ~/.talon/ns while the
+ * daemon runs: file-backed mounts are served as symlinks (the kernel
+ * follows them — heavy file I/O never crosses the FUSE boundary) and
+ * synthetic mounts (proc/, plugins/) are served live through a
+ * threadsafe callback bridge into the JS Vfs.
+ *
+ * Per-arch artifact like blake3-napi: present on binary-channel and
+ * source installs, absent otherwise — absence simply means the FUSE
+ * layer is off and the namespace falls back to the symlink farm.
+ * `TALON_FUSEFS_NODE` overrides the location, `TALON_NO_FUSEFS=1`
+ * disables it. Linux-only: fuser's pure-Rust mount path (no libfuse
+ * link) needs only /dev/fuse + fusermount3 at runtime.
+ */
+
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+/** One root symlink entry the mount serves (a file-backed mount). */
+export interface FuseSymlinkSpec {
+  name: string;
+  target: string;
+}
+
+/**
+ * A bridge request from the FUSE thread. Answer by calling `reply(id,
+ * json)` — every request MUST be answered or the kernel caller waits
+ * out the addon's internal timeout and gets EIO. `path` is
+ * namespace-relative ("proc/tasks/7"). The reply JSON shapes are
+ * defined by `serveNamespaceRequest` in core/vfs/fusefs.ts.
+ */
+export type FuseBridgeHandler = (id: number, op: string, path: string) => void;
+
+/** The N-API surface exported by native/talon-fusefs. */
+export interface NativeFuseFs {
+  version(): string;
+  /**
+   * Mount at `mountpoint` and return once the kernel accepted the
+   * mount. Throws when mounting fails (no /dev/fuse, no fusermount,
+   * mountpoint busy). The FUSE session runs on its own thread until
+   * `unmount()`.
+   */
+  mount(
+    mountpoint: string,
+    symlinks: FuseSymlinkSpec[],
+    synthetic: string[],
+    onRequest: FuseBridgeHandler,
+  ): void;
+  /** Answer a bridge request. Unknown/expired ids are ignored. */
+  reply(id: number, json: string): void;
+  /** Tear the mount down. Idempotent. */
+  unmount(): void;
+}
+
+let addon: NativeFuseFs | null | undefined;
+
+/** Resolve the addon, or null when the FUSE layer must stay off. */
+export function nativeFuseFs(): NativeFuseFs | null {
+  if (addon === undefined) addon = loadNativeFuseFs();
+  return addon;
+}
+
+function loadNativeFuseFs(): NativeFuseFs | null {
+  if (process.env.TALON_NO_FUSEFS === "1") return null;
+
+  let candidate = process.env.TALON_FUSEFS_NODE;
+  if (!candidate) {
+    try {
+      // Beside bin/talon.js — where build:fusefs and packaging put it.
+      // Throws under bun single-binary builds (no real fs URL): those
+      // ship through channels that set TALON_FUSEFS_NODE, or fall back.
+      candidate = fileURLToPath(
+        new URL("../../bin/talon-fusefs.node", import.meta.url),
+      );
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const requireAddon = createRequire(import.meta.url);
+    const loaded = requireAddon(candidate) as NativeFuseFs;
+    // Trust nothing that can't state its version — a truncated or
+    // wrong-arch artifact fails here and the FUSE layer stays off.
+    if (typeof loaded.version() !== "string") return null;
+    return loaded;
+  } catch {
+    return null;
+  }
+}
+
+/** Tests swap addons via TALON_FUSEFS_NODE and need the memo dropped. */
+export function _resetNativeFuseFsForTesting(): void {
+  addon = undefined;
+}

package/src/util/config.ts

@@ -479,6 +479,14 @@ const configSchema = z.object({
   // and restart), with an instant rollback by flipping back to false.
   nativeTools: z.boolean().default(false),
 
+  // FUSE layer for the talon:// namespace (~/.talon/ns). "auto" mounts the
+  // live views (proc/, plugins/) when the host can (Linux, /dev/fuse, the
+  // talon-fusefs addon present) and degrades to the plain symlink farm with a
+  // logged reason when it can't — fuseless hosts get the identical namespace
+  // minus live views. "off" never mounts. There is no "force": a mount that
+  // can't come up healthy is always rolled back rather than half-served.
+  fuse: z.enum(["auto", "off"]).default("auto"),
+
   // Display name shown in terminal UI (defaults to "Talon")
   botDisplayName: z.string().default("Talon"),
 

package/src/util/log.ts

@@ -48,6 +48,7 @@ export type LogComponent =
   | "heartbeat"
   | "dispatcher"
   | "gateway"
+  | "fusefs"
   | "plugin"
   | "teams"
   | "discord"

package/src/util/paths.ts

@@ -72,6 +72,13 @@ export const dirs = {
   skills: resolve(TALON_ROOT, "workspace", "skills"),
   /** Key material (bridge TLS identity, release keys): ~/.talon/keys/ */
   keys: resolve(TALON_ROOT, "keys"),
+  /**
+   * The talon:// namespace on disk: ~/.talon/ns/. Holds one symlink per
+   * file-backed mount (home → workspace/, skills/, …); while the daemon
+   * runs with FUSE the synthetic mounts (proc/, plugins/) appear here too.
+   * `talon://x` and `~/.talon/ns/x` are the same address in two spellings.
+   */
+  ns: resolve(TALON_ROOT, "ns"),
   /** CLI-installed plugins (`talon plugin install`): ~/.talon/plugins/ */
   plugins: resolve(TALON_ROOT, "plugins"),
 } as const;

package/src/cli/fs.ts

@@ -1,138 +0,0 @@
-/**
- * `talon ls` / `talon cat` — the talon:// namespace from the outside.
- *
- * A running daemon answers through the gateway (`GET /vfs/list|read`) so
- * the synthetic mounts (proc, plugins) show live state. With no daemon,
- * the same namespace is served in-process — file mounts work identically,
- * the synthetic mounts are simply empty — so browsing the workspace never
- * requires Talon to be up.
- */
-
-import pc from "picocolors";
-import { findRunningInstance } from "../core/daemon/discovery.js";
-import type { VfsErrorCode, VfsResult, VfsStat } from "../core/vfs/index.js";
-import { fetchGateway } from "./daemon-api.js";
-
-/**
- * Ask the daemon first (live proc/plugins state), fall back to serving the
- * namespace in-process. `live` records which one answered.
- */
-async function query(
-  op: "list" | "read",
-  path: string,
-): Promise<{ result: VfsResult<VfsStat[] | string>; live: boolean }> {
-  const instance = await findRunningInstance();
-  if (instance?.port) {
-    const body = (await fetchGateway(
-      instance.port,
-      `/vfs/${op}?path=${encodeURIComponent(path)}`,
-    )) as {
-      ok: boolean;
-      entries?: VfsStat[];
-      content?: string;
-      error?: string;
-      detail?: string;
-    };
-    const result: VfsResult<VfsStat[] | string> = body.ok
-      ? { ok: true, value: op === "list" ? body.entries! : body.content! }
-      : {
-          ok: false,
-          error: (body.error ?? "io-error") as VfsErrorCode,
-          ...(body.detail !== undefined ? { detail: body.detail } : {}),
-        };
-    return { result, live: true };
-  }
-
-  const { getVfs } = await import("../core/vfs/index.js");
-  const vfs = getVfs();
-  return {
-    result: op === "list" ? vfs.list(path) : vfs.read(path),
-    live: false,
-  };
-}
-
-function printError(
-  path: string,
-  result: { error: string; detail?: string },
-): void {
-  console.error(
-    `  ${pc.red("✖")} talon://${path}: ${result.error}${result.detail ? ` — ${result.detail}` : ""}`,
-  );
-  process.exitCode = 1;
-}
-
-function formatModified(entry: VfsStat): string {
-  if (entry.modifiedAt === undefined) return "-";
-  return new Date(entry.modifiedAt)
-    .toISOString()
-    .slice(0, 16)
-    .replace("T", " ");
-}
-
-export async function showLs(rawPath: string | undefined): Promise<void> {
-  const path = (rawPath ?? "").trim();
-  console.log();
-  const { result, live } = await query("list", path);
-  if (!result.ok) {
-    printError(path, result);
-    return;
-  }
-  const entries = result.value as VfsStat[];
-
-  if (!live) {
-    console.log(
-      `  ${pc.dim("Talon is not running — file mounts only; proc/ and plugins/ are empty.")}`,
-    );
-  }
-  if (entries.length === 0) {
-    console.log(`  ${pc.dim("(empty)")}\n`);
-    return;
-  }
-
-  const header = ["KIND", "SIZE", "MODIFIED", "NAME"];
-  const cells = entries.map((entry) => [
-    entry.kind === "dir" ? "dir" : "file",
-    entry.kind === "dir" ? "-" : String(entry.size ?? "?"),
-    formatModified(entry),
-    entry.kind === "dir" ? `${entry.name}/` : entry.name,
-  ]);
-  const widths = header.map((h, col) =>
-    Math.max(h.length, ...cells.map((row) => row[col]!.length)),
-  );
-  console.log(
-    `  ${pc.dim(header.map((h, col) => h.padEnd(widths[col]!)).join("  "))}`,
-  );
-  cells.forEach((row, i) => {
-    const padded = row.map((cell, col) => cell.padEnd(widths[col]!));
-    const name = entries[i]!.kind === "dir" ? pc.cyan(padded[3]!) : padded[3]!;
-    // Root entries carry the mount's disk location — show the mapping, it's
-    // what shell commands (which can't read talon://) need.
-    const entry = entries[i]!;
-    const mapping =
-      entry.osPath !== undefined && !entry.path.includes("/")
-        ? pc.dim(`  → ${entry.osPath}`)
-        : "";
-    console.log(
-      `  ${padded[0]}  ${padded[1]}  ${padded[2]}  ${name}${mapping}`,
-    );
-  });
-  console.log();
-}
-
-export async function showCat(rawPath: string | undefined): Promise<void> {
-  if (!rawPath || !rawPath.trim()) {
-    console.error(
-      `  ${pc.red("✖")} Usage: ${pc.cyan("talon cat <path>")} — e.g. ${pc.cyan("talon cat proc/events")}`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const path = rawPath.trim();
-  const { result } = await query("read", path);
-  if (!result.ok) {
-    printError(path, result);
-    return;
-  }
-  // Raw content, no decoration — `talon cat x | jq` must work.
-  process.stdout.write(result.value as string);
-}

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

@@ -1,69 +0,0 @@
-/**
- * VFS — the `talon://` namespace over the gateway: list / read / write.
- * Formatting only; the namespace itself lives in core/vfs.
- */
-
-import { getVfs, type VfsResult, type VfsStat } from "../../vfs/index.js";
-import { log } from "../../../util/log.js";
-import type { SharedActionHandlers } from "./types.js";
-
-function describeError(
-  path: string,
-  result: { error: string; detail?: string },
-): string {
-  return `talon://${path}: ${result.error}${result.detail ? ` — ${result.detail}` : ""}`;
-}
-
-function formatSize(entry: VfsStat): string {
-  return entry.kind === "dir" ? "-" : String(entry.size ?? "?");
-}
-
-function formatEntry(entry: VfsStat): string {
-  const kind = entry.kind === "dir" ? "d" : "-";
-  const write = entry.writable ? "w" : "-";
-  const suffix = entry.kind === "dir" ? "/" : "";
-  // Root entries (single-segment paths) show where the mount lives on
-  // disk — the bridge for OS-level tools, which can't read talon://.
-  const mapping =
-    entry.osPath !== undefined && !entry.path.includes("/")
-      ? `  → ${entry.osPath}`
-      : "";
-  return `${kind}${write} ${formatSize(entry).padStart(9)}  ${entry.name}${suffix}${mapping}`;
-}
-
-function normalize(body: Record<string, unknown>): string {
-  return String(body.path ?? "").trim();
-}
-
-export const vfsHandlers: SharedActionHandlers = {
-  vfs_list: (body) => {
-    const path = normalize(body);
-    const result = getVfs().list(path);
-    if (!result.ok) return { ok: false, error: describeError(path, result) };
-    const header = `talon://${path.replace(/\/+$/, "")}${path ? "/" : ""} (${result.value.length} entries)`;
-    const lines = result.value.map(formatEntry);
-    return {
-      ok: true,
-      text: [header, ...(lines.length > 0 ? lines : ["(empty)"])].join("\n"),
-    };
-  },
-
-  vfs_read: (body) => {
-    const path = normalize(body);
-    const result = getVfs().read(path);
-    if (!result.ok) return { ok: false, error: describeError(path, result) };
-    return { ok: true, text: result.value };
-  },
-
-  vfs_write: (body) => {
-    const path = normalize(body);
-    const content = String(body.content ?? "");
-    const result: VfsResult<VfsStat> = getVfs().write(path, content);
-    if (!result.ok) return { ok: false, error: describeError(path, result) };
-    log("gateway", `vfs_write: talon://${result.value.path}`);
-    return {
-      ok: true,
-      text: `Wrote ${result.value.size ?? content.length} bytes to talon://${result.value.path}`,
-    };
-  },
-};

package/src/core/tools/vfs.ts

@@ -1,61 +0,0 @@
-/**
- * VFS tools — the unified `talon://` namespace.
- *
- * One browsable tree over everything the daemon owns: real stores (the
- * workspace, skills, scripts, logs) and live synthetic state (`proc/` for
- * the task table and event bus, `plugins/` for the registry) answer the
- * same three tools. The synthetic mounts are the point — this is the only
- * way to read live daemon state as plain files.
- */
-
-import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
-
-const NAMESPACE = `Namespace roots: home/ (workspace), skills/, scripts/, logs/, proc/ (live task table under proc/tasks/<id> and the event ring at proc/events), plugins/ (registry view). List "" to see the root and where each mount lives on disk. Absolute OS paths inside a mounted directory are accepted and translated.`;
-
-export const vfsTools: ToolDefinition[] = [
-  {
-    name: "vfs_list",
-    description: `List a directory in the talon:// namespace — the unified view over Talon's own state. ${NAMESPACE} Entries show kind (d/-), writability, size, and name.`,
-    schema: {
-      path: z
-        .string()
-        .describe(
-          'Namespace path, e.g. "" (root), "proc/tasks", "skills/review-pr". Forward slashes on every platform; "talon://" prefix optional.',
-        ),
-    },
-    execute: (params, bridge) => bridge("vfs_list", params),
-    tag: "vfs",
-  },
-
-  {
-    name: "vfs_read",
-    description: `Read a file from the talon:// namespace (UTF-8 text, 256KB cap). ${NAMESPACE} Reading proc/tasks/<id> returns that task as JSON; proc/events returns the event ring as JSON Lines.`,
-    schema: {
-      path: z
-        .string()
-        .describe(
-          'Namespace file path, e.g. "proc/events" or "logs/2026-07-16.md"',
-        ),
-    },
-    execute: (params, bridge) => bridge("vfs_read", params),
-    tag: "vfs",
-  },
-
-  {
-    name: "vfs_write",
-    description: `Write a UTF-8 file into a writable part of the talon:// namespace (home/, skills/, scripts/). Parent directories are created; synthetic mounts (proc/, plugins/) and logs/ are read-only views.`,
-    schema: {
-      path: z
-        .string()
-        .describe(
-          'Namespace file path under a writable mount, e.g. "home/notes/ideas.md"',
-        ),
-      content: z
-        .string()
-        .describe("Full file content (replaces any existing content)"),
-    },
-    execute: (params, bridge) => bridge("vfs_write", params),
-    tag: "vfs",
-  },
-];