talon-agent 5.28.0 → 5.30.0

package/src/core/agents/types.ts

@@ -87,6 +87,21 @@ export interface AgentRecord {
   readonly children: readonly string[];
   /** Messages waiting to be drained by `check_inbox`. */
   readonly inboxDepth: number;
+  /**
+   * What the run had been doing when it settled — set on every settlement
+   * the runner makes, shown to the parent when the run did not end `done`.
+   */
+  readonly trail?: AgentTrail;
+}
+
+/** A settled run's last interim messages, progress notes and changed files. */
+export interface AgentTrail {
+  /** Last `message_parent` notes, oldest first. */
+  readonly messages: readonly string[];
+  /** Last assistant texts, oldest first. */
+  readonly notes: readonly string[];
+  /** Files it wrote or edited (best-effort, from the run log). */
+  readonly files: readonly string[];
 }
 
 /** What `spawnAgent` is asked for. */
@@ -94,12 +109,23 @@ export interface AgentSpawnSpec {
   readonly brief: string;
   readonly label: string;
   readonly parent: AgentParent;
-  /** Defaults to the parent's backend. */
+  /**
+   * Unset: a child of another agent inherits its parent's backend (and,
+   * with no model either, its model); a top-level spawn starts from the
+   * chat's backend and may be routed.
+   */
   readonly backendId?: string;
-  /** Defaults to the resolved backend's own default model. */
+  /**
+   * Defaults to the parent agent's model when the backend is inherited from
+   * one, else the resolved backend's own default model.
+   */
   readonly model?: string;
   readonly reasoningEffort?: ReasoningEffortLevel;
-  /** Hard wall-clock cap. Defaults to `agents.defaultTimeoutMs`. */
+  /**
+   * Hard wall-clock cap. Unset = `agents.defaultTimeoutMs`, and with that
+   * unset too, no cap at all — the no-progress watchdog is what ends a run
+   * that has gone quiet.
+   */
   readonly timeoutMs?: number;
   /**
    * Append the pre-flight lane instruction (run `npm run preflight` before
@@ -130,6 +156,18 @@ export interface AgentCaps {
   readonly maxConcurrent: number;
   /** Deepest `depth` an agent may have — 2 means chat → A → B. */
   readonly maxDepth: number;
-  /** Default hard timeout for one run. */
-  readonly defaultTimeoutMs: number;
+  /** Hard timeout for a spawn that sets none. Unset = no hard timeout. */
+  readonly defaultTimeoutMs?: number;
+  /** Ceiling on any run's hard timeout, requested or not. Unset = none. */
+  readonly maxTimeoutMs?: number;
+  /**
+   * No-progress watchdog step N: ping the agent after N ms of silence, warn
+   * its parent after 2N, kill it after 3N. 0 disables the watchdog.
+   */
+  readonly stallTimeoutMs: number;
+  /**
+   * Backends a sub-agent may run on. Unset or empty = any backend with a
+   * background capability. Enforced by `spawnAgent` on the final choice.
+   */
+  readonly allowedBackends?: readonly string[];
 }

package/src/core/agents/watchdog.ts

@@ -0,0 +1,70 @@
+/**
+ * No-progress watchdog for a sub-agent run.
+ *
+ * Replaces the old "everyone gets a 15-minute hard cap" safety net with one
+ * that only fires on an agent that has actually gone quiet. With
+ * `stallMs = N`, measured from the last sign of life (a run-log line or an
+ * assistant text — see `RunTrail`):
+ *
+ *   - after N   → the agent is pinged (a message in its own mailbox);
+ *   - after 2N  → its parent is told, so it can intervene or kill early;
+ *   - after 3N  → the run is aborted and settles as `timed_out` ("stalled").
+ *
+ * Any activity resets the ladder. The watchdog owns one unref'd interval and
+ * nothing else; every action is a callback, so it is trivially testable.
+ */
+
+export interface WatchdogActions {
+  /** Last sign of life, epoch ms. */
+  readonly lastActivityAt: () => number;
+  readonly pingAgent: (idleMs: number) => void;
+  readonly warnParent: (idleMs: number, killInMs: number) => void;
+  readonly kill: (idleMs: number) => void;
+}
+
+export interface WatchdogHandle {
+  stop(): void;
+  /** Evaluate now — exposed for tests; the interval calls it too. */
+  check(now?: number): void;
+}
+
+/** Start a watchdog. `stallMs <= 0` returns an inert handle. */
+export function startWatchdog(
+  stallMs: number,
+  actions: WatchdogActions,
+  checkEveryMs: number = Math.max(1_000, Math.min(60_000, stallMs / 4)),
+): WatchdogHandle {
+  if (!(stallMs > 0)) return { stop: () => {}, check: () => {} };
+  // 0 = quiet, 1 = pinged, 2 = parent warned, 3 = killed.
+  let stage = 0;
+  let stageAnchor = actions.lastActivityAt();
+
+  const check = (now: number = Date.now()): void => {
+    if (stage >= 3) return;
+    const last = actions.lastActivityAt();
+    if (last !== stageAnchor) {
+      // Signs of life since the last escalation — start over.
+      stageAnchor = last;
+      stage = 0;
+    }
+    const idle = now - last;
+    if (stage < 1 && idle >= stallMs) {
+      stage = 1;
+      actions.pingAgent(idle);
+    }
+    if (stage < 2 && idle >= 2 * stallMs) {
+      stage = 2;
+      actions.warnParent(idle, Math.max(0, 3 * stallMs - idle));
+    }
+    if (stage < 3 && idle >= 3 * stallMs) {
+      stage = 3;
+      actions.kill(idle);
+      stop();
+    }
+  };
+
+  const timer = setInterval(() => check(), checkEveryMs);
+  timer.unref();
+  const stop = (): void => clearInterval(timer);
+  return { stop, check };
+}

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

@@ -37,8 +37,11 @@ export interface IsolatedRunOptions {
   readonly background: BackgroundRunner;
   /** Fully-built one-shot params (must carry an `abortController`). */
   readonly params: OneShotAgentParams;
-  /** Hard timeout before the run is aborted. */
-  readonly timeoutMs: number;
+  /**
+   * Hard timeout before the run is aborted. Unset = none: the run is only
+   * ended by its own completion or by an abort of `params.abortController`.
+   */
+  readonly timeoutMs?: number;
   /** Bounded grace for the backend to honour the abort (default 30s). */
   readonly abortGraceMs?: number;
   /**
@@ -91,6 +94,7 @@ export async function runIsolatedAgent(
   const agentPromise = background.runOneShotAgent(params);
 
   const timeoutPromise = new Promise<never>((_, reject) => {
+    if (timeoutMs === undefined) return;
     timer = setTimeout(() => {
       timeoutError = new IsolatedAgentTimeoutError(timeoutMs);
       try {

package/src/core/backup/plan.ts

@@ -75,6 +75,10 @@ export const HOME_INCLUDES: readonly string[] = [
   "prompts",
   "data",
   "keys",
+  // Operator secrets (~/.talon/secrets, the secret drop's folder). Held to
+  // the same rule as keys/ and workspace/secrets: in the snapshot, so
+  // encrypt backups (docs/backup-security.md).
+  "secrets",
   "google",
   "plugins",
   "mesh-devices.json",

package/src/core/config/index.ts

@@ -642,18 +642,31 @@ 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.
    */
   agents: z
     .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(),
     })
     .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 };
+  },
+};