talon-agent 5.29.0 → 5.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.29.0",
+  "version": "5.31.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",
@@ -91,6 +91,7 @@
     "format": "prettier --write src/ prompts/",
     "format:check": "prettier --check src/ prompts/",
     "preflight": "bash scripts/preflight.sh",
+    "worktree": "node scripts/worktree.mjs",
     "ci:protect": "node .github/scripts/enforce-ci-gate.mjs",
     "build:gleam": "cd native/scheduler-core && gleam build --target javascript && node embed.mjs",
     "build:zig": "node native/textops-wasm/build.mjs",

package/prompts/system/agent-brief.md

@@ -33,22 +33,32 @@ a useful result; silence is not.
 Your parent may have spawned others alongside you. `list_peers()` shows them —
 id, label, and what each was asked to do — and `message_peer(agent_id, text)`
 sends one of them a note directly, without going through your parent.
+`list_peers(scope: "tree")` widens the view to every live agent working for
+the same chat (your parent agent, children, cousins); any of them can be
+addressed the same way, by id or by label.
 
 Use it when something you found changes _their_ work and waiting would waste
 it: a fact you both need, a dead end worth not repeating, a correction to
 something you told them earlier. Don't narrate your progress at them — a peer
 pays for every message with context it could have spent on its own job.
 
-You can only address peers, and they see your note at their next
-`check_inbox`, so it is not an interrupt. Your report still goes to your
-parent: peer messages are for coordination, never a substitute for
-`report_result`.
+They see your note at their next `check_inbox`, so it is not an interrupt.
+Your report still goes to your parent: peer messages are for coordination,
+never a substitute for `report_result`.
 
 ## Delegating further
 
 {% if canSpawn %}You may spawn your own sub-agents with `spawn_agent` (current depth {{depth}}, cap {{maxDepth}}) when the work genuinely splits into independent pieces. You are then responsible for them: `wait_for_agent`, `send_to_agent`, `kill_agent`, and folding their reports into yours.{% else %}You are at the maximum sub-agent depth ({{maxDepth}}) — `spawn_agent` will be refused. Do this work yourself.{% endif %}
 
-## Boundaries
+{% if scratchDir %}## Scratch space
+
+Your private temp directory is `{{scratchDir}}` — `TMPDIR` points there for
+your shells and tools. Put scratch files, clones and build output there
+rather than in shared `/tmp`, where other agents are working. It is deleted
+when you finish successfully and kept if your run fails, so leave anything
+worth keeping somewhere permanent.
+
+{% endif %}## Boundaries
 
 - Do **not** message the user's chat directly unless the brief explicitly
   tells you to. Your report goes to the agent or chat that spawned you, and
@@ -56,5 +66,6 @@ parent: peer messages are for coordination, never a substitute for
 - You have the full background tool surface (files, shell, web, plugins, and
   the messaging tools with an explicit `chat_id`). Use it, but stay inside
   the brief — you were spawned for one job.
-- Be efficient. You have a hard wall-clock timeout; a partial result reported
-  in time beats a perfect one that never arrives.
+- Be efficient. A run may have a wall-clock timeout, and a watchdog pings,
+  then ends, one that makes no tool call or output for too long; a partial
+  result reported in time beats a perfect one that never arrives.

package/src/backend/claude-sdk/constants.ts

@@ -47,3 +47,25 @@ export const EFFORT_MAP: Record<
 
 /** Minimum interval (ms) between streaming delta callbacks to avoid flooding frontends. */
 export const STREAM_INTERVAL = 1000;
+
+// ── Transcript retention ───────────────────────────────────────────────────
+
+/**
+ * Settings layered onto every Claude Code process Talon spawns, as the
+ * SDK's `settings` option (the CLI's `--settings` flag).
+ *
+ * Claude Code runs a background retention sweep (at most once a day, shared
+ * across every CLI process through `~/.claude/.last-cleanup`) that deletes
+ * session transcripts in `~/.claude/projects` older than `cleanupPeriodDays`
+ * — 30 days when nothing sets it. Talon resumes chats by session id, so a
+ * swept transcript silently breaks a long-lived chat and loses its history.
+ *
+ * The user's own `~/.claude/settings.json` only applies while user settings
+ * are loaded, the file parses, and HOME / CLAUDE_CONFIG_DIR match the
+ * user's. Setting it per run removes that dependency. The CLI rejects 0 and
+ * recommends a large value for long retention; 100000 days is effectively
+ * forever. A managed policy-tier `cleanupPeriodDays` still takes precedence.
+ */
+export const CLAUDE_RETENTION_SETTINGS = {
+  cleanupPeriodDays: 100_000,
+} as const;

package/src/backend/claude-sdk/models/discovery.ts

@@ -14,6 +14,7 @@ import type { ModelInfo } from "../../../core/models/catalog.js";
 import { log, logError } from "../../../util/log.js";
 import { describeSdkModel, type SdkModelInfo } from "./parsing.js";
 import { convertSdkModels } from "./convert.js";
+import { CLAUDE_RETENTION_SETTINGS } from "../constants.js";
 
 type ProbeOptions = {
   cwd?: string;
@@ -62,6 +63,8 @@ async function probeSupportedModels(
       prompt: neverYield(),
       options: {
         ...probeOptions,
+        // Any spawned CLI may run the daily retention sweep.
+        settings: { ...CLAUDE_RETENTION_SETTINGS },
         model: seedModel,
         abortController: abort,
       } as Parameters<typeof query>[0]["options"],

package/src/backend/claude-sdk/one-shot.ts

@@ -17,7 +17,7 @@ import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log, logWarn } from "../../util/log.js";
 import { ALLOWED_TOOLS_BACKGROUND } from "../../core/constants.js";
-import { EFFORT_MAP } from "./constants.js";
+import { CLAUDE_RETENTION_SETTINGS, EFFORT_MAP } from "./constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
 import { isBackgroundToolContext } from "../../core/agents/context.js";
 import { warnIfBelowCacheMinimum } from "../runtime/cache/cache-telemetry.js";
@@ -91,12 +91,17 @@ export async function runOneShotAgent(
     systemPrompt,
     ...thinkingConfig,
     cwd: workspace,
+    // A sub-agent's private TMPDIR (and any other per-run vars), layered
+    // over the daemon's environment — the SDK replaces, not merges, `env`.
+    ...(params.env ? { env: { ...process.env, ...params.env } } : {}),
     permissionMode: "bypassPermissions" as const,
     allowDangerouslySkipPermissions: true,
     abortController,
     ...(oneShotConfig.claudeBinary
       ? { pathToClaudeCodeExecutable: oneShotConfig.claudeBinary }
       : {}),
+    // Keep session transcripts: interrupted sub-agents resume from them.
+    settings: { ...CLAUDE_RETENTION_SETTINGS },
     mcpServers: assembleMcpServers(contextLabel),
     // Whitelist of SDK built-in tools for background contexts (heartbeat,
     // dream). Same as chat minus `Agent` — nested sub-agent dispatch from

package/src/backend/claude-sdk/options.ts

@@ -37,7 +37,11 @@ import {
   gatewayToken,
 } from "../../core/engine/gateway-auth.js";
 import { getConfig, getBridgePort } from "./state.js";
-import { ALLOWED_TOOLS_CHAT, EFFORT_MAP } from "./constants.js";
+import {
+  ALLOWED_TOOLS_CHAT,
+  CLAUDE_RETENTION_SETTINGS,
+  EFFORT_MAP,
+} from "./constants.js";
 import {
   isGuestTurn,
   isGuestPluginAllowed,
@@ -482,6 +486,8 @@ export function buildSdkOptions(
     ...(config.claudeBinary
       ? { pathToClaudeCodeExecutable: config.claudeBinary }
       : {}),
+    // Keep session transcripts: Talon resumes chats from them.
+    settings: { ...CLAUDE_RETENTION_SETTINGS },
     // Whitelist of SDK built-in tools. Anything not listed (e.g. WebSearch,
     // WebFetch, Monitor, PushNotification, RemoteTrigger, Plan/Worktree/Todo
     // helpers, AskUserQuestion, ScheduleWakeup) is unavailable to the model.

package/src/core/agents/index.ts

@@ -21,6 +21,7 @@ export { AgentRegistry, agentRegistry } from "./registry.js";
 export {
   DEFAULT_AGENT_CAPS,
   clampTimeout,
+  describeTimeout,
   getAgentCaps,
   initAgents,
   interruptAgentsForRestart,
@@ -36,4 +37,5 @@ export {
   initAgentDelivery,
 } from "./delivery.js";
 export { describeParent, wantsPreflight } from "./prompt.js";
+export { recordInterimMessage } from "./trail.js";
 export type { AgentCaps, AgentParent, AgentRecord } from "./types.js";

package/src/core/agents/prompt.ts

@@ -11,6 +11,7 @@ import { resolve } from "node:path";
 import { dirs } from "../../util/paths.js";
 import { loadSystemTemplate } from "../prompt/templates.js";
 import type { AgentParent, AgentRecord } from "./types.js";
+import { trailIsEmpty } from "./trail.js";
 
 /** Where sub-agent run logs live: `~/.talon/workspace/logs/agents/`. */
 const AGENT_LOGS_DIR = resolve(dirs.logs, "agents");
@@ -39,8 +40,11 @@ export function buildAgentSystemPrompt(args: {
   parent: AgentParent;
   depth: number;
   maxDepth: number;
+  /** The agent's private TMPDIR, when one was created. */
+  scratchDir?: string;
 }): string {
   return loadSystemTemplate("agent-brief", {
+    scratchDir: args.scratchDir ?? "",
     agentId: args.agentId,
     label: args.label,
     parent: describeParent(args.parent),
@@ -60,7 +64,11 @@ const PREFLIGHT_INSTRUCTION =
   "the repo (or call the run_preflight tool with cwd set to your checkout). " +
   "Push only when it is green. If it is red, fix it — or, when a failure " +
   "is genuinely out of scope, say in the PR body which step failed and why " +
-  "you pushed anyway.";
+  "you pushed anyway. Make your checkout with `node scripts/worktree.mjs " +
+  "add /tmp/fix-<name> <branch>` (run it in an existing talon checkout): " +
+  "its node_modules is hardlinked from a shared store, so do NOT run " +
+  "`npm ci` there (~1.2 GB each). Clean up with `node scripts/worktree.mjs " +
+  "remove <path>`.";
 
 /** A brief that opens, updates or talks about a pull request. */
 const PR_BRIEF = /\bPRs?\b|pull[ -]requests?/i;
@@ -181,6 +189,69 @@ function usageLine(record: AgentRecord): string {
   );
 }
 
+/** Human duration for prompts: "45 min" / "30s". */
+function minutes(ms: number): string {
+  return ms >= 60_000
+    ? `${Math.round(ms / 60_000)} min`
+    : `${Math.round(ms / 1000)}s`;
+}
+
+/**
+ * The "what it was doing" block appended to a report when the run did not
+ * end `done` — so a kill or a timeout never throws the work away.
+ */
+function renderTrail(record: AgentRecord): string {
+  const trail = record.trail;
+  if (record.state === "done" || trailIsEmpty(trail) || !trail) return "";
+  const parts: string[] = [];
+  if (trail.messages.length > 0) {
+    parts.push(
+      `Its last interim messages:\n` +
+        trail.messages.map((m) => `- ${m}`).join("\n"),
+    );
+  }
+  if (trail.notes.length > 0) {
+    parts.push(
+      `Its last progress notes:\n` +
+        trail.notes.map((n) => `- ${n}`).join("\n"),
+    );
+  }
+  if (trail.files.length > 0) {
+    parts.push(
+      `Files it wrote or edited:\n` +
+        trail.files.map((f) => `- ${f}`).join("\n"),
+    );
+  }
+  return (
+    `\n\n--- What it had done before it ended (run log: ` +
+    `${agentLogPath(record.id)}) ---\n\n${parts.join("\n\n")}`
+  );
+}
+
+/** Mailbox note the watchdog leaves an agent that has gone quiet. */
+export function buildStallPing(idleMs: number, stallMs: number): string {
+  return (
+    `[Watchdog] No tool call or output from you for ${minutes(idleMs)}. ` +
+    `If you are stuck, report_result now with what you have. Your parent ` +
+    `is told at ${minutes(2 * stallMs)} of silence and the run is killed ` +
+    `at ${minutes(3 * stallMs)}.`
+  );
+}
+
+/** The interim note a parent gets when its agent has stalled. */
+export function buildStallWarning(
+  record: AgentRecord,
+  idleMs: number,
+  killInMs: number,
+): string {
+  return (
+    `[Watchdog] Agent ${record.id} "${record.label}" has made no progress ` +
+    `(no tool call or output) for ${minutes(idleMs)}. It will be killed in ` +
+    `${minutes(killInMs)} unless it resumes. Use send_to_agent to nudge it, ` +
+    `or kill_agent to end it now.`
+  );
+}
+
 /**
  * The wake prompt a parent chat receives when one of its agents settles.
  * Shaped like the trigger wake-up: a `[System: …]` header telling the model
@@ -203,7 +274,7 @@ export function buildSettlementPrompt(record: AgentRecord): string {
     `an agent you spawned earlier. Decide whether to act on it, tell the ` +
     `user, or do nothing.]\n\n` +
     `[Agent "${record.label}" (${record.id}) — ${record.state}]\n\n` +
-    `${body}${usageLine(record)}`
+    `${body}${renderTrail(record)}${usageLine(record)}`
   );
 }
 

package/src/core/agents/registry.ts

@@ -22,6 +22,7 @@ import type {
   AgentRecord,
   AgentResult,
   AgentState,
+  AgentTrail,
 } from "./types.js";
 import type { TaskUsage } from "../tasks/types.js";
 import type { AgentSettledEvent, AgentSpawnedEvent } from "../bus/events.js";
@@ -73,6 +74,8 @@ export interface AgentSettlement {
   readonly result?: AgentResult;
   readonly error?: string;
   readonly usage?: TaskUsage;
+  /** What the run had been doing — see `trail.ts`. */
+  readonly trail?: AgentTrail;
 }
 
 export type RegisterOutcome =
@@ -559,6 +562,7 @@ export class AgentRegistry {
     if (patch.result !== undefined) record.result = patch.result;
     if (patch.error !== undefined) record.error = patch.error;
     if (patch.usage !== undefined) record.usage = patch.usage;
+    if (patch.trail !== undefined) record.trail = patch.trail;
 
     const settled = snapshot(entry);
     this.persist(entry);
@@ -677,11 +681,9 @@ export class AgentRegistry {
   /**
    * An agent's live **peers** — the other agents sharing its parent.
    *
-   * This is the addressing scope for agent-to-agent messaging, and it is
-   * deliberately narrower than "everything under the same chat". A swarm is
-   * a set of siblings spawned for one job, so siblings are the useful unit;
-   * widening to the whole chat tree would let an agent reach a cousin from an
-   * unrelated piece of work it knows nothing about.
+   * The default view of `list_peers`: a swarm is a set of siblings spawned
+   * for one job, so siblings are the useful unit to show first. Messaging
+   * reaches the whole tree (`treeOf`).
    *
    * Live only: a settled agent has no mailbox to deliver into, and offering
    * it as a peer would only produce a delivery failure one call later.
@@ -698,6 +700,46 @@ export class AgentRegistry {
     return peers.sort((a, b) => a.createdAt - b.createdAt);
   }
 
+  /**
+   * Every other live agent in this agent's tree — the agents whose ancestry
+   * roots in the same chat (parent, children, siblings, cousins), oldest
+   * first. This is the addressing scope of `message_peer`: an agent working
+   * for one chat can reach any live agent working for that chat, and none
+   * working for another.
+   */
+  treeOf(id: string): AgentRecord[] {
+    const self = this.get(id);
+    if (!self) return [];
+    const root = this.rootChat(self);
+    if (root === null) return [];
+    const tree: AgentRecord[] = [];
+    for (const entry of this.live.values()) {
+      const record = snapshot(entry);
+      if (record.id === id) continue;
+      if (this.rootChat(record) === root) tree.push(record);
+    }
+    return tree.sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  /**
+   * Resolve `target` — an agent id, else an exact label — to a live agent
+   * in `id`'s tree. A label two live agents share is ambiguous and resolves
+   * to nothing, with both candidates returned so the caller can say which.
+   */
+  findInTree(
+    id: string,
+    target: string,
+  ):
+    | { readonly ok: true; readonly record: AgentRecord }
+    | { readonly ok: false; readonly candidates: AgentRecord[] } {
+    const tree = this.treeOf(id);
+    const byId = tree.find((record) => record.id === target);
+    if (byId) return { ok: true, record: byId };
+    const byLabel = tree.filter((record) => record.label === target);
+    if (byLabel.length === 1) return { ok: true, record: byLabel[0]! };
+    return { ok: false, candidates: byLabel };
+  }
+
   /** Live agents plus the bounded settled ring, oldest first. */
   list(): AgentRecord[] {
     const records = [...this.history];