talon-agent 3.31.0 → 3.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.31.0",
+  "version": "3.32.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/core/mesh/companion-pairing.ts

@@ -0,0 +1,181 @@
+/**
+ * CompanionPairStore — one-time grants that connect a phone to this bridge
+ * without anyone typing a host, a port, or a bearer token.
+ *
+ * The problem it removes: a companion joins the mesh by being told the
+ * bridge's address, its bearer token, and (over TLS) the certificate
+ * fingerprint to pin. Reading those off a terminal and typing them into a
+ * phone is the single worst step in setting Talon up, and a mistyped token
+ * fails in a way that looks like a network problem.
+ *
+ * So the daemon mints a grant and hands out ONE link. The bridge serves it
+ * on a route that must work pre-auth — the phone holds no credential yet, so
+ * the grant token IS the authorization, the same trust model as node
+ * provisioning (node-provision.ts) and streamed transfers (transfers.ts):
+ * random 192-bit, single-use, expiring unused.
+ *
+ *   GET /pair?grant=<token>              → the pairing page (once)
+ *   GET /pair?grant=<token>&format=json  → the same payload as JSON
+ *
+ * Opening the link on the phone lands on a page whose button is a
+ * `talon://pair` deep link carrying the credentials, so the companion fills
+ * its own connection form. The page also prints the values for anyone who
+ * would rather type them, because a deep link is exactly the thing that
+ * silently does nothing when the app isn't installed.
+ *
+ * The grant is consumed by whichever leg is served first, and both legs
+ * render the same claimed grant — by the time a page has rendered, the
+ * credentials are already on the phone, so a second serve would only widen
+ * the window for someone else to replay the URL.
+ */
+
+import { randomBytes } from "node:crypto";
+
+/** Unclaimed grants die after this long. A pairing link is used at once. */
+const GRANT_TTL_MS = 10 * 60 * 1000;
+
+export type CompanionPairGrant = {
+  token: string;
+  /** Bridge base URL as reachable from the phone. */
+  bridgeUrl: string;
+  /** Bearer token the companion will authenticate with. */
+  bearerToken: string;
+  /** Bridge TLS certificate fingerprint to pre-pin (absent over plain HTTP). */
+  fingerprint?: string;
+  /** What this daemon calls itself, so the phone can label the connection. */
+  label?: string;
+  createdAt: number;
+  used: boolean;
+};
+
+/** What the phone needs to connect, as served to the companion. */
+export type CompanionPairPayload = {
+  url: string;
+  token: string;
+  fingerprint?: string;
+  label?: string;
+};
+
+export class CompanionPairStore {
+  private readonly grants = new Map<string, CompanionPairGrant>();
+
+  constructor(private readonly ttlMs = GRANT_TTL_MS) {}
+
+  create(
+    grant: Omit<CompanionPairGrant, "token" | "createdAt" | "used">,
+  ): CompanionPairGrant {
+    this.sweep();
+    const full: CompanionPairGrant = {
+      ...grant,
+      // The label is interpolated into generated HTML and a URL query —
+      // keep it to characters that can't carry markup out of either.
+      ...(grant.label
+        ? { label: grant.label.replace(/[^\w .-]+/g, "").slice(0, 64) }
+        : {}),
+      token: randomBytes(24).toString("base64url"),
+      createdAt: Date.now(),
+      used: false,
+    };
+    this.grants.set(full.token, full);
+    return full;
+  }
+
+  /** Resolve a live grant — once. */
+  claim(token: string): CompanionPairPayload | null {
+    this.sweep();
+    const grant = this.grants.get(token);
+    if (!grant || grant.used) return null;
+    grant.used = true;
+    this.grants.delete(token);
+    return {
+      url: grant.bridgeUrl,
+      token: grant.bearerToken,
+      ...(grant.fingerprint ? { fingerprint: grant.fingerprint } : {}),
+      ...(grant.label ? { label: grant.label } : {}),
+    };
+  }
+
+  private sweep(): void {
+    const cutoff = Date.now() - this.ttlMs;
+    for (const [token, grant] of this.grants) {
+      if (grant.createdAt < cutoff) this.grants.delete(token);
+    }
+  }
+}
+
+/** The link a human opens on the phone. */
+export function pairLink(grant: CompanionPairGrant): string {
+  return `${grant.bridgeUrl}/pair?grant=${grant.token}`;
+}
+
+/**
+ * The `talon://pair` deep link the companion registers for. Carries the
+ * credentials themselves rather than the grant, because the grant is spent
+ * by the time this reaches the phone — and because a deep link that needed
+ * another round trip would fail on exactly the flaky first connection it
+ * exists to make painless.
+ */
+export function pairDeepLink(payload: CompanionPairPayload): string {
+  const q = new URLSearchParams({ u: payload.url, t: payload.token });
+  if (payload.fingerprint) q.set("f", payload.fingerprint);
+  if (payload.label) q.set("n", payload.label);
+  return `talon://pair?${q.toString()}`;
+}
+
+/** Minimal HTML escape for the values interpolated into the pairing page. */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * The page the phone lands on. Deliberately one self-contained file with no
+ * external assets: it is served by a bridge the browser has usually just
+ * warned about (self-signed cert), often over a LAN with no internet route,
+ * and a page that half-loads there is worse than no page at all.
+ */
+export function pairPage(payload: CompanionPairPayload): string {
+  const deep = pairDeepLink(payload);
+  const fp = payload.fingerprint;
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect to Talon</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; padding: 24px; font: 15px/1.5 system-ui, sans-serif; }
+  main { max-width: 32rem; margin: 0 auto; }
+  h1 { font-size: 1.25rem; margin: 0 0 .25rem; }
+  p.sub { margin: 0 0 1.5rem; opacity: .7; }
+  a.go { display: block; text-align: center; padding: 14px; border-radius: 10px;
+         background: #2f6fed; color: #fff; text-decoration: none; font-weight: 600; }
+  dl { margin: 1.5rem 0 0; }
+  dt { font-size: .8rem; text-transform: uppercase; letter-spacing: .04em; opacity: .6; margin-top: 1rem; }
+  dd { margin: .2rem 0 0; font-family: ui-monospace, monospace; font-size: .85rem; word-break: break-all; }
+  footer { margin-top: 2rem; font-size: .8rem; opacity: .6; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Connect to Talon</h1>
+  <p class="sub">${payload.label ? esc(payload.label) : "This daemon"} is ready to pair.</p>
+  <a class="go" href="${esc(deep)}">Open in Talon</a>
+  <dl>
+    <dt>Bridge</dt><dd>${esc(payload.url)}</dd>
+    <dt>Token</dt><dd>${esc(payload.token)}</dd>
+    ${fp ? `<dt>Certificate</dt><dd>${esc(fp)}</dd>` : ""}
+  </dl>
+  <footer>
+    If the button does nothing, the companion isn't installed yet — install it,
+    then enter the values above by hand. This link is single-use and is now spent.
+  </footer>
+</main>
+</body>
+</html>
+`;
+}

package/src/core/mesh/service.ts

@@ -43,6 +43,12 @@ import {
   resolveNodeBinary,
   type NodeBinaryResolver,
 } from "./node-binaries.js";
+import {
+  CompanionPairStore,
+  pairLink,
+  pairPage,
+  type CompanionPairPayload,
+} from "./companion-pairing.js";
 import { installOneLiner, NodeProvisionStore } from "./node-provision.js";
 import { MeshRegistry } from "./registry.js";
 import { TransferStore } from "./transfers.js";
@@ -174,6 +180,8 @@ export class MeshService {
   private readonly transfers = new TransferStore();
   /** 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 readonly resolveNode: NodeBinaryResolver;
   private bridgeInfo: MeshBridgeInfo | null = null;
   private readonly freshFixTimeoutMs: number;
@@ -1162,6 +1170,112 @@ export class MeshService {
     };
   }
 
+  /**
+   * 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);

package/src/frontend/native/index.ts

@@ -1263,6 +1263,7 @@ export function createNativeFrontend(
       mesh.acceptFileUpload(token, body, fromDeviceId),
     openFileDownload: (token, fromDeviceId) =>
       mesh.openFileDownload(token, fromDeviceId),
+    openCompanionPair: (token, format) => mesh.openCompanionPair(token, format),
     openNodeInstall: (token) => mesh.openNodeInstall(token),
     openNodeBinary: (token) => mesh.openNodeBinary(token),
   };

package/src/frontend/native/server.ts

@@ -145,6 +145,11 @@ export type BridgeServerHandlers = {
     token: string,
     fromDeviceId?: string,
   ): Promise<{ path: string; size: number } | null>;
+  /** Resolve a companion-pairing grant to its page/payload, or null. */
+  openCompanionPair(
+    token: string,
+    format: "html" | "json",
+  ): { contentType: string; body: string } | null;
   /** Resolve a node-provisioning token to its installer script, or null. */
   openNodeInstall(token: string): { script: string; filename: string } | null;
   /** Resolve a node-provisioning token to the binary to stream, or null. */
@@ -464,6 +469,34 @@ export class BridgeServer {
       });
     }
 
+    // Companion pairing is PRE-AUTH for the same reason as node
+    // provisioning below: the phone holds no bridge credential yet, and the
+    // single-use grant is what it comes to collect. Serving the page IS the
+    // handover, so the grant is spent whichever leg is hit.
+    if (method === "GET" && path === "/pair") {
+      const token = url.searchParams.get("grant") ?? "";
+      const wantsJson =
+        url.searchParams.get("format") === "json" ||
+        (req.headers.accept ?? "").includes("application/json");
+      const served = token
+        ? this.handlers.openCompanionPair(token, wantsJson ? "json" : "html")
+        : null;
+      if (!served) {
+        return this.json(res, 404, {
+          ok: false,
+          error: "Unknown, expired, or already-used pairing link",
+        });
+      }
+      res.writeHead(200, {
+        "Content-Type": served.contentType,
+        // A pairing payload is a credential; nothing may keep a copy.
+        "Cache-Control": "no-store",
+        ...this.corsHeaders(),
+      });
+      res.end(served.body);
+      return;
+    }
+
     // Node provisioning runs PRE-AUTH by design: the target host holds no
     // bridge credential yet — the single-use grant token (minted by
     // make_node_install_link, expiring, one serve per leg) is the entire

package/src/frontend/telegram/commands/definitions.ts

@@ -22,7 +22,10 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
   },
   { command: "status", description: "Session info, usage, and stats" },
   { command: "ping", description: "Health check with latency" },
-  { command: "mesh", description: "Ping and list mesh devices" },
+  {
+    command: "mesh",
+    description: "Mesh devices; /mesh link pairs a new one",
+  },
   { command: "model", description: "Show or change model" },
   { command: "effort", description: "Set thinking effort level" },
   { command: "pulse", description: "Conversation engagement settings" },

package/src/frontend/telegram/commands/info.ts

@@ -2,10 +2,16 @@
  * Informational commands — /start, /help, /ping, /plugins.
  */
 
-import type { Bot } from "grammy";
+import type { Bot, Context } from "grammy";
 import { isUserClientReady } from "../userbot.js";
 import { escapeHtml } from "../formatting.js";
-import { formatDuration, renderMeshReport } from "../helpers/index.js";
+import {
+  formatDuration,
+  renderMeshPairLink,
+  renderMeshReport,
+  type MeshReachability,
+} from "../helpers/index.js";
+import { isAuthorizedAdmin } from "./state.js";
 import { getLoadedPlugins } from "../../../core/plugin/index.js";
 import { getMeshService } from "../../../core/mesh/index.js";
 import type { MeshPingResult } from "../../../core/mesh/service.js";
@@ -104,7 +110,49 @@ export function registerInfoCommands(bot: Bot): void {
     }
   });
 
+  /**
+   * The bridge footer `/mesh` prints for this caller.
+   *
+   * The admin gets the whole connection profile — URL, bearer token,
+   * certificate — because an operator asking their own daemon how to reach
+   * itself should get an answer rather than a scavenger hunt through config
+   * files. Everyone else gets the address only: a group member reading the
+   * fleet has no business holding the key to it.
+   */
+  const bridgeFor = (ctx: Context): MeshReachability => {
+    const reach = getMeshService().bridgeReachability();
+    if (!reach.ok || isAuthorizedAdmin(ctx)) return reach;
+    return {
+      ok: true,
+      url: reach.url,
+      authRequired: reach.authRequired,
+    };
+  };
+
   bot.command("mesh", async (ctx) => {
+    const arg = (ctx.match ?? "").toString().trim();
+    // `/mesh link` mints a bridge credential and posts it into the chat, so
+    // it is admin-gated even though plain `/mesh` is not — reading the fleet
+    // is not the same act as handing out the keys to it.
+    if (/^(link|pair)\b/i.test(arg)) {
+      if (!isAuthorizedAdmin(ctx)) {
+        await ctx.reply("Only the configured admin can mint a pairing link.");
+        return;
+      }
+      // `/mesh link Car` names the connection on the phone; with no name it
+      // inherits the bot's, which is what the operator already calls this
+      // daemon everywhere else.
+      const named = arg.replace(/^(link|pair)\b/i, "").trim();
+      const minted = getMeshService().makeCompanionPairLink(
+        named || ctx.me.first_name,
+      );
+      await ctx.reply(renderMeshPairLink(minted), {
+        parse_mode: "HTML",
+        link_preview_options: { is_disabled: true },
+      });
+      return;
+    }
+
     const sent = await ctx.reply("Pinging mesh devices…");
     let results: MeshPingResult[];
     try {
@@ -122,7 +170,7 @@ export function registerInfoCommands(bot: Bot): void {
       bot,
       ctx.chat.id,
       sent.message_id,
-      renderMeshReport(results),
+      renderMeshReport(results, Date.now(), bridgeFor(ctx)),
     );
   });
 

package/src/frontend/telegram/helpers/diagnostics.ts

@@ -310,9 +310,18 @@ function meshDeviceLine(r: MeshPingResult, now: number): string {
 export function renderMeshReport(
   results: MeshPingResult[],
   now = Date.now(),
+  bridge?: MeshReachability,
 ): string {
   if (results.length === 0) {
-    return "<b>Mesh</b>\n\n<i>No devices have registered yet.</i>";
+    // An empty fleet is the one case where "what do I point a device at?" is
+    // the only useful thing to say, so the bridge line carries the answer
+    // instead of leaving the operator to hunt for host and port.
+    return [
+      "<b>Mesh</b>",
+      "",
+      "<i>No devices have registered yet.</i>",
+      ...bridgeLines(bridge),
+    ].join("\n");
   }
 
   const responding = results
@@ -344,6 +353,76 @@ export function renderMeshReport(
   section("Responding", responding);
   section("Unreachable", unreachable);
   section("Offline", offline);
+  lines.push(...bridgeLines(bridge));
 
   return lines.join("\n");
 }
+
+/** What `/mesh` says about the bridge a new device would dial. */
+export type MeshReachability =
+  | {
+      ok: true;
+      url: string;
+      authRequired: boolean;
+      token?: string;
+      fingerprint?: string;
+    }
+  | { ok: false; text: string };
+
+/**
+ * The bridge footer.
+ *
+ * The bearer token and certificate appear when the caller passed them, which
+ * `/mesh` does for the configured admin and not for anyone else: an operator
+ * asking their own daemon how to reach itself should get the answer, while a
+ * group member reading the fleet has no business holding the key to it.
+ */
+function bridgeLines(bridge?: MeshReachability): string[] {
+  if (!bridge) return [];
+  if (!bridge.ok) return ["", `<b>Bridge</b> — ${escapeHtml(bridge.text)}`];
+  const auth = bridge.authRequired ? "token required" : "no token";
+  return [
+    "",
+    `<b>Bridge</b> <code>${escapeHtml(bridge.url)}</code> · ${auth}`,
+    ...(bridge.token ? [`Token <code>${escapeHtml(bridge.token)}</code>`] : []),
+    ...(bridge.fingerprint
+      ? [`Certificate <code>${escapeHtml(bridge.fingerprint)}</code>`]
+      : []),
+    "Run <code>/mesh link</code> for a one-tap pairing link.",
+  ];
+}
+
+/**
+ * Render a minted pairing link, or why one couldn't be minted.
+ *
+ * The values are printed alongside the link because the link's whole payoff
+ * — the phone configuring itself — depends on the companion already being
+ * installed, and the fallback needs to be right there when it isn't.
+ */
+export function renderMeshPairLink(
+  minted:
+    | {
+        ok: true;
+        link: string;
+        url: string;
+        token: string;
+        fingerprint?: string;
+      }
+    | { ok: false; text: string },
+): string {
+  if (!minted.ok) {
+    return `<b>Pairing</b>\n\n${escapeHtml(minted.text)}`;
+  }
+  return [
+    "<b>Pair a device</b>",
+    "",
+    `Open on the phone: ${escapeHtml(minted.link)}`,
+    "",
+    "Single-use, expires in 10 minutes. If the companion isn't installed yet:",
+    `  Bridge <code>${escapeHtml(minted.url)}</code>`,
+    `  Token <code>${escapeHtml(minted.token)}</code>`,
+    ...(minted.fingerprint
+      ? [`  Certificate <code>${escapeHtml(minted.fingerprint)}</code>`]
+      : []),
+  ].join("\n");
+}