talon-agent 3.32.1 → 3.33.1

package/src/cli/status.ts

@@ -9,7 +9,7 @@ import { findRunningInstance } from "../core/daemon/discovery.js";
 import { printBanner, loadConfig } from "./config.js";
 import { CONFIG_FILE } from "./context.js";
 
-export function formatUptime(seconds: number): string {
+function formatUptime(seconds: number): string {
   if (seconds < 60) return `${seconds}s`;
   if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
   return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;

package/src/core/agent-runtime/backend-registry.ts

@@ -58,7 +58,7 @@ export interface BackendInitContext {
 }
 
 /** Result returned by a backend factory's `init` step. */
-export interface BackendInstance {
+interface BackendInstance {
   /** The fully-wired `Backend` the dispatcher will route to. */
   backend: Backend;
   /**

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

@@ -188,7 +188,7 @@ export interface SessionBackend {
  * the live registry. Returns the diff so the dispatcher can log
  * what changed.
  */
-export interface ToolRefreshResult {
+interface ToolRefreshResult {
   added: string[];
   removed: string[];
   errors: Record<string, string>;

package/src/core/agent-runtime/events.ts

@@ -81,7 +81,7 @@ export interface AgentResult {
  * `core/errors.ts` already produces — keep the values stable so
  * downstream code can pattern-match deterministically.
  */
-export type AgentErrorKind =
+type AgentErrorKind =
   | "context_overflow"
   | "rate_limit"
   | "overload"

package/src/core/background/heartbeat/agent.ts

@@ -83,7 +83,7 @@ export function buildHeartbeatSystemPrompt(): string {
  * the heartbeat is a global agent, so it sees every chat's open goals (with
  * chat ids for routing updates back). Exported for tests.
  */
-export function renderGoalsBlock(): { text: string; count: number } {
+function renderGoalsBlock(): { text: string; count: number } {
   let text = "(no open goals)";
   let count = 0;
   try {

package/src/core/background/heartbeat/index.ts

@@ -13,7 +13,6 @@
  * Re-exports the same public surface the old single-file module exposed.
  */
 
-export type { HeartbeatState } from "./state.js";
 export {
   initHeartbeat,
   startHeartbeatTimer,
@@ -22,4 +21,4 @@ export {
   forceHeartbeat,
   getHeartbeatStatus,
 } from "./scheduler.js";
-export { buildHeartbeatSystemPrompt, renderGoalsBlock } from "./agent.js";
+export { buildHeartbeatSystemPrompt } from "./agent.js";

package/src/core/background/isolated-agent.ts

@@ -19,7 +19,7 @@ import type { OneShotAgentParams, OneShotUsage } from "../types.js";
 import { logWarn, logError } from "../../util/log.js";
 
 /** Default bounded grace after an abort before giving up on the backend. */
-export const DEFAULT_ABORT_GRACE_MS = 30 * 1000;
+const DEFAULT_ABORT_GRACE_MS = 30 * 1000;
 
 export interface IsolatedRunOptions {
   readonly background: BackgroundRunner;

package/src/core/background/triggers/exit.ts

@@ -79,7 +79,7 @@ export async function shutdownTriggers(): Promise<void> {
   await new Promise((r) => setTimeout(r, 250));
 }
 
-export function killChild(id: string, child: ChildProcess): void {
+function killChild(id: string, child: ChildProcess): void {
   try {
     child.kill("SIGTERM");
   } catch {

package/src/core/background/triggers/index.ts

@@ -19,7 +19,7 @@ import { commandForLanguage } from "./command.js";
 import { handleStdoutLine } from "./output.js";
 import { handleTimeout, finalizeExit } from "./exit.js";
 
-export { initTriggers, getRunningCount, type TriggerDeps } from "./state.js";
+export { initTriggers, getRunningCount } from "./state.js";
 export { commandForLanguage } from "./command.js";
 export { spawnTrigger } from "./spawn.js";
 export { cancelTrigger, shutdownTriggers } from "./exit.js";

package/src/core/bus/events.ts

@@ -32,7 +32,7 @@ export interface TaskSettledEvent {
 }
 
 /** A chat turn bound its warp and is about to run on the backend. */
-export interface TurnStartedEvent {
+interface TurnStartedEvent {
   readonly type: "turn.started";
   readonly chatId: string;
   readonly source: string;
@@ -41,7 +41,7 @@ export interface TurnStartedEvent {
 }
 
 /** A chat turn finished successfully (refusals and failures never emit this). */
-export interface TurnCompletedEvent {
+interface TurnCompletedEvent {
   readonly type: "turn.completed";
   readonly chatId: string;
   readonly source: string;

package/src/core/doctor.ts

@@ -17,7 +17,7 @@ import { execFileSync } from "node:child_process";
 import { NATIVE_MODULES } from "../native/registry.js";
 import { dirs } from "../util/paths.js";
 
-export type DoctorStatus = "ok" | "warn" | "fail" | "info";
+type DoctorStatus = "ok" | "warn" | "fail" | "info";
 
 export interface DoctorCheck {
   label: string;

package/src/core/engine/backend-controller/index.ts

@@ -28,7 +28,7 @@
  */
 
 export * from "./types.js";
-export { roleHolder, chatHolder } from "./holders.js";
+export { roleHolder } from "./holders.js";
 export {
   initBackendPool,
   hasBackendPool,
@@ -48,8 +48,6 @@ export {
   clearBackendChangeListenersForTest,
 } from "./pool.js";
 export {
-  rebindHolder,
-  releaseHolder,
   rebindRole,
   rebindChat,
   releaseChat,

package/src/core/engine/backend-controller/rebind.ts

@@ -36,7 +36,7 @@ import type { BackendHolder, BackendRole, RebindResult } from "./types.js";
  *
  * Use `rebindRole` / `rebindChat` for typed wrappers.
  */
-export async function rebindHolder(
+async function rebindHolder(
   holder: BackendHolder,
   newId: string,
   config: TalonConfig,
@@ -113,7 +113,7 @@ export async function rebindHolder(
  * No-op when the holder isn't bound — useful for "clear my override"
  * flows that don't want to care whether the override was ever set.
  */
-export async function releaseHolder(holder: BackendHolder): Promise<void> {
+async function releaseHolder(holder: BackendHolder): Promise<void> {
   const id = bindings.get(holder);
   if (!id) return;
   bindings.delete(holder);

package/src/core/engine/dispatcher.ts

@@ -11,12 +11,7 @@
 import type { ExecuteParams, ExecuteResult } from "../types.js";
 import { log } from "../../util/log.js";
 import { taskTable, type KillOutcome } from "../tasks/index.js";
-import {
-  initWeaver,
-  type Weaver,
-  type WeaverDeps,
-  type ThreadSnapshot,
-} from "../weaver/index.js";
+import { initWeaver, type Weaver, type WeaverDeps } from "../weaver/index.js";
 
 // ── Dependencies (injected at startup) ──────────────────────────────────────
 
@@ -49,15 +44,6 @@ export function getActiveCount(): number {
   return weaver?.getActiveCount() ?? 0;
 }
 
-/**
- * A live view of every Thread the Loom holds — model/backend warp, in-flight
- * count, and context state per chat. The hub's observability surface for
- * `/status`, drift detection, and remote frontends. Empty before init.
- */
-export function snapshot(): ThreadSnapshot[] {
-  return weaver?.snapshot() ?? [];
-}
-
 /**
  * Stop only this chat's active turn. A later message already waiting in the
  * per-chat FIFO is intentionally left alone and runs after the stop settles.

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

@@ -100,6 +100,3 @@ export async function handleChatFreeAction(
   if (!handler) return null;
   return handler(body, 0);
 }
-
-export { chatFreeActions };
-export type { SharedActionHandler, SharedActionHandlers } from "./types.js";

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

@@ -9,7 +9,7 @@
 import type { ActionResult } from "../../types.js";
 import type { Backend } from "../../agent-runtime/capabilities.js";
 
-export type SharedActionHandler = (
+type SharedActionHandler = (
   body: Record<string, unknown>,
   chatId: number,
   backend?: Backend | null,

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

@@ -58,5 +58,3 @@ export type FrontendCreate = (
 
 /** A fully-registered frontend: identity plus the factory. */
 export type FrontendFactory = FrontendDescriptor & { create: FrontendCreate };
-
-export type { FrontendDescriptor } from "./registry.js";

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

@@ -9,12 +9,7 @@
 
 import "./builtins.js";
 
-export type {
-  Frontend,
-  FrontendCreate,
-  FrontendDescriptor,
-  FrontendFactory,
-} from "./capabilities.js";
+export type { Frontend } from "./capabilities.js";
 export {
   getFrontendDescriptor,
   hasFrontend,

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

@@ -12,5 +12,4 @@ export {
   getFrontendDescriptor,
   resolveFrontendIdAmong,
   resolveOwnerFrontendId,
-  type FrontendDescriptor,
 } from "./registry.js";

package/src/core/mcp-hub/children.ts

@@ -82,11 +82,6 @@ function failureBackoffMs(count: number): number {
   );
 }
 
-/** Test seam: forget recorded spawn failures. */
-export function resetSpawnFailures(): void {
-  spawnFailures.clear();
-}
-
 /** Idle TTL for hub children; tunable for tests / tight deployments. */
 function idleTtlMs(): number {
   const raw = Number(process.env.TALON_MCP_HUB_IDLE_MS);

package/src/core/mesh/bridge-links.ts

@@ -0,0 +1,319 @@
+/**
+ * Bridge links — the MeshService collaborator that hands a device what it
+ * needs to reach this daemon: node provisioning (a single-use installer
+ * link that fetches a digest-verified talon-node binary from the bridge),
+ * companion pairing (a single-use link carrying the bridge URL, token and
+ * certificate fingerprint), and the reachability answer behind both.
+ *
+ * It owns the grant stores and the bridge's self-reported identity; it
+ * never touches devices or commands.
+ */
+
+import { networkInterfaces } from "node:os";
+import {
+  CompanionPairStore,
+  pairLink,
+  pairPage,
+  type CompanionPairPayload,
+} from "./companion-pairing.js";
+import { formatBytes, type MeshToolResult } from "./common.js";
+import {
+  NODE_TARGETS,
+  normalizeGoarch,
+  normalizeGoos,
+  type NodeBinaryResolver,
+} from "./node-binaries.js";
+import { installOneLiner, NodeProvisionStore } from "./node-provision.js";
+
+/**
+ * What the native bridge tells the mesh about itself once it's listening —
+ * everything a generated node installer needs to point a fresh host here.
+ * Registered by the native frontend after server start; null when the
+ * bridge isn't running (provisioning tools then fail with a clear reason).
+ */
+export type MeshBridgeInfo = {
+  scheme: "http" | "https";
+  /** The bind host from config — may be a wildcard (0.0.0.0/::). */
+  host: string;
+  port: number;
+  /** Bearer token clients authenticate with (absent on open loopback). */
+  token?: string;
+  /** TLS certificate SHA-256 (absent over plain HTTP). */
+  fingerprint?: string;
+};
+
+export class BridgeLinks {
+  /** One-time grants for bridge-served node installers. */
+  private readonly provision = new NodeProvisionStore();
+  /** One-time grants that hand a phone this bridge's connection details. */
+  private readonly companionPairs = new CompanionPairStore();
+  private bridgeInfo: MeshBridgeInfo | null = null;
+
+  constructor(private readonly resolveNode: NodeBinaryResolver) {}
+
+  /** The native bridge reports its reachable identity here (null on stop). */
+  setBridgeInfo(info: MeshBridgeInfo | null): void {
+    this.bridgeInfo = info;
+  }
+
+  // ── Node provisioning ──────────────────────────────────────────────────────
+
+  /**
+   * `get_node_binary`: materialize a talon-node binary for any supported
+   * platform/arch on the daemon host — source build in a dev checkout, else
+   * the digest-verified release download (cached under ~/.talon/node-bin).
+   */
+  async getNodeBinary(os: unknown, arch: unknown): Promise<MeshToolResult> {
+    const goos = normalizeGoos(os);
+    const goarch = normalizeGoarch(arch);
+    if (!goos || !goarch) {
+      return { ok: false, text: unknownTargetText(os, arch) };
+    }
+    try {
+      const bin = await this.resolveNode(goos, goarch);
+      return {
+        ok: true,
+        text: `talon-node ${bin.version} for ${goos}/${goarch}: ${bin.path} (${formatBytes(bin.size)}, sha256 ${bin.sha256}, via ${bin.source})`,
+      };
+    } catch (err) {
+      return { ok: false, text: (err as Error).message };
+    }
+  }
+
+  /**
+   * `make_node_install_link`: mint a single-use provisioning URL on the
+   * bridge and return the one command that turns a fresh host into a mesh
+   * node — it fetches the installer script, which downloads the (digest-
+   * verified) binary from the same bridge, installs it, pre-pins the bridge
+   * certificate, and registers the boot service.
+   */
+  async makeNodeInstallLink(
+    os: unknown,
+    arch: unknown,
+    name?: unknown,
+    bridgeUrl?: unknown,
+  ): Promise<MeshToolResult> {
+    const goos = normalizeGoos(os);
+    const goarch = normalizeGoarch(arch);
+    if (!goos || !goarch) {
+      return { ok: false, text: unknownTargetText(os, arch) };
+    }
+    const info = this.bridgeInfo;
+    if (!info) {
+      return {
+        ok: false,
+        text: "The native bridge isn't running, so there is nothing for a new node to connect to. Enable the native frontend first.",
+      };
+    }
+    if (!info.token) {
+      return {
+        ok: false,
+        text: "The bridge has no bearer token (loopback-only bind), and nodes authenticate with one. Set native.host to a reachable address (a token is auto-minted) and restart.",
+      };
+    }
+    const base = this.bridgeBaseUrl(info, bridgeUrl);
+    if (typeof base !== "string") return { ok: false, text: base.error };
+    let bin;
+    try {
+      bin = await this.resolveNode(goos, goarch);
+    } catch (err) {
+      return { ok: false, text: (err as Error).message };
+    }
+    const grant = this.provision.create({
+      goos,
+      goarch,
+      ...(typeof name === "string" && name.trim() ? { name: name.trim() } : {}),
+      binaryPath: bin.path,
+      sha256: bin.sha256,
+      size: bin.size,
+      version: bin.version,
+      bridgeUrl: base,
+      bearerToken: info.token,
+      ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
+    });
+    return {
+      ok: true,
+      text: [
+        `Run this on the new ${goos}/${goarch} host:`,
+        "",
+        `  ${installOneLiner(grant)}`,
+        "",
+        `It installs talon-node ${bin.version} (sha256-verified against ${grant.sha256.slice(0, 12)}…), pins the bridge certificate, and registers a boot service — the host appears on the mesh within a minute.`,
+        `Single-use link, expires in 30 minutes. The host must be able to reach ${base}.`,
+      ].join("\n"),
+    };
+  }
+
+  /**
+   * Mint a single-use link that connects a phone to this bridge without
+   * anyone typing an address or a token — the companion half of
+   * {@link makeNodeInstallLink}.
+   *
+   * Returns the link plus the values it carries, so a caller (a `/mesh`
+   * reply, say) can print both: the link is the one-tap path, the values are
+   * what someone falls back to when the app isn't installed yet.
+   */
+  makeCompanionPairLink(
+    label?: unknown,
+    bridgeUrl?: unknown,
+  ):
+    | {
+        ok: true;
+        link: string;
+        url: string;
+        token: string;
+        fingerprint?: string;
+      }
+    | { ok: false; text: string } {
+    const info = this.bridgeInfo;
+    if (!info) {
+      return {
+        ok: false,
+        text: "The native bridge isn't running, so there is nothing for a phone to connect to. Enable the native frontend first.",
+      };
+    }
+    if (!info.token) {
+      return {
+        ok: false,
+        text: "The bridge has no bearer token (loopback-only bind), and companions authenticate with one. Set native.host to a reachable address (a token is auto-minted) and restart.",
+      };
+    }
+    const base = this.bridgeBaseUrl(info, bridgeUrl);
+    if (typeof base !== "string") return { ok: false, text: base.error };
+    const grant = this.companionPairs.create({
+      bridgeUrl: base,
+      bearerToken: info.token,
+      ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
+      ...(typeof label === "string" && label.trim()
+        ? { label: label.trim() }
+        : {}),
+    });
+    return {
+      ok: true,
+      link: pairLink(grant),
+      url: base,
+      token: info.token,
+      ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
+    };
+  }
+
+  /**
+   * GET /pair — serve a pairing grant (single-use), as the landing page or
+   * as the JSON the companion reads.
+   */
+  openCompanionPair(
+    token: string,
+    format: "html" | "json",
+  ): { contentType: string; body: string } | null {
+    const payload = this.companionPairs.claim(token);
+    if (!payload) return null;
+    return format === "json"
+      ? {
+          contentType: "application/json; charset=utf-8",
+          body: JSON.stringify(payload satisfies CompanionPairPayload),
+        }
+      : {
+          contentType: "text/html; charset=utf-8",
+          body: pairPage(payload),
+        };
+  }
+
+  /**
+   * How this bridge is reachable, for an operator asking "what do I point a
+   * device at?".
+   *
+   * The bearer token comes back with it. Deciding who may see a credential is
+   * the caller's job, not this seam's — the Telegram `/mesh` shows it to the
+   * configured admin and withholds it from everyone else — and an operator who
+   * asked their own daemon for its own connection details should get an
+   * answer, not a lecture.
+   */
+  bridgeReachability():
+    | {
+        ok: true;
+        url: string;
+        authRequired: boolean;
+        token?: string;
+        fingerprint?: string;
+      }
+    | { ok: false; text: string } {
+    const info = this.bridgeInfo;
+    if (!info) return { ok: false, text: "The native bridge isn't running." };
+    const base = this.bridgeBaseUrl(info);
+    if (typeof base !== "string") return { ok: false, text: base.error };
+    return {
+      ok: true,
+      url: base,
+      authRequired: Boolean(info.token),
+      ...(info.token ? { token: info.token } : {}),
+      ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
+    };
+  }
+
+  /** GET /node/install — serve a grant's installer script (single-use). */
+  openNodeInstall(token: string): { script: string; filename: string } | null {
+    return this.provision.openScript(token);
+  }
+
+  /** GET /node/binary — serve a grant's binary (single-use). */
+  openNodeBinary(token: string): { path: string; size: number } | null {
+    return this.provision.openBinary(token);
+  }
+
+  /**
+   * The bridge base URL a NEW host should dial: an explicit override wins;
+   * otherwise derive from the bridge's bind. A wildcard bind maps to this
+   * host's first external IPv4; a loopback bind is unreachable from other
+   * machines, so it's an error rather than a link that can't work.
+   */
+  private bridgeBaseUrl(
+    info: MeshBridgeInfo,
+    explicit?: unknown,
+  ): string | { error: string } {
+    if (typeof explicit === "string" && explicit.trim()) {
+      const url = explicit.trim().replace(/\/+$/, "");
+      if (!/^https?:\/\/\S+$/.test(url)) {
+        return { error: `bridge_url must be an http(s) URL, got "${url}".` };
+      }
+      return url;
+    }
+    let host = info.host;
+    if (host === "0.0.0.0" || host === "::") {
+      const external = firstExternalIPv4();
+      if (!external) {
+        return {
+          error:
+            "Could not determine this host's external address — pass bridge_url explicitly (the URL the new node should dial).",
+        };
+      }
+      host = external;
+    } else if (isLoopbackAddress(host)) {
+      return {
+        error: `The bridge is bound to loopback (${host}), which other machines can't reach. Set native.host to a reachable address, or pass bridge_url if a tunnel exposes it.`,
+      };
+    }
+    return `${info.scheme}://${host}:${info.port}`;
+  }
+}
+
+/** Error text for an os/arch pair outside the talon-node build matrix. */
+function unknownTargetText(os: unknown, arch: unknown): string {
+  return `No talon-node target for os="${String(os)}", arch="${String(arch)}". Supported: ${NODE_TARGETS.map(
+    (t) => `${t.goos}/${t.goarch}`,
+  ).join(", ")} (macos ≡ darwin, x86_64 ≡ amd64, aarch64 ≡ arm64).`;
+}
+
+/** First non-internal IPv4 on this host — the wildcard-bind fallback. */
+function firstExternalIPv4(): string | undefined {
+  for (const list of Object.values(networkInterfaces())) {
+    for (const iface of list ?? []) {
+      if (!iface.internal && iface.family === "IPv4") return iface.address;
+    }
+  }
+  return undefined;
+}
+
+function isLoopbackAddress(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "localhost" || h === "::1" || h.startsWith("127.");
+}

package/src/core/mesh/common.ts

@@ -0,0 +1,30 @@
+/**
+ * Small helpers shared by the mesh service and its collaborators
+ * (device-files.ts, bridge-links.ts).
+ */
+
+/** The model-facing shape every mesh tool answers with. */
+export type MeshToolResult = { ok: boolean; text: string };
+
+/** Timeout for a single filesystem command (list/stat/one chunk/etc.). */
+export const FS_COMMAND_TIMEOUT_MS = 30_000;
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function age(ms: number): string {
+  const sec = Math.max(0, Math.round(ms / 1000));
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hrs = Math.round(min / 60);
+  return `${hrs}h ago`;
+}
+
+/** Trim a string path param, returning undefined when blank. */
+export function requirePath(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}