@0xkahi/pi-qol 0.0.3 → 0.0.5

package/assets/config.schema.json

@@ -43,14 +43,9 @@
             "provider",
             "modelId",
             "reasoning"
-          ],
-          "additionalProperties": false
+          ]
         }
-      },
-      "required": [
-        "enabled"
-      ],
-      "additionalProperties": false
+      }
     },
     "model_select": {
       "default": {
@@ -81,8 +76,7 @@
             "required": [
               "provider",
               "modelId"
-            ],
-            "additionalProperties": false
+            ]
           }
         },
         "provider_filter": {
@@ -101,14 +95,7 @@
             "overlay"
           ]
         }
-      },
-      "required": [
-        "enabled",
-        "favourite",
-        "provider_filter",
-        "layout"
-      ],
-      "additionalProperties": false
+      }
     },
     "custom_footer": {
       "default": {
@@ -160,12 +147,7 @@
               "type": "string",
               "pattern": "^#[0-9a-fA-F]{6}$"
             }
-          },
-          "required": [
-            "anthropicUsage",
-            "codexUsage"
-          ],
-          "additionalProperties": false
+          }
         },
         "icons": {
           "default": {
@@ -197,15 +179,7 @@
               "default": " ",
               "type": "string"
             }
-          },
-          "required": [
-            "directory",
-            "refresh",
-            "cache",
-            "cacheRead",
-            "cacheWrite"
-          ],
-          "additionalProperties": false
+          }
         },
         "display": {
           "default": {
@@ -222,27 +196,9 @@
               "default": true,
               "type": "boolean"
             }
-          },
-          "required": [
-            "tokens",
-            "cache"
-          ],
-          "additionalProperties": false
+          }
         }
-      },
-      "required": [
-        "enabled",
-        "colors",
-        "icons",
-        "display"
-      ],
-      "additionalProperties": false
+      }
     }
-  },
-  "required": [
-    "auto_session_name",
-    "model_select",
-    "custom_footer"
-  ],
-  "additionalProperties": false
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xkahi/pi-qol",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "quality of life pi extensions",
   "type": "module",
   "keywords": [

package/src/codemap.md

@@ -0,0 +1,60 @@
+# src/
+
+## Responsibility
+
+Top-level source root for `pi-qol`, a Pi coding-agent extension that layers small quality-of-life features onto the agent core.
+
+It coordinates three feature modules:
+
+- **auto_session_name**: Generates and applies a concise session title from the user's first message before the agent runs.
+- **model_select**: Registers a `/select-model` command (plus a cross-extension event) for picking or searching available models with favourites and provider filtering.
+- **custom_footer**: Replaces the default footer with a richer status bar showing cwd/branch/session, token/cost/cache stats, context-window usage, subscription-rate usage, and the current model/thinking level.
+
+Shared concerns live here too: extension configuration loading, path resolution, model/auth resolution, output colorization, and Zod schemas for every feature.
+
+## Design Patterns
+
+- **Plugin / Extension registration**: `index.ts` is a thin bootstrap that instantiates shared services and calls `register*` factory functions for each feature. Each feature registers itself against the `ExtensionAPI` event bus and command surface.
+- **Event-driven lifecycle**: Features hook into `session_start`, `session_shutdown`, and `before_agent_start` events. They gate behaviour behind config flags and store transient state in closure variables (`lastSessionStartReason`, `titleController`, `installed`, `latestCtx`).
+- **Configuration layering**: `ConfigLoader` merges a built-in default with a global JSON config and an optional project-level config, validated and typed with Zod. Only trusted projects load project-level overrides.
+- **Strategy pattern for subscription usage**: `SubscriptionUsageManager` dispatches to provider-specific `SubscriptionUsageStrategy` implementations (`AnthropicOauthUsageStrategy`, `OpenAiCodexUsageStrategy`) behind a common `SubscriptionUsageApi` interface.
+- **Component-based TUI**: `CustomFooterComponent` and `ModelSelectDialog` implement the host TUI's `Component`/`Focusable` interfaces, render to string arrays, and rely on the host for input routing and re-rendering.
+- **Abortable async work**: `auto_session_name` tracks an `AbortController` across `before_agent_start` invocations so stale title requests are cancelled before a new one starts.
+- **Utility classes as pure helpers**: `PathUtil`, `ModelResolver`, `ModelFormatter`, `AutoSessionNameGuard`, `AutoSessionNameTitleGenerator` are stateless or request-scoped helpers.
+
+## Data & Control Flow
+
+1. **Bootstrap** (`index.ts`)
+   - Creates `ConfigLoader`.
+   - On every `session_start`, calls `config.initializeConfig(ctx)`; surfaces validation errors via `ctx.ui.notify`.
+   - Registers the three feature modules, passing the shared loader.
+
+2. **Config loading** (`config-loader.ts`, `utils/path.util.ts`, `schemas/*.schema.ts`)
+   - Defaults → global `~/.pi/extensions/pi-qol/config.json` → project `.pi/extensions/pi-qol/config.json` (if trusted).
+   - Each partial config is shallow-merged per top-level key and re-validated by `ConfigSchema`.
+   - `PathUtil` owns the config/auth file path conventions.
+
+3. **auto_session_name** (`extensions/auto-session-name/`)
+   - Captures `session_start.reason`.
+   - On `before_agent_start`, guards check: enabled, no existing session name, not a child/fork session, and first user turn.
+   - `ModelResolver` picks the configured model or falls back to the session model, requiring resolvable auth.
+   - `AutoSessionNameTitleGenerator` builds a title-generation context, calls `completeSimple` from `pi-ai`, strips thinking tags/quotes, truncates to `MAX_TITLE_LENGTH`, and applies it via `pi.setSessionName`.
+
+4. **model_select** (`extensions/model-select/`)
+   - Lazily registers once on `session_start` when enabled.
+   - `/select-model [args]` handler refreshes the registry, attempts an exact provider/model match, otherwise opens a custom TUI dialog.
+   - `ModelSelectDialog` filters search items with fuzzy matching, navigates favourites/search sections, and returns the chosen model to `pi.setModel`.
+   - `PI_VIM_KEY_EVENT_ID` allows other extensions to trigger the same picker.
+
+5. **custom_footer** (`extensions/custom-footer/`)
+   - On first enabled `session_start`, installs a footer component via `ctx.ui.setFooter`.
+   - Each render reads live data from `ExtensionContext` (`sessionManager`, `modelRegistry`, `model`, `getContextUsage`, `footerData`), calculates session totals, formats tokens/cost/context usage, and optionally fetches subscription usage through cached strategies.
+
+## Integration Points
+
+- **@earendil-works/pi-coding-agent**: Provides `ExtensionAPI`, `ExtensionContext`, `ExtensionCommandContext`, events (`session_start`, `session_shutdown`, `before_agent_start`), command registration (`pi.registerCommand`), UI notifications (`ctx.ui.notify`), footer injection (`ctx.ui.setFooter`), custom dialogs (`ctx.ui.custom`), session naming (`pi.setSessionName`/`getSessionName`), and model selection (`pi.setModel`/`getThinkingLevel`).
+- **@earendil-works/pi-ai**: Used for `completeSimple`, `Model<Api>`, `modelsAreEqual`, and model-metadata types during title generation and model selection.
+- **@earendil-works/pi-tui**: Provides the `Component`/`Focusable` contracts, `TUI`, `Theme`, `Input`, and text-width helpers (`truncateToWidth`, `visibleWidth`, `fuzzyFilter`) used by the footer and model picker.
+- **Filesystem**: Reads global and project JSON configs and `~/.pi/auth.json` for OAuth tokens.
+- **External provider APIs**: `SubscriptionUsageApi` and strategies call Anthropic/OpenAI Codex usage endpoints when OAuth auth is present.
+- **Cross-extension events**: `piVimKeyEventId` from `constants.ts` lets other Pi extensions emit events that `model_select` listens on.

package/src/extensions/auto-session-name/codemap.md

@@ -0,0 +1,48 @@
+# src/extensions/auto-session-name/
+
+## Responsibility
+
+Automatically generate and apply a short, descriptive name for a Pi session based on the user's opening message. The extension runs once per session, only on the user's first turn, and only when no session name has already been set and the session is not a child/fork. Generated titles are surfaced through the normal Pi session name API so they appear in the UI and are persisted with the session.
+
+## Design Patterns
+
+- **Event-driven extension registration**: `registerAutoSessionName` attaches handlers to Pi lifecycle events (`session_start`, `before_agent_start`, `session_shutdown`) and coordinates state across them.
+- **Guard object**: `AutoSessionNameGuard` isolates all preconditions (feature enabled check is kept in the caller) so the main flow reads as a simple chain of boolean decisions.
+- **Static command object**: `AutoSessionNameTitleGenerator` encapsulates the entire LLM-backed title generation as a single static entry point with pure helper methods for extraction, cleaning, and truncation.
+- **Prompt-as-data**: `prompt.ts` builds a `Context` value object containing a detailed system prompt and a single user message; no prompt logic leaks into the generator.
+- **Dependency injection by structural typing**: All collaborators are accepted as `Pick<...>` or local interfaces, making the extension easy to unit test and minimizing coupling to the full ExtensionAPI surface.
+- **Cancellation token**: A module-level `AbortController` is created per title request and aborted on `session_shutdown` or when a newer request starts, preventing stale completions from overwriting the session name.
+- **Defensive post-condition check**: After applying the title, the code compares `pi.getSessionName()` with the generated text and warns if they diverge.
+
+## Data & Control Flow
+
+1. **Session start**: The `session_start` handler records `event.reason` in `lastSessionStartReason`.
+2. **Agent start trigger**: On `before_agent_start`, the handler first verifies:
+   - `auto_session_name` is enabled in config.
+   - No session name is currently set (`getSessionName() !== undefined`).
+   - The session is not a child/fork (`startReason !== 'fork'` and no `parentSession` header).
+   - This is the user's first turn (zero prior user messages in the branch).
+   - The current user prompt is non-empty.
+3. **Model resolution**: `ModelResolver` resolves the configured title model into a concrete `ResolvedModel` (model, API key, headers, reasoning preference). Errors are surfaced via `ctx.ui.notify`.
+4. **Title generation**: `AutoSessionNameTitleGenerator.generateAndApplyTitle` sends a single-turn completion to the LLM using the context from `buildTitleContext`.
+5. **Title cleaning**: The raw response has `<think>` blocks stripped, is reduced to the first non-empty line, has surrounding quotes removed, and is truncated to `MAX_TITLE_LENGTH`.
+6. **Application**: The cleaned title is applied via `pi.setSessionName`. If application fails or returns a different value, a warning is shown.
+7. **Feedback**: Success or failure is reported through `ctx.ui.notify`.
+8. **Cancellation/reset**: `session_shutdown` aborts any pending request and clears the controller.
+
+## Integration Points
+
+- **Pi ExtensionAPI**:
+  - Events: `session_start`, `session_shutdown`, `before_agent_start`.
+  - Methods: `getSessionName`, `setSessionName`.
+- **Pi Context/session manager** (`ctx.sessionManager`):
+  - `getBranch()` and `getHeader()` are used to detect first user turn and child sessions.
+- **ConfigLoader** (`../../config-loader`):
+  - `isEnabled('auto_session_name')` toggles the feature.
+  - `getAutoSessionName()` supplies the optional per-feature model override.
+- **ModelResolver** (`../../utils/model-resolver.util`):
+  - Resolves the configured model string into a full `ResolvedModel` usable by `pi-ai`.
+- **pi-ai** (`@earendil-works/pi-ai`):
+  - `completeSimple` performs the actual LLM completion.
+- **Pi UI notifications** (`ctx.ui.notify`):
+  - All user-facing status, warnings, and errors are emitted through the Pi notification channel.

package/src/extensions/codemap.md

@@ -0,0 +1,59 @@
+# src/extensions/
+
+## Responsibility
+
+This folder contains the feature-level extension modules for `pi-qol`. Each child module registers one self-contained quality-of-life feature into the Pi Coding Agent runtime by subscribing to lifecycle events, commands, and UI hooks exposed by the `ExtensionAPI`.
+
+Current features:
+
+- `auto-session-name` – automatically generates and applies a concise session title from the user’s first message.
+- `model-select` – provides an interactive `/select-model` command (and cross-extension activation hook) for choosing models from the registry with favourites, search, and provider filtering.
+- `custom-footer` – replaces the TUI footer with a richer status bar showing cwd, git branch, session name, model, token/cost usage, context-window usage, and subscription usage.
+
+## Design Patterns
+
+- **Registration function pattern**: each module exports a single `register*` function that takes `ExtensionAPI` and a `{ config: ConfigLoader }` dependency object. `src/index.ts` calls all three registration functions after initializing configuration.
+- **Event-driven lifecycle wiring**: registration is non-blocking; actual work is triggered by Pi runtime events (`session_start`, `session_shutdown`, `before_agent_start`).
+- **Lazy / once-only activation**: `model-select` and `custom-footer` use guard flags (`modelSelectRegistered`, `installed`) to ensure handlers or UI components are registered only once per process.
+- **Command registration**: `model-select` registers a slash command via `pi.registerCommand` and defers heavy work to an async handler.
+- **TUI component pattern**: `custom-footer` constructs a `Component` that renders live on each frame, invalidating Pi’s default footer rendering.
+- **Guard classes**: `auto-session-name/guards.ts` isolates predicate logic (session name already set, child session, first user turn) for easy testing and readable early returns.
+- **Pure helpers / formatters**: `model-formatter.ts`, `token-stats.ts`, `model-lists.ts`, and `prompt.ts` keep transformation and rendering logic free of side effects.
+- **Cross-extension event bus**: `model-select` listens on a dedicated `pi.events` channel (`PI_VIM_KEY_EVENT_ID`) so other extensions can open the picker without invoking the slash command directly.
+- **Abortable async work**: `auto-session-name` keeps an `AbortController` and cancels in-flight title generation on `session_shutdown` or a new `before_agent_start`.
+
+## Data & Control Flow
+
+1. **Configuration load** (`src/index.ts`)
+   - On `session_start`, `ConfigLoader.initializeConfig(ctx)` merges global and (if trusted) project JSON configs, validated by Zod schemas.
+   - All enabled checks and section values are read through `ConfigLoader`.
+
+2. **auto-session-name flow**
+   - Records `lastSessionStartReason` on `session_start`.
+   - On `before_agent_start`, guards verify the feature is enabled, the session has no name yet, it is not a child session, and this is the user’s first turn.
+   - Resolves the configured title-generation model via `ModelResolver`.
+   - Calls `completeSimple` with a small title-generation context built by `prompt.ts`.
+   - Cleans the result, calls `pi.setSessionName(title)`, and notifies the UI.
+   - Aborts any previous in-flight request before starting a new one.
+
+3. **model-select flow**
+   - Lazy-activated once on `session_start` if enabled.
+   - Command handler calls `waitForIdle` (when available), refreshes `ctx.modelRegistry`, attempts an exact provider/model match from arguments, then falls back to an interactive `ModelSelectDialog`.
+   - The dialog uses fuzzy filtering, tab switching between favourites/search, and keyboard navigation; selection is applied via `pi.setModel`.
+   - The event-bus handler captures the latest context so the picker can also be opened without a command context.
+
+4. **custom-footer flow**
+   - On `session_start`, installs a `CustomFooterComponent` factory via `ctx.ui.setFooter`.
+   - Each render reads from `ExtensionContext` (cwd, session name, model, context usage, entries), `FooterDataProvider` (git branch, extension statuses, available providers), and a cached `SubscriptionUsageManager`.
+   - The component builds and truncates lines to the available terminal width and requests re-renders via `tui.requestRender()` when branch changes or subscription usage updates.
+
+## Integration Points
+
+- **`@earendil-works/pi-coding-agent`** – `ExtensionAPI`, `ExtensionContext`, `ExtensionCommandContext`, events, commands, session manager, and UI notifications.
+- **`@earendil-works/pi-ai`** – model types (`Model`, `Api`), `completeSimple`, and `modelsAreEqual`.
+- **`@earendil-works/pi-tui`** – `Component`, `Focusable`, `Input`, `TUI`, `Theme`, `KeybindingsManager`, and width helpers.
+- **`src/config-loader.ts`** – shared `ConfigLoader` used by all three registration functions for feature flags and section config.
+- **`src/utils/model-resolver.util.ts`** – resolves provider/model/auth configuration for `auto-session-name`.
+- **`src/libs/subscription-usage/`** – `SubscriptionUsageApi` and provider-specific strategies used by the footer to fetch OAuth subscription usage.
+- **`src/constants.ts` / `piVimKeyEventId`** – generates the cross-extension event id consumed by `model-select`.
+- **`src/index.ts`** – orchestrates config initialization and calls each `register*` function in a fixed order.

package/src/extensions/custom-footer/codemap.md

@@ -0,0 +1,49 @@
+# src/extensions/custom-footer/
+
+## Responsibility
+
+Renders a custom TUI footer that replaces the default agent footer. It displays:
+
+- The current working directory, git branch, and session name.
+- Token usage totals (input/output) for assistant messages in the current session.
+- Cache read/write totals and the latest cache hit rate.
+- Estimated session cost, with a subscription indicator when using OAuth models.
+- Context window usage as a percentage of the active model's context window.
+- OAuth subscription usage (Anthropic / OpenAI Codex) including a progress bar, percentage, and reset description.
+- The active model name and reasoning/thinking level.
+- Sorted, sanitized extension status messages.
+
+The extension is feature-gated by the `custom_footer` config flag and can dynamically restore the default footer when disabled.
+
+## Design Patterns
+
+- **Plugin registration**: `index.ts` listens to the agent's `session_start` event and registers a single footer component factory via `ctx.ui.setFooter`.
+- **Component pattern**: `CustomFooterComponent` implements the `Component` interface (`render`, `invalidate`, `dispose`) so the TUI can call it on every frame.
+- **Dependency injection**: The component receives its dependencies (`tui`, `theme`, `footerData`, `ctx`, `config`, `getThinkingLevel`) in a single `CustomFooterComponentDeps` object, keeping rendering logic decoupled from construction.
+- **Data provider abstraction**: `FooterDataProvider` isolates footer-specific data (git branch, extension statuses, provider count, branch-change notifications) from the broader `ExtensionContext`.
+- **Cache manager**: `SubscriptionUsageManager` caches OAuth usage responses with a TTL and coalesces in-flight requests per provider.
+- **Strategy pattern**: Provider-specific OAuth usage fetch strategies (`AnthropicOauthUsageStrategy`, `OpenAiCodexUsageStrategy`) are selected at runtime inside `SubscriptionUsageManager`.
+- **Pure formatting helpers**: `token-stats.ts` and `progress-bar.ts` contain stateless functions for number formatting, usage aggregation, and progress-bar rendering, making them easy to test.
+
+## Data & Control Flow
+
+1. **Registration**: `registerCustomFooter` waits for `session_start`, checks the `custom_footer` feature flag, and installs `CustomFooterComponent` as the footer renderer. It guards against double installation.
+2. **Rendering trigger**: The TUI calls `CustomFooterComponent.render(width)` on every footer repaint.
+3. **Dynamic disable**: If `custom_footer` is disabled at render time, the component calls `ctx.ui.setFooter(undefined)` once and returns an empty array so the default footer is restored.
+4. **Line assembly**: `render` builds up to three lines:
+   - `renderPathLine`: directory, branch, session name.
+   - `renderStatsLine`: token/cost/context/subscription stats plus the model name.
+   - Extension status line (only when statuses exist).
+5. **Stats composition**: `buildStatsLeft` aggregates assistant-message usage from `sessionManager.getEntries()`, formats tokens, adds cache info, cost, context usage, and an optional subscription segment.
+6. **Subscription usage**: `renderSubscriptionUsageSegment` resolves the provider, asks `SubscriptionUsageManager.ensureFresh(provider)` for cached data, picks the rate window with the nearest reset, and builds a colored progress segment.
+7. **Async refresh**: `SubscriptionUsageManager` fetches usage asynchronously when the cached entry is older than `SUBSCRIPTION_USAGE_TTL_MS`. On success it calls `tui.requestRender()` via the `onUpdate` callback to update the footer.
+8. **Git branch updates**: `footerData.onBranchChange` registers a render request callback that is cleaned up in `dispose`.
+
+## Integration Points
+
+- **`@earendil-works/pi-coding-agent`**: Uses `ExtensionAPI` (event subscription, `getThinkingLevel`), `ExtensionContext` (`model`, `modelRegistry`, `sessionManager`, `getContextUsage`, `ui.setFooter`), and `ContextUsage` / `SessionEntry` types.
+- **`@earendil-works/pi-tui`**: Implements the `Component` contract and uses `truncateToWidth`, `visibleWidth`, and `TUI.requestRender`.
+- **`../../config-loader`**: Reads the `custom_footer` feature flag and full footer config (colors, icons, display toggles) via `ConfigLoader`.
+- **`../../schemas/config.schema`**: `CustomFooterConfig` is derived from the `Config` schema's `custom_footer` shape.
+- **`../../utils/crayon.util`**: Applies custom ANSI colors to directory text, model name, and subscription usage labels.
+- **`../../libs/subscription-usage/**`**: Delegates OAuth usage fetching and reset formatting to `SubscriptionUsageApi` and provider-specific strategies.

package/src/extensions/model-select/codemap.md

@@ -0,0 +1,59 @@
+# src/extensions/model-select/
+
+## Responsibility
+
+This extension implements the `/select-model` command and its interactive picker. Its job is to let the user search, browse, and choose a model from the global model registry, optionally constrained by a provider filter and a configured list of favourites. It highlights the currently active model, supports keyboard navigation, and applies the final selection by calling the extension API. It can be triggered both as a user-facing command and programmatically from another extension (e.g., `pi-vim-keys`) via an event-bus hook.
+
+## Design Patterns
+
+- **Lazy command activation**: `registerModelSelect` waits for the first `session_start` event before calling `activateModelSelect`, ensuring the extension is wired up once a session exists.
+- **Command + event-bus controller**: `activateModelSelect` registers the `/select-model` command and also listens on a cross-extension event ID so external extensions can open the picker without invoking the command directly.
+- **Context caching for async triggers**: The most recent `ExtensionContext` is stored (`latestCtx`) so the event-bus handler (which receives no context argument) can still open the dialog.
+- **Separation of concerns**:
+  - `index.ts`: orchestrates activation, command handling, and applying the selected model.
+  - `model-lists.ts`: queries the registry and prepares favourite + searchable model lists.
+  - `model-formatter.ts`: pure static utilities for labels, descriptions, sorting, and token formatting.
+  - `model-select-dialog.ts`: TUI component that renders the picker and translates user input into selection events.
+- **TUI Component pattern**: `ModelSelectDialog` implements `Component` and `Focusable`, rendering itself into lines and delegating focus to an internal `Input` component.
+- **Defensive guards**: checks feature enablement, UI availability, idle state (`waitForIdle`), exact-match short-circuit, and auth availability before applying a model.
+
+## Data & Control Flow
+
+1. **Activation**
+   - `registerModelSelect` listens for `session_start`.
+   - On first eligible session, it calls `activateModelSelect`, which stores the initial context and registers the `/select-model` command and the `PI_VIM_KEY_EVENT_ID` listener.
+
+2. **Command invocation**
+   - The command handler stores the command context as `latestCtx`.
+   - It aborts if `model_select` is disabled.
+   - It calls `showModelSelector` with the raw argument string.
+
+3. **Selection short-circuit**
+   - `showModelSelector` waits for idle if available, then refreshes the model registry.
+   - If the argument can be parsed as `provider/modelId` and resolves through `findExactModel`, the model is applied immediately and the dialog is skipped.
+
+4. **Dialog path**
+   - If no exact match is found and a UI is present, the extension loads the `model_select` config.
+   - `buildModelLists` refreshes the registry, optionally filters by `provider_filter`, sorts search items with the current model first, and validates configured favourites (collecting warnings for missing models or missing auth).
+   - `ctx.ui.custom` creates a `ModelSelectDialog` with the prepared lists, current model, warnings, layout, and an `onDone` callback.
+   - The dialog renders two sections (Favourites and Search), a search input, config warnings, and a help footer.
+
+5. **User interaction**
+   - Keyboard input is mapped through `keybindings.matches` for navigation, section switching, confirmation, and cancellation.
+   - Typing printable characters switches focus to the search input and re-filters the search list via `fuzzyFilter`.
+   - Confirming a selection invokes `onDone` with the chosen `Model`.
+
+6. **Apply result**
+   - If a model is selected, `applySelectedModel` calls `pi.setModel`.
+   - A success or missing-auth notification is shown via `ctx.ui.notify`.
+
+## Integration Points
+
+- **`ExtensionAPI` (`@earendil-works/pi-coding-agent`)**: used to register the command, listen to `session_start`, set the active model (`pi.setModel`), and access the shared event bus (`pi.events`).
+- **`ExtensionContext` / `ExtensionCommandContext` (`@earendil-works/pi-coding-agent`)**: provides `modelRegistry`, `ui`, `hasUI`, `model`, and the optional `waitForIdle` guard.
+- **`ModelRegistry`**: refreshed and queried for available models, configured auth, and lookup by `provider` + `modelId`.
+- **`ConfigLoader` (`../../config-loader`)**: provides feature toggle state (`isEnabled('model_select')`) and the typed `model_select` configuration object.
+- **`@earendil-works/pi-ai`**: supplies the `Model<Api>` type and `modelsAreEqual` for stable identity comparisons.
+- **`@earendil-works/pi-tui`**: supplies the `Input` component, `fuzzyFilter`, theme helpers, and rendering utilities (`truncateToWidth`, `visibleWidth`) used by the dialog.
+- **`pi-vim-keys` / other extensions**: can trigger the picker by emitting `PI_VIM_KEY_EVENT_ID` on the shared event bus.
+- **Configuration schemas**: `model_select` shape and `ModelSelectLayout` are defined by `../../schemas/config.schema` and `../../schemas/model-select.config.schema`.

package/src/extensions/model-select/model-select-dialog.ts

@@ -5,22 +5,13 @@ import { MAX_CONFIG_WARNING_LINES, MAX_VISIBLE_MODELS } from './constants';
 import { ModelFormatter } from './model-formatter';
 import type { DialogOptions, ModelItem, SelectionSection } from './types';
 
-function isPrintableInput(data: string): boolean {
-  if (data.length === 0) {
-    return false;
-  }
-  return [...data].every(char => {
-    const code = char.charCodeAt(0);
-    return code >= 32 && code !== 0x7f && (code < 0x80 || code > 0x9f);
-  });
-}
-
 export class ModelSelectDialog implements Component, Focusable {
   private readonly searchInput = new Input();
   private activeSection: SelectionSection;
   private selectedFavouriteIndex = 0;
   private selectedSearchIndex = 0;
   private filteredSearchItems: ModelItem[];
+  private filteredFavouriteItems: ModelItem[];
   private _focused = false;
 
   constructor(
@@ -35,9 +26,10 @@ export class ModelSelectDialog implements Component, Focusable {
       : -1;
     this.selectedFavouriteIndex = currentFavouriteIndex >= 0 ? currentFavouriteIndex : 0;
     this.searchInput.setValue(options.initialSearch);
-    this.searchInput.onSubmit = () => this.selectCurrentSearchItem();
+    this.searchInput.onSubmit = () => this.selectCurrentItem();
     this.searchInput.onEscape = () => this.options.onDone(null);
-    this.filteredSearchItems = this.filterSearchItems(options.initialSearch);
+    this.filteredSearchItems = this.filterItems(options.searchItems, options.initialSearch);
+    this.filteredFavouriteItems = this.filterItems(options.favouriteItems, options.initialSearch);
     this.syncFocus();
   }
 
@@ -95,17 +87,16 @@ export class ModelSelectDialog implements Component, Focusable {
       return;
     }
 
-    if (this.activeSection !== 'search' && isPrintableInput(data)) {
-      this.activeSection = 'search';
-      this.syncFocus();
-    }
+    this.searchInput.handleInput(data);
+    this.applyFilter(this.searchInput.getValue());
+    this.tui.requestRender();
+  }
 
-    if (this.activeSection === 'search') {
-      this.searchInput.handleInput(data);
-      this.filteredSearchItems = this.filterSearchItems(this.searchInput.getValue());
-      this.selectedSearchIndex = Math.min(this.selectedSearchIndex, Math.max(0, this.filteredSearchItems.length - 1));
-      this.tui.requestRender();
-    }
+  private applyFilter(query: string): void {
+    this.filteredSearchItems = this.filterItems(this.options.searchItems, query);
+    this.filteredFavouriteItems = this.filterItems(this.options.favouriteItems, query);
+    this.selectedSearchIndex = Math.min(this.selectedSearchIndex, Math.max(0, this.filteredSearchItems.length - 1));
+    this.selectedFavouriteIndex = Math.min(this.selectedFavouriteIndex, Math.max(0, this.filteredFavouriteItems.length - 1));
   }
 
   render(width: number): string[] {
@@ -179,12 +170,12 @@ export class ModelSelectDialog implements Component, Focusable {
   }
 
   private syncFocus(): void {
-    this.searchInput.focused = this._focused && this.activeSection === 'search';
+    this.searchInput.focused = this._focused;
   }
 
   private moveSelection(delta: number): void {
     if (this.activeSection === 'favourites') {
-      this.selectedFavouriteIndex = this.wrapIndex(this.selectedFavouriteIndex + delta, this.options.favouriteItems.length);
+      this.selectedFavouriteIndex = this.wrapIndex(this.selectedFavouriteIndex + delta, this.filteredFavouriteItems.length);
       return;
     }
 
@@ -200,7 +191,7 @@ export class ModelSelectDialog implements Component, Focusable {
 
   private selectCurrentItem(): void {
     if (this.activeSection === 'favourites') {
-      const item = this.options.favouriteItems[this.selectedFavouriteIndex];
+      const item = this.filteredFavouriteItems[this.selectedFavouriteIndex];
       if (item) {
         this.options.onDone(item.model);
       }
@@ -217,12 +208,12 @@ export class ModelSelectDialog implements Component, Focusable {
     }
   }
 
-  private filterSearchItems(query: string): ModelItem[] {
+  private filterItems(items: ModelItem[], query: string): ModelItem[] {
     const trimmed = query.trim();
     if (!trimmed) {
-      return this.options.searchItems;
+      return items;
     }
-    return fuzzyFilter(this.options.searchItems, trimmed, item => item.searchText);
+    return fuzzyFilter(items, trimmed, item => item.searchText);
   }
 
   private renderTitle(): string {
@@ -233,9 +224,9 @@ export class ModelSelectDialog implements Component, Focusable {
   private renderTabs(): string {
     const tabs: string[] = [];
     if (this.options.hasFavouriteSection) {
-      tabs.push(this.renderTab('favourites', `Favourites ${this.options.favouriteItems.length}`));
+      tabs.push(this.renderTab('favourites', `Favourites ${this.filteredFavouriteItems.length}`));
     }
-    tabs.push(this.renderTab('search', `Search ${this.options.searchItems.length}`));
+    tabs.push(this.renderTab('search', `Search ${this.filteredSearchItems.length}`));
     return tabs.join(this.theme.fg('muted', '  '));
   }
 
@@ -250,11 +241,17 @@ export class ModelSelectDialog implements Component, Focusable {
   private renderFavourites(width: number): string[] {
     const lines: string[] = [];
 
+    lines.push(this.line(this.theme.fg('muted', 'Filter:'), width));
+    lines.push(...this.searchInput.render(width));
+    lines.push('');
+
     if (this.options.favouriteItems.length === 0) {
       lines.push(this.line(this.theme.fg('muted', '  No configured favourites are available.'), width));
+    } else if (this.filteredFavouriteItems.length === 0) {
+      lines.push(this.line(this.theme.fg('muted', '  No matching favourites'), width));
     } else {
-      lines.push(...this.renderModelList(this.options.favouriteItems, this.selectedFavouriteIndex, width));
-      const selected = this.options.favouriteItems[this.selectedFavouriteIndex];
+      lines.push(...this.renderModelList(this.filteredFavouriteItems, this.selectedFavouriteIndex, width));
+      const selected = this.filteredFavouriteItems[this.selectedFavouriteIndex];
       if (selected) {
         lines.push('');
         lines.push(this.line(this.theme.fg('muted', `  ${selected.description}`), width));

package/src/libs/codemap.md

@@ -0,0 +1,33 @@
+# src/libs/
+
+## Responsibility
+
+`src/libs/` hosts shared, domain-specific library modules that are consumed by extensions and features across the project. It is not a generic utilities folder; modules here encapsulate cohesive business capabilities with stable public APIs.
+
+Currently, the folder contains the `subscription-usage` module, whose job is to fetch and normalize subscription/rate-limit usage data from upstream OAuth providers (Anthropic, OpenAI Codex) so that UI code can display a consistent usage indicator without needing to know provider-specific API details.
+
+## Design Patterns
+
+- **Strategy pattern** — A provider-agnostic `SubscriptionUsageStrategy` interface is implemented by per-provider strategies (`AnthropicOauthUsageStrategy`, `OpenAiCodexUsageStrategy`). This keeps provider-specific request building, response parsing, and window mapping isolated and makes adding new providers a matter of adding another strategy.
+- **API facade** — `SubscriptionUsageApi` presents a single `fetchUsage(strategy)` entry point. It handles credential lookup and delegates the provider-specific call to the supplied strategy, returning a normalized `FetchUsageResponse`.
+- **Adapter/normalization** — Each strategy adapts a different upstream API shape into the common `RateWindow[]` model (`label`, `usedPercent`, `resetAt`), so consumers operate on one uniform data structure.
+- **Defensive parsing** — Strategies use `RawDataParser` to coerce unknown provider JSON into typed records/values, avoiding runtime exceptions from unexpected payload shapes.
+- **Config-driven auth** — `SubscriptionUsageApi` reads provider tokens (and optional account IDs) from a local pi auth config file rather than accepting credentials directly.
+
+## Data & Control Flow
+
+1. A consumer (e.g., `SubscriptionUsageManager`) selects a provider and asks `SubscriptionUsageApi.fetchUsage()` to load usage data for that provider's strategy.
+2. `SubscriptionUsageApi` loads the auth config via `PathUtil.findPiAuthConfig()`, extracts the token/account for the strategy's provider, and bails out gracefully if no auth is available.
+3. The strategy builds its provider-specific HTTP request, calls the upstream endpoint, and parses the response.
+4. The strategy maps the provider payload into `RateWindow[]` and returns it.
+5. `SubscriptionUsageApi` wraps the windows with the strategy's human-readable `label` into a `FetchUsageResponse`.
+6. Consumers can use `SubscriptionUsageApi.formatResetDescription(date)` to turn a `resetAt` timestamp into a short relative string such as `15m`, `2h30m`, or `1d`.
+
+## Integration Points
+
+- **Consumers** — `src/extensions/custom-footer/subscription-usage-manager.ts` imports the strategies and `SubscriptionUsageApi`, caches responses, picks the most relevant window, and drives UI updates.
+- **Auth/config** — `src/utils/path.util.ts` (`PathUtil.findPiAuthConfig()`) locates the local auth file; the API expects provider entries keyed by `SubscriptionProvider` names.
+- **Parsing utility** — `src/utils/raw-data-parser.util.ts` is used across strategies to safely read fields from dynamic JSON.
+- **External services** — Strategies call live provider endpoints:
+  - Anthropic: `https://api.anthropic.com/api/oauth/usage`
+  - OpenAI Codex: `https://chatgpt.com/backend-api/wham/usage`

package/src/libs/subscription-usage/codemap.md

@@ -0,0 +1,28 @@
+# src/libs/subscription-usage/
+
+## Responsibility
+
+Encapsulates fetching and normalizing subscription usage (rate-limit utilization) from external AI providers into a common `RateWindow` representation. It is the single place the system queries provider-specific usage APIs and turns their heterogeneous responses into a consistent, UI-friendly shape.
+
+## Design Patterns
+
+- **Strategy**: `SubscriptionUsageApi` consumes a `SubscriptionUsageStrategy` (`AnthropicOauthUsageStrategy`, `OpenAiCodexUsageStrategy`) without knowing provider-specific details.
+- **Adapter / Normalization**: each strategy adapts a provider response to the shared `RateWindow[]` model (`label`, `usedPercent`, `resetAt`).
+- **Safe parsing**: `RawDataParser` guards against unexpected JSON shapes and missing fields.
+- **Utility API class**: `SubscriptionUsageApi` wraps auth loading, fetching, and formatting in one injectable-style class.
+
+## Data & Control Flow
+
+1. A caller invokes `SubscriptionUsageApi.fetchUsage(strategy)`.
+2. The API loads provider OAuth credentials from the local auth config via `PathUtil.findPiAuthConfig()`.
+3. It calls `strategy.fetchUsage(auth)`.
+4. The strategy performs a provider HTTP request, parses JSON, and maps relevant fields to `RateWindow[]`.
+5. The API wraps the result in `FetchUsageResponse` (`label`, `rateWindow`).
+6. `formatResetDescription(resetAt)` converts reset timestamps to human-readable relative strings (`5m`, `2h30m`, `1d`, etc.).
+
+## Integration Points
+
+- **Local auth config**: `PathUtil.findPiAuthConfig()` supplies `SubscriptionAuthconfig`, which maps providers to `{ access, accountId }` objects.
+- **Anthropic API**: `AnthropicOauthUsageStrategy` calls `https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`.
+- **OpenAI Codex API**: `OpenAiCodexUsageStrategy` calls `https://chatgpt.com/backend-api/wham/usage` with bearer token and optional `ChatGPT-Account-Id` header.
+- **Shared utilities**: depends on `src/utils/path.util` for config discovery and `src/utils/raw-data-parser.util` for defensive JSON parsing.

package/src/libs/subscription-usage/strategy/codemap.md

@@ -0,0 +1,44 @@
+# subscription-usage strategy codemap
+
+## Responsibility
+
+This directory contains provider-specific implementations of `SubscriptionUsageStrategy`.
+Each strategy is responsible for:
+
+- Building the authenticated HTTP request for a single provider.
+- Fetching usage data from that provider's API.
+- Parsing the raw JSON response into a normalized `RateWindow[]`.
+- Returning `undefined` when no usable usage data is available.
+
+Current strategies:
+
+- `AnthropicOauthUsageStrategy` — fetches Anthropic OAuth usage and exposes the `five_hour` and `seven_day` windows.
+- `OpenAiCodexUsageStrategy` — fetches OpenAI Codex usage and exposes the main `rate_limit` windows plus any `additional_rate_limits`.
+
+## Design Patterns
+
+- **Strategy pattern** — both classes implement the common `SubscriptionUsageStrategy` interface, so the caller (`SubscriptionUsageApi`) can treat them uniformly.
+- **Encapsulation of provider details** — request construction, response parsing, and window labeling are kept private to each strategy.
+- **Defensive parsing** — unknown API responses are coerced safely through `RawDataParser` before being used.
+- **Helper decomposition** — the OpenAI strategy splits parsing into small private helpers (`pushRateLimitWindows`, `pushRateWindow`, `getResetDate`, `getWindowLabel`) to keep the main flow readable.
+
+## Data & Control Flow
+
+1. `SubscriptionUsageApi.fetchUsage(strategy)` loads provider credentials and calls `strategy.fetchUsage(auth)`.
+2. Each strategy builds a provider-specific `Request` and calls `fetch`.
+3. The JSON response is converted to a `Record<string, unknown>` via `RawDataParser.asRecord`.
+4. Relevant fields are extracted:
+   - **Anthropic**: iterates over `five_hour` and `seven_day`, reads `utilization` as `usedPercent`, and parses `resets_at` into a `Date`.
+   - **OpenAI**: reads `rate_limit.primary_window` and `rate_limit.secondary_window`, then loops over `additional_rate_limits`.
+5. Each discovered window is pushed as a `RateWindow` object with `label`, `usedPercent`, and optional `resetAt`.
+6. The array is returned to `SubscriptionUsageApi`, which wraps it in a `FetchUsageResponse` keyed by the strategy's `label`.
+
+## Integration Points
+
+- **Interface contract**: strategies implement `SubscriptionUsageStrategy` and use the `ProviderAuth`, `RateWindow`, and `SubscriptionProvider` types from `../subscription-usage-api.util`.
+- **Shared utility**: all parsing helpers come from `../../../utils/raw-data-parser.util` (`RawDataParser`).
+- **Network layer**: strategies use the global `fetch` API directly.
+- **Provider endpoints**:
+  - Anthropic: `https://api.anthropic.com/api/oauth/usage` — authenticated with a `Bearer` token and the `anthropic-beta: oauth-2025-04-20` header.
+  - OpenAI Codex: `https://chatgpt.com/backend-api/wham/usage` — authenticated with a `Bearer` token and an optional `ChatGPT-Account-Id` header.
+- **Consumer**: `SubscriptionUsageApi` orchestrates strategies, loads auth config via `PathUtil.findPiAuthConfig`, and formats results for downstream display.

package/src/schemas/codemap.md

@@ -0,0 +1,29 @@
+# src/schemas/
+
+## Responsibility
+
+This directory defines the Zod-based configuration schemas for the pi-qol plugin. It is the single source of truth for the shape, defaults, and validation rules of user-facing configuration. It covers the top-level config object and per-feature schemas for `auto-session-name`, `model-select`, and `custom-footer`, plus reusable shared schema building blocks.
+
+## Design Patterns
+
+- **Schema-first configuration**: Uses Zod to declare schemas and derive TypeScript types via `z.infer`.
+- **Composition over monolith**: Per-feature schemas (`auto-session-name.config.schema.ts`, `model-select.config.schema.ts`, `custom-footer-config.schema.ts`) are composed into the top-level `ConfigSchema` in `config.schema.ts`.
+- **Defaults embedded in schemas**: `.default()` is used heavily so schemas are self-describing and can parse incomplete inputs safely.
+- **Full vs. Partial schemas**: Each feature exposes a full schema and a `Partial*` variant to support partial/merging updates (e.g., user overrides layered over defaults).
+- **Shared primitives**: `shared-config.schema.ts` centralizes reusable concepts like `ModelConfigSchema` and `ColorHexSchema`.
+- **Default object parsing**: `custom-footer-config.schema.ts` uses `Schema.parse({})` to derive concrete default objects rather than hand-writing inline literals.
+
+## Data & Control Flow
+
+1. **Input**: Raw JSON/user config enters the system.
+2. **Validation**: The top-level `ConfigSchema.parse()` validates the whole object, falling back to per-field defaults for missing keys.
+3. **Feature decomposition**: `ConfigSchema` delegates validation of each feature section to its dedicated schema (`AutoSessionNameConfigSchema`, `ModelSelectConfigSchema`, `CustomFooterConfigSchema`), which in turn use shared schemas (`ModelConfigSchema`, `ColorHexSchema`, `ReasoningLevelSchema`).
+4. **Partial updates**: `PartialConfigSchema` and its feature-level partial variants allow validating incremental config changes without requiring a complete config object.
+5. **Output**: Validated `Config` and `PartialConfig` types are exported for use by config loading, merging, and runtime feature code elsewhere in the plugin.
+
+## Integration Points
+
+- **Config loading / merging layer**: `config.schema.ts` exports `Config` and `PartialConfig` types consumed by whatever loads and merges user config with defaults.
+- **Feature modules**: Auto-session-name, model-select, and custom-footer runtime code import their respective config types from this directory.
+- **Constants**: `shared-config.schema.ts` imports `COLOR_HEX_REGEX` from `../constants` to validate hex colors.
+- **Type system**: All schemas feed TypeScript types via `z.infer`, providing compile-time guarantees across the plugin.

package/src/utils/codemap.md

@@ -0,0 +1,58 @@
+# src/utils/
+
+## Responsibility
+
+This folder contains low-level, reusable helpers used across the `pi-qol` extension. They are pure utility modules with no business logic or UI concerns.
+
+- **`crayon.util.ts`** — ANSI terminal styling: colorize text with hex foreground/background colors, apply reverse video, and strip ANSI escape sequences.
+- **`model-resolver.util.ts`** — Resolve a concrete AI model and its authentication credentials from a configured `ModelConfig` or the active session model.
+- **`raw-data-parser.util.ts`** — Type-safe coercion helpers for `unknown` runtime values into `Record<string, unknown>`, trimmed `string`, or finite `number`.
+- **`path.util.ts`** — Locate extension-specific files on disk: generic file existence checks, global/project extension `config.json`, and the shared `auth.json` file.
+
+## Design Patterns
+
+- **Static utility classes** (`RawDataParser`, `PathUtil`) group related stateless functions under a clear namespace.
+- **Service class with injected context** (`ModelResolver`) receives an `ExtensionContext` dependency rather than importing global state, keeping it testable and decoupled.
+- **Object-as-namespace export** (`crayon`) exposes a small, discoverable API surface while hiding internal helpers (`hexToRgb`, `fgAnsi`, `bgAnsi`, `ANSI_ESCAPE_REGEX`).
+- **Result/Option types** (`ResolveModelResult`, `FileSearchResult`) avoid exceptions and force callers to handle success and failure paths explicitly.
+- **Function overloads** (`PathUtil.findExtensionConfig`) provide type-safe, domain-driven entry points for global vs. project lookups.
+- **Defensive validation** (`RawDataParser`, `crayon.colorize`) silently returns `undefined` or the original input when data is invalid instead of throwing.
+
+## Data & Control Flow
+
+1. **Terminal styling**
+   - `crayon.colorize(text, { fg?, bg? })` validates hex strings against `COLOR_HEX_REGEX`.
+   - Valid colors are converted to RGB and wrapped in ANSI escape codes; the text is returned unchanged if no valid colors are provided.
+   - `crayon.stripAnsi(text)` removes all ANSI escape sequences using a compiled regex.
+
+2. **Model resolution**
+   - `ModelResolver.resolveModel(configModel?)` builds a candidate list in priority order: configured model first, then the active session model (deduplicated).
+   - For each candidate it calls `ctx.modelRegistry.getApiKeyAndHeaders(model)`.
+   - The first candidate with successful auth is returned as a `ResolvedModel`, including the API key, headers, reasoning settings, and OAuth flag.
+   - If all candidates fail, a consolidated error string is returned.
+
+3. **Raw data parsing**
+   - `RawDataParser.asRecord` checks for non-null, non-array objects.
+   - `stringValue` returns only non-empty trimmed strings.
+   - `numberValue` coerces strings/numbers and returns only finite values.
+
+4. **Path resolution**
+   - `PathUtil.findFile` checks `existsSync` and returns both existence and the resolved path.
+   - `findExtensionConfig({ type: 'global' })` resolves to `<agentDir>/extensions/<EXTENSION_ID>/config.json`.
+   - `findExtensionConfig({ type: 'project', cwd })` resolves to `<cwd>/.pi/extensions/<EXTENSION_ID>/config.json`.
+   - `findPiAuthConfig` resolves to `<agentDir>/auth.json`.
+
+## Integration Points
+
+- `@earendil-works/pi-coding-agent`
+  - `ExtensionContext` is injected into `ModelResolver` for model registry and session access.
+  - `getAgentDir()` is used by `PathUtil` to resolve global and auth paths.
+- `@earendil-works/pi-ai`
+  - `Model<Api>` is the resolved entity returned by `ModelResolver`.
+- `../constants`
+  - `COLOR_HEX_REGEX` drives hex validation in `crayon`.
+  - `EXTENSION_ID` is used by `PathUtil` to build config directory paths.
+- `../schemas/shared-config.schema`
+  - `ModelConfig` and its `reasoning` field are consumed by `ModelResolver`.
+- `node:fs` / `node:path`
+  - `PathUtil` relies on Node built-ins for synchronous file existence and cross-platform path joining.

package/src/utils/path.util.ts

@@ -1,8 +1,11 @@
 import { existsSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
 import path from 'node:path';
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { EXTENSION_ID } from '../constants';
 
+const SHELL_VAR_REGEX = /\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
 export type FileSearchResult = {
   exists: boolean;
   path: string;
@@ -11,6 +14,27 @@ export type FileSearchResult = {
 type FindConfigInput = { type: 'global' } | { type: 'project'; cwd: string };
 
 export class PathUtil {
+  /**
+   * Expand shell-style variables in a path string.
+   * Supports: `~`, `$HOME`, `$USER`, `$VAR`, `${VAR}`.
+   */
+  static expandPath(rawPath: string): string {
+    let result = rawPath;
+
+    result = result.replace(SHELL_VAR_REGEX, (_match, braced, bare) => {
+      const name = braced ?? bare;
+      if (name === 'HOME') return homedir();
+      if (name === 'USER') return userInfo().username;
+      return process.env[name] ?? _match;
+    });
+
+    if (result === '~' || result.startsWith('~/') || result.startsWith('~\\')) {
+      result = path.join(homedir(), result.slice(1));
+    }
+
+    return result;
+  }
+
   static findFile(filePath: string): FileSearchResult {
     if (existsSync(filePath)) {
       return { exists: true, path: filePath };