talon-agent 5.4.0 → 5.5.0

package/src/core/engine/backend-router/ledger.ts

@@ -0,0 +1,248 @@
+/**
+ * Local rolling token ledger — the headroom signal for backends with no
+ * account usage API.
+ *
+ * Claude and Codex report subscription windows; `agy` has no account
+ * endpoint and `openai-agents` has no plan at all. Without a second signal
+ * the router would treat those as infinitely fresh and pile every background
+ * run onto them. So Talon counts what it spends itself: every chat turn,
+ * one-shot and sub-agent folds its token total into a per-backend ledger,
+ * and `headroom.ts` reads that against the operator's soft budget
+ * (`config.backendBudgets`).
+ *
+ * The ledger is deliberately a *local estimate*, not accounting: it only
+ * sees what this daemon ran, and a plan API always takes precedence when
+ * one exists. Entries older than the widest window (24h) are pruned on
+ * every read and write, which also bounds the file.
+ *
+ * Persistence is `~/.talon/data/backend-ledger.json`, written atomically so
+ * a restart mid-write can't leave a truncated file — a zeroed ledger would
+ * silently hand a spent backend a full headroom score.
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { dirs } from "../../../util/paths.js";
+import { logWarn } from "../../../util/log.js";
+import { writePrivateJson } from "../../mesh/persist.js";
+
+/** Widest window the ledger answers for; everything older is dropped. */
+export const LEDGER_RETENTION_MS = 24 * 60 * 60_000;
+/** The short window, as `backendBudgets.tokensPer5h` measures it. */
+export const LEDGER_SHORT_WINDOW_MS = 5 * 60 * 60_000;
+
+/** How long a write is coalesced for, so a burst of turns is one fsync. */
+const FLUSH_DEBOUNCE_MS = 2_000;
+
+/** One recorded spend: when it happened and how many tokens it cost. */
+interface LedgerEntry {
+  /** Epoch ms. */
+  readonly t: number;
+  /** Total tokens (input + output + cache + thinking, as the backend counts). */
+  readonly n: number;
+}
+
+interface LedgerFile {
+  readonly version: 1;
+  readonly backends: Record<string, LedgerEntry[]>;
+}
+
+interface LedgerState {
+  entries: Map<string, LedgerEntry[]>;
+  loaded: boolean;
+  loading: Promise<void> | null;
+  flushTimer: ReturnType<typeof setTimeout> | null;
+  dirty: boolean;
+  /** Overridable for tests; resolved lazily so TALON_HOME changes are seen. */
+  path: string | null;
+}
+
+const state: LedgerState = {
+  entries: new Map(),
+  loaded: false,
+  loading: null,
+  flushTimer: null,
+  dirty: false,
+  path: null,
+};
+
+function ledgerPath(): string {
+  return state.path ?? resolve(dirs.data, "backend-ledger.json");
+}
+
+/** Drop entries that have aged out of the widest window. */
+function prune(list: LedgerEntry[], now: number): LedgerEntry[] {
+  const floor = now - LEDGER_RETENTION_MS;
+  // Entries are appended in time order, so the survivors are a suffix —
+  // but a clock step backwards can break that, hence a filter not a slice.
+  return list.filter((e) => e.t > floor);
+}
+
+function parseLedger(raw: unknown): Map<string, LedgerEntry[]> {
+  const out = new Map<string, LedgerEntry[]>();
+  if (!raw || typeof raw !== "object") return out;
+  const file = raw as Partial<LedgerFile>;
+  if (file.version !== 1 || !file.backends) return out;
+  const now = Date.now();
+  for (const [id, list] of Object.entries(file.backends)) {
+    if (!Array.isArray(list)) continue;
+    const clean = list.filter(
+      (e): e is LedgerEntry =>
+        Boolean(e) &&
+        typeof (e as LedgerEntry).t === "number" &&
+        typeof (e as LedgerEntry).n === "number" &&
+        Number.isFinite((e as LedgerEntry).t) &&
+        Number.isFinite((e as LedgerEntry).n),
+    );
+    const pruned = prune(clean, now);
+    if (pruned.length > 0) out.set(id, pruned);
+  }
+  return out;
+}
+
+/**
+ * Load the persisted ledger once per process. Idempotent and safe to call
+ * concurrently — every caller awaits the same read. A missing or corrupt
+ * file starts an empty ledger rather than failing a routing decision.
+ */
+export async function loadBackendLedger(): Promise<void> {
+  if (state.loaded) return;
+  if (state.loading) return state.loading;
+  state.loading = (async () => {
+    try {
+      const raw = await readFile(ledgerPath(), "utf8");
+      const parsed = parseLedger(JSON.parse(raw));
+      // In-process records taken while the read was in flight win: merge
+      // rather than replace, so a turn that landed during boot isn't lost.
+      for (const [id, list] of parsed) {
+        state.entries.set(id, [...list, ...(state.entries.get(id) ?? [])]);
+      }
+    } catch {
+      /* no ledger yet, or unreadable — start empty */
+    }
+    state.loaded = true;
+    state.loading = null;
+  })();
+  return state.loading;
+}
+
+function scheduleFlush(): void {
+  state.dirty = true;
+  if (state.flushTimer) return;
+  const timer = setTimeout(() => {
+    state.flushTimer = null;
+    void flushBackendLedger();
+  }, FLUSH_DEBOUNCE_MS);
+  timer.unref?.();
+  state.flushTimer = timer;
+}
+
+/** Write the ledger out now. Exported so shutdown and tests can force it. */
+export async function flushBackendLedger(): Promise<void> {
+  if (!state.dirty) return;
+  state.dirty = false;
+  const now = Date.now();
+  const backends: Record<string, LedgerEntry[]> = {};
+  for (const [id, list] of state.entries) {
+    const pruned = prune(list, now);
+    state.entries.set(id, pruned);
+    if (pruned.length > 0) backends[id] = pruned;
+  }
+  try {
+    await writePrivateJson(ledgerPath(), {
+      version: 1,
+      backends,
+    } satisfies LedgerFile);
+  } catch (err) {
+    logWarn(
+      "router",
+      `Could not persist the backend ledger: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/**
+ * Fold one run's token spend into a backend's ledger.
+ *
+ * Called from the shared turn accounting and from every one-shot completion
+ * path, so *all* backends accumulate a ledger — the plan API simply wins over
+ * it where one exists. Cheap and synchronous: the disk write is debounced.
+ */
+export function recordBackendUsage(
+  backendId: string,
+  tokens: number,
+  at = Date.now(),
+): void {
+  if (!backendId) return;
+  if (!Number.isFinite(tokens) || tokens <= 0) return;
+  // A first record before the file has been read would be overwritten by the
+  // load; kick the read off here so the merge in loadBackendLedger keeps it.
+  if (!state.loaded && !state.loading) void loadBackendLedger();
+  const list = state.entries.get(backendId) ?? [];
+  list.push({ t: at, n: Math.round(tokens) });
+  state.entries.set(backendId, prune(list, at));
+  scheduleFlush();
+}
+
+/**
+ * Fold a completed run's usage into the ledger. The same four fields every
+ * background path reports (`OneShotUsage`, `TaskUsage`), summed — cache
+ * reads included, because they still count against a subscription window.
+ */
+export function recordBackendRunUsage(
+  backendId: string,
+  usage:
+    | {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+      }
+    | undefined
+    | null,
+  at = Date.now(),
+): void {
+  if (!usage) return;
+  const total =
+    (usage.inputTokens ?? 0) +
+    (usage.outputTokens ?? 0) +
+    (usage.cacheRead ?? 0) +
+    (usage.cacheWrite ?? 0);
+  recordBackendUsage(backendId, total, at);
+}
+
+/** Tokens a backend spent inside a window ending now. */
+export function tokensInWindow(
+  backendId: string,
+  windowMs: number,
+  now = Date.now(),
+): number {
+  const list = state.entries.get(backendId);
+  if (!list || list.length === 0) return 0;
+  const floor = now - windowMs;
+  let total = 0;
+  for (const entry of list) if (entry.t > floor) total += entry.n;
+  return total;
+}
+
+/** Both windows the budget schema knows about, for one backend. */
+export function ledgerUsage(
+  backendId: string,
+  now = Date.now(),
+): { tokens5h: number; tokensDay: number } {
+  return {
+    tokens5h: tokensInWindow(backendId, LEDGER_SHORT_WINDOW_MS, now),
+    tokensDay: tokensInWindow(backendId, LEDGER_RETENTION_MS, now),
+  };
+}
+
+/** Test seam — point the ledger at a temp file and start from empty. */
+export function resetBackendLedgerForTest(path?: string): void {
+  if (state.flushTimer) clearTimeout(state.flushTimer);
+  state.entries = new Map();
+  state.loaded = false;
+  state.loading = null;
+  state.flushTimer = null;
+  state.dirty = false;
+  state.path = path ?? null;
+}

package/src/core/engine/backend-router/router.ts

@@ -0,0 +1,322 @@
+/**
+ * Plan-aware backend routing for background work.
+ *
+ * Background work — `spawn_agent` sub-agents, cron `query` jobs, the
+ * heartbeat — used to inherit whichever backend the chat happened to be on.
+ * On a multi-subscription install that is a good way to burn one plan to its
+ * ceiling while another sits idle. When nothing is pinned, this picks the
+ * backend with the most headroom instead.
+ *
+ * The rules, in order:
+ *
+ *   1. An explicit backend (or a model, which pins its backend) always wins.
+ *      Routing is what happens in the *absence* of a choice, never over one.
+ *   2. `config.router.enabled: false` returns the caller's own backend —
+ *      byte-identical to pre-router Talon.
+ *   3. Otherwise: rank the candidates by headroom, skip anyone at or above
+ *      `ceilingPercent`, and take the top one.
+ *
+ * Only backends that can actually host an isolated run are candidates, and
+ * routing never boots a cold provider to find out: a backend qualifies when
+ * it is pooled with a `background` slot, or when the operator gave it a local
+ * budget (`backendBudgets`), which is both an opt-in and the only way it
+ * would have a headroom signal. The caller's own backend is always in the
+ * running, so there is always an answer.
+ */
+
+import type { TalonConfig } from "../../config/index.js";
+import type { ReasoningEffortLevel } from "../../types.js";
+import { log } from "../../../util/log.js";
+import {
+  acquireBackendInstance,
+  getPoolConfig,
+  getPooledBackend,
+  listAvailableBackends,
+} from "../backend-controller/index.js";
+import {
+  formatHeadroom,
+  getBackendHeadroom,
+  hasBudget,
+  type BackendHeadroom,
+} from "./headroom.js";
+
+/** Default for `config.router.ceilingPercent`. */
+export const DEFAULT_CEILING_PERCENT = 85;
+
+/** Which background subsystem is asking. Logged, and nothing else — yet. */
+export type RoutePurpose = "subagent" | "cron" | "heartbeat";
+
+/**
+ * A coarse shape-of-work hint. It never outranks headroom: a class either
+ * *vetoes* backends that cannot do the job at all, or breaks a tie.
+ */
+export type TaskClass = "coding" | "mechanical" | "reasoning";
+
+/**
+ * The one place the task-class opinions live. `require` is a veto (applied
+ * only when at least one required backend is a candidate, so a deployment
+ * without it still gets an answer); `prefer` is tie-break order.
+ *
+ *   - coding      — agentic edit/test loops; Codex and Claude are the two
+ *                   with real harnesses behind them.
+ *   - mechanical  — sweeps and reformatting; cheapest first (agy's flash
+ *                   tier, then Claude's haiku tier).
+ *   - reasoning   — deep thinking (also where `xhigh` effort lands); Claude
+ *                   is the only backend Talon drives an opus-class model on.
+ */
+const TASK_CLASS_RULES: Record<
+  TaskClass,
+  { readonly prefer: readonly string[]; readonly require?: readonly string[] }
+> = {
+  coding: { prefer: ["codex", "claude"] },
+  mechanical: { prefer: ["agy", "claude"] },
+  reasoning: { prefer: ["claude"], require: ["claude"] },
+};
+
+/** Ranking priority of a headroom source — measured beats unmeasured. */
+const SOURCE_RANK: Record<BackendHeadroom["source"], number> = {
+  plan: 0,
+  ledger: 1,
+  none: 2,
+};
+
+export interface RouteHints {
+  readonly taskClass?: TaskClass;
+  readonly effort?: ReasoningEffortLevel;
+}
+
+export interface RouteRequest {
+  readonly purpose: RoutePurpose;
+  /** An explicit backend from the caller. Wins outright. */
+  readonly requestedBackendId?: string;
+  /** An explicit model. Pins whatever backend is serving it. */
+  readonly requestedModel?: string;
+  /** The backend the caller would have used before routing existed. */
+  readonly chatBackendId: string;
+  /** Defaults to the config the backend pool was initialised with. */
+  readonly config?: TalonConfig;
+  readonly hints?: RouteHints;
+}
+
+export interface RouteDecision {
+  readonly backendId: string;
+  /** Only set when the caller pinned one — model choice stays downstream. */
+  readonly model?: string;
+  /** Human-readable: `pinned`, `disabled`, or why this backend won. */
+  readonly reason: string;
+  /** True when headroom actually chose this, rather than a pin or a default. */
+  readonly routed: boolean;
+  /** What the decision saw, for the spawn reply and the log line. */
+  readonly headroom?: BackendHeadroom;
+}
+
+/** The task class a reasoning-effort level implies, if any. */
+export function taskClassForEffort(
+  effort: ReasoningEffortLevel | undefined,
+): TaskClass | undefined {
+  return effort === "xhigh" || effort === "high" ? "reasoning" : undefined;
+}
+
+/** `config.router`, with the documented defaults filled in. */
+function routerSettings(config: TalonConfig | undefined): {
+  enabled: boolean;
+  ceilingPercent: number;
+} {
+  return {
+    enabled: config?.router?.enabled ?? true,
+    ceilingPercent: config?.router?.ceilingPercent ?? DEFAULT_CEILING_PERCENT,
+  };
+}
+
+/**
+ * Can this backend host an isolated run, without booting it to find out?
+ * A pooled instance answers from its capability slots; a cold one qualifies
+ * only on an explicit local budget (see the module comment).
+ */
+function isCandidate(
+  id: string,
+  config: TalonConfig | undefined,
+  chatBackendId: string,
+): boolean {
+  if (id === chatBackendId) return true;
+  const pooled = getPooledBackend(id);
+  if (pooled) return Boolean(pooled.background);
+  return hasBudget(config, id);
+}
+
+/** Percent of the tightest window — what the ceiling is applied to. */
+function limitingPercent(entry: BackendHeadroom): number {
+  return entry.limiting?.percent ?? 0;
+}
+
+/** Comparator: headroom first, then the documented tie-breaks. */
+function rank(
+  a: BackendHeadroom,
+  b: BackendHeadroom,
+  chatBackendId: string,
+  prefer: readonly string[],
+): number {
+  // Headroom to 3dp: two backends a thousandth apart are a tie, not a winner.
+  const byHeadroom =
+    Math.round(b.headroom * 1000) - Math.round(a.headroom * 1000);
+  if (byHeadroom !== 0) return byHeadroom;
+  const bySource = SOURCE_RANK[a.source] - SOURCE_RANK[b.source];
+  if (bySource !== 0) return bySource;
+  const preferIndex = (id: string): number => {
+    const i = prefer.indexOf(id);
+    return i === -1 ? prefer.length : i;
+  };
+  const byPrefer = preferIndex(a.id) - preferIndex(b.id);
+  if (byPrefer !== 0) return byPrefer;
+  // Cache warmth: a sub-agent is isolated, but the caller's backend is
+  // already up and its MCP servers are already spawned.
+  if (a.id === chatBackendId) return -1;
+  if (b.id === chatBackendId) return 1;
+  return a.id.localeCompare(b.id);
+}
+
+/**
+ * Apply a task class's hard requirement, when a candidate still satisfies it.
+ * Runs on the post-ceiling set, so a spent required backend is already gone.
+ */
+function applyVeto(
+  entries: BackendHeadroom[],
+  required: readonly string[] | undefined,
+): BackendHeadroom[] {
+  if (!required || required.length === 0) return entries;
+  const kept = entries.filter((e) => required.includes(e.id));
+  return kept.length > 0 ? kept : entries;
+}
+
+/** Drop candidates at or above the ceiling — unless that drops all of them. */
+function applyCeiling(
+  entries: BackendHeadroom[],
+  ceilingPercent: number,
+): { kept: BackendHeadroom[]; allOverCeiling: boolean } {
+  const kept = entries.filter((e) => limitingPercent(e) < ceilingPercent);
+  if (kept.length > 0) return { kept, allOverCeiling: false };
+  // Everything is spent. Running the least-bad one beats running nothing:
+  // the background subsystems have no queue to defer into.
+  return { kept: entries, allOverCeiling: true };
+}
+
+function decisionFor(
+  winner: BackendHeadroom,
+  allOverCeiling: boolean,
+): RouteDecision {
+  const reason = allOverCeiling
+    ? `every backend is over the ceiling — least spent: ${formatHeadroom(winner)}`
+    : `most headroom ${Math.round(winner.headroom * 100)}%`;
+  return {
+    backendId: winner.id,
+    reason,
+    routed: true,
+    headroom: winner,
+  };
+}
+
+function logDecision(
+  request: RouteRequest,
+  decision: RouteDecision,
+  candidates: BackendHeadroom[],
+): void {
+  const seen = candidates.map((c) => `${c.id}=${formatHeadroom(c)}`).join(", ");
+  log(
+    "router",
+    `${request.purpose}: → ${decision.backendId} (${decision.reason})` +
+      (seen ? ` | candidates: ${seen}` : ""),
+  );
+}
+
+/**
+ * Choose the backend a piece of background work should run on.
+ *
+ * Never throws and never returns nothing: every path ends at a real backend
+ * id, falling back to the caller's own.
+ */
+export async function chooseBackend(
+  request: RouteRequest,
+): Promise<RouteDecision> {
+  const { chatBackendId, purpose } = request;
+
+  if (request.requestedBackendId || request.requestedModel) {
+    const decision: RouteDecision = {
+      backendId: request.requestedBackendId ?? chatBackendId,
+      reason: "pinned",
+      routed: false,
+      ...(request.requestedModel ? { model: request.requestedModel } : {}),
+    };
+    log("router", `${purpose}: → ${decision.backendId} (pinned)`);
+    return decision;
+  }
+
+  const config = request.config ?? getPoolConfig() ?? undefined;
+  const settings = routerSettings(config);
+  if (!settings.enabled) {
+    return { backendId: chatBackendId, reason: "disabled", routed: false };
+  }
+
+  const ids = listAvailableBackends(config)
+    .filter(({ id }) => isCandidate(id, config, chatBackendId))
+    .map(({ id, label }) => ({ id, label }));
+  if (ids.length === 0) {
+    return { backendId: chatBackendId, reason: "no candidates", routed: false };
+  }
+
+  const measured = await Promise.all(
+    ids.map(({ id, label }) => getBackendHeadroom(id, label, config)),
+  );
+
+  const rules = request.hints?.taskClass
+    ? TASK_CLASS_RULES[request.hints.taskClass]
+    : undefined;
+  // Ceiling first, THEN the veto: a hard task-class requirement must not be
+  // able to send work to a backend that is out of plan. A lesser model that
+  // runs beats the right one that rate-limits.
+  const { kept, allOverCeiling } = applyCeiling(
+    measured,
+    settings.ceilingPercent,
+  );
+  const eligible = applyVeto(kept, rules?.require);
+  const ordered = [...eligible].sort((a, b) =>
+    rank(a, b, chatBackendId, rules?.prefer ?? []),
+  );
+  const winner = ordered[0];
+  if (!winner) {
+    return { backendId: chatBackendId, reason: "no candidates", routed: false };
+  }
+
+  const decision = decisionFor(winner, allOverCeiling);
+  logDecision(request, decision, measured);
+  return decision;
+}
+
+/**
+ * The default model for a backend the router just picked.
+ *
+ * A routed run cannot carry the caller's model across — a model id is
+ * backend-specific. Config's `backendDefaults` wins (it is the operator's
+ * answer to "what should this provider run"), then the backend's own
+ * canonical default. Resolves `null` when neither exists, which the call
+ * sites read as "stay where you were".
+ */
+export async function resolveRoutedModel(
+  backendId: string,
+  config?: TalonConfig,
+): Promise<string | null> {
+  const settings = config ?? getPoolConfig() ?? undefined;
+  const configured = settings?.backendDefaults?.[backendId];
+  if (configured) return configured;
+  try {
+    const pooled = getPooledBackend(backendId);
+    if (pooled) return (await pooled.models?.getDefaultModelId()) ?? null;
+    const acquired = await acquireBackendInstance(backendId);
+    try {
+      return (await acquired.backend.models?.getDefaultModelId()) ?? null;
+    } finally {
+      await acquired.release();
+    }
+  } catch {
+    return null;
+  }
+}

package/src/core/engine/backend-router/usage.ts

@@ -0,0 +1,80 @@
+/**
+ * One usage snapshot per backend — what `/usage`, the `plan_usage` tool and
+ * `list_backends` all read.
+ *
+ * It lives in core rather than in the frontend presentation layer because
+ * the gateway tools need it too, and core cannot import a frontend. The
+ * split is: this module *gathers* (plan windows, headroom, and the reason
+ * there is nothing to show), renderers *format*.
+ *
+ * Nothing here boots a backend. Reading a number should never cost a
+ * subprocess per idle provider, so a backend that isn't running is listed
+ * with a reason instead of being woken or omitted.
+ */
+
+import type { PlanUsage } from "../../agent-runtime/capabilities.js";
+import type { TalonConfig } from "../../config/index.js";
+import {
+  getPooledBackend,
+  listAvailableBackends,
+} from "../backend-controller/index.js";
+import { getBackendHeadroom, type BackendHeadroom } from "./headroom.js";
+
+export interface BackendUsageSnapshot {
+  readonly id: string;
+  readonly label: string;
+  /** Raw plan windows, when this backend reported any. */
+  readonly plan?: PlanUsage;
+  /** Always present — every backend gets a comparable headroom figure. */
+  readonly headroom: BackendHeadroom;
+  /** Why there is no `plan`. Absent when there is one. */
+  readonly note?: string;
+}
+
+/** The reason a backend has no plan windows to show. */
+function noteFor(id: string, headroom: BackendHeadroom): string {
+  const backend = getPooledBackend(id);
+  if (!backend) return "not running";
+  if (!backend.usage?.getPlanUsage) return "no plan limits on this backend";
+  if (headroom.source === "ledger") return "tracked against a local budget";
+  return "no usage information available";
+}
+
+/**
+ * Every exposed backend, in config order, with its plan (where it has one)
+ * and its headroom (always).
+ *
+ * `force` skips the 60s headroom cache — a person looking at `/usage` wants
+ * the number now, where a routing decision a second after another one does
+ * not.
+ */
+export async function collectBackendUsage(
+  config: TalonConfig | undefined,
+  options?: { force?: boolean },
+): Promise<BackendUsageSnapshot[]> {
+  const backends = listAvailableBackends(config);
+  return Promise.all(
+    backends.map(async ({ id, label }) => {
+      const headroom = await getBackendHeadroom(id, label, config, options);
+      if (headroom.plan && headroom.plan.windows.length > 0) {
+        return { id, label, headroom, plan: headroom.plan };
+      }
+      return { id, label, headroom, note: noteFor(id, headroom) };
+    }),
+  );
+}
+
+/**
+ * Reorder a snapshot list so one backend comes first, everything else
+ * keeping config order. The `plan_usage` tool leads with the chat's own
+ * backend so callers that only read the first entry see what they used to.
+ */
+export function leadWith(
+  entries: BackendUsageSnapshot[],
+  id: string,
+): BackendUsageSnapshot[] {
+  const index = entries.findIndex((e) => e.id === id);
+  if (index <= 0) return entries;
+  const lead = entries[index] as BackendUsageSnapshot;
+  return [lead, ...entries.filter((_, i) => i !== index)];
+}

package/src/core/engine/gateway-actions/agents/control.ts

@@ -208,7 +208,8 @@ export const agentControlHandlers: SharedActionHandlers = {
       ok: true,
       text:
         `Spawned agent "${parsed.label}" (id: ${outcome.agentId})\n` +
-        `Backend: ${outcome.backendId}/${outcome.model}\n` +
+        `Backend: ${outcome.backendId}/${outcome.model}` +
+        `${outcome.routing ? ` (routed: ${outcome.routing})` : ""}\n` +
         `Timeout: ${timeoutS}s\n` +
         `It runs in the background. You will be woken with its report — ` +
         `carry on with what you were doing.`,