pi-better-openai 0.1.18 → 0.1.21

package/index.ts

@@ -4,37 +4,37 @@
  * Adds `service_tier: "priority"` to OpenAI provider payloads while fast mode is
  * enabled and the selected model is in the configured allow-list.
  */
+import { sep } from "node:path";
 import {
   getSettingsListTheme,
   type ExtensionAPI,
   type ExtensionContext,
-} from "@mariozechner/pi-coding-agent";
-import {
-  calculateImageRows,
-  Container,
-  getCapabilities,
-  getCellDimensions,
-  Key,
-  matchesKey,
-  SettingsList,
-} from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, SettingsList } from "@earendil-works/pi-tui";
 import { CONFIG_BASENAME, STATUS_KEY } from "./src/identity.ts";
-import { formatTokens, sanitizeStatusText, truncateToWidth, visibleWidth } from "./src/format.ts";
+import {
+  formatTokens,
+  redactDiagnosticValue,
+  sanitizeStatusText,
+  truncateToWidth,
+  visibleWidth,
+} from "./src/format.ts";
 import {
   DEFAULT_CONFIG,
   DEFAULT_IMAGE_CONFIG,
   DEFAULT_PET_CONFIG,
   DEFAULT_SUPPORTED_MODELS,
-  FOOTER_MODES,
-  IMAGE_OUTPUT_FORMATS,
-  IMAGE_SAVE_MODES,
-  PET_PLACEMENTS,
   PET_STATES,
+  FOOTER_SETTING_DESCRIPTORS,
+  USAGE_SETTING_DESCRIPTORS,
+  IMAGE_SETTING_DESCRIPTORS,
+  PET_SETTING_DESCRIPTORS,
+  FAST_SETTING_DESCRIPTORS,
+  type SettingsOptionDescriptor,
   configPaths,
   type ResolvedConfig,
   type PetPlacement,
   type PetState,
-  type SupportedModel,
   isRecord,
   parseModelKey,
   normalizeModelKeys,
@@ -42,42 +42,34 @@ import {
   readRawConfig,
   resolveConfig,
   writeConfig,
+  applySettingToRawConfig,
 } from "./src/config.ts";
 import {
-  AUTH_FILE,
-  type UsageSnapshot,
   formatPercent,
-  formatResetCountdown,
   formatUsageSnapshot,
   parseUsageSnapshot,
   readCodexAuth,
-  requestCodexUsage,
 } from "./src/usage.ts";
 import { registerOpenAIImage, _imageTest } from "./src/image.ts";
 import {
   type CodexPetPackage,
-  type LoadedCodexPet,
-  loadCodexPet,
-  animationFrameAt,
   codexHome,
   describeCodexPetSelectionIssue,
+  findCodexPet,
   findReadyCodexPet,
   formatNoReadyCodexPetsMessage,
   listCodexPets,
-  nextAnimationFrameDelayMs,
-  PET_ANIMATION_ROWS,
-  CodexPetKittyManager,
   registerOpenAIPets,
-  renderCodexPetFrame,
   _petsTest,
 } from "./src/pets.ts";
+import { FastController, modelList, supportsFast } from "./src/fast-controller.ts";
+import { UsageController } from "./src/usage-controller.ts";
+import { PetFooterController } from "./src/pet-footer-controller.ts";
 
 const COMMAND = "fast";
 const OPENAI_STATUS_COMMAND = "openai-usage";
 const OPENAI_SETTINGS_COMMAND = "openai-settings";
 const FLAG = "fast";
-const PET_RESIZE_FREEZE_MS = 120;
-const PET_RENDER_CACHE_LIMIT = 48;
 const PET_EMPTY_VALUE = "not selected";
 const SERVICE_TIER = "priority";
 type SettingsPickerItem = {
@@ -92,53 +84,24 @@ type SettingsPickerItem = {
   ) => { render(width: number): string[]; invalidate(): void; handleInput?(data: string): void };
 };
 
-function currentModelKey(ctx: ExtensionContext): string {
-  return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none";
-}
-
-function supportsFast(ctx: ExtensionContext, supportedModels: SupportedModel[]): boolean {
-  const current = ctx.model;
-  if (!current) return false;
-  return supportedModels.some(
-    (model) => model.provider === current.provider && model.id === current.id,
-  );
-}
-
-function modelList(supportedModels: SupportedModel[]): string {
-  return supportedModels.length > 0
-    ? supportedModels.map((model) => `${model.provider}/${model.id}`).join(", ")
-    : "none configured";
-}
-
-function stateText(
-  ctx: ExtensionContext,
-  desiredActive: boolean,
-  active: boolean,
-  supportedModels: SupportedModel[],
+function abbreviateHomePath(
+  path: string,
+  home = process.env.HOME || process.env.USERPROFILE,
 ): string {
-  const model = currentModelKey(ctx);
-  if (active) return `Fast mode is on for ${model}.`;
-  if (desiredActive) {
-    return `Fast mode is requested, but inactive for unsupported model ${model}. Supported models: ${modelList(supportedModels)}.`;
-  }
-  return `Fast mode is off. Current model: ${model}.`;
-}
-
-function isOpenAISubscriptionModel(ctx: ExtensionContext, cfg: ResolvedConfig): boolean {
-  if (!ctx.model || (ctx.model.provider !== "openai" && ctx.model.provider !== "openai-codex"))
-    return false;
-  return !cfg.usage.showOnlyOnSubscriptionModels || ctx.modelRegistry.isUsingOAuth(ctx.model);
-}
-
-function randomIdleEmoteState(idleState: PetState, random = Math.random): PetState {
-  const candidates = (["waving", "jumping"] as const).filter((state) => state !== idleState);
-  return candidates[Math.floor(random() * candidates.length)] ?? "waving";
+  if (!home) return path;
+  if (path === home) return "~";
+  const homePrefix = home.endsWith(sep) ? home : `${home}${sep}`;
+  return path.startsWith(homePrefix) ? `~/${path.slice(homePrefix.length)}` : path;
 }
 
 function isInlinePetPlacement(placement: PetPlacement): boolean {
   return placement === "inline-left" || placement === "inline-right" || placement === "badge";
 }
 
+function hasTerminalUI(ctx: ExtensionContext): boolean {
+  return ctx.mode === "tui" || (ctx.mode === undefined && ctx.hasUI);
+}
+
 function petSizeCellsForPlacement(placement: PetPlacement, sizeCells: number): number {
   return placement === "badge" ? Math.min(6, sizeCells) : sizeCells;
 }
@@ -156,19 +119,10 @@ function petSlugFromPickerValue(value: string): string {
   return value === PET_EMPTY_VALUE ? "" : value;
 }
 
-function petPickerLookupKey(value: string): string {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
-}
-
 function findPickerPet(value: string, pets: CodexPetPackage[]): CodexPetPackage | undefined {
-  const requested = petPickerLookupKey(value.trim());
-  if (!requested) return undefined;
-  return pets.find(
-    (pet) =>
-      pet.hasSpritesheet &&
-      (petPickerLookupKey(pet.slug) === requested ||
-        petPickerLookupKey(pet.name) === requested ||
-        (pet.id !== undefined && petPickerLookupKey(pet.id) === requested)),
+  return findCodexPet(
+    pets.filter((pet) => pet.hasSpritesheet),
+    value,
   );
 }
 
@@ -293,109 +247,34 @@ function combineInlinePetFooter(
   return lines;
 }
 
-function petFrameInfo(pet: LoadedCodexPet, state: PetState, elapsedMs: number) {
-  const frames = pet.states[state] ?? pet.states.idle;
-  const frame = animationFrameAt(frames, elapsedMs);
-  return { frame, frameIndex: frame ? frames.indexOf(frame) : -1 };
-}
-
-function petFrameRows(
-  pet: LoadedCodexPet,
-  state: PetState,
-  elapsedMs: number,
-  width: number,
-  sizeCells: number,
-): number {
-  const { frame } = petFrameInfo(pet, state, elapsedMs);
-  if (!frame || !getCapabilities().images) return 0;
-  const columns = Math.max(1, Math.min(Math.max(1, width - 2), sizeCells));
-  return calculateImageRows(
-    { widthPx: frame.widthPx, heightPx: frame.heightPx },
-    columns,
-    getCellDimensions(),
-  );
-}
-
-function petPlaceholderLines(
-  pet: LoadedCodexPet,
-  state: PetState,
-  elapsedMs: number,
-  width: number,
-  sizeCells: number,
-): string[] {
-  return Array.from({ length: petFrameRows(pet, state, elapsedMs, width, sizeCells) }, () => "");
-}
-
-function petRenderCacheKey(
-  pet: LoadedCodexPet,
-  state: PetState,
-  frameIndex: number,
-  placement: PetPlacement,
-  width: number,
-  sizeCells: number,
-): string {
-  const cellDimensions = getCellDimensions();
-  const imageProtocol = getCapabilities().images ?? "none";
-  return [
-    pet.pet.slug,
-    state,
-    frameIndex,
-    placement,
-    width,
-    sizeCells,
-    imageProtocol,
-    cellDimensions.widthPx,
-    cellDimensions.heightPx,
-  ].join(":");
+function textPanel(title: string, lines: string[], done: () => void) {
+  return {
+    render(width: number) {
+      const clipped = lines.map((line) => truncateToWidth(line, width, "..."));
+      return [title, "", ...clipped, "", "Esc/q to go back"];
+    },
+    invalidate() {},
+    handleInput(data: string) {
+      if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c")) || data === "q") done();
+    },
+  };
 }
 
 export default function betterOpenAI(pi: ExtensionAPI): void {
-  let desiredActive = false;
-  let active = false;
+  const fastController = new FastController(SERVICE_TIER);
   let cachedConfig: ResolvedConfig | undefined;
-  let usageSnapshot: UsageSnapshot | undefined;
-  let usageUpdatedAt: number | undefined;
-  let usageError: string | undefined;
-  let usageLastFetchAt: number | undefined;
-  let usageTimer: ReturnType<typeof setInterval> | undefined;
   let footerTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
-  let usageRefreshInFlight = false;
-  let queuedUsageRefresh: { ctx: ExtensionContext; modelId?: string; notify?: boolean } | undefined;
-  let shuttingDown = false;
-  let usageAbortController: AbortController | undefined;
   let footerInstalled = false;
   let statusInstalled = false;
-  let requestFooterRender: (() => void) | undefined;
-  let requestSettingsRender: (() => void) | undefined;
-  let lastInjectedAt: number | undefined;
-  let lastInjectedModel: string | undefined;
-  let lastInjectedTier: string | undefined;
-  let pet: LoadedCodexPet | undefined;
-  let petError: string | undefined;
-  let petLoadKey: string | undefined;
-  let petLoadInFlight = false;
-  let petLoadingKey: string | undefined;
-  let petLoadNotify = false;
-  let queuedPetRefresh: { ctx: ExtensionContext; notify: boolean } | undefined;
-  let petTimer: ReturnType<typeof setTimeout> | undefined;
-  let petRenderRequestTimer: ReturnType<typeof setTimeout> | undefined;
-  let petRuntimeState: PetState = "idle";
-  let petPreviewState: PetState | undefined;
-  let petSettingsPreviewActive = false;
-  let petSettingsPets: CodexPetPackage[] = [];
-  let petFlashState: PetState | undefined;
-  let petFlashUntil: number | undefined;
-  let petFlashTimer: ReturnType<typeof setTimeout> | undefined;
-  let petIdleEmoteTimer: ReturnType<typeof setTimeout> | undefined;
-  let petResizeTimer: ReturnType<typeof setTimeout> | undefined;
-  let petResizeFreezeUntil = 0;
-  let stdoutResizeHandler: (() => void) | undefined;
-  let petAnimationState: PetState | undefined;
-  let petAnimationStartedAt = Date.now();
-  const petRenderCache = new Map<string, string[]>();
-  const activeToolCallIds = new Set<string>();
-  const petImageId = 0x70657401;
-  const petKittyManager = new CodexPetKittyManager(petImageId);
+  let contextUsageCached = false;
+  let cachedContextUsage: ReturnType<ExtensionContext["getContextUsage"]>;
+  let cachedContextLeafId: string | null | undefined;
+  let cachedContextModel: ExtensionContext["model"];
+  let sessionNameCached = false;
+  let cachedSessionNameLeafId: string | null | undefined;
+  let cachedSessionName: string | undefined;
+  const usageController = new UsageController(config, updateFooter);
+  const petController = new PetFooterController(config, updateFooter, () => footerInstalled);
 
   function refresh(ctx: ExtensionContext): ResolvedConfig {
     cachedConfig = resolveConfig(ctx.cwd || process.cwd());
@@ -407,413 +286,38 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   }
 
   function persist(nextConfig: ResolvedConfig): void {
-    cachedConfig = { ...nextConfig, active, desiredActive };
+    cachedConfig = {
+      ...nextConfig,
+      active: fastController.active,
+      desiredActive: fastController.desiredActive,
+    };
     if (!nextConfig.persistState) return;
     writeConfig(nextConfig.configPath, {
       ...readRawConfig(nextConfig.configPath),
-      active,
-      desiredActive,
+      active: fastController.active,
+      desiredActive: fastController.desiredActive,
     });
   }
 
-  function shouldLoadPetForConfig(cfg: ResolvedConfig): boolean {
-    return cfg.pets.enabled || petSettingsPreviewActive;
-  }
-
-  function shouldRenderPetInFooter(cfg: ResolvedConfig): boolean {
-    return cfg.pets.enabled || (petSettingsPreviewActive && footerInstalled);
-  }
-
-  function setPetSettingsPreviewActive(ctx: ExtensionContext, next: boolean): void {
-    if (petSettingsPreviewActive === next) return;
-    petSettingsPreviewActive = next;
-    if (!config(ctx).pets.enabled) petLoadKey = undefined;
-    void refreshPet(ctx, config(ctx)).then(() => {
-      if (!shouldRenderPetInFooter(config(ctx))) flushPetKittyCleanupNow();
-      requestSettingsRender?.();
-    });
-    updateFooter(ctx);
-  }
-
-  function petStateAnimationDurationMs(state: PetState): number {
-    return PET_ANIMATION_ROWS[state].durations.reduce((sum, duration) => sum + duration, 0);
-  }
-
-  function clearPetFlash(): void {
-    if (petFlashTimer) clearTimeout(petFlashTimer);
-    petFlashTimer = undefined;
-    petFlashState = undefined;
-    petFlashUntil = undefined;
-    petAnimationState = undefined;
-  }
-
-  function stopPetIdleEmotes(): void {
-    if (petIdleEmoteTimer) clearTimeout(petIdleEmoteTimer);
-    petIdleEmoteTimer = undefined;
-  }
-
-  function resetPetRenderCache(): void {
-    petRenderCache.clear();
-  }
-
-  function queuePetKittyCleanup(target = pet): void {
-    petKittyManager.invalidate(target);
-  }
-
-  function takePetKittyCleanupSequence(): string {
-    return petKittyManager.takeCleanupSequence();
-  }
-
-  function withPendingPetKittyCleanup(lines: string[]): string[] {
-    const sequence = takePetKittyCleanupSequence();
-    if (!sequence) return lines;
-    if (lines.length === 0) return [sequence];
-    return [`${sequence}\x1b[0m${lines[0]}\x1b[0m`, ...lines.slice(1)];
-  }
-
-  function writePetKittySequence(sequence: string): void {
-    if (sequence && process.stdout.isTTY) process.stdout.write(sequence);
-  }
-
-  function flushPetKittyCleanupNow(): void {
-    writePetKittySequence(takePetKittyCleanupSequence());
-  }
-
-  function disposePetKittyNow(target = pet): void {
-    writePetKittySequence(petKittyManager.dispose(target));
-  }
-
-  function rememberPetRender(key: string, lines: string[]): void {
-    petRenderCache.set(key, lines);
-    while (petRenderCache.size > PET_RENDER_CACHE_LIMIT) {
-      const firstKey = petRenderCache.keys().next().value;
-      if (firstKey === undefined) break;
-      petRenderCache.delete(firstKey);
-    }
-  }
-
-  function petResizeFrozen(now = Date.now()): boolean {
-    return now < petResizeFreezeUntil;
-  }
-
-  function clearPetResizeFreeze(): void {
-    if (petResizeTimer) clearTimeout(petResizeTimer);
-    petResizeTimer = undefined;
-    petResizeFreezeUntil = 0;
-  }
-
-  function freezePetForResize(ctx: ExtensionContext, now = Date.now()): void {
-    petResizeFreezeUntil = now + PET_RESIZE_FREEZE_MS;
-    queuePetKittyCleanup();
-    stopPetAnimation();
-    stopPetIdleEmotes();
-    stopPendingPetRenderRequest();
-    if (petResizeTimer) clearTimeout(petResizeTimer);
-    petResizeTimer = setTimeout(() => {
-      petResizeTimer = undefined;
-      petResizeFreezeUntil = 0;
-      petKittyManager.resetForResize(pet);
-      resetPetRenderCache();
-      updateFooter(ctx);
-    }, PET_RESIZE_FREEZE_MS);
-    petResizeTimer.unref?.();
-  }
-
-  function installPetResizeGuard(ctx: ExtensionContext): void {
-    if (stdoutResizeHandler || !process.stdout.isTTY) return;
-    stdoutResizeHandler = () => freezePetForResize(ctx);
-    process.stdout.on("resize", stdoutResizeHandler);
-  }
-
-  function uninstallPetResizeGuard(): void {
-    if (stdoutResizeHandler) process.stdout.off("resize", stdoutResizeHandler);
-    stdoutResizeHandler = undefined;
-    clearPetResizeFreeze();
-  }
-
-  function currentPetState(ctx: ExtensionContext, cfg = config(ctx)): PetState {
-    if (petPreviewState) return petPreviewState;
-    const now = Date.now();
-    if (petFlashState && petFlashUntil !== undefined && now < petFlashUntil) return petFlashState;
-    if (petFlashState) clearPetFlash();
-    return petRuntimeState === "idle" ? cfg.pets.state : petRuntimeState;
-  }
-
-  function currentPetAnimation(ctx: ExtensionContext, cfg = config(ctx)) {
-    const state = currentPetState(ctx, cfg);
-    const now = Date.now();
-    if (state !== petAnimationState) {
-      petAnimationState = state;
-      petAnimationStartedAt = now;
-    }
-    return { state, elapsedMs: now - petAnimationStartedAt };
-  }
-
-  function stopPetAnimation(): void {
-    if (petTimer) clearTimeout(petTimer);
-    petTimer = undefined;
-  }
-
-  function stopPendingPetRenderRequest(): void {
-    if (petRenderRequestTimer) clearTimeout(petRenderRequestTimer);
-    petRenderRequestTimer = undefined;
-  }
-
-  function requestPetFooterRender(): void {
-    if (petRenderRequestTimer) return;
-    petRenderRequestTimer = setTimeout(() => {
-      petRenderRequestTimer = undefined;
-      requestFooterRender?.();
-      requestSettingsRender?.();
-    }, 16);
-    petRenderRequestTimer.unref?.();
-  }
-
-  function schedulePetAnimation(ctx: ExtensionContext): void {
-    if (!pet || petTimer || petResizeFrozen() || !getCapabilities().images) return;
-    const { state, elapsedMs } = currentPetAnimation(ctx);
-    const frames = pet.states[state] ?? pet.states.idle;
-    petTimer = setTimeout(
-      () => {
-        petTimer = undefined;
-        if (petResizeFrozen()) return;
-        requestPetFooterRender();
-        schedulePetAnimation(ctx);
-      },
-      nextAnimationFrameDelayMs(frames, elapsedMs),
-    );
-    petTimer.unref?.();
-  }
-
-  function startPetAnimation(ctx: ExtensionContext): void {
-    schedulePetAnimation(ctx);
-    void refreshPet(ctx);
-  }
-
-  function shouldRunIdleEmotes(ctx: ExtensionContext, cfg = config(ctx)): boolean {
-    return (
-      cfg.pets.enabled &&
-      cfg.pets.idleEmotes &&
-      getCapabilities().images !== null &&
-      pet !== undefined &&
-      petRuntimeState === "idle" &&
-      activeToolCallIds.size === 0 &&
-      petPreviewState === undefined &&
-      !petSettingsPreviewActive &&
-      petFlashState === undefined &&
-      !petResizeFrozen()
-    );
-  }
-
-  function playPetFlash(ctx: ExtensionContext, state: PetState, cfg = config(ctx)): void {
-    if (!cfg.pets.enabled || !getCapabilities().images) return;
-    clearPetFlash();
-    const durationMs = petStateAnimationDurationMs(state);
-    petFlashState = state;
-    petFlashUntil = Date.now() + durationMs;
-    petFlashTimer = setTimeout(() => {
-      petFlashTimer = undefined;
-      petFlashState = undefined;
-      petFlashUntil = undefined;
-      petAnimationState = undefined;
-      updateFooter(ctx);
-    }, durationMs);
-    petFlashTimer.unref?.();
-    updateFooter(ctx);
-  }
-
-  function schedulePetIdleEmote(ctx: ExtensionContext, cfg = config(ctx)): void {
-    if (petIdleEmoteTimer || !shouldRunIdleEmotes(ctx, cfg)) return;
-    const delayMs = Math.round(cfg.pets.idleEmoteIntervalMs * (0.75 + Math.random() * 0.75));
-    petIdleEmoteTimer = setTimeout(() => {
-      petIdleEmoteTimer = undefined;
-      const nextConfig = config(ctx);
-      if (shouldRunIdleEmotes(ctx, nextConfig)) {
-        playPetFlash(ctx, randomIdleEmoteState(nextConfig.pets.state), nextConfig);
-      }
-      schedulePetIdleEmote(ctx, nextConfig);
-    }, delayMs);
-    petIdleEmoteTimer.unref?.();
-  }
-
-  function petLoadKeyForConfig(cfg: ResolvedConfig): string {
-    const cellDimensions = getCellDimensions();
-    return [
-      cfg.pets.slug || "__first__",
-      cfg.pets.sizeCells,
-      getCapabilities().images ?? "none",
-      cellDimensions.widthPx,
-      cellDimensions.heightPx,
-    ].join(":");
-  }
-
-  async function refreshPet(
-    ctx: ExtensionContext,
-    cfg = config(ctx),
-    notify = false,
-  ): Promise<void> {
-    if (shuttingDown) return;
-    if (!shouldLoadPetForConfig(cfg)) {
-      queuedPetRefresh = undefined;
-      queuePetKittyCleanup();
-      pet = undefined;
-      petError = undefined;
-      petLoadKey = undefined;
-      resetPetRenderCache();
-      clearPetFlash();
-      stopPetIdleEmotes();
-      stopPetAnimation();
-      return;
-    }
-
-    const key = petLoadKeyForConfig(cfg);
-    if (petLoadKey === key) return;
-    if (petLoadInFlight) {
-      if (petLoadingKey === key) petLoadNotify ||= notify;
-      else queuedPetRefresh = { ctx, notify: queuedPetRefresh?.notify || notify };
-      return;
-    }
-
-    petLoadInFlight = true;
-    petLoadingKey = key;
-    petLoadNotify = notify;
-    petError = undefined;
-    const previousPet = pet;
-
-    function shouldApplyLoadResult(): boolean {
-      if (shuttingDown || queuedPetRefresh) return false;
-      const latestConfig = config(ctx);
-      return shouldLoadPetForConfig(latestConfig) && petLoadKeyForConfig(latestConfig) === key;
-    }
-
-    try {
-      const loadedPet = await loadCodexPet(cfg.pets.slug || undefined, undefined, {
-        sizeCells: cfg.pets.sizeCells,
-      });
-      if (!shouldApplyLoadResult()) return;
-      if (previousPet) queuePetKittyCleanup(previousPet);
-      pet = loadedPet;
-      const petIssue = pet
-        ? undefined
-        : describeCodexPetSelectionIssue(await listCodexPets(), cfg.pets.slug || undefined);
-      petAnimationState = undefined;
-      resetPetRenderCache();
-      petLoadKey = key;
-      if (!pet && petIssue) petError = petIssue.short;
-      if (petLoadNotify) {
-        ctx.ui.notify(
-          pet
-            ? `Rendering ${pet.pet.name} in the Better OpenAI footer.`
-            : (petIssue?.message ?? "No ready custom Codex pet found."),
-          pet ? "info" : "warning",
-        );
-      }
-    } catch (error) {
-      if (!shouldApplyLoadResult()) return;
-      if (previousPet) queuePetKittyCleanup(previousPet);
-      pet = undefined;
-      petLoadKey = key;
-      petError = error instanceof Error ? error.message : String(error);
-      if (petLoadNotify) ctx.ui.notify(`Could not render Codex pet: ${petError}`, "warning");
-    } finally {
-      petLoadInFlight = false;
-      petLoadingKey = undefined;
-      petLoadNotify = false;
-      const queued = queuedPetRefresh;
-      queuedPetRefresh = undefined;
-      if (queued && !shuttingDown) void refreshPet(queued.ctx, config(queued.ctx), queued.notify);
-      if (!shuttingDown) updateFooter(ctx);
-    }
-  }
-
   function writePetConfig(ctx: ExtensionContext, patch: Record<string, unknown>): ResolvedConfig {
     const cfg = refresh(ctx);
     const current = readRawConfig(cfg.configPath);
     const pets = isRecord(current.pets) ? current.pets : {};
     writeConfig(cfg.configPath, { ...current, pets: { ...pets, ...patch } });
-    petLoadKey = undefined;
+    petController.invalidateLoadKey();
     return refresh(ctx);
   }
 
-  function applyDesiredFastState(ctx: ExtensionContext, cfg = config(ctx)): void {
-    active = desiredActive && supportsFast(ctx, cfg.supportedModels);
-  }
-
   function setActive(ctx: ExtensionContext, next: boolean): void {
     const nextConfig = refresh(ctx);
-    desiredActive = next;
-    applyDesiredFastState(ctx, nextConfig);
+    fastController.setDesired(ctx, nextConfig, next);
     persist(nextConfig);
     updateFooter(ctx);
-    if (next && !active) {
-      ctx.ui.notify(
-        `Fast mode requested, but ${currentModelKey(ctx)} is unsupported. It will activate automatically when you switch to a supported model: ${modelList(nextConfig.supportedModels)}.`,
-        "warning",
-      );
-      return;
-    }
-    ctx.ui.notify(stateText(ctx, desiredActive, active, nextConfig.supportedModels), "info");
-  }
-
-  async function refreshUsage(
-    ctx: ExtensionContext,
-    modelId = ctx.model?.id,
-    options?: { notify?: boolean },
-  ): Promise<void> {
-    if (shuttingDown || !ctx.hasUI) return;
-    if (usageRefreshInFlight) {
-      queuedUsageRefresh = { ctx, modelId, notify: queuedUsageRefresh?.notify || options?.notify };
+    if (next && !fastController.active) {
+      ctx.ui.notify(fastController.unsupportedRequestMessage(ctx, nextConfig), "warning");
       return;
     }
-    usageRefreshInFlight = true;
-    const cfg = config(ctx);
-    try {
-      if (!cfg.usage.enabled) {
-        usageSnapshot = undefined;
-        usageError = "Usage display is disabled.";
-        if (!shuttingDown) updateFooter(ctx);
-        return;
-      }
-      if (!isOpenAISubscriptionModel(ctx, cfg)) {
-        if (!shuttingDown) updateFooter(ctx);
-        return;
-      }
-      usageAbortController = new AbortController();
-      const timeoutSignal = AbortSignal.timeout(10_000);
-      const signal = ctx.signal
-        ? AbortSignal.any([ctx.signal, timeoutSignal, usageAbortController.signal])
-        : AbortSignal.any([timeoutSignal, usageAbortController.signal]);
-      const data = await requestCodexUsage(signal);
-      usageLastFetchAt = Date.now();
-      usageSnapshot = data ? parseUsageSnapshot(data, modelId) : undefined;
-      usageUpdatedAt = usageSnapshot ? Date.now() : undefined;
-      usageError = data ? undefined : `Missing openai-codex OAuth credentials in ${AUTH_FILE}.`;
-      if (!shuttingDown) updateFooter(ctx);
-      if (!shuttingDown && options?.notify)
-        ctx.ui.notify(formatUsageStatus(ctx), usageSnapshot ? "info" : "warning");
-    } catch (error) {
-      if (shuttingDown) return;
-      usageError = error instanceof Error ? error.message : String(error);
-      updateFooter(ctx);
-      if (options?.notify) ctx.ui.notify(formatUsageStatus(ctx), "warning");
-    } finally {
-      usageAbortController = undefined;
-      usageRefreshInFlight = false;
-      if (!shuttingDown && queuedUsageRefresh) {
-        const next = queuedUsageRefresh;
-        queuedUsageRefresh = undefined;
-        void refreshUsage(next.ctx, next.modelId, { notify: next.notify });
-      }
-    }
-  }
-
-  function startUsageRefresh(ctx: ExtensionContext): void {
-    if (usageTimer) clearInterval(usageTimer);
-    const cfg = config(ctx);
-    if (!cfg.usage.enabled) return;
-    void refreshUsage(ctx);
-    usageTimer = setInterval(() => void refreshUsage(ctx), cfg.usage.refreshIntervalMs);
-    usageTimer.unref?.();
+    ctx.ui.notify(fastController.stateText(ctx, nextConfig), "info");
   }
 
   function refreshFooterTotals(ctx: ExtensionContext): void {
@@ -828,35 +332,39 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     }
   }
 
-  function formatUsageDebug(ctx: ExtensionContext): string {
-    const cfg = config(ctx);
-    const auth = readCodexAuth();
-    return [
-      `Usage enabled: ${cfg.usage.enabled}`,
-      `Current model: ${currentModelKey(ctx)}`,
-      `Current model eligible: ${isOpenAISubscriptionModel(ctx, cfg)}`,
-      `Requires subscription model: ${cfg.usage.showOnlyOnSubscriptionModels}`,
-      `Auth: ${auth ? "found" : "missing"}`,
-      `Account ID: ${auth?.accountId ?? "none"}`,
-      `Last fetch: ${usageLastFetchAt ? new Date(usageLastFetchAt).toLocaleTimeString() : "never"}`,
-      `Last successful update: ${usageUpdatedAt ? new Date(usageUpdatedAt).toLocaleTimeString() : "never"}`,
-      `Last error: ${usageError ?? "none"}`,
-      `Refresh interval: ${cfg.usage.refreshIntervalMs}ms`,
-      `Endpoint: https://chatgpt.com/backend-api/wham/usage`,
-    ].join("\n");
+  function invalidateContextUsage(): void {
+    contextUsageCached = false;
+    cachedContextUsage = undefined;
+    cachedContextLeafId = undefined;
+    cachedContextModel = undefined;
   }
 
-  function formatUsageStatus(ctx: ExtensionContext): string {
-    const cfg = config(ctx);
-    if (!cfg.usage.enabled) return "Usage display is disabled.";
-    if (!isOpenAISubscriptionModel(ctx, cfg))
-      return "Usage hidden: current model is not an OpenAI subscription model.";
-    if (!usageSnapshot) return `Usage unavailable${usageError ? `: ${usageError}` : "."}`;
-    const stale =
-      usageUpdatedAt && Date.now() - usageUpdatedAt > cfg.usage.refreshIntervalMs * 2
-        ? ` | stale ${formatResetCountdown((Date.now() - usageUpdatedAt) / 1000)}`
-        : "";
-    return `${formatUsageSnapshot(usageSnapshot, cfg.usage)}${stale}`;
+  function contextUsage(ctx: ExtensionContext): ReturnType<ExtensionContext["getContextUsage"]> {
+    const leafId = ctx.sessionManager.getLeafId();
+    const model = ctx.model;
+    if (!contextUsageCached || leafId !== cachedContextLeafId || model !== cachedContextModel) {
+      cachedContextUsage = ctx.getContextUsage();
+      contextUsageCached = true;
+      cachedContextLeafId = leafId;
+      cachedContextModel = model;
+    }
+    return cachedContextUsage;
+  }
+
+  function sessionName(ctx: ExtensionContext): string | undefined {
+    const leafId = ctx.sessionManager.getLeafId();
+    if (!sessionNameCached || leafId !== cachedSessionNameLeafId) {
+      cachedSessionName = ctx.sessionManager.getSessionName();
+      cachedSessionNameLeafId = leafId;
+      sessionNameCached = true;
+    }
+    return cachedSessionName;
+  }
+
+  function invalidateSessionName(): void {
+    sessionNameCached = false;
+    cachedSessionNameLeafId = undefined;
+    cachedSessionName = undefined;
   }
 
   pi.registerFlag(FLAG, {
@@ -868,15 +376,10 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   function formatDebugStatus(ctx: ExtensionContext): string {
     const cfg = config(ctx);
     return [
-      `Fast desired: ${desiredActive}`,
-      `Fast active: ${active}`,
-      `Current model: ${currentModelKey(ctx)}`,
-      `Supported model: ${supportsFast(ctx, cfg.supportedModels)}`,
-      `Configured service_tier: ${SERVICE_TIER}`,
-      `Last injected: ${lastInjectedAt ? `${new Date(lastInjectedAt).toLocaleTimeString()} (${lastInjectedModel}, ${lastInjectedTier})` : "never"}`,
+      ...fastController.debugLines(ctx, cfg),
       `Footer mode: ${cfg.footer.mode}`,
       "",
-      formatUsageDebug(ctx),
+      usageController.formatDebug(ctx),
       "",
       `Image enabled: ${cfg.image.enabled}`,
       `Image default save: ${cfg.image.defaultSave}`,
@@ -885,22 +388,17 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       `Pet placement: ${cfg.pets.placement}`,
       `Pet failed tool state: ${cfg.pets.failedToolState}`,
       `Pet idle emotes: ${cfg.pets.idleEmotes} (${cfg.pets.idleEmoteIntervalMs}ms)`,
-      `Pet loaded: ${pet?.pet.name ?? "none"}`,
-      `Pet error: ${petError ?? "none"}`,
+      `Pet loaded: ${petController.loadedPet?.pet.name ?? "none"}`,
+      `Pet error: ${petController.error ?? "none"}`,
       `Config: ${cfg.configPath}`,
     ].join("\n");
   }
 
-  function formatOpenAIStatus(ctx: ExtensionContext): string {
-    refresh(ctx);
-    return formatUsageStatus(ctx);
-  }
-
   pi.registerCommand(COMMAND, {
     description: "Toggle OpenAI fast mode",
     handler: async (args, ctx) => {
       const arg = args.trim().toLowerCase();
-      if (!arg) return setActive(ctx, !desiredActive);
+      if (!arg) return setActive(ctx, !fastController.desiredActive);
       ctx.ui.notify("Usage: /fast", "error");
     },
   });
@@ -908,98 +406,18 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   pi.registerCommand(OPENAI_STATUS_COMMAND, {
     description: "Show OpenAI subscription usage status",
     handler: async (_args, ctx) => {
-      ctx.ui.notify(formatOpenAIStatus(ctx), "info");
+      await usageController.refresh(ctx, ctx.model?.id, { notify: true, force: true });
     },
   });
 
-  function textPanel(title: string, lines: string[], done: () => void) {
-    return {
-      render(width: number) {
-        const clipped = lines.map((line) => truncateToWidth(line, width, "..."));
-        return [title, "", ...clipped, "", "Esc/q to go back"];
-      },
-      invalidate() {},
-      handleInput(data: string) {
-        if (data.includes("\x1b") || data === "escape" || data === "q" || data === "\x03") done();
-      },
-    };
-  }
-
   function buildPetSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
-    return [
-      {
-        id: "pets.enabled",
-        label: "Enabled",
-        currentValue: String(cfg.pets.enabled),
-        values: ["true", "false"],
-        description:
-          "Render a custom Codex pet from ${CODEX_HOME:-~/.codex}/pets in the Better OpenAI footer.",
-      },
-      {
-        id: "pets.slug",
-        label: "Pet",
+    return settingsItemsFromDescriptors(PET_SETTING_DESCRIPTORS, cfg, {
+      "pets.slug": {
         currentValue: petConfigPickerValue(cfg),
-        values: readyPetPickerValues(petSettingsPets),
-        description: petPickerDescription(cfg, petSettingsPets),
-      },
-      {
-        id: "pets.placement",
-        label: "Placement",
-        currentValue: cfg.pets.placement,
-        values: [...PET_PLACEMENTS],
-        description:
-          "Footer layout: stacked, inline-left, inline-right, badge, or habitat divider.",
-      },
-      {
-        id: "pets.state",
-        label: "Idle state",
-        currentValue: cfg.pets.state,
-        values: [...PET_STATES],
-        description: "Animation row to show when pi is idle.",
-      },
-      {
-        id: "pets.thinkingState",
-        label: "Thinking state",
-        currentValue: cfg.pets.thinkingState,
-        values: [...PET_STATES],
-        description: "Animation row to show while the model is thinking or streaming.",
-      },
-      {
-        id: "pets.toolState",
-        label: "Tool state",
-        currentValue: cfg.pets.toolState,
-        values: [...PET_STATES],
-        description: "Animation row to show during tool execution.",
-      },
-      {
-        id: "pets.failedToolState",
-        label: "Failed tool state",
-        currentValue: cfg.pets.failedToolState,
-        values: [...PET_STATES],
-        description: "Animation row to flash after any tool call returns an error.",
-      },
-      {
-        id: "pets.idleEmotes",
-        label: "Random idle emotes",
-        currentValue: String(cfg.pets.idleEmotes),
-        values: ["true", "false"],
-        description: "Occasionally flash a wave or jump while pi is idle.",
-      },
-      {
-        id: "pets.idleEmoteIntervalMs",
-        label: "Idle emote interval",
-        currentValue: String(cfg.pets.idleEmoteIntervalMs),
-        values: ["5000", "15000", "30000", "60000", "120000", "300000"],
-        description: "Average delay between random idle pet emotes in milliseconds.",
+        values: readyPetPickerValues(petController.settingsPets),
+        description: petPickerDescription(cfg, petController.settingsPets),
       },
-      {
-        id: "pets.sizeCells",
-        label: "Size",
-        currentValue: String(cfg.pets.sizeCells),
-        values: ["4", "6", "8", "10", "12", "16"],
-        description: "Pet image width in terminal cells.",
-      },
-    ];
+    });
   }
 
   function petPreviewFromItem(item: SettingsPickerItem | undefined): PetState | undefined {
@@ -1015,23 +433,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   }
 
   function renderPetSettingsPreview(ctx: ExtensionContext, width: number): string[] {
-    if (!petSettingsPreviewActive || shouldRenderPetInFooter(config(ctx))) return [];
-    if (!pet) {
-      return [petError ? `Preview unavailable: ${petError}` : "Preview: loading pet…"];
-    }
-    const cfg = config(ctx);
-    const { state, elapsedMs } = currentPetAnimation(ctx, cfg);
-    const plainTheme = { fg: (_color: string, value: string) => value };
-    return [
-      `Preview: ${pet.pet.name}`,
-      ...renderCodexPetFrame(pet, state, width, plainTheme, {
-        sizeCells: cfg.pets.sizeCells,
-        imageId: petImageId,
-        now: elapsedMs,
-        durationMultiplier: 1,
-        kittyManager: petKittyManager,
-      }),
-    ];
+    return petController.renderSettingsPreview(ctx, width);
   }
 
   function settingsSubmenu(
@@ -1206,10 +608,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   }
 
   function fastSettingsSummary(ctx: ExtensionContext, cfg: ResolvedConfig): string {
-    if (active) return "on";
-    if (desiredActive)
-      return supportsFast(ctx, cfg.supportedModels) ? "requested" : "requested inactive";
-    return "off";
+    return fastController.settingsSummary(ctx, cfg);
   }
 
   function usageSettingsSummary(cfg: ResolvedConfig): string {
@@ -1230,113 +629,52 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     return `${status} · ${selected} · ${cfg.pets.placement}`;
   }
 
-  function buildFastSettingsItems(
-    ctx: ExtensionContext,
+  type SettingsItemOverrides = Record<
+    string,
+    Partial<Pick<SettingsPickerItem, "currentValue" | "description" | "values">>
+  >;
+
+  function settingsItemsFromDescriptors(
+    descriptors: readonly SettingsOptionDescriptor[],
     cfg: ResolvedConfig,
+    overrides: SettingsItemOverrides = {},
   ): SettingsPickerItem[] {
+    return descriptors.map((descriptor) => {
+      const override = overrides[descriptor.id] ?? {};
+      const values = override.values ?? descriptor.values;
+      return {
+        id: descriptor.id,
+        label: descriptor.label,
+        currentValue: override.currentValue ?? descriptor.currentValue(cfg),
+        values: values ? [...values] : undefined,
+        description: override.description ?? descriptor.description,
+      };
+    });
+  }
+
+  function buildFastSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
     return [
       {
         id: "fast.enabled",
         label: "Fast mode",
-        currentValue: String(desiredActive),
+        currentValue: String(fastController.desiredActive),
         values: ["true", "false"],
         description: `Request OpenAI fast mode. Activates for supported models: ${modelList(cfg.supportedModels)}.`,
       },
-      {
-        id: "persistState",
-        label: "Persist fast state",
-        currentValue: String(cfg.persistState),
-        values: ["true", "false"],
-        description: "Remember fast-mode state across sessions.",
-      },
+      ...settingsItemsFromDescriptors(FAST_SETTING_DESCRIPTORS, cfg),
     ];
   }
 
   function buildFooterSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
-    return [
-      {
-        id: "footer.mode",
-        label: "Footer mode",
-        currentValue: cfg.footer.mode,
-        values: [...FOOTER_MODES],
-        description:
-          "replace = custom footer, status = pi footer plus status line, off = no Better OpenAI footer/status unless Footer pet is enabled.",
-      },
-    ];
+    return settingsItemsFromDescriptors(FOOTER_SETTING_DESCRIPTORS, cfg);
   }
 
   function buildUsageSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
-    return [
-      {
-        id: "usage.enabled",
-        label: "Usage display",
-        currentValue: String(cfg.usage.enabled),
-        values: ["true", "false"],
-        description: "Fetch and display OpenAI subscription usage windows.",
-      },
-      {
-        id: "usage.refreshIntervalMs",
-        label: "Usage refresh",
-        currentValue: String(cfg.usage.refreshIntervalMs),
-        values: ["15000", "30000", "60000", "120000", "300000", "600000"],
-        description: "Usage refresh interval in milliseconds.",
-      },
-      {
-        id: "usage.showOnlyOnSubscriptionModels",
-        label: "Usage only on OAuth",
-        currentValue: String(cfg.usage.showOnlyOnSubscriptionModels),
-        values: ["true", "false"],
-        description: "Only show usage when the current OpenAI model uses subscription/OAuth auth.",
-      },
-      {
-        id: "usage.showResetTimes",
-        label: "Usage reset times",
-        currentValue: String(cfg.usage.showResetTimes),
-        values: ["true", "false"],
-        description: "Include compact reset countdowns and local reset times.",
-      },
-    ];
+    return settingsItemsFromDescriptors(USAGE_SETTING_DESCRIPTORS, cfg);
   }
 
   function buildImageSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
-    return [
-      {
-        id: "image.enabled",
-        label: "Image tool",
-        currentValue: String(cfg.image.enabled),
-        values: ["true", "false"],
-        description: "Allow the openai_image tool to make image requests.",
-      },
-      {
-        id: "image.defaultModel",
-        label: "Image model",
-        currentValue: cfg.image.defaultModel,
-        values: ["gpt-5.5", "gpt-5.4", "gpt-5.2", "gpt-5"],
-        description:
-          "Mainline model used for image generation when current model is not openai-codex.",
-      },
-      {
-        id: "image.defaultSave",
-        label: "Image save",
-        currentValue: cfg.image.defaultSave,
-        values: [...IMAGE_SAVE_MODES],
-        description: "Where generated images are saved by default.",
-      },
-      {
-        id: "image.outputFormat",
-        label: "Image format",
-        currentValue: cfg.image.outputFormat,
-        values: [...IMAGE_OUTPUT_FORMATS],
-        description: "Generated image file format.",
-      },
-      {
-        id: "image.timeoutMs",
-        label: "Image timeout",
-        currentValue: String(cfg.image.timeoutMs),
-        values: ["30000", "60000", "120000", "180000", "300000"],
-        description: "Image request timeout in milliseconds.",
-      },
-    ];
+    return settingsItemsFromDescriptors(IMAGE_SETTING_DESCRIPTORS, cfg);
   }
 
   function buildDiagnosticsSettingsItems(
@@ -1362,11 +700,13 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         id: "config.print",
         label: "Print config",
         currentValue: "open",
-        description: "Show the selected raw config JSON.",
+        description: "Show the selected config JSON with sensitive fields redacted.",
         submenu: (_value, done) =>
           textPanel(
             "Config",
-            JSON.stringify(readRawConfig(cfg.configPath), null, 2).split("\n"),
+            JSON.stringify(redactDiagnosticValue(readRawConfig(cfg.configPath)), null, 2).split(
+              "\n",
+            ),
             () => done(),
           ),
       },
@@ -1383,7 +723,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         submenu: (_value, done) =>
           settingsSubmenu(
             "Fast mode settings",
-            () => buildFastSettingsItems(ctx, config(ctx)),
+            () => buildFastSettingsItems(config(ctx)),
             ctx,
             () => done(fastSettingsSummary(ctx, config(ctx))),
           ),
@@ -1433,7 +773,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         currentValue: petSettingsSummary(cfg),
         description: "Configure footer pet visibility, animation-state mapping, and size.",
         submenu: (_value, done) => {
-          setPetSettingsPreviewActive(ctx, true);
+          petController.setSettingsPreviewActive(ctx, true);
           return settingsSubmenu(
             "Footer pet settings",
             () => buildPetSettingsItems(config(ctx)),
@@ -1442,14 +782,14 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
             {
               onSelection: (item) => {
                 const previewState = petPreviewFromItem(item);
-                if (previewState !== petPreviewState) {
-                  petPreviewState = previewState;
+                if (previewState !== petController.previewState) {
+                  petController.setPreviewState(previewState);
                   updateFooter(ctx);
                 }
               },
               onClose: () => {
-                petPreviewState = undefined;
-                setPetSettingsPreviewActive(ctx, false);
+                petController.setPreviewState(undefined);
+                petController.setSettingsPreviewActive(ctx, false);
                 updateFooter(ctx);
               },
               renderExtra: (width) => renderPetSettingsPreview(ctx, width),
@@ -1477,79 +817,47 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     const cfg = refresh(ctx);
     const current = readRawConfig(cfg.configPath);
     const bool = rawValue === "true";
-    const num = Number(rawValue);
     if (id === "fast.enabled") {
-      desiredActive = bool;
-      applyDesiredFastState(ctx, cfg);
-      if (cfg.persistState) {
-        current.active = active;
-        current.desiredActive = desiredActive;
-      }
-    } else if (id === "persistState") current.persistState = bool;
-    else if (id.startsWith("usage.")) {
-      const usage = isRecord(current.usage) ? current.usage : {};
-      const key = id.slice("usage.".length);
-      usage[key] = key === "refreshIntervalMs" ? num : bool;
-      current.usage = usage;
-    } else if (id === "footer.mode") {
-      const footer = isRecord(current.footer) ? current.footer : {};
-      footer.mode = rawValue;
-      current.footer = footer;
-    } else if (id.startsWith("pets.")) {
-      const pets = isRecord(current.pets) ? current.pets : {};
-      const key = id.slice("pets.".length);
-      pets[key] =
-        key === "sizeCells" || key === "idleEmoteIntervalMs"
-          ? num
-          : key === "slug"
-            ? petSlugFromPickerValue(rawValue)
-            : rawValue === "true"
-              ? true
-              : rawValue === "false"
-                ? false
-                : rawValue;
-      current.pets = pets;
-      if (key === "enabled" || key === "sizeCells" || key === "slug") petLoadKey = undefined;
-      if (key === "placement" || key === "sizeCells" || key === "slug") resetPetRenderCache();
-      if (key === "idleEmotes" || key === "idleEmoteIntervalMs") stopPetIdleEmotes();
-    } else if (id.startsWith("image.")) {
-      const image = isRecord(current.image) ? current.image : {};
-      const key = id.slice("image.".length);
-      image[key] =
-        key === "timeoutMs"
-          ? num
-          : rawValue === "true"
-            ? true
-            : rawValue === "false"
-              ? false
-              : rawValue;
-      current.image = image;
+      fastController.setDesired(ctx, cfg, bool);
+    }
+    const petKey = id.startsWith("pets.") ? id.slice("pets.".length) : undefined;
+    const nextRawConfig = applySettingToRawConfig(current, id, rawValue, {
+      persistState: cfg.persistState,
+      active: fastController.active,
+      desiredActive: fastController.desiredActive,
+      petEmptyValue: PET_EMPTY_VALUE,
+    });
+    if (petKey) {
+      if (petKey === "enabled" || petKey === "sizeCells" || petKey === "slug")
+        petController.invalidateLoadKey();
+      if (petKey === "placement" || petKey === "sizeCells" || petKey === "slug")
+        petController.resetRenderCache();
+      if (petKey === "idleEmotes" || petKey === "idleEmoteIntervalMs")
+        petController.stopIdleEmotes();
     }
-    writeConfig(cfg.configPath, current);
+    writeConfig(cfg.configPath, nextRawConfig);
     const next = refresh(ctx);
     if (id === "pets.enabled" || id === "pets.sizeCells" || id === "pets.slug")
-      void refreshPet(ctx, next);
+      void petController.refresh(ctx, next);
     if (id.startsWith("usage.")) {
-      if (usageTimer) clearInterval(usageTimer);
-      usageTimer = undefined;
-      if (next.usage.enabled) startUsageRefresh(ctx);
-      else {
-        usageSnapshot = undefined;
-        usageError = "Usage display is disabled.";
-      }
+      usageController.restartAfterSettingsChange(ctx, next);
     }
     updateFooter(ctx);
   }
 
   async function showSettingsPicker(ctx: ExtensionContext): Promise<void> {
+    if (!hasTerminalUI(ctx)) {
+      ctx.ui.notify("Better OpenAI settings require interactive TUI mode.", "warning");
+      return;
+    }
     try {
-      petSettingsPets = await listCodexPets();
+      petController.settingsPets = await listCodexPets();
     } catch {
-      petSettingsPets = [];
+      petController.settingsPets = [];
     }
     try {
       await ctx.ui.custom((tui, theme, _kb, done) => {
-        requestSettingsRender = () => tui.requestRender();
+        petController.setSettingsRenderRequest(() => tui.requestRender());
         const container = new Container();
         container.addChild(
           new (class {
@@ -1595,12 +903,10 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         };
       });
     } finally {
-      requestSettingsRender = undefined;
-      if (petPreviewState !== undefined || petSettingsPreviewActive) {
-        petPreviewState = undefined;
-        setPetSettingsPreviewActive(ctx, false);
-        updateFooter(ctx);
-      }
+      petController.setSettingsRenderRequest(undefined);
+      petController.setPreviewState(undefined);
+      petController.setSettingsPreviewActive(ctx, false);
+      updateFooter(ctx);
     }
   }
 
@@ -1628,17 +934,16 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
         slug: selectedPet.slug,
       });
       updateFooter(ctx);
-      await refreshPet(ctx, next, true);
+      if (hasTerminalUI(ctx)) await petController.refresh(ctx, next, true);
+      else
+        ctx.ui.notify(
+          `Enabled ${selectedPet.name} (${selectedPet.slug}); footer pets render in interactive TUI mode.`,
+          "info",
+        );
     },
     tuck: (ctx) => {
       writePetConfig(ctx, { enabled: false });
-      queuePetKittyCleanup();
-      pet = undefined;
-      petError = undefined;
-      resetPetRenderCache();
-      clearPetFlash();
-      stopPetIdleEmotes();
-      stopPetAnimation();
+      petController.tuck();
       updateFooter(ctx);
       ctx.ui.notify("Footer pet tucked away.", "info");
     },
@@ -1659,8 +964,14 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
 
       const next = writePetConfig(ctx, { slug: selectedPet.slug });
       updateFooter(ctx);
-      if (shouldLoadPetForConfig(next)) await refreshPet(ctx, next, true);
-      else {
+      if (petController.shouldLoadForConfig(next)) {
+        if (hasTerminalUI(ctx)) await petController.refresh(ctx, next, true);
+        else
+          ctx.ui.notify(
+            `Selected ${selectedPet.name} (${selectedPet.slug}); footer pets render in interactive TUI mode.`,
+            "info",
+          );
+      } else {
         ctx.ui.notify(
           `Selected ${selectedPet.name} (${selectedPet.slug}) for the footer pet. Use /pets wake to show it.`,
           "info",
@@ -1671,36 +982,36 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
 
   function installFooter(ctx: ExtensionContext): void {
     if (footerInstalled) {
-      requestFooterRender?.();
+      petController.requestFooterRenderNow();
       return;
     }
     footerInstalled = true;
     ctx.ui.setFooter((tui, theme, footerData) => {
-      requestFooterRender = () => tui.requestRender();
+      petController.setFooterRenderRequest(() => tui.requestRender());
       const unsubscribe = footerData.onBranchChange?.(() => tui.requestRender());
       let lastFooterSizeKey: string | undefined;
       return {
         dispose: () => {
           unsubscribe?.();
-          stopPetIdleEmotes();
-          stopPetAnimation();
-          stopPendingPetRenderRequest();
-          disposePetKittyNow();
+          petController.stopIdleEmotes();
+          petController.stopAnimation();
+          petController.stopPendingRenderRequest();
+          petController.disposeKittyNow();
           footerInstalled = false;
-          requestFooterRender = undefined;
+          petController.setFooterRenderRequest(undefined);
         },
         invalidate() {
-          queuePetKittyCleanup();
-          resetPetRenderCache();
+          petController.queueKittyCleanup();
+          petController.resetRenderCache();
         },
         render(width: number): string[] {
           const now = Date.now();
           const footerSizeKey = `${width}:${process.stdout.rows ?? 0}`;
           if (lastFooterSizeKey !== undefined && lastFooterSizeKey !== footerSizeKey) {
-            freezePetForResize(ctx, now);
+            petController.freezeForResize(ctx, now);
           }
           lastFooterSizeKey = footerSizeKey;
-          const freezePetFrame = petResizeFrozen(now);
+          const freezePetFrame = petController.isResizeFrozen(now);
 
           const totalInput = footerTotals.input;
           const totalOutput = footerTotals.output;
@@ -1708,15 +1019,13 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           const totalCacheWrite = footerTotals.cacheWrite;
           const totalCost = footerTotals.cost;
 
-          let pwd = ctx.sessionManager.getCwd();
-          const home = process.env.HOME || process.env.USERPROFILE;
-          if (home && pwd.startsWith(home)) pwd = `~${pwd.slice(home.length)}`;
+          let pwd = abbreviateHomePath(ctx.sessionManager.getCwd());
 
           const branch = footerData.getGitBranch?.();
           if (branch) pwd = `${pwd} (${branch})`;
 
-          const sessionName = ctx.sessionManager.getSessionName();
-          if (sessionName) pwd = `${pwd} • ${sessionName}`;
+          const currentSessionName = sessionName(ctx);
+          if (currentSessionName) pwd = `${pwd} • ${currentSessionName}`;
 
           const parts: string[] = [];
           if (totalInput) parts.push(`↑${formatTokens(totalInput)}`);
@@ -1728,11 +1037,11 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           if (totalCost || usingSubscription)
             parts.push(`$${totalCost.toFixed(3)}${usingSubscription ? " (sub)" : ""}`);
 
-          const contextUsage = ctx.getContextUsage();
-          const contextWindow = contextUsage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
-          const contextPercentValue = contextUsage?.percent ?? 0;
+          const currentContextUsage = contextUsage(ctx);
+          const contextWindow = currentContextUsage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+          const contextPercentValue = currentContextUsage?.percent ?? 0;
           const contextPercent =
-            contextUsage?.percent !== null ? contextPercentValue.toFixed(1) : "?";
+            currentContextUsage?.percent !== null ? contextPercentValue.toFixed(1) : "?";
           const contextDisplay =
             contextPercent === "?"
               ? `?/${formatTokens(contextWindow)} (auto)`
@@ -1746,27 +1055,24 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           parts.push(contextText);
 
           const cfg = config(ctx);
-          const cfgForPets = cfg;
-          const shouldRenderPet = shouldRenderPetInFooter(cfgForPets);
-          const requestedPetPlacement = cfgForPets.pets.placement;
+          const shouldRenderPet = petController.shouldRenderInFooter(cfg);
+          const requestedPetPlacement = cfg.pets.placement;
           const requestedPetSizeCells = petSizeCellsForPlacement(
             requestedPetPlacement,
-            cfgForPets.pets.sizeCells,
+            cfg.pets.sizeCells,
           );
           const inlinePet = Boolean(
             shouldRenderPet &&
-            pet &&
+            petController.loadedPet &&
             isInlinePetPlacement(requestedPetPlacement) &&
             width >= requestedPetSizeCells + 32,
           );
-          const petRenderSizeCells = inlinePet ? requestedPetSizeCells : cfgForPets.pets.sizeCells;
+          const petRenderSizeCells = inlinePet ? requestedPetSizeCells : cfg.pets.sizeCells;
           const petColumnWidth = Math.min(petRenderSizeCells, Math.max(1, width - 1));
           const footerTextWidth = inlinePet ? Math.max(1, width - petColumnWidth - 2) : width;
 
-          let usageLine: string | undefined;
-          if (usageSnapshot && cfg.usage.enabled && isOpenAISubscriptionModel(ctx, cfg)) {
-            usageLine = theme.fg("dim", formatUsageSnapshot(usageSnapshot, cfg.usage));
-          }
+          const usageStatusLine = usageController.statusLine(ctx, cfg, usingSubscription);
+          const usageLine = usageStatusLine ? theme.fg("dim", usageStatusLine) : undefined;
 
           let statsLeft = parts.join(" ");
           let statsLeftWidth = visibleWidth(statsLeft);
@@ -1778,7 +1084,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
           const modelName = ctx.model?.id || "no-model";
           const thinkingLevel = pi.getThinkingLevel();
           const fastSuffix =
-            active && supportsFast(ctx, config(ctx).supportedModels) ? " fast" : "";
+            fastController.active && supportsFast(ctx, cfg.supportedModels) ? " fast" : "";
           let rightWithoutProvider = modelName;
           if (ctx.model?.reasoning) {
             rightWithoutProvider =
@@ -1835,65 +1141,21 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
             textLines.push(truncateToWidth(statusLine, footerTextWidth, theme.fg("dim", "...")));
           }
 
-          const petLines: string[] = [];
-          if (shouldRenderPet) {
-            if (pet) {
-              const { state: petState, elapsedMs } = currentPetAnimation(ctx, cfgForPets);
-              if (freezePetFrame) {
-                petLines.push(
-                  ...petPlaceholderLines(
-                    pet,
-                    petState,
-                    elapsedMs,
-                    petColumnWidth,
-                    petRenderSizeCells,
-                  ),
-                );
-              } else {
-                const { frameIndex } = petFrameInfo(pet, petState, elapsedMs);
-                const cacheKey = petRenderCacheKey(
-                  pet,
-                  petState,
-                  frameIndex,
-                  requestedPetPlacement,
-                  petColumnWidth,
-                  petRenderSizeCells,
-                );
-                const cachedPetLines = petRenderCache.get(cacheKey);
-                const imageProtocol = getCapabilities().images;
-                if (cachedPetLines) {
-                  petLines.push(...cachedPetLines);
-                } else {
-                  const renderedPetLines = renderCodexPetFrame(
-                    pet,
-                    petState,
-                    petColumnWidth,
-                    theme,
-                    {
-                      sizeCells: petRenderSizeCells,
-                      imageId: petImageId,
-                      now: elapsedMs,
-                      durationMultiplier: 1,
-                      kittyManager: petKittyManager,
-                    },
-                  );
-                  petLines.push(...renderedPetLines);
-                  if (renderedPetLines.length > 0) {
-                    if (imageProtocol !== null && imageProtocol !== "kitty")
-                      rememberPetRender(cacheKey, renderedPetLines);
-                  }
-                }
-              }
-            } else if (petError) {
-              petLines.push(truncateToWidth(theme.fg("warning", `pet: ${petError}`), width, "..."));
-            }
-          }
+          const petLines = petController.renderPetLines(ctx, cfg, {
+            shouldRenderPet,
+            freezePetFrame,
+            requestedPetPlacement,
+            petColumnWidth,
+            petRenderSizeCells,
+            width,
+            theme,
+          });
 
           if (!shouldRenderPet || petLines.length === 0)
-            return withPendingPetKittyCleanup(textLines);
+            return petController.withPendingKittyCleanup(textLines);
 
           if (inlinePet) {
-            return withPendingPetKittyCleanup(
+            return petController.withPendingKittyCleanup(
               combineInlinePetFooter(
                 petLines,
                 textLines,
@@ -1904,16 +1166,16 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
             );
           }
 
-          if (requestedPetPlacement === "habitat" && pet) {
-            const label = ` ${pet.pet.name} `;
+          if (requestedPetPlacement === "habitat" && petController.loadedPet) {
+            const label = ` ${petController.loadedPet.pet.name} `;
             const divider = theme.fg(
               "dim",
               truncateToWidth(`─${label}${"─".repeat(width)}`, width, ""),
             );
-            return withPendingPetKittyCleanup([divider, ...petLines, ...textLines]);
+            return petController.withPendingKittyCleanup([divider, ...petLines, ...textLines]);
           }
 
-          return withPendingPetKittyCleanup([...petLines, ...textLines]);
+          return petController.withPendingKittyCleanup([...petLines, ...textLines]);
         },
       };
     });
@@ -1921,10 +1183,10 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
 
   function clearFooter(ctx: ExtensionContext): void {
     if (!footerInstalled) return;
-    disposePetKittyNow();
+    petController.disposeKittyNow();
     ctx.ui.setFooter(undefined);
     footerInstalled = false;
-    requestFooterRender = undefined;
+    petController.setFooterRenderRequest(undefined);
   }
 
   function setStatus(ctx: ExtensionContext, text: string | undefined): void {
@@ -1935,13 +1197,20 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
 
   function updateFooter(ctx: ExtensionContext): void {
     const cfg = config(ctx);
-    const resizeFrozen = petResizeFrozen();
-    const shouldAnimatePet = shouldLoadPetForConfig(cfg);
-    const shouldRenderPet = shouldRenderPetInFooter(cfg);
-    stopPetAnimation();
-    if (shouldAnimatePet && !resizeFrozen) startPetAnimation(ctx);
-    if (!resizeFrozen && shouldRunIdleEmotes(ctx, cfg)) schedulePetIdleEmote(ctx, cfg);
-    else stopPetIdleEmotes();
+
+    if (!hasTerminalUI(ctx)) {
+      if (cfg.footer.mode === "off") {
+        setStatus(ctx, undefined);
+        return;
+      }
+      const fast = fastController.statusSegment(ctx, cfg);
+      const usage = usageController.statusLine(ctx, cfg);
+      setStatus(ctx, [fast, usage].filter(Boolean).join(" | ") || undefined);
+      return;
+    }
+
+    petController.updateActivity(ctx, cfg);
+    const shouldRenderPet = petController.shouldRenderInFooter(cfg);
 
     if (cfg.footer.mode === "replace" || shouldRenderPet) {
       setStatus(ctx, undefined);
@@ -1956,135 +1225,114 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       return;
     }
 
-    const fast =
-      active && supportsFast(ctx, cfg.supportedModels)
-        ? `${ctx.model?.id ?? "model"} fast`
-        : undefined;
-    const usage =
-      usageSnapshot && cfg.usage.enabled && isOpenAISubscriptionModel(ctx, cfg)
-        ? formatUsageSnapshot(usageSnapshot, cfg.usage)
-        : undefined;
+    const fast = fastController.statusSegment(ctx, cfg);
+    const usage = usageController.statusLine(ctx, cfg);
     setStatus(ctx, [fast, usage].filter(Boolean).join(" | ") || undefined);
   }
 
   pi.on("session_start", (_event, ctx) => {
+    invalidateContextUsage();
+    invalidateSessionName();
     const nextConfig = refresh(ctx);
-    desiredActive = nextConfig.persistState ? nextConfig.desiredActive : false;
-    if (pi.getFlag(FLAG) === true) desiredActive = true;
-    applyDesiredFastState(ctx, nextConfig);
-    if (desiredActive !== nextConfig.desiredActive || active !== nextConfig.active)
+    fastController.initializeForSession(ctx, nextConfig, pi.getFlag(FLAG) === true);
+    if (
+      fastController.desiredActive !== nextConfig.desiredActive ||
+      fastController.active !== nextConfig.active
+    )
       persist(nextConfig);
-    if (desiredActive && !active) {
-      ctx.ui.notify(
-        `Fast mode requested, but ${currentModelKey(ctx)} is unsupported. It will activate automatically when you switch to a supported model: ${modelList(nextConfig.supportedModels)}.`,
-        "warning",
-      );
+    if (fastController.desiredActive && !fastController.active) {
+      ctx.ui.notify(fastController.unsupportedRequestMessage(ctx, nextConfig), "warning");
     }
-    installPetResizeGuard(ctx);
+    if (hasTerminalUI(ctx)) petController.installResizeGuard(ctx);
     refreshFooterTotals(ctx);
     updateFooter(ctx);
-    if (nextConfig.pets.enabled) void refreshPet(ctx, nextConfig);
-    startUsageRefresh(ctx);
-    if (active)
-      ctx.ui.notify(stateText(ctx, desiredActive, active, nextConfig.supportedModels), "info");
+    if (hasTerminalUI(ctx) && nextConfig.pets.enabled) void petController.refresh(ctx, nextConfig);
+    usageController.start(ctx);
+    if (fastController.active) ctx.ui.notify(fastController.stateText(ctx, nextConfig), "info");
   });
 
   pi.on("agent_start", (_event, ctx) => {
-    activeToolCallIds.clear();
-    clearPetFlash();
-    petRuntimeState = config(ctx).pets.thinkingState;
+    invalidateContextUsage();
+    petController.agentStart(ctx);
     updateFooter(ctx);
   });
 
   pi.on("tool_execution_start", (event, ctx) => {
-    activeToolCallIds.add(event.toolCallId);
-    petRuntimeState = config(ctx).pets.toolState;
+    petController.toolStart(ctx, event.toolCallId);
     updateFooter(ctx);
   });
 
   pi.on("tool_execution_end", (event, ctx) => {
-    activeToolCallIds.delete(event.toolCallId);
-    const cfg = config(ctx);
-    petRuntimeState = activeToolCallIds.size > 0 ? cfg.pets.toolState : cfg.pets.thinkingState;
-    if (event.isError) {
-      playPetFlash(ctx, cfg.pets.failedToolState, cfg);
-      return;
-    }
-    updateFooter(ctx);
+    petController.toolEnd(ctx, event.toolCallId, event.isError);
+    if (!event.isError) updateFooter(ctx);
   });
 
   pi.on("agent_end", (_event, ctx) => {
-    activeToolCallIds.clear();
-    petRuntimeState = "idle";
+    petController.agentEnd();
     updateFooter(ctx);
   });
 
-  pi.on("turn_end", (_event, ctx) => {
-    refreshFooterTotals(ctx);
+  pi.on("turn_end", (event, ctx) => {
+    invalidateContextUsage();
+    if (event.message?.role === "assistant") {
+      footerTotals.input += event.message.usage.input;
+      footerTotals.output += event.message.usage.output;
+      footerTotals.cacheRead += event.message.usage.cacheRead;
+      footerTotals.cacheWrite += event.message.usage.cacheWrite;
+      footerTotals.cost += event.message.usage.cost.total;
+    } else refreshFooterTotals(ctx);
     updateFooter(ctx);
-    void refreshUsage(ctx);
+    void usageController.refresh(ctx);
   });
 
   pi.on("session_compact", (_event, ctx) => {
+    invalidateContextUsage();
     refreshFooterTotals(ctx);
-    queuePetKittyCleanup();
-    resetPetRenderCache();
+    petController.queueKittyCleanup();
+    petController.resetRenderCache();
     updateFooter(ctx);
   });
 
   pi.on("session_tree", (_event, ctx) => {
+    invalidateContextUsage();
     refreshFooterTotals(ctx);
-    queuePetKittyCleanup();
-    resetPetRenderCache();
+    petController.queueKittyCleanup();
+    petController.resetRenderCache();
     updateFooter(ctx);
   });
 
   pi.on("model_select", (event, ctx) => {
+    invalidateContextUsage();
     const cfg = config(ctx);
-    const wasActive = active;
-    applyDesiredFastState(ctx, cfg);
-    if (active !== wasActive) {
+    const wasActive = fastController.active;
+    fastController.applyDesiredState(ctx, cfg);
+    if (fastController.active !== wasActive) {
       persist(cfg);
       ctx.ui.notify(
-        active
-          ? stateText(ctx, desiredActive, active, cfg.supportedModels)
-          : `Fast mode inactive for unsupported model ${currentModelKey(ctx)}.`,
-        active ? "info" : "warning",
+        fastController.active
+          ? fastController.stateText(ctx, cfg)
+          : fastController.inactiveForModelMessage(ctx),
+        fastController.active ? "info" : "warning",
       );
     }
     updateFooter(ctx);
-    void refreshUsage(ctx, event.model.id);
+    void usageController.refresh(ctx, event.model.id, { force: true });
   });
 
   pi.on("session_shutdown", () => {
-    shuttingDown = true;
-    queuedUsageRefresh = undefined;
-    queuedPetRefresh = undefined;
-    petLoadingKey = undefined;
-    petLoadNotify = false;
-    usageAbortController?.abort();
-    usageAbortController = undefined;
-    if (usageTimer) clearInterval(usageTimer);
-    usageTimer = undefined;
-    activeToolCallIds.clear();
-    uninstallPetResizeGuard();
-    disposePetKittyNow();
-    resetPetRenderCache();
-    clearPetFlash();
-    stopPetIdleEmotes();
-    stopPetAnimation();
-    stopPendingPetRenderRequest();
+    invalidateContextUsage();
+    invalidateSessionName();
+    usageController.shutdown();
+    petController.shutdown();
   });
 
   pi.on("before_provider_request", (event, ctx) => {
-    const nextConfig = config(ctx);
-    if (!active || !supportsFast(ctx, nextConfig.supportedModels) || !isRecord(event.payload))
-      return;
-    lastInjectedAt = Date.now();
-    lastInjectedModel = currentModelKey(ctx);
-    lastInjectedTier = SERVICE_TIER;
-    return { ...event.payload, service_tier: SERVICE_TIER };
+    return fastController.injectProviderPayload(event, ctx, config(ctx));
   });
+
+  pi.on("message_start", invalidateContextUsage);
+  pi.on("message_update", invalidateContextUsage);
+  pi.on("message_end", invalidateContextUsage);
 }
 
 export const _test = {
@@ -2095,6 +1343,7 @@ export const _test = {
   DEFAULT_PET_CONFIG,
   SERVICE_TIER,
   configPaths,
+  abbreviateHomePath,
   parseModelKey,
   normalizeModelKeys,
   parseModels,
@@ -2112,6 +1361,7 @@ export const _test = {
   formatPercent,
   formatUsageSnapshot,
   readCodexAuth,
+  textPanel,
   imageTest: _imageTest,
   petsTest: _petsTest,
 };