@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/dist/types/overlays/hub-frame.d.ts

@@ -0,0 +1,77 @@
+/** A scope row shared by fullscreen hubs, with hub-specific kinds and metadata. */
+export interface SidebarEntry<TKind extends string> {
+    id: string;
+    kind: TKind;
+    label: string;
+    annotation?: string;
+}
+/** A pre-styled footer choice carrying a hub-specific action. */
+export interface StripChip<TAction> {
+    label: string;
+    styled: string;
+    action: TAction;
+}
+/** Shared selection state for a hub's chip-bearing strip variants. */
+export interface StripState<TChip extends StripChip<unknown>> {
+    chips: TChip[];
+    index: number;
+}
+/** A chip hit range in frame-relative columns. */
+export interface ChipRange {
+    start: number;
+    end: number;
+    index: number;
+}
+/** Hub-specific sidebar decoration, independent of viewport and row layout. */
+export interface SidebarStyle {
+    icon: string;
+    annotation: string;
+    muted?: boolean;
+    hovered?: boolean;
+    padTruncated?: boolean;
+}
+/** Cycle a strip's selection for directional and tab input, returning whether it handled the key. */
+export declare function moveStripSelection(strip: StripState<StripChip<unknown>>, data: string): boolean;
+/** Persistent fullscreen split frame, sidebar viewport, and footer chip renderer. */
+export declare class HubFrame {
+    #private;
+    /** Current sidebar viewport offset, shared with the hub's navigation. */
+    sidebarScroll: number;
+    /** Chip hit ranges from the last footer render. */
+    chipRanges: ChipRange[];
+    /** Compose hub-specific sidebar and body renderers into a persistent frame. */
+    constructor(title: string, sidebarBounds: {
+        min: number;
+        max: number;
+    }, renderSidebar: (width: number, rows: number) => string[], renderBody: (width: number, height: number | undefined) => readonly string[]);
+    /** Invalidate the composed layout. */
+    invalidate(): void;
+    /** Measure labels and annotations within this hub's sidebar width bounds. */
+    sidebarWidth(entries: readonly SidebarEntry<string>[]): number;
+    /** Pan the sidebar within the current viewport's bounds. */
+    scrollSidebar(delta: number, rows: number, entryCount: number): void;
+    /** Select a footer chip at a frame-relative column, if one was painted there. */
+    selectChipAt(strip: StripState<StripChip<unknown>>, col: number): boolean;
+    /** Render the sidebar viewport while retaining each hub's follow and clipping policy. */
+    renderSidebar<TEntry extends SidebarEntry<string>>(entries: readonly TEntry[], width: number, rows: number, selection: {
+        id: string;
+        focused: boolean;
+        follow: boolean;
+        clamp: boolean;
+    }, style: (entry: TEntry, index: number) => SidebarStyle): string[];
+    /** Render footer hints or a hub-specific strip, resetting stale mouse ranges. */
+    renderFooter(width: number, hint: string, renderStrip?: () => string): string;
+    /** Render footer chips from a hub-selected horizontal window and record their hit ranges. */
+    renderChips(width: number, prefix: string, strip: StripState<StripChip<unknown>>, start?: number): string;
+    /** Translate a mouse position into footer, sidebar, and body coordinates. */
+    locate(row: number, col: number): {
+        footerColumn: number | undefined;
+        bodyHeight: number;
+        contentLine: number;
+        overSidebar: boolean;
+        overBody: boolean;
+        bodyLine: number;
+    };
+    /** Paint a complete fullscreen hub with its title, width bounds, and contextual footer. */
+    render(width: number, height: number, entries: readonly SidebarEntry<string>[], footer: string): readonly string[];
+}

package/dist/types/overlays/login-dialog.d.ts

@@ -0,0 +1,43 @@
+import type { OAuthPrompt } from "@oh-my-pi/pi-ai/oauth/types";
+import { type TUI } from "../index.js";
+import { OverlayPanel } from "../chrome/overlay-box.js";
+/**
+ * Login dialog component - replaces editor during OAuth login flow
+ */
+export declare class LoginDialogComponent extends OverlayPanel {
+    #private;
+    constructor(tui: TUI, providerId: string, onComplete: (success: boolean, message?: string) => void, openUrl: (url: string) => void);
+    get signal(): AbortSignal;
+    /**
+     * Called by the OAuth `onAuth` callback. Renders the full authorization URL
+     * as the primary copy target — that works from any machine, including
+     * SSH/WSL/headless sessions where the OMP-hosted `launchUrl` would resolve
+     * against the user's local browser and fail. When `launchUrl` is present it
+     * is offered as an additional local shortcut so narrow local terminals still
+     * have a truncation-safe copy target (viewport clipping on a long authorize
+     * URL silently drops trailing OAuth query parameters — e.g.
+     * `code_challenge_method=S256`). Every physical URL row carries its own OSC 8
+     * link to the full URL, so clicking any wrapped fragment opens the same target.
+     */
+    showAuth(url: string, instructions?: string, launchUrl?: string): void;
+    /**
+     * Show input for manual code/URL entry (for callback server providers)
+     */
+    showManualInput(prompt: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * Called by onPrompt callback - show prompt and wait for input
+     * Note: Does NOT clear content, appends to existing (preserves URL from showAuth)
+     */
+    showPrompt(prompt: OAuthPrompt): Promise<string>;
+    /**
+     * Show waiting message (for polling flows like GitHub Copilot)
+     */
+    showWaiting(message: string): void;
+    /**
+     * Called by onProgress callback
+     */
+    showProgress(message: string): void;
+    /** Route non-bracketed paste transports into the active login input. */
+    pasteText(text: string): void;
+    handleInput(data: string): void;
+}

package/dist/types/overlays/logout-account-selector.d.ts

@@ -0,0 +1,15 @@
+import { OverlayPanel } from "../chrome/overlay-box.js";
+export interface LogoutAccount {
+    credentialId: number;
+    provider: string;
+    label: string;
+    detail: string;
+    type: "api_key" | "oauth";
+    active: boolean;
+}
+/** Account picker for `/logout` after the provider has been selected. */
+export declare class LogoutAccountSelectorComponent extends OverlayPanel {
+    #private;
+    constructor(providerName: string, accounts: LogoutAccount[], onSelect: (account: LogoutAccount) => void, onCancel: () => void);
+    handleInput(keyData: string): void;
+}

package/dist/types/overlays/mcp-add-wizard.d.ts

@@ -0,0 +1,87 @@
+import { OverlayPanel } from "../chrome/overlay-box.js";
+type Scope = "user" | "project";
+/** Authentication fields produced by the wizard. */
+interface MCPAddWizardAuth {
+    type: "oauth";
+    credentialId: string;
+    tokenUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    resource?: string;
+}
+interface MCPAddWizardConfigBase {
+    timeout?: number;
+    auth?: MCPAddWizardAuth;
+}
+interface MCPAddWizardStdioConfig extends MCPAddWizardConfigBase {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+interface MCPAddWizardRemoteConfig extends MCPAddWizardConfigBase {
+    type: "http" | "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** Server configuration fields produced for testing and persistence. */
+export type MCPAddWizardConfig = MCPAddWizardStdioConfig | MCPAddWizardRemoteConfig;
+interface MCPAddWizardOAuthEndpoints {
+    authorizationUrl: string;
+    tokenUrl: string;
+    issuerUrl?: string;
+    clientId?: string;
+    registrationUrl?: string;
+    scopes?: string;
+    resource?: string;
+}
+interface MCPAddWizardAuthDetection {
+    requiresAuth: boolean;
+    authType?: "oauth" | "apikey" | "unknown";
+    oauth?: MCPAddWizardOAuthEndpoints;
+    authServerUrl?: string;
+    resourceMetadataUrl?: string;
+    scopes?: string;
+}
+/** Host-owned validation and OAuth discovery capabilities. */
+export interface MCPAddWizardDeps {
+    validateServerName(name: string): string | undefined;
+    analyzeAuthError(error: Error, serverUrl?: string): MCPAddWizardAuthDetection;
+    discoverOAuthEndpoints(serverUrl: string, authServerUrl?: string, resourceMetadataUrl?: string, options?: {
+        protectedScopes?: string;
+    }): Promise<MCPAddWizardOAuthEndpoints | null>;
+    fetchResourceMetadataScopes(resourceMetadataUrl: string): Promise<string | undefined>;
+}
+/**
+ * Result of the wizard's OAuth callback. `credentialId` is mandatory;
+ * `clientId` is populated when the OAuth provider performed dynamic client
+ * registration (or when the caller pre-supplied it) so the wizard can fold it
+ * into the final `mcp.json` entry. Refresh material (including any DCR client
+ * secret) is embedded in the stored credential, never written to config files.
+ */
+export interface MCPAddWizardOAuthResult {
+    credentialId: string;
+    clientId?: string;
+    resource?: string;
+}
+interface MCPAddWizardOAuthOptions {
+    serverUrl?: string;
+    resource?: string;
+    stripSameOriginResource?: boolean;
+    registrationUrl?: string;
+    issuerUrl?: string;
+    /**
+     * External cancellation source. Aborting it tears down the in-flight OAuth
+     * flow and surfaces a neutral cancellation error. The wizard wires its own
+     * controller here so Esc cancels the OAuth wait instead of stepping back
+     * through the form (the wizard is focused, so the editor's Esc hook does
+     * not fire).
+     */
+    abortSignal?: AbortSignal;
+}
+export declare class MCPAddWizard extends OverlayPanel {
+    #private;
+    constructor(deps: MCPAddWizardDeps, onComplete: (name: string, config: MCPAddWizardConfig, scope: Scope) => void, onCancel: () => void, onOAuth?: (authUrl: string, tokenUrl: string, clientId: string, clientSecret: string, scopes: string, options?: MCPAddWizardOAuthOptions) => Promise<MCPAddWizardOAuthResult>, onTestConnection?: (config: MCPAddWizardConfig) => Promise<void>, onRender?: () => void, initialName?: string);
+    handleInput(keyData: string): void;
+}
+export {};

package/dist/types/overlays/model-browser.d.ts

@@ -0,0 +1,213 @@
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { Component } from "../tui.js";
+import type { SgrMouseEvent } from "../mouse.js";
+import { type ConfiguredThinkingLevel } from "../thinking.js";
+import { type ThemeColor } from "../theme/theme.js";
+/** Canonical display ordering of built-in model roles. */
+export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "tiny" | "task" | "advisor";
+export declare const MODEL_ROLE_IDS: ModelRole[];
+/** Measured model performance shown in browser rows. */
+export interface ModelBrowserPerf {
+    samples: number;
+    tps: number;
+    ttftMs: number | null;
+}
+/** Role metadata shown in model selectors. */
+export interface ModelBrowserRoleInfo {
+    tag?: string;
+    name: string;
+    color?: ThemeColor;
+    hidden?: boolean;
+}
+/** Role lookup used for scoped model resolution. */
+export interface ModelRoleLookup {
+    getModelRole(role: string): string | undefined;
+}
+/** Resolved selector metadata required by model overlays. */
+export interface ResolvedModelRoleValue {
+    model: Model | undefined;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    explicitThinkingLevel: boolean;
+    warning?: string;
+}
+/** Host-provided preferences and model-role resolution for the browser. */
+export interface ModelBrowserSource extends ModelRoleLookup {
+    readonly defaultThinkingLevel: string;
+    readonly modelProviderOrder: readonly string[];
+    readonly knownRoleIds: readonly string[];
+    readonly mruOrder: readonly string[];
+    readonly modelPerf: ReadonlyMap<string, ModelBrowserPerf>;
+    getRoleInfo(role: string): ModelBrowserRoleInfo;
+    resolveRoleValue(value: string | undefined, models: Model[], roleLookup?: ModelRoleLookup): ResolvedModelRoleValue;
+}
+/** Read-only catalog surface consumed by model browsers. */
+export interface ModelBrowserRegistry {
+    getError(): unknown;
+    getAvailable(): Model[];
+    getAll(): Model[];
+}
+/** One selectable row. `selector` is a canonical model key or host-specific virtual key. */
+export interface ModelBrowserItem {
+    provider: string;
+    id: string;
+    model: Model;
+    selector: string;
+    /** Optional foreground color for the row label. */
+    labelColor?: ThemeColor;
+}
+/** Resolved role assignment as displayed by the browser and the hub. */
+export interface RoleAssignment {
+    model: Model;
+    thinkingLevel: ConfiguredThinkingLevel;
+    /** True when the role has no configured value and fell back to auto-selection. */
+    autoSelected: boolean;
+}
+/** Map of role id to its resolved assignment (absent roles are unresolved). */
+export type RoleAssignments = Record<string, RoleAssignment | undefined>;
+/**
+ * Resolve every known role to its display assignment: configured role values
+ * resolve against `allModels`; unconfigured roles fall back to auto-selection
+ * over `autoCandidates` (skipped when empty). Shared by the /models hub and
+ * the alt+p session picker.
+ */
+export declare function resolveRoleAssignments(settings: ModelBrowserSource, allModels: ReadonlyArray<Model>, autoCandidates: ReadonlyArray<Model>): RoleAssignments;
+/** Wrap raw models into browser items. */
+export declare function buildBrowserItems(models: ReadonlyArray<Model>): ModelBrowserItem[];
+/** Options for {@link sortModelItems}. */
+export interface SortModelItemsOptions {
+    roles?: RoleAssignments;
+    mruOrder?: ReadonlyArray<string>;
+    /**
+     * When a search query is narrowing the list, role assignments should NOT
+     * promote a weakly-matching default model above a perfect text match —
+     * defer to MRU/version instead so user affinity drives the order.
+     */
+    skipRoleRank?: boolean;
+}
+/**
+ * Order models for display: role-assigned first, then most-recently-used,
+ * then per provider by priority, version, and recency.
+ */
+export declare function sortModelItems(items: ModelBrowserItem[], options?: SortModelItemsOptions): void;
+/** Picker candidates and ordering inputs shared with composer model mentions. */
+export interface SessionModelScope {
+    items: ModelBrowserItem[];
+    roles: RoleAssignments;
+    mruOrder: ReadonlyArray<string>;
+    error: string | undefined;
+}
+/** Build the session picker's current scope without creating an interactive browser. */
+export declare function buildSessionModelScope(settings: ModelBrowserSource, registry: ModelBrowserRegistry, scopedModels: ReadonlyArray<Model>): SessionModelScope;
+/** User affinity used to order search matches within one relevance tier. */
+export interface SearchAffinity {
+    /** `provider/id` (lowercased) → rank; configured-role models first, then MRU. */
+    models: Map<string, number>;
+    /** provider (lowercased) → rank; explicit order, then role providers, then MRU providers. */
+    providers: Map<string, number>;
+}
+/**
+ * Build model and provider affinity from explicit configuration, configured
+ * role assignments, and recent model use. Auto-selected roles are catalog
+ * policy, not evidence of user preference.
+ */
+export declare function buildSearchAffinity(providerOrder: ReadonlyArray<string>, roles: RoleAssignments, mruOrder: ReadonlyArray<string>): SearchAffinity;
+/** Rank picker and mention candidates by text relevance, user affinity, and MRU/version order. */
+export declare function rankModelItems(query: string, items: ReadonlyArray<ModelBrowserItem>, options: {
+    roles: RoleAssignments;
+    mruOrder: ReadonlyArray<string>;
+    affinity: SearchAffinity;
+}): ModelBrowserItem[];
+/**
+ * A slim role chip: `● default ◉` — solid dot for configured assignments,
+ * hollow for auto-selected fallbacks, thinking glyph attached when set.
+ *
+ * The space after the status glyph is load-bearing. Under the `nerd` preset
+ * these are Nerd Font private-use icons (U+F111 / U+F10C) whose glyphs are
+ * drawn two cells wide, while `visibleWidth` counts them as one
+ * (`ambiguousIsNarrow: true` in tui/utils.ts — the PUA block is
+ * East_Asian_Width=Ambiguous). Without a separator the icon overhangs and
+ * eats the label's first character (`● default` renders as `●efault`).
+ * Mirrors the spacing already used for `status.success` in model-hub.
+ */
+export declare function formatRoleChip(role: string, assignment: RoleAssignment, settings: ModelBrowserSource): string;
+/**
+ * The fuzzy haystack for a model row: the displayed `provider/id`, plus `free`
+ * for zero-cost models so the cost column's own word is searchable even when
+ * the id never says it (openrouter suffixes `:free`; nvidia does not).
+ *
+ * Must stay a pure function of the item — never of the query. `fuzzyRank`
+ * caches match indices keyed on this string and stops admitting new entries
+ * past its cap, so a query-dependent haystack would thrash that cache.
+ */
+export declare function modelSearchText({ provider, id, model }: ModelBrowserItem): string;
+/** Behavior switches for {@link ModelBrowser}. */
+export interface ModelBrowserOptions {
+    /** Render the dim `provider/` prefix before model ids. Default true. */
+    showProvider?: boolean;
+    /** Session token count used to flag models whose context window is exceeded. */
+    currentContextTokens?: number;
+    /** When true, over-context rows render grayed; picking one compacts first (session-switch mode). */
+    markOverContext?: boolean;
+    /** Host-provided empty-state text (e.g. provider discovery status). */
+    emptyText?: () => string | undefined;
+}
+/**
+ * The reusable browser component. Renders a fixed-height block
+ * (`maxVisible + LIST_ROW_START + DETAIL_ROWS` rows) so host mouse geometry
+ * stays stable across renders.
+ */
+export declare class ModelBrowser implements Component {
+    #private;
+    /** Enter or click-on-selected. */
+    onActivate?: (item: ModelBrowserItem) => void;
+    onSelectionChange?: (item: ModelBrowserItem | undefined) => void;
+    onQueryChange?: (query: string) => void;
+    /** Cancel key with an empty query (a non-empty query is cleared first). */
+    onCancel?: () => void;
+    constructor(settings: ModelBrowserSource, options?: ModelBrowserOptions);
+    /** Mark `selector` as the session's active model (undefined clears the mark). */
+    setCurrentSelector(selector: string | undefined): void;
+    /** Replace the scope's base items; the live query re-applies and selection is pinned by selector. */
+    setItems(items: ModelBrowserItem[]): void;
+    setRoles(roles: RoleAssignments): void;
+    setMruOrder(order: ReadonlyArray<string>): void;
+    /** Measured TPS/TTFT averages keyed by `provider/id` selector (see AgentStorage.getModelPerf). */
+    setPerfStats(perf: ReadonlyMap<string, ModelBrowserPerf>): void;
+    setMaxVisible(rows: number): void;
+    setShowProvider(show: boolean): void;
+    /** Keep the source order after fuzzy filtering instead of applying model-specific ranking. */
+    setPreserveQueryOrder(preserve: boolean): void;
+    /** Allow hosts to toggle context-window flagging between browser modes. */
+    setMarkOverContext(mark: boolean): void;
+    /** Focused: accent cursor + selected-row background band. Unfocused: dim cursor, no band. */
+    setFocused(focused: boolean): void;
+    /** Total rendered height for the current `maxVisible` (host layout budgeting). */
+    get renderedRows(): number;
+    get query(): string;
+    setQuery(query: string): void;
+    getSelected(): ModelBrowserItem | undefined;
+    get visibleCount(): number;
+    /** Move selection to `selector`; false when it is not in the current view. */
+    selectSelector(selector: string): boolean;
+    /** True when `item`'s context window is smaller than the live session token count (grayed row; hosts compact before switching). */
+    isOverContext(item: ModelBrowserItem): boolean;
+    /**
+     * Move the selection by `delta` rows, skipping disabled rows. Single steps
+     * wrap at the ends; `wrap: false` (page/home/end jumps) clamps instead.
+     */
+    moveSelection(delta: number, options?: {
+        wrap?: boolean;
+    }): void;
+    handleInput(data: string): void;
+    /** Cancel-key ladder: clear a non-empty query first, then bubble to the host. */
+    handleCancel(): void;
+    /**
+     * Route a mouse event. `line` is relative to the browser's first rendered
+     * row (the search row).
+     */
+    routeMouse(event: SgrMouseEvent, line: number): void;
+    /** Drop the hover band. Hosts call this when the pointer leaves the browser pane. */
+    clearHover(): void;
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/types/overlays/model-hub.d.ts

@@ -0,0 +1,72 @@
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { Component, TUI } from "../tui.js";
+import type { ModelBrowserSource, ModelBrowserRegistry } from "./model-browser.js";
+import { type ConfiguredThinkingLevel } from "../thinking.js";
+/** Live preferences and selector operations supplied by the host. */
+export interface ModelHubSource extends ModelBrowserSource {
+    readonly disabledProviders: readonly string[];
+    readonly fallbackChains: Record<string, string[]>;
+    readonly modelRoleStorage: "global" | "project";
+    readonly cycleOrder: readonly string[];
+    getProjectModelRole(role: string): string | undefined;
+    getGlobalModelRole(role: string): string | undefined;
+    getModelRoleSource(role: string): "global" | "project" | "default";
+}
+/** Catalog capabilities required by the model hub. */
+export interface ModelHubRegistry extends ModelBrowserRegistry {
+    readonly authStorage: {
+        hasAuth(provider: string): boolean;
+    };
+    getDiscoverableProviders(): string[];
+    getProviderDiscoveryState(provider: string): {
+        optional: boolean;
+        status: "idle" | "ok" | "empty" | "cached" | "unavailable" | "unauthenticated";
+        fetchedAt?: number;
+        error?: string;
+    } | undefined;
+    find(provider: string, id: string): Model | undefined;
+    refresh(strategy: "online"): Promise<void>;
+    refreshProvider(provider: string, strategy: "online", options?: {
+        refreshCommandCredentials?: boolean;
+    }): Promise<void>;
+}
+/** A `--models` scope entry (mirrors the session's scoped model list). */
+export interface ScopedModelItem {
+    model: Model;
+    thinkingLevel?: string;
+}
+export type ModelRoleSelectionScope = "global" | "project";
+export interface ModelHubCallbacks {
+    /** Persist a role assignment. */
+    onAssign: (model: Model, role: string, thinkingLevel: ConfiguredThinkingLevel | undefined, selector: string, scope?: ModelRoleSelectionScope) => void | boolean | Promise<void | boolean>;
+    /** Clear a configured role back to auto-selection. */
+    onUnassign: (role: string, scope?: ModelRoleSelectionScope) => void;
+    /** Persist a `retry.fallbackChains` entry — keyed by a role, `provider/model-id`, or `provider/*`; an empty chain clears the key. */
+    onFallbackChainChange?: (role: string, chain: string[]) => void;
+    /** Locked provider activation: forward to the /login flow. */
+    onLoginRequest?: (providerId: string) => void;
+    /** Persist a new quick-switch cycle order (the ctrl+p role cycle). */
+    onCycleOrderChange?: (order: string[]) => void;
+    onCancel: () => void;
+}
+export interface ModelHubOptions {
+    /** Preselect this provider's sidebar entry (e.g. when reopening after /login). */
+    initialProviderId?: string;
+}
+/** Test hook: forget which providers were auto-refreshed this process. */
+export declare function resetProviderAutoRefreshGuard(): void;
+/**
+ * The fullscreen model hub component. Hosted via `ui.showOverlay(..., { fullscreen: true })`;
+ * the host must call {@link ModelHubComponent.dispose} when the overlay closes.
+ */
+export declare class ModelHubComponent implements Component {
+    #private;
+    constructor(tui: TUI, settings: ModelHubSource, registry: ModelHubRegistry, scopedModels: ReadonlyArray<ScopedModelItem>, callbacks: ModelHubCallbacks, options?: ModelHubOptions);
+    /** Cancel pending provider refresh timers and the spinner. Host calls this on overlay close. */
+    dispose(): void;
+    invalidate(): void;
+    /** Re-sync after an asynchronous callback finishes mutating settings. */
+    refreshAfterExternalMutation(): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+}

package/dist/types/overlays/model-picker.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Compact session-model picker (alt+p / `/switch`): a bottom-anchored
+ * floating overlay hosting just a {@link ModelBrowser} — no provider sidebar.
+ * Model entries switch the current session only; a search beginning with `@`
+ * exposes the configured ctrl+p quick roles.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+import { type KeyId } from "../keys.js";
+import type { Component, TUI } from "../tui.js";
+import type { ModelBrowserRegistry, ModelBrowserSource } from "./model-browser.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { ScopedModelItem } from "./model-hub.js";
+/** Configured role resolved to a concrete model. */
+export interface ResolvedRoleModel {
+    role: string;
+    model: Model;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    explicitThinkingLevel: boolean;
+}
+/** Catalog refresh capability used by the session picker. */
+export interface ModelPickerRegistry extends ModelBrowserRegistry {
+    refresh(strategy: "offline"): Promise<void>;
+}
+export interface ModelPickerCallbacks {
+    /**
+     * A model was chosen for a session-only switch. `selector` is `provider/id`.
+     * `overContext` is true when the session transcript exceeds the model's
+     * context window — the host must compact before switching.
+     */
+    onPick: (model: Model, selector: string, meta: {
+        overContext: boolean;
+    }) => void;
+    /** A configured ctrl+p quick role was chosen. */
+    onPickRole?: (entry: ResolvedRoleModel) => void;
+    /**
+     * A model was chosen for Task subagents (task mode, toggled by pressing the
+     * picker shortcut again). Session-only: the host applies a runtime override.
+     */
+    onPickTask?: (model: Model, selector: string) => void;
+    /** The picker was dismissed. */
+    onCancel: () => void;
+}
+export interface ModelPickerOptions {
+    /** Session token count; models with smaller context windows are grayed and compact-first on pick. */
+    currentContextTokens?: number;
+    /** `provider/id` of the session's active model; highlighted and preselected. */
+    currentSelector?: string;
+    /** Resolved role models in the same order used by the ctrl+p quick-role cycle. */
+    quickRoles?: ReadonlyArray<ResolvedRoleModel>;
+    /** Complete ctrl+p order, including unavailable roles, to preserve segment colors. */
+    quickRoleOrder?: ReadonlyArray<string>;
+    /** Active quick role, highlighted when the search begins with `@`. */
+    currentQuickRole?: string;
+    /** Keys that toggle task-subagent mode while the picker is open; typically the alt+p binding. */
+    taskModeKeys?: readonly KeyId[];
+    /** Human-readable label for the toggle key, shown in footer hints (e.g. "alt+p"). */
+    taskModeKeyLabel?: string;
+    /** `provider/id` highlighted and preselected in task mode (current Task subagent model). */
+    taskSelector?: string;
+}
+/** Rows the browser renders around its list window (search + blank, blank + two detail rows). */
+export declare const BROWSER_FRAME_ROWS = 5;
+/**
+ * The alt+p picker component. Hosted as a non-fullscreen bottom-anchored
+ * overlay (`ui.showOverlay(..., { anchor: "bottom-center" })`); keyboard-only,
+ * since mouse tracking is reserved for fullscreen overlays.
+ */
+export declare class ModelPickerComponent implements Component {
+    #private;
+    constructor(tui: TUI, settings: ModelBrowserSource, registry: ModelPickerRegistry, scopedModels: ReadonlyArray<ScopedModelItem>, callbacks: ModelPickerCallbacks, options?: ModelPickerOptions);
+    invalidate(): void;
+    handleInput(data: string): void;
+    render(width: number): string[];
+}

package/dist/types/overlays/model-selector.d.ts

@@ -0,0 +1,52 @@
+import { type ConfiguredThinkingLevel } from "../thinking.js";
+/** Opt-in selectors that can otherwise be literal model-id suffixes. */
+export interface ThinkingSuffixOptions {
+    allowMaxSuffix?: boolean;
+    allowAutoAlias?: boolean;
+}
+/** Selector parsing options with authoritative literal-model lookup. */
+export interface ModelStringParseOptions extends ThinkingSuffixOptions {
+    isLiteralModelId?: (provider: string, id: string) => boolean;
+}
+/** Recognize all configured effort selectors after literal-id matching. */
+export declare const MAX_THINKING_SUFFIX_OPTIONS: ThinkingSuffixOptions;
+/** Parse a suffix while preserving selectors not explicitly enabled. */
+export declare function parseThinkingSuffix(value: string, options?: ThinkingSuffixOptions): ConfiguredThinkingLevel | undefined;
+/**
+ * Split a trailing `:<level>` thinking selector off a model pattern.
+ *
+ * `level` is set when the suffix parses as a concrete thinking level (or, when
+ * the caller opts in via `allowMaxSuffix`/`allowAutoAlias`, the guarded `:max`
+ * level / `:auto` sentinel); `base` then has the suffix stripped. Otherwise
+ * `base` is the input.
+ * `minColonIndex` requires the colon to appear strictly after that index —
+ * role-alias callers pass the matched alias prefix length.
+ */
+export declare function splitThinkingSuffix(pattern: string, minColonIndex?: number, options?: ThinkingSuffixOptions): {
+    base: string;
+    level?: ConfiguredThinkingLevel;
+};
+/**
+ * Parse a model string in "provider/modelId" format.
+ * Returns undefined if the format is invalid.
+ */
+export declare function parseModelString(modelStr: string, options?: ModelStringParseOptions): {
+    provider: string;
+    id: string;
+    thinkingLevel?: ConfiguredThinkingLevel;
+} | undefined;
+export declare function formatModelSelectorValue(selector: string, thinkingLevel: ConfiguredThinkingLevel | undefined): string;
+/**
+ * Split a trailing `@<upstream>` provider-routing selector off a model pattern.
+ *
+ * `openrouter/z-ai/glm-4.7@cerebras` -> base `openrouter/z-ai/glm-4.7`, upstream
+ * `cerebras`. Tiered upstreams keep their path (`...@google-ai-studio/priority`).
+ * A `:thinking` suffix after the slug is kept on the base
+ * (`...@cerebras:high` -> base `...:high`). Returns undefined when there is no
+ * `@` or the suffix is not a bare provider slug, so model ids that legitimately
+ * contain `@` (`claude-opus-4-8@default`, `workers-ai/@cf/...`) are never split.
+ */
+export declare function splitUpstreamRouting(pattern: string): {
+    base: string;
+    upstream: string;
+} | undefined;