@bismawy/pi-vision-watcher 1.0.7

package/src/usage.ts

@@ -0,0 +1,261 @@
+/**
+ * Describer usage + energy capture for pi-vision-watcher.
+ *
+ * One record is produced per REAL describer provider call (cache hits emit
+ * nothing):
+ *   - model + tokens: from completeSimple()'s AssistantMessage.usage
+ *   - energy + cost + raw MCR/energy/cost payloads: from Neuralwatt SSE comment
+ *     lines parsed out of the teed response body (readEnergyFromTee). Present
+ *     ONLY when the vision model is a Neuralwatt model — non-Neuralwatt models
+ *     produce no comment lines, so the energy fields are OMITTED (not zeroed)
+ *     for easy downstream filtering ("no energy" vs "zero energy").
+ *
+ * The caller (vision-watcher.ts) persists the record via pi.appendEntry (replays
+ * on session resume/branch) AND emits it on pi.events so a live consumer can
+ * filter on the one channel for tokens AND energy.
+ *
+ * Split out of vision-watcher.ts so the pure pieces (readEnergyFromTee,
+ * buildUsageRecord) and the concurrency-safe fetch interceptor are unit-testable
+ * through the normal src/ import path — vision-watcher.ts runs readConfig() at
+ * module load and pulls in the TUI selector, so it is not unit-test-friendly.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Api, AssistantMessage, Model, Usage } from "@earendil-works/pi-ai";
+
+/** Custom session-entry type persisted via pi.appendEntry. */
+export const USAGE_ENTRY_TYPE = "vision-watcher-usage";
+
+/** Event-bus channel emitted via pi.events. */
+export const USAGE_EVENT_CHANNEL = "vision-watcher:usage";
+
+/** Parsed Neuralwatt SSE-comment energy/cost/MCR data for one describer call. */
+export interface VisionHandoffEnergyCapture {
+  energyJoules: number;
+  costUsd: number;
+  energyRaw: Record<string, unknown> | null;
+  mcrSessionRaw: Record<string, unknown> | null;
+  costRaw: Record<string, unknown> | null;
+}
+
+/** Shared empty capture. Safe to share: readEnergyFromTee returns a fresh object
+ *  and never mutates this; buildUsageRecord only reads from its argument. */
+export const EMPTY_ENERGY_CAPTURE: VisionHandoffEnergyCapture = {
+  energyJoules: 0,
+  costUsd: 0,
+  energyRaw: null,
+  mcrSessionRaw: null,
+  costRaw: null,
+};
+
+/** A single describer-call usage record. Energy fields are present only when
+ *  Neuralwatt SSE energy comments were captured (omitted, not zeroed, otherwise).
+ *
+ *  One record is emitted per REAL describer provider call (cache hits emit
+ *  nothing). A batched call that describes several images at once still emits a
+ *  single record: `imageHash` is the representative (first) member and
+ *  `imageHashes` lists every image the call covered, so consumers can attribute
+ *  the call's tokens/energy to each member image without double-counting. */
+export interface VisionHandoffUsageRecord {
+  /** Representative image hash (first member of the batch). */
+  imageHash: string;
+  /** All image hashes covered by this describer call. Present only for batched
+   *  calls (length > 1); omitted for single-image calls. */
+  imageHashes?: string[];
+  model: string;
+  provider: string;
+  responseModel?: string;
+  responseId?: string;
+  usage: Usage;
+  /** Neuralwatt energy — present only when SSE energy comments were captured. */
+  energyJoules?: number;
+  costUsd?: number;
+  energyRaw?: Record<string, unknown> | null;
+  mcrSessionRaw?: Record<string, unknown> | null;
+  costRaw?: Record<string, unknown> | null;
+}
+
+/**
+ * Parse Neuralwatt SSE comment lines (`: energy`, `: cost`, `: mcr-session`)
+ * from a teed response body into a fresh capture object. Mirrors
+ * pi-neuralwatt-provider's readEnergyFromTee but returns a result instead of
+ * mutating module state — vision-watcher describes images concurrently (the
+ * before_agent_start warm-up fires several in parallel), so each call needs its
+ * own capture routed via {@link describeAls}. For non-Neuralwatt vision models
+ * no comment lines are present and the returned capture stays empty.
+ */
+export async function readEnergyFromTee(
+  body: ReadableStream<Uint8Array>,
+): Promise<VisionHandoffEnergyCapture> {
+  const result: VisionHandoffEnergyCapture = { ...EMPTY_ENERGY_CAPTURE };
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  function processLine(line: string): void {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(": energy ")) {
+      try {
+        const energy = JSON.parse(trimmed.slice(9));
+        result.energyJoules += energy.energy_joules || 0;
+        result.energyRaw = energy;
+      } catch {
+        // malformed energy comment — ignore
+      }
+    } else if (trimmed.startsWith(": mcr-session ")) {
+      try {
+        result.mcrSessionRaw = JSON.parse(trimmed.slice(14));
+      } catch {
+        // malformed mcr-session comment — ignore
+      }
+    } else if (trimmed.startsWith(": cost ")) {
+      try {
+        const cost = JSON.parse(trimmed.slice(7));
+        result.costUsd += cost.request_cost_usd || 0;
+        result.costRaw = cost;
+      } catch {
+        // malformed cost comment — ignore
+      }
+    }
+  }
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) processLine(line);
+    }
+  } catch {
+    // tee stream may error if the main stream is aborted — that's fine
+  }
+
+  const final = decoder.decode(new Uint8Array(0), { stream: false });
+  const remaining = (buffer + final).trim();
+  if (remaining) processLine(remaining);
+
+  try {
+    reader.releaseLock();
+  } catch {
+    // ignore
+  }
+  return result;
+}
+
+/**
+ * Build a usage record from a describer response + energy capture. Returns
+ * null when there is nothing meaningful to report (e.g. a provider-level
+ * failure with zero tokens and no energy) so the caller can skip emitting.
+ *
+ * Energy fields are OMITTED entirely (not zeroed) when no Neuralwatt SSE energy
+ * comments were captured, so consumers can distinguish "no energy" from
+ * "zero energy".
+ */
+export function buildUsageRecord(
+  response: AssistantMessage,
+  capture: VisionHandoffEnergyCapture,
+  visionModel: Model<Api>,
+  imageHash: string,
+  imageHashes?: string[],
+): VisionHandoffUsageRecord | null {
+  const hasEnergy = !!(
+    capture.energyRaw ||
+    capture.costRaw ||
+    capture.mcrSessionRaw ||
+    capture.energyJoules > 0 ||
+    capture.costUsd > 0
+  );
+  const hasUsage =
+    !!response.usage &&
+    (response.usage.totalTokens > 0 || response.usage.input > 0 || response.usage.output > 0);
+  if (!hasUsage && !hasEnergy) return null;
+
+  const record: VisionHandoffUsageRecord = {
+    imageHash,
+    model: response.model || visionModel.id,
+    provider: response.provider || visionModel.provider,
+    responseModel: response.responseModel,
+    responseId: response.responseId,
+    usage: response.usage,
+  };
+  // Present only for genuine batched calls (more than one image). Keeps the
+  // single-image record shape unchanged for existing consumers.
+  if (imageHashes && imageHashes.length > 1) {
+    record.imageHashes = imageHashes;
+  }
+  if (hasEnergy) {
+    record.energyJoules = capture.energyJoules;
+    record.costUsd = capture.costUsd;
+    record.energyRaw = capture.energyRaw;
+    record.mcrSessionRaw = capture.mcrSessionRaw;
+    record.costRaw = capture.costRaw;
+  }
+  return record;
+}
+
+// ── Concurrency-safe fetch interceptor ─────────────────────────────────────
+//
+// The only body-interception point for completeSimple() is globalThis.fetch (pi-ai's
+// StreamOptions.onResponse exposes headers only, not the body where the
+// `: energy` SSE comments live). before_agent_start fires several describeImage()
+// calls fire-and-forget, so a naïve save/patch/restore of globalThis.fetch would
+// clobber under concurrency. The fix is a refcounted shared interceptor
+// (installed only while ≥1 describe is in flight, so non-describe fetches pass
+// through unmodified) + AsyncLocalStorage to route each teed response body to
+// the describe call that issued it. Nested patches from other extensions (e.g.
+// pi-neuralwatt-provider's streamNeuralwatt, which also tees for its own energy
+// display) chain on top and restore back to this interceptor, so both tees read
+// the same comment lines independently.
+
+/** Per-describer-call ALS slot carrying the energy tee reader. */
+export interface DescribeContext {
+  energyReader: Promise<VisionHandoffEnergyCapture> | undefined;
+}
+
+/** Routes each teed response body to the describe call that issued it. */
+export const describeAls = new AsyncLocalStorage<DescribeContext>();
+
+let fetchInterceptRefCount = 0;
+let savedRealFetch: typeof globalThis.fetch | null = null;
+
+/** Install the globalThis.fetch interceptor. Refcounted: the first caller
+ *  patches fetch; later callers just bump the count. Idempotent per install. */
+export function installFetchInterceptor(): void {
+  if (fetchInterceptRefCount === 0) {
+    savedRealFetch = globalThis.fetch;
+    globalThis.fetch = interceptedFetch;
+  }
+  fetchInterceptRefCount++;
+}
+
+/** Remove the interceptor. Refcounted: only the last caller restores fetch. */
+export function uninstallFetchInterceptor(): void {
+  if (fetchInterceptRefCount > 0) fetchInterceptRefCount--;
+  if (fetchInterceptRefCount === 0 && savedRealFetch) {
+    globalThis.fetch = savedRealFetch;
+    savedRealFetch = null;
+  }
+}
+
+/** Current refcount — 0 means the interceptor is not installed. Test hook. */
+export function fetchInterceptorRefcount(): number {
+  return fetchInterceptRefCount;
+}
+
+async function interceptedFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  const real = savedRealFetch ?? globalThis.fetch;
+  const response = await real(input, init);
+  const store = describeAls.getStore();
+  // Outside a describer call (no ALS store) or for bodiless responses: pass
+  // through untouched.
+  if (!store || !response.body) return response;
+  const [bodyForSdk, bodyForEnergy] = response.body.tee();
+  store.energyReader = readEnergyFromTee(bodyForEnergy);
+  return new Response(bodyForSdk, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}

package/src/vision-model-selector.ts

@@ -0,0 +1,452 @@
+/**
+ * VisionModelSelectorComponent — an interactive TUI for choosing which model
+ * describes images during vision handoff.
+ *
+ * Uses the same patterns as pi's built-in selectors and pi-hide-providers:
+ * - Lists connected (authenticated) models, vision-capable ones first (👀 badge)
+ * - A leading "None" row clears the configured vision model
+ * - Search/filter via Input component
+ * - Enter or Ctrl+S confirms the highlighted model and saves
+ * - Esc / Ctrl+C cancels
+ * - The currently configured vision model is marked ✓
+ */
+
+import {
+  Container,
+  type Component,
+  fuzzyFilter,
+  getKeybindings,
+  Input,
+  Key,
+  matchesKey,
+  Spacer,
+  Text,
+  truncateToWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import { DynamicBorder, keyText } from "@earendil-works/pi-coding-agent";
+import { formatModelRef, isVisionModel, THINKING_LEVELS } from "./index.js";
+
+interface DisplayItem {
+  /** "provider/id", or null for the synthetic "None" row. */
+  ref: string | null;
+  provider: string;
+  modelId: string;
+  modelName: string;
+  vision: boolean;
+  /** Whether the model declares reasoning (thinking) support. */
+  reasoning: boolean;
+  none?: boolean;
+}
+
+export interface VisionModelSelectorResult {
+  /** The selected "provider/id", or null if the user picked "None" / cancelled. */
+  ref: string | null;
+  /** True if the user cancelled (esc) — config should not change. */
+  cancelled: boolean;
+  /** Thinking on/off chosen in the picker. */
+  thinking: boolean;
+  /** Thinking effort chosen in the picker. */
+  thinkingLevel: ThinkingLevel;
+  /** Whether pasted paths should be injected if no matching read wins. */
+  asyncClipboardHandoff: boolean;
+}
+
+export class VisionModelSelectorComponent implements Component {
+  private theme: Theme;
+  private done: (result: VisionModelSelectorResult) => void;
+
+  private allItems: DisplayItem[];
+  private filteredItems: DisplayItem[];
+  private selectedIndex = 0;
+  private readonly maxVisible = 10;
+  private searchInput: Input;
+  private listContainer: Container;
+  private footerText: Text;
+
+  private currentRef: string | null;
+  private thinking: boolean;
+  private thinkingLevel: ThinkingLevel;
+  private asyncClipboardHandoff: boolean;
+
+  private _focused = false;
+  get focused(): boolean {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor(
+    theme: Theme,
+    allModels: Array<{
+      provider: string;
+      id: string;
+      name: string;
+      input?: ("text" | "image")[];
+      reasoning?: boolean;
+    }>,
+    currentRef: string | null,
+    currentThinking: boolean,
+    currentThinkingLevel: ThinkingLevel,
+    currentAsyncClipboardHandoff: boolean,
+    done: (result: VisionModelSelectorResult) => void,
+  ) {
+    this.theme = theme;
+    this.done = done;
+    this.currentRef = currentRef;
+    this.thinking = currentThinking;
+    this.thinkingLevel = currentThinkingLevel;
+    this.asyncClipboardHandoff = currentAsyncClipboardHandoff;
+    this.allItems = this.buildItems(allModels);
+    this.filteredItems = this.allItems;
+
+    const startIdx = this.allItems.findIndex((i) => i.ref === currentRef);
+    this.selectedIndex = startIdx >= 0 ? startIdx : 0;
+
+    this.searchInput = new Input();
+    this.listContainer = new Container();
+    this.footerText = new Text(this.getFooterText(), 0, 0);
+
+    this.searchInput.onSubmit = () => {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.confirm(item);
+    };
+
+    this.updateList();
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+    lines.push(...new DynamicBorder((s) => this.theme.fg("accent", s)).render(width));
+    lines.push("");
+    lines.push(
+      truncateToWidth(
+        this.theme.fg("accent", this.theme.bold("Vision Watcher")),
+        width,
+        "",
+      ),
+    );
+    lines.push(
+      ...wrapTextWithAnsi(
+        this.theme.fg(
+          "muted",
+          "Pick a vision-capable model to describe images for text-only models.",
+        ),
+        width,
+      ),
+    );
+    lines.push("");
+    lines.push(...this.searchInput.render(width));
+    lines.push("");
+    lines.push(...this.listContainer.render(width));
+    lines.push("");
+    lines.push(...this.footerText.render(width));
+    lines.push(...new DynamicBorder((s) => this.theme.fg("accent", s)).render(width));
+    return lines.map((line) => truncateToWidth(line, width, ""));
+  }
+
+  handleInput(data: string): void {
+    const kb = getKeybindings();
+
+    if (kb.matches(data, "tui.select.up")) {
+      if (this.filteredItems.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.filteredItems.length - 1
+          : this.selectedIndex - 1;
+      this.updateList();
+      return;
+    }
+
+    if (kb.matches(data, "tui.select.down")) {
+      if (this.filteredItems.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.filteredItems.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+      this.updateList();
+      return;
+    }
+
+    if (kb.matches(data, "tui.select.confirm")) {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.confirm(item);
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl("s"))) {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.confirm(item);
+      return;
+    }
+
+    if (matchesKey(data, Key.escape)) {
+      this.finish(true);
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl("c"))) {
+      if (this.searchInput.getValue()) {
+        this.searchInput.setValue("");
+        this.refresh();
+      } else {
+        this.finish(true);
+      }
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl("a"))) {
+      this.asyncClipboardHandoff = !this.asyncClipboardHandoff;
+      this.updateList();
+      return;
+    }
+
+    // Thinking controls — reuse pi's own app.thinking.* keybindings so the
+    // hints and behaviour match the rest of pi: ctrl+t toggles thinking
+    // on/off, shift+tab cycles the effort level. Intercepted before the
+    // search input so they never get swallowed as filter text.
+    if (kb.matches(data, "app.thinking.toggle")) {
+      this.thinking = !this.thinking;
+      this.updateList();
+      return;
+    }
+
+    if (kb.matches(data, "app.thinking.cycle")) {
+      this.cycleThinkingLevel();
+      this.updateList();
+      return;
+    }
+
+    this.searchInput.handleInput(data);
+    this.refresh();
+  }
+
+  invalidate(): void {
+    this.searchInput.invalidate();
+    this.listContainer.invalidate();
+    this.footerText.invalidate();
+  }
+
+  // Internal helpers
+
+  private buildItems(
+    allModels: Array<{
+      provider: string;
+      id: string;
+      name: string;
+      input?: ("text" | "image")[];
+      reasoning?: boolean;
+    }>,
+  ): DisplayItem[] {
+    const items: DisplayItem[] = [
+      {
+        ref: null,
+        provider: "",
+        modelId: "none",
+        modelName: "None — disable vision handoff",
+        vision: false,
+        reasoning: false,
+        none: true,
+      },
+    ];
+
+    const make = (m: {
+      provider: string;
+      id: string;
+      name: string;
+      input?: ("text" | "image")[];
+      reasoning?: boolean;
+    }): DisplayItem => ({
+      ref: formatModelRef(m.provider, m.id),
+      provider: m.provider,
+      modelId: m.id,
+      modelName: m.name || m.id,
+      vision: isVisionModel(m),
+      reasoning: !!m.reasoning,
+    });
+
+    // Only vision-capable models are listed — a text-only model can't describe
+    // images, so it would only produce "[Image: description unavailable]" errors.
+    const visionModels = allModels.filter((m) => isVisionModel(m)).map(make);
+    return [...items, ...visionModels];
+  }
+
+  private getFooterText(): string {
+    const totalCount = this.allItems.length - 1; // exclude the None row
+
+    const current = this.currentRef
+      ? `current: ${this.currentRef}`
+      : "current: none";
+
+    const parts: string[] = [
+      `${keyText("tui.select.confirm")} select`,
+      `ctrl+s done`,
+      `${keyText("app.thinking.toggle")} thinking`,
+      `${keyText("app.thinking.cycle")} effort`,
+      `ctrl+a async fallback`,
+      `esc cancel`,
+      this.searchInput.getValue() ? `${this.filteredItems.length - 1} match` : `${totalCount} vision-capable models`,
+    ];
+
+    return this.theme.fg("dim", `  ${parts.join(" · ")} · ${current} `);
+  }
+
+  private refresh(): void {
+    const query = this.searchInput.getValue();
+    this.filteredItems = query
+      ? fuzzyFilter(
+          this.allItems,
+          query,
+          (i) => `${i.provider} ${i.modelId} ${i.ref ?? "none"} ${i.modelName}`,
+        )
+      : this.allItems;
+    this.selectedIndex = Math.min(
+      this.selectedIndex,
+      Math.max(0, this.filteredItems.length - 1),
+    );
+    this.updateList();
+  }
+
+  private updateList(): void {
+    this.listContainer.clear();
+
+    if (this.filteredItems.length === 0) {
+      this.listContainer.addChild(
+        new Text(this.theme.fg("muted", "  No matching models"), 0, 0),
+      );
+      this.footerText.setText(this.getFooterText());
+      return;
+    }
+
+    const startIndex = Math.max(
+      0,
+      Math.min(
+        this.selectedIndex - Math.floor(this.maxVisible / 2),
+        this.filteredItems.length - this.maxVisible,
+      ),
+    );
+    const endIndex = Math.min(startIndex + this.maxVisible, this.filteredItems.length);
+
+    for (let i = startIndex; i < endIndex; i++) {
+      const item = this.filteredItems[i];
+      if (!item) continue;
+
+      const isSelected = i === this.selectedIndex;
+      const prefix = isSelected ? this.theme.fg("accent", "→ ") : "  ";
+
+      let label: string;
+      if (item.none) {
+        label = this.theme.fg("warning", item.modelName);
+      } else {
+        const labelled = isSelected
+          ? this.theme.fg("accent", item.modelId)
+          : item.modelId;
+        const badge = item.vision ? this.theme.fg("success", " 👀") : this.theme.fg("muted", " ·");
+        const providerBadge = this.theme.fg("muted", ` [${item.provider}]`);
+        label = `${labelled}${providerBadge}${badge}`;
+      }
+
+      const current = item.ref === this.currentRef && item.ref !== null
+        ? this.theme.fg("success", " ✓")
+        : item.none && this.currentRef === null
+          ? this.theme.fg("success", " ✓")
+          : "";
+
+      this.listContainer.addChild(new Text(`${prefix}${label}${current}`, 0, 0));
+    }
+
+    if (startIndex > 0 || endIndex < this.filteredItems.length) {
+      this.listContainer.addChild(
+        new Text(
+          this.theme.fg("muted", `  (${this.selectedIndex + 1}/${this.filteredItems.length})`),
+          0, 0,
+        ),
+      );
+    }
+
+    const selected = this.filteredItems[this.selectedIndex];
+    if (selected) {
+      this.listContainer.addChild(new Spacer(1));
+      if (selected.none) {
+        this.listContainer.addChild(
+          new Text(this.theme.fg("muted", `  ${selected.modelName}`), 0, 0),
+        );
+      } else {
+        this.listContainer.addChild(
+          new Text(this.theme.fg("muted", `  Model Name: ${selected.modelName}`), 0, 0),
+        );
+        this.listContainer.addChild(
+          new Text(this.theme.fg("dim", "  👀 vision-capable — recommended describer"), 0, 0),
+        );
+      }
+      this.renderThinkingDetail(selected);
+      const fallback = this.asyncClipboardHandoff
+        ? this.theme.fg("success", "on")
+        : this.theme.fg("muted", "off");
+      this.listContainer.addChild(
+        new Text(this.theme.fg("dim", `  Async pasted-path fallback: ${fallback}`), 0, 0),
+      );
+    }
+
+    this.footerText.setText(this.getFooterText());
+  }
+
+  /** Append the thinking on/off + effort line to the detail pane, with a
+   *  warning when the highlighted model can't reason (so the setting would
+   *  be silently ignored by the describer). */
+  private renderThinkingDetail(selected: DisplayItem): void {
+    const state = this.thinking
+      ? this.theme.fg("success", `on (${this.thinkingLevel})`)
+      : this.theme.fg("muted", "off");
+    this.listContainer.addChild(
+      new Text(this.theme.fg("dim", `  Thinking: ${state}`), 0, 0),
+    );
+    if (this.thinking && !selected.none && !selected.reasoning) {
+      this.listContainer.addChild(
+        new Text(
+          this.theme.fg(
+            "warning",
+            `  ⚠ ${selected.modelId} declares no reasoning — thinking will be ignored`,
+          ),
+          0, 0,
+        ),
+      );
+    }
+  }
+
+  private confirm(item: DisplayItem): void {
+    this.done({
+      ref: item.ref,
+      cancelled: false,
+      thinking: this.thinking,
+      thinkingLevel: this.thinkingLevel,
+      asyncClipboardHandoff: this.asyncClipboardHandoff,
+    });
+  }
+
+  private finish(cancelled: boolean): void {
+    this.done({
+      ref: null,
+      cancelled,
+      thinking: this.thinking,
+      thinkingLevel: this.thinkingLevel,
+      asyncClipboardHandoff: this.asyncClipboardHandoff,
+    });
+  }
+
+  /** Cycle the thinking effort forward through {@link THINKING_LEVELS},
+   *  wrapping from the last back to the first. Cycling implicitly turns
+   *  thinking on (you don't usually cycle a switch you want off) — matching
+   *  pi's own `app.thinking.cycle` behaviour, which is a no-op only when the
+   *  active model has no reasoning. */
+  private cycleThinkingLevel(): void {
+    if (!this.thinking) this.thinking = true;
+    const idx = THINKING_LEVELS.indexOf(this.thinkingLevel);
+    const next = THINKING_LEVELS[(idx + 1) % THINKING_LEVELS.length]!;
+    this.thinkingLevel = next;
+  }
+}