talon-agent 5.4.0 → 5.5.0

package/src/core/engine/gateway-actions/models.ts

@@ -10,11 +10,33 @@ import {
   getBackendForChat,
   getBackendIdForChat,
   getAvailableBackends,
+  getPoolConfig,
   getPooledBackend,
   acquireBackendInstance,
 } from "../backend-controller/index.js";
+import {
+  collectBackendUsage,
+  formatHeadroom,
+  leadWith,
+  type BackendUsageSnapshot,
+} from "../backend-router/index.js";
 import type { SharedActionHandlers } from "./types.js";
 
+/** One `plan_usage` block: the headroom line, then any plan windows. */
+function usageLines(entry: BackendUsageSnapshot): string[] {
+  const head = `- ${entry.label || entry.id}: ${formatHeadroom(entry.headroom)}`;
+  if (!entry.plan) {
+    return [`${head}${entry.note ? ` (${entry.note})` : ""}`];
+  }
+  return [
+    `${head}${entry.plan.plan ? ` · ${entry.plan.plan}` : ""}`,
+    ...entry.plan.windows.map(
+      (w) =>
+        `    ${w.label}: ${w.percent}% used${w.resetsAt ? `, resets ${w.resetsAt}` : ""}`,
+    ),
+  ];
+}
+
 export const modelHandlers: SharedActionHandlers = {
   list_models: async (body, chatId, _backend, chatKey) => {
     const chatIdStr = chatKey;
@@ -98,52 +120,67 @@ export const modelHandlers: SharedActionHandlers = {
     }
   },
 
-  // Account-level, so it falls back to the pooled Claude backend when
-  // another provider is serving this chat.
+  // Account-level and fleet-wide: every exposed backend, with the headroom
+  // figure the plan-aware router ranks on — a backend with no usage API
+  // still answers, from its local budget ledger. The chat's own backend
+  // leads so a caller reading only the first entry sees what it used to.
   plan_usage: async (_body, chatId, _backend, chatKey) => {
-    const current = getPooledBackend(getBackendIdForChat(chatKey));
-    const source = current?.usage?.getPlanUsage
-      ? current
-      : getPooledBackend("claude");
-    if (!source?.usage?.getPlanUsage)
-      return {
-        ok: false,
-        error: "No configured backend reports subscription rate limits.",
-      };
-
-    const usage = await source.usage.getPlanUsage();
-    if (!usage)
-      return {
-        ok: false,
-        error:
-          "Plan usage is unavailable — no subscription credentials, or this session authenticates with an API key.",
-      };
-
-    const lines = usage.windows.map(
-      (w) =>
-        `- ${w.label}: ${w.percent}% used${w.resetsAt ? `, resets ${w.resetsAt}` : ""}`,
+    const currentId = getBackendIdForChat(chatKey);
+    const entries = leadWith(
+      await collectBackendUsage(getPoolConfig() ?? undefined, { force: true }),
+      currentId,
     );
+    if (entries.length === 0)
+      return { ok: false, error: "No backends are available." };
+
+    const lead = entries[0] as BackendUsageSnapshot;
     return {
       ok: true,
-      plan: usage.plan ?? null,
-      windows: usage.windows,
-      text: `Plan usage${usage.plan ? ` (${usage.plan})` : ""}:\n${lines.join("\n")}`,
+      // Kept for callers written against the single-backend shape.
+      plan: lead.plan?.plan ?? null,
+      windows: lead.plan?.windows ?? [],
+      backends: entries.map((entry) => ({
+        id: entry.id,
+        label: entry.label,
+        current: entry.id === currentId,
+        headroom: Math.round(entry.headroom.headroom * 100) / 100,
+        source: entry.headroom.source,
+        limiting: entry.headroom.limiting ?? null,
+        stale: entry.headroom.stale ?? false,
+        plan: entry.plan?.plan ?? null,
+        windows: entry.plan?.windows ?? [],
+        ...(entry.note ? { note: entry.note } : {}),
+      })),
+      text: `Plan usage and headroom by backend:\n${entries.flatMap(usageLines).join("\n")}`,
     };
   },
 
-  list_backends: (body, chatId, _backend, chatKey) => {
+  list_backends: async (body, chatId, _backend, chatKey) => {
     const currentId = getBackendIdForChat(chatKey);
-    const backends = getAvailableBackends().map((b) => ({
-      id: b.id,
-      label: b.label,
-      current: b.id === currentId,
-    }));
-    if (backends.length === 0)
+    const available = getAvailableBackends();
+    if (available.length === 0)
       return { ok: true, backends: [], text: "No backends are available." };
-    const lines = backends.map(
-      (b) =>
-        `- ${b.id}${b.label && b.label !== b.id ? ` (${b.label})` : ""}${b.current ? " — current" : ""}`,
-    );
+    // Headroom comes off the router's 60s cache, so listing backends is
+    // cheap even though it now answers "which one has room?" as well.
+    const usage = await collectBackendUsage(getPoolConfig() ?? undefined);
+    const byId = new Map(usage.map((entry) => [entry.id, entry]));
+    const backends = available.map((b) => {
+      const entry = byId.get(b.id);
+      return {
+        id: b.id,
+        label: b.label,
+        current: b.id === currentId,
+        headroom: entry
+          ? Math.round(entry.headroom.headroom * 100) / 100
+          : null,
+        headroomSource: entry?.headroom.source ?? null,
+      };
+    });
+    const lines = backends.map((b) => {
+      const entry = byId.get(b.id);
+      const room = entry ? ` — ${formatHeadroom(entry.headroom)} free` : "";
+      return `- ${b.id}${b.label && b.label !== b.id ? ` (${b.label})` : ""}${b.current ? " — current" : ""}${room}`;
+    });
     return {
       ok: true,
       backends,

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

@@ -31,7 +31,7 @@ export const modelTools: ToolDefinition[] = [
   {
     name: "plan_usage",
     description:
-      "Read your own subscription usage: how much of the 5-hour, weekly, and per-model rate-limit windows is spent, and when each resets. Use it before starting long or expensive work, or when deciding whether to defer something. Only answers on a subscription-backed Anthropic backend; other providers report no plan limits.",
+      "Read usage and headroom for EVERY configured backend, not just this chat's: how much of each subscription's rate-limit windows is spent, when they reset, and one comparable headroom figure per backend. A backend with no usage API reports headroom from Talon's own local token ledger against its configured budget (marked 'local budget'), and one with neither says so. Use it before starting long or expensive work, when deciding whether to defer something, or to see which backend background work will be routed to.",
     schema: {},
     execute: (_params, bridge) => bridge("plan_usage", {}),
     tag: "models",
@@ -40,7 +40,7 @@ export const modelTools: ToolDefinition[] = [
   {
     name: "list_backends",
     description:
-      "List the available backends (providers) and which one this chat is currently using. Useful for understanding the model/provider landscape. Note: a per-job `model` override must stay on this chat's current backend, so use list_models (no argument) to pick a model for a trigger or cron job.",
+      "List the available backends (providers), which one this chat is currently using, and how much plan headroom each has left. Useful for understanding the model/provider landscape and for seeing where unpinned background work (sub-agents, cron query jobs, the heartbeat) will be routed. Note: a per-job `model` override must stay on this chat's current backend, so use list_models (no argument) to pick a model for a trigger or cron job.",
     schema: {},
     execute: (_params, bridge) => bridge("list_backends", {}),
     tag: "models",

package/src/frontend/presentation/plan-usage-report.ts

@@ -6,15 +6,21 @@
  * through whichever provider it fronts, and an API-key install pays per
  * token with no window to be near the end of. Those are listed with a
  * reason rather than omitted, so the answer to "am I close to a limit?" is
- * never silence.
+ * never silence — and since the plan-aware router landed they carry a
+ * headroom figure too, derived from a local token budget where one is
+ * configured, so "which backend has room?" is answerable for all of them.
+ *
+ * The gathering itself lives in core (`engine/backend-router/usage.ts`),
+ * because the gateway tools need the same data and core cannot import a
+ * frontend. This module is the rendering adapter over it.
  */
 
 import type { TalonConfig } from "../../core/config/index.js";
-import type { PlanUsage } from "../../core/agent-runtime/capabilities.js";
 import {
-  listAvailableBackends,
-  getPooledBackend,
-} from "../../core/engine/backend-controller/index.js";
+  collectBackendUsage,
+  formatHeadroom,
+  type BackendHeadroom,
+} from "../../core/engine/backend-router/index.js";
 import { buildPlanDisplay, type PlanDisplay } from "./status-context.js";
 
 export interface BackendUsageEntry {
@@ -24,6 +30,10 @@ export interface BackendUsageEntry {
   plan: PlanDisplay | null;
   /** Why there is nothing to show. Absent when `plan` is set. */
   note?: string;
+  /** Comparable "how much is left", present for every backend. */
+  headroom: BackendHeadroom;
+  /** One-line rendering of `headroom`, ready to print. */
+  headroomLabel: string;
 }
 
 /**
@@ -36,37 +46,18 @@ export interface BackendUsageEntry {
 export async function collectPlanUsage(
   config: TalonConfig,
 ): Promise<BackendUsageEntry[]> {
-  const entries: BackendUsageEntry[] = [];
-
-  for (const { id, label } of listAvailableBackends(config)) {
-    const backend = getPooledBackend(id);
-    if (!backend) {
-      entries.push({ id, label, plan: null, note: "not running" });
-      continue;
-    }
-    if (!backend.usage?.getPlanUsage) {
-      entries.push({
-        id,
-        label,
-        plan: null,
-        note: "no plan limits on this backend",
-      });
-      continue;
-    }
-
-    let usage: PlanUsage | undefined;
-    try {
-      usage = await backend.usage.getPlanUsage();
-    } catch {
-      usage = undefined;
-    }
-    const plan = buildPlanDisplay(usage);
-    entries.push(
-      plan
-        ? { id, label, plan }
-        : { id, label, plan: null, note: "no usage information available" },
-    );
-  }
-
-  return entries;
+  const snapshots = await collectBackendUsage(config, { force: true });
+  return snapshots.map((snapshot) => {
+    const plan = buildPlanDisplay(snapshot.plan);
+    return {
+      id: snapshot.id,
+      label: snapshot.label,
+      plan,
+      headroom: snapshot.headroom,
+      headroomLabel: formatHeadroom(snapshot.headroom),
+      ...(plan
+        ? {}
+        : { note: snapshot.note ?? "no usage information available" }),
+    };
+  });
 }

package/src/frontend/presentation/reports.ts

@@ -443,10 +443,14 @@ export function renderUsageMessage(
 
   for (const entry of entries) {
     const name = fmt.escape(entry.label || entry.id);
+    // Headroom is the one figure every backend can answer, so it goes on
+    // every block — including the ones with no plan windows to draw.
+    const headroom = `  ${fmt.bold("Headroom:")} ${fmt.escape(entry.headroomLabel)}`;
     if (!entry.plan) {
       lines.push(
         "",
         `${fmt.bold(name)} — ${fmt.italic(fmt.escape(entry.note ?? ""))}`,
+        headroom,
       );
       continue;
     }
@@ -454,7 +458,7 @@ export function renderUsageMessage(
       ? ` ${fmt.emphasis(`(${entry.plan.ageLabel})`)}`
       : "";
     const plan = entry.plan.plan ? ` · ${fmt.escape(entry.plan.plan)}` : "";
-    lines.push("", `${fmt.bold(name)}${plan}${age}`);
+    lines.push("", `${fmt.bold(name)}${plan}${age}`, headroom);
     if (entry.plan.resetsAvailable) {
       const n = entry.plan.resetsAvailable;
       const resets = `usage limit reset${n === 1 ? "" : "s"} available`;

package/src/frontend/telegram/formatting.ts

@@ -89,6 +89,36 @@ function applyInlineFormatting(input: string, urls: string[]): string {
   return out;
 }
 
+/**
+ * Block-level passes over already-escaped text: ATX headings → bold lines,
+ * runs of `> ` lines → one `<blockquote>`. Placeholders for code are opaque
+ * `\x00…\x00` tokens, so a `#` inside a fenced block is never seen here.
+ */
+function applyBlockFormatting(input: string): string {
+  const lines = input.split("\n");
+  const out: string[] = [];
+  let quote: string[] | null = null;
+  const flushQuote = () => {
+    if (quote) out.push(`<blockquote>${quote.join("\n")}</blockquote>`);
+    quote = null;
+  };
+  for (const line of lines) {
+    const quoted = /^&gt;[ \t]?(.*)$/.exec(line);
+    if (quoted) {
+      (quote ??= []).push(quoted[1] ?? "");
+      continue;
+    }
+    flushQuote();
+    // `#` must be followed by whitespace to be a heading: `#993` is a
+    // reference, not a title. Trailing closing hashes (`## Title ##`) are
+    // markdown too and are dropped.
+    const heading = /^#{1,6}[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/.exec(line);
+    out.push(heading ? `<b>${heading[1]}</b>` : line);
+  }
+  flushQuote();
+  return out.join("\n");
+}
+
 /**
  * Convert Markdown output to Telegram-safe HTML.
  *
@@ -145,6 +175,15 @@ export function markdownToTelegramHtml(text: string): string {
   // oxlint-disable-next-line no-control-regex
   processed = processed.replace(/[^`\x00]+/g, (segment) => escapeHtml(segment));
 
+  // Step 3b: Block-level markdown. Telegram HTML has no headings, so an
+  // ATX heading becomes a bold line — the alternative is the `###` going
+  // out raw, and `# Title` alone turns `#Title` into a hashtag entity.
+  // Only `#` followed by whitespace is a heading: `#993` is a PR/hashtag
+  // reference and stays literal. Runs of `> ` lines become a blockquote,
+  // which Telegram does render. The text is already escaped here, so the
+  // quote marker is `&gt;`.
+  processed = applyBlockFormatting(processed);
+
   // Step 4: Apply inline formatting, but only keep it if the result is
   // actually parseable. `processed` at this point holds escaped text plus
   // tag-free placeholders, so it is a safe unformatted fallback.

package/src/frontend/terminal/builtins/status.ts

@@ -14,7 +14,14 @@ import {
 import { getChatSettings } from "../../../storage/chat-settings.js";
 import { getSessionInfo } from "../../../storage/sessions.js";
 import { getLoadedPlugins } from "../../../core/plugin/index.js";
-import { getPooledBackend } from "../../../core/engine/backend-controller/index.js";
+import {
+  getPoolConfig,
+  getPooledBackend,
+} from "../../../core/engine/backend-controller/index.js";
+import {
+  collectBackendUsage,
+  formatHeadroom,
+} from "../../../core/engine/backend-router/index.js";
 import type { Command, CommandContext } from "../command-registry.js";
 
 type BackendRef = CommandContext["backend"];
@@ -146,6 +153,27 @@ async function writePlan(ctx: CommandContext, be: BackendRef): Promise<void> {
       );
     }
   }
+  await writeHeadroom(ctx);
+}
+
+/**
+ * What the plan-aware router sees: one comparable figure per backend, so
+ * "why did that sub-agent run on agy?" is answerable from `/status`.
+ * Ledger-derived rows say so — they are Talon's own count, not the
+ * provider's.
+ */
+async function writeHeadroom(ctx: CommandContext): Promise<void> {
+  const entries = await collectBackendUsage(getPoolConfig() ?? undefined).catch(
+    () => [],
+  );
+  if (entries.length === 0) return;
+  ctx.renderer.writeln();
+  ctx.renderer.writeln(`  ${pc.bold("Headroom")}`);
+  for (const entry of entries) {
+    ctx.renderer.writeln(
+      `  ${(entry.label || entry.id).padEnd(14)}${pc.dim(formatHeadroom(entry.headroom))}`,
+    );
+  }
 }
 
 function writePlugins(ctx: CommandContext): void {

package/src/index.ts

@@ -10,6 +10,7 @@
  * backends/frontends/plugins.
  */
 
+import { installSignalListenerGuard } from "./core/daemon/signals.js";
 import {
   MCP_LAUNCH_SUBCOMMAND,
   runSupervisor,
@@ -20,6 +21,12 @@ import {
   runHandoffWatch,
 } from "./core/daemon/handoff.js";
 
+// Before anything can remove a signal listener: under Bun that would
+// silently disarm SIGTERM/SIGINT for the whole process (core/daemon/
+// signals.ts). Every Talon process passes through here, so every one
+// is covered.
+installSignalListenerGuard();
+
 if (process.argv[2] === MCP_LAUNCH_SUBCOMMAND) {
   await runSupervisor(process.argv.slice(3));
 } else if (process.argv[2] === LUA_RUN_SUBCOMMAND) {

package/src/util/log.ts

@@ -68,6 +68,7 @@ export type LogComponent =
   | "memory"
   | "stickers"
   | "backup"
+  | "router"
   | "backend-controller";
 
 const LOG_FILE = files.log;