talon-agent 1.49.0 → 1.50.0

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;

package/src/core/vfs/vfs.ts

@@ -0,0 +1,237 @@
+/**
+ * VFS resolver — the mount table and the address grammar.
+ *
+ * The resolver owns everything mounts shouldn't have to repeat: address
+ * parsing, normalization, traversal rejection, routing to the mount, and
+ * 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:
+ *
+ *   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.
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { VfsMount, VfsResult, VfsStat } from "./types.js";
+import { vfsError, vfsOk } from "./types.js";
+
+const SCHEME = "talon://";
+
+/** OS-absolute spellings: `/x`, `\\server\x`, `C:\x`, `C:/x`. */
+const OS_ABSOLUTE = /^(?:[\\/]|[A-Za-z]:[\\/])/;
+
+/** A parsed path: which mount, and the path inside it. */
+type Resolved = { mount: VfsMount; prefix: string; rel: string };
+
+export class Vfs {
+  readonly #mounts = new Map<string, VfsMount>();
+
+  /** Register a mount under a single-segment name ("skills", "proc"). */
+  mount(name: string, mount: VfsMount): void {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+      throw new Error(`Invalid mount name: "${name}"`);
+    }
+    if (this.#mounts.has(name)) {
+      throw new Error(`Mount "${name}" already registered`);
+    }
+    this.#mounts.set(name, mount);
+  }
+
+  stat(path: string): VfsResult<VfsStat> {
+    const parsed = this.#parse(path);
+    if (!parsed.ok) return parsed;
+    if (parsed.value === null) {
+      return vfsOk({
+        path: "",
+        name: SCHEME,
+        kind: "dir" as const,
+        writable: false,
+      });
+    }
+    const { mount, prefix, rel } = parsed.value;
+    const result = mount.stat(rel);
+    return result.ok ? vfsOk(withPrefix(result.value, prefix)) : result;
+  }
+
+  list(path: string): VfsResult<VfsStat[]> {
+    const parsed = this.#parse(path);
+    if (!parsed.ok) return parsed;
+    if (parsed.value === null) {
+      return vfsOk(
+        [...this.#mounts.entries()].map(([name, mount]) => ({
+          path: name,
+          name,
+          kind: "dir" as const,
+          writable: mount.writable,
+          ...(mount.osRoot !== undefined ? { osPath: mount.osRoot } : {}),
+        })),
+      );
+    }
+    const { mount, prefix, rel } = parsed.value;
+    const result = mount.list(rel);
+    return result.ok
+      ? vfsOk(result.value.map((entry) => withPrefix(entry, prefix)))
+      : result;
+  }
+
+  read(path: string): VfsResult<string> {
+    const parsed = this.#parse(path);
+    if (!parsed.ok) return parsed;
+    if (parsed.value === null) return vfsError("is-a-directory");
+    return parsed.value.mount.read(parsed.value.rel);
+  }
+
+  write(path: string, content: string): VfsResult<VfsStat> {
+    const parsed = this.#parse(path);
+    if (!parsed.ok) return parsed;
+    if (parsed.value === null) return vfsError("is-a-directory");
+    const { mount, prefix, rel } = parsed.value;
+    if (!mount.write) {
+      return vfsError("not-writable", `talon://${prefix} is read-only`);
+    }
+    const result = mount.write(rel, content);
+    return result.ok ? vfsOk(withPrefix(result.value, prefix)) : result;
+  }
+
+  /**
+   * Where an address lives on disk: the absolute path for nodes of
+   * file-backed mounts (whether or not the node exists yet), `undefined`
+   * for addresses with no disk representation (the root, synthetic
+   * mounts). This is the namespace→OS direction of the address grammar —
+   * OS-level tools call it to run real file operations on a talon://
+   * address.
+   */
+  locate(path: string): VfsResult<string | undefined> {
+    const parsed = this.#parse(path);
+    if (!parsed.ok) return parsed;
+    if (parsed.value === null) return vfsOk(undefined);
+    const { mount, rel } = parsed.value;
+    if (mount.osRoot === undefined) return vfsOk(undefined);
+    return vfsOk(
+      rel === "" ? mount.osRoot : resolve(mount.osRoot, ...rel.split("/")),
+    );
+  }
+
+  /** Mount names + descriptions, for docs/tool output. */
+  describeMounts(): { name: string; description: string; writable: boolean }[] {
+    return [...this.#mounts.entries()].map(([name, mount]) => ({
+      name,
+      description: mount.description,
+      writable: mount.writable,
+    }));
+  }
+
+  /** null = the namespace root. */
+  #parse(raw: string): VfsResult<Resolved | null> {
+    let path = raw.trim();
+    const schemed = path.startsWith(SCHEME);
+    if (schemed) {
+      path = path.slice(SCHEME.length);
+    } 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',
+        );
+      }
+    }
+    if (path.includes("\\")) {
+      return vfsError(
+        "invalid-path",
+        "Namespace paths use / on every platform",
+      );
+    }
+    const segments = path.split("/").filter((s) => s.length > 0);
+    if (segments.some((s) => s === "." || s === "..")) {
+      return vfsError("invalid-path", "Relative segments are not allowed");
+    }
+    if (segments.length === 0) return vfsOk(null);
+
+    const [head, ...rest] = segments;
+    const mount = this.#mounts.get(head!);
+    if (!mount) {
+      return vfsError(
+        "not-found",
+        `No mount "${head}" — the root lists what exists`,
+      );
+    }
+    return vfsOk({ mount, prefix: head!, rel: rest.join("/") });
+  }
+
+  /**
+   * Route an OS-absolute address through the mount table by containment —
+   * the most specific (longest) disk root wins, so a mount nested inside
+   * another's root (skills/ inside the workspace) claims its own subtree.
+   * Outside every mount there is nothing to address: refuse with the mount
+   * table rather than guess.
+   */
+  #parseOsPath(osPath: string): VfsResult<Resolved> {
+    // isAbsolute guards the host boundary: a foreign spelling (a drive path
+    // on POSIX) can't be resolved against this host's roots.
+    if (isAbsolute(osPath)) {
+      const abs = resolve(osPath);
+      let best: (Resolved & { rootLength: number }) | undefined;
+      for (const [name, mount] of this.#mounts) {
+        if (mount.osRoot === undefined) continue;
+        const offset = relative(mount.osRoot, abs);
+        if (
+          offset === ".." ||
+          offset.startsWith(`..${sep}`) ||
+          isAbsolute(offset)
+        ) {
+          continue;
+        }
+        if (best !== undefined && mount.osRoot.length <= best.rootLength) {
+          continue;
+        }
+        best = {
+          mount,
+          prefix: name,
+          rel: offset
+            .split(sep)
+            .filter((s) => s.length > 0)
+            .join("/"),
+          rootLength: mount.osRoot.length,
+        };
+      }
+      if (best !== undefined) {
+        return vfsOk({ mount: best.mount, prefix: best.prefix, rel: best.rel });
+      }
+    }
+    const respelled = osPath
+      .split(/[\\/]+/)
+      .filter((s) => s.length > 0 && !/^[A-Za-z]:$/.test(s));
+    if (respelled[0] !== undefined && this.#mounts.has(respelled[0])) {
+      return vfsError(
+        "not-found",
+        `OS paths resolve only inside a mounted directory — did you mean "talon://${respelled.join("/")}"?`,
+      );
+    }
+    const roots = [...this.#mounts.entries()]
+      .filter(([, mount]) => mount.osRoot !== undefined)
+      .map(([name, mount]) => `${name} → ${mount.osRoot}`);
+    return vfsError(
+      "not-found",
+      roots.length > 0
+        ? `Not inside any mounted directory. Mounts on disk: ${roots.join(", ")}`
+        : "Not inside any mounted directory",
+    );
+  }
+}
+
+function withPrefix(stat: VfsStat, prefix: string): VfsStat {
+  const path = stat.path === "" ? prefix : `${prefix}/${stat.path}`;
+  return { ...stat, path, name: stat.path === "" ? prefix : stat.name };
+}

package/src/core/weaver/weaver.ts

@@ -73,14 +73,32 @@ export class Weaver {
 
   runTurn(params: ExecuteParams): Promise<ExecuteResult> {
     const thread = this.loom.thread(params.chatId);
+    // A turn is killable when its backend can interrupt an in-flight
+    // chat turn. The abort hook tracks lifecycle through this closure:
+    // before the turn starts, a kill just marks it (run() then refuses to
+    // start); once running, the kill signals the backend — which stops
+    // the turn cleanly per the interruptChatTurn contract. The started
+    // guard matters in a queue: killing a queued turn must never
+    // interrupt the same chat's currently running one.
+    const chat = this.deps.getBackend(params.chatId).chat;
+    const interrupt = chat?.interruptChatTurn?.bind(chat);
+    const lifecycle = { started: false, killed: false };
     // Registered before enqueueing so a turn waiting in its chat's FIFO is
     // visible as `queued` in the task table, not invisible until it runs.
     const task = taskTable.enqueue({
       kind: "turn",
       label: params.source,
       chatId: params.chatId,
+      ...(interrupt
+        ? {
+            abort: () => {
+              lifecycle.killed = true;
+              if (lifecycle.started) void interrupt(params.chatId);
+            },
+          }
+        : {}),
     });
-    return thread.enqueue(() => this.run(thread, params, task));
+    return thread.enqueue(() => this.run(thread, params, task, lifecycle));
   }
 
   /** Number of turns currently running (not queued) across all chats. */
@@ -101,17 +119,36 @@ export class Weaver {
     thread: Thread,
     params: ExecuteParams,
     task: TaskHandle,
+    lifecycle: { started: boolean; killed: boolean },
   ): Promise<ExecuteResult> {
+    if (lifecycle.killed) {
+      // Killed while queued — the turn never reaches the backend. The
+      // caller still gets a resolved (empty) result; nothing is delivered
+      // to the chat, which is the point of the kill.
+      task.fail(new Error("killed while queued"));
+      return this.emptyResult("Turn killed before it started.", params);
+    }
+    lifecycle.started = true;
     this.activeCount++;
     task.start();
     try {
       const result = await this.executeInner(thread, params, task);
-      task.succeed({
+      const usage = {
         inputTokens: result.inputTokens,
         outputTokens: result.outputTokens,
         cacheRead: result.cacheRead,
         cacheWrite: result.cacheWrite,
-      });
+      };
+      if (lifecycle.killed) {
+        // The interrupt landed and the backend closed the turn early but
+        // cleanly — that IS the interrupt contract, so the stream ends as
+        // a completion, not an error. The task still settles as killed
+        // (the truthful outcome of `talon kill`), usage included; the
+        // partial result flows back to the caller for normal handling.
+        task.fail(new Error("interrupted by kill"), usage);
+      } else {
+        task.succeed(usage);
+      }
       return result;
     } catch (err) {
       task.fail(err);

package/src/frontend/native/discovery.ts

@@ -9,6 +9,8 @@ export type BridgeDiscoveryInfo = {
   port: number;
   token?: string;
   scheme?: string;
+  /** Certificate SHA-256 (hex) when the bridge serves HTTPS. */
+  fingerprint?: string;
   startedAt?: number;
 };
 
@@ -24,6 +26,7 @@ export async function writeBridgeDiscovery(
       port: info.port,
       token: info.token ?? null,
       scheme: info.scheme ?? "http",
+      fingerprint: info.fingerprint ?? null,
       pid: process.pid,
       protocol: BRIDGE_PROTOCOL_VERSION,
       startedAt: info.startedAt ?? now,

package/src/frontend/native/index.ts

@@ -68,6 +68,7 @@ import { BridgeServer, type BridgeServerHandlers } from "./server.js";
 import { createNativeActionHandler } from "./actions.js";
 import { getMeshService } from "../../core/mesh/index.js";
 import { removeBridgeDiscovery, writeBridgeDiscovery } from "./discovery.js";
+import { isLoopbackHost, loadOrCreateBridgeTlsIdentity } from "./tls.js";
 import { readLogEntries } from "./logs.js";
 import {
   BRIDGE_PROTOCOL_VERSION,
@@ -1183,12 +1184,17 @@ export function createNativeFrontend(
   };
 
   const nativeCfg = config.native ?? { port: 19880, host: "127.0.0.1" };
+  const bridgeHost = nativeCfg.host ?? "127.0.0.1";
+  // Encrypted by default the moment the bridge leaves the machine; loopback
+  // stays plain HTTP unless explicitly opted in (`native.tls`).
+  const bridgeTls = nativeCfg.tls ?? !isLoopbackHost(bridgeHost);
   const server = new BridgeServer(
     {
-      host: nativeCfg.host ?? "127.0.0.1",
+      host: bridgeHost,
       port: nativeCfg.port ?? 19880,
       token: nativeCfg.token,
       startedAt,
+      ...(bridgeTls ? { tls: () => loadOrCreateBridgeTlsIdentity() } : {}),
     },
     handlers,
   );
@@ -1253,9 +1259,12 @@ export function createNativeFrontend(
       log("native", `Gateway on :${gatewayPort}`);
       chats.restore();
       await server.start();
+      const fingerprint = server.getFingerprint();
       await writeBridgeDiscovery({
         port: server.getPort(),
         token: nativeCfg.token,
+        scheme: server.getScheme(),
+        ...(fingerprint ? { fingerprint } : {}),
         startedAt: Date.parse(startedAt),
       });
     },

package/src/frontend/native/server.ts

@@ -9,7 +9,9 @@
  * curl one-liner identically.
  *
  * Binds `host` (loopback by default) with the gateway's EADDRINUSE +1..+5
- * fallback so two daemons on one machine don't collide.
+ * fallback so two daemons on one machine don't collide. With a TLS identity
+ * injected (see tls.ts) the same server speaks HTTPS instead — clients pin
+ * the certificate fingerprint surfaced on `/health`.
  */
 
 import {
@@ -18,10 +20,13 @@ import {
   type Server,
   type ServerResponse,
 } from "node:http";
+import { createServer as createTlsServer } from "node:https";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
 import { extname } from "node:path";
 import { log, logError, logDebug } from "../../util/log.js";
+import { formatFingerprint, type BridgeTlsIdentity } from "./tls.js";
 import {
   BRIDGE_PROTOCOL_VERSION,
   isLogLevel,
@@ -138,6 +143,7 @@ export class BridgeServer {
   private clients = new Set<ServerResponse>();
   private pingTimer: ReturnType<typeof setInterval> | undefined;
   private port = 0;
+  private tlsIdentity: BridgeTlsIdentity | null = null;
 
   constructor(
     private readonly opts: {
@@ -145,6 +151,12 @@ export class BridgeServer {
       port: number;
       token?: string;
       startedAt: string;
+      /**
+       * When present, the bridge serves HTTPS with this identity. A provider
+       * (not the identity itself) so the transport stays free of key-file
+       * I/O — it resolves once, inside `start()`.
+       */
+      tls?: () => Promise<BridgeTlsIdentity>;
     },
     private readonly handlers: BridgeServerHandlers,
   ) {}
@@ -153,6 +165,16 @@ export class BridgeServer {
     return this.port;
   }
 
+  /** "https" once started with a TLS identity, else "http". */
+  getScheme(): "http" | "https" {
+    return this.tlsIdentity ? "https" : "http";
+  }
+
+  /** The served certificate's SHA-256 fingerprint (hex), or null over HTTP. */
+  getFingerprint(): string | null {
+    return this.tlsIdentity?.fingerprint ?? null;
+  }
+
   /** Push an event to every connected SSE client. */
   broadcast(event: BridgeEvent): void {
     if (this.clients.size === 0) return;
@@ -168,7 +190,8 @@ export class BridgeServer {
 
   async start(): Promise<number> {
     if (this.server) return this.port;
-    const server = createServer((req, res) => {
+    this.tlsIdentity = this.opts.tls ? await this.opts.tls() : null;
+    const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
       this.handle(req, res).catch((err) => {
         logError("native", "Bridge request handler threw", err);
         if (!res.headersSent) {
@@ -176,7 +199,15 @@ export class BridgeServer {
           res.end(JSON.stringify({ ok: false, error: "Internal error" }));
         }
       });
-    });
+    };
+    // https.Server extends http.Server's request/lifecycle surface — one
+    // `Server`-typed field serves both transports.
+    const server: Server = this.tlsIdentity
+      ? createTlsServer(
+          { key: this.tlsIdentity.keyPem, cert: this.tlsIdentity.certPem },
+          onRequest,
+        )
+      : createServer(onRequest);
 
     this.pingTimer = setInterval(() => {
       for (const res of this.clients) {
@@ -215,9 +246,17 @@ export class BridgeServer {
           );
           log(
             "native",
-            `Bridge listening on ${this.opts.host}:${this.port}` +
+            `Bridge listening on ${this.getScheme()}://${this.opts.host}:${this.port}` +
               (this.opts.token ? " (token required)" : ""),
           );
+          if (this.tlsIdentity) {
+            // The pairing datum: clients confirm this fingerprint on first
+            // connect, so it belongs in the log where the operator looks.
+            log(
+              "native",
+              `Bridge certificate fingerprint ${formatFingerprint(this.tlsIdentity.fingerprint)}`,
+            );
+          }
           resolve(this.port);
         });
       };
@@ -271,6 +310,10 @@ export class BridgeServer {
         protocol: BRIDGE_PROTOCOL_VERSION,
         host: this.opts.host,
         port: this.port,
+        scheme: this.getScheme(),
+        // The certificate's own hash — public by definition (any TLS client
+        // sees the certificate), surfaced so pairing UIs can display it.
+        fingerprint: this.getFingerprint(),
         authRequired: Boolean(this.opts.token),
         startedAt: this.opts.startedAt,
         botName: s.botName,
@@ -600,10 +643,26 @@ export class BridgeServer {
   private authOk(req: IncomingMessage, url: URL): boolean {
     if (!this.opts.token) return true;
     const header = req.headers["authorization"];
-    if (typeof header === "string" && header === `Bearer ${this.opts.token}`)
+    if (
+      typeof header === "string" &&
+      header.startsWith("Bearer ") &&
+      this.tokenMatches(header.slice("Bearer ".length))
+    )
       return true;
     // EventSource can't set headers, so SSE clients pass ?token=… instead.
-    return url.searchParams.get("token") === this.opts.token;
+    return this.tokenMatches(url.searchParams.get("token"));
+  }
+
+  /**
+   * Constant-time token comparison. Hashing both sides first equalizes
+   * lengths (timingSafeEqual demands it) without leaking the real length.
+   */
+  private tokenMatches(candidate: string | null): boolean {
+    if (candidate === null || !this.opts.token) return false;
+    return timingSafeEqual(
+      createHash("sha256").update(candidate).digest(),
+      createHash("sha256").update(this.opts.token).digest(),
+    );
   }
 
   private corsHeaders(): Record<string, string> {