talon-agent 5.1.0 → 5.2.1

package/src/core/engine/gateway-actions/agents/report.ts

@@ -0,0 +1,107 @@
+/**
+ * Agent-side sub-agent actions — the three tools that only mean something
+ * inside a sub-agent run.
+ *
+ * The calling agent is identified from the gateway chat key (`agent:<id>`),
+ * which the backend derives from the run's `contextLabel` and the MCP hub
+ * binds to the tool session. Nothing is taken from the model's parameters:
+ * an agent cannot claim to be a different agent, because it never names one.
+ *
+ * Called from a chat (or any other context) these are refused rather than
+ * silently no-oping — a model that thinks it reported when it did not is the
+ * one failure mode worth being loud about.
+ */
+
+import {
+  agentIdFromContextLabel,
+  agentRegistry,
+  deliverMessage,
+  describeParent,
+} from "../../../agents/index.js";
+import { logError } from "../../../../util/log.js";
+import type { ActionResult } from "../../../types.js";
+import type { AgentRecord } from "../../../agents/index.js";
+import type { SharedActionHandlers } from "../types.js";
+
+function notAnAgent(tool: string): ActionResult {
+  return {
+    ok: false,
+    error:
+      `${tool} is only callable inside a sub-agent run. This context is a ` +
+      `chat, which has no parent to report to.`,
+  };
+}
+
+/** The live agent behind this chat key, or null when the caller isn't one. */
+function callingAgent(chatKey: string): AgentRecord | null {
+  const id = agentIdFromContextLabel(chatKey);
+  if (!id || !agentRegistry.isLive(id)) return null;
+  return agentRegistry.get(id);
+}
+
+export const agentReportHandlers: SharedActionHandlers = {
+  report_result: (body, _chatId, _backend, chatKey) => {
+    const record = callingAgent(chatKey);
+    if (!record) return notAnAgent("report_result");
+    const summary = String(body.summary ?? "").trim();
+    if (!summary) return { ok: false, error: "Missing summary" };
+    const details = body.details ? String(body.details).trim() : undefined;
+    const stored = agentRegistry.report(record.id, {
+      summary,
+      ...(details ? { details } : {}),
+    });
+    if (!stored) {
+      return {
+        ok: false,
+        error:
+          "You have already reported a result. It is recorded and will be " +
+          "delivered when your run ends — finish up instead of reporting again.",
+      };
+    }
+    return {
+      ok: true,
+      text:
+        `Result recorded. It is delivered to ${describeParent(record.parent)} ` +
+        `when your run ends — you can stop now.`,
+    };
+  },
+
+  message_parent: (body, _chatId, _backend, chatKey) => {
+    const record = callingAgent(chatKey);
+    if (!record) return notAnAgent("message_parent");
+    const text = String(body.text ?? "").trim();
+    if (!text) return { ok: false, error: "Missing text" };
+    // Fire-and-forget: waking a chat runs a whole turn, and this tool call
+    // must not block for the length of the parent's reply.
+    void deliverMessage(record, text).catch((err: unknown) =>
+      logError(
+        "agents",
+        `message_parent delivery failed for ${record.id}`,
+        err,
+      ),
+    );
+    return {
+      ok: true,
+      text: `Note sent to ${describeParent(record.parent)}. Carry on — this did not end your run.`,
+    };
+  },
+
+  check_inbox: (_body, _chatId, _backend, chatKey) => {
+    const record = callingAgent(chatKey);
+    if (!record) return notAnAgent("check_inbox");
+    const messages = agentRegistry.drain(record.id);
+    if (messages.length === 0) {
+      return { ok: true, text: "Inbox empty — no new instructions." };
+    }
+    const rendered = messages
+      .map((message) => {
+        const at = new Date(message.at).toISOString().slice(11, 19);
+        return `[${at}] from ${message.from}:\n${message.text}`;
+      })
+      .join("\n\n");
+    return {
+      ok: true,
+      text: `${messages.length} message(s):\n\n${rendered}`,
+    };
+  },
+};

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

@@ -11,6 +11,8 @@
  *   - `fetch-url` — fetch a URL (text extraction or binary download)
  *   - `cron`      — scheduled-job CRUD
  *   - `triggers`  — long-running watcher-script CRUD
+ *   - `agents`    — sub-agent spawn / inspect / message, and the agent-side
+ *                   report / inbox tools
  *   - `goals`     — persistent multi-turn objectives
  *   - `memory`    — remember / recall / forget over the typed memory store
  *   - `scripts`   — reusable agent-authored scripts
@@ -28,6 +30,7 @@ import { historyHandlers } from "./history.js";
 import { fetchUrlHandlers } from "./fetch-url.js";
 import { cronHandlers } from "./cron.js";
 import { triggerHandlers } from "./triggers.js";
+import { agentContextActions, agentHandlers } from "./agents/index.js";
 import { goalHandlers } from "./goals.js";
 import { memoryHandlers } from "./memory.js";
 import { scriptHandlers } from "./scripts.js";
@@ -53,6 +56,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...fetchUrlHandlers,
   ...cronHandlers,
   ...triggerHandlers,
+  ...agentHandlers,
   ...goalHandlers,
   ...memoryHandlers,
   ...scriptHandlers,
@@ -102,6 +106,32 @@ export function isChatFreeAction(action: string): boolean {
   return chatFreeActions.has(action);
 }
 
+/**
+ * True when the action belongs to the sub-agent family, i.e. the gateway may
+ * dispatch it for an `agent:<id>` chat key (which has an identity but no
+ * chat). Anything else stays chat-routed.
+ */
+export function isAgentContextAction(action: string): boolean {
+  return agentContextActions.has(action);
+}
+
+/**
+ * Dispatch a sub-agent action on behalf of a running agent. `contextKey` is
+ * the agent's `agent:<id>` label, handed through as the `chatKey` so the
+ * handlers can identify the caller; `0` is the explicit "no chat" chatId,
+ * same sentinel the chat-free path uses.
+ */
+export async function handleAgentContextAction(
+  body: Record<string, unknown>,
+  contextKey: string,
+): Promise<ActionResult | null> {
+  const action = body.action as string;
+  if (!isAgentContextAction(action)) return null;
+  const handler = handlers[action];
+  if (!handler) return null;
+  return handler(body, 0, undefined, contextKey);
+}
+
 /**
  * Dispatch a chat-free action. The handler signature still takes a chatId
  * (they all share one type); chat-free handlers ignore it, and `0` is passed

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

@@ -9,7 +9,7 @@
  */
 
 import { getMeshService } from "../../../mesh/index.js";
-import { getTeleport, setTeleportCwd } from "../../../mesh/teleport.js";
+import { getTeleport, setTeleportCwd } from "../../../mesh/devices/teleport.js";
 import { renderExec, type Result } from "./results.js";
 import { shellQuote } from "./shell.js";
 

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

@@ -10,7 +10,7 @@
 
 import { spawn } from "node:child_process";
 import { stat as fsStat } from "node:fs/promises";
-import { getTeleport } from "../../../mesh/teleport.js";
+import { getTeleport } from "../../../mesh/devices/teleport.js";
 import { createOutputCapture } from "../../../../util/exec-output.js";
 import { bashBackground } from "./exec-background.js";
 import { bashTeleported } from "./exec-remote.js";

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

@@ -10,7 +10,7 @@
 import { readFile, stat as fsStat } from "node:fs/promises";
 import { extname } from "node:path";
 import { getMeshService } from "../../../mesh/index.js";
-import { getTeleport } from "../../../mesh/teleport.js";
+import { getTeleport } from "../../../mesh/devices/teleport.js";
 import { num, resolvePathParam, str } from "./params.js";
 import type { Result } from "./results.js";
 import type { SharedActionHandlers } from "../types.js";

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

@@ -9,7 +9,7 @@
 
 import { glob as fsGlob, readFile, stat as fsStat } from "node:fs/promises";
 import { join } from "node:path";
-import { getTeleport } from "../../../mesh/teleport.js";
+import { getTeleport } from "../../../mesh/devices/teleport.js";
 import { bashTeleported } from "./exec-remote.js";
 import { resolvePathParam, str } from "./params.js";
 import type { Result } from "./results.js";

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

@@ -6,7 +6,7 @@
  */
 
 import { getMeshService } from "../../../mesh/index.js";
-import { clearTeleport, setTeleport } from "../../../mesh/teleport.js";
+import { clearTeleport, setTeleport } from "../../../mesh/devices/teleport.js";
 import type { Result } from "./results.js";
 import type { SharedActionHandlers } from "../types.js";
 

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

@@ -10,7 +10,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { getMeshService } from "../../../mesh/index.js";
-import { getTeleport } from "../../../mesh/teleport.js";
+import { getTeleport } from "../../../mesh/devices/teleport.js";
 import { resolvePathParam, str } from "./params.js";
 import type { Result } from "./results.js";
 import type { SharedActionHandlers } from "../types.js";

package/src/core/engine/gateway-routes.ts

@@ -6,6 +6,7 @@
 import type { IncomingMessage, Server, ServerResponse } from "node:http";
 import { bus } from "../bus/index.js";
 import { taskTable } from "../tasks/index.js";
+import { agentRegistry } from "../agents/index.js";
 import { handleHubRequest, HUB_PATH_PREFIX } from "../mcp-hub/index.js";
 import { log, logError } from "../../util/log.js";
 
@@ -95,6 +96,17 @@ const ROUTES: readonly GatewayRoute[] = [
     handle: ({ res }) =>
       sendJson(res, 200, { ok: true, tasks: taskTable.list() }),
   },
+  {
+    // The sub-agent registry — live agents plus the settled ring. Same
+    // content-free contract as /tasks: ids, labels, states, never briefs.
+    method: "GET",
+    path: "/agents",
+    handle: ({ res }) =>
+      sendJson(res, 200, {
+        ok: true,
+        agents: agentRegistry.list().map(({ brief: _brief, ...rest }) => rest),
+      }),
+  },
   {
     // Abort one killable task by id — the transport for `talon kill`.
     method: "POST",

package/src/core/engine/gateway.ts

@@ -19,8 +19,10 @@ import { log, logError, logDebug } from "../../util/log.js";
 import {
   handleSharedAction,
   handleChatFreeAction,
+  handleAgentContextAction,
   isChatFreeAction,
 } from "./gateway-actions/index.js";
+import { AGENT_CONTEXT_PREFIX } from "../agents/context.js";
 import { registerCrossSendTarget } from "./gateway-actions/cross-send.js";
 import { getHubSessionCount } from "../mcp-hub/index.js";
 import {
@@ -99,6 +101,11 @@ export class Gateway {
   private readonly frontendHandlers = new Map<string, FrontendActionHandler>();
   private readonly chatFrontendOwners = new Map<number, string>();
   private server: ReturnType<typeof createServer> | null = null;
+  /**
+   * In-flight `start()` bind, so concurrent callers share one HTTP server.
+   * Non-null only between the first `start()` call and its bind settling.
+   */
+  private starting: Promise<number> | null = null;
   private port = 0;
   private readonly startedAt = new Date().toISOString();
   private startedListeners: Array<(port: number) => void> = [];
@@ -238,6 +245,50 @@ export class Gateway {
 
   // ── Action dispatch ────────────────────────────────────────────────────────
 
+  /**
+   * Dispatch the actions that resolve without a chat, or `null` when the
+   * request needs one after all.
+   *
+   * Two families qualify, and they short-circuit routing for the same
+   * reason: there is no chat to route to.
+   *
+   *   - **Chat-free** actions (the device mesh, cross-send) read daemon-wide
+   *     state and ignore chatId. Gating them behind an active chat made the
+   *     whole mesh unreachable from background runs — and unlike send/react
+   *     they carry no `chat_id` param to promote.
+   *   - **Sub-agent** actions arrive from a run whose `contextLabel` is
+   *     `agent:<id>`; the MCP hub binds that to the tool session and the
+   *     bridge sends it back as `_chatId`. Such a caller has an identity but
+   *     no chat, so the key is handed through as the chatKey — which is how
+   *     `report_result` knows which agent reported. Everything else a
+   *     sub-agent calls still routes by an explicit `chat_id`, exactly as a
+   *     heartbeat run does.
+   */
+  private async dispatchWithoutChat(
+    body: Record<string, unknown>,
+    rawChatId: string,
+  ): Promise<unknown | null> {
+    const action = typeof body.action === "string" ? body.action : "";
+    const agentContext = rawChatId.startsWith(AGENT_CONTEXT_PREFIX);
+    if (!action || (!agentContext && !isChatFreeAction(action))) return null;
+    const where = agentContext ? rawChatId : "chat-free";
+    const t0 = Date.now();
+    try {
+      const result = agentContext
+        ? await handleAgentContextAction(body, rawChatId)
+        : await handleChatFreeAction(body);
+      if (result) {
+        logDebug("gateway", `${action} ${where} ${Date.now() - t0}ms`);
+        return result;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("gateway", `${action} (${where}) failed: ${msg}`);
+      return { ok: false, error: `${action}: ${msg}` };
+    }
+    return null;
+  }
+
   private async handleAction(body: Record<string, unknown>): Promise<unknown> {
     // Route by _chatId from the MCP subprocess request.
     // _chatId may be a string (Teams: "teams_chat_19:...") or numeric string
@@ -251,32 +302,12 @@ export class Gateway {
     // active-context-required check — the action handler will reach the
     // chat directly via the Telegram Bot API. The legacy context-required
     // path remains for chat-mode calls where `chat_id` is absent.
-    // Chat-free actions (the device mesh) short-circuit routing entirely:
-    // they read daemon-wide state, ignore chatId, and are the only command
-    // channel a heartbeat run has to a remote box. Gating them behind an
-    // active chat made the whole mesh unreachable from background runs —
-    // and unlike send/react they carry no `chat_id` param to promote.
-    const requestedAction =
-      typeof body.action === "string" ? body.action : undefined;
-    if (requestedAction && isChatFreeAction(requestedAction)) {
-      const t0 = Date.now();
-      try {
-        const result = await handleChatFreeAction(body);
-        if (result) {
-          logDebug(
-            "gateway",
-            `${requestedAction} chat=none ${Date.now() - t0}ms (chat-free)`,
-          );
-          return result;
-        }
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logError("gateway", `${requestedAction} (chat-free) failed: ${msg}`);
-        return { ok: false, error: `${requestedAction}: ${msg}` };
-      }
-    }
-
+    // Actions that need no chat at all (the device mesh, and a sub-agent's
+    // own tool family) short-circuit routing — see `dispatchWithoutChat`.
     const rawChatId = body._chatId ? String(body._chatId) : "";
+    const unrouted = await this.dispatchWithoutChat(body, rawChatId);
+    if (unrouted) return unrouted;
+
     const numericId = Number(rawChatId);
     const explicitChatIdProvided = typeof body.chat_id !== "undefined";
     let chatId: number | null = null;
@@ -359,8 +390,38 @@ export class Gateway {
 
   // ── HTTP server ──────────────────────────────────────────────────────────
 
+  /**
+   * Bind the action gateway's HTTP server, returning the bound port.
+   *
+   * Single-flight: every frontend calls this from its own `start()`, and
+   * `app.ts` starts the non-stdin frontends concurrently with `Promise.all`,
+   * so two or more callers routinely land here at once. All of them await the
+   * same bind and get the same port; the FIRST caller's requested port is the
+   * one attempted (later callers' `port` arguments are ignored), and
+   * `onStarted` listeners fire exactly once. Without this, each caller built
+   * its own `http.Server` and `listenWithRetry` walked them onto consecutive
+   * ports — one process listening on :19876 AND :19877, `/health` and the
+   * pidfile disagreeing about which, and `stop()` leaking the other listener.
+   *
+   * A failed bind clears the in-flight state, so a later `start()` retries;
+   * so does `stop()`, so start-after-stop binds afresh.
+   */
   async start(port = 19876): Promise<number> {
     if (this.server) return this.port;
+    if (this.starting) return this.starting;
+    const attempt = this.bind(port);
+    this.starting = attempt;
+    try {
+      return await attempt;
+    } finally {
+      // Only clear our own attempt — never a newer one started after a
+      // stop() that raced this bind.
+      if (this.starting === attempt) this.starting = null;
+    }
+  }
+
+  /** The actual bind. Always called through `start()`'s single-flight guard. */
+  private async bind(port: number): Promise<number> {
     const host: GatewayRouteHost = {
       healthSnapshot: () => this.healthSnapshot(),
       requestShutdown: () => {
@@ -427,6 +488,15 @@ export class Gateway {
   }
 
   async stop(): Promise<void> {
+    // A start() racing this stop() would otherwise hand us back a bound
+    // server with nothing left to close it. Let it finish first.
+    if (this.starting) {
+      try {
+        await this.starting;
+      } catch {
+        // The bind failed — nothing was left listening.
+      }
+    }
     return new Promise((resolve) => {
       if (!this.server) {
         resolve();
@@ -435,6 +505,7 @@ export class Gateway {
       const server = this.server;
       const settle = (): void => {
         this.server = null;
+        this.starting = null;
         this.port = 0;
         resolve();
       };

package/src/core/frontend-runtime/capabilities.ts

@@ -33,6 +33,12 @@ import type { FrontendDescriptor } from "./registry.js";
  * The runtime interface every frontend implements (moved here from
  * `bootstrap.ts`; `bootstrap.ts` re-exports it for existing importers).
  * Lifecycle: `create → init → start → stop`.
+ *
+ * `start()` resolves at STARTED, never at STOPPED. A frontend that kept
+ * its run-until-stopped loop as the `start()` promise made the boot end
+ * at shutdown: boot metrics, the resource sampler and the "Ready in …"
+ * line all fired hours late, and anything the composition root
+ * sequenced after the await never ran while the daemon was alive.
  */
 export type Frontend = {
   /** Registry id of the frontend that created this instance. */
@@ -42,7 +48,19 @@ export type Frontend = {
   sendMessage: (chatId: number, text: string) => Promise<void>;
   getBridgePort: () => number;
   init: () => Promise<void>;
+  /**
+   * Bring the surface up and resolve once it is LISTENING: bot identity
+   * fetched and polling running, socket connecting, server bound, prompt
+   * loop drawn. A frontend with a run-until-stopped loop (long-poll,
+   * reconnect loop) keeps that promise internally — see
+   * `runUntilStopped` in `run-loop.ts` — and awaits it in `stop()`.
+   * Rejecting means the frontend never came up; the boot fails loudly.
+   */
   start: () => Promise<void>;
+  /**
+   * Take the surface down and resolve once it is fully stopped,
+   * including the run loop `start()` left running.
+   */
   stop: () => Promise<void>;
 };
 

package/src/core/frontend-runtime/index.ts

@@ -10,6 +10,10 @@
 import "./builtins.js";
 
 export type { Frontend } from "./capabilities.js";
+export { startFrontends } from "./lifecycle.js";
+// `runUntilStopped` (run-loop.js) is imported by the frontends that own a
+// run loop, straight from its module — it is not part of the composition
+// root's surface.
 export {
   getFrontendDescriptor,
   hasFrontend,

package/src/core/frontend-runtime/lifecycle.ts

@@ -0,0 +1,33 @@
+/**
+ * Frontend lifecycle sequencing for the composition roots (`app.ts`,
+ * `cli/chat.ts`).
+ *
+ * One rule, no per-frontend special cases: `start()` resolves when the
+ * frontend is listening (`capabilities.ts`), so bringing the daemon up
+ * is "start them all, wait for readiness" — and whatever the caller
+ * sequences afterwards (boot metrics, the resource sampler, the "Ready
+ * in …" line) runs at the true end of the boot.
+ */
+
+import { log } from "../../util/log.js";
+import type { Frontend } from "./capabilities.js";
+import { getFrontendDescriptor } from "./registry.js";
+
+/**
+ * Start every configured frontend in parallel and resolve once they are
+ * all listening. Rejects as soon as one fails to come up.
+ */
+export async function startFrontends(
+  frontends: readonly Frontend[],
+): Promise<void> {
+  const sharesStdin = frontends.some(
+    (frontend) => getFrontendDescriptor(frontend.name)?.sharesStdin === true,
+  );
+  if (sharesStdin && frontends.length > 1) {
+    log(
+      "bot",
+      "Terminal frontend shares stdin with the other frontends; keystrokes here reach the terminal prompt only.",
+    );
+  }
+  await Promise.all(frontends.map((frontend) => frontend.start()));
+}

package/src/core/frontend-runtime/registry.ts

@@ -65,9 +65,9 @@ export type FrontendDescriptor = {
    */
   messaging: boolean;
   /**
-   * Reads stdin interactively, so `start()` blocks for the process
-   * lifetime. The composition root starts such frontends without
-   * awaiting them when they run alongside others.
+   * Reads stdin interactively (terminal only). Its `start()` returns
+   * like any other frontend's — this says that keystrokes belong to it,
+   * which the composition root notes when it runs alongside others.
    */
   sharesStdin?: boolean;
 };

package/src/core/frontend-runtime/run-loop.ts

@@ -0,0 +1,59 @@
+/**
+ * The "started, not stopped" seam for frontends that own a
+ * run-until-stopped loop (Telegram's long-poll, WhatsApp's reconnect
+ * loop).
+ *
+ * Those loops resolve when the frontend STOPS, which is the opposite of
+ * what `start()` promises (`capabilities.ts`). This splits one loop into
+ * the two signals the lifecycle actually needs: `ready`, which settles
+ * the moment the loop reports it is listening, and `stopped`, the loop
+ * itself — kept by the frontend and awaited in `stop()`.
+ */
+
+/** A split run loop: readiness for `start()`, the loop itself for `stop()`. */
+export type RunHandle = {
+  /** Resolves when the loop signalled readiness; rejects if it failed first. */
+  ready: Promise<void>;
+  /** Resolves when the loop has ended. Never rejects — see `onError`. */
+  stopped: Promise<void>;
+};
+
+/**
+ * Run `loop`, handing it the callback that marks the frontend listening.
+ *
+ * A loop that ends — or throws — before it ever signalled readiness
+ * settles `ready` anyway: a boot must fail or proceed, never hang on a
+ * surface that already gave up. `onError` receives a failure the loop
+ * hits after readiness, which nothing else would ever observe.
+ */
+export function runUntilStopped(
+  loop: (signalReady: () => void) => Promise<void>,
+  onError: (err: unknown) => void,
+): RunHandle {
+  let resolveReady!: () => void;
+  let rejectReady!: (err: unknown) => void;
+  const ready = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  let readyState: "pending" | "resolved" | "rejected" = "pending";
+  const markReady = (): void => {
+    if (readyState !== "pending") return;
+    readyState = "resolved";
+    resolveReady();
+  };
+  const running = loop(markReady);
+  // Settle `ready` on the loop's own outcome too: a loop that ends (or
+  // fails) before signalling readiness must not leave the boot hanging.
+  running.then(markReady, (err: unknown) => {
+    if (readyState !== "pending") return;
+    readyState = "rejected";
+    rejectReady(err);
+  });
+  const stopped = running.catch((err: unknown) => {
+    // A failure before readiness is already the caller's — `start()`
+    // rejects with it. Only report what nobody else would see.
+    if (readyState !== "rejected") onError(err);
+  });
+  return { ready, stopped };
+}

package/src/core/mesh/{registry.ts → devices/registry.ts}

@@ -8,9 +8,9 @@
  */
 
 import { resolve } from "node:path";
-import { logWarn } from "../../util/log.js";
-import { dirs } from "../../util/paths.js";
-import { readArray, writePrivateJson } from "./persist.js";
+import { logWarn } from "../../../util/log.js";
+import { dirs } from "../../../util/paths.js";
+import { readArray, writePrivateJson } from "../persist.js";
 import {
   sanitizeCapabilities,
   toDeviceInfo,
@@ -18,7 +18,7 @@ import {
   type DeviceInfo,
   type DeviceLocation,
   type DevicePlatform,
-} from "./types.js";
+} from "../types.js";
 
 /**
  * A device is offline once it misses several heartbeats. The companion

package/src/core/mesh/{service.ts → devices/service.ts}

@@ -35,24 +35,27 @@
 
 import { randomUUID } from "node:crypto";
 import type { Readable } from "node:stream";
-import { clampExecOutput } from "../../util/exec-output.js";
-import { BridgeLinks, type MeshBridgeInfo } from "./bridge-links.js";
+import { clampExecOutput } from "../../../util/exec-output.js";
+import { BridgeLinks, type MeshBridgeInfo } from "../links/bridge-links.js";
 import {
   age,
   formatBytes,
   FS_COMMAND_TIMEOUT_MS,
   requirePath,
   type MeshToolResult,
-} from "./common.js";
-import { DeviceFiles } from "./device-files.js";
-import { resolveNodeBinary, type NodeBinaryResolver } from "./node-binaries.js";
+} from "../tool-surface.js";
+import { DeviceFiles } from "../transfers/device-files.js";
+import {
+  resolveNodeBinary,
+  type NodeBinaryResolver,
+} from "../links/node-binaries.js";
 import { MeshRegistry } from "./registry.js";
 import type {
   DeviceCommand,
   DeviceCommandResult,
   DeviceInfo,
   DeviceLocation,
-} from "./types.js";
+} from "../types.js";
 
 /** How a transport pushes mesh traffic to connected companion devices. */
 export type MeshTransport = {
@@ -62,7 +65,7 @@ export type MeshTransport = {
   command(command: DeviceCommand): void;
 };
 
-export type { MeshToolResult } from "./common.js";
+export type { MeshToolResult } from "../tool-surface.js";
 
 /** Outcome of pinging one device (see {@link MeshService.pingAll}). */
 export type MeshPingResult = {
@@ -88,7 +91,7 @@ export type MeshServiceOptions = {
   nodeBinaryResolver?: NodeBinaryResolver;
 };
 
-export type { MeshBridgeInfo } from "./bridge-links.js";
+export type { MeshBridgeInfo } from "../links/bridge-links.js";
 
 const DEFAULT_FRESH_FIX_TIMEOUT_MS = 8_000;
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
@@ -604,7 +607,7 @@ export class MeshService {
     return { ok: true, text: `${p} — ${fields.join(" · ")}` };
   }
 
-  // ── File transfer + self-update (see device-files.ts) ─────────────────────
+  // ── File transfer + self-update (see transfers/device-files.ts) ───────────
 
   /** POST /devices/file — a device streams a pull's file body up. */
   acceptFileUpload(
@@ -681,7 +684,7 @@ export class MeshService {
     return this.files.updateNodeBinary(query, localBinaryPath, remotePath);
   }
 
-  // ── Provisioning + pairing (see bridge-links.ts) ──────────────────────────
+  // ── Provisioning + pairing (see links/bridge-links.ts) ────────────────────
 
   /** `get_node_binary`: materialize a talon-node binary on the daemon host. */
   getNodeBinary(os: unknown, arch: unknown): Promise<MeshToolResult> {