talon-agent 5.29.0 → 5.30.0

package/src/core/config/index.ts

@@ -642,7 +642,15 @@ const configSchema = z.object({
    *   - `maxDepth` — how far delegation may nest. 0 = chats only, 2 (the
    *     default) = chat → agent → agent.
    *   - `defaultTimeoutMs` — hard wall-clock cap when a spawn doesn't pass
-   *     its own. Per-spawn values are clamped to [30s, 60min].
+   *     its own. Unset (the default) = no hard cap: a run ends when it is
+   *     done, killed, or stalled (see `stallTimeoutMs`).
+   *   - `maxTimeoutMs` — optional global ceiling on every run's hard cap,
+   *     including spawns that pass none. Unset = no ceiling. Per-spawn
+   *     values are floored at 30s.
+   *   - `stallTimeoutMs` — the no-progress watchdog step N (default 15
+   *     min): after N with no tool call or output the agent is pinged,
+   *     after 2N its parent is warned, after 3N it is killed (`timed_out`).
+   *     0 disables it.
    *   - `allowedBackends` — optional allowlist of backend ids sub-agents
    *     may run on. Unset = any backend with a background capability. A
    *     spawn that names (or inherits) a backend outside it is refused.
@@ -651,11 +659,12 @@ const configSchema = z.object({
     .object({
       maxConcurrent: z.number().int().min(1).max(64).default(6),
       maxDepth: z.number().int().min(0).max(5).default(2),
-      defaultTimeoutMs: z
+      defaultTimeoutMs: z.number().int().min(30_000).optional(),
+      maxTimeoutMs: z.number().int().min(30_000).optional(),
+      stallTimeoutMs: z
         .number()
         .int()
-        .min(30_000)
-        .max(3_600_000)
+        .min(0)
         .default(15 * 60 * 1000),
       allowedBackends: z.array(z.string().min(1)).optional(),
     })

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

@@ -16,6 +16,7 @@ import {
   agentIdFromContextLabel,
   agentRegistry,
   clampTimeout,
+  describeTimeout,
   deliverToAgent,
   getAgentCaps,
   killAgent,
@@ -210,7 +211,8 @@ export const agentControlHandlers: SharedActionHandlers = {
       preflight: parsed.preflight,
     });
     if (!outcome.ok) return { ok: false, error: outcome.error };
-    const timeoutS = Math.round(clampTimeout(parsed.timeoutMs) / 1000);
+    const timeout = describeTimeout(clampTimeout(parsed.timeoutMs));
+    const stall = getAgentCaps().stallTimeoutMs;
     log("gateway", `spawn_agent: "${parsed.label}" [${outcome.agentId}]`);
     return {
       ok: true,
@@ -218,7 +220,12 @@ export const agentControlHandlers: SharedActionHandlers = {
         `Spawned agent "${parsed.label}" (id: ${outcome.agentId})\n` +
         `Backend: ${outcome.backendId}/${outcome.model}` +
         `${outcome.routing ? ` (routed: ${outcome.routing})` : ""}\n` +
-        `Timeout: ${timeoutS}s\n` +
+        `Timeout: ${timeout}` +
+        (stall > 0
+          ? ` (watchdog: pinged after ${describeTimeout(stall)} quiet, ` +
+            `killed after ${describeTimeout(3 * stall)})`
+          : "") +
+        `\n` +
         (parsed.preflight ? `Pre-flight lane: on\n` : "") +
         `It runs in the background. You will be woken with its report — ` +
         `carry on with what you were doing.`,

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

@@ -28,6 +28,10 @@ const PREFLIGHT_TIMEOUT_MS = 600_000;
 const KILL_GRACE_MS = 5_000;
 /** Lines of each failing step's log to hand back. */
 const FAIL_TAIL_LINES = 30;
+/** How to give a checkout dependencies without a fresh ~1.2 GB `npm ci`. */
+const LINK_HINT =
+  "No node_modules in this checkout: run `node scripts/worktree.mjs link` " +
+  "in it (hardlinks a shared install, ~0 extra disk), then retry.";
 
 interface PreflightStep {
   readonly name: string;
@@ -64,6 +68,15 @@ function repoRoot(dir: string): Promise<string> {
   });
 }
 
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function isFile(path: string): Promise<boolean> {
   try {
     return (await stat(path)).isFile();
@@ -193,11 +206,14 @@ async function runPreflight(
   }
   const summary = await readSummary(root);
   if (!summary) {
+    const hint = (await exists(join(root, "node_modules")))
+      ? ""
+      : `\n${LINK_HINT}`;
     return {
       ok: false,
       error:
         `Pre-flight exited ${run.code} without writing .preflight/last.json. ` +
-        `Output:\n${run.output.slice(-2_000)}`,
+        `Output:\n${run.output.slice(-2_000)}${hint}`,
     };
   }
   // A red lane is a successful tool call with a red verdict — the model is

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

@@ -18,12 +18,40 @@ import {
   deliverMessage,
   deliverToAgent,
   describeParent,
+  recordInterimMessage,
 } 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";
 
+/** How `other` relates to `self` within their shared tree. */
+function relation(self: AgentRecord, other: AgentRecord): string {
+  if (self.parent.kind === "agent" && self.parent.agentId === other.id) {
+    return "your parent";
+  }
+  if (other.parent.kind === "agent" && other.parent.agentId === self.id) {
+    return "your child";
+  }
+  const sameParent =
+    self.parent.kind === other.parent.kind &&
+    (self.parent.kind === "chat"
+      ? other.parent.kind === "chat" &&
+        other.parent.chatId === self.parent.chatId
+      : other.parent.kind === "agent" &&
+        other.parent.agentId === self.parent.agentId);
+  return sameParent ? "sibling" : `in your tree, depth ${other.depth}`;
+}
+
+/** One agent in a `list_peers` listing. */
+function renderPeer(peer: AgentRecord, rel?: string): string {
+  return (
+    `- ${peer.label} [${peer.state}]${rel ? ` — ${rel}` : ""}\n` +
+    `  ID: ${peer.id}\n` +
+    `  Working on: ${peer.brief.slice(0, 160).replace(/\s+/g, " ")}…`
+  );
+}
+
 function notAnAgent(tool: string): ActionResult {
   return {
     ok: false,
@@ -72,6 +100,8 @@ export const agentReportHandlers: SharedActionHandlers = {
     if (!record) return notAnAgent("message_parent");
     const text = String(body.text ?? "").trim();
     if (!text) return { ok: false, error: "Missing text" };
+    // Kept for the parent's wake-up should the run be cut short.
+    recordInterimMessage(record.id, 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) =>
@@ -87,64 +117,91 @@ export const agentReportHandlers: SharedActionHandlers = {
     };
   },
 
-  list_peers: (_body, _chatId, _backend, chatKey) => {
+  list_peers: (body, _chatId, _backend, chatKey) => {
     const record = callingAgent(chatKey);
     if (!record) return notAnAgent("list_peers");
+    const scope = body.scope === undefined ? "siblings" : String(body.scope);
+    if (scope !== "siblings" && scope !== "tree") {
+      return {
+        ok: false,
+        error: `Unknown scope "${scope}". Use "siblings" or "tree".`,
+      };
+    }
+    if (scope === "tree") {
+      const tree = agentRegistry.treeOf(record.id);
+      if (tree.length === 0) {
+        return {
+          ok: true,
+          text: "No other live agents in your tree. Report to your parent as usual.",
+        };
+      }
+      return {
+        ok: true,
+        text:
+          `${tree.length} other live agent(s) in your tree (everything ` +
+          `working for the same chat). Any of them can be reached with ` +
+          `message_peer:\n\n` +
+          tree
+            .map((other) => renderPeer(other, relation(record, other)))
+            .join("\n"),
+      };
+    }
     const peers = agentRegistry.peersOf(record.id);
     if (peers.length === 0) {
       return {
         ok: true,
         text:
           "No peers — you are the only agent your parent has running. " +
-          "Report to your parent as usual.",
+          'Report to your parent as usual (list_peers with scope "tree" ' +
+          "shows the rest of your agent tree).",
       };
     }
-    const rendered = peers
-      .map(
-        (peer) =>
-          `- ${peer.label} [${peer.state}]\n  ID: ${peer.id}\n  Working on: ${peer.brief.slice(0, 160).replace(/\s+/g, " ")}…`,
-      )
-      .join("\n");
     return {
       ok: true,
-      text: `${peers.length} peer(s) running alongside you:\n\n${rendered}`,
+      text:
+        `${peers.length} peer(s) running alongside you:\n\n` +
+        peers.map((peer) => renderPeer(peer)).join("\n"),
     };
   },
 
   message_peer: (body, _chatId, _backend, chatKey) => {
     const record = callingAgent(chatKey);
     if (!record) return notAnAgent("message_peer");
-    const id = String(body.agent_id ?? "").trim();
-    if (!id) return { ok: false, error: "Missing agent_id" };
+    const target = String(body.agent_id ?? body.label ?? "").trim();
+    if (!target) return { ok: false, error: "Missing agent_id (or label)" };
     const text = String(body.text ?? "").trim();
     if (!text) return { ok: false, error: "Missing text" };
-    // Peers only. An agent may address a sibling, never an arbitrary id:
-    // resolving through peersOf is what stops one swarm reaching into
-    // another, and it means a wrong id fails closed rather than delivering.
-    const peer = agentRegistry
-      .peersOf(record.id)
-      .find((candidate) => candidate.id === id);
-    if (!peer) {
+    // Resolved through the caller's own tree: an agent can reach any live
+    // agent working for the same chat, never one working for another — a
+    // wrong or foreign id fails closed rather than delivering.
+    const found = agentRegistry.findInTree(record.id, target);
+    if (!found.ok) {
       return {
         ok: false,
         error:
-          `No peer "${id}". You can only message agents spawned by the same ` +
-          `parent as you — call list_peers to see them.`,
+          found.candidates.length > 1
+            ? `"${target}" is ambiguous — ${found.candidates.length} live ` +
+              `agents in your tree have that label ` +
+              `(${found.candidates.map((c) => c.id).join(", ")}). Use the id.`
+            : `No live agent "${target}" in your tree. You can message any ` +
+              `live agent working for the same chat as you — call ` +
+              `list_peers with scope "tree" to see them.`,
       };
     }
-    if (!deliverToAgent(record.id, id, text)) {
+    const peer = found.record;
+    if (!deliverToAgent(record.id, peer.id, text)) {
       return {
         ok: false,
         error:
-          `Could not deliver to "${peer.label}" (${id}): it has already ` +
+          `Could not deliver to "${peer.label}" (${peer.id}): it has already ` +
           `settled, or its inbox is full.`,
       };
     }
     return {
       ok: true,
       text:
-        `Queued for peer "${peer.label}" (${id}). It reads its inbox at its ` +
-        `own milestones, so this is not an interrupt.`,
+        `Queued for "${peer.label}" (${peer.id}, ${relation(record, peer)}). ` +
+        `It reads its inbox at its own milestones, so this is not an interrupt.`,
     };
   },
 

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

@@ -22,6 +22,7 @@
  *   - `mesh`      — companion device mesh (presence + location)
  *   - `cross-send` — explicit-target sends through any enabled frontend
  *   - `backup`    — snapshots and checkpoints (chat-free; no restore)
+ *   - `secrets`   — secret-drop links (core/secrets; needs the chat)
  */
 
 import type { ActionResult } from "../../types.js";
@@ -49,6 +50,7 @@ import {
 } from "./whatsapp-account.js";
 import { nativeActionRefusal, nativeHandlers } from "./native/index.js";
 import { backupChatFreeActions, backupHandlers } from "./backup/index.js";
+import { secretHandlers } from "../../secrets/actions.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method — `handlers[action]` only
@@ -70,6 +72,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...whatsappAccountHandlers,
   ...nativeHandlers,
   ...backupHandlers,
+  ...secretHandlers,
 });
 
 /**

package/src/core/mcp-hub/guest-scope.ts

@@ -83,12 +83,14 @@ export const GUEST_TOOL_ALLOWLIST: ReadonlySet<string> = new Set([
 
 /**
  * Tools whose output is a live credential (an install command or pairing
- * link embedding a bridge bearer token). Operator-only, and their output is delivered
+ * link embedding a bridge bearer token, or a secret-drop link). Operator-only, and their output is delivered
  * to the operator's private chat, never into a shared one.
  */
 export const OPERATOR_PRIVATE_OUTPUT_TOOLS: ReadonlySet<string> = new Set([
   "make_node_install_link",
   "make_companion_pair_link",
+  // A secret-drop link writes into ~/.talon/secrets for whoever opens it.
+  "request_secret",
 ]);
 
 /** Parameters that name another chat. A guest may only name its own. */

package/src/core/mesh/devices/service.ts

@@ -863,6 +863,13 @@ export class MeshService {
     return this.links.makeCompanionPairLink(label, bridgeUrl);
   }
 
+  /** The bridge base URL a bridge-served link should use (secret drop). */
+  bridgeBaseUrl(
+    explicit?: unknown,
+  ): ReturnType<BridgeLinks["bridgeBaseUrlFor"]> {
+    return this.links.bridgeBaseUrlFor(explicit);
+  }
+
   /** `make_companion_pair_link`: the pairing link as a tool result. */
   makeCompanionPairLinkText(
     label?: unknown,

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

@@ -371,6 +371,26 @@ export class BridgeLinks {
     };
   }
 
+  /**
+   * The base URL a device should open a bridge-served link at (secret
+   * drop): the same answer the pairing and install links use.
+   */
+  bridgeBaseUrlFor(
+    explicit?: unknown,
+  ): { ok: true; url: 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 to serve the link. Enable the native frontend first.",
+      };
+    }
+    const base = this.bridgeBaseUrl(info, explicit);
+    return typeof base === "string"
+      ? { ok: true, url: base }
+      : { ok: false, text: base.error };
+  }
+
   /** GET /node/install — serve a grant's installer script (single-use). */
   /**
    * An auto grant is pinned here first, from the os/arch its one-liner

package/src/core/secrets/actions.ts

@@ -0,0 +1,18 @@
+/**
+ * Gateway action for `request_secret`. Needs the chat (the receipt goes
+ * back to it), so it is not chat-free.
+ */
+
+import type { SharedActionHandlers } from "../engine/gateway-actions/types.js";
+import { requestSecretDrop } from "./service.js";
+
+export const secretHandlers: SharedActionHandlers = {
+  request_secret: (body, _chatId, _backend, chatKey) => {
+    const minted = requestSecretDrop({
+      name: body.name,
+      purpose: body.purpose,
+      chatKey,
+    });
+    return { ok: minted.ok, text: minted.text };
+  },
+};

package/src/core/secrets/drop.ts

@@ -0,0 +1,176 @@
+/**
+ * Secret drop: single-use, expiring grants that let the operator paste a
+ * password into a form served by the native bridge instead of into a chat.
+ *
+ * Same trust model as companion pairing (mesh/links/companion-pairing.ts):
+ * the bridge serves the grant pre-auth, and the random 192-bit grant in the
+ * query is the whole authorization. Differences:
+ *
+ *   - GET only shows the form and does NOT spend the grant. Chat apps
+ *     fetch links to build previews, and a preview must not burn the link
+ *     before the human opens it.
+ *   - POST spends it, once, whether or not the write then succeeds — a
+ *     failed write asks for a fresh link rather than leaving a live one
+ *     open to retries.
+ *
+ * The grant records which chat asked, so the receipt ("stored ✓ as <name>")
+ * goes back there. The value itself never leaves `consume` except into the
+ * file.
+ */
+
+import { randomBytes } from "node:crypto";
+
+/** Unused grants die after this long. */
+export const SECRET_GRANT_TTL_MS = 15 * 60 * 1000;
+
+export type SecretDropGrant = {
+  token: string;
+  /** Validated secret name — the file under ~/.talon/secrets. */
+  name: string;
+  /** Shown on the form so the operator knows what is being asked for. */
+  purpose?: string;
+  /** Chat that asked, for the receipt. */
+  chatKey: string;
+  /** Frontend that chat lives on. */
+  frontend: string;
+  createdAt: number;
+};
+
+export class SecretDropStore {
+  private readonly grants = new Map<string, SecretDropGrant>();
+
+  constructor(
+    private readonly ttlMs = SECRET_GRANT_TTL_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  create(grant: Omit<SecretDropGrant, "token" | "createdAt">): SecretDropGrant {
+    this.sweep();
+    const full: SecretDropGrant = {
+      ...grant,
+      ...(grant.purpose ? { purpose: cleanPurpose(grant.purpose) } : {}),
+      token: randomBytes(24).toString("base64url"),
+      createdAt: this.now(),
+    };
+    this.grants.set(full.token, full);
+    return full;
+  }
+
+  /** A live grant, without spending it (the GET form). */
+  peek(token: string): SecretDropGrant | null {
+    this.sweep();
+    return this.grants.get(token) ?? null;
+  }
+
+  /** Spend a live grant (the POST). Null when unknown, expired or used. */
+  consume(token: string): SecretDropGrant | null {
+    this.sweep();
+    const grant = this.grants.get(token);
+    if (!grant) return null;
+    this.grants.delete(token);
+    return grant;
+  }
+
+  private sweep(): void {
+    const cutoff = this.now() - this.ttlMs;
+    for (const [token, grant] of this.grants) {
+      if (grant.createdAt <= cutoff) this.grants.delete(token);
+    }
+  }
+}
+
+/** Purposes come from the model: one line, no markup, bounded. */
+function cleanPurpose(purpose: string): string {
+  return purpose
+    .replace(/[\r\n\t]+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
+/** Minimal HTML escape for values interpolated into the pages. */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+const 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.25rem; opacity: .7; }
+  textarea { box-sizing: border-box; width: 100%; min-height: 6rem; padding: 10px;
+             font: 14px ui-monospace, monospace; border-radius: 8px; }
+  button { margin-top: 12px; width: 100%; padding: 14px; border: 0; border-radius: 10px;
+           background: #2f6fed; color: #fff; font-weight: 600; font-size: 1rem; }
+  footer { margin-top: 1.5rem; font-size: .8rem; opacity: .6; }`;
+
+/**
+ * One self-contained page, no script and no external assets. `no-referrer`
+ * keeps the grant out of any Referer and makes the browser send
+ * `Origin: null` on the POST; the bridge also accepts its own origin there.
+ */
+function page(title: string, body: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<meta name="robots" content="noindex">
+<title>${esc(title)}</title>
+<style>
+  ${STYLE}
+</style>
+</head>
+<body>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+
+/** The paste form for a live grant. */
+export function secretDropForm(grant: SecretDropGrant): string {
+  const minutes = Math.round(SECRET_GRANT_TTL_MS / 60_000);
+  return page(
+    "Talon secret drop",
+    `  <h1>Store a secret</h1>
+  <p class="sub">Saved as <b>${esc(grant.name)}</b> on the Talon host.${
+    grant.purpose ? `<br>For: ${esc(grant.purpose)}` : ""
+  }</p>
+  <form method="post" action="?grant=${esc(grant.token)}" autocomplete="off">
+    <textarea name="value" required autofocus spellcheck="false"
+      autocapitalize="off" autocorrect="off" aria-label="Secret value"></textarea>
+    <button type="submit">Store</button>
+  </form>
+  <footer>The value goes straight to a file readable only by Talon's user. It is
+  not posted to the chat or shown to the model. This link works once and expires
+  ${minutes} minutes after it was made.</footer>`,
+  );
+}
+
+/** What the browser sees after a POST. */
+export function secretDropResult(
+  ok: boolean,
+  name: string | null,
+  error?: string,
+): string {
+  return ok && name
+    ? page(
+        "Stored",
+        `  <h1>Stored ✓</h1>
+  <p class="sub">Saved as <b>${esc(name)}</b>. You can close this page.</p>`,
+      )
+    : page(
+        "Not stored",
+        `  <h1>Not stored</h1>
+  <p class="sub">${esc(error ?? "This link is unknown, expired, or already used.")}</p>
+  <footer>Ask for a fresh link with /secret &lt;name&gt;.</footer>`,
+      );
+}

package/src/core/secrets/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Secrets — the ~/.talon/secrets folder and the drop links that fill it
+ * without a password ever crossing a chat.
+ */
+
+export {
+  isLiveSecretDrop,
+  openSecretDropForm,
+  secretCommandReply,
+  submitSecretDrop,
+} from "./service.js";