talon-agent 5.1.0 → 5.2.0

package/src/core/background/{cron/isolated-agent.ts → isolated-agent.ts}

@@ -14,13 +14,25 @@
  * unset to avoid sweeping the other context's subprocesses.
  */
 
-import type { BackgroundRunner } from "../../agent-runtime/capabilities.js";
-import type { OneShotAgentParams, OneShotUsage } from "../../types.js";
-import { logWarn, logError } from "../../../util/log.js";
+import type { BackgroundRunner } from "../agent-runtime/capabilities.js";
+import type { OneShotAgentParams, OneShotUsage } from "../types.js";
+import { logWarn, logError, type LogComponent } from "../../util/log.js";
 
 /** Default bounded grace after an abort before giving up on the backend. */
 const DEFAULT_ABORT_GRACE_MS = 30 * 1000;
 
+/**
+ * Thrown when the hard timeout fires. A distinct class (rather than a string
+ * match on the message) so a caller can tell "ran out of wall-clock" apart
+ * from "the backend failed" and settle its own state accordingly.
+ */
+export class IsolatedAgentTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`isolated agent timed out after ${timeoutMs}ms`);
+    this.name = "IsolatedAgentTimeoutError";
+  }
+}
+
 export interface IsolatedRunOptions {
   readonly background: BackgroundRunner;
   /** Fully-built one-shot params (must carry an `abortController`). */
@@ -34,6 +46,8 @@ export interface IsolatedRunOptions {
    * ignores the abort. Leave unset when the tag is shared with another context.
    */
   readonly evictLabel?: string;
+  /** Log category for the abort/eviction diagnostics (default "triggers"). */
+  readonly logCategory?: LogComponent;
 }
 
 /** Resolves to the value, or the string "timed_out" if `ms` elapses first. */
@@ -63,20 +77,24 @@ export async function runIsolatedAgent(
 ): Promise<OneShotUsage | void> {
   const { background, params, timeoutMs } = opts;
   const graceMs = opts.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
+  const category = opts.logCategory ?? "triggers";
 
-  let timedOut = false;
+  // Doubles as the "did we time out?" flag: set before the abort, so a
+  // backend that rejects synchronously from its abort handler can't make the
+  // run look like an ordinary failure.
+  let timeoutError: IsolatedAgentTimeoutError | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   const agentPromise = background.runOneShotAgent(params);
 
   const timeoutPromise = new Promise<never>((_, reject) => {
     timer = setTimeout(() => {
-      timedOut = true;
+      timeoutError = new IsolatedAgentTimeoutError(timeoutMs);
       try {
         params.abortController.abort();
       } catch {
         /* ignore */
       }
-      reject(new Error(`isolated agent timed out after ${timeoutMs}ms`));
+      reject(timeoutError);
     }, timeoutMs);
     timer.unref();
   });
@@ -86,30 +104,33 @@ export async function runIsolatedAgent(
   } catch (err) {
     // Snapshot + clear before any await so a late timer can't reclassify a
     // non-timeout failure as a timeout (heartbeat learned this the hard way).
-    const wasTimeout = timedOut;
+    const wasTimeout = timeoutError;
     if (timer) {
       clearTimeout(timer);
       timer = undefined;
     }
-    if (wasTimeout) {
-      const settled = await raceWithTimeout(
-        agentPromise.catch(() => "settled"),
-        graceMs,
-      );
-      if (settled === "timed_out" && opts.evictLabel) {
-        const evict = background.evictOrphanSubprocesses;
-        if (evict) {
-          evict(opts.evictLabel).catch((sweepErr: unknown) => {
-            logError("triggers", "orphan subprocess sweep failed", sweepErr);
-          });
-        } else {
-          logWarn("triggers", "backend ignored abort and has no eviction hook");
-        }
-      }
-    } else {
+    if (!wasTimeout) {
       await agentPromise.catch(() => {});
+      throw err;
+    }
+    const settled = await raceWithTimeout(
+      agentPromise.catch(() => "settled"),
+      graceMs,
+    );
+    if (settled === "timed_out" && opts.evictLabel) {
+      const evict = background.evictOrphanSubprocesses;
+      if (evict) {
+        evict(opts.evictLabel).catch((sweepErr: unknown) => {
+          logError(category, "orphan subprocess sweep failed", sweepErr);
+        });
+      } else {
+        logWarn(category, "backend ignored abort and has no eviction hook");
+      }
     }
-    throw err;
+    // A backend that honours the abort rejects with its own error, which can
+    // win the race against the timeout's rejection. The run still ran out of
+    // wall-clock, so that is what the caller is told either way.
+    throw wasTimeout;
   } finally {
     if (timer) clearTimeout(timer);
   }

package/src/core/background/run-log.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-run markdown log files for unattended agent runs.
+ *
+ * Every background one-shot writes a transcript nobody is watching live:
+ * heartbeat, dream, isolated cron/trigger jobs, and sub-agents. They all
+ * want the same three things — create the directory, stamp a header, hand
+ * back an appender that can never throw into the run — so they share one.
+ *
+ * Appends are best-effort by design: a full disk must slow nothing down and
+ * must never fail a run whose only remaining job is to report a result.
+ */
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/** An `OneShotAgentParams.appendLog` bound to one file. */
+export type RunLogAppender = (text: string) => Promise<void>;
+
+/**
+ * Open (creating the directory) a run log at `file`, write `header`, and
+ * return the appender for it.
+ */
+export async function openRunLog(
+  file: string,
+  header: string,
+): Promise<RunLogAppender> {
+  await mkdir(dirname(file), { recursive: true }).catch(() => {});
+  const appendLog: RunLogAppender = async (text) => {
+    await appendFile(file, text).catch(() => {});
+  };
+  await appendLog(header);
+  return appendLog;
+}

package/src/core/bus/events.ts

@@ -6,11 +6,15 @@
  * a one-line union change; each addition should land together with its
  * publisher (and ideally its first subscriber).
  *
- * Two families exist today:
+ * Three families exist today:
  *
  *   - `task.*` — lifecycle of agent work, published by the task table
  *     (core/tasks). Uniform across kinds: a heartbeat pass, a dream run, an
  *     isolated cron/trigger job, and a chat turn all surface here.
+ *   - `agent.*` — the sub-agent lifecycle, published by `core/agents`:
+ *     `agent.spawned` when an isolated sub-agent run starts, `agent.settled`
+ *     when it reaches a terminal state, `agent.message` when a note or a
+ *     report crosses between an agent and its parent.
  *   - `turn.*` — the chat-domain moments inside a turn that other
  *     subsystems key off: `turn.started` fires once the warp is bound and
  *     the backend is about to run (never for a no-model refusal);
@@ -18,6 +22,7 @@
  */
 
 import type { TaskRecord } from "../tasks/types.js";
+import type { AgentState } from "../agents/types.js";
 
 /** A task left the queue and began running. */
 export interface TaskStartedEvent {
@@ -50,8 +55,50 @@ interface TurnCompletedEvent {
   readonly outputTokens: number;
 }
 
+/** A sub-agent was registered and its isolated run began. */
+export interface AgentSpawnedEvent {
+  readonly type: "agent.spawned";
+  readonly agentId: string;
+  readonly label: string;
+  readonly parentKind: "chat" | "agent";
+  /** Chat key or parent agent id — an identifier, never content. */
+  readonly parent: string;
+  readonly backendId: string;
+  readonly model: string;
+  readonly depth: number;
+}
+
+/** A sub-agent reached a terminal state. */
+export interface AgentSettledEvent {
+  readonly type: "agent.settled";
+  readonly agentId: string;
+  readonly label: string;
+  readonly state: AgentState;
+  readonly durationMs: number;
+}
+
+/**
+ * A message crossed between a sub-agent and its parent: an explicit note
+ * (`message`), or the settlement report (`result`). Ids only — the text
+ * itself never rides the bus.
+ */
+interface AgentMessageEvent {
+  readonly type: "agent.message";
+  /** Chat key or agent id. */
+  readonly from: string;
+  /** Chat key or agent id. */
+  readonly to: string;
+  readonly kind: "message" | "result";
+}
+
 export type TalonEvent =
-  TaskStartedEvent | TaskSettledEvent | TurnStartedEvent | TurnCompletedEvent;
+  | TaskStartedEvent
+  | TaskSettledEvent
+  | TurnStartedEvent
+  | TurnCompletedEvent
+  | AgentSpawnedEvent
+  | AgentSettledEvent
+  | AgentMessageEvent;
 
 export type TalonEventType = TalonEvent["type"];
 

package/src/core/config/index.ts

@@ -433,6 +433,31 @@ const configSchema = z.object({
    * silently ignored by Kilo / OpenCode, which have none.
    */
   heartbeatEffort: z.enum(REASONING_EFFORT_ENUM).optional(),
+  /**
+   * Sub-agents — the caps on Talon's own delegation mechanism (see
+   * `docs/agents.md`). There is no on/off switch: the tools are always
+   * present, and a deployment that doesn't want fan-out sets
+   * `maxConcurrent: 1` / `maxDepth: 0`.
+   *
+   *   - `maxConcurrent` — live agents daemon-wide. Each one is a real
+   *     backend run, so this is the token-spend lever.
+   *   - `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].
+   */
+  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
+        .number()
+        .int()
+        .min(30_000)
+        .max(3_600_000)
+        .default(15 * 60 * 1000),
+    })
+    .optional(),
   braveApiKey: z.string().optional(),
   /**
    * Codex-specific OpenAI API key. Prefer this, CODEX_API_KEY, or

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

@@ -0,0 +1,299 @@
+/**
+ * Parent-side sub-agent actions — spawn, list, inspect, wait, message, kill.
+ *
+ * The caller is whoever the gateway routed: a chat (the ordinary chatKey) or
+ * another sub-agent (`agent:<id>`, routed by the gateway's agent-context
+ * branch). Both can delegate, so both go through the same handlers; the only
+ * difference is the parent recorded on the new agent and which agents the
+ * caller may see.
+ *
+ * Visibility is scoped like triggers are scoped to their chat: a chat sees the
+ * agents rooted in it (descendants included), an agent sees its own
+ * descendants. An id from another chat is simply "not found".
+ */
+
+import {
+  agentIdFromContextLabel,
+  agentRegistry,
+  clampTimeout,
+  deliverToAgent,
+  getAgentCaps,
+  killAgent,
+  spawnAgent,
+  type AgentParent,
+  type AgentRecord,
+} from "../../../agents/index.js";
+import { log } from "../../../../util/log.js";
+import type { ReasoningEffortLevel } from "../../../types.js";
+import type { ActionResult } from "../../../types.js";
+import type { SharedActionHandlers } from "../types.js";
+
+const EFFORTS: ReadonlySet<string> = new Set([
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]);
+
+/** Default and ceiling for `wait_for_agent`, in seconds. */
+const DEFAULT_WAIT_S = 60;
+const MAX_WAIT_S = 120;
+
+type Caller =
+  | { kind: "chat"; chatKey: string; numericChatId: number }
+  | { kind: "agent"; agentId: string };
+
+/** Who is calling, read off the gateway's chat key. */
+function callerOf(chatId: number, chatKey: string): Caller {
+  const agentId = agentIdFromContextLabel(chatKey);
+  return agentId
+    ? { kind: "agent", agentId }
+    : { kind: "chat", chatKey, numericChatId: chatId };
+}
+
+/** The parent a newly spawned agent gets. */
+function parentOf(caller: Caller): AgentParent {
+  return caller.kind === "chat"
+    ? {
+        kind: "chat",
+        chatId: caller.chatKey,
+        numericChatId: caller.numericChatId,
+      }
+    : { kind: "agent", agentId: caller.agentId };
+}
+
+/** The agents this caller is allowed to see and act on. */
+function visible(caller: Caller): AgentRecord[] {
+  if (caller.kind === "chat") return agentRegistry.listForChat(caller.chatKey);
+  const seen: AgentRecord[] = [];
+  const queue = [caller.agentId];
+  // Breadth-first over the caller's own descendants; the registry's depth cap
+  // bounds the walk, and `seen` ids are unique by construction.
+  while (queue.length > 0) {
+    const next = agentRegistry.get(queue.shift() as string);
+    if (!next) continue;
+    for (const child of next.children) {
+      const record = agentRegistry.get(child);
+      if (!record) continue;
+      seen.push(record);
+      queue.push(child);
+    }
+  }
+  return seen;
+}
+
+/** Look one agent up within the caller's scope. */
+function lookup(caller: Caller, id: string): AgentRecord | null {
+  if (!id) return null;
+  return visible(caller).find((record) => record.id === id) ?? null;
+}
+
+function notFound(id: string): ActionResult {
+  return {
+    ok: false,
+    error: `No agent "${id}" in this chat. Call list_agents to see yours.`,
+  };
+}
+
+function ageOf(record: AgentRecord): string {
+  const end = record.endedAt ?? Date.now();
+  return `${Math.round((end - record.createdAt) / 1000)}s`;
+}
+
+/** One line per agent for `list_agents`. */
+function renderListEntry(record: AgentRecord): string {
+  return (
+    `- ${record.label} [${record.state}]\n` +
+    `  ID: ${record.id}\n` +
+    `  Backend: ${record.backendId}/${record.model ?? "(resolving)"}\n` +
+    `  Depth: ${record.depth}  Age: ${ageOf(record)}  ` +
+    `Result: ${record.result ? "yes" : "no"}`
+  );
+}
+
+/** The full `agent_status` body — everything but the brief. */
+function renderStatus(record: AgentRecord): string {
+  const lines = [
+    `Agent "${record.label}" (${record.id})`,
+    `State: ${record.state}`,
+    `Backend: ${record.backendId}/${record.model ?? "(resolving)"}` +
+      (record.reasoningEffort ? ` effort=${record.reasoningEffort}` : ""),
+    `Depth: ${record.depth}  Age: ${ageOf(record)}  Inbox: ${record.inboxDepth}`,
+  ];
+  if (record.children.length > 0) {
+    lines.push(`Children: ${record.children.join(", ")}`);
+  }
+  if (record.usage) {
+    lines.push(
+      `Tokens: in=${record.usage.inputTokens} out=${record.usage.outputTokens}`,
+    );
+  }
+  if (record.result) {
+    lines.push("", `Result: ${record.result.summary}`);
+    if (record.result.details) lines.push("", record.result.details);
+  }
+  if (record.error) lines.push("", `Error: ${record.error}`);
+  if (!record.result && !record.error) {
+    lines.push("", "No result yet — the agent is still working.");
+  }
+  return lines.join("\n");
+}
+
+/** Validate and normalise `spawn_agent`'s body. */
+function readSpawnBody(body: Record<string, unknown>):
+  | {
+      ok: true;
+      brief: string;
+      label: string;
+      backendId?: string;
+      model?: string;
+      reasoningEffort?: ReasoningEffortLevel;
+      timeoutMs?: number;
+    }
+  | { ok: false; error: string } {
+  const brief = String(body.brief ?? "").trim();
+  if (!brief) return { ok: false, error: "Missing brief" };
+  const label = String(body.label ?? "").trim();
+  if (!label) return { ok: false, error: "Missing label" };
+  const effort = body.effort === undefined ? undefined : String(body.effort);
+  if (effort !== undefined && !EFFORTS.has(effort)) {
+    return {
+      ok: false,
+      error: `Unknown effort "${effort}". Use minimal, low, medium, high or xhigh.`,
+    };
+  }
+  const timeoutS =
+    body.timeout_s === undefined ? undefined : Number(body.timeout_s);
+  if (timeoutS !== undefined && !Number.isFinite(timeoutS)) {
+    return { ok: false, error: "timeout_s must be a number of seconds" };
+  }
+  return {
+    ok: true,
+    brief,
+    label,
+    ...(body.backend ? { backendId: String(body.backend) } : {}),
+    ...(body.model ? { model: String(body.model) } : {}),
+    ...(effort !== undefined
+      ? { reasoningEffort: effort as ReasoningEffortLevel }
+      : {}),
+    ...(timeoutS !== undefined
+      ? { timeoutMs: clampTimeout(timeoutS * 1000) }
+      : {}),
+  };
+}
+
+export const agentControlHandlers: SharedActionHandlers = {
+  spawn_agent: async (body, chatId, _backend, chatKey) => {
+    const parsed = readSpawnBody(body);
+    if (!parsed.ok) return parsed;
+    const caller = callerOf(chatId, chatKey);
+    const outcome = await spawnAgent({
+      brief: parsed.brief,
+      label: parsed.label,
+      parent: parentOf(caller),
+      ...(parsed.backendId ? { backendId: parsed.backendId } : {}),
+      ...(parsed.model ? { model: parsed.model } : {}),
+      ...(parsed.reasoningEffort
+        ? { reasoningEffort: parsed.reasoningEffort }
+        : {}),
+      ...(parsed.timeoutMs !== undefined
+        ? { timeoutMs: parsed.timeoutMs }
+        : {}),
+    });
+    if (!outcome.ok) return { ok: false, error: outcome.error };
+    const timeoutS = Math.round(clampTimeout(parsed.timeoutMs) / 1000);
+    log("gateway", `spawn_agent: "${parsed.label}" [${outcome.agentId}]`);
+    return {
+      ok: true,
+      text:
+        `Spawned agent "${parsed.label}" (id: ${outcome.agentId})\n` +
+        `Backend: ${outcome.backendId}/${outcome.model}\n` +
+        `Timeout: ${timeoutS}s\n` +
+        `It runs in the background. You will be woken with its report — ` +
+        `carry on with what you were doing.`,
+    };
+  },
+
+  list_agents: (body, chatId, _backend, chatKey) => {
+    const records = visible(callerOf(chatId, chatKey));
+    if (records.length === 0) {
+      return { ok: true, text: "No sub-agents for this chat." };
+    }
+    const caps = getAgentCaps();
+    return {
+      ok: true,
+      text:
+        `Agents (${records.length}, ${agentRegistry.liveCount()} live of ` +
+        `${caps.maxConcurrent} daemon-wide):\n\n` +
+        records.map(renderListEntry).join("\n\n"),
+    };
+  },
+
+  agent_status: (body, chatId, _backend, chatKey) => {
+    const id = String(body.agent_id ?? "");
+    const record = lookup(callerOf(chatId, chatKey), id);
+    if (!record) return notFound(id);
+    return { ok: true, text: renderStatus(record) };
+  },
+
+  wait_for_agent: async (body, chatId, _backend, chatKey) => {
+    const id = String(body.agent_id ?? "");
+    const record = lookup(callerOf(chatId, chatKey), id);
+    if (!record) return notFound(id);
+    const requested = Number(body.timeout_s ?? DEFAULT_WAIT_S);
+    const seconds = Math.min(
+      MAX_WAIT_S,
+      Math.max(1, Number.isFinite(requested) ? requested : DEFAULT_WAIT_S),
+    );
+    const settled = await agentRegistry.waitForSettle(id, seconds * 1000);
+    if (!settled) return notFound(id);
+    if (settled.state === "running" || settled.state === "queued") {
+      return {
+        ok: true,
+        text:
+          `Agent "${settled.label}" (${id}) is still ${settled.state} after ` +
+          `${seconds}s. Stop waiting — its report will wake you when it lands.`,
+      };
+    }
+    return { ok: true, text: renderStatus(settled) };
+  },
+
+  send_to_agent: (body, chatId, _backend, chatKey) => {
+    const id = String(body.agent_id ?? "");
+    const caller = callerOf(chatId, chatKey);
+    const record = lookup(caller, id);
+    if (!record) return notFound(id);
+    const text = String(body.text ?? "").trim();
+    if (!text) return { ok: false, error: "Missing text" };
+    const from = caller.kind === "chat" ? caller.chatKey : caller.agentId;
+    if (!deliverToAgent(from, id, text)) {
+      return {
+        ok: false,
+        error:
+          `Could not deliver to "${id}": it has already settled, or its ` +
+          `inbox is full. Check agent_status.`,
+      };
+    }
+    return {
+      ok: true,
+      text: `Queued for agent "${record.label}" (${id}). It reads its inbox at its own milestones.`,
+    };
+  },
+
+  kill_agent: (body, chatId, _backend, chatKey) => {
+    const id = String(body.agent_id ?? "");
+    const record = lookup(callerOf(chatId, chatKey), id);
+    if (!record) return notFound(id);
+    if (!killAgent(id)) {
+      return {
+        ok: true,
+        text: `Agent "${record.label}" (${id}) had already settled as "${record.state}".`,
+      };
+    }
+    return {
+      ok: true,
+      text: `Abort requested for agent "${record.label}" (${id}). You will still get its report.`,
+    };
+  },
+};

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

@@ -0,0 +1,31 @@
+/**
+ * Sub-agent actions — the registry half of `core/tools/ops/agents.ts`.
+ *
+ *   - `control` — what a parent calls: spawn / list / status / wait / send /
+ *     kill. Works from a chat and from inside another agent.
+ *   - `report`  — what a sub-agent calls about itself: report_result /
+ *     message_parent / check_inbox.
+ *
+ * Both sets are reachable from an `agent:<id>` context: the gateway routes
+ * those chat keys straight here (see `Gateway.handleAction`), because a
+ * sub-agent has an identity but no chat, and `agentContextActions` is the
+ * list it consults.
+ */
+
+import type { SharedActionHandlers } from "../types.js";
+import { agentControlHandlers } from "./control.js";
+import { agentReportHandlers } from "./report.js";
+
+export const agentHandlers: SharedActionHandlers = {
+  ...agentControlHandlers,
+  ...agentReportHandlers,
+};
+
+/**
+ * Actions the gateway will dispatch for an `agent:<id>` chat key. Everything
+ * else stays chat-routed — a sub-agent calling a chat-scoped action still has
+ * to name a chat explicitly, exactly as a heartbeat run does.
+ */
+export const agentContextActions: ReadonlySet<string> = new Set(
+  Object.keys(agentHandlers),
+);