talon-agent 3.16.1 → 3.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.16.1",
+  "version": "3.18.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

@@ -11,6 +11,7 @@ import { startUploadCleanup, stopUploadCleanup } from "./util/workspace.js";
 import { flushDatabase } from "./storage/db.js";
 import { getActiveCount } from "./core/engine/dispatcher.js";
 import { startPulseTimer, stopPulseTimer } from "./core/background/pulse.js";
+import { stopPlanAlerts } from "./core/background/plan-alerts.js";
 import {
   startHeartbeatTimer,
   stopHeartbeatTimer,
@@ -179,6 +180,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
     await awaitHeartbeat();
   });
   await shutdownStep("cron timer", stopCronTimer);
+  await shutdownStep("plan alerts", stopPlanAlerts);
   await shutdownStep("trigger prune timer", () => {
     if (triggerPruneTimer) clearInterval(triggerPruneTimer);
     triggerPruneTimer = null;

package/src/backend/codex/factory.ts

@@ -16,7 +16,9 @@ import {
   type ChatBackend,
   type BackgroundRunner,
   type ModelCatalog,
+  type UsageTelemetry,
 } from "../../core/agent-runtime/capabilities.js";
+import { getPlanUsage as getCodexPlanUsage } from "./plan-usage.js";
 
 import { initCodexAgent, getCodexAuthInfo } from "./init.js";
 import { handleMessage as codexHandleMessage } from "./handler/index.js";
@@ -77,6 +79,12 @@ const codexFactory: BackendFactory = {
     // the per-chat thread lifecycle directly via `setSessionId` on
     // `storage/sessions.ts`. No `sessions` slot needed; `/reset`
     // clears the stored thread id through the storage path.
+    // No per-session snapshot to offer, but a ChatGPT-plan install can
+    // report its rate-limit windows.
+    const usage: UsageTelemetry = {
+      getPlanUsage: () => getCodexPlanUsage(),
+    };
+
     const backend = composeBackend({
       id: "codex",
       label: "Codex",
@@ -84,6 +92,7 @@ const codexFactory: BackendFactory = {
       chat,
       background,
       models,
+      usage,
     });
 
     return {

package/src/backend/codex/plan-usage.ts

@@ -0,0 +1,160 @@
+/**
+ * ChatGPT subscription rate-limit windows for the Codex backend.
+ *
+ * The Codex CLI reads these from an endpoint on the ChatGPT backend and
+ * caches the result in its session transcripts; `/status` renders that cache
+ * rather than re-fetching. Talon queries the endpoint directly so `/usage`
+ * reports the current state instead of whatever the last turn happened to
+ * see, using the OAuth token `codex login` already stored.
+ *
+ * Degrades to `undefined` for API-key installs (no plan to report), a
+ * missing or expired token, or any transport failure.
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { logWarn } from "../../util/log.js";
+import type {
+  PlanUsage,
+  PlanWindow,
+} from "../../core/agent-runtime/capabilities.js";
+
+const USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
+const REQUEST_TIMEOUT_MS = 5_000;
+const CACHE_TTL_MS = 60_000;
+
+let cache: { value: PlanUsage; fetchedAt: number } | undefined;
+let inFlight: Promise<PlanUsage | undefined> | undefined;
+
+function authPath(): string {
+  const home = process.env.CODEX_HOME?.trim();
+  return home && home.length > 0
+    ? join(home, "auth.json")
+    : join(homedir(), ".codex", "auth.json");
+}
+
+interface CodexAuth {
+  accessToken: string;
+  accountId?: string;
+}
+
+async function readAuth(): Promise<CodexAuth | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(authPath(), "utf8")) as {
+      auth_mode?: string;
+      tokens?: { access_token?: string; account_id?: string };
+    };
+    const token = parsed.tokens?.access_token;
+    if (!token) return undefined;
+    return {
+      accessToken: token,
+      ...(parsed.tokens?.account_id
+        ? { accountId: parsed.tokens.account_id }
+        : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+interface RawWindow {
+  used_percent?: number;
+  limit_window_seconds?: number;
+  reset_at?: number;
+}
+
+/**
+ * Window label from its length. The plan exposes a weekly window and,
+ * historically, a shorter one; naming them by duration keeps the label
+ * right whichever windows the account actually has.
+ */
+function windowLabel(seconds: number | undefined): string {
+  if (!seconds || !Number.isFinite(seconds)) return "limit";
+  const hours = Math.round(seconds / 3600);
+  if (hours % 24 === 0 && hours >= 24) return `${hours / 24}d`;
+  return `${hours}h`;
+}
+
+function toWindow(raw: RawWindow | null | undefined): PlanWindow | undefined {
+  if (!raw || typeof raw.used_percent !== "number") return undefined;
+  return {
+    label: windowLabel(raw.limit_window_seconds),
+    percent: Math.max(0, Math.min(100, Math.round(raw.used_percent))),
+    // `reset_at` is unix seconds; the shared shape speaks ISO.
+    ...(typeof raw.reset_at === "number" && raw.reset_at > 0
+      ? { resetsAt: new Date(raw.reset_at * 1000).toISOString() }
+      : {}),
+  };
+}
+
+export function parseCodexUsage(body: unknown): PlanUsage | undefined {
+  const data = body as {
+    plan_type?: string;
+    rate_limit?: {
+      primary_window?: RawWindow | null;
+      secondary_window?: RawWindow | null;
+    };
+  } | null;
+  const limit = data?.rate_limit;
+  if (!limit) return undefined;
+
+  const windows = [
+    toWindow(limit.primary_window),
+    toWindow(limit.secondary_window),
+  ].filter((w): w is PlanWindow => Boolean(w));
+  if (windows.length === 0) return undefined;
+
+  return {
+    ...(data?.plan_type ? { plan: data.plan_type } : {}),
+    windows,
+    fetchedAt: Date.now(),
+  };
+}
+
+async function load(): Promise<PlanUsage | undefined> {
+  const auth = await readAuth();
+  if (!auth) return undefined;
+
+  try {
+    const res = await fetch(USAGE_ENDPOINT, {
+      headers: {
+        Authorization: `Bearer ${auth.accessToken}`,
+        ...(auth.accountId ? { "chatgpt-account-id": auth.accountId } : {}),
+        Accept: "application/json",
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      logWarn("agent", `codex usage: endpoint returned ${res.status}`);
+      return undefined;
+    }
+    return parseCodexUsage(await res.json());
+  } catch (err) {
+    logWarn(
+      "agent",
+      `codex usage: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Plan windows for `/usage`, cached for a minute. A failed refresh keeps
+ * serving the last known values — `fetchedAt` lets the caller age them.
+ */
+export async function getPlanUsage(): Promise<PlanUsage | undefined> {
+  if (cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS) return cache.value;
+
+  inFlight ??= load().finally(() => {
+    inFlight = undefined;
+  });
+  const loaded = await inFlight;
+  if (loaded) cache = { value: loaded, fetchedAt: loaded.fetchedAt };
+  return loaded ?? cache?.value;
+}
+
+export function resetCodexPlanUsageForTest(): void {
+  cache = undefined;
+  inFlight = undefined;
+}

package/src/backend/kilo/factory.ts

@@ -69,25 +69,8 @@ const kiloFactory: BackendFactory = {
       // through to `config.backendDefaults.kilo`.
       getDefaultModelId: () => undefined,
       getRawModelInfo: (id) => kiloGetModelInfo(id),
-      getSettingsPresentation: async (m, options) => {
-        // Kilo's internal helper returns the bare picker shape;
-        // wrap into the canonical `ModelPickerResult`. Kilo doesn't
-        // expose pagination or a free-tier filter so the result is
-        // always page 1 of 1 with filter "all".
-        const inner = await kiloGetSettingsPresentation(
-          m,
-          options?.callbackPrefix,
-        );
-        return {
-          ...inner,
-          view: "models" as const,
-          page: 1,
-          totalPages: 1,
-          filter: "all" as const,
-          freeCount: 0,
-          totalCount: inner.modelButtons.length,
-        };
-      },
+      getSettingsPresentation: (m, options) =>
+        kiloGetSettingsPresentation(m, options),
       getProviders: () => kiloGetProviders(),
       getProviderModels: (p, pg, ps) => kiloGetProviderModels(p, pg, ps),
       formatModelError: (q, r) => kiloFormatModelError(q, r),

package/src/backend/opencode/factory.ts

@@ -66,21 +66,8 @@ const opencodeFactory: BackendFactory = {
       // Catalog-driven backend with no canonical default.
       getDefaultModelId: () => undefined,
       getRawModelInfo: (id) => ocGetModelInfo(id),
-      getSettingsPresentation: async (m, options) => {
-        const inner = await ocGetSettingsPresentation(
-          m,
-          options?.callbackPrefix,
-        );
-        return {
-          ...inner,
-          view: "models" as const,
-          page: 1,
-          totalPages: 1,
-          filter: "all" as const,
-          freeCount: 0,
-          totalCount: inner.modelButtons.length,
-        };
-      },
+      getSettingsPresentation: (m, options) =>
+        ocGetSettingsPresentation(m, options),
       getProviders: () => ocGetProviders(),
       getProviderModels: (p, pg, ps) => ocGetProviderModels(p, pg, ps),
       formatModelError: (q, r) => ocFormatModelError(q, r),

package/src/backend/remote-server/model-catalog/presentation.ts

@@ -35,8 +35,40 @@ export interface RemotePresentationOptions {
    * true where the transport accepts arbitrary characters (Discord).
    */
   allowCallbackSeparators: boolean;
-  /** How many quick-pick buttons to offer (Telegram 4, Discord 24). */
+  /**
+   * Default page size when the frontend doesn't ask for one — also the
+   * legacy quick-pick count (Telegram 4, Discord 24).
+   */
   quickPickLimit: number;
+  /**
+   * Flat model lists longer than this collapse into provider chips, so a
+   * catalog of several hundred models opens as a handful of providers
+   * rather than dozens of indistinguishable pages. Defaults to 60.
+   */
+  groupThreshold?: number;
+}
+
+/** Paging / filtering knobs, mirroring `ModelPickerOptions`. */
+export interface RemotePickerOptions {
+  callbackPrefix?: string;
+  navCallbackPrefix?: string;
+  page?: number;
+  pageSize?: number;
+  filter?: "all" | "free";
+  provider?: string;
+}
+
+/** What the frontend needs to render one page of the picker. */
+export interface RemotePickerResult {
+  modelButtons: Array<ModelButton>;
+  modelDetails: Array<string>;
+  view: "groups" | "models";
+  page: number;
+  totalPages: number;
+  filter: "all" | "free";
+  freeCount: number;
+  totalCount: number;
+  provider?: string;
 }
 
 function getAvailabilityLabel(model: RemoteModelCatalogEntry) {
@@ -69,8 +101,8 @@ export interface RemoteModelPresentation {
   ): Array<RemoteModelCatalogEntry>;
   getSettingsPresentation(
     activeModel: string,
-    callbackPrefix?: string,
-  ): Promise<{ modelButtons: Array<ModelButton>; modelDetails: Array<string> }>;
+    options?: RemotePickerOptions,
+  ): Promise<RemotePickerResult>;
   renderModelSummary(
     activeModel: string,
     defaultModel: string,
@@ -92,6 +124,7 @@ export function createRemoteModelPresentation(
     maxCallbackIdLength,
     allowCallbackSeparators,
     quickPickLimit,
+    groupThreshold = 60,
   } = options;
 
   function isCallbackSafeModelID(modelID: string): boolean {
@@ -140,30 +173,64 @@ export function createRemoteModelPresentation(
 
   async function getSettingsPresentation(
     activeModel: string,
-    callbackPrefix = "settings:model:",
-  ): Promise<{
-    modelButtons: Array<ModelButton>;
-    modelDetails: Array<string>;
-  }> {
+    options: RemotePickerOptions = {},
+  ): Promise<RemotePickerResult> {
+    const callbackPrefix = options.callbackPrefix ?? "settings:model:";
+    const navPrefix = options.navCallbackPrefix ?? "settings:models";
     const catalog = await getCatalog();
     const current = getRemoteModelInfo(catalog, activeModel);
-    const picks = getQuickPickModels(catalog, activeModel);
 
-    const modelButtons: Array<ModelButton> = picks.map((m) => {
-      const btnLabel =
-        m.id.length <= 20 ? m.id : m.name.length <= 20 ? m.name : m.id;
-      const txt = m.free ? `${btnLabel} ★` : btnLabel;
-      const sel =
-        current && m.id === current.id && m.providerID === current.providerID;
-      return {
-        text: sel ? `✓ ${txt}` : txt,
-        callback_data: `${callbackPrefix}${m.id}`,
-      };
-    });
-    modelButtons.push({
-      text: "Reset",
-      callback_data: `${callbackPrefix}reset`,
-    });
+    const filter = options.filter === "free" ? "free" : "all";
+    const selectable = catalog.connectedModels.filter((m) =>
+      isCallbackSafeModelID(m.id),
+    );
+    const freeCount = selectable.filter((m) => m.free).length;
+    const scoped = selectable.filter(
+      (m) =>
+        (filter === "all" || m.free) &&
+        (!options.provider || m.providerID === options.provider),
+    );
+
+    // A remote catalog can run to hundreds of models, and only the first
+    // page's worth ever fit on screen — so offer the provider list as the
+    // way in when nothing narrower was asked for and the flat list would be
+    // unreadable anyway.
+    const providers = catalog.connectedProviders;
+    const asGroups =
+      !options.provider &&
+      providers.length > 1 &&
+      scoped.length > groupThreshold;
+
+    const pageSize = Math.max(1, options.pageSize ?? quickPickLimit);
+    const source = asGroups ? providers : scoped;
+    const totalPages = Math.max(1, Math.ceil(source.length / pageSize));
+    const page = Math.min(Math.max(1, options.page ?? 1), totalPages);
+    const slice = source.slice((page - 1) * pageSize, page * pageSize);
+
+    const modelButtons: Array<ModelButton> = asGroups
+      ? (slice as typeof providers).map((p) => ({
+          text: `${p.name} (${p.modelCount})`,
+          callback_data: `${navPrefix}:provider:${p.id}`,
+        }))
+      : (slice as typeof scoped).map((m) => {
+          const btnLabel =
+            m.id.length <= 20 ? m.id : m.name.length <= 20 ? m.name : m.id;
+          const txt = m.free ? `${btnLabel} ★` : btnLabel;
+          const sel =
+            current &&
+            m.id === current.id &&
+            m.providerID === current.providerID;
+          return {
+            text: sel ? `✓ ${txt}` : txt,
+            callback_data: `${callbackPrefix}${m.id}`,
+          };
+        });
+    if (!asGroups) {
+      modelButtons.push({
+        text: "Reset",
+        callback_data: `${callbackPrefix}reset`,
+      });
+    }
 
     const details: Array<string> = [];
     if (current) {
@@ -189,7 +256,17 @@ export function createRemoteModelPresentation(
       );
     }
     details.push("Hint: use /model <name> to switch.");
-    return { modelButtons, modelDetails: details };
+    return {
+      modelButtons,
+      modelDetails: details,
+      view: asGroups ? "groups" : "models",
+      page,
+      totalPages,
+      filter,
+      freeCount,
+      totalCount: selectable.length,
+      ...(options.provider ? { provider: options.provider } : {}),
+    };
   }
 
   async function renderModelSummary(

package/src/backend/remote-server/model-catalog/provider.ts

@@ -19,6 +19,10 @@ import type {
   RemoteModelCatalogEntry,
   RemoteModelResolution,
 } from "./types.js";
+import type {
+  RemotePickerOptions,
+  RemotePickerResult,
+} from "./presentation.js";
 
 export interface RemoteModelProviderDeps {
   /** Human label — "OpenCode" / "Kilo" — used in error strings. */
@@ -36,8 +40,8 @@ export interface RemoteModelProviderDeps {
   formatUnavailableModel(model: RemoteModelCatalogEntry): string;
   getSettingsPresentation(
     activeModel: string,
-    callbackPrefix?: string,
-  ): Promise<{ modelButtons: ModelButton[]; modelDetails: string[] }>;
+    options?: RemotePickerOptions,
+  ): Promise<RemotePickerResult>;
 }
 
 export interface RemoteModelProvider {
@@ -45,8 +49,8 @@ export interface RemoteModelProvider {
   getModelInfo(id: string): Promise<UnifiedModelInfo | undefined>;
   getSettingsPresentation(
     activeModel: string,
-    callbackPrefix?: string,
-  ): Promise<{ modelButtons: ModelButton[]; modelDetails: string[] }>;
+    options?: RemotePickerOptions,
+  ): Promise<RemotePickerResult>;
   getProviders(): Promise<UnifiedProviderInfo[]>;
   getProviderModels(
     providerId: string,
@@ -118,8 +122,8 @@ export function createRemoteModelProvider(
       return entry ? toUnifiedModelInfo(entry) : undefined;
     },
 
-    getSettingsPresentation(activeModel, callbackPrefix = "settings:model:") {
-      return deps.getSettingsPresentation(activeModel, callbackPrefix);
+    getSettingsPresentation(activeModel, options) {
+      return deps.getSettingsPresentation(activeModel, options);
     },
 
     async getProviders() {

package/src/bootstrap.ts

@@ -26,6 +26,7 @@ import { bus } from "./core/bus/index.js";
 import { appendToJournal } from "./storage/journal.js";
 import { initPulse, resetPulseTimer } from "./core/background/pulse.js";
 import { initCron } from "./core/background/cron.js";
+import { initPlanAlerts } from "./core/background/plan-alerts.js";
 import {
   initTriggers,
   resumeAfterRestart as resumeTriggersAfterRestart,
@@ -420,6 +421,19 @@ export async function initBackendAndDispatcher(
     log("triggers", `resumeAfterRestart failed: ${err}`),
   );
 
+  initPlanAlerts({
+    sendMessage: async (chatId: number, text: string, stringId?: string) =>
+      resolveFrontendByNumericId(chatId, stringId, frontends).sendMessage(
+        chatId,
+        text,
+      ),
+    enabled: config.planAlerts,
+    threshold: config.planAlertThreshold,
+    chatId:
+      config.planAlertChatId ??
+      (config.adminUserId ? String(config.adminUserId) : undefined),
+  });
+
   // Soul — initialize the identity kernel singleton from config so the prompt
   // injection / dream hooks see the right enabled state. Off by default; a
   // failure here must never block startup.

package/src/cli/doctor.ts

@@ -25,9 +25,19 @@ export async function runDoctor(): Promise<void> {
     config: hasConfigFile ? loadConfig() : undefined,
     hasConfigFile,
   });
-  for (const check of report.checks) {
+  const print = (check: (typeof report.checks)[number]): void => {
     const detail = check.detail ? ` ${pc.dim(`(${check.detail})`)}` : "";
     console.log(`  ${DOCTOR_ICONS[check.status]} ${check.label}${detail}`);
+  };
+  for (const check of report.checks.filter((c) => !c.inactive)) print(check);
+
+  // Configured-but-idle backends 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) {
+    console.log(`\n  ${pc.bold("Other backends")}\n`);
+    for (const check of idle) print(check);
+    console.log();
   }
   // Native plane, one line per embedded module with provenance.
   for (const mod of report.native) {

package/src/core/background/plan-alerts.ts

@@ -0,0 +1,115 @@
+/**
+ * Plan rate-limit warnings.
+ *
+ * Off unless `planAlerts` is enabled. Polls the subscription's windows on a
+ * timer and messages the admin chat the first time one crosses the
+ * threshold, so a long background run doesn't walk into the ceiling
+ * unannounced.
+ *
+ * One message per window per reset cycle: the reset timestamp identifies the
+ * cycle, and a window that drops back under the threshold re-arms (which is
+ * also what covers windows the plan reports no reset for).
+ */
+
+import { getPooledBackend } from "../engine/backend-controller/index.js";
+import { log, logWarn } from "../../util/log.js";
+import { formatSmartTimestamp } from "../../util/time.js";
+
+const CHECK_INTERVAL_MS = 5 * 60_000;
+
+export interface PlanAlertDeps {
+  sendMessage: (
+    chatId: number,
+    text: string,
+    stringId?: string,
+  ) => Promise<void>;
+  enabled: boolean;
+  threshold: number;
+  /** Chat the warnings go to. Callers resolve the admin default. */
+  chatId: string | undefined;
+}
+
+let deps: PlanAlertDeps | undefined;
+let timer: ReturnType<typeof setInterval> | null = null;
+
+/** Window label → the reset cycle it was last warned about. */
+const warned = new Map<string, string>();
+
+export function initPlanAlerts(d: PlanAlertDeps): void {
+  deps = d;
+  stopPlanAlerts();
+  warned.clear();
+  if (!d.enabled) return;
+  if (!d.chatId) {
+    logWarn(
+      "bot",
+      "planAlerts is on but no chat to warn — set planAlertChatId or adminUserId",
+    );
+    return;
+  }
+  timer = setInterval(() => {
+    void checkPlanAlerts();
+  }, CHECK_INTERVAL_MS);
+  timer.unref?.();
+  log("bot", `Plan alerts: on (threshold ${d.threshold}%)`);
+}
+
+export function stopPlanAlerts(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+}
+
+function warningText(
+  label: string,
+  percent: number,
+  resetsAt: string | undefined,
+): string {
+  const ts = resetsAt ? Date.parse(resetsAt) : NaN;
+  const reset = Number.isFinite(ts)
+    ? `, resets ${formatSmartTimestamp(Math.round(ts / 60_000) * 60_000)}`
+    : "";
+  return `⚠️ Plan limit — ${label} at ${percent}% used${reset}.`;
+}
+
+/** One pass. Exported so the timer isn't the only way to drive it. */
+export async function checkPlanAlerts(): Promise<void> {
+  const d = deps;
+  if (!d?.enabled || !d.chatId) return;
+
+  const usage = await getPooledBackend("claude")
+    ?.usage?.getPlanUsage?.()
+    .catch(() => undefined);
+  if (!usage) return;
+
+  for (const window of usage.windows) {
+    // An unwarned window that is back under the threshold re-arms.
+    if (window.percent < d.threshold) {
+      warned.delete(window.label);
+      continue;
+    }
+    const cycle = window.resetsAt ?? "";
+    if (warned.get(window.label) === cycle) continue;
+    warned.set(window.label, cycle);
+
+    const text = warningText(window.label, window.percent, window.resetsAt);
+    try {
+      await d.sendMessage(Number(d.chatId), text, d.chatId);
+      log("bot", `Plan alert sent: ${window.label} at ${window.percent}%`);
+    } catch (err) {
+      // Keep it marked as warned — a frontend that can't deliver now won't
+      // deliver on the next tick either, and retrying would spam on recovery.
+      logWarn(
+        "bot",
+        `Plan alert delivery failed: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
+export function resetPlanAlertsForTest(): void {
+  stopPlanAlerts();
+  deps = undefined;
+  warned.clear();
+}