@esso0428/pi-subagents 0.15.0

package/src/ui/fleet-list.ts

@@ -0,0 +1,380 @@
+/**
+ * fleet-list.ts — Claude Code-style "FleetView" list rendered below the editor.
+ *
+ * Shows `main` + each running/queued subagent as a navigable list. Pressing ↓ (or
+ * ←) at an empty prompt activates the list; ↑/↓ move the selection (filled ● marker),
+ * Enter opens the selected agent's live conversation overlay, Esc returns to the prompt.
+ * A viewer stays open when its agent finishes; finished agents linger briefly in the list.
+ *
+ * Mechanics (see plan): the list is a `belowEditor` widget (render-only), and ALL key
+ * handling goes through `onTerminalInput` — which fires before the focused editor and
+ * can `consume` keys — gated on `getEditorText() === ""` so normal typing is untouched.
+ */
+
+import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { AgentManager } from "../agent-manager.js";
+import type { AgentRecord } from "../types.js";
+import { getLifetimeTotal } from "../usage.js";
+import { type AgentActivity, getDisplayName, type Theme } from "./agent-widget.js";
+import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
+
+/** Widget key for the below-editor fleet list. */
+const FLEET_KEY = "fleet";
+/** Max agent rows shown at once; extras collapse into a "↓ N more" indicator. */
+const MAX_AGENT_ROWS = 5;
+/** Re-render cadence so elapsed/token stats tick while agents run. */
+const TICK_MS = 200;
+/** How long a finished agent lingers in the list before it drops out. */
+const FINISHED_LINGER_MS = 4000;
+
+/** Minimal UI surface the FleetView needs from `ctx.ui` (structural subset). */
+export type FleetUICtx = {
+  setWidget(
+    key: string,
+    content: undefined | ((tui: any, theme: Theme) => { render(width: number): string[]; invalidate(): void; dispose?(): void }),
+    options?: { placement?: "aboveEditor" | "belowEditor" },
+  ): void;
+  onTerminalInput(handler: (data: string) => { consume?: boolean; data?: string } | undefined): () => void;
+  getEditorText(): string;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+  custom<T>(
+    factory: (tui: any, theme: Theme, keybindings: any, done: (result: T) => void) => { render(width: number): string[]; invalidate(): void; dispose?(): void },
+    options?: { overlay?: boolean; overlayOptions?: unknown; onHandle?: (handle: unknown) => void },
+  ): Promise<T>;
+};
+
+type MainEntry = { kind: "main" };
+type AgentEntry = { kind: "agent"; record: AgentRecord };
+type FleetEntry = MainEntry | AgentEntry;
+
+/** `11s` — integer seconds, no decimal/suffix (matches Claude Code, unlike formatMs). */
+export function formatFleetElapsed(ms: number): string {
+  return `${Math.max(0, Math.round(ms / 1000))}s`;
+}
+
+/** `↓ 13.1k tokens` — down-arrow prefix, compact magnitude, plural "tokens". */
+export function formatFleetTokens(count: number): string {
+  let compact: string;
+  if (count >= 1_000_000) compact = `${(count / 1_000_000).toFixed(1)}M`;
+  else if (count >= 1_000) compact = `${(count / 1_000).toFixed(1)}k`;
+  else compact = `${count}`;
+  return `↓ ${compact} tokens`;
+}
+
+/**
+ * Place `right` flush to `width`, truncating `left` first so the stats survive.
+ * The final clamp guarantees the line never exceeds `width` (which would wrap and
+ * desync pi's line-diff → flicker) even on a terminal too narrow for the stats.
+ */
+function rightAlign(left: string, right: string, width: number): string {
+  const rightW = visibleWidth(right);
+  const maxLeft = Math.max(0, width - rightW - 1);
+  const leftClamped = truncateToWidth(left, maxLeft);
+  const gap = Math.max(1, width - visibleWidth(leftClamped) - rightW);
+  return truncateToWidth(leftClamped + " ".repeat(gap) + right, width);
+}
+
+export class FleetList {
+  private ui: FleetUICtx | undefined;
+  private tui: any | undefined;
+  private inputUnsub: (() => void) | undefined;
+  private widgetRegistered = false;
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  private enabled = true;
+  /** Whether arrow keys currently navigate the list (vs. flow to the editor). */
+  private active = false;
+  /** 0 = `main`, 1..N = subagents. */
+  private selectedIndex = 0;
+  /** Set while a conversation overlay is open; calling it closes the overlay. */
+  private viewerClose: (() => void) | undefined;
+  private viewingAgentId: string | undefined;
+
+  constructor(
+    private manager: AgentManager,
+    private agentActivity: Map<string, AgentActivity>,
+  ) {}
+
+  // ---- Lifecycle ----
+
+  setEnabled(enabled: boolean): void {
+    if (enabled === this.enabled) return;
+    this.enabled = enabled;
+    if (!enabled) this.active = false;
+    this.update();
+  }
+
+  /** Capture the UI context and (re)register the global input handler. */
+  setUICtx(ui: FleetUICtx): void {
+    if (ui === this.ui) return;
+    this.inputUnsub?.();
+    this.ui = ui;
+    this.widgetRegistered = false;
+    this.tui = undefined;
+    this.inputUnsub = ui.onTerminalInput(data => this.handleKey(data));
+  }
+
+  /** Ensure the re-render timer is running (called when an agent spawns). */
+  ensureTimer(): void {
+    if (!this.timer) this.timer = setInterval(() => this.update(), TICK_MS);
+  }
+
+  /**
+   * Called when an agent finishes. The viewer (if open on it) stays open so the
+   * final output remains readable, and the row lingers in the list — just refresh.
+   */
+  onAgentFinished(_id: string): void {
+    this.update();
+  }
+
+  dispose(): void {
+    if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
+    this.inputUnsub?.();
+    this.inputUnsub = undefined;
+    if (this.viewerClose) { this.viewerClose(); this.viewerClose = undefined; }
+    this.viewingAgentId = undefined;
+    if (this.ui && this.widgetRegistered) this.ui.setWidget(FLEET_KEY, undefined);
+    this.widgetRegistered = false;
+    this.tui = undefined;
+    this.active = false;
+    // Null last so a `viewerClose()` microtask above can't re-register the widget.
+    this.ui = undefined;
+  }
+
+  /** Re-register/refresh the below-editor widget; clears it when no agents remain. */
+  update(): void {
+    if (!this.ui) return;
+    const hasAgents = this.enabled && this.agentRecords().length > 0;
+
+    if (!hasAgents) {
+      if (this.widgetRegistered) {
+        this.ui.setWidget(FLEET_KEY, undefined);
+        this.widgetRegistered = false;
+        this.tui = undefined;
+      }
+      if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
+      this.active = false;
+      this.selectedIndex = 0;
+      return;
+    }
+
+    this.clampSelection();
+    this.ensureTimer(); // keep stats ticking whenever the list is shown (e.g. after a re-enable)
+
+    if (!this.widgetRegistered) {
+      this.ui.setWidget(FLEET_KEY, (tui, theme) => {
+        this.tui = tui;
+        return {
+          render: (w: number) => this.renderBar(w, theme),
+          invalidate: () => { this.widgetRegistered = false; this.tui = undefined; },
+        };
+      }, { placement: "belowEditor" });
+      this.widgetRegistered = true;
+    } else {
+      this.tui?.requestRender();
+    }
+  }
+
+  // ---- Roster ----
+
+  /**
+   * Agents shown in the list, ordered earliest-launched first so the ones you
+   * started sooner sit at the top. Every row is openable (has a session), so Enter
+   * never dead-ends. Included: running/queued, plus the agent currently being
+   * viewed, plus recently-finished ones (they linger briefly before dropping out).
+   * Pending agents with no session yet are hidden until they start.
+   * (`listAgents()` is newest-first, so we re-sort.)
+   */
+  private agentRecords(): AgentRecord[] {
+    const now = Date.now();
+    return this.manager.listAgents()
+      .filter(a => a.session && (
+        a.status === "running" || a.status === "queued"
+        || a.id === this.viewingAgentId
+        || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)
+      ))
+      .sort((a, b) => a.startedAt - b.startedAt);
+  }
+
+  private roster(): FleetEntry[] {
+    return [{ kind: "main" }, ...this.agentRecords().map(record => ({ kind: "agent" as const, record }))];
+  }
+
+  private clampSelection(): void {
+    const max = this.roster().length - 1;
+    if (this.selectedIndex > max) this.selectedIndex = Math.max(0, max);
+    if (this.selectedIndex < 0) this.selectedIndex = 0;
+  }
+
+  // ---- Key handling ----
+
+  /** Returns `{consume:true}` to swallow a key, or undefined to let it through. */
+  handleKey(data: string): { consume?: boolean; data?: string } | undefined {
+    if (!this.enabled || !this.ui) return undefined;
+    // Input listeners receive BOTH key-press and key-release (the kitty protocol
+    // emits both, and matchesKey matches either) — act on press only, or every
+    // tap would move/fire twice. Repeats still pass through for held-key nav.
+    if (isKeyRelease(data)) return undefined;
+    // While an overlay is open, let it own all input.
+    if (this.viewerClose) return undefined;
+    // Input listeners fire BEFORE the focused component, and dialogs
+    // (ctx.ui.select/confirm/input, pi's own menus) swap the prompt editor out
+    // while getEditorText() still reads the detached — empty — editor. So when
+    // anything but the editor owns the keyboard, stay out of its keys (#123).
+    if (!this.editorHasFocus()) {
+      if (this.active) this.deactivate();
+      return undefined;
+    }
+
+    if (!this.active) {
+      // Activate: ↓ or ← at an empty prompt moves focus into the list.
+      const isActivator = matchesKey(data, "down") || matchesKey(data, "left");
+      if (isActivator && this.agentRecords().length > 0 && this.ui.getEditorText() === "") {
+        this.active = true;
+        this.selectedIndex = 0;
+        this.update();
+        return { consume: true };
+      }
+      return undefined;
+    }
+
+    // Active — arrows navigate, Enter opens, Esc / Up-past-top exits.
+    if (matchesKey(data, "down")) {
+      const max = this.roster().length - 1;
+      this.selectedIndex = Math.min(max, this.selectedIndex + 1);
+      this.update();
+      return { consume: true };
+    }
+    if (matchesKey(data, "up")) {
+      if (this.selectedIndex === 0) { this.deactivate(); return { consume: true }; }
+      this.selectedIndex -= 1;
+      this.update();
+      return { consume: true };
+    }
+    if (matchesKey(data, "escape")) { this.deactivate(); return { consume: true }; }
+    if (matchesKey(data, Key.enter)) { this.openSelected(); return { consume: true }; }
+
+    // Any other key cancels navigation and flows to the editor.
+    this.deactivate();
+    return undefined;
+  }
+
+  /**
+   * True when pi's prompt editor owns the keyboard. pi's editor is an `Editor`
+   * subclass (CustomEditor) while every dialog/selector is not, and the loader
+   * aliases pi-tui to pi's own copy, so `instanceof` is a reliable identity
+   * check. `focusedComponent` is TUI-private (no public accessor), hence the
+   * best-effort peek: unknowable focus (no tui seen yet, nothing focused)
+   * counts as the editor so activation keeps working.
+   */
+  private editorHasFocus(): boolean {
+    const focused = (this.tui as { focusedComponent?: unknown } | undefined)?.focusedComponent;
+    return focused == null || focused instanceof Editor;
+  }
+
+  private deactivate(): void {
+    this.active = false;
+    this.selectedIndex = 0;
+    this.update();
+  }
+
+  private openSelected(): void {
+    const entry = this.roster()[this.selectedIndex];
+    if (!entry || entry.kind === "main") {
+      // `main` = return to the prompt; the native transcript is already shown.
+      this.deactivate();
+      return;
+    }
+    const record = entry.record;
+    if (!this.ui) return;
+    if (!record.session) {
+      this.ui.notify(`Agent is ${record.status} — no session available.`, "info");
+      return;
+    }
+    const session = record.session;
+    const activity = this.agentActivity.get(record.id);
+    this.viewingAgentId = record.id;
+
+    void this.ui.custom<undefined>(
+      (tui, theme, keybindings, done) => {
+        this.viewerClose = () => done(undefined);
+        return new ConversationViewer(
+          tui,
+          session,
+          record,
+          activity,
+          theme,
+          done,
+          () => {
+            if (this.manager.abort(record.id)) this.ui?.notify(`Stopped "${record.description}".`, "info");
+          },
+          keybindings,
+          (message: string) => this.manager.steer(record.id, message),
+        );
+      },
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
+      },
+    ).then(() => this.clearViewer(), () => this.clearViewer());
+  }
+
+  /** Reset overlay state and return to the list (on close, auto-close, or error). */
+  private clearViewer(): void {
+    // Keep the cursor on the agent we were viewing — re-resolve by id so it
+    // still feels natural if the list reordered (an earlier agent finished)
+    // while the overlay was open. If that agent is gone, leave the index for
+    // update()'s clamp to settle.
+    if (this.viewingAgentId) {
+      const idx = this.roster().findIndex(e => e.kind === "agent" && e.record.id === this.viewingAgentId);
+      if (idx >= 0) this.selectedIndex = idx;
+    }
+    this.viewerClose = undefined;
+    this.viewingAgentId = undefined;
+    this.update();
+  }
+
+  // ---- Rendering ----
+
+  private renderBar(width: number, theme: Theme): string[] {
+    const agents = this.roster().slice(1) as AgentEntry[];
+    if (agents.length === 0) return [];
+    // Clamp locally so a render between a roster shrink and the next update()
+    // (e.g. on terminal resize) never loses the selection marker.
+    const sel = Math.min(this.selectedIndex, agents.length);
+
+    const hint = this.active
+      ? "↑↓ select · enter view · esc back"
+      : "esc to interrupt · ← for agents · ↓ to manage";
+    const lines: string[] = [];
+    lines.push(truncateToWidth("  " + theme.fg("dim", hint), width));
+    lines.push("");
+    lines.push(truncateToWidth(`  ${this.bullet(0, sel, theme)} main`, width));
+
+    // Window the agent rows so the selected one stays visible.
+    const visible = Math.min(MAX_AGENT_ROWS, agents.length);
+    const selAgent = Math.max(0, sel - 1);
+    const start = selAgent < visible ? 0 : selAgent - visible + 1;
+    const hiddenBelow = agents.length - (start + visible);
+
+    if (start > 0) lines.push(rightAlign("", theme.fg("dim", `↑ ${start} more`), width));
+    for (let a = start; a < start + visible; a++) {
+      lines.push(this.renderAgentRow(a + 1, sel, agents[a].record, width, theme));
+    }
+    if (hiddenBelow > 0) lines.push(rightAlign("", theme.fg("dim", `↓ ${hiddenBelow} more`), width));
+
+    return lines;
+  }
+
+  private bullet(rosterIndex: number, sel: number, theme: Theme): string {
+    return rosterIndex === sel ? theme.fg("accent", "●") : theme.fg("dim", "○");
+  }
+
+  private renderAgentRow(rosterIndex: number, sel: number, record: AgentRecord, width: number, theme: Theme): string {
+    const left = `  ${this.bullet(rosterIndex, sel, theme)} ${theme.fg("muted", getDisplayName(record.type))}  ${record.description}`;
+    const tokens = getLifetimeTotal(this.agentActivity.get(record.id)?.lifetimeUsage ?? record.lifetimeUsage);
+    const elapsedMs = (record.completedAt ?? Date.now()) - record.startedAt; // freezes once finished
+    const right = theme.fg("dim", `${formatFleetElapsed(elapsedMs)} · ${formatFleetTokens(tokens)}`);
+    return rightAlign(left, right, width);
+  }
+}

package/src/ui/schedule-menu.ts

@@ -0,0 +1,104 @@
+/**
+ * schedule-menu.ts — `/agents → Scheduled jobs` submenu.
+ *
+ * Minimal v1 surface: list scheduled jobs, select one to inspect details +
+ * confirm cancellation. No create wizard (the `Agent` tool's `schedule` param
+ * is the canonical creation path), no toggle/cleanup (cancel is enough for
+ * "I scheduled something dumb, get rid of it"). Add management surfaces here
+ * if real demand emerges.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SubagentScheduler } from "../schedule.js";
+import type { ScheduledSubagent } from "../types.js";
+
+/** Format an ISO timestamp as relative time ("in 4h", "2d ago", "—"). */
+function relTime(iso: string | undefined, now = Date.now()): string {
+  if (!iso) return "—";
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return "—";
+  const diff = t - now;
+  const abs = Math.abs(diff);
+  const future = diff > 0;
+  if (abs < 60_000) return future ? "in <1m" : "<1m ago";
+  const m = Math.round(abs / 60_000);
+  if (m < 60) return future ? `in ${m}m` : `${m}m ago`;
+  const h = Math.round(abs / 3_600_000);
+  if (h < 24) return future ? `in ${h}h` : `${h}h ago`;
+  const d = Math.round(abs / 86_400_000);
+  return future ? `in ${d}d` : `${d}d ago`;
+}
+
+/** One-line status icon. */
+function statusIcon(j: ScheduledSubagent): string {
+  if (!j.enabled) return "✗";
+  if (j.lastStatus === "error") return "!";
+  if (j.lastStatus === "running") return "⋯";
+  return "✓";
+}
+
+/** Compact selectable row — name, schedule, agent type, next/last run, count. */
+function formatJob(j: ScheduledSubagent, scheduler: SubagentScheduler): string {
+  const next = scheduler.getNextRun(j.id);
+  return [
+    statusIcon(j),
+    j.name.padEnd(18).slice(0, 18),
+    j.schedule.padEnd(14).slice(0, 14),
+    `[${j.subagent_type}]`,
+    `next ${relTime(next)}`,
+    `last ${relTime(j.lastRun)}`,
+    `runs ${j.runCount}`,
+  ].join("  ");
+}
+
+/** Multi-line details block for the cancel confirm. */
+function formatDetails(j: ScheduledSubagent, scheduler: SubagentScheduler): string {
+  const next = scheduler.getNextRun(j.id) ?? "—";
+  return [
+    `name:      ${j.name}`,
+    `schedule:  ${j.schedule} (${j.scheduleType})`,
+    `agent:     ${j.subagent_type}`,
+    `prompt:    ${j.prompt.slice(0, 200)}${j.prompt.length > 200 ? "…" : ""}`,
+    `created:   ${j.createdAt}`,
+    `last run:  ${j.lastRun ?? "—"} (${j.lastStatus ?? "—"})`,
+    `next run:  ${next}`,
+    `runs:      ${j.runCount}`,
+  ].join("\n");
+}
+
+/**
+ * List scheduled jobs; selecting one opens a cancel-confirm with details.
+ * Returns when the user backs out or after a cancellation.
+ */
+export async function showSchedulesMenu(
+  ctx: ExtensionCommandContext,
+  scheduler: SubagentScheduler,
+): Promise<void> {
+  if (!scheduler.isActive()) {
+    ctx.ui.notify("Scheduler is not active in this session.", "warning");
+    return;
+  }
+
+  const jobs = scheduler.list();
+  if (jobs.length === 0) {
+    ctx.ui.notify("No scheduled jobs.", "info");
+    return;
+  }
+
+  const labels = jobs.map(j => formatJob(j, scheduler));
+  const choice = await ctx.ui.select(
+    `Scheduled jobs (${jobs.length}) — select to cancel`,
+    labels,
+  );
+  if (!choice) return;
+
+  const idx = labels.indexOf(choice);
+  if (idx < 0) return;
+  const job = jobs[idx];
+
+  const ok = await ctx.ui.confirm(`Cancel "${job.name}"?`, formatDetails(job, scheduler));
+  if (!ok) return;
+
+  scheduler.removeJob(job.id);
+  ctx.ui.notify(`Cancelled "${job.name}".`, "info");
+}

package/src/ui/viewer-keys.ts

@@ -0,0 +1,39 @@
+/**
+ * viewer-keys.ts — Scroll key matchers for the conversation viewer.
+ *
+ * Resolves `tui.select.*` through the user's keybindings when pi provides a
+ * manager, falling back to the previous hardcoded keys otherwise. The viewer's
+ * k/j and shift+arrow aliases always work alongside whatever is bound.
+ */
+
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+/** The `tui.select.*` keybinding ids the viewer resolves. */
+export type ViewerScrollKeybinding =
+  | "tui.select.up"
+  | "tui.select.down"
+  | "tui.select.pageUp"
+  | "tui.select.pageDown";
+
+/** Structural subset of pi-tui's `KeybindingsManager` (which satisfies it). */
+export interface ViewerKeybindings {
+  matches(data: string, keybinding: ViewerScrollKeybinding): boolean;
+}
+
+export interface ViewerKeys {
+  scrollUp(data: string): boolean;
+  scrollDown(data: string): boolean;
+  pageUp(data: string): boolean;
+  pageDown(data: string): boolean;
+}
+
+export function createViewerKeys(keybindings?: ViewerKeybindings): ViewerKeys {
+  const matches = (data: string, id: ViewerScrollKeybinding, fallback: KeyId): boolean =>
+    keybindings ? keybindings.matches(data, id) : matchesKey(data, fallback);
+  return {
+    scrollUp: (data) => matches(data, "tui.select.up", "up") || matchesKey(data, "k"),
+    scrollDown: (data) => matches(data, "tui.select.down", "down") || matchesKey(data, "j"),
+    pageUp: (data) => matches(data, "tui.select.pageUp", "pageUp") || matchesKey(data, "shift+up"),
+    pageDown: (data) => matches(data, "tui.select.pageDown", "pageDown") || matchesKey(data, "shift+down"),
+  };
+}

package/src/usage.ts

@@ -0,0 +1,60 @@
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+export type LifetimeUsage = { input: number; output: number; cacheWrite: number };
+
+/** Sum of lifetime usage components, or 0 if undefined. */
+export function getLifetimeTotal(u?: LifetimeUsage): number {
+  return u ? u.input + u.output + u.cacheWrite : 0;
+}
+
+/** Add a usage delta into a target accumulator (mutates target). */
+export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
+  into.input += delta.input;
+  into.output += delta.output;
+  into.cacheWrite += delta.cacheWrite;
+}
+
+/** Minimal shape we read from upstream `getSessionStats()`. */
+export type SessionStatsLike = {
+  tokens: { input: number; output: number; cacheWrite: number };
+  contextUsage?: { percent: number | null };
+};
+export type SessionLike = { getSessionStats(): SessionStatsLike };
+
+/**
+ * Session-scoped token count: input + output + cacheWrite as reported by
+ * upstream `getSessionStats().tokens` for the *current* session window.
+ *
+ * RESETS at compaction — upstream replaces `session.state.messages` and the
+ * stats are derived from that array. For a lifetime total that survives
+ * compaction, use `getLifetimeTotal(lifetimeUsage)` instead, which reads
+ * from an independent accumulator fed by `message_end` events.
+ *
+ * Avoids upstream's `tokens.total` field, which sums per-turn `cacheRead`
+ * and so counts the cumulative cached prefix N times across N turns
+ * (issue #38).
+ */
+export function getSessionTokens(session: SessionLike | undefined): number {
+  if (!session) return 0;
+  try {
+    const t = session.getSessionStats().tokens;
+    return t.input + t.output + t.cacheWrite;
+  } catch { return 0; }
+}
+
+/**
+ * Context-window utilization (0–100), or null when unavailable
+ * (no model contextWindow, or post-compaction before the next response).
+ */
+export function getSessionContextPercent(session: SessionLike | undefined): number | null {
+  if (!session) return null;
+  try { return session.getSessionStats().contextUsage?.percent ?? null; }
+  catch { return null; }
+}