talon-agent 1.53.0 → 2.0.0

package/src/core/vfs/fusefs.ts

@@ -0,0 +1,269 @@
+/**
+ * FUSE layer lifecycle — mounts the talon:// namespace at ~/.talon/ns
+ * while the daemon runs.
+ *
+ * The mount serves symlinks for file-backed mounts (kernel-followed, so
+ * heavy I/O never crosses FUSE) and answers synthetic subtrees (proc/,
+ * plugins/) live from the JS Vfs over the addon's callback bridge. When
+ * anything is missing — config off, addon absent, no /dev/fuse, mount
+ * or sanity check fails — the layer degrades to the plain symlink farm
+ * and records why: fuseless hosts get the identical experience minus
+ * live views, never an error at boot.
+ *
+ * Deadlock rule: the daemon must never do SYNCHRONOUS fs I/O under
+ * ~/.talon/ns — a sync call blocks the one JS thread that answers the
+ * bridge, wedging both sides. Async fs is safe (libuv worker blocks,
+ * the event loop answers), and child/external processes are always
+ * safe. The bridge handler itself only touches in-memory synthetic
+ * mounts, keeping replies non-blocking by construction.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { log, logWarn } from "../../util/log.js";
+import { dirs } from "../../util/paths.js";
+import type { NativeFuseFs } from "../../native/fusefs.js";
+import { nativeFuseFs } from "../../native/fusefs.js";
+import { syncNamespaceDir } from "./nsdir.js";
+import type { VfsErrorCode } from "./types.js";
+import type { Vfs } from "./vfs.js";
+
+export type FuseStatus = {
+  readonly mounted: boolean;
+  /** Why the layer is off — set exactly when `mounted` is false. */
+  readonly reason?: string;
+};
+
+/** How long a post-mount sanity probe may take before we bail out. */
+const SANITY_TIMEOUT_MS = 3_000;
+
+let status: FuseStatus = { mounted: false, reason: "not started" };
+let activeAddon: NativeFuseFs | null = null;
+
+/** Is the FUSE layer live? Consulted by the address/command resolvers. */
+export function isNamespaceFsMounted(): boolean {
+  return status.mounted;
+}
+
+/** Current layer status, for doctor/status surfaces. */
+export function namespaceFsStatus(): FuseStatus {
+  return status;
+}
+
+/** Test seam — force a status without a real mount. */
+export function _setNamespaceFsStatusForTesting(next: FuseStatus): void {
+  status = next;
+}
+
+// ── Bridge: FUSE thread → JS Vfs ─────────────────────────────────────────────
+
+const ERRNO: Record<VfsErrorCode, string> = {
+  "not-found": "ENOENT",
+  "invalid-path": "ENOENT",
+  "is-a-directory": "EISDIR",
+  "not-a-directory": "ENOTDIR",
+  "not-writable": "EROFS",
+  "too-large": "EFBIG",
+  "binary-file": "EIO",
+  "io-error": "EIO",
+};
+
+/**
+ * Answer one bridge request. Pure Vfs → JSON: `path` is
+ * namespace-relative ("proc/tasks/7"); ops are stat / list / read.
+ * Never throws — every failure becomes an errno reply, because an
+ * unanswered request strands a kernel caller until the addon times it
+ * out.
+ */
+export function serveNamespaceRequest(
+  vfs: Vfs,
+  op: string,
+  path: string,
+): string {
+  try {
+    const address = `talon://${path}`;
+    if (op === "stat") {
+      const result = vfs.stat(address);
+      if (!result.ok) return errno(result.error);
+      return JSON.stringify({
+        ok: true,
+        kind: result.value.kind,
+        size: result.value.size ?? 0,
+        mtimeMs: result.value.modifiedAt ?? 0,
+      });
+    }
+    if (op === "list") {
+      const result = vfs.list(address);
+      if (!result.ok) return errno(result.error);
+      return JSON.stringify({
+        ok: true,
+        entries: result.value.map((entry) => ({
+          name: entry.name,
+          kind: entry.kind,
+        })),
+      });
+    }
+    if (op === "read") {
+      const result = vfs.read(address);
+      if (!result.ok) return errno(result.error);
+      return JSON.stringify({
+        ok: true,
+        data: Buffer.from(result.value, "utf-8").toString("base64"),
+      });
+    }
+    return errno("io-error");
+  } catch {
+    return JSON.stringify({ ok: false, errno: "EIO" });
+  }
+}
+
+function errno(code: VfsErrorCode): string {
+  return JSON.stringify({ ok: false, errno: ERRNO[code] });
+}
+
+// ── Mount lifecycle ──────────────────────────────────────────────────────────
+
+export interface MountOptions {
+  /** `config.fuse` — "auto" mounts when possible, "off" never mounts. */
+  mode: "auto" | "off";
+  vfs: Vfs;
+  /** Test seams; production callers omit them. */
+  nsRoot?: string;
+  addon?: NativeFuseFs | null;
+}
+
+/**
+ * Bring the FUSE layer up if this host can. Never throws: every failure
+ * path lands in `{ mounted: false, reason }` with the symlink farm
+ * already synced, so the fuseless experience is intact regardless.
+ */
+export async function mountNamespaceFs(
+  options: MountOptions,
+): Promise<FuseStatus> {
+  const nsRoot = options.nsRoot ?? dirs.ns;
+  await recoverStaleMount(nsRoot);
+  try {
+    syncNamespaceDir(options.vfs, nsRoot);
+  } catch (err) {
+    return down(`namespace dir sync failed: ${message(err)}`);
+  }
+
+  if (options.mode === "off") return down('disabled (config fuse: "off")');
+  if (process.platform !== "linux") {
+    return down("FUSE layer is Linux-only for now");
+  }
+  if (!existsSync("/dev/fuse")) return down("/dev/fuse not present");
+
+  const addon = options.addon !== undefined ? options.addon : nativeFuseFs();
+  if (!addon) return down("talon-fusefs addon not available");
+
+  const synthetic = options.vfs
+    .describeMounts()
+    .filter((mount) => mount.osRoot === undefined)
+    .map((mount) => mount.name);
+  const symlinks = options.vfs
+    .describeMounts()
+    .filter((mount) => mount.osRoot !== undefined)
+    .map((mount) => ({ name: mount.name, target: mount.osRoot! }));
+
+  try {
+    addon.mount(nsRoot, symlinks, synthetic, (id, op, path) => {
+      addon.reply(id, serveNamespaceRequest(options.vfs, op, path));
+    });
+  } catch (err) {
+    return down(`mount failed: ${message(err)}`);
+  }
+  activeAddon = addon;
+
+  // Sanity: the mount must actually answer before we advertise it.
+  // Async fs only — see the deadlock rule in the module doc.
+  const probe = synthetic[0];
+  const healthy = await withTimeout(
+    (async () => {
+      const entries = await readdir(nsRoot);
+      if (probe !== undefined && !entries.includes(probe)) return false;
+      if (probe !== undefined) {
+        if (!(await stat(`${nsRoot}/${probe}`)).isDirectory()) return false;
+      }
+      return true;
+    })(),
+    SANITY_TIMEOUT_MS,
+  );
+  if (healthy !== true) {
+    await unmountNamespaceFs();
+    // The failed mount may have shadowed the symlink farm — restore it.
+    try {
+      syncNamespaceDir(options.vfs, nsRoot);
+    } catch {
+      // best effort; the boot log already carries the real failure
+    }
+    return down(
+      healthy === false
+        ? "mount sanity check failed (synthetic mounts not visible)"
+        : `mount sanity check timed out after ${SANITY_TIMEOUT_MS}ms`,
+    );
+  }
+
+  status = { mounted: true };
+  log("fusefs", `talon:// namespace mounted at ${nsRoot}`);
+  return status;
+}
+
+/** Tear the layer down (daemon shutdown). Never throws, idempotent. */
+export async function unmountNamespaceFs(): Promise<void> {
+  const addon = activeAddon;
+  activeAddon = null;
+  if (status.mounted) status = { mounted: false, reason: "unmounted" };
+  if (!addon) return;
+  try {
+    addon.unmount();
+  } catch (err) {
+    logWarn("fusefs", `unmount failed: ${message(err)}`);
+  }
+}
+
+/**
+ * A daemon that died without unmounting leaves the mountpoint wedged —
+ * every syscall answers ENOTCONN ("transport endpoint is not
+ * connected") until someone detaches it. A predecessor that is alive
+ * but not answering is worse: its mount HANGS syscalls instead, so the
+ * probe itself carries a timeout and a hang counts as stale. Detect
+ * and lazy-unmount before touching the directory.
+ */
+async function recoverStaleMount(nsRoot: string): Promise<void> {
+  const probe = await withTimeout(
+    stat(nsRoot).then(
+      () => "ok" as const,
+      (err) => (err as NodeJS.ErrnoException).code ?? "error",
+    ),
+    SANITY_TIMEOUT_MS,
+  );
+  if (probe !== "ENOTCONN" && probe !== "timeout") return;
+  logWarn("fusefs", `stale mount at ${nsRoot} — detaching`);
+  for (const bin of ["fusermount3", "fusermount"]) {
+    const result = spawnSync(bin, ["-uz", nsRoot], { stdio: "ignore" });
+    if (result.status === 0) return;
+  }
+  spawnSync("umount", ["-l", nsRoot], { stdio: "ignore" });
+}
+
+function down(reason: string): FuseStatus {
+  status = { mounted: false, reason };
+  log("fusefs", `FUSE layer off — ${reason}`);
+  return status;
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function withTimeout<T>(work: Promise<T>, ms: number): Promise<T | "timeout"> {
+  return Promise.race([
+    work,
+    new Promise<"timeout">((resolve) => {
+      const timer = setTimeout(() => resolve("timeout"), ms);
+      timer.unref();
+    }),
+  ]);
+}

package/src/core/vfs/index.ts

@@ -15,8 +15,11 @@
  *     proc/       task table + event bus ring (synthetic, read-only)
  *     plugins/    plugin registry view (synthetic, read-only)
  *
- * Read surfaces: gateway `GET /vfs/list` / `GET /vfs/read` and the
- * vfs_* MCP tools (via gateway actions); CLI `talon ls` / `talon cat`.
+ * The namespace IS the filesystem: it lives at ~/.talon/ns (symlink
+ * farm via nsdir.ts, live synthetic mounts via fusefs.ts when FUSE is
+ * available), and every consumer — native tools, shell commands, the
+ * user's own terminal — reaches it through real paths. Address
+ * translation for tools lives in rewrite.ts.
  */
 
 import { dirs } from "../../util/paths.js";
@@ -32,6 +35,22 @@ export { Vfs } from "./vfs.js";
 export { createFileMount } from "./mounts/files.js";
 export { createProcMount, type ProcMountDeps } from "./mounts/proc.js";
 export { createPluginsMount, type PluginView } from "./mounts/plugins.js";
+export { syncNamespaceDir, type NsDirSync } from "./nsdir.js";
+export {
+  resolveNamespacePath,
+  rewriteNamespaceRefs,
+  type CommandRewrite,
+  type PathResolution,
+} from "./rewrite.js";
+export {
+  isNamespaceFsMounted,
+  mountNamespaceFs,
+  namespaceFsStatus,
+  serveNamespaceRequest,
+  unmountNamespaceFs,
+  type FuseStatus,
+  type MountOptions,
+} from "./fusefs.js";
 export type {
   VfsErrorCode,
   VfsMount,

package/src/core/vfs/nsdir.ts

@@ -0,0 +1,85 @@
+/**
+ * The namespace on disk — ~/.talon/ns/, the OS spelling of talon://.
+ *
+ * One symlink per file-backed mount (home → workspace/, skills/, …), so
+ * `talon://` ↔ `~/.talon/ns/` is a pure prefix substitution: any shell
+ * command, editor, or external tool reaches namespace nodes through
+ * ordinary paths. Synthetic mounts (proc/, plugins/) are NOT represented
+ * here — they exist only while the FUSE layer (core/vfs/fusefs.ts) is
+ * mounted over this directory, exactly like /proc appearing at boot.
+ *
+ * The sync is idempotent and owns only symlinks: stale or retargeted
+ * links it created are replaced, anything that isn't a symlink is left
+ * untouched and reported rather than deleted.
+ */
+
+import {
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { dirs } from "../../util/paths.js";
+import type { Vfs } from "./vfs.js";
+
+export interface NsDirSync {
+  /** Symlinks created or retargeted this pass (mount names). */
+  readonly linked: string[];
+  /** Stale symlinks removed (no longer a mount, or wrong target). */
+  readonly pruned: string[];
+  /** Entries skipped because they aren't symlinks we own. */
+  readonly foreign: string[];
+}
+
+/**
+ * Bring ~/.talon/ns/ (or `nsRoot`) in line with the mount table. Safe to
+ * call repeatedly; called at daemon boot before the FUSE layer mounts
+ * over the directory. Mount targets are created if missing so the links
+ * are never dangling — workspace directories appear lazily elsewhere too.
+ */
+export function syncNamespaceDir(
+  vfs: Vfs,
+  nsRoot: string = dirs.ns,
+): NsDirSync {
+  mkdirSync(nsRoot, { recursive: true });
+  const desired = new Map(
+    vfs
+      .describeMounts()
+      .filter((mount) => mount.osRoot !== undefined)
+      .map((mount) => [mount.name, mount.osRoot!]),
+  );
+
+  const linked: string[] = [];
+  const pruned: string[] = [];
+  const foreign: string[] = [];
+
+  for (const entry of readdirSync(nsRoot)) {
+    const path = `${nsRoot}/${entry}`;
+    if (!lstatSync(path).isSymbolicLink()) {
+      foreign.push(entry);
+      // A foreign entry shadowing a mount name wins — we never delete
+      // what we didn't create, so don't try to link over it either.
+      desired.delete(entry);
+      continue;
+    }
+    const target = desired.get(entry);
+    if (target !== undefined && readlinkSync(path) === target) {
+      desired.delete(entry); // already correct
+      continue;
+    }
+    rmSync(path);
+    if (target === undefined) pruned.push(entry);
+  }
+
+  for (const [name, target] of desired) {
+    mkdirSync(target, { recursive: true });
+    // "dir" matters only on Windows (junction-style resolution); ignored
+    // elsewhere.
+    symlinkSync(target, `${nsRoot}/${name}`, "dir");
+    linked.push(name);
+  }
+
+  return { linked, pruned, foreign };
+}

package/src/core/vfs/rewrite.ts

@@ -0,0 +1,170 @@
+/**
+ * talon:// → real path translation — the seam that makes the namespace
+ * seamless for OS-level tools.
+ *
+ * Because the namespace exists on disk (~/.talon/ns/, see nsdir.ts and
+ * fusefs.ts), translating an address is pure prefix substitution — no
+ * tokenizing, no quoting rules, correct anywhere in a command string:
+ *
+ *   FUSE mounted   talon://           →  ~/.talon/ns/           (total)
+ *   fuseless       talon://home/x     →  <workspace>/x          (per mount)
+ *                  talon://           →  ~/.talon/ns            (symlink farm)
+ *                  talon://proc/x     →  refused — live views exist only
+ *                                        while the FUSE layer is mounted
+ *
+ * Two consumers: `resolveNamespacePath` for a single address parameter
+ * (read/write/edit/glob/search), `rewriteNamespaceRefs` for a whole
+ * shell command (bash). Both return real host paths that ordinary fs
+ * code and child processes use with no further special-casing.
+ */
+
+import { dirs } from "../../util/paths.js";
+import type { Vfs } from "./vfs.js";
+
+const SCHEME = "talon://";
+
+/** Chars that can continue a mount name — used as a replace boundary. */
+const MOUNT_NAME = /^[a-z0-9-]+/;
+
+export type PathResolution =
+  { ok: true; path: string } | { ok: false; error: string };
+
+export type CommandRewrite =
+  | { ok: true; command: string; mappings: string[] }
+  | { ok: false; error: string };
+
+function lockedError(name: string): string {
+  return (
+    `talon://${name} is a live view that only exists while the FUSE layer is ` +
+    `mounted, and it isn't mounted on this host (config \`fuse: "off"\`, ` +
+    `missing talon-fusefs addon, or no FUSE support). File-backed mounts ` +
+    `under ${dirs.ns} keep working.`
+  );
+}
+
+function unknownMountError(name: string, vfs: Vfs): string {
+  const mounts = vfs
+    .describeMounts()
+    .map((mount) => mount.name)
+    .join(", ");
+  return `No mount "${name}" in the talon:// namespace — mounts: ${mounts}`;
+}
+
+function isSynthetic(name: string, vfs: Vfs): boolean {
+  return vfs
+    .describeMounts()
+    .some((mount) => mount.name === name && mount.osRoot === undefined);
+}
+
+/**
+ * Resolve one talon:// address to the real host path it names. The
+ * caller has already checked the scheme prefix. With FUSE mounted every
+ * address maps into the mountpoint; fuseless, file-backed mounts map to
+ * their disk roots and live views are refused (they don't exist).
+ */
+export function resolveNamespacePath(
+  address: string,
+  vfs: Vfs,
+  fuseMounted: boolean,
+  nsRoot: string = dirs.ns,
+): PathResolution {
+  const rest = address.slice(SCHEME.length).replace(/^\/+/, "");
+  if (rest === "") return { ok: true, path: nsRoot };
+  if (fuseMounted) return { ok: true, path: `${nsRoot}/${rest}` };
+
+  const name = MOUNT_NAME.exec(rest)?.[0] ?? "";
+  if (isSynthetic(name, vfs)) return { ok: false, error: lockedError(name) };
+
+  const located = vfs.locate(address);
+  if (!located.ok) {
+    return {
+      ok: false,
+      error: `Cannot resolve ${address}: ${located.error}${located.detail ? ` — ${located.detail}` : ""}`,
+    };
+  }
+  if (located.value === undefined) {
+    // A mount the table knows but has no disk root and isn't flagged
+    // synthetic can't exist; treat as locked for the same honest reason.
+    return { ok: false, error: lockedError(name) };
+  }
+  return { ok: true, path: located.value };
+}
+
+/**
+ * Translate every talon:// reference in a shell command to its real
+ * path, so `ls talon://home | head` runs untouched by any namespace
+ * plumbing. Returns the applied mappings for the tool result, so the
+ * translation is visible rather than silent.
+ */
+export function rewriteNamespaceRefs(
+  command: string,
+  vfs: Vfs,
+  fuseMounted: boolean,
+  nsRoot: string = dirs.ns,
+): CommandRewrite {
+  if (!command.includes("talon:")) {
+    return { ok: true, command, mappings: [] };
+  }
+  // Near-miss schemes that are unambiguously typos get corrected rather
+  // than letting the shell chase a path that never existed: the
+  // single-slash form (talon:/x), and talon:<name> when <name> is a real
+  // mount. Anything else containing "talon:" (a grep pattern, a log tag)
+  // passes through untouched.
+  const nearMiss =
+    /talon:\/(?!\/)([a-z0-9-][^\s'"`]*)/.exec(command) ??
+    /talon:(?!\/)([a-z0-9-]+)/.exec(command);
+  if (nearMiss) {
+    const rest = nearMiss[1]!;
+    const name = MOUNT_NAME.exec(rest)?.[0] ?? "";
+    const known = vfs.describeMounts().some((mount) => mount.name === name);
+    if (nearMiss[0].startsWith("talon:/") || known) {
+      return {
+        ok: false,
+        error: `"${nearMiss[0]}" is not an address — spell it ${SCHEME}${rest}`,
+      };
+    }
+  }
+  if (!command.includes(SCHEME)) {
+    return { ok: true, command, mappings: [] };
+  }
+
+  if (fuseMounted) {
+    return {
+      ok: true,
+      command: command.split(SCHEME).join(`${nsRoot}/`),
+      mappings: [`talon:// → ${nsRoot}/`],
+    };
+  }
+
+  let rewritten = command;
+  const mappings: string[] = [];
+  const mounts = vfs
+    .describeMounts()
+    .filter((mount) => mount.osRoot !== undefined)
+    .sort((a, b) => b.name.length - a.name.length);
+  for (const mount of mounts) {
+    const ref = new RegExp(`talon://${mount.name}(?![a-z0-9-])`, "g");
+    if (ref.test(rewritten)) {
+      rewritten = rewritten.replace(ref, mount.osRoot!);
+      mappings.push(`talon://${mount.name} → ${mount.osRoot}`);
+    }
+  }
+
+  const residual = /talon:\/\/([a-z0-9-]+)/.exec(rewritten);
+  if (residual) {
+    const name = residual[1]!;
+    return {
+      ok: false,
+      error: isSynthetic(name, vfs)
+        ? lockedError(name)
+        : unknownMountError(name, vfs),
+    };
+  }
+
+  // Bare talon:// (the namespace root) — the symlink farm is always there.
+  if (rewritten.includes(SCHEME)) {
+    rewritten = rewritten.split(SCHEME).join(`${nsRoot}/`);
+    mappings.push(`talon:// → ${nsRoot}/`);
+  }
+  return { ok: true, command: rewritten, mappings };
+}

package/src/core/vfs/vfs.ts

@@ -6,18 +6,18 @@
  * re-prefixing the mount-relative stats that come back. Mounts therefore
  * only ever see clean relative paths.
  *
- * An address is one of three spellings of the same node:
+ * An address is one of exactly two spellings of the same node:
  *
  *   talon://home/notes.md   scheme form — always namespace-interpreted
- *   home/notes.md           mount-relative form
  *   <workspace>/notes.md    OS-absolute form — routed through the mount
  *                           table by containment, exactly like a kernel
  *                           resolving a path through its mounts
  *
- * The grammar is total: an unschemed address starting with a separator or
- * drive prefix is always an OS path, never mount-relative — so an OS path
- * can't silently misroute into a like-named mount, and a namespace path
- * can't be mistaken for disk.
+ * Nothing else is an address. Bare relative paths and `~` spellings are
+ * refused with the correction rather than guessed at — the old
+ * mount-relative form (`home/notes.md`) was ambiguous with a relative OS
+ * path and is gone. The empty string (and bare separators) still name the
+ * namespace root for internal callers.
  */
 
 import { isAbsolute, relative, resolve, sep } from "node:path";
@@ -121,31 +121,46 @@ export class Vfs {
     );
   }
 
-  /** Mount names + descriptions, for docs/tool output. */
-  describeMounts(): { name: string; description: string; writable: boolean }[] {
+  /**
+   * The mount table as data: name, description, writability, and — for
+   * file-backed mounts — the disk root. Consumed by the namespace dir
+   * builder (symlink farm), the command rewriter, and docs/tool output.
+   */
+  describeMounts(): {
+    name: string;
+    description: string;
+    writable: boolean;
+    osRoot?: string;
+  }[] {
     return [...this.#mounts.entries()].map(([name, mount]) => ({
       name,
       description: mount.description,
       writable: mount.writable,
+      ...(mount.osRoot !== undefined ? { osRoot: mount.osRoot } : {}),
     }));
   }
 
   /** null = the namespace root. */
   #parse(raw: string): VfsResult<Resolved | null> {
     let path = raw.trim();
-    const schemed = path.startsWith(SCHEME);
-    if (schemed) {
+    if (path.startsWith(SCHEME)) {
       path = path.slice(SCHEME.length);
+    } else if (path === "" || /^[\\/]+$/.test(path)) {
+      // Internal callers address the namespace root as "" or bare separators.
+      return vfsOk(null);
+    } else if (OS_ABSOLUTE.test(path)) {
+      return this.#parseOsPath(path);
+    } else if (path.startsWith("talon:")) {
+      // A near-miss scheme (talon:/x, talon:x) is always a typo, never a path.
+      return vfsError(
+        "invalid-path",
+        `Did you mean "${SCHEME}${path.replace(/^talon:\/{0,2}/, "")}"?`,
+      );
     } else {
-      // Bare separators address the namespace root ("talon ls /").
-      if (/^[\\/]+$/.test(path)) return vfsOk(null);
-      if (OS_ABSOLUTE.test(path)) return this.#parseOsPath(path);
-      if (path.startsWith("~")) {
-        return vfsError(
-          "invalid-path",
-          '"~" is not expanded — use an absolute path or a talon:// address',
-        );
-      }
+      return vfsError(
+        "invalid-path",
+        `Not an address — use ${SCHEME}<mount>/… or an absolute OS path`,
+      );
     }
     if (path.includes("\\")) {
       return vfsError(