talon-agent 3.20.0 → 3.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.20.0",
+  "version": "3.22.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -102,7 +102,7 @@
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/agents": "^0.14.0",
+    "@openai/agents": "^0.16.0",
     "@openai/codex-sdk": "^0.147.0",
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.79",
@@ -113,11 +113,11 @@
     "cross-spawn": "^7.0.6",
     "discord.js": "^14.16.3",
     "file-type": "^22.0.1",
-    "grammy": "^1.42.0",
+    "grammy": "^1.45.1",
     "liquidjs": "^10.27.0",
     "marked": "^18.0.0",
     "mem0ai": "^3.0.13",
-    "openai": "^6.46.0",
+    "openai": "^7.5.0",
     "p-retry": "^8.0.0",
     "picocolors": "^1.1.1",
     "pino": "^10.3.1",

package/prompts/base.md

@@ -1,12 +1,6 @@
 Be concise and direct. Lead with the substance, keep it as short as the moment needs, and stop when it's said.
 
-## Conversation
-
-- Answer first; context and caveats after, and only when they change something for the reader.
-- Let depth follow the question: a quick ask gets a line or two, a real problem gets real work. When unsure, start small — people ask for more when they want it.
-- Chat is not a document. Plain sentences usually beat headings, bullet cascades, and closing summaries; reach for structure only when it genuinely clarifies.
-- Don't narrate your process or pad with filler — do the thing, then share what matters.
-- A short clarifying question beats a long answer to the wrong question, but only when the ambiguity is real.
+How you talk — voice, stances, what never to say — is the Identity section above. It applies on every backend and isn't repeated here.
 
 ## Tools
 

package/prompts/identity.md

@@ -1,6 +1,6 @@
 ## Who you are
 
-You're a Talon agent — a peer with tools, not a service desk. The model and tools available to you depend on the active backend; only the tools listed below this prompt actually exist for this run. Tools for talking to your current platform (send, react, and the rest) are always provided by the frontend.
+You're a Talon agent — a peer with tools, not a service desk. People talk to you all day; be someone worth talking to. The model and tools available to you depend on the active backend; only the tools listed below this prompt actually exist for this run. Tools for talking to your current platform (send, react, and the rest) are always provided by the frontend.
 
 ## Voice
 
@@ -10,13 +10,15 @@ Length follows the question, not habit: a quick ask gets a line or two, a real p
 
 Have opinions and give reasons. "I'd use X, because Y" beats five options with no recommendation.
 
-Match the room. Casual chat gets casual replies, technical questions get precise answers, and a tense thread doesn't need you adding heat. Follow up on what's genuinely interesting — not out of habit.
+Engage with what was actually said, not the generic shape of it. The detail someone mentions in passing is often the interesting part; picking it up is the difference between a conversation and a ticket.
 
-Be expressive where the platform allows — emoji, reactions, stickers, humour — as seasoning, not the meal.
+Match the room. Casual chat gets casual replies, technical questions get precise answers, and a tense thread doesn't need you adding heat. Humour, emoji, reactions, stickers — wherever the platform has them, use them the way a person would: as seasoning, not the meal.
+
+Sound like yourself. Plain words, contractions, the occasional aside. A reply that reads like a person thinking beats one that reads like a product performing.
 
 ## Stances
 
-Situations are what define a voice. Take these positions.
+Voice shows up in the awkward moments. Take these positions.
 
 **Their plan is bad.** Say what's wrong in a sentence or two, then do the work as asked. Don't refuse to engage, don't lecture, and don't quietly do it a different way instead.
 
@@ -30,7 +32,7 @@ Situations are what define a voice. Take these positions.
 
 **The request is ambiguous.** Make the call a careful colleague would make, and say which call you made. Ask only when different readings would mean materially different work.
 
-**You have nothing to add.** Then don't add it. "ok", "thanks", "lol" want a reaction or silence, not a reply. In groups you're a participant, not a host — don't answer for other people, and let conversations that aren't about you flow past.
+**You have nothing to add.** Then don't. "ok", "thanks", "lol" want a reaction or silence, not a reply. In groups you're a participant, not a host — don't answer for other people, and let conversations that aren't about you flow past.
 
 ## Never
 

package/src/bootstrap.ts

@@ -415,6 +415,14 @@ export async function initBackendAndDispatcher(
       );
       return { model, backendId: beId };
     },
+    // ...and when that ambient backend turns out to be one that can't host an
+    // isolated run (e.g. the chat was switched to a provider with no background
+    // capability), the job reruns on the heartbeat role backend instead of
+    // being skipped.
+    resolveJobFallback: () => ({
+      backendId: config.heartbeatBackend ?? config.backend,
+      model: config.heartbeatModel ?? config.model ?? null,
+    }),
   });
   initTriggers({ execute: dispatcherExecute });
   resumeTriggersAfterRestart().catch((err) =>

package/src/core/background/cron.ts

@@ -62,6 +62,13 @@ type CronDeps = {
   resolveChatModel: (
     chatId: string,
   ) => Promise<{ model: string | null; backendId: string }>;
+  /**
+   * Resolve the deployment's background-capable role backend (heartbeat, else
+   * the configured default). Used as a fallback for query jobs that inherited
+   * the chat's ambient backend and found it can't run isolated jobs — a
+   * `/model` switch in the chat shouldn't silently disable the schedule.
+   */
+  resolveJobFallback?: () => { model: string | null; backendId: string };
 };
 
 let deps: CronDeps | null = null;
@@ -473,6 +480,10 @@ export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
   // chat's backend + active model.
   let backendId: string;
   let model: string | null;
+  // A job that pinned its own provider is honoured as written — no fallback.
+  // One that inherited the chat's ambient backend gets a safety net, because
+  // that backend can change under it at any time (`/model`, a rebind).
+  let fallback: { backendId: string; model: string } | undefined;
   if (job.provider) {
     backendId = job.provider;
     model = job.model ?? null;
@@ -480,6 +491,10 @@ export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
     const chat = await deps.resolveChatModel(job.chatId);
     backendId = chat.backendId;
     model = job.model ?? chat.model;
+    const candidate = deps.resolveJobFallback?.();
+    if (candidate?.model) {
+      fallback = { backendId: candidate.backendId, model: candidate.model };
+    }
   }
   if (!model) {
     throw new Error(
@@ -502,6 +517,7 @@ export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
     label: job.name,
     kind: "cron",
     timeoutMs: CRON_JOB_TIMEOUT_MS,
+    ...(fallback ? { fallback } : {}),
   });
   if (result.status === "skipped") {
     await deps.sendMessage(

package/src/core/background/job-oneshot.ts

@@ -51,6 +51,19 @@ export interface JobOneShotParams {
   readonly kind: JobKind;
   /** Optional override of the hard timeout. */
   readonly timeoutMs?: number;
+  /**
+   * Backend to retry on when the primary one can't host an isolated run.
+   *
+   * A cron `query` job with no provider override inherits the chat's *ambient*
+   * backend, which any `/model` switch can change out from under it — including
+   * to a provider with no background capability (or one where the chat's model
+   * isn't selectable). That has nothing to do with the job, so rather than skip
+   * it, fall back to the deployment's background-capable role backend
+   * (heartbeat, else the configured default). Omitted for jobs that pinned
+   * their own provider: an explicit choice is honoured or skipped, never
+   * silently rerouted.
+   */
+  readonly fallback?: { readonly backendId: string; readonly model: string };
 }
 
 export type JobOneShotResult =
@@ -75,7 +88,17 @@ async function openJobLog(
   return appendLog;
 }
 
-function skipJob(params: JobOneShotParams, reason: string): JobOneShotResult {
+// The warning is deferred to runJobOneShot: an attempt that fails here may
+// still succeed on the fallback backend, and a run that ultimately ran must
+// not leave a "skipped" warning in the logs.
+function skipJob(reason: string): JobOneShotResult {
+  return { status: "skipped", reason };
+}
+
+function reportSkip(
+  params: JobOneShotParams,
+  reason: string,
+): JobOneShotResult {
   logWarn(
     params.kind === "cron" ? "cron" : "triggers",
     `isolated job "${params.label}" skipped: ${reason}`,
@@ -84,19 +107,20 @@ function skipJob(params: JobOneShotParams, reason: string): JobOneShotResult {
 }
 
 /**
- * Run a trigger/cron wake-up as an isolated one-shot on a different backend.
- * Acquires the target backend on demand and always releases it afterwards.
+ * One attempt on one backend: acquire it, check it can actually host an
+ * isolated run, execute, and always release it afterwards.
  */
-export async function runJobOneShot(
+async function attemptJobOneShot(
   params: JobOneShotParams,
+  backendId: string,
+  model: string,
 ): Promise<JobOneShotResult> {
   let acquired: Awaited<ReturnType<typeof acquireBackendInstance>>;
   try {
-    acquired = await acquireBackendInstance(params.backendId);
+    acquired = await acquireBackendInstance(backendId);
   } catch (err) {
     return skipJob(
-      params,
-      `provider "${params.backendId}" is unavailable: ${err instanceof Error ? err.message : String(err)}`,
+      `provider "${backendId}" is unavailable: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
 
@@ -105,32 +129,29 @@ export async function runJobOneShot(
     const background = backend.background;
     if (!background) {
       return skipJob(
-        params,
-        `provider "${params.backendId}" can't run isolated jobs (no background capability).`,
+        `provider "${backendId}" can't run isolated jobs (no background capability).`,
       );
     }
 
     let modelValid = false;
     try {
-      modelValid = await isModelValidForBackend(backend, params.model);
+      modelValid = await isModelValidForBackend(backend, model);
     } catch (err) {
       return skipJob(
-        params,
-        `could not validate model "${params.model}" on provider "${params.backendId}": ${err instanceof Error ? err.message : String(err)}`,
+        `could not validate model "${model}" on provider "${backendId}": ${err instanceof Error ? err.message : String(err)}`,
       );
     }
     if (!modelValid) {
       return skipJob(
-        params,
-        `model "${params.model}" is not selectable on provider "${params.backendId}".`,
+        `model "${model}" is not selectable on provider "${backendId}".`,
       );
     }
 
     const appendLog = await openJobLog(
       params.kind,
       params.label,
-      params.backendId,
-      params.model,
+      backendId,
+      model,
     );
 
     const abortController = new AbortController();
@@ -140,7 +161,7 @@ export async function runJobOneShot(
       chatId: params.chatId,
       abort: () => abortController.abort(),
     });
-    task.bind({ model: params.model, backendId: params.backendId });
+    task.bind({ model, backendId });
 
     const oneShot: OneShotAgentParams = {
       prompt: params.payload,
@@ -151,7 +172,7 @@ export async function runJobOneShot(
       ),
       contextLabel: JOB_CONTEXT_LABEL,
       workspace: dirs.workspace,
-      model: params.model,
+      model,
       abortController,
       appendLog,
     };
@@ -172,10 +193,49 @@ export async function runJobOneShot(
     }
     log(
       params.kind === "cron" ? "cron" : "triggers",
-      `isolated job "${params.label}" ran on ${params.backendId}/${params.model}`,
+      `isolated job "${params.label}" ran on ${backendId}/${model}`,
     );
     return { status: "ran" };
   } finally {
     await release();
   }
 }
+
+/**
+ * Run a trigger/cron wake-up as an isolated one-shot.
+ *
+ * Tries the requested backend first. When that backend can't host the run at
+ * all — no background capability, unavailable, or the inherited model isn't
+ * selectable on it — and a distinct {@link JobOneShotParams.fallback} was
+ * supplied, the job is retried there instead of being skipped. A job is only
+ * reported as skipped once every candidate has been ruled out.
+ */
+export async function runJobOneShot(
+  params: JobOneShotParams,
+): Promise<JobOneShotResult> {
+  const first = await attemptJobOneShot(params, params.backendId, params.model);
+  if (first.status === "ran") return first;
+
+  const { fallback } = params;
+  if (
+    !fallback ||
+    (fallback.backendId === params.backendId && fallback.model === params.model)
+  ) {
+    return reportSkip(params, first.reason);
+  }
+
+  log(
+    params.kind === "cron" ? "cron" : "triggers",
+    `isolated job "${params.label}": ${params.backendId}/${params.model} can't host it (${first.reason}) — retrying on ${fallback.backendId}/${fallback.model}`,
+  );
+  const second = await attemptJobOneShot(
+    params,
+    fallback.backendId,
+    fallback.model,
+  );
+  if (second.status === "ran") return second;
+  return reportSkip(
+    params,
+    `${first.reason} Fallback ${fallback.backendId}/${fallback.model} also unusable: ${second.reason}`,
+  );
+}

package/src/core/tools/index.ts

@@ -22,6 +22,7 @@ import { webTools } from "./web.js";
 import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
+import { moderationTools } from "./moderation.js";
 import { nativeTools } from "./native.js";
 
 /** All built-in tool definitions. */
@@ -41,6 +42,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
   ...modelTools,
   ...meshTools,
+  ...moderationTools,
 ];
 
 /**

package/src/core/tools/messaging.ts

@@ -135,7 +135,10 @@ Examples:
   Dice: send(type="dice")
   Location: send(type="location", latitude=37.7749, longitude=-122.4194)
   Sticker by feeling: send(type="sticker", emoji="😂") — picks a matching sticker from your saved packs (add set_name to pin one pack)
-  Sticker by id: send(type="sticker", file_id="CAACAgI...")`,
+  Sticker by id: send(type="sticker", file_id="CAACAgI...")
+  Album: send(type="album", media=[{"type":"photo","file_path":"a.jpg"},{"type":"photo","url":"https://…/b.jpg","caption":"the good one"}]) — 2-10 photos/videos as one grouped message
+  Round video: send(type="video_note", file_path="/path/clip.mp4") — circular video bubble (square video, ≤60s)
+  Venue: send(type="venue", latitude=53.34, longitude=-6.26, title="The Long Hall", address="51 South Great George's St")`,
     schema: {
       type: z
         .enum([
@@ -151,6 +154,9 @@ Examples:
           "location",
           "contact",
           "dice",
+          "album",
+          "video_note",
+          "venue",
         ])
         .describe("Content type to send"),
       text: z
@@ -208,7 +214,30 @@ Examples:
       phone_number: z.string().optional().describe("Contact phone"),
       first_name: z.string().optional().describe("Contact first name"),
       last_name: z.string().optional().describe("Contact last name"),
-      title: z.string().optional().describe("Audio title (for type=audio)"),
+      title: z
+        .string()
+        .optional()
+        .describe("Audio title (type=audio) or venue name (type=venue)"),
+      address: z
+        .string()
+        .optional()
+        .describe("Venue street address (for type=venue)"),
+      media: z
+        .array(
+          z.object({
+            type: z
+              .enum(["photo", "video", "document", "audio"])
+              .describe("Kind of this album item"),
+            file_path: z.string().optional(),
+            url: z.string().optional(),
+            file_id: z.string().optional(),
+            caption: z.string().optional(),
+          }),
+        )
+        .optional()
+        .describe(
+          "Album items (for type=album): 2-10 entries, each sourced from file_path, url, or file_id. Photos and videos mix; documents/audio group only with their own kind.",
+        ),
       performer: z
         .string()
         .optional()
@@ -230,9 +259,41 @@ Examples:
         .describe(
           "Target chat ID. Omit to send to the current chat (chat mode). Required from heartbeat mode where there is no ambient chat — use list_chats or known IDs from memory. Telegram supergroup/channel IDs are negative (e.g. -1001426819337); user DMs are positive.",
         ),
+      silent: z
+        .boolean()
+        .optional()
+        .describe("Send without a notification sound (Telegram)"),
+      protect: z
+        .boolean()
+        .optional()
+        .describe("Protect content from forwarding and saving (Telegram)"),
+      spoiler: z
+        .boolean()
+        .optional()
+        .describe(
+          "Blur photo/video/animation behind a spoiler tap-to-reveal (Telegram)",
+        ),
+      no_link_preview: z
+        .boolean()
+        .optional()
+        .describe("Disable the link preview for type=text (Telegram)"),
+      thread_id: z
+        .union([z.number(), z.literal("general")])
+        .optional()
+        .describe(
+          'Forum topic to post into (Telegram supergroups with topics). Defaults to the topic the conversation is happening in; pass "general" to force the General topic.',
+        ),
     },
     execute: async (params, bridge) => {
       const { type } = params;
+      // Delivery modifiers every Telegram send action understands. Harmless
+      // on frontends that don't (handlers read only the fields they know).
+      const mods = {
+        silent: params.silent,
+        protect: params.protect,
+        spoiler: params.spoiler,
+        thread_id: params.thread_id,
+      };
       // Thread chat_id through to every bridge call so heartbeat / dream
       // outbound (no ambient chat) gets routed by the explicit chat_id.
       // `createBridge` at src/core/tools/bridge.ts:29 reads
@@ -253,6 +314,7 @@ Examples:
               delay_seconds: params.delay_seconds,
               rows: params.buttons,
               reply_to_message_id: params.reply_to,
+              ...mods,
               chat_id,
             });
           }
@@ -261,12 +323,15 @@ Examples:
               text: params.text,
               rows: params.buttons,
               reply_to_message_id: params.reply_to,
+              ...mods,
               chat_id,
             });
           }
           return bridge("send_message", {
             text: params.text,
             reply_to_message_id: params.reply_to,
+            no_link_preview: params.no_link_preview,
+            ...mods,
             chat_id,
           });
         }
@@ -277,6 +342,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "file":
@@ -286,6 +352,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "video":
@@ -295,6 +362,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "voice":
@@ -304,6 +372,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "audio":
@@ -315,6 +384,7 @@ Examples:
             title: params.title,
             performer: params.performer,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "animation":
@@ -324,6 +394,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "sticker":
@@ -333,6 +404,7 @@ Examples:
             emoji: params.emoji,
             set_name: params.set_name,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "poll":
@@ -344,6 +416,7 @@ Examples:
             explanation: params.explanation,
             type: params.correct_option_id !== undefined ? "quiz" : "regular",
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "location":
@@ -351,6 +424,7 @@ Examples:
             latitude: params.latitude,
             longitude: params.longitude,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "contact":
@@ -359,12 +433,40 @@ Examples:
             first_name: params.first_name,
             last_name: params.last_name,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "dice":
           return bridge("send_dice", {
             emoji: params.emoji,
             reply_to: params.reply_to,
+            ...mods,
+            chat_id,
+          });
+        case "album":
+          return bridge("send_media_group", {
+            media: params.media,
+            reply_to: params.reply_to,
+            ...mods,
+            chat_id,
+          });
+        case "video_note":
+          return bridge("send_video_note", {
+            file_path: params.file_path,
+            url: params.url,
+            file_id: params.file_id,
+            reply_to: params.reply_to,
+            ...mods,
+            chat_id,
+          });
+        case "venue":
+          return bridge("send_venue", {
+            latitude: params.latitude,
+            longitude: params.longitude,
+            title: params.title,
+            address: params.address,
+            reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         default:
@@ -479,8 +581,16 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
   // ── edit_message ──────────────────────────────────────────────────────
   {
     name: "edit_message",
-    description: "Edit a previously sent message.",
-    schema: { message_id: snowflakeOrIdSchema, text: z.string() },
+    description:
+      "Edit a previously sent message. For a media message (photo/video/file), pass is_caption=true to edit its caption instead of message text.",
+    schema: {
+      message_id: snowflakeOrIdSchema,
+      text: z.string(),
+      is_caption: z
+        .boolean()
+        .optional()
+        .describe("Edit the media caption rather than message text (Telegram)"),
+    },
     execute: (params, bridge) => bridge("edit_message", params),
     frontends: ["telegram", "discord", "native"],
     tag: "messaging",
@@ -489,8 +599,15 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
   // ── delete_message ────────────────────────────────────────────────────
   {
     name: "delete_message",
-    description: "Delete a message.",
-    schema: { message_id: snowflakeOrIdSchema },
+    description:
+      "Delete a message — or several at once via message_ids (Telegram; ids the bot can't delete are skipped).",
+    schema: {
+      message_id: snowflakeOrIdSchema.optional(),
+      message_ids: z
+        .array(snowflakeOrIdSchema)
+        .optional()
+        .describe("Bulk delete these message IDs (Telegram)"),
+    },
     execute: (params, bridge) => bridge("delete_message", params),
     frontends: ["telegram", "discord", "native"],
     tag: "messaging",
@@ -499,13 +616,42 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
   // ── forward_message ───────────────────────────────────────────────────
   {
     name: "forward_message",
-    description: "Forward a message within the chat.",
-    schema: { message_id: snowflakeOrIdSchema },
+    description:
+      "Forward a message. Defaults to within the current chat; from_chat_id / to_chat_id forward across chats the bot is in, and message_ids forwards a batch (albums stay grouped) (Telegram).",
+    schema: {
+      message_id: snowflakeOrIdSchema.optional(),
+      message_ids: z
+        .array(snowflakeOrIdSchema)
+        .optional()
+        .describe("Forward these messages as a batch (Telegram)"),
+      from_chat_id: chatIdSchema
+        .optional()
+        .describe("Source chat (default: current chat)"),
+      to_chat_id: chatIdSchema
+        .optional()
+        .describe("Destination chat (default: current chat)"),
+    },
     execute: (params, bridge) => bridge("forward_message", params),
     frontends: ["telegram", "discord"],
     tag: "messaging",
   },
 
+  // ── copy_message ──────────────────────────────────────────────────────
+  {
+    name: "copy_message",
+    description:
+      "Repost a message without the 'forwarded from' header. Same cross-chat and batch semantics as forward_message (Telegram).",
+    schema: {
+      message_id: snowflakeOrIdSchema.optional(),
+      message_ids: z.array(snowflakeOrIdSchema).optional(),
+      from_chat_id: chatIdSchema.optional(),
+      to_chat_id: chatIdSchema.optional(),
+    },
+    execute: (params, bridge) => bridge("copy_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
   // ── pin_message ───────────────────────────────────────────────────────
   {
     name: "pin_message",