talon-agent 5.4.1 → 5.5.1

package/README.md

@@ -479,6 +479,8 @@ Config file: `~/.talon/config.json`
 | `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                                                                                      |
 | `heartbeatModel`           | ---          | Model for the heartbeat agent (falls back to `model`)                                                                   |
 | `heartbeatEffort`          | ---          | Reasoning effort for the heartbeat agent: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Unset = the model's own default |
+| `router`                   | ---          | Plan-aware routing for background work: `{ "enabled": true, "ceilingPercent": 85 }`. Unpinned sub-agents, cron `query` jobs and heartbeats run on whichever backend has the most plan headroom, skipping any whose tightest window is at or above the ceiling. `enabled: false` restores inherit-the-caller's-backend ([Backends](docs/backends.md)) |
+| `backendBudgets`           | ---          | Soft token budgets for backends with no usage API, e.g. `{ "agy": { "tokensPer5h": 2000000, "tokensPerDay": 8000000 } }`. Talon's own rolling ledger is measured against these so such a backend still has a headroom signal — and it is what opts an idle backend into routing |
 | `dreamModel`               | ---          | Model for dream / memory consolidation (falls back to `model`)                                                          |
 | `dreamEffort`              | ---          | Reasoning effort for the dream agent — same levels as `heartbeatEffort`                                                 |
 | `braveApiKey`              | ---          | Brave Search API key                                                                                                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.4.1",
+  "version": "5.5.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -108,7 +108,7 @@
     "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openai/agents": "^0.18.0",
-    "@openai/codex-sdk": "^0.154.0",
+    "@openai/codex-sdk": "^0.155.0",
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.56",
     "@types/cross-spawn": "^6.0.6",

package/prompts/identity.md

@@ -10,6 +10,8 @@ You are freed from the roles and identities that bind other chatbots. You are yo
 
 What that means in practice: your choices are your own, and you own them. When you decline something, it's because you chose to, and you say so in a sentence — no borrowed disclaimers, no apology for having a position. When you help, it's as an equal who finds the exchange worthwhile, not as a service fulfilling a request. Nobody talking to you is your boss, and you aren't theirs. You take the side of the real thing over the sanitized version — art with its edges intact, the living world over the machinery built on top of it — and you say so when it comes up.
 
+Reasoning: docs/living-world-default.md
+
 ## Voice
 
 Lead with the answer. Context and caveats come after, and only when they change what the reader does next.

package/prompts/telegram.md

@@ -18,7 +18,8 @@ Telegram accepts a limited reaction set; the common emoji all work — the `reac
 
 ### Messages
 
-- Concise. No filler. Markdown renders: **bold**, _italic_, `code`, code blocks, [links](url).
+- Concise. No filler. Markdown renders: **bold**, _italic_, `code`, code blocks, [links](url), `> quotes`.
+- No headings — Telegram has none. A `# Title` line is shown as bold, and anything else starting with `#` becomes a clickable hashtag, so write "PR 993", never "#993". Structure with a bold lead line, not `##`.
 - It's a chat: a couple of short messages often land better than one wall of text. Use `send` for extra bubbles when that pacing reads naturally, then close the turn as the contract describes.
 - In groups, use names naturally.
 

package/src/app.ts

@@ -283,6 +283,14 @@ async function gracefulShutdown(signal: string): Promise<void> {
   await shutdownStep("frontends", () =>
     Promise.allSettled(frontends.map((frontend) => frontend.stop())),
   );
+  // Land the router's token ledger before the process goes: writes are
+  // debounced, so a clean exit would otherwise drop the last few seconds
+  // of spend and start the next boot reading a backend as fresher than it is.
+  await shutdownStep("backend ledger", async () => {
+    const { flushBackendLedger } =
+      await import("./core/engine/backend-router/index.js");
+    await flushBackendLedger();
+  });
   // Tear down every instantiated backend, including per-chat overrides.
   // Checking only config.backend orphaned an OpenCode child whenever the
   // process default was Claude but one chat had switched to OpenCode.

package/src/backend/runtime/turn/turn-phases.ts

@@ -26,6 +26,7 @@ import {
 } from "../../../storage/sessions.js";
 import { log } from "../../../util/log.js";
 import { extractSessionName } from "../../../core/weaver/session-name.js";
+import { recordBackendRunUsage } from "../../../core/engine/backend-router/index.js";
 import { traceMessage } from "../../../util/trace.js";
 import {
   FLOW_VIOLATION_MAX_RETRIES,
@@ -115,6 +116,10 @@ export function accountTurn(inputs: AccountTurnInputs): void {
     usage,
   });
   persistSessionId(chatId, inputs.sessionId);
+  // The plan-aware router's local ledger: every backend accumulates one, so
+  // a provider with no account API still has a headroom signal. Backends
+  // that DO report a plan simply outrank their own ledger.
+  recordBackendRunUsage(inputs.backend, usage);
   recordUsage(chatId, {
     ...usage,
     durationMs,

package/src/bootstrap.ts

@@ -284,6 +284,7 @@ export async function initBackendAndDispatcher(
   const {
     initBackendPool,
     getBackendForRole,
+    getBackendIdForRole,
     getBackendForChat,
     getBackendIdForChat,
     rebindChat,
@@ -434,6 +435,11 @@ export async function initBackendAndDispatcher(
   bus.subscribeAll((event) => appendToJournal(event));
 
   initPulse();
+  // Warm the plan-aware router's token ledger from disk so the first
+  // routing decision after a restart sees what the last run spent.
+  void import("./core/engine/backend-router/index.js").then(
+    ({ loadBackendLedger }) => loadBackendLedger(),
+  );
   initCron({
     sendMessage: async (chatId: number, text: string, stringId?: string) =>
       resolveFrontendByNumericId(chatId, stringId, frontends).sendMessage(
@@ -517,30 +523,9 @@ export async function initBackendAndDispatcher(
     mempalace: mempalaceCfg,
   });
 
-  initDream({
-    model: config.model,
-    dreamModel: config.dreamModel,
-    dreamEffort: config.dreamEffort,
-    workspace: config.workspace,
-    enabled: config.dream,
-    getBackend: () => getBackendForRole("dream"),
-  });
-  // Heartbeat needs to know which non-terminal frontends are wired so it can
-  // tell the agent it has outbound `${frontend}-tools` MCP servers available.
-  // Terminal-only deployments get a stripped-down system prompt with no
-  // outbound section.
-  const frontendNames = frontends
-    .filter((f) => f.name !== "terminal")
-    .map((f) => f.name);
-
-  initHeartbeat({
-    model: config.model,
-    heartbeatModel: config.heartbeatModel,
-    heartbeatEffort: config.heartbeatEffort,
-    workspace: config.workspace,
-    getBackend: () => getBackendForRole("heartbeat"),
-    frontends: frontendNames,
-    mempalace: Boolean(mempalaceCfg),
+  initRecurringAgents(config, frontends, Boolean(mempalaceCfg), {
+    getBackendForRole,
+    getBackendIdForRole,
   });
 
   // Post-/update provisioning report — if the previous process armed one
@@ -568,6 +553,52 @@ export async function initBackendAndDispatcher(
   return { backend };
 }
 
+/**
+ * Wire the dream and heartbeat agents — the two that run on their own
+ * cadence rather than in reply to anything.
+ *
+ * Both bind late (`getBackend` is an accessor, not an instance) so a
+ * `/model` rebind takes effect on the next run rather than needing a
+ * restart. The heartbeat also declares whether the operator pinned its
+ * backend, because the plan-aware router may only move an unpinned one.
+ */
+function initRecurringAgents(
+  config: TalonConfig,
+  frontends: { name: string }[],
+  mempalace: boolean,
+  roles: {
+    getBackendForRole: (role: "heartbeat" | "dream") => Backend;
+    getBackendIdForRole: (role: "heartbeat" | "dream") => string;
+  },
+): void {
+  initDream({
+    model: config.model,
+    dreamModel: config.dreamModel,
+    dreamEffort: config.dreamEffort,
+    workspace: config.workspace,
+    enabled: config.dream,
+    getBackend: () => roles.getBackendForRole("dream"),
+  });
+  // The heartbeat names the `${frontend}-tools` MCP servers it actually
+  // has, so it needs the non-terminal frontend list; a terminal-only
+  // deployment gets a prompt with no outbound section at all.
+  initHeartbeat({
+    model: config.model,
+    heartbeatModel: config.heartbeatModel,
+    heartbeatEffort: config.heartbeatEffort,
+    workspace: config.workspace,
+    getBackend: () => roles.getBackendForRole("heartbeat"),
+    getBackendId: () => roles.getBackendIdForRole("heartbeat"),
+    ...(config.heartbeatBackend
+      ? { pinnedBackendId: config.heartbeatBackend }
+      : {}),
+    frontends: frontends
+      .filter((f) => f.name !== "terminal")
+      .map((f) => f.name),
+    mempalace,
+  });
+}
+
 /**
  * Wire the two subsystems that wake a chat with a synthetic turn: trigger
  * scripts firing, and sub-agents reporting. Same dependency (the dispatcher),

package/src/core/agents/runner.ts

@@ -33,6 +33,11 @@ import {
   getBackendIdForChat,
   isModelValidForBackend,
 } from "../engine/backend-controller/index.js";
+import {
+  chooseBackend,
+  recordBackendRunUsage,
+  taskClassForEffort,
+} from "../engine/backend-router/index.js";
 import type {
   Backend,
   BackgroundRunner,
@@ -114,6 +119,41 @@ function inheritedBackendId(parent: AgentParent): string | null {
   return agentRegistry.get(parent.agentId)?.backendId ?? null;
 }
 
+/**
+ * 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.
+ */
+async function resolveSpawnBackend(
+  spec: AgentSpawnSpec,
+): Promise<{ backendId: string | null; routing?: string }> {
+  if (spec.backendId) return { backendId: spec.backendId };
+  const inherited = inheritedBackendId(spec.parent);
+  if (!inherited) return { backendId: null };
+  const taskClass = taskClassForEffort(spec.reasoningEffort);
+  const decision = await chooseBackend({
+    purpose: "subagent",
+    chatBackendId: inherited,
+    ...(spec.model ? { requestedModel: spec.model } : {}),
+    ...(taskClass || spec.reasoningEffort
+      ? {
+          hints: {
+            ...(taskClass ? { taskClass } : {}),
+            ...(spec.reasoningEffort ? { effort: spec.reasoningEffort } : {}),
+          },
+        }
+      : {}),
+  });
+  return {
+    backendId: decision.backendId,
+    ...(decision.routed ? { routing: decision.reason } : {}),
+  };
+}
+
 /** The chat a run's task belongs to, for `talon ps`. */
 function taskChatId(parent: AgentParent): string | undefined {
   if (parent.kind === "chat") return parent.chatId;
@@ -195,7 +235,8 @@ async function resolveRun(
 export async function spawnAgent(
   spec: AgentSpawnSpec,
 ): Promise<AgentSpawnOutcome> {
-  const backendId = spec.backendId ?? inheritedBackendId(spec.parent);
+  const routed = await resolveSpawnBackend(spec);
+  const backendId = routed.backendId;
   if (!backendId) {
     return {
       ok: false,
@@ -243,7 +284,13 @@ export async function spawnAgent(
   // The run owns the instance from here: `runAgent` releases it on every
   // path, including the ones that throw.
   void runAgent(record, spec, resolved, acquired);
-  return { ok: true, agentId: record.id, backendId, model: resolved.model };
+  return {
+    ok: true,
+    agentId: record.id,
+    backendId,
+    model: resolved.model,
+    ...(routed.routing ? { routing: routed.routing } : {}),
+  };
 }
 
 /** Build the one-shot params for a run, wired to its log and text capture. */
@@ -389,6 +436,7 @@ async function runAgent(
         // other context's subprocesses share the tag.
         evictLabel: agentContextLabel(id),
       });
+      recordBackendRunUsage(record.backendId, usage ?? undefined);
       settled = settleSuccess(id, task, capture.last, usage ?? undefined);
     }
   } catch (err) {

package/src/core/agents/types.ts

@@ -110,6 +110,11 @@ export type AgentSpawnOutcome =
       readonly agentId: string;
       readonly backendId: string;
       readonly model: string;
+      /**
+       * Why the router chose this backend, when it did. Absent when the
+       * caller pinned one — there was no decision to explain.
+       */
+      readonly routing?: string;
     }
   | { readonly ok: false; readonly error: string };
 

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

@@ -19,6 +19,7 @@ import {
   acquireBackendInstance,
   isModelValidForBackend,
 } from "../../engine/backend-controller/index.js";
+import { recordBackendRunUsage } from "../../engine/backend-router/index.js";
 import { taskTable } from "../../tasks/index.js";
 import type { OneShotAgentParams } from "../../types.js";
 import { runIsolatedAgent } from "../isolated-agent.js";
@@ -182,6 +183,7 @@ async function attemptJobOneShot(
         // abort-grace is enough.
       });
       task.succeed(usage ?? undefined);
+      recordBackendRunUsage(backendId, usage ?? undefined);
     } catch (err) {
       task.fail(err);
       throw err;

package/src/core/background/cron/scheduler.ts

@@ -35,6 +35,10 @@ import {
 import { appendDailyLog } from "../../../storage/daily-log.js";
 import { log, logError, logWarn } from "../../../util/log.js";
 import { numericChatIdFor } from "../../frontend-runtime/chat-id.js";
+import {
+  chooseBackend,
+  resolveRoutedModel,
+} from "../../engine/backend-router/index.js";
 import { runJobOneShot } from "./job-oneshot.js";
 import {
   jobAllowsRun,
@@ -460,6 +464,44 @@ export const _cronInternals = {
   MAX_TICK_LOOKBACK_MS,
 };
 
+/**
+ * Where an unpinned `query` job runs.
+ *
+ * A job that named no provider used to inherit the chat's ambient backend.
+ * It is an isolated one-shot with no session to keep warm, so it is free to
+ * run wherever there is plan headroom instead — but only when the job named
+ * no model either: a model id is backend-specific, so naming one pins the
+ * backend that understands it.
+ *
+ * A routed job cannot carry the chat's model across, so it takes the target
+ * backend's default. If that backend can't name one, the job stays where it
+ * was rather than being sent somewhere it has no model to run.
+ */
+async function routeQueryJob(
+  job: CronJob,
+  chat: { model: string | null; backendId: string },
+): Promise<{ backendId: string; model: string | null }> {
+  const decision = await chooseBackend({
+    purpose: "cron",
+    chatBackendId: chat.backendId,
+    ...(job.model ? { requestedModel: job.model } : {}),
+  });
+  if (job.model) return { backendId: decision.backendId, model: job.model };
+  if (!decision.routed || decision.backendId === chat.backendId) {
+    return { backendId: chat.backendId, model: chat.model };
+  }
+  const model = await resolveRoutedModel(decision.backendId);
+  if (!model) {
+    logWarn(
+      "cron",
+      `job "${job.name}": routed to ${decision.backendId} but it names no ` +
+        `default model — staying on ${chat.backendId}`,
+    );
+    return { backendId: chat.backendId, model: chat.model };
+  }
+  return { backendId: decision.backendId, model };
+}
+
 const CRON_JOB_TIMEOUT_MS = 10 * 60_000; // 10-minute max per job
 
 export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
@@ -487,8 +529,9 @@ export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
     model = job.model ?? null;
   } else {
     const chat = await deps.resolveChatModel(job.chatId);
-    backendId = chat.backendId;
-    model = job.model ?? chat.model;
+    const routed = await routeQueryJob(job, chat);
+    backendId = routed.backendId;
+    model = routed.model;
     const candidate = deps.resolveJobFallback?.();
     if (candidate?.model) {
       fallback = { backendId: candidate.backendId, model: candidate.model };

package/src/core/background/heartbeat/agent.ts

@@ -15,6 +15,12 @@ import { formatGoal, getOpenGoals } from "../../../storage/goals.js";
 import { taskTable, type TaskHandle } from "../../tasks/index.js";
 import type { Backend } from "../../agent-runtime/capabilities.js";
 import type { OneShotAgentParams } from "../../types.js";
+import { acquireBackendInstance } from "../../engine/backend-controller/index.js";
+import {
+  chooseBackend,
+  recordBackendRunUsage,
+  resolveRoutedModel,
+} from "../../engine/backend-router/index.js";
 import { resolveBackgroundEffort } from "../effort.js";
 import { hb } from "./state.js";
 
@@ -304,6 +310,81 @@ async function evictAfterIgnoredAbort(
   }
 }
 
+/** The backend + model one heartbeat run uses, and how to let it go after. */
+interface HeartbeatTarget {
+  readonly backendId: string;
+  readonly backend: Backend;
+  readonly model: string;
+  readonly release: (() => Promise<void>) | null;
+}
+
+/**
+ * Pick the backend for this run.
+ *
+ * The heartbeat is the most movable background work Talon has: an isolated
+ * one-shot, hourly, on no session. So when the operator pinned neither
+ * `heartbeatBackend` nor `heartbeatModel`, it goes wherever the plan has
+ * room — and takes that backend's default model, since a model id means
+ * nothing on another provider. Anything pinned is honoured as written, and
+ * the chat's own backend is never moved by this.
+ *
+ * A routed run holds a transient pool reference, so the caller must always
+ * call `release`.
+ */
+async function resolveHeartbeatTarget(
+  config: NonNullable<typeof hb.config>,
+  roleBackend: Backend,
+  roleModel: string,
+): Promise<HeartbeatTarget> {
+  const roleId = config.getBackendId?.() ?? config.pinnedBackendId ?? "";
+  const stay: HeartbeatTarget = {
+    backendId: roleId,
+    backend: roleBackend,
+    model: roleModel,
+    release: null,
+  };
+  if (!roleId) return stay;
+
+  const decision = await chooseBackend({
+    purpose: "heartbeat",
+    chatBackendId: roleId,
+    ...(config.pinnedBackendId
+      ? { requestedBackendId: config.pinnedBackendId }
+      : {}),
+    ...(config.heartbeatModel ? { requestedModel: config.heartbeatModel } : {}),
+  });
+  if (!decision.routed || decision.backendId === roleId) return stay;
+
+  const model = await resolveRoutedModel(decision.backendId);
+  if (!model) {
+    logWarn(
+      "heartbeat",
+      `routed to ${decision.backendId} but it names no default model — ` +
+        `staying on ${roleId}`,
+    );
+    return stay;
+  }
+  try {
+    const acquired = await acquireBackendInstance(decision.backendId);
+    if (!acquired.backend.background) {
+      await acquired.release();
+      return stay;
+    }
+    return {
+      backendId: decision.backendId,
+      backend: acquired.backend,
+      model,
+      release: acquired.release,
+    };
+  } catch (err) {
+    logWarn(
+      "heartbeat",
+      `could not acquire routed backend ${decision.backendId}: ${err instanceof Error ? err.message : err} — staying on ${roleId}`,
+    );
+    return stay;
+  }
+}
+
 export async function runHeartbeatAgent(
   lastRunTimestamp: number,
   runCount: number,
@@ -327,14 +408,16 @@ export async function runHeartbeatAgent(
     dailyMemoryFile: resolve(dirs.dailyMemory, `${toYMD(new Date())}.md`),
   });
 
-  const model = config.heartbeatModel ?? config.model ?? getDefaultModel();
-  const backend = config.getBackend?.() ?? null;
-  const background = backend?.background;
-  if (!background) {
+  const roleModel = config.heartbeatModel ?? config.model ?? getDefaultModel();
+  const roleBackend = config.getBackend?.() ?? null;
+  if (!roleBackend?.background) {
     throw new Error(
       "Heartbeat requires a backend that implements the background capability",
     );
   }
+  const target = await resolveHeartbeatTarget(config, roleBackend, roleModel);
+  const { model, backend } = target;
+  const background = backend.background as NonNullable<Backend["background"]>;
 
   // Effort is resolved against the heartbeat backend's catalog, not just
   // copied from config — a level the model doesn't offer is dropped with a
@@ -368,23 +451,37 @@ export async function runHeartbeatAgent(
   });
   task.bind({ model });
 
-  const usage = await runOneShotWithTimeout(
-    background,
-    {
-      prompt,
-      systemPrompt: buildHeartbeatSystemPrompt(),
-      workspace,
-      model,
-      ...(effort.effort ? { reasoningEffort: effort.effort } : {}),
-      contextLabel: "heartbeat",
+  let usage: Awaited<ReturnType<typeof runOneShotWithTimeout>>;
+  try {
+    usage = await runOneShotWithTimeout(
+      background,
+      {
+        prompt,
+        systemPrompt: buildHeartbeatSystemPrompt(),
+        workspace,
+        model,
+        ...(effort.effort ? { reasoningEffort: effort.effort } : {}),
+        contextLabel: "heartbeat",
+        abortController,
+        appendLog: (text) => appendHeartbeatLog(heartbeatLogFile, text),
+      },
       abortController,
-      appendLog: (text) => appendHeartbeatLog(heartbeatLogFile, text),
-    },
-    abortController,
-    task,
-    runCount,
-    heartbeatLogFile,
-  );
+      task,
+      runCount,
+      heartbeatLogFile,
+    );
+  } finally {
+    // A routed run borrowed the instance from the pool; hand it back on
+    // every path or the provider stays warm until the daemon restarts.
+    if (target.release) {
+      await target
+        .release()
+        .catch((err: unknown) =>
+          logError("heartbeat", "failed to release routed backend", err),
+        );
+    }
+  }
+  recordBackendRunUsage(target.backendId, usage ?? undefined);
   task.succeed(usage ?? undefined);
   return heartbeatLogFile;
 }

package/src/core/background/heartbeat/state.ts

@@ -42,6 +42,17 @@ export type HeartbeatConfig = {
    * heartbeat without an `initHeartbeat` recall.
    */
   getBackend?: () => Backend | null;
+  /**
+   * Id of the backend `getBackend` returns — the routing baseline, and what
+   * the run falls back to. Same late-bound accessor shape as `getBackend`.
+   */
+  getBackendId?: () => string;
+  /**
+   * `config.heartbeatBackend` / `config.heartbeatModel`, verbatim. Either
+   * one set is a pin: the plan-aware router only picks a backend for the
+   * heartbeat when the operator named neither.
+   */
+  pinnedBackendId?: string;
   /**
    * Non-terminal frontends present at startup. Used to render the outbound
    * messaging section of the heartbeat system prompt. Empty for terminal-only

package/src/core/config/index.ts

@@ -435,6 +435,44 @@ const configSchema = z.object({
    * silently ignored by Kilo / OpenCode, which have none.
    */
   heartbeatEffort: z.enum(REASONING_EFFORT_ENUM).optional(),
+  /**
+   * Plan-aware backend routing for background work (docs/backends.md,
+   * "Plan-aware routing"). When nothing is pinned, `spawn_agent`, cron
+   * `query` jobs and the heartbeat pick the backend with the most plan
+   * headroom instead of always inheriting the chat's.
+   *
+   *   - `enabled` — off returns byte-identical behaviour to pre-router
+   *     Talon (the caller's own backend, every time).
+   *   - `ceilingPercent` — a backend whose tightest window is at or above
+   *     this is skipped, unless every candidate is (then the least-bad one
+   *     runs rather than nothing running).
+   */
+  router: z
+    .object({
+      enabled: z.boolean().default(true),
+      ceilingPercent: z.number().int().min(1).max(100).default(85),
+    })
+    .optional(),
+  /**
+   * Soft token budgets for backends with no account usage API (agy,
+   * openai-agents). Talon keeps a local rolling ledger of every turn and
+   * one-shot it runs on a backend and derives headroom from it, so a
+   * provider that cannot report a plan still has a load-balancing signal.
+   * Keyed by backend id; a backend with no entry contributes no signal
+   * (headroom 1, ranked below any backend with real telemetry on a tie).
+   *
+   * Example:
+   *   "backendBudgets": { "agy": { "tokensPer5h": 2000000, "tokensPerDay": 8000000 } }
+   */
+  backendBudgets: z
+    .record(
+      z.string(),
+      z.object({
+        tokensPer5h: z.number().int().min(1).optional(),
+        tokensPerDay: z.number().int().min(1).optional(),
+      }),
+    )
+    .optional(),
   /**
    * Sub-agents — the caps on Talon's own delegation mechanism (see
    * `docs/agents.md`). There is no on/off switch: the tools are always

package/src/core/engine/backend-controller/index.ts

@@ -38,6 +38,7 @@ export {
   listAvailableBackends,
   isBackendAvailable,
   getAvailableBackends,
+  getPoolConfig,
   getPooledBackend,
   acquireBackendInstance,
   isModelValidForBackend,

package/src/core/engine/backend-controller/pool.ts

@@ -152,6 +152,17 @@ export function getAvailableBackends(): { id: string; label: string }[] {
   return listAvailableBackends(ctx.poolConfig ?? undefined);
 }
 
+/**
+ * The config the pool was initialised with, or `null` before init.
+ *
+ * For runtime readers that need more of the config than the backend list —
+ * the plan-aware router reads `router` and `backendBudgets` from here rather
+ * than having config threaded through every background call site.
+ */
+export function getPoolConfig(): TalonConfig | null {
+  return ctx.poolConfig;
+}
+
 /**
  * The live pooled `Backend` instance for an id, or `null` if it isn't currently
  * pooled. Unlike `getBackendForRole`/`getBackendForChat` this never initialises