talon-agent 3.15.2 → 3.16.0

package/package.json

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

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

@@ -22,7 +22,9 @@ import {
   type SessionBackend,
   type SystemControl,
   type ToolRuntime,
+  type UsageTelemetry,
 } from "../../core/agent-runtime/capabilities.js";
+import { getPlanUsage } from "./plan-usage.js";
 
 import {
   initAgent as initClaudeAgent,
@@ -117,6 +119,12 @@ const claudeSdkFactory: BackendFactory = {
       updateSystemPrompt: (prompt) => claudeUpdateSystemPrompt(prompt),
     };
 
+    // No per-session snapshot to offer (each turn is a fresh subprocess),
+    // but the subscription's rate-limit windows are readable.
+    const usage: UsageTelemetry = {
+      getPlanUsage: () => getPlanUsage(),
+    };
+
     const backend = composeBackend({
       id: "claude",
       label: "Anthropic",
@@ -126,6 +134,7 @@ const claudeSdkFactory: BackendFactory = {
       models,
       sessions,
       tools,
+      usage,
       control,
     });
 

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

@@ -36,6 +36,7 @@ import { applyRetryDecisionStream } from "../shared/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 { frontendsForChat } from "../shared/frontends.js";
 import {
   createStreamState,
@@ -43,6 +44,7 @@ import {
   isStreamEvent,
   isAssistant,
   isResult,
+  isRateLimitEvent,
   isUserMessage,
   extractToolResults,
   processStreamDelta,
@@ -384,6 +386,14 @@ export async function* runChatTurn(
         continue;
       }
 
+      // The turn just moved the plan's usage — drop the cached windows so
+      // the next /status reads them again instead of showing pre-turn
+      // figures.
+      if (isRateLimitEvent(message)) {
+        invalidatePlanUsage();
+        continue;
+      }
+
       if (isResult(message)) {
         processResultMessage(message, state, options.model ?? activeModel);
         armPostResultWatchdog();
@@ -515,6 +525,7 @@ export async function* runChatTurn(
     contextTokens: state.contextTokens,
     contextWindow: state.contextWindow,
     numApiCalls: state.numApiCalls,
+    costUsd: state.costUsd,
   });
 
   // Set a descriptive session name from the first message.

package/src/backend/claude-sdk/plan-usage.ts

@@ -0,0 +1,170 @@
+/**
+ * Claude.ai subscription rate-limit windows for /status.
+ *
+ * The 5-hour, weekly, and per-model utilisation percentages come from the
+ * same OAuth endpoint Claude Code's own usage panel reads. The Agent SDK
+ * also exposes them through a control request, but that path additionally
+ * builds a local-session behaviour report and costs seconds per call; the
+ * endpoint alone answers in well under a second.
+ *
+ * Everything degrades to `undefined`: no credentials, an API-key session
+ * (plan limits don't apply), or any transport failure. /status hides the
+ * section rather than rendering zeroes.
+ */
+
+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://api.anthropic.com/api/oauth/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 credentialsPath(): string {
+  const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
+  return join(
+    configDir && configDir.length > 0 ? configDir : join(homedir(), ".claude"),
+    ".credentials.json",
+  );
+}
+
+interface OAuthCredentials {
+  accessToken?: string;
+  subscriptionType?: string;
+}
+
+async function readCredentials(): Promise<OAuthCredentials | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(credentialsPath(), "utf8")) as {
+      claudeAiOauth?: OAuthCredentials;
+    };
+    const oauth = parsed.claudeAiOauth;
+    return oauth?.accessToken ? oauth : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+interface RawLimit {
+  kind?: string;
+  percent?: number;
+  resets_at?: string | null;
+  scope?: { model?: { display_name?: string | null } | null } | null;
+}
+
+/**
+ * Short display label for one window, or undefined to skip the row.
+ *
+ * Only the three documented kinds are rendered. The response also carries
+ * internal codenamed windows; skipping unknown kinds keeps those out of the
+ * user-facing panel.
+ */
+function windowLabel(limit: RawLimit): string | undefined {
+  if (limit.kind === "session") return "5h";
+  if (limit.kind === "weekly_all") return "7d";
+  if (limit.kind === "weekly_scoped") {
+    const model = limit.scope?.model?.display_name?.trim();
+    return model && model.length > 0 ? model : undefined;
+  }
+  return undefined;
+}
+
+export function parsePlanUsage(
+  body: unknown,
+  subscriptionType?: string,
+): PlanUsage | undefined {
+  const limits = (body as { limits?: unknown } | null)?.limits;
+  if (!Array.isArray(limits)) return undefined;
+
+  const windows: PlanWindow[] = [];
+  for (const limit of limits as RawLimit[]) {
+    const label = windowLabel(limit);
+    if (!label) continue;
+    const raw = limit.percent;
+    const percent =
+      typeof raw === "number" && Number.isFinite(raw)
+        ? Math.max(0, Math.min(100, Math.round(raw)))
+        : 0;
+    windows.push({
+      label,
+      percent,
+      ...(typeof limit.resets_at === "string"
+        ? { resetsAt: limit.resets_at }
+        : {}),
+    });
+  }
+
+  if (windows.length === 0) return undefined;
+  return {
+    ...(subscriptionType ? { plan: subscriptionType } : {}),
+    windows,
+    fetchedAt: Date.now(),
+  };
+}
+
+async function load(): Promise<PlanUsage | undefined> {
+  const creds = await readCredentials();
+  if (!creds?.accessToken) return undefined;
+
+  try {
+    const res = await fetch(USAGE_ENDPOINT, {
+      headers: {
+        Authorization: `Bearer ${creds.accessToken}`,
+        "anthropic-beta": "oauth-2025-04-20",
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      logWarn("agent", `plan usage: endpoint returned ${res.status}`);
+      return undefined;
+    }
+    return parsePlanUsage(await res.json(), creds.subscriptionType);
+  } catch (err) {
+    logWarn(
+      "agent",
+      `plan usage: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Plan windows for /status, cached for a minute so a burst of commands
+ * makes one request. A failed refresh falls back to the last known values
+ * — `fetchedAt` lets the caller age them.
+ */
+export async function getPlanUsage(): Promise<PlanUsage | undefined> {
+  // An API-key session bills against the key, not the subscription, so the
+  // stored OAuth credentials would describe limits that don't apply here.
+  if (process.env.ANTHROPIC_API_KEY) return 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;
+}
+
+/**
+ * Expire the cache after the SDK reports a rate-limit change, so the next
+ * /status re-reads instead of showing figures from before the turn.
+ */
+export function invalidatePlanUsage(): void {
+  if (cache) cache.fetchedAt = 0;
+}
+
+export function resetPlanUsageForTest(): void {
+  cache = undefined;
+  inFlight = undefined;
+}

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

@@ -39,6 +39,8 @@ export type StreamState = {
   sdkOutputTokens: number;
   sdkCacheRead: number;
   sdkCacheWrite: number;
+  /** Cost of this turn in USD, as reported by the result message. */
+  costUsd: number;
   /**
    * Per-turn cache behaviour derived from the result message's per-request
    * `usage.iterations`. Undefined when the provider reported none — the
@@ -113,6 +115,7 @@ export function createStreamState(): StreamState {
     sdkOutputTokens: 0,
     sdkCacheRead: 0,
     sdkCacheWrite: 0,
+    costUsd: 0,
     cacheStats: undefined,
     lastStreamUpdate: 0,
     lastTrailingText: "",
@@ -148,6 +151,11 @@ export function isResult(msg: SDKMessage): msg is SDKResultMessage {
   return msg.type === "result";
 }
 
+/** Emitted when the subscription's rate-limit state changes mid-turn. */
+export function isRateLimitEvent(msg: SDKMessage): boolean {
+  return msg.type === "rate_limit_event";
+}
+
 // ── Message processors ──────────────────────────────────────────────────────
 
 /** Output of `processStreamDelta` when the throttle interval has elapsed. */
@@ -337,6 +345,11 @@ export function processResultMessage(
 ): void {
   state.numApiCalls = msg.num_turns ?? 0;
 
+  // Per-turn, not cumulative across a resumed session — safe to add up.
+  if (typeof msg.total_cost_usd === "number" && msg.total_cost_usd > 0) {
+    state.costUsd = msg.total_cost_usd;
+  }
+
   // Context fill from last API iteration
   const usage = msg.usage;
   if (usage && Array.isArray(usage.iterations) && usage.iterations.length > 0) {

package/src/backend/remote-server/events.ts

@@ -28,6 +28,7 @@
 import {
   appendText,
   closeCurrentSegment,
+  markProgressDelivered,
   recordTokens,
   recordToolUse,
   recordToolCall,
@@ -279,6 +280,10 @@ async function processPartUpdate(
   if (progress && ctx.onTextBlock) {
     try {
       await ctx.onTextBlock(progress);
+      // Only now is this text actually with the user. `closeCurrentSegment`
+      // folded it into `allResponseText`, so without this the end-of-turn
+      // delivery would ship it a second time inside the full transcript.
+      markProgressDelivered(ctx.state);
     } catch (err) {
       // Non-fatal — never break the stream loop on a UI callback. Logged
       // at debug level so a repeatedly-failing frontend is visible to

package/src/backend/shared/delivery.ts

@@ -1,7 +1,7 @@
 /**
  * Unified delivery routing for the remote-server backend family.
  *
- * Both OpenCode and Kilo can reach the user through one of four paths
+ * Both OpenCode and Kilo can reach the user through one of several paths
  * after a turn completes. The decision tree below is identical between
  * them, so it lives here as a shared helper instead of being duplicated
  * in each handler.
@@ -19,7 +19,12 @@
  *     marker, or analogous failure path). Surface as a Talon error
  *     instead of shipping the raw upstream string as a reply.
  *   - `text-part` — model emitted plain assistant text and didn't call
- *     a delivery tool. Ship it through `onTextBlock`.
+ *     a delivery tool. Ship the part the user hasn't already seen through
+ *     `onTextBlock` (see `progress` below).
+ *   - `progress` — every line of the reply already reached the user as a
+ *     mid-turn progress message, so there is nothing left to send. Recorded
+ *     distinctly rather than as `empty`, which means "the model said
+ *     nothing at all".
  *   - `empty` — no tool, no text, no synthetic-error. Surface a concise
  *     notice so the user isn't left staring at silence.
  *
@@ -29,11 +34,13 @@
  */
 
 import type { StreamState } from "./stream-state.js";
+import { undeliveredResponseText } from "./stream-state.js";
 import { logWarn } from "../../util/log.js";
 import { incrementCounter } from "../../storage/metrics.js";
 
 /** Route the delivery decision selected. */
-export type DeliveryRoute = "tool" | "text-part" | "synthetic-error" | "empty";
+export type DeliveryRoute =
+  "tool" | "text-part" | "progress" | "synthetic-error" | "empty";
 
 export class TextBlockDeliveryError extends Error {
   readonly route: DeliveryRoute;
@@ -163,23 +170,41 @@ export async function routeDelivery(
     };
   }
 
-  // Route 3 — plain text part. Ship it.
-  if (responseText && !state.turnTerminated) {
+  // Route 3 — plain text part. Ship only what the user hasn't already seen.
+  //
+  // The remote-server backends flush each pre-tool segment through
+  // `onTextBlock` as a progress message, and `closeCurrentSegment` also folds
+  // that segment into `allResponseText`. Shipping `responseText` wholesale
+  // therefore re-sent every narration line a second time, concatenated — the
+  // doubled-message symptom on a tool-heavy OpenCode/Kilo turn.
+  //
+  // The subtraction is gated on a progress send having actually happened.
+  // `responseText` is an explicit input and callers are not required to derive
+  // it from `state` (several pass a literal), so reading the remainder off
+  // `allResponseText` unconditionally would silently drop their reply.
+  const pending =
+    state.progressDeliveredLen > 0
+      ? undeliveredResponseText(state)
+      : responseText;
+  if (pending && !state.turnTerminated) {
     if (onTextBlock) {
       try {
-        await onTextBlock(responseText);
+        await onTextBlock(pending);
       } catch (err) {
         logWarn("agent", `[${chatId}] onTextBlock failed: ${errMsg(err)}`);
         if (propagateDeliveryFailure) {
-          throw new TextBlockDeliveryError(
-            "text-part",
-            responseText.length,
-            err,
-          );
+          throw new TextBlockDeliveryError("text-part", pending.length, err);
         }
       }
     }
-    return { route: "text-part", chars: responseText.length };
+    return { route: "text-part", chars: pending.length };
+  }
+
+  // Route 3b — the whole reply already reached the user as progress messages.
+  // Nothing left to send; recorded distinctly so the turn isn't misfiled as an
+  // empty completion in the logs or the empty-turn counter.
+  if (responseText && !state.turnTerminated) {
+    return { route: "progress", chars: responseText.length };
   }
 
   // Route 4 — empty turn. The model produced no text (and didn't end_turn):

package/src/backend/shared/index.ts

@@ -96,6 +96,8 @@ export {
   createStreamState,
   appendText,
   closeCurrentSegment,
+  markProgressDelivered,
+  undeliveredResponseText,
   recordToolUse,
   recordTokens,
   pushLiveUsage,

package/src/backend/shared/stream-state.ts

@@ -44,6 +44,21 @@ export interface StreamState {
   allResponseText: string;
   /** Text *after* the last tool call (or the entire response if no tools). */
   lastTrailingText: string;
+  /**
+   * How much of `allResponseText` has already reached the user as a
+   * mid-turn progress message.
+   *
+   * The remote-server backends flush the pending segment through
+   * `onTextBlock` at each tool boundary, but `closeCurrentSegment` also
+   * folds that segment into `allResponseText` — so the end-of-turn
+   * delivery would ship every narration line a second time, concatenated.
+   * Delivery ships only `allResponseText.slice(progressDeliveredLen)`.
+   *
+   * Advanced only after a progress send actually succeeds, so a flush that
+   * throws (e.g. Telegram's 4096-char limit) leaves its text pending and
+   * the end-of-turn delivery still carries it.
+   */
+  progressDeliveredLen: number;
 
   // ── Session ───────────────────────────────────────────────────────────────
   /** Provider-assigned session id, if one was announced during the stream. */
@@ -133,6 +148,7 @@ export function createStreamState(chatId?: string): StreamState {
     currentBlockText: "",
     allResponseText: "",
     lastTrailingText: "",
+    progressDeliveredLen: 0,
     newSessionId: undefined,
     toolCalls: 0,
     turnTerminated: false,
@@ -279,3 +295,23 @@ export function finalizeResponseText(state: StreamState): string {
   }
   return state.allResponseText.trim();
 }
+
+/**
+ * Record that everything accumulated so far has been shipped to the user
+ * as a progress message. Call only after the send succeeds.
+ */
+export function markProgressDelivered(state: StreamState): void {
+  state.progressDeliveredLen = state.allResponseText.length;
+}
+
+/**
+ * The portion of the turn's text that has NOT already been shipped as a
+ * mid-turn progress message — i.e. what end-of-turn delivery still owes
+ * the user.
+ *
+ * Backends that never flush progress leave `progressDeliveredLen` at 0,
+ * so this is the whole response and their behaviour is unchanged.
+ */
+export function undeliveredResponseText(state: StreamState): string {
+  return state.allResponseText.slice(state.progressDeliveredLen).trim();
+}

package/src/core/agent-runtime/capabilities.ts

@@ -199,10 +199,11 @@ export interface ToolRuntime {
 }
 
 /**
- * `/status` enrichment. Backends that track per-session usage
- * (Codex, OpenAI Agents) implement this. Backends without a
- * per-session model (Claude SDK on a fresh subprocess per turn)
- * return `undefined`.
+ * `/status` enrichment. Both members are optional — a backend
+ * implements whichever it can answer. Backends that track per-session
+ * usage (Codex, OpenAI Agents) supply `getSessionSnapshot`; a backend
+ * with no per-session model (Claude SDK on a fresh subprocess per
+ * turn) omits it and may still report plan limits.
  *
  * The snapshot's `contextModelId` carries the resolved-this-turn
  * model id when the SDK can surface it. Frontend `/status` reads
@@ -211,7 +212,7 @@ export interface ToolRuntime {
  * ChatGPT-OAuth).
  */
 export interface UsageTelemetry {
-  getSessionSnapshot(sessionId: string): Promise<
+  getSessionSnapshot?(sessionId: string): Promise<
     | {
         inputTokens?: number;
         outputTokens?: number;
@@ -221,6 +222,31 @@ export interface UsageTelemetry {
       }
     | undefined
   >;
+  /**
+   * Subscription rate-limit windows. Account-level rather than
+   * per-chat: `/status` renders whichever backend can answer, even
+   * when another one is serving the chat. Absent on backends with no
+   * plan concept; resolves `undefined` when the data can't be read.
+   */
+  getPlanUsage?(): Promise<PlanUsage | undefined>;
+}
+
+/** One subscription rate-limit window, as `/status` renders it. */
+export interface PlanWindow {
+  /** Short label — `5h`, `7d`, or the scoped model's display name. */
+  label: string;
+  /** Window utilisation, 0-100. */
+  percent: number;
+  /** ISO timestamp of the next reset, when the plan reports one. */
+  resetsAt?: string;
+}
+
+export interface PlanUsage {
+  /** Subscription tier (`max`, `pro`, …) when known. */
+  plan?: string;
+  windows: PlanWindow[];
+  /** Epoch ms of the read, so renderers can flag figures as aged. */
+  fetchedAt: number;
 }
 
 /**

package/src/core/agent-runtime/contract-tests.ts

@@ -272,16 +272,16 @@ export async function assertModelCatalogDefaultShape(
 }
 
 /**
- * Backends that expose `UsageTelemetry` must answer
- * `getSessionSnapshot` with either a `UsageSnapshot` object whose
- * counters are non-negative numbers, or `undefined`. Negative
- * counters or `NaN`s are contract violations.
+ * Backends that implement `getSessionSnapshot` must answer it with
+ * either a `UsageSnapshot` object whose counters are non-negative
+ * numbers, or `undefined`. Negative counters or `NaN`s are contract
+ * violations. Backends that only report plan limits are skipped.
  */
 export async function assertUsageTelemetryShape(
   backend: Backend,
   sessionId = "contract-test-session",
 ): Promise<void> {
-  if (!backend.usage) return;
+  if (!backend.usage?.getSessionSnapshot) return;
   const snapshot = await backend.usage.getSessionSnapshot(sessionId);
   if (snapshot === undefined) return;
   const fields: (keyof typeof snapshot)[] = [

package/src/core/engine/gateway-actions/models.ts

@@ -98,6 +98,39 @@ export const modelHandlers: SharedActionHandlers = {
     }
   },
 
+  // Account-level, so it falls back to the pooled Claude backend when
+  // another provider is serving this chat.
+  plan_usage: async (_body, chatId) => {
+    const current = getPooledBackend(getBackendIdForChat(String(chatId)));
+    const source = current?.usage?.getPlanUsage
+      ? current
+      : getPooledBackend("claude");
+    if (!source?.usage?.getPlanUsage)
+      return {
+        ok: false,
+        error: "No configured backend reports subscription rate limits.",
+      };
+
+    const usage = await source.usage.getPlanUsage();
+    if (!usage)
+      return {
+        ok: false,
+        error:
+          "Plan usage is unavailable — no subscription credentials, or this session authenticates with an API key.",
+      };
+
+    const lines = usage.windows.map(
+      (w) =>
+        `- ${w.label}: ${w.percent}% used${w.resetsAt ? `, resets ${w.resetsAt}` : ""}`,
+    );
+    return {
+      ok: true,
+      plan: usage.plan ?? null,
+      windows: usage.windows,
+      text: `Plan usage${usage.plan ? ` (${usage.plan})` : ""}:\n${lines.join("\n")}`,
+    };
+  },
+
   list_backends: (body, chatId) => {
     const currentId = getBackendIdForChat(String(chatId));
     const backends = getAvailableBackends().map((b) => ({

package/src/core/tools/models.ts

@@ -28,6 +28,15 @@ export const modelTools: ToolDefinition[] = [
     tag: "models",
   },
 
+  {
+    name: "plan_usage",
+    description:
+      "Read your own subscription usage: how much of the 5-hour, weekly, and per-model rate-limit windows is spent, and when each resets. Use it before starting long or expensive work, or when deciding whether to defer something. Only answers on a subscription-backed Anthropic backend; other providers report no plan limits.",
+    schema: {},
+    execute: (_params, bridge) => bridge("plan_usage", {}),
+    tag: "models",
+  },
+
   {
     name: "list_backends",
     description:

package/src/frontend/discord/commands/session.ts

@@ -13,6 +13,7 @@ import {
   formatDuration,
   formatTokenCount,
   formatBytes,
+  formatUsd,
 } from "../helpers.js";
 import {
   getBackendIdForChat,
@@ -78,8 +79,18 @@ export async function handleStatus(
           `  Read ${formatTokenCount(s.cache.read)}${s.cache.showsWrite ? `  Write ${formatTokenCount(s.cache.write)}` : ""}`,
         ]
       : []),
-    `  Input ${formatTokenCount(s.inputTokens)}  Output ${formatTokenCount(s.outputTokens)}`,
+    `  Input ${formatTokenCount(s.inputTokens)}  Output ${formatTokenCount(s.outputTokens)}${s.costUsd > 0 ? `  Cost ${formatUsd(s.costUsd)}` : ""}`,
     "",
+    ...(s.plan
+      ? [
+          `**Plan**${s.plan.plan ? `  ${s.plan.plan}` : ""}${s.plan.ageLabel ? ` *(${s.plan.ageLabel})*` : ""}`,
+          ...s.plan.windows.map(
+            (w) =>
+              `  \`${w.label.padEnd(6)}${w.bar} ${String(w.percent).padStart(3)}%\`${w.resetLabel ? ` reset ${w.resetLabel}` : ""}`,
+          ),
+          "",
+        ]
+      : []),
     `**Pulse**  ${s.pulseOn ? "on" : "off"}`,
     `**Workspace**  ${formatBytes(s.diskBytes)}`,
     `**Session**   ${s.sessionName ? `"${s.sessionName}" ` : ""}${s.sessionId ? "`" + s.sessionId.slice(0, 8) + "...`" : "_(new)_"} · ${s.sessionAge} old`,

package/src/frontend/discord/helpers.ts

@@ -20,6 +20,7 @@ export {
   formatDuration,
   formatTokenCount,
   formatBytes,
+  formatUsd,
   formatModelLabel,
 } from "../shared/format.js";
 

package/src/frontend/shared/session-status.ts

@@ -23,11 +23,14 @@ import { isPulseEnabled } from "../../core/background/pulse.js";
 import { getWorkspaceDiskUsage } from "../../util/workspace.js";
 import { appendDailyLog } from "../../storage/daily-log.js";
 import { resolveActiveModelForChat } from "../../core/models/active-model.js";
+import { getPooledBackend } from "../../core/engine/backend-controller/index.js";
 import {
   buildCacheDisplay,
   buildContextDisplay,
+  buildPlanDisplay,
   type CacheDisplay,
   type ContextDisplay,
+  type PlanDisplay,
 } from "./status-context.js";
 import { formatDuration } from "./format.js";
 
@@ -70,8 +73,10 @@ export interface SessionStatusData {
   pulseOn: boolean;
   context: ContextDisplay;
   cache: CacheDisplay | null;
+  plan: PlanDisplay | null;
   inputTokens: number;
   outputTokens: number;
+  costUsd: number;
   turns: number;
   turnsModelLabel: string | undefined;
   lastResponseMs: number;
@@ -157,6 +162,16 @@ export async function collectSessionStatus(
     contextWindow: ctxMax,
   });
 
+  // Plan limits belong to the account, not the chat: fall back to the pooled
+  // Claude backend so the section still shows while another provider serves
+  // this chat.
+  const planSource = backend?.usage?.getPlanUsage
+    ? backend
+    : getPooledBackend("claude");
+  const plan = buildPlanDisplay(
+    await planSource?.usage?.getPlanUsage?.().catch(() => undefined),
+  );
+
   const avgResponseMs =
     info.turns > 0 && u.totalResponseMs
       ? Math.round(u.totalResponseMs / info.turns)
@@ -170,8 +185,10 @@ export async function collectSessionStatus(
     pulseOn: isPulseEnabled(chatId),
     context,
     cache,
+    plan,
     inputTokens,
     outputTokens,
+    costUsd: u.estimatedCostUsd,
     turns: info.turns,
     turnsModelLabel,
     lastResponseMs: u.lastResponseMs || 0,

package/src/frontend/shared/status-context.ts

@@ -1,4 +1,6 @@
 import type { CacheMetricsSupport } from "../../core/types.js";
+import type { PlanUsage } from "../../core/agent-runtime/capabilities.js";
+import { formatSmartTimestamp, formatRelativeAge } from "../../util/time.js";
 
 // ── /context breakdown ────────────────────────────────────────────────────────
 
@@ -284,3 +286,63 @@ export function buildCacheDisplay(input: {
     showsWrite: mode === "readwrite",
   };
 }
+
+// ── Plan limits ─────────────────────────────────────────────────────────────
+
+/** Figures older than this are labelled with their age in /status. */
+const PLAN_STALE_AFTER_MS = 5 * 60_000;
+
+export interface PlanWindowDisplay {
+  label: string;
+  percent: number;
+  bar: string;
+  /** Local-time reset, absent for windows the plan reports no reset for. */
+  resetLabel: string | undefined;
+}
+
+export interface PlanDisplay {
+  plan: string | undefined;
+  windows: PlanWindowDisplay[];
+  /** Set only once the figures have aged, e.g. "12m ago". */
+  ageLabel: string | undefined;
+}
+
+function planResetLabel(iso: string | undefined): string | undefined {
+  if (!iso) return undefined;
+  const ts = Date.parse(iso);
+  if (!Number.isFinite(ts)) return undefined;
+  // Windows are reported a second short of the boundary (20:59:59); round to
+  // the minute so the panel reads 21:00, as the plan's own dashboards do.
+  return formatSmartTimestamp(Math.round(ts / 60_000) * 60_000);
+}
+
+/**
+ * Lay out the subscription's rate-limit windows for /status. Returns null
+ * when the backend has nothing to report, so the section disappears rather
+ * than rendering empty bars.
+ */
+export function buildPlanDisplay(
+  usage: PlanUsage | undefined,
+  barLen = 20,
+): PlanDisplay | null {
+  if (!usage || usage.windows.length === 0) return null;
+
+  const age = Date.now() - usage.fetchedAt;
+  return {
+    plan: usage.plan,
+    ageLabel:
+      age > PLAN_STALE_AFTER_MS
+        ? formatRelativeAge(usage.fetchedAt)
+        : undefined,
+    windows: usage.windows.map((w) => {
+      const percent = Math.max(0, Math.min(100, Math.round(w.percent)));
+      const filled = Math.round((percent / 100) * barLen);
+      return {
+        label: w.label,
+        percent,
+        bar: "█".repeat(filled) + "░".repeat(barLen - filled),
+        resetLabel: planResetLabel(w.resetsAt),
+      };
+    }),
+  };
+}

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

@@ -12,6 +12,7 @@ import {
   formatDuration,
   formatTokenCount,
   formatBytes,
+  formatUsd,
 } from "../helpers/index.js";
 import { resolveBackendForChat } from "../model-menu.js";
 import { getBackendIdForChat } from "../../../core/engine/backend-controller/index.js";
@@ -65,8 +66,18 @@ export function registerSessionCommands(
             `  Read ${formatTokenCount(s.cache.read)}${s.cache.showsWrite ? `  Write ${formatTokenCount(s.cache.write)}` : ""}`,
           ]
         : []),
-      `  Input ${formatTokenCount(s.inputTokens)}  Output ${formatTokenCount(s.outputTokens)}`,
+      `  Input ${formatTokenCount(s.inputTokens)}  Output ${formatTokenCount(s.outputTokens)}${s.costUsd > 0 ? `  Cost ${formatUsd(s.costUsd)}` : ""}`,
       "",
+      ...(s.plan
+        ? [
+            `<b>Plan</b>${s.plan.plan ? `  ${escapeHtml(s.plan.plan)}` : ""}${s.plan.ageLabel ? ` <i>(${s.plan.ageLabel})</i>` : ""}`,
+            ...s.plan.windows.map(
+              (w) =>
+                `  <code>${escapeHtml(w.label.padEnd(6))}${w.bar} ${String(w.percent).padStart(3)}%</code>${w.resetLabel ? ` reset ${w.resetLabel}` : ""}`,
+            ),
+            "",
+          ]
+        : []),
       `<b>Pulse</b>  ${s.pulseOn ? "on" : "off"}`,
       `<b>Workspace</b>  ${formatBytes(s.diskBytes)}`,
       `<b>Session</b>   ${s.sessionName ? `"${escapeHtml(s.sessionName)}" ` : ""}${s.sessionId ? "<code>" + escapeHtml(s.sessionId.slice(0, 8)) + "...</code>" : "<i>(new)</i>"} · ${s.sessionAge} old`,

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

@@ -13,6 +13,7 @@ export {
   formatDuration,
   formatTokenCount,
   formatBytes,
+  formatUsd,
   formatModelLabel,
 } from "../../shared/format.js";
 

package/src/frontend/terminal/commands.ts

@@ -18,6 +18,7 @@ import {
 import {
   buildCacheDisplay,
   buildContextDisplay,
+  buildPlanDisplay,
   buildContextBreakdown,
   estimateContextTokens,
   apportionCells,
@@ -43,6 +44,7 @@ import {
   setSessionName,
 } from "../../storage/sessions.js";
 import { getLoadedPlugins } from "../../core/plugin/index.js";
+import { getPooledBackend } from "../../core/engine/backend-controller/index.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -430,6 +432,24 @@ export function registerBuiltinCommands(): void {
           `  ${pc.dim(`estimated session cost ${formatUsd(u.estimatedCostUsd)}`)}`,
         );
       }
+
+      const planSource = be?.usage?.getPlanUsage
+        ? be
+        : getPooledBackend("claude");
+      const plan = buildPlanDisplay(
+        await planSource?.usage?.getPlanUsage?.().catch(() => undefined),
+      );
+      if (plan) {
+        ctx.renderer.writeln();
+        ctx.renderer.writeln(
+          `  ${pc.bold("Plan")}${plan.plan ? `  ${plan.plan}` : ""}${plan.ageLabel ? pc.dim(`  (${plan.ageLabel})`) : ""}`,
+        );
+        for (const w of plan.windows) {
+          ctx.renderer.writeln(
+            `  ${w.label.padEnd(6)}${pc.dim(w.bar)} ${String(w.percent).padStart(3)}%${w.resetLabel ? pc.dim(`  reset ${w.resetLabel}`) : ""}`,
+          );
+        }
+      }
       if (backendModelLine) {
         ctx.renderer.writeln();
         ctx.renderer.writeln(backendModelLine);