talon-agent 5.26.0 → 5.26.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.26.0",
+  "version": "5.26.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/backend/claude-sdk/model-provider.ts

@@ -71,19 +71,68 @@ function isSelectedModel(currentModel: string, candidateId: string): boolean {
 
 // ── Public API ─────────────────────────────────────────────────────────────
 
-export async function resolveModel(
-  query: string,
-): Promise<UnifiedModelResolution> {
-  const canonicalId = resolveModelId(query);
-  const model = getModel(canonicalId);
+const ONE_MILLION_SUFFIX = "[1m]";
 
-  if (model) {
+/**
+ * Split a `[1m]` context-variant suffix off a query ("opus[1m]" →
+ * { stem: "opus", oneMillion: true }). Claude Code accepts the suffix on
+ * any alias or id; the SDK's `supportedModels()` list does not enumerate
+ * the suffixed forms, so the catalog can't match them directly.
+ */
+function splitOneMillion(query: string): { stem: string; oneMillion: boolean } {
+  const trimmed = query.trim();
+  if (trimmed.toLowerCase().endsWith(ONE_MILLION_SUFFIX)) {
     return {
-      kind: "exact",
-      model: toUnified(model),
-      storedValue: model.id,
+      stem: trimmed.slice(0, -ONE_MILLION_SUFFIX.length).trim(),
+      oneMillion: true,
     };
   }
+  return { stem: trimmed, oneMillion: false };
+}
+
+/**
+ * Exact-match a query against the registry: its id/alias directly, or —
+ * for a `[1m]` query the registry doesn't list — the base model, returned
+ * as a 1M variant whose id keeps the suffix so the SDK actually selects
+ * the 1M context window.
+ *
+ * The SDK reports no context-window metadata per model, so there's no
+ * evidence to reject a `[1m]` request on; the binary is the authority.
+ * The one form refused is `default[1m]`: "default" is a moving target,
+ * not an alias Claude Code suffixes.
+ */
+function resolveExactUnified(query: string): UnifiedModelInfo | undefined {
+  const direct = getModel(resolveModelId(query));
+  if (direct) return toUnified(direct);
+
+  const { stem, oneMillion } = splitOneMillion(query);
+  if (!oneMillion || !stem) return undefined;
+  const baseId = resolveModelId(stem);
+  const base = getModel(baseId);
+  if (!base || stem.toLowerCase() === "default") return undefined;
+
+  // Pass the SDK a form it knows: the canonical id when it's concrete, the
+  // user's own stem when the canonical is the "default" alias (e.g. "opus"
+  // folds into "default" when default currently serves Opus).
+  const sdkStem = baseId === "default" ? stem : baseId;
+  const displayName = /\(1m context\)/i.test(base.displayName)
+    ? base.displayName
+    : `${base.displayName} (1M context)`;
+  return {
+    ...toUnified(base),
+    id: `${sdkStem}${ONE_MILLION_SUFFIX}`,
+    displayName,
+    contextWindow: 1_000_000,
+  };
+}
+
+export async function resolveModel(
+  query: string,
+): Promise<UnifiedModelResolution> {
+  const exact = resolveExactUnified(query);
+  if (exact) {
+    return { kind: "exact", model: exact, storedValue: exact.id };
+  }
 
   // No exact match -- try a substring search across display names and aliases
   const allModels = getModels(PROVIDER_ID);
@@ -112,9 +161,7 @@ export async function resolveModel(
 export async function getModelInfo(
   id: string,
 ): Promise<UnifiedModelInfo | undefined> {
-  const canonicalId = resolveModelId(id);
-  const model = getModel(canonicalId);
-  return model ? toUnified(model) : undefined;
+  return resolveExactUnified(id);
 }
 
 export async function getSettingsPresentation(

package/src/core/frontend-runtime/admin-notify.ts

@@ -7,7 +7,10 @@
  * wiring, which does the same thing privately). Alerts raised before that
  * — early boot is exactly when restore reports and security alerts fire —
  * are held in a small bounded queue and flushed, oldest first, the moment
- * a notifier is wired. With nothing ever wired (tests, terminal mode with
+ * a notifier is wired. An alert carrying a key (operator alerts do) is
+ * deduplicated while it waits: a re-raise replaces the queued copy instead
+ * of queueing another, and a key that resolves before anyone could hear it
+ * is withdrawn outright. With nothing ever wired (tests, terminal mode with
  * no admin) they stay a log line; nothing throws.
  *
  * First consumer: WhatsApp pairing. When WhatsApp unlinks the device,
@@ -25,7 +28,14 @@ let deliver: Deliver | null = null;
 /** Most alerts held while no notifier is wired; the oldest are dropped past it. */
 export const ADMIN_NOTIFY_QUEUE_MAX = 20;
 
-type Pending = { text: string; at: number };
+type Pending = {
+  text: string;
+  at: number;
+  /** Dedup key (operator alert key); unkeyed alerts never coalesce. */
+  key?: string;
+  /** Re-raises folded into this entry while it waited. */
+  repeats: number;
+};
 const pending: Pending[] = [];
 let droppedWhileUnwired = 0;
 let flushing: Promise<void> | null = null;
@@ -68,6 +78,7 @@ async function flushPending(fn: Deliver): Promise<void> {
     batch.unshift({
       text: `${dropped} earlier admin alert(s) were dropped before a notifier was wired (queue holds ${ADMIN_NOTIFY_QUEUE_MAX}); see the daemon log.`,
       at: Date.now(),
+      repeats: 0,
     });
   }
   log("notify", `Flushing ${batch.length} queued admin alert(s)`);
@@ -79,7 +90,10 @@ async function flushPending(fn: Deliver): Promise<void> {
       continue;
     }
     const ageS = Math.round((Date.now() - item.at) / 1000);
-    const text = ageS >= 5 ? `(delayed ${ageS}s) ${item.text}` : item.text;
+    const repeated =
+      item.repeats > 0 ? `\n(raised ${item.repeats + 1}× while starting)` : "";
+    const text =
+      (ageS >= 5 ? `(delayed ${ageS}s) ${item.text}` : item.text) + repeated;
     try {
       await fn(text);
       log("notify", `Admin notified (queued): ${preview(item.text)}`);
@@ -95,6 +109,17 @@ async function flushPending(fn: Deliver): Promise<void> {
 }
 
 function enqueue(item: Pending): void {
+  if (item.key !== undefined) {
+    const i = pending.findIndex((p) => p.key === item.key);
+    if (i >= 0) {
+      // Same fault raised again while waiting: keep one entry, newest text,
+      // original timestamp (so the "delayed" note stays honest).
+      const prior = pending[i];
+      prior.text = item.text;
+      prior.repeats += item.repeats + 1;
+      return;
+    }
+  }
   pending.push(item);
   while (pending.length > ADMIN_NOTIFY_QUEUE_MAX) {
     const lost = pending.shift();
@@ -111,14 +136,29 @@ function preview(text: string): string {
   return text.slice(0, 80).replace(/\n/g, " ");
 }
 
+/**
+ * Withdraw a queued, not-yet-delivered alert by key (its fault cleared
+ * before a notifier was wired). Returns whether one was withdrawn.
+ */
+export function withdrawAdminNotification(key: string): boolean {
+  const i = pending.findIndex((p) => p.key === key);
+  if (i < 0) return false;
+  const [gone] = pending.splice(i, 1);
+  log("notify", `Withdrew queued admin alert ${key}: ${preview(gone.text)}`);
+  return true;
+}
+
 /**
  * Send `text` to the admin chat. Never throws; returns whether it was
  * delivered now (false = failed, or queued because no notifier is wired
- * yet — it is sent when one is).
+ * yet — it is sent when one is). `key` deduplicates while queued.
  */
-export async function notifyAdmin(text: string): Promise<boolean> {
+export async function notifyAdmin(
+  text: string,
+  key?: string,
+): Promise<boolean> {
   if (!deliver) {
-    enqueue({ text, at: Date.now() });
+    enqueue({ text, at: Date.now(), key, repeats: 0 });
     logWarn(
       "notify",
       `No admin notifier wired yet; queued (${pending.length}/${ADMIN_NOTIFY_QUEUE_MAX}): ${text.slice(0, 120)}`,

package/src/core/frontend-runtime/alerts.ts

@@ -15,7 +15,7 @@
  */
 
 import { log, logWarn } from "../../util/log.js";
-import { notifyAdmin } from "./admin-notify.js";
+import { notifyAdmin, withdrawAdminNotification } from "./admin-notify.js";
 
 export type AlertSeverity = "warn" | "error" | "critical";
 
@@ -39,7 +39,8 @@ const RANK: Record<AlertSeverity, number> = { warn: 0, error: 1, critical: 2 };
 const active = new Map<string, ActiveAlert>();
 let cooldownMs = DEFAULT_COOLDOWN_MS;
 let enabled = true;
-let send: (text: string) => Promise<unknown> = notifyAdmin;
+type Send = (text: string, key?: string) => Promise<unknown>;
+let send: Send = notifyAdmin;
 
 /** Apply operator settings (config `alerts`). */
 export function configureAlerts(opts: {
@@ -86,7 +87,9 @@ export function raiseAlert(
     // Nobody heard it: don't let the cooldown swallow the next raise.
     if (active.get(key) === entry) entry.lastSentAt = 0;
   };
-  void send(`${ICON[severity]} ${message}${repeat}`).then((ok) => {
+  // The key lets a still-queued copy (no notifier wired yet) be replaced by
+  // this raise rather than queued twice.
+  void send(`${ICON[severity]} ${message}${repeat}`, key).then((ok) => {
     if (ok === false) undelivered();
   }, undelivered);
 }
@@ -99,6 +102,9 @@ export function resolveAlert(key: string, message?: string): void {
   const mins = Math.max(1, Math.round((Date.now() - prior.firstAt) / 60_000));
   log("alert", `resolved ${key} after ${mins} min`);
   if (!enabled) return;
+  // Still queued for a notifier that never got to send it: withdraw it, and
+  // there is nothing to announce a recovery from.
+  if (withdrawAdminNotification(key)) return;
   void send(`✅ ${message ?? `Recovered: ${key}`} (after ${mins} min)`).catch(
     () => {},
   );
@@ -120,9 +126,7 @@ export function activeAlerts(): ReadonlyArray<{
 }
 
 /** Test seam: reset state and swap the delivery function. */
-export function resetAlertsForTest(
-  deliver: (text: string) => Promise<unknown> = notifyAdmin,
-): void {
+export function resetAlertsForTest(deliver: Send = notifyAdmin): void {
   active.clear();
   cooldownMs = DEFAULT_COOLDOWN_MS;
   enabled = true;

package/src/core/models/active-model.ts

@@ -36,19 +36,20 @@
  *   1. `modelByBackend[B]` — per-chat-per-backend pick, if it still
  *      validates against B's catalog. Cross-backend orphans surface
  *      as `kind: "missing"` and fall through.
- *   2. `backend.models?.getDefaultModelId()` — backend's canonical default.
+ *   2. `config.backendDefaults[B]` — operator-configured per-backend
+ *      default in `talon.json`.
+ *   3. `config.model` — only when B is the global chat-role backend
+ *      (`config.backend === B`).
+ *      Operator picks (2/3) must validate against B's catalog when B
+ *      has a canonical default to fall back to; an unknown pin falls
+ *      through to step 4 (what the boot-time model audit warns about).
+ *   4. `backend.models?.getDefaultModelId()` — backend's canonical default.
  *      Codex picks auth-aware (`gpt-5-codex` on API key, `gpt-5.5`
  *      on ChatGPT OAuth). Claude SDK returns the `"default"` alias.
  *      Stock OpenAI Agents returns a constant.
  *      Catalog-driven backends without a canonical (Kilo, OpenCode,
  *      OpenAI Agents on OpenRouter / custom OpenAI-compatible) do
- *      NOT implement this — they fall through to step 3.
- *   3. `config.backendDefaults[B]` — operator-configured per-backend
- *      default in `talon.json`. Escape hatch for "no canonical"
- *      backends.
- *   4. `config.model` — only when B is the global chat-role backend
- *      (`config.backend === B`). Back-compat for installs that
- *      predate `backendDefaults`.
+ *      NOT implement this.
  *   5. `null` → UI renders "No model selected", send guard refuses
  *      with a "use /model to pick one" reply.
  *
@@ -56,6 +57,10 @@
  * is called. Only `kind: "exact"` with `selectable: true` honours the
  * stored override. Anything else falls through to step 2.
  *
+ * Operator config ranks above the canonical so a pinned `config.model`
+ * is actually honoured (it used to lose to Claude's `"default"`, so a
+ * claude install pinned to any model silently ran the default).
+ *
  * Backends with no `resolveModel` (rare — defensive fallback only)
  * have their stored override returned verbatim — no way to validate.
  */
@@ -157,8 +162,8 @@ async function runChain(
     }
   }
 
-  // ── Step 2-5: backend canonical → config.backendDefaults →
-  //              config.model (chat-role only) → null
+  // ── Steps 2-5: backendDefaults → config.model (chat-role only) →
+  //              backend canonical → null
   return stepsTwoThroughFive(backend, backendId, config, null);
 }
 
@@ -196,57 +201,61 @@ async function stepsTwoThroughFive(
   config: TalonConfig,
   fallbackSourceOverride: "override-invalid-fallback" | null,
 ): Promise<{ model: string | null; source: ActiveModelSource }> {
-  // Step 2: backend.models.getDefaultModelId()
-  if (backend?.models) {
-    const canonical = await safeBackendDefault(backend);
-    if (canonical) {
-      return {
-        model: canonical,
-        source: fallbackSourceOverride ?? "backend-canonical",
-      };
+  const withSource = (model: string, source: ActiveModelSource) => ({
+    model,
+    source: fallbackSourceOverride ?? source,
+  });
+
+  const operatorPick = pickOperatorDefault(backendId, config);
+  const canonical = backend?.models ? await safeBackendDefault(backend) : null;
+
+  // Operator config (steps 2/3) beats the backend canonical (step 4): a
+  // pinned `config.model` is an explicit choice, and letting the canonical
+  // win meant a claude install pinned to e.g. "opus[1m]" silently ran
+  // "default" on every turn. The pin must still validate — a withdrawn id
+  // falls back to the canonical, exactly what the boot-time model audit
+  // warns about. Without a canonical to fall back to, the pin is returned
+  // unvalidated (catalog-driven backends with no default, unchanged).
+  if (operatorPick) {
+    if (!canonical) return withSource(operatorPick.model, operatorPick.source);
+    if (await validateModelOnBackend(backend, operatorPick.model)) {
+      return withSource(operatorPick.model, operatorPick.source);
     }
   }
 
-  // Step 3: config.backendDefaults[backendId]
+  // Step 4: backend.models.getDefaultModelId()
+  if (canonical) return withSource(canonical, "backend-canonical");
+
+  // Step 5: null. Callers must render "No model selected" / refuse send.
+  return { model: null, source: "none" };
+}
+
+/**
+ * The operator-configured default for a backend, if any:
+ *   - `config.backendDefaults[B]`;
+ *   - else `config.model` — only when B is the global chat-role backend
+ *     (`config.backend === B`), or when no backend id is known at all
+ *     (pre-bootstrap callers passing null).
+ */
+function pickOperatorDefault(
+  backendId: string | null,
+  config: TalonConfig,
+): { model: string; source: ActiveModelSource } | null {
   if (backendId && config.backendDefaults) {
     const operatorDefault = config.backendDefaults[backendId];
     if (operatorDefault && operatorDefault.length > 0) {
-      return {
-        model: operatorDefault,
-        source: fallbackSourceOverride ?? "config-backend-defaults",
-      };
+      return { model: operatorDefault, source: "config-backend-defaults" };
     }
   }
-
-  // Step 4: legacy config.model — only for the global chat-role backend
+  const modelAppliesHere = !backendId || backendId === config.backend;
   if (
-    backendId &&
-    backendId === config.backend &&
+    modelAppliesHere &&
     typeof config.model === "string" &&
     config.model.length > 0
   ) {
-    return {
-      model: config.model,
-      source: fallbackSourceOverride ?? "config-legacy-global",
-    };
+    return { model: config.model, source: "config-legacy-global" };
   }
-
-  // Step 4b: even without a backendId, honour config.model if no
-  // backend is bound at all (callers passing null for both — rare,
-  // typically pre-bootstrap code paths).
-  if (
-    !backendId &&
-    typeof config.model === "string" &&
-    config.model.length > 0
-  ) {
-    return {
-      model: config.model,
-      source: fallbackSourceOverride ?? "config-legacy-global",
-    };
-  }
-
-  // Step 5: null. Callers must render "No model selected" / refuse send.
-  return { model: null, source: "none" };
+  return null;
 }
 
 async function validateModelOnBackend(

package/src/core/plugin/loader.ts

@@ -98,6 +98,15 @@ function registerPluginInstance(
   return loaded;
 }
 
+/**
+ * Run a plugin's init, waiting at most `timeoutMs` for it before boot moves
+ * on. The deadline bounds how long boot waits, not the init itself: a
+ * plugin stays registered either way (its tools are served from
+ * `mcpServer` whether or not init finished), so an init that outlives the
+ * deadline keeps running and, when it does finish, clears the alert the
+ * timeout raised — a slow handshake on a busy boot is a delay, not a
+ * failure that lingers until the next restart.
+ */
 export async function initPluginWithTimeout(
   plugin: TalonPlugin,
   config: Record<string, unknown>,
@@ -108,28 +117,54 @@ export async function initPluginWithTimeout(
   if (!plugin.init) return;
 
   let timer: ReturnType<typeof setTimeout> | undefined;
-
   const alertKey = `plugin.${plugin.name}`;
+  const startedAt = Date.now();
+  // Started (and timed) only here, when this plugin's own init begins.
+  const init = Promise.resolve().then(() => plugin.init!(config));
+  const TIMED_OUT = Symbol("timed out");
+
   try {
-    await Promise.race([
-      Promise.resolve(plugin.init(config)),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          reject(
-            new Error(`${timeoutLabel} timed out after ${timeoutMs / 1000}s`),
-          );
-        }, timeoutMs);
+    const outcome = await Promise.race([
+      init,
+      new Promise<typeof TIMED_OUT>((settle) => {
+        timer = setTimeout(() => settle(TIMED_OUT), timeoutMs);
         timer.unref?.();
       }),
     ]);
-    resolveAlert(alertKey, `Plugin "${plugin.name}" initialised normally.`);
+    if (outcome !== TIMED_OUT) {
+      resolveAlert(alertKey, `Plugin "${plugin.name}" initialised normally.`);
+      return;
+    }
+    const message = `${timeoutLabel} timed out after ${timeoutMs / 1000}s`;
+    logError("plugin", `${errorPrefix}: ${message}; still waiting for it`);
+    raiseAlert(
+      alertKey,
+      `Plugin "${plugin.name}" failed to initialise: ${message}. Its tools stay registered; this clears itself if init finishes late.`,
+    );
+    void init.then(
+      () => {
+        // Reloaded or unloaded meanwhile: this instance's verdict is moot.
+        if (registry.getByName(plugin.name)?.plugin !== plugin) return;
+        const took = Math.round((Date.now() - startedAt) / 1000);
+        log("plugin", `${plugin.name} init finished late (${took}s)`);
+        resolveAlert(
+          alertKey,
+          `Plugin "${plugin.name}" finished initialising late (${took}s).`,
+        );
+      },
+      (err: unknown) =>
+        logError(
+          "plugin",
+          `${errorPrefix} (after timing out): ${err instanceof Error ? err.message : err}`,
+        ),
+    );
   } catch (err) {
     logError(
       "plugin",
       `${errorPrefix}: ${err instanceof Error ? err.message : err}`,
     );
-    // Init runs once per boot or reload: a plugin that failed it stays
-    // half-loaded until someone fixes it, so this needs no threshold.
+    // An init that threw won't retry on its own: it needs a reload or
+    // restart, so this needs no threshold.
     raiseAlert(
       alertKey,
       `Plugin "${plugin.name}" failed to initialise: ${faultText(err)}. Its tools may not work until the next reload or restart.`,

package/src/frontend/telegram/actions/media.ts

@@ -54,8 +54,8 @@ export function resolveMediaInput(
 
 /** Telegram's hard limit on media captions, counted after entity parsing. */
 export const TELEGRAM_MAX_CAPTION = 1024;
-/** Visible length a truncated caption is cut to, leaving room for the "…". */
-const TRUNCATED_CAPTION_LEN = 1000;
+/** Below this head budget the splitter is fighting pathological markup; give up. */
+const MIN_CAPTION_HEAD = 64;
 
 /**
  * Drop every `<...>` tag in one linear pass. Only used to *measure* the
@@ -104,35 +104,76 @@ export function visibleCaptionText(html: string): string {
 export type FittedCaption = {
   caption?: string;
   parse_mode?: "HTML";
-  /** Full caption text to deliver as a follow-up message when it was cut. */
+  /** Caption text that did not fit, to deliver as follow-up message(s). */
   overflow?: string;
 };
 
+/** Visible (Telegram-counted) length of a markdown caption once rendered. */
+export function captionUnits(markdown: string): number {
+  // Telegram counts UTF-16 code units, which is what .length measures.
+  return visibleCaptionText(markdownToTelegramHtml(markdown)).length;
+}
+
+/**
+ * Split a markdown caption into the leading part that fits `max` visible
+ * units and the remainder. Splits the *markdown source* with the shared
+ * message splitter (paragraph → newline → space boundaries, surrogate-safe,
+ * ``` fences closed/reopened), so the head is rendered to HTML on its own
+ * and can never strand a tag or entity. Returns null if no clean head fits.
+ */
+export function splitCaption(
+  text: string,
+  max: number = TELEGRAM_MAX_CAPTION,
+): { head: string; rest: string } | null {
+  // Rendering usually shrinks markdown (markers and link URLs vanish), so
+  // the first try nearly always fits; shrink the budget if it does not.
+  for (let budget = max; budget >= MIN_CAPTION_HEAD;) {
+    const chunks = splitMessage(text, budget);
+    const head = chunks[0] ?? "";
+    if (head.trim() && captionUnits(head) <= max) {
+      const at = text.indexOf(head);
+      // The splitter only trims at boundaries, so the head is normally a
+      // verbatim prefix; when it closed a ``` fence it is not, and the
+      // splitter's own reopened chunks carry the remainder instead.
+      const rest =
+        at >= 0
+          ? text.slice(at + head.length).replace(/^\s+/, "")
+          : chunks.slice(1).join("\n\n");
+      return { head, rest };
+    }
+    budget = Math.floor(budget * 0.8);
+  }
+  return null;
+}
+
 /**
  * Convert a markdown caption to what Telegram accepts. Captions over 1024
  * visible characters are rejected outright ("message caption is too long"),
- * losing the media along with them — so an oversized caption is cut to a
- * plain-text preview (no parse_mode: a cut through HTML could strand a tag
- * or entity) and the full text is returned as `overflow` for the caller to
- * send as a normal, chunked text message.
+ * losing the media along with them — so an oversized caption is split: the
+ * leading part that fits rides on the media (still formatted), and the rest
+ * is returned as `overflow` for the caller to send as follow-up text.
  */
 export function fitCaption(raw: unknown): FittedCaption {
   if (!raw) return {};
   const text = String(raw);
   const html = markdownToTelegramHtml(text);
-  const visible = visibleCaptionText(html);
-  // Telegram counts UTF-16 code units, which is what .length measures.
-  if (visible.length <= TELEGRAM_MAX_CAPTION)
+  if (visibleCaptionText(html).length <= TELEGRAM_MAX_CAPTION)
     return { caption: html, parse_mode: "HTML" };
-  let cut = visible.slice(0, TRUNCATED_CAPTION_LEN);
-  // Don't strand half a surrogate pair at the cut.
-  const last = cut.charCodeAt(cut.length - 1);
-  if (last >= 0xd800 && last <= 0xdbff) cut = cut.slice(0, -1);
-  return { caption: `${cut.trimEnd()}…`, overflow: text };
+  const split = splitCaption(text);
+  if (split) {
+    return {
+      caption: markdownToTelegramHtml(split.head),
+      parse_mode: "HTML",
+      ...(split.rest ? { overflow: split.rest } : {}),
+    };
+  }
+  // No clean boundary fits (pathological markup): send the media bare and
+  // deliver the whole caption as text rather than cut through it.
+  return { overflow: text };
 }
 
 /**
- * Deliver the full text of a caption that did not fit, threaded as a reply
+ * Deliver the part of a caption that did not fit, threaded as a reply
  * to the media it belongs to. Best-effort: the media already landed, so a
  * failure here is reported as a warning rather than failing the send.
  */
@@ -167,7 +208,7 @@ async function sendCaptionOverflow(
       `Caption overflow follow-up failed (chat=${chatId}): ${msg}`,
     );
     return {
-      warning: `Media sent with a truncated caption, but sending the full caption text failed: ${msg}`,
+      warning: `Media sent, but the rest of its caption (past Telegram's ${TELEGRAM_MAX_CAPTION}-char limit) failed to send: ${msg}`,
     };
   }
 }
@@ -176,8 +217,8 @@ function overflowResult(
   r: { message_ids: number[] } | { warning: string },
 ): Record<string, unknown> {
   return "warning" in r
-    ? { caption_truncated: true, warning: r.warning }
-    : { caption_truncated: true, caption_message_ids: r.message_ids };
+    ? { caption_split: true, warning: r.warning }
+    : { caption_split: true, caption_message_ids: r.message_ids };
 }
 
 const sendMediaFile: TelegramActionHandlers[string] = async (

package/src/frontend/telegram/actions/messaging.ts

@@ -21,6 +21,7 @@ import {
   richMessagesAvailable,
 } from "./rich-messages.js";
 import { toPositiveId } from "./coerce.js";
+import { captionUnits, TELEGRAM_MAX_CAPTION } from "./media.js";
 import { resolveThreadId } from "../topics.js";
 import { TELEGRAM_MAX_TEXT, type TelegramActionHandlers } from "./types.js";
 
@@ -260,6 +261,14 @@ export const messagingHandlers: TelegramActionHandlers = {
     // Media messages have captions, not text — editMessageText on them fails
     // with "there is no text in the message to edit".
     if (body.is_caption === true) {
+      // An edit cannot spill into a follow-up message the way a send does,
+      // so refuse up front with guidance rather than a raw Bot API 400.
+      const units = captionUnits(text);
+      if (units > TELEGRAM_MAX_CAPTION)
+        return {
+          ok: false,
+          error: `Caption too long (${units} chars, max ${TELEGRAM_MAX_CAPTION}) — shorten it, or send the rest as a separate message`,
+        };
       await withRetry(async () => {
         try {
           await bot.api.editMessageCaption(chatId, Number(body.message_id), {