talon-agent 5.28.0 → 5.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.28.0",
+  "version": "5.29.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",
@@ -111,7 +111,7 @@
     "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openai/agents": "^0.18.0",
-    "@openai/codex-sdk": "^0.155.0",
+    "@openai/codex-sdk": "^0.156.1",
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.56",
     "@types/cross-spawn": "^6.0.6",

package/src/core/agents/runner.ts

@@ -112,7 +112,10 @@ export function initAgents(
     "agents",
     `Initialized — maxConcurrent=${capsHolder.caps.maxConcurrent} ` +
       `maxDepth=${capsHolder.caps.maxDepth} ` +
-      `timeout=${Math.round(capsHolder.caps.defaultTimeoutMs / 1000)}s`,
+      `timeout=${Math.round(capsHolder.caps.defaultTimeoutMs / 1000)}s` +
+      (capsHolder.caps.allowedBackends?.length
+        ? ` allowedBackends=${capsHolder.caps.allowedBackends.join(",")}`
+        : ""),
   );
 }
 
@@ -137,19 +140,37 @@ function inheritedBackendId(parent: AgentParent): string | null {
   return agentRegistry.get(parent.agentId)?.backendId ?? null;
 }
 
+/** Where a spawn lands: backend, the model it inherits, and why. */
+interface SpawnTarget {
+  readonly backendId: string | null;
+  /** The parent agent's model, inherited by an unpinned child. */
+  readonly inheritedModel?: string;
+  readonly routing?: string;
+}
+
 /**
  * Which backend this agent runs on, and why.
  *
  * An explicit backend (or model — a model id is backend-specific, so naming
- * one pins its backend) is honoured as written. With neither, the run is a
- * routing decision: sub-agents are isolated one-shots with no session to
- * keep warm, so they are the cheapest work to move onto whichever
- * subscription has room.
+ * one pins its backend) is honoured as written. A child of another agent
+ * with neither inherits its parent's backend *and* model: a tree of agents
+ * stays on the backend its root was put on, so a parent that chose (or was
+ * told to use) a backend does not see its children wander off to another
+ * subscription. A top-level spawn with neither is a routing decision:
+ * sub-agents are isolated one-shots with no session to keep warm, so they
+ * are the cheapest work to move onto whichever subscription has room.
  */
-async function resolveSpawnBackend(
-  spec: AgentSpawnSpec,
-): Promise<{ backendId: string | null; routing?: string }> {
+async function resolveSpawnBackend(spec: AgentSpawnSpec): Promise<SpawnTarget> {
   if (spec.backendId) return { backendId: spec.backendId };
+  if (spec.parent.kind === "agent" && !spec.model) {
+    const parent = agentRegistry.get(spec.parent.agentId);
+    if (parent) {
+      return {
+        backendId: parent.backendId,
+        ...(parent.model ? { inheritedModel: parent.model } : {}),
+      };
+    }
+  }
   const inherited = inheritedBackendId(spec.parent);
   if (!inherited) return { backendId: null };
   const taskClass = taskClassForEffort(spec.reasoningEffort);
@@ -166,12 +187,37 @@ async function resolveSpawnBackend(
         }
       : {}),
   });
+  // A routed pick outside the allowlist falls back to the inherited
+  // backend rather than refusing a spawn the caller never pinned.
+  if (
+    decision.routed &&
+    !isBackendAllowed(decision.backendId) &&
+    isBackendAllowed(inherited)
+  ) {
+    return { backendId: inherited };
+  }
   return {
     backendId: decision.backendId,
     ...(decision.routed ? { routing: decision.reason } : {}),
   };
 }
 
+/** Whether `agents.allowedBackends` (when set) lets an agent run here. */
+function isBackendAllowed(backendId: string): boolean {
+  const allowed = capsHolder.caps.allowedBackends;
+  return !allowed || allowed.length === 0 || allowed.includes(backendId);
+}
+
+/** The tool error for a backend outside `agents.allowedBackends`. */
+function disallowedBackendError(backendId: string): string {
+  const allowed = capsHolder.caps.allowedBackends ?? [];
+  return (
+    `Backend "${backendId}" is not allowed for sub-agents ` +
+    `(agents.allowedBackends: ${allowed.join(", ")}). Pass one of those ` +
+    `as backend, or leave it unset to inherit.`
+  );
+}
+
 /** The chat a run's task belongs to, for `talon ps`. */
 function taskChatId(parent: AgentParent): string | undefined {
   if (parent.kind === "chat") return parent.chatId;
@@ -262,6 +308,10 @@ export async function spawnAgent(
         "Could not resolve a backend for this agent — pass one explicitly.",
     };
   }
+  if (!isBackendAllowed(backendId)) {
+    return { ok: false, error: disallowedBackendError(backendId) };
+  }
+  const model = spec.model ?? routed.inheritedModel;
 
   // Register first: the slot and the depth are claimed synchronously, so two
   // concurrent spawns can never both slip past maxConcurrent while awaiting
@@ -296,7 +346,7 @@ export async function spawnAgent(
     };
   }
 
-  const resolved = await resolveRun(acquired.backend, backendId, spec.model);
+  const resolved = await resolveRun(acquired.backend, backendId, model);
   if (!resolved.ok) {
     agentRegistry.discard(record.id);
     await acquired.release();

package/src/core/agents/types.ts

@@ -94,9 +94,16 @@ 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`. */
@@ -132,4 +139,9 @@ export interface AgentCaps {
   readonly maxDepth: number;
   /** Default hard timeout for one run. */
   readonly defaultTimeoutMs: 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/config/index.ts

@@ -643,6 +643,9 @@ const configSchema = z.object({
    *     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].
+   *   - `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({
@@ -654,6 +657,7 @@ const configSchema = z.object({
         .min(30_000)
         .max(3_600_000)
         .default(15 * 60 * 1000),
+      allowedBackends: z.array(z.string().min(1)).optional(),
     })
     .optional(),
   /**

package/src/core/tools/ops/agents.ts

@@ -35,8 +35,8 @@ Bad uses: anything needing a back-and-forth with the user, trivial work you
 could do in one tool call, or work whose result you need in the next second
 (spawning costs a model cold-start).
 
-Backend and model default to this chat's; pass them to put the agent
-somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
+Backend and model default to the caller's (a sub-agent's own children
+inherit its backend and model); pass them to put the agent somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
 a bigger context window). Returns the agent id immediately.`;
 
 export const agentTools: ToolDefinition[] = [
@@ -61,13 +61,13 @@ export const agentTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe(
-          "Backend id to run on. Unset = this chat's backend (agents inherit their parent's). Must have a background capability.",
+          "Backend id to run on. Unset = inherit: an agent's children run on its own backend and model; a chat's spawns start from the chat's backend (and may be routed to one with more headroom). Must have a background capability and, when the deployment sets agents.allowedBackends, be on that list.",
         ),
       model: z
         .string()
         .optional()
         .describe(
-          "Model id on the chosen backend. Unset = that backend's default model. Call list_models for valid ids.",
+          "Model id on the chosen backend. Unset = the parent agent's model when the backend is inherited from one, else that backend's default model. Call list_models for valid ids.",
         ),
       effort: z
         .enum(["minimal", "low", "medium", "high", "xhigh"])

package/src/frontend/discord/handlers/messages.ts

@@ -66,15 +66,17 @@ export async function handleMessage(
   if (msg.attachments.size > 0) {
     for (const att of msg.attachments.values()) {
       try {
-        const savedPath = await downloadAttachment(att, config.workspace);
+        const downloadedPath = await downloadAttachment(att, config.workspace);
         const cls = classifyAttachment(att);
-        setMessageFilePath(chatId, numericMessageId, savedPath);
-        addMedia({
+        setMessageFilePath(chatId, numericMessageId, downloadedPath);
+        // addMedia may dedupe onto an existing identical file and delete
+        // the fresh download — prompt with the path it resolves to.
+        const savedPath = await addMedia({
           chatId,
           msgId: numericMessageId,
           senderName: sender,
           type: cls.type,
-          filePath: savedPath,
+          filePath: downloadedPath,
           caption: cleanedContent || undefined,
           timestamp: Date.now(),
         });

package/src/frontend/telegram/actions/chat-info.ts

@@ -21,6 +21,7 @@ import {
   getPinnedMessages as userbotPinnedMessages,
   getOnlineCount as userbotOnlineCount,
 } from "../userbot.js";
+import { getMediaForMessage } from "../../../storage/media-index.js";
 import { savePackToLibrary } from "../sticker-library.js";
 import { toPositiveId } from "./coerce.js";
 import type { TelegramActionHandlers } from "./types.js";
@@ -308,16 +309,32 @@ export const chatInfoHandlers: TelegramActionHandlers = {
   },
 
   download_media: async (body, chatId) => {
+    const msgId = toPositiveId(body.message_id);
+    if (!msgId) return { ok: false, error: "Required: message_id" };
+    // Media the bot received is already on disk and indexed. Answer from
+    // the index first: the userbot can't see messages in the bot's own
+    // DMs (message ids there are per-account), so asking it for an
+    // inbound photo by id reports "not found".
+    const indexed = getMediaForMessage(String(chatId), msgId);
+    if (indexed && existsSync(indexed.filePath)) {
+      return {
+        ok: true,
+        text: `Saved at: ${indexed.filePath} (${indexed.type}). Use the Read tool on this path to view the content.`,
+        file_path: indexed.filePath,
+      };
+    }
     if (isUserClientReady()) {
       const { downloadMessageMedia } = await import("../userbot.js");
       return {
         ok: true,
-        text: await downloadMessageMedia({
-          chatId,
-          messageId: Number(body.message_id),
-        }),
+        text: await downloadMessageMedia({ chatId, messageId: msgId }),
       };
     }
-    return { ok: false, error: "User client not connected." };
+    return {
+      ok: false,
+      error: indexed
+        ? `Media for message ${msgId} is no longer on disk and the user client is not connected to re-download it.`
+        : "User client not connected.",
+    };
   },
 };

package/src/frontend/telegram/handlers/messages.ts

@@ -72,16 +72,18 @@ async function handleMediaMessage(
       return;
     }
 
-    const savedPath = await downloadTelegramFile(
+    const downloadedPath = await downloadTelegramFile(
       bot,
       config,
       media.fileId,
       media.fileName,
     );
 
-    // Store file path in history + media index
-    setMessageFilePath(chatId, ctx.message.message_id, savedPath);
-    addMedia({
+    // Store file path in history + media index. addMedia may dedupe the
+    // download onto an identical file already on disk (and delete the
+    // fresh one), so the prompt must use the path it resolves to.
+    setMessageFilePath(chatId, ctx.message.message_id, downloadedPath);
+    const savedPath = await addMedia({
       chatId,
       msgId: ctx.message.message_id,
       senderName: sender,
@@ -93,7 +95,7 @@ async function handleMediaMessage(
         | "animation"
         | "audio"
         | "sticker",
-      filePath: savedPath,
+      filePath: downloadedPath,
       caption: media.caption,
       timestamp: Date.now(),
     });

package/src/frontend/whatsapp/messages/media-store.ts

@@ -96,7 +96,9 @@ export async function saveInboundMedia(
     writeFileSync(filePath, buffer);
 
     const caption = content?.caption ?? undefined;
-    addMedia({
+    // addMedia may dedupe onto an existing identical file and delete
+    // this download — report the path it resolves to.
+    const savedPath = await addMedia({
       chatId,
       msgId,
       senderName,
@@ -105,7 +107,7 @@ export async function saveInboundMedia(
       timestamp: Date.now(),
       ...(caption ? { caption } : {}),
     });
-    return { filePath, type, ...(caption ? { caption } : {}) };
+    return { filePath: savedPath, type, ...(caption ? { caption } : {}) };
   } catch (err) {
     logWarn(
       "whatsapp",

package/src/storage/media-index.ts

@@ -73,7 +73,19 @@ function importLegacyMediaIndex(): void {
 
 // ── CRUD ────────────────────────────────────────────────────────────────────
 
-export function addMedia(entry: Omit<MediaEntry, "id">): void {
+/**
+ * Index a downloaded file and dedupe it against identical content.
+ *
+ * Resolves to the path the message's media now lives at — the
+ * canonical copy when the download duplicated one already on disk
+ * (the fresh file is then deleted), otherwise `entry.filePath`.
+ * Callers MUST use the resolved path for anything they show the
+ * model: the original path may no longer exist once this settles.
+ *
+ * The row is written synchronously, so it is queryable before the
+ * hash finishes.
+ */
+export async function addMedia(entry: Omit<MediaEntry, "id">): Promise<string> {
   try {
     repo.upsert(entry);
   } catch (err) {
@@ -85,13 +97,32 @@ export function addMedia(entry: Omit<MediaEntry, "id">): void {
     recordError(
       `Media index write failed: ${err instanceof Error ? err.message : err}`,
     );
-    return;
+    return entry.filePath;
   }
-  // Hash + dedupe off the hot path — the caller is mid-message-handling
-  // and the row is already queryable without the hash.
-  void hashAndDedupe(entry).catch((err) =>
-    logError("media", `Media content hash failed for ${entry.filePath}`, err),
+  // Serialize dedupe: two identical files hashed concurrently (e.g. an
+  // album) could otherwise each pick the other as canonical and both
+  // get unlinked.
+  const run = dedupeChain.then(() => hashAndDedupe(entry));
+  dedupeChain = run.then(
+    () => undefined,
+    () => undefined,
   );
+  try {
+    return await run;
+  } catch (err) {
+    logError("media", `Media content hash failed for ${entry.filePath}`, err);
+    return entry.filePath;
+  }
+}
+
+let dedupeChain: Promise<void> = Promise.resolve();
+
+/** The indexed entry for a message, if any. */
+export function getMediaForMessage(
+  chatId: string,
+  msgId: number,
+): MediaEntry | undefined {
+  return repo.byMessage(chatId, msgId);
 }
 
 /**
@@ -101,15 +132,15 @@ export function addMedia(entry: Omit<MediaEntry, "id">): void {
  * canonical copy and drop the duplicate file, so re-posted media costs
  * one copy on disk no matter how many messages carry it.
  */
-async function hashAndDedupe(entry: Omit<MediaEntry, "id">): Promise<void> {
-  if (!existsSync(entry.filePath)) return; // gone already (expiry, tests)
+async function hashAndDedupe(entry: Omit<MediaEntry, "id">): Promise<string> {
+  if (!existsSync(entry.filePath)) return entry.filePath; // gone already (expiry, tests)
   const hash = await blake3HexFile(entry.filePath);
   repo.setContentHash(entry.chatId, entry.msgId, hash);
 
   const canonical = repo.firstByContentHash(hash, entry.chatId, entry.msgId);
-  if (!canonical) return;
-  if (canonical.filePath === entry.filePath) return; // re-download of the same path
-  if (!existsSync(canonical.filePath)) return; // canonical copy lost — keep ours
+  if (!canonical) return entry.filePath;
+  if (canonical.filePath === entry.filePath) return entry.filePath; // re-download of the same path
+  if (!existsSync(canonical.filePath)) return entry.filePath; // canonical copy lost — keep ours
 
   repo.setFilePath(entry.chatId, entry.msgId, canonical.filePath);
   setMessageFilePath(entry.chatId, entry.msgId, canonical.filePath);
@@ -131,6 +162,7 @@ async function hashAndDedupe(entry: Omit<MediaEntry, "id">): Promise<void> {
       );
     }
   }
+  return canonical.filePath;
 }
 
 /** Get recent media for a chat, newest first. */

package/src/storage/repositories/media-index-repo.ts

@@ -33,7 +33,7 @@ export type MediaEntry = {
   timestamp: number;
   /**
    * BLAKE3 hex digest of the file contents (native/blake3-wasm).
-   * Filled in asynchronously after addMedia; undefined until hashed.
+   * Filled in by addMedia before it resolves; undefined until hashed.
    */
   contentHash?: string;
 };
@@ -112,6 +112,17 @@ export function firstByContentHash(
   return row ? rowToEntry(row) : undefined;
 }
 
+/** The entry for one message, if indexed. */
+export function byMessage(
+  chatId: string,
+  msgId: number,
+): MediaEntry | undefined {
+  const row = getDatabase()
+    .prepare(mediaIndexSql.byMessage)
+    .get(chatId, msgId) as Row | undefined;
+  return row ? rowToEntry(row) : undefined;
+}
+
 /** Entries currently pointing at a file — dedupe makes this > 1. */
 export function countByFilePath(filePath: string): number {
   const row = getDatabase()

package/src/storage/sql/media-index.sql

@@ -43,3 +43,7 @@ ORDER BY timestamp ASC, rowid ASC LIMIT 1
 
 -- name: countByFilePath
 SELECT COUNT(*) AS n FROM media_index WHERE file_path = ?
+
+-- name: byMessage
+SELECT chat_id, msg_id, sender_name, type, file_path, caption, timestamp, content_hash
+FROM media_index WHERE chat_id = ? AND msg_id = ?

package/src/storage/sql/statements.generated.ts

@@ -767,6 +767,8 @@ FROM media_index
 WHERE content_hash = ? AND NOT (chat_id = ? AND msg_id = ?)
 ORDER BY timestamp ASC, rowid ASC LIMIT 1`,
   countByFilePath: `SELECT COUNT(*) AS n FROM media_index WHERE file_path = ?`,
+  byMessage: `SELECT chat_id, msg_id, sender_name, type, file_path, caption, timestamp, content_hash
+FROM media_index WHERE chat_id = ? AND msg_id = ?`,
 } as const;
 
 export const memorySql = {