talon-agent 5.10.0 → 5.12.0

package/README.md

@@ -508,6 +508,33 @@ Config file: `~/.talon/config.json`
 | `memory`                   | ---          | Long-term memory backend selection: `mempalace` or `mem0` (see above)                                                   |
 | `mempalace`                | ---          | Legacy MemPalace plugin config (prefer `memory`)                                                                        |
 | `playwright`               | ---          | Playwright plugin config (see above)                                                                                    |
+| `triggers`                 | ---          | Per-chat trigger caps, e.g. `{ "maxActivePerChat": 5, "maxPersistentPerChat": 3 }` ([Scaling limits](#scaling-limits)) |
+| `agents`                   | ---          | Sub-agent caps: `{ "maxConcurrent": 6, "maxDepth": 2, "defaultTimeoutMs": 900000 }` ([docs/agents.md](docs/agents.md)) |
+
+### Scaling limits
+
+Two caps bound how much background work Talon keeps alive. Both keep their
+historical defaults and are raised in `~/.talon/config.json`; the error a
+capped tool returns names the key to raise.
+
+| Key                             | Default | Bounds | What it caps                                                 |
+| ------------------------------- | ------- | ------ | ------------------------------------------------------------ |
+| `triggers.maxActivePerChat`     | `5`     | 1–50   | Active (running or pending) triggers per chat                |
+| `triggers.maxPersistentPerChat` | unset   | 1–50   | Optional separate budget for persistent triggers (see below) |
+| `agents.maxConcurrent`          | `6`     | 1–64   | Live sub-agents daemon-wide, children included               |
+
+With `maxPersistentPerChat` unset, persistent and ad-hoc triggers share
+`maxActivePerChat`, exactly as before. Set it and the two draw from separate
+budgets: persistent triggers count only against `maxPersistentPerChat`, and
+`maxActivePerChat` then bounds ad-hoc (non-persistent) triggers only — so a
+chat running long-lived watchers still has room for a short CI wait. Caps are
+checked at `trigger_create`; lowering one never kills a trigger already
+running, and persistent triggers resumed after a restart are not re-checked.
+
+```json
+"triggers": { "maxActivePerChat": 5, "maxPersistentPerChat": 6 },
+"agents": { "maxConcurrent": 12 }
+```
 
 ### Background reasoning effort
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.10.0",
+  "version": "5.12.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/app.ts

@@ -6,7 +6,7 @@
  * are loaded dynamically — only the selected platform's dependencies are required.
  */
 
-import { getFrontends } from "./core/config/index.js";
+import { ConfigFileError, getFrontends } from "./core/config/index.js";
 import { startUploadCleanup, stopUploadCleanup } from "./core/vfs/workspace.js";
 import { flushDatabase } from "./storage/db.js";
 import { getActiveCount, stopAllTurns } from "./core/engine/dispatcher.js";
@@ -40,6 +40,7 @@ import {
   crashCleanup,
   crashStep,
   handleUncaughtException,
+  handleUnhandledRejection,
 } from "./core/daemon/crash.js";
 import { log, logError, logWarn } from "./util/log.js";
 import { bootPhase, bootReport } from "./core/daemon/boot-timer.js";
@@ -119,9 +120,31 @@ async function applyStagedRestore(): Promise<string | null> {
   );
 }
 
-const restoreReport = await bootPhase("staged restore", applyStagedRestore);
+/**
+ * A present-but-invalid config.json is fatal at startup: print the file
+ * path and every problem, then exit non-zero. Booting on defaults instead
+ * would put the daemon in a surprising state (wrong frontend, no plugins).
+ */
+async function withConfigGuard<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof ConfigFileError) {
+      logError("config", err.message);
+      console.error(`talon: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+const restoreReport = await withConfigGuard(() =>
+  bootPhase("staged restore", applyStagedRestore),
+);
 
-const { config } = await bootPhase("bootstrap", () => bootstrap());
+const { config } = await withConfigGuard(() =>
+  bootPhase("bootstrap", () => bootstrap()),
+);
 
 // Record this process as the daemon. The gateway port is appended once
 // the gateway binds (it may fall back from the default on EADDRINUSE).
@@ -361,12 +384,7 @@ process.on("uncaughtException", (err) =>
   handleUncaughtException(err, crashHooks),
 );
 
-process.on("unhandledRejection", (reason) => {
-  logWarn(
-    "bot",
-    `Unhandled rejection: ${reason instanceof Error ? reason.message : reason}`,
-  );
-});
+process.on("unhandledRejection", handleUnhandledRejection);
 
 // ── Start ────────────────────────────────────────────────────────────────────
 

package/src/backend/claude-sdk/factory.ts

@@ -30,6 +30,7 @@ import {
   evictOrphanSubprocesses as claudeEvictOrphanSubprocesses,
 } from "./index.js";
 import { createInProcessAgentHost } from "./host/in-process.js";
+import { claimBankedReset, getBankedResetOffer } from "./usage/banked-reset.js";
 
 import * as modelProvider from "./model-provider.js";
 import { claudeDoctorChecks } from "./doctor.js";
@@ -105,6 +106,10 @@ const claudeSdkFactory: BackendFactory = {
     // but the subscription's rate-limit windows are readable.
     const usage: UsageTelemetry = {
       getPlanUsage: () => host.planUsage(),
+      bankedResets: {
+        getOffer: () => getBankedResetOffer(),
+        claim: (grantId, requestId) => claimBankedReset(grantId, requestId),
+      },
     };
 
     const backend = composeBackend({

package/src/backend/claude-sdk/handler.ts

@@ -38,7 +38,7 @@ import { applyRetryDecisionStream } from "../runtime/turn/handle-retry.js";
 import { getConfig } from "./state.js";
 import { buildSdkOptions, getActiveFrontends } from "./options.js";
 import { waitForMcpServersReady } from "./mcp-ready.js";
-import { invalidatePlanUsage } from "./plan-usage.js";
+import { invalidatePlanUsage } from "./usage/plan-usage.js";
 import { frontendsForChat } from "../runtime/frontends.js";
 import { rollUpTurnCache } from "../runtime/cache/cache-metrics.js";
 import {

package/src/backend/claude-sdk/host/in-process.ts

@@ -39,7 +39,7 @@ import {
 } from "../handler.js";
 import { waitForMcpServersReady } from "../mcp-ready.js";
 import { listModels as claudeListModels } from "../model-provider.js";
-import { getPlanUsage } from "../plan-usage.js";
+import { getPlanUsage } from "../usage/plan-usage.js";
 
 /**
  * Install an MCP server set on the chat's live query. `null` when the

package/src/backend/claude-sdk/usage/banked-reset.ts

@@ -0,0 +1,304 @@
+/**
+ * Spending a banked Claude usage-limit reset (the claude.ai "Reset for free"
+ * grants, program `cedar_ember`).
+ *
+ * The same OAuth usage endpoint `/usage` reads lists the grants; a claim is a
+ * POST to the organization's `reset_rate_limits` route, the one Claude Code's
+ * own `/limit-reset` uses. The request and response shapes mirror the CLI:
+ *
+ *   POST /api/organizations/<org>/reset_rate_limits
+ *   { program: "cedar_ember", grant_id, request_id }
+ *   → { result, reason?, resets_left?, cleared?, weekly_resets_at?, cooldown_until? }
+ *
+ * `request_id` is an idempotency key. A retry of the same user action must
+ * reuse it, so a claim whose answer was lost can't spend a second reset.
+ *
+ * A reset is one-off and irreversible. Nothing here is reachable from an
+ * agent tool; the only caller is a confirm button a human presses.
+ */
+
+import { randomUUID } from "node:crypto";
+import { logWarn } from "../../../util/log.js";
+import type {
+  BankedResetClaim,
+  BankedResetGrant,
+  BankedResetOffer,
+  BankedResetResult,
+} from "../../../core/agent-runtime/capabilities.js";
+import {
+  CLI_USER_AGENT,
+  USAGE_ENDPOINT,
+  invalidatePlanUsage,
+  readCredentials,
+} from "./plan-usage.js";
+
+const API_BASE = "https://api.anthropic.com";
+const PROFILE_ENDPOINT = `${API_BASE}/api/oauth/profile`;
+const PROGRAM = "cedar_ember";
+const READ_TIMEOUT_MS = 5_000;
+// The CLI allows a claim 25s; the server may do real work before answering.
+const CLAIM_TIMEOUT_MS = 25_000;
+
+// Same patterns the CLI enforces before it will send a claim.
+const GRANT_ID = /^[a-z0-9_-]{1,40}$/;
+const REQUEST_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const ORG_ID = /^[A-Za-z0-9-]{1,64}$/;
+
+const SERVER_RESULTS: ReadonlySet<string> = new Set([
+  "reset",
+  "already_used",
+  "not_limited",
+  "cooldown",
+  "ineligible",
+  "unavailable",
+]);
+
+export function isValidGrantId(id: string): boolean {
+  return GRANT_ID.test(id);
+}
+
+export function isValidRequestId(id: string): boolean {
+  return REQUEST_ID.test(id);
+}
+
+/** A fresh idempotency key for one user action. */
+export function newResetRequestId(): string {
+  return randomUUID().replace(/-/g, "");
+}
+
+export interface ResetStatus {
+  atLimit: boolean;
+  cooldownUntil?: string;
+  nextGrantId?: string;
+  grants: Array<BankedResetGrant & { paused: boolean; usableNow: boolean }>;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function strings(v: unknown): string[] {
+  return Array.isArray(v)
+    ? v.filter((x): x is string => typeof x === "string")
+    : [];
+}
+
+function percents(v: unknown): Record<string, number> {
+  const out: Record<string, number> = {};
+  if (!v || typeof v !== "object") return out;
+  for (const [k, p] of Object.entries(v as Record<string, unknown>)) {
+    if (typeof p === "number" && Number.isFinite(p))
+      out[k] = Math.max(0, Math.min(100, Math.round(p)));
+  }
+  return out;
+}
+
+/** The `cedar_ember` block of a usage response, or undefined without one. */
+export function parseResetStatus(body: unknown): ResetStatus | undefined {
+  const raw = (body as { cedar_ember?: unknown } | null)?.cedar_ember as
+    Record<string, unknown> | null | undefined;
+  if (!raw || typeof raw !== "object" || raw.eligible === false)
+    return undefined;
+  const grants: ResetStatus["grants"] = [];
+  for (const g of Array.isArray(raw.grants) ? raw.grants : []) {
+    if (!g || typeof g !== "object") continue;
+    const r = g as Record<string, unknown>;
+    const id = str(r.id);
+    // A malformed id is one the CLI would refuse to claim; skip it here too.
+    if (!id || !isValidGrantId(id)) continue;
+    const left = r.resets_left;
+    const endsAt = str(r.ends_at);
+    grants.push({
+      id,
+      label: str(r.label) ?? id,
+      resetsLeft:
+        typeof left === "number" && Number.isFinite(left)
+          ? Math.max(0, Math.floor(left))
+          : 0,
+      ...(endsAt ? { endsAt } : {}),
+      clears: strings(r.clears),
+      percentUsed: percents(r.percent_used),
+      // The CLI defaults an absent flag to the cautious reading.
+      useRequiresLimit: r.use_requires_limit !== false,
+      paused: r.paused === true,
+      usableNow: r.usable_now === true,
+    });
+  }
+  const cooldownUntil = str(raw.cooldown_until);
+  const nextGrantId = str(raw.next_grant_id);
+  return {
+    atLimit: raw.at_limit === true,
+    ...(cooldownUntil ? { cooldownUntil } : {}),
+    ...(nextGrantId ? { nextGrantId } : {}),
+    grants,
+  };
+}
+
+function usable(grant: ResetStatus["grants"][number], now: number): boolean {
+  if (!grant.usableNow || grant.paused || grant.resetsLeft <= 0) return false;
+  const ends = grant.endsAt ? Date.parse(grant.endsAt) : NaN;
+  return !(Number.isFinite(ends) && ends <= now);
+}
+
+/**
+ * The grant a claim should spend: the server's `next_grant_id` when that
+ * grant is usable, else the usable grant that expires soonest (a grant with
+ * no deadline goes last).
+ */
+export function pickGrant(
+  status: ResetStatus,
+  now = Date.now(),
+): ResetStatus["grants"][number] | undefined {
+  const candidates = status.grants.filter((g) => usable(g, now));
+  const next = candidates.find((g) => g.id === status.nextGrantId);
+  if (next) return next;
+  const deadline = (g: { endsAt?: string }) => {
+    const t = g.endsAt ? Date.parse(g.endsAt) : NaN;
+    return Number.isFinite(t) ? t : Infinity;
+  };
+  return candidates.sort((a, b) => deadline(a) - deadline(b))[0];
+}
+
+function authHeaders(token: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${token}`,
+    "anthropic-beta": "oauth-2025-04-20",
+    "User-Agent": CLI_USER_AGENT,
+  };
+}
+
+async function oauthToken(): Promise<string | undefined> {
+  // An API-key session isn't on the subscription whose resets these are.
+  if (process.env.ANTHROPIC_API_KEY) return undefined;
+  return (await readCredentials())?.accessToken;
+}
+
+/** What a claim would spend right now, or undefined when there's nothing. */
+export async function getBankedResetOffer(
+  now = Date.now(),
+): Promise<BankedResetOffer | undefined> {
+  const token = await oauthToken();
+  if (!token) return undefined;
+  try {
+    const res = await fetch(USAGE_ENDPOINT, {
+      headers: authHeaders(token),
+      signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      logWarn("agent", `banked resets: usage returned ${res.status}`);
+      return undefined;
+    }
+    const status = parseResetStatus(await res.json());
+    if (!status) return undefined;
+    const grant = pickGrant(status, now);
+    if (!grant) return undefined;
+    const { paused: _p, usableNow: _u, ...clean } = grant;
+    const totalResetsLeft = status.grants
+      .filter((g) => usable(g, now))
+      .reduce((n, g) => n + g.resetsLeft, 0);
+    return {
+      grant: clean,
+      atLimit: status.atLimit,
+      ...(status.cooldownUntil ? { cooldownUntil: status.cooldownUntil } : {}),
+      totalResetsLeft,
+    };
+  } catch (err) {
+    logWarn(
+      "agent",
+      `banked resets: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+async function organizationId(token: string): Promise<string | undefined> {
+  const res = await fetch(PROFILE_ENDPOINT, {
+    headers: authHeaders(token),
+    signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+  });
+  if (!res.ok) return undefined;
+  const body = (await res.json()) as { organization?: { uuid?: unknown } };
+  const id = body?.organization?.uuid;
+  return typeof id === "string" && ORG_ID.test(id) ? id : undefined;
+}
+
+const failed = (result: BankedResetResult): BankedResetClaim => ({
+  result,
+  cleared: [],
+});
+
+/** Map a claim response body onto a result; unknown results read as unavailable. */
+export function parseClaimResponse(body: unknown): BankedResetClaim {
+  const r = (body && typeof body === "object" ? body : {}) as Record<
+    string,
+    unknown
+  >;
+  const result =
+    typeof r.result === "string" && SERVER_RESULTS.has(r.result)
+      ? (r.result as BankedResetResult)
+      : "unavailable";
+  const reason = str(r.reason);
+  const left = r.resets_left;
+  const weeklyResetsAt = str(r.weekly_resets_at);
+  const cooldownUntil = str(r.cooldown_until);
+  return {
+    result,
+    ...(reason ? { reason } : {}),
+    ...(typeof left === "number" && Number.isInteger(left) && left >= 0
+      ? { resetsLeft: left }
+      : {}),
+    cleared: strings(r.cleared),
+    ...(weeklyResetsAt ? { weeklyResetsAt } : {}),
+    ...(cooldownUntil ? { cooldownUntil } : {}),
+  };
+}
+
+/**
+ * Spend one reset from `grantId`. Never throws: every failure comes back as
+ * a result the caller can put into words.
+ */
+export async function claimBankedReset(
+  grantId: string,
+  requestId: string = newResetRequestId(),
+): Promise<BankedResetClaim> {
+  if (!isValidGrantId(grantId) || !isValidRequestId(requestId)) {
+    logWarn("agent", "banked resets: refusing a malformed grant or request id");
+    return failed("error");
+  }
+  const token = await oauthToken();
+  if (!token) return failed("auth_error");
+
+  try {
+    const org = await organizationId(token);
+    if (!org) return failed("auth_error");
+    const res = await fetch(
+      `${API_BASE}/api/organizations/${org}/reset_rate_limits`,
+      {
+        method: "POST",
+        headers: { ...authHeaders(token), "Content-Type": "application/json" },
+        body: JSON.stringify({
+          program: PROGRAM,
+          grant_id: grantId,
+          request_id: requestId,
+        }),
+        signal: AbortSignal.timeout(CLAIM_TIMEOUT_MS),
+      },
+    );
+    if (res.status === 429) return failed("rate_limited");
+    if (res.status === 401 || res.status === 403) return failed("auth_error");
+    if (!res.ok) {
+      logWarn("agent", `banked resets: claim returned ${res.status}`);
+      return failed("error");
+    }
+    const claim = parseClaimResponse(await res.json().catch(() => null));
+    // Any settled answer changes what /usage should say; re-read next time.
+    if (claim.result !== "unavailable") invalidatePlanUsage();
+    return claim;
+  } catch (err) {
+    logWarn(
+      "agent",
+      `banked resets: claim failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return failed("error");
+  }
+}

package/src/backend/claude-sdk/{plan-usage.ts → usage/plan-usage.ts}

@@ -15,13 +15,20 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { logWarn } from "../../util/log.js";
+import { logWarn } from "../../../util/log.js";
 import type {
   PlanUsage,
   PlanWindow,
-} from "../../core/agent-runtime/capabilities.js";
-
-const USAGE_ENDPOINT = "https://api.anthropic.com/api/oauth/usage";
+} from "../../../core/agent-runtime/capabilities.js";
+
+// `cedar_ember=1` asks the endpoint to include banked limit resets (the
+// claude.ai "Reset for free" grants); `skip_spend=1` drops the spend block we
+// don't render. Resets are only reported to the CLI surface — any other
+// user agent gets `ineligible_reason: "surface"` — so the request identifies
+// as the CLI, which is what the Agent SDK runs anyway.
+export const USAGE_ENDPOINT =
+  "https://api.anthropic.com/api/oauth/usage?cedar_ember=1&skip_spend=1";
+export const CLI_USER_AGENT = "claude-cli/2.1.280 (external, cli)";
 const REQUEST_TIMEOUT_MS = 5_000;
 const CACHE_TTL_MS = 60_000;
 
@@ -41,7 +48,7 @@ interface OAuthCredentials {
   subscriptionType?: string;
 }
 
-async function readCredentials(): Promise<OAuthCredentials | undefined> {
+export async function readCredentials(): Promise<OAuthCredentials | undefined> {
   try {
     const parsed = JSON.parse(await readFile(credentialsPath(), "utf8")) as {
       claudeAiOauth?: OAuthCredentials;
@@ -77,6 +84,48 @@ function windowLabel(limit: RawLimit): string | undefined {
   return undefined;
 }
 
+interface RawResetGrant {
+  resets_left?: number;
+  ends_at?: string | null;
+  paused?: boolean;
+}
+
+/**
+ * Banked limit resets still usable: unpaused grants whose window hasn't
+ * closed. Returns the count and the soonest deadline among grants that still
+ * hold a reset, or undefined when there's nothing to offer.
+ */
+export function parseBankedResets(
+  body: unknown,
+  now = Date.now(),
+): { count: number; expiresAt?: string } | undefined {
+  const program = (body as { cedar_ember?: unknown } | null)?.cedar_ember as
+    { eligible?: boolean; grants?: unknown } | null | undefined;
+  if (!program || program.eligible === false || !Array.isArray(program.grants))
+    return undefined;
+
+  let count = 0;
+  let expiresAt: string | undefined;
+  for (const grant of program.grants as RawResetGrant[]) {
+    const left = grant.resets_left;
+    if (typeof left !== "number" || !Number.isFinite(left) || left <= 0)
+      continue;
+    if (grant.paused === true) continue;
+    const ends =
+      typeof grant.ends_at === "string" ? Date.parse(grant.ends_at) : NaN;
+    if (Number.isFinite(ends) && ends <= now) continue;
+    count += Math.floor(left);
+    if (
+      typeof grant.ends_at === "string" &&
+      Number.isFinite(ends) &&
+      (!expiresAt || ends < Date.parse(expiresAt))
+    )
+      expiresAt = grant.ends_at;
+  }
+  if (count <= 0) return undefined;
+  return { count, ...(expiresAt ? { expiresAt } : {}) };
+}
+
 export function parsePlanUsage(
   body: unknown,
   subscriptionType?: string,
@@ -103,9 +152,16 @@ export function parsePlanUsage(
   }
 
   if (windows.length === 0) return undefined;
+  const banked = parseBankedResets(body);
   return {
     ...(subscriptionType ? { plan: subscriptionType } : {}),
     windows,
+    ...(banked
+      ? {
+          resetsAvailable: banked.count,
+          ...(banked.expiresAt ? { resetsExpireAt: banked.expiresAt } : {}),
+        }
+      : {}),
     fetchedAt: Date.now(),
   };
 }
@@ -119,6 +175,7 @@ async function load(): Promise<PlanUsage | undefined> {
       headers: {
         Authorization: `Bearer ${creds.accessToken}`,
         "anthropic-beta": "oauth-2025-04-20",
+        "User-Agent": CLI_USER_AGENT,
       },
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     });

package/src/bootstrap.ts

@@ -607,7 +607,10 @@ function initRecurringAgents(
  * same delivery shape, so they are wired together.
  */
 function initWakeSubsystems(config: TalonConfig): void {
-  initTriggers({ execute: dispatcherExecute });
+  initTriggers({
+    execute: dispatcherExecute,
+    ...(config.triggers ? { caps: config.triggers } : {}),
+  });
   initAgents({
     execute: dispatcherExecute,
     ...(config.agents ? { caps: config.agents } : {}),