talon-agent 1.48.0 → 1.50.0

package/src/core/tools/vfs.ts

@@ -0,0 +1,61 @@
+/**
+ * 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",
+  },
+];

package/src/core/vfs/index.ts

@@ -0,0 +1,113 @@
+/**
+ * VFS — public surface and default namespace.
+ *
+ * `getVfs()` serves the process-wide namespace, built on first use rather
+ * than at module load: the file mounts capture `dirs.*` when constructed,
+ * and eager construction would freeze those paths into whichever process
+ * (or test mock) happened to import this barrel first. Mounts project
+ * live singletons, so there is nothing to inject at bootstrap:
+ *
+ *   talon://
+ *     home/       workspace (writable)
+ *     skills/     SKILL.md bundles (writable)
+ *     scripts/    agent script bodies (writable)
+ *     logs/       daily logs (read-only — the daemon writes these)
+ *     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`.
+ */
+
+import { dirs } from "../../util/paths.js";
+import { bus } from "../bus/index.js";
+import { registry } from "../plugin/registry.js";
+import { taskTable } from "../tasks/index.js";
+import { createFileMount } from "./mounts/files.js";
+import { createPluginsMount, type PluginView } from "./mounts/plugins.js";
+import { createProcMount } from "./mounts/proc.js";
+import { Vfs } from "./vfs.js";
+
+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 type {
+  VfsErrorCode,
+  VfsMount,
+  VfsNodeKind,
+  VfsResult,
+  VfsStat,
+} from "./types.js";
+export { VFS_MAX_READ_BYTES, vfsError, vfsOk } from "./types.js";
+
+function pluginViews(): PluginView[] {
+  const modules: PluginView[] = registry.all.map(({ plugin, path }) => ({
+    name: plugin.name,
+    kind: "module",
+    ...(plugin.description !== undefined
+      ? { description: plugin.description }
+      : {}),
+    ...(plugin.version !== undefined ? { version: plugin.version } : {}),
+    source: path,
+  }));
+  const mcp: PluginView[] = registry.mcpEntries.map((entry) => ({
+    name: entry.name,
+    kind: "mcp",
+    source: `${entry.command}${entry.args ? ` ${entry.args.join(" ")}` : ""}`,
+  }));
+  return [...modules, ...mcp];
+}
+
+function buildDefaultNamespace(): Vfs {
+  const vfs = new Vfs();
+  vfs.mount(
+    "home",
+    createFileMount({
+      root: dirs.workspace,
+      description: "The workspace — the agent's home directory",
+      writable: true,
+    }),
+  );
+  vfs.mount(
+    "skills",
+    createFileMount({
+      root: dirs.skills,
+      description: "SKILL.md workflow bundles",
+      writable: true,
+    }),
+  );
+  vfs.mount(
+    "scripts",
+    createFileMount({
+      root: dirs.scripts,
+      description: "Agent-authored script bodies",
+      writable: true,
+    }),
+  );
+  vfs.mount(
+    "logs",
+    createFileMount({
+      root: dirs.logs,
+      description: "Daily interaction logs (daemon-written)",
+      writable: false,
+    }),
+  );
+  vfs.mount(
+    "proc",
+    createProcMount({
+      tasks: () => taskTable.list(),
+      events: () => bus.recent(0),
+    }),
+  );
+  vfs.mount("plugins", createPluginsMount(pluginViews));
+  return vfs;
+}
+
+let defaultVfs: Vfs | undefined;
+
+/** The process-wide namespace, built on first use. */
+export function getVfs(): Vfs {
+  defaultVfs ??= buildDefaultNamespace();
+  return defaultVfs;
+}

package/src/core/vfs/mounts/files.ts

@@ -0,0 +1,154 @@
+/**
+ * File mount — a real directory exposed into the namespace.
+ *
+ * Backs the workspace-shaped mounts (home, skills, scripts, logs). The
+ * resolver has already rejected traversal segments; the containment check
+ * here is belt-and-braces so no future caller can reach outside the root.
+ * A missing root reads as an empty directory — mounts exist from boot,
+ * the workspace dirs appear lazily.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { VfsMount, VfsResult, VfsStat } from "../types.js";
+import { VFS_MAX_READ_BYTES, vfsError, vfsOk } from "../types.js";
+
+export function createFileMount(options: {
+  root: string;
+  description: string;
+  writable: boolean;
+}): VfsMount {
+  const root = resolve(options.root);
+
+  /** Absolute path for `rel`, or undefined when it would escape the root. */
+  function realPath(rel: string): string | undefined {
+    const abs = resolve(root, ...rel.split("/"));
+    const offset = relative(root, abs);
+    if (
+      offset.startsWith(`..${sep}`) ||
+      offset === ".." ||
+      isAbsolute(offset)
+    ) {
+      return undefined;
+    }
+    return abs;
+  }
+
+  function statAt(rel: string, abs: string): VfsResult<VfsStat> {
+    try {
+      const stats = statSync(abs);
+      const name = rel === "" ? "" : rel.split("/").at(-1)!;
+      return vfsOk({
+        path: rel,
+        name,
+        kind: stats.isDirectory() ? ("dir" as const) : ("file" as const),
+        ...(stats.isFile() ? { size: stats.size } : {}),
+        modifiedAt: Math.floor(stats.mtimeMs),
+        writable: options.writable,
+        osPath: abs,
+      });
+    } catch {
+      return vfsError("not-found");
+    }
+  }
+
+  return {
+    description: options.description,
+    writable: options.writable,
+    osRoot: root,
+
+    stat(rel) {
+      const abs = realPath(rel);
+      if (!abs) return vfsError("invalid-path");
+      if (rel === "" && !existsSync(abs)) {
+        return vfsOk({
+          path: "",
+          name: "",
+          kind: "dir",
+          writable: options.writable,
+          osPath: abs,
+        });
+      }
+      return statAt(rel, abs);
+    },
+
+    list(rel) {
+      const abs = realPath(rel);
+      if (!abs) return vfsError("invalid-path");
+      if (rel === "" && !existsSync(abs)) return vfsOk([]);
+      let stats;
+      try {
+        stats = statSync(abs);
+      } catch {
+        return vfsError("not-found");
+      }
+      if (!stats.isDirectory()) return vfsError("not-a-directory");
+      const entries = readdirSync(abs, { withFileTypes: true })
+        .map((entry) => {
+          const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+          const child = statAt(childRel, resolve(abs, entry.name));
+          return child.ok ? child.value : undefined;
+        })
+        .filter((entry): entry is VfsStat => entry !== undefined)
+        .sort(
+          (a, b) =>
+            Number(a.kind === "file") - Number(b.kind === "file") ||
+            a.name.localeCompare(b.name),
+        );
+      return vfsOk(entries);
+    },
+
+    read(rel) {
+      const abs = realPath(rel);
+      if (!abs) return vfsError("invalid-path");
+      let stats;
+      try {
+        stats = statSync(abs);
+      } catch {
+        return vfsError("not-found");
+      }
+      if (stats.isDirectory()) return vfsError("is-a-directory");
+      if (stats.size > VFS_MAX_READ_BYTES) {
+        return vfsError(
+          "too-large",
+          `${stats.size} bytes (cap ${VFS_MAX_READ_BYTES}) — on disk at ${abs}`,
+        );
+      }
+      const buffer = readFileSync(abs);
+      if (buffer.includes(0)) {
+        return vfsError("binary-file", "Content contains null bytes");
+      }
+      return vfsOk(buffer.toString("utf-8"));
+    },
+
+    ...(options.writable
+      ? {
+          write(rel: string, content: string): VfsResult<VfsStat> {
+            if (rel === "") return vfsError("is-a-directory");
+            const abs = realPath(rel);
+            if (!abs) return vfsError("invalid-path");
+            if (existsSync(abs) && statSync(abs).isDirectory()) {
+              return vfsError("is-a-directory");
+            }
+            try {
+              mkdirSync(dirname(abs), { recursive: true });
+              writeFileSync(abs, content, "utf-8");
+            } catch (err) {
+              return vfsError(
+                "io-error",
+                err instanceof Error ? err.message : String(err),
+              );
+            }
+            return statAt(rel, abs);
+          },
+        }
+      : {}),
+  };
+}

package/src/core/vfs/mounts/plugins.ts

@@ -0,0 +1,72 @@
+/**
+ * Plugins mount — the plugin registry as a synthetic read-only directory:
+ * one file per loaded plugin (or registered standalone MCP entry), whose
+ * content is the registry's view of it as pretty JSON. Provider-injected
+ * like proc — the index wires the live registry, tests wire fixtures.
+ */
+
+import type { VfsMount, VfsResult, VfsStat } from "../types.js";
+import { vfsError, vfsOk } from "../types.js";
+
+/** The registry facts one plugin file exposes. */
+export interface PluginView {
+  readonly name: string;
+  readonly kind: "module" | "mcp";
+  readonly description?: string;
+  readonly version?: string;
+  /** Module path, or the MCP entry's command line. */
+  readonly source: string;
+}
+
+function render(view: PluginView): string {
+  return `${JSON.stringify(view, null, 2)}\n`;
+}
+
+function fileStat(view: PluginView): VfsStat {
+  return {
+    path: view.name,
+    name: view.name,
+    kind: "file",
+    size: Buffer.byteLength(render(view), "utf-8"),
+    writable: false,
+  };
+}
+
+export function createPluginsMount(
+  plugins: () => readonly PluginView[],
+): VfsMount {
+  function byName(rel: string): PluginView | undefined {
+    return plugins().find((view) => view.name === rel);
+  }
+
+  return {
+    description: "Loaded plugins and registered MCP servers (registry view)",
+    writable: false,
+
+    stat(rel): VfsResult<VfsStat> {
+      if (rel === "")
+        return vfsOk({ path: "", name: "", kind: "dir", writable: false });
+      const view = byName(rel);
+      return view ? vfsOk(fileStat(view)) : vfsError("not-found");
+    },
+
+    list(rel) {
+      if (rel !== "") {
+        return byName(rel)
+          ? vfsError("not-a-directory")
+          : vfsError("not-found");
+      }
+      return vfsOk(
+        plugins()
+          .map(fileStat)
+          .sort((a, b) => a.name.localeCompare(b.name)),
+      );
+    },
+
+    read(rel) {
+      if (rel === "") return vfsError("is-a-directory");
+      const view = byName(rel);
+      return view ? vfsOk(render(view)) : vfsError("not-found");
+    },
+  };
+}

package/src/core/vfs/mounts/proc.ts

@@ -0,0 +1,125 @@
+/**
+ * Proc mount — live daemon state as a synthetic read-only tree, in the
+ * /proc tradition:
+ *
+ *   proc/
+ *     tasks/<id>   one task table record, pretty JSON
+ *     events       the event bus ring, JSON Lines (newest last)
+ *
+ * Providers are injected so the mount is a pure projection — the index
+ * wires the real task table and bus, tests wire fixtures. Sizes and
+ * timestamps are computed from the rendered content on demand; this is a
+ * view of live state, nothing is cached.
+ */
+
+import type { PublishedEvent } from "../../bus/index.js";
+import type { TaskRecord } from "../../tasks/index.js";
+import type { VfsMount, VfsResult, VfsStat } from "../types.js";
+import { vfsError, vfsOk } from "../types.js";
+
+export interface ProcMountDeps {
+  tasks: () => readonly TaskRecord[];
+  events: () => readonly PublishedEvent[];
+}
+
+const DIR = (path: string, name: string): VfsStat => ({
+  path,
+  name,
+  kind: "dir",
+  writable: false,
+});
+
+function fileStat(path: string, content: string, modifiedAt?: number): VfsStat {
+  return {
+    path,
+    name: path.split("/").at(-1)!,
+    kind: "file",
+    size: Buffer.byteLength(content, "utf-8"),
+    ...(modifiedAt !== undefined ? { modifiedAt } : {}),
+    writable: false,
+  };
+}
+
+function renderTask(task: TaskRecord): string {
+  return `${JSON.stringify(task, null, 2)}\n`;
+}
+
+function taskModifiedAt(task: TaskRecord): number {
+  return task.endedAt ?? task.startedAt ?? task.queuedAt;
+}
+
+function renderEvents(events: readonly PublishedEvent[]): string {
+  if (events.length === 0) return "";
+  return events.map((event) => JSON.stringify(event)).join("\n") + "\n";
+}
+
+export function createProcMount(deps: ProcMountDeps): VfsMount {
+  function taskById(id: string): TaskRecord | undefined {
+    if (!/^\d+$/.test(id)) return undefined;
+    return deps.tasks().find((task) => task.id === Number(id));
+  }
+
+  function resolveNode(rel: string): VfsResult<VfsStat> {
+    if (rel === "") return vfsOk(DIR("", ""));
+    if (rel === "tasks") return vfsOk(DIR("tasks", "tasks"));
+    if (rel === "events") {
+      const events = deps.events();
+      return vfsOk(fileStat("events", renderEvents(events), events.at(-1)?.at));
+    }
+    const taskId = rel.startsWith("tasks/") ? rel.slice("tasks/".length) : null;
+    if (taskId !== null && !taskId.includes("/")) {
+      const task = taskById(taskId);
+      if (!task) return vfsError("not-found");
+      return vfsOk(
+        fileStat(`tasks/${task.id}`, renderTask(task), taskModifiedAt(task)),
+      );
+    }
+    return vfsError("not-found");
+  }
+
+  return {
+    description: "Live daemon state: task table and event bus ring",
+    writable: false,
+
+    stat: resolveNode,
+
+    list(rel) {
+      if (rel === "") {
+        const events = deps.events();
+        return vfsOk([
+          DIR("tasks", "tasks"),
+          fileStat("events", renderEvents(events), events.at(-1)?.at),
+        ]);
+      }
+      if (rel === "tasks") {
+        return vfsOk(
+          deps
+            .tasks()
+            .map((task) =>
+              fileStat(
+                `tasks/${task.id}`,
+                renderTask(task),
+                taskModifiedAt(task),
+              ),
+            )
+            .sort((a, b) => Number(a.name) - Number(b.name)),
+        );
+      }
+      const node = resolveNode(rel);
+      if (!node.ok) return node;
+      return vfsError("not-a-directory");
+    },
+
+    read(rel) {
+      if (rel === "events") return vfsOk(renderEvents(deps.events()));
+      if (rel.startsWith("tasks/")) {
+        const task = taskById(rel.slice("tasks/".length));
+        if (!task) return vfsError("not-found");
+        return vfsOk(renderTask(task));
+      }
+      const node = resolveNode(rel);
+      if (!node.ok) return node;
+      return vfsError("is-a-directory");
+    },
+  };
+}

package/src/core/vfs/types.ts

@@ -0,0 +1,103 @@
+/**
+ * VFS vocabulary — the unified `talon://` namespace.
+ *
+ * One rooted, mountable namespace over everything the daemon owns, in the
+ * Plan 9 tradition: real-file stores (workspace, skills, scripts, logs)
+ * and synthetic /proc-style views of live state (task table, event bus,
+ * plugin registry) answer the same four operations. The namespace is for
+ * unification and introspection — mounts decide what they can do (a
+ * synthetic view has nothing meaningful to write), but the VFS is never a
+ * permission layer.
+ *
+ * An address reaches the namespace in one of three spellings, all resolved
+ * by the same grammar (see `Vfs.#parse`):
+ *
+ *   - scheme:         `talon://skills/review-pr/SKILL.md`
+ *   - mount-relative: `skills/review-pr/SKILL.md` (`/`-separated everywhere)
+ *   - OS-absolute:    the disk spelling of a node inside a file-backed
+ *                     mount's root — the same node, other coordinate system
+ *
+ * Mounts receive mount-relative paths ("" = the mount root) and report
+ * entry paths mount-relative too — the resolver owns prefixing.
+ */
+
+/** What a path points at. */
+export type VfsNodeKind = "dir" | "file";
+
+/** Errno-style failure vocabulary — every operation fails with one of these. */
+export type VfsErrorCode =
+  | "not-found"
+  | "invalid-path"
+  | "is-a-directory"
+  | "not-a-directory"
+  | "not-writable"
+  | "too-large"
+  | "binary-file"
+  | "io-error";
+
+export type VfsResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | {
+      readonly ok: false;
+      readonly error: VfsErrorCode;
+      readonly detail?: string;
+    };
+
+export function vfsOk<T>(value: T): VfsResult<T> {
+  return { ok: true, value };
+}
+
+export function vfsError<T>(
+  error: VfsErrorCode,
+  detail?: string,
+): VfsResult<T> {
+  return { ok: false, error, ...(detail !== undefined ? { detail } : {}) };
+}
+
+/** One node's metadata — also the shape of directory listing entries. */
+export interface VfsStat {
+  /** Root-relative path (`skills/review-pr/SKILL.md`); "" is the root. */
+  readonly path: string;
+  /** Last path segment; the mount name for a mount root. */
+  readonly name: string;
+  readonly kind: VfsNodeKind;
+  /** Content size in bytes, when the mount can know it cheaply. */
+  readonly size?: number;
+  /** Last modification, epoch ms, when known. */
+  readonly modifiedAt?: number;
+  /** Whether write() can target this node (or nodes under this dir). */
+  readonly writable: boolean;
+  /**
+   * Where this node lives on disk, for file-backed mounts. Absent on
+   * synthetic nodes — they have no disk representation. This is what lets
+   * OS-level tools (shell, editors) reach a node the namespace named.
+   */
+  readonly osPath?: string;
+}
+
+/**
+ * One mounted store. Implementations receive mount-relative paths that the
+ * resolver has already normalized (no "..", no backslashes, no empty
+ * segments) and return stats with mount-relative `path`s.
+ */
+export interface VfsMount {
+  /** One line shown when listing the namespace root. */
+  readonly description: string;
+  /** Can write() ever succeed here? Synthetic views say false. */
+  readonly writable: boolean;
+  /**
+   * Absolute disk root, for file-backed mounts. The single fact that makes
+   * addresses bidirectional: the resolver routes OS-absolute addresses into
+   * the mount by containment, and `Vfs.locate` maps namespace addresses
+   * back to disk. Synthetic mounts omit it.
+   */
+  readonly osRoot?: string;
+  stat(rel: string): VfsResult<VfsStat>;
+  list(rel: string): VfsResult<VfsStat[]>;
+  read(rel: string): VfsResult<string>;
+  /** Optional — absent means the whole mount is read-only. */
+  write?(rel: string, content: string): VfsResult<VfsStat>;
+}
+
+/** Read cap — a namespace read is a context payload, not a file transfer. */
+export const VFS_MAX_READ_BYTES = 256 * 1024;