talon-agent 3.16.1 → 3.18.0

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

@@ -0,0 +1,72 @@
+/**
+ * `/usage` data gathering — plan limits across every backend the config
+ * exposes, not just the one serving this chat.
+ *
+ * Most backends have no plan to report: a gateway (Kilo, OpenCode) bills
+ * 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.
+ */
+
+import type { TalonConfig } from "../../util/config.js";
+import type { PlanUsage } from "../../core/agent-runtime/capabilities.js";
+import {
+  listAvailableBackends,
+  getPooledBackend,
+} from "../../core/engine/backend-controller/index.js";
+import { buildPlanDisplay, type PlanDisplay } from "./status-context.js";
+
+export interface BackendUsageEntry {
+  id: string;
+  label: string;
+  /** Rendered windows, or null when this backend reported nothing. */
+  plan: PlanDisplay | null;
+  /** Why there is nothing to show. Absent when `plan` is set. */
+  note?: string;
+}
+
+/**
+ * One entry per exposed backend, in config order.
+ *
+ * Only backends already running are queried — booting one to read a
+ * number would spawn a subprocess or a server per idle provider, which is
+ * far more than a status command should cost.
+ */
+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;
+}

package/src/frontend/telegram/commands/admin.ts

@@ -21,7 +21,9 @@ import {
   renderDoctorMessage,
   renderMetricsKeyboard,
   renderMetricsPanel,
+  renderUsageMessage,
 } from "../helpers/index.js";
+import { collectPlanUsage } from "../../shared/plan-usage-report.js";
 import { collectDoctorReport } from "../../../core/doctor.js";
 import { handleAdminCommand } from "../admin.js";
 import { getTodayMetrics } from "../../../storage/metrics.js";
@@ -53,6 +55,14 @@ export function registerAdminCommands(
     });
   });
 
+  // /usage — plan limits across every exposed backend, not just this
+  // chat's. Not admin-gated: it says how close the shared account is to a
+  // wall, which is exactly what a user hitting one needs to know.
+  bot.command("usage", async (ctx) => {
+    const entries = await collectPlanUsage(config);
+    await ctx.reply(renderUsageMessage(entries), { parse_mode: "HTML" });
+  });
+
   bot.command("doctor", async (ctx) => {
     if (!isAuthorizedAdmin(ctx)) {
       await ctx.reply("Not authorized.");

package/src/frontend/telegram/commands/definitions.ts

@@ -28,6 +28,7 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
   { command: "pulse", description: "Conversation engagement settings" },
   { command: "reset", description: "Clear session and start fresh" },
   { command: "restart", description: "Restart the bot (admin)" },
+  { command: "usage", description: "Plan limits across every backend" },
   { command: "metrics", description: "Aggregate performance metrics" },
   {
     command: "doctor",

package/src/frontend/telegram/helpers/diagnostics.ts

@@ -5,6 +5,7 @@
 import { escapeHtml } from "../formatting.js";
 import type { DoctorReport } from "../../../core/doctor.js";
 import type { MeshPingResult } from "../../../core/mesh/service.js";
+import type { BackendUsageEntry } from "../../shared/plan-usage-report.js";
 import type { SettingsButton } from "./menu.js";
 import { formatDuration, formatBytes } from "./format.js";
 
@@ -208,14 +209,47 @@ const DOCTOR_ICONS: Record<string, string> = {
  * when this renders, the bot is by definition running, so the CLI's
  * "is the bot up" probe becomes an uptime line instead.
  */
+/** Render the `/usage` report — one block per exposed backend. */
+export function renderUsageMessage(entries: BackendUsageEntry[]): string {
+  const lines = ["<b>📊 Plan usage</b>"];
+
+  for (const entry of entries) {
+    const name = escapeHtml(entry.label || entry.id);
+    if (!entry.plan) {
+      lines.push("", `<b>${name}</b> — <i>${escapeHtml(entry.note ?? "")}</i>`);
+      continue;
+    }
+    const age = entry.plan.ageLabel ? ` <i>(${entry.plan.ageLabel})</i>` : "";
+    const plan = entry.plan.plan ? ` · ${escapeHtml(entry.plan.plan)}` : "";
+    lines.push("", `<b>${name}</b>${plan}${age}`);
+    for (const w of entry.plan.windows) {
+      const reset = w.resetLabel ? ` reset ${w.resetLabel}` : "";
+      lines.push(
+        `  <code>${escapeHtml(w.label.padEnd(6))}${w.bar} ${String(w.percent).padStart(3)}%</code>${reset}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
 export function renderDoctorMessage(report: DoctorReport): string {
   const lines = ["<b>🩺 Talon Doctor</b>", "", "<b>Environment</b>"];
 
-  for (const check of report.checks) {
+  const render = (check: DoctorReport["checks"][number]): string => {
     const detail = check.detail ? ` (${escapeHtml(check.detail)})` : "";
-    lines.push(
-      `${DOCTOR_ICONS[check.status]} ${escapeHtml(check.label)}${detail}`,
-    );
+    return `${DOCTOR_ICONS[check.status]} ${escapeHtml(check.label)}${detail}`;
+  };
+
+  for (const check of report.checks.filter((c) => !c.inactive)) {
+    lines.push(render(check));
+  }
+
+  // Configured-but-idle backends get their own block: they describe what a
+  // switch would run into, not the state of the running deployment.
+  const idle = report.checks.filter((c) => c.inactive);
+  if (idle.length > 0) {
+    lines.push("", "<b>Other backends</b>", ...idle.map(render));
   }
 
   lines.push("", "<b>Native modules</b>");

package/src/util/config.ts

@@ -340,6 +340,16 @@ const configSchema = z.object({
   allowedUsers: z.array(z.number().int()).optional(), // Whitelist of user IDs allowed to DM the bot
   pulse: z.boolean().default(true),
   pulseIntervalMs: z.number().int().min(60000).default(300000),
+  /**
+   * Warn the admin chat when a subscription rate-limit window crosses
+   * `planAlertThreshold`. Off by default. Needs a backend that reports plan
+   * limits (Claude on a subscription); one message per window per reset
+   * cycle.
+   */
+  planAlerts: z.boolean().default(false),
+  planAlertThreshold: z.number().int().min(1).max(100).default(80),
+  /** Chat that receives plan warnings. Defaults to `adminUserId`. */
+  planAlertChatId: z.string().optional(),
   /** Background memory-consolidation (dream) runs. Mirrors `pulse`/`heartbeat`. */
   dream: z.boolean().default(true),
   /**