@nicknisi/pi-model-switch 0.1.0 → 0.2.1

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export interface ModelSwitchSection {
+    name: string;
+    models: string[];
+}
+export interface ModelSwitchConfig {
+    sections: ModelSwitchSection[];
+}
+export interface ModelSwitchKeybindings {
+    forward: string;
+    backward: string;
+    select: string;
+}
+export declare const DEFAULT_MODEL_CYCLE_KEYBINDINGS: ModelSwitchKeybindings;
+export type ConfigLoadResult = {
+    ok: true;
+    config: ModelSwitchConfig;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function modelCycleConfigPath(): string;
+export declare function modelCycleKeybindingsPath(): string;
+export declare function loadModelSwitchKeybindings(path?: string): ModelSwitchKeybindings;
+export declare function loadModelSwitchConfig(path?: string): ConfigLoadResult;

package/dist/config.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+export const DEFAULT_MODEL_CYCLE_KEYBINDINGS = {
+    forward: 'ctrl+shift+m',
+    backward: 'ctrl+shift+alt+m',
+    select: 'ctrl+shift+l',
+};
+const FORWARD_KEYBINDING = 'model-switch.cycleForward';
+const BACKWARD_KEYBINDING = 'model-switch.cycleBackward';
+const SELECT_KEYBINDING = 'model-switch.select';
+export function modelCycleConfigPath() {
+    return join(getAgentDir(), 'configs', 'model-switch.json');
+}
+export function modelCycleKeybindingsPath() {
+    return join(getAgentDir(), 'keybindings.json');
+}
+export function loadModelSwitchKeybindings(path = modelCycleKeybindingsPath()) {
+    if (!existsSync(path))
+        return { ...DEFAULT_MODEL_CYCLE_KEYBINDINGS };
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return { ...DEFAULT_MODEL_CYCLE_KEYBINDINGS };
+    }
+    if (!value || typeof value !== 'object')
+        return { ...DEFAULT_MODEL_CYCLE_KEYBINDINGS };
+    const bindings = value;
+    const forward = bindings[FORWARD_KEYBINDING];
+    const backward = bindings[BACKWARD_KEYBINDING];
+    const select = bindings[SELECT_KEYBINDING];
+    return {
+        forward: typeof forward === 'string' && forward.trim().length > 0
+            ? forward.trim()
+            : DEFAULT_MODEL_CYCLE_KEYBINDINGS.forward,
+        backward: typeof backward === 'string' && backward.trim().length > 0
+            ? backward.trim()
+            : DEFAULT_MODEL_CYCLE_KEYBINDINGS.backward,
+        select: typeof select === 'string' && select.trim().length > 0 ? select.trim() : DEFAULT_MODEL_CYCLE_KEYBINDINGS.select,
+    };
+}
+function validateModelStrings(raw, path, context) {
+    if (!Array.isArray(raw)) {
+        return { error: `Invalid model-switch config at ${path}: expected "${context}" to be a string[]` };
+    }
+    if (raw.some((model) => typeof model !== 'string' || model.trim().length === 0)) {
+        return { error: `Invalid model-switch config at ${path}: every model in "${context}" must be a non-empty string` };
+    }
+    return raw.map((model) => model.trim());
+}
+export function loadModelSwitchConfig(path = modelCycleConfigPath()) {
+    if (!existsSync(path)) {
+        return { ok: true, config: { sections: [] } };
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Invalid model-switch config at ${path}: ${message}` };
+    }
+    if (!value || typeof value !== 'object') {
+        return { ok: false, error: `Invalid model-switch config at ${path}: expected an object` };
+    }
+    const obj = value;
+    // Prefer "sections" if present; fall back to legacy "models" as a single section.
+    if ('sections' in obj && obj.sections && typeof obj.sections === 'object') {
+        const sectionsRaw = obj.sections;
+        const sections = [];
+        for (const [name, modelsRaw] of Object.entries(sectionsRaw)) {
+            const result = validateModelStrings(modelsRaw, path, `sections.${name}`);
+            if (!Array.isArray(result))
+                return { ok: false, error: result.error };
+            sections.push({ name, models: result });
+        }
+        if (sections.length === 0) {
+            return {
+                ok: false,
+                error: `Invalid model-switch config at ${path}: "sections" must define at least one section`,
+            };
+        }
+        return { ok: true, config: { sections } };
+    }
+    if ('models' in obj) {
+        const result = validateModelStrings(obj.models, path, 'models');
+        if (!Array.isArray(result))
+            return { ok: false, error: result.error };
+        return { ok: true, config: { sections: [{ name: 'models', models: result }] } };
+    }
+    return {
+        ok: false,
+        error: `Invalid model-switch config at ${path}: expected { "sections": { ... } } or { "models": [...] }`,
+    };
+}

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_MODEL_CYCLE_KEYBINDINGS, loadModelSwitchConfig, loadModelSwitchKeybindings } from './config.js';
+const tempDirs = [];
+function tempConfig(content) {
+    const dir = mkdtempSync(join(tmpdir(), 'pi-model-switch-'));
+    tempDirs.push(dir);
+    const path = join(dir, 'model-switch.json');
+    if (content !== undefined)
+        writeFileSync(path, content);
+    return path;
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('loadModelSwitchKeybindings', () => {
+    it('uses defaults when keybindings.json is missing or malformed', () => {
+        expect(loadModelSwitchKeybindings(tempConfig())).toEqual(DEFAULT_MODEL_CYCLE_KEYBINDINGS);
+        expect(loadModelSwitchKeybindings(tempConfig('{ nope'))).toEqual(DEFAULT_MODEL_CYCLE_KEYBINDINGS);
+    });
+    it('loads extension-owned bindings from keybindings.json', () => {
+        const result = loadModelSwitchKeybindings(tempConfig(JSON.stringify({
+            'model-switch.cycleForward': 'ctrl+alt+n',
+            'model-switch.cycleBackward': 'ctrl+alt+b',
+            'model-switch.select': 'ctrl+alt+l',
+            'app.model.select': 'ctrl+l',
+        })));
+        expect(result).toEqual({
+            forward: 'ctrl+alt+n',
+            backward: 'ctrl+alt+b',
+            select: 'ctrl+alt+l',
+        });
+    });
+    it('falls back per binding when extension-owned values are absent or invalid', () => {
+        const result = loadModelSwitchKeybindings(tempConfig(JSON.stringify({
+            'model-switch.cycleForward': [],
+            'model-switch.cycleBackward': ' ctrl+alt+b ',
+        })));
+        expect(result).toEqual({
+            forward: DEFAULT_MODEL_CYCLE_KEYBINDINGS.forward,
+            backward: 'ctrl+alt+b',
+            select: DEFAULT_MODEL_CYCLE_KEYBINDINGS.select,
+        });
+    });
+});
+describe('loadModelSwitchConfig', () => {
+    it('returns empty sections when the config is missing', () => {
+        const result = loadModelSwitchConfig(tempConfig());
+        expect(result).toEqual({ ok: true, config: { sections: [] } });
+    });
+    it('loads named sections in order', () => {
+        const result = loadModelSwitchConfig(tempConfig(JSON.stringify({
+            sections: {
+                work: ['cloudflare-ai-gateway/grok-4.5', '  fireworks/.../kimi-k3  '],
+                personal: ['fireworks/.../kimi-k3'],
+            },
+        })));
+        expect(result).toEqual({
+            ok: true,
+            config: {
+                sections: [
+                    { name: 'work', models: ['cloudflare-ai-gateway/grok-4.5', 'fireworks/.../kimi-k3'] },
+                    { name: 'personal', models: ['fireworks/.../kimi-k3'] },
+                ],
+            },
+        });
+    });
+    it('falls back to legacy flat models as a single section', () => {
+        const result = loadModelSwitchConfig(tempConfig(JSON.stringify({ models: ['cloudflare-ai-gateway/grok-4.5'] })));
+        expect(result).toEqual({
+            ok: true,
+            config: { sections: [{ name: 'models', models: ['cloudflare-ai-gateway/grok-4.5'] }] },
+        });
+    });
+    it('prefers sections when both sections and models are present', () => {
+        const result = loadModelSwitchConfig(tempConfig(JSON.stringify({
+            sections: { work: ['provider/model-a'] },
+            models: ['provider/model-b'],
+        })));
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.config.sections).toEqual([{ name: 'work', models: ['provider/model-a'] }]);
+    });
+    it('reports malformed JSON with the config path', () => {
+        const path = tempConfig('{ nope');
+        const result = loadModelSwitchConfig(path);
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error).toContain(path);
+            expect(result.error).toContain('Invalid model-switch config');
+        }
+    });
+    it.each([
+        ['non-object input', '[]'],
+        ['missing sections and models', '{}'],
+        ['non-object sections', JSON.stringify({ sections: 'nope' })],
+        ['empty sections object', JSON.stringify({ sections: {} })],
+        ['non-array section models', JSON.stringify({ sections: { work: 'nope' } })],
+        ['non-string model in section', JSON.stringify({ sections: { work: [42] } })],
+        ['empty model in section', JSON.stringify({ sections: { work: ['  '] } })],
+        ['non-array legacy models', JSON.stringify({ models: 'grok-4.5' })],
+    ])('rejects %s', (_label, content) => {
+        const path = tempConfig(content);
+        const result = loadModelSwitchConfig(path);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error).toContain(path);
+    });
+});

package/dist/cycle.d.ts

@@ -0,0 +1,22 @@
+import type { Api, Model } from '@earendil-works/pi-ai';
+import type { ModelSwitchSection } from './config.js';
+export type CycleDirection = 'forward' | 'backward';
+export interface ModelReference {
+    provider: string;
+    modelId: string;
+}
+export interface ModelRegistryLike {
+    find(provider: string, modelId: string): Model<Api> | undefined;
+    getApiKeyAndHeaders(model: Model<Api>): Promise<{
+        ok: true;
+        apiKey?: string;
+        headers?: Record<string, string | null>;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+export declare function parseModelReference(value: string): ModelReference | undefined;
+export declare function resolveAvailableModels(references: readonly string[], registry: ModelRegistryLike): Promise<Model<Api>[]>;
+export declare function findActiveSection(sections: readonly ModelSwitchSection[], current: Model<Api> | undefined): ModelSwitchSection | undefined;
+export declare function selectCycleTarget(current: Model<Api> | undefined, available: readonly Model<Api>[], direction: CycleDirection): Model<Api> | undefined;

package/dist/cycle.js

@@ -0,0 +1,48 @@
+export function parseModelReference(value) {
+    const separator = value.indexOf('/');
+    if (separator <= 0 || separator === value.length - 1)
+        return undefined;
+    return {
+        provider: value.slice(0, separator),
+        modelId: value.slice(separator + 1),
+    };
+}
+export async function resolveAvailableModels(references, registry) {
+    const available = [];
+    for (const value of references) {
+        const reference = parseModelReference(value);
+        if (!reference)
+            continue;
+        const model = registry.find(reference.provider, reference.modelId);
+        if (!model)
+            continue;
+        const auth = await registry.getApiKeyAndHeaders(model);
+        if (auth.ok)
+            available.push(model);
+    }
+    return available;
+}
+export function findActiveSection(sections, current) {
+    if (sections.length === 0)
+        return undefined;
+    if (!current)
+        return sections[0];
+    const found = sections.find((section) => section.models.some((value) => {
+        const ref = parseModelReference(value);
+        return ref?.provider === current.provider && ref?.modelId === current.id;
+    }));
+    return found ?? sections[0];
+}
+export function selectCycleTarget(current, available, direction) {
+    if (available.length === 0)
+        return undefined;
+    const currentIndex = current
+        ? available.findIndex((model) => model.provider === current.provider && model.id === current.id)
+        : -1;
+    if (currentIndex === -1) {
+        return direction === 'forward' ? available[0] : available[available.length - 1];
+    }
+    const offset = direction === 'forward' ? 1 : -1;
+    const nextIndex = (currentIndex + offset + available.length) % available.length;
+    return available[nextIndex];
+}

package/dist/cycle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cycle.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { findActiveSection, parseModelReference, resolveAvailableModels, selectCycleTarget, } from './cycle.js';
+function model(provider, id) {
+    return { provider, id };
+}
+function registry(models, unauthenticated = []) {
+    const byReference = new Map(models.map((item) => [`${item.provider}/${item.id}`, item]));
+    const unavailable = new Set(unauthenticated);
+    return {
+        find(provider, modelId) {
+            return byReference.get(`${provider}/${modelId}`);
+        },
+        async getApiKeyAndHeaders(item) {
+            const reference = `${item.provider}/${item.id}`;
+            return unavailable.has(reference)
+                ? { ok: false, error: 'not authenticated' }
+                : { ok: true, apiKey: 'test' };
+        },
+    };
+}
+describe('parseModelReference', () => {
+    it('keeps slashes inside the model id', () => {
+        expect(parseModelReference('fireworks/accounts/fireworks/models/kimi-k3')).toEqual({
+            provider: 'fireworks',
+            modelId: 'accounts/fireworks/models/kimi-k3',
+        });
+    });
+    it.each(['missing-provider', '/missing-provider', 'missing-model/'])('rejects %s', (value) => {
+        expect(parseModelReference(value)).toBeUndefined();
+    });
+});
+describe('resolveAvailableModels', () => {
+    it('preserves configured order while skipping invalid, missing, and unauthenticated models', async () => {
+        const grok = model('cloudflare-ai-gateway', 'grok-4.5');
+        const kimi = model('fireworks', 'accounts/fireworks/models/kimi-k3');
+        const deepseek = model('fireworks', 'accounts/fireworks/models/deepseek-v4-pro');
+        const result = await resolveAvailableModels([
+            'fireworks/accounts/fireworks/models/kimi-k3',
+            'invalid',
+            'missing/nope',
+            'cloudflare-ai-gateway/grok-4.5',
+            'fireworks/accounts/fireworks/models/deepseek-v4-pro',
+        ], registry([grok, kimi, deepseek], ['fireworks/accounts/fireworks/models/deepseek-v4-pro']));
+        expect(result).toEqual([kimi, grok]);
+    });
+});
+describe('findActiveSection', () => {
+    const workSection = {
+        name: 'work',
+        models: ['provider/work-a', 'provider/work-b'],
+    };
+    const personalSection = {
+        name: 'personal',
+        models: ['provider/personal-a'],
+    };
+    const sections = [workSection, personalSection];
+    it('returns undefined for empty sections', () => {
+        expect(findActiveSection([], model('provider', 'x'))).toBeUndefined();
+    });
+    it('returns the first section when there is no current model', () => {
+        expect(findActiveSection(sections, undefined)).toBe(workSection);
+    });
+    it('returns the section containing the current model', () => {
+        expect(findActiveSection(sections, model('provider', 'work-b'))).toBe(workSection);
+        expect(findActiveSection(sections, model('provider', 'personal-a'))).toBe(personalSection);
+    });
+    it('falls back to the first section when the current model is not in any section', () => {
+        expect(findActiveSection(sections, model('other', 'outside'))).toBe(workSection);
+    });
+});
+describe('selectCycleTarget', () => {
+    const first = model('provider', 'first');
+    const second = model('provider', 'second');
+    const third = model('provider', 'third');
+    const available = [first, second, third];
+    it('returns undefined for an empty list', () => {
+        expect(selectCycleTarget(first, [], 'forward')).toBeUndefined();
+    });
+    it('returns the only model in either direction', () => {
+        expect(selectCycleTarget(first, [first], 'forward')).toBe(first);
+        expect(selectCycleTarget(first, [first], 'backward')).toBe(first);
+    });
+    it('enters at the directional boundary when current is outside the list', () => {
+        const outside = model('other', 'outside');
+        expect(selectCycleTarget(outside, available, 'forward')).toBe(first);
+        expect(selectCycleTarget(outside, available, 'backward')).toBe(third);
+        expect(selectCycleTarget(undefined, available, 'forward')).toBe(first);
+        expect(selectCycleTarget(undefined, available, 'backward')).toBe(third);
+    });
+    it('moves in both directions and wraps at each boundary', () => {
+        expect(selectCycleTarget(first, available, 'forward')).toBe(second);
+        expect(selectCycleTarget(second, available, 'backward')).toBe(first);
+        expect(selectCycleTarget(third, available, 'forward')).toBe(first);
+        expect(selectCycleTarget(first, available, 'backward')).toBe(third);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function modelCycle(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,94 @@
+import { loadModelSwitchConfig, loadModelSwitchKeybindings, modelCycleConfigPath } from './config.js';
+import { findActiveSection, resolveAvailableModels, selectCycleTarget } from './cycle.js';
+import { SectionPicker } from './section-picker.js';
+async function resolveSectionModels(references, ctx) {
+    return resolveAvailableModels(references, ctx.modelRegistry);
+}
+async function switchModel(pi, ctx, target) {
+    if (!(await pi.setModel(target))) {
+        ctx.ui.notify(`Could not switch to ${target.provider}/${target.id}`, 'warning');
+    }
+}
+async function cycleConfiguredModel(pi, ctx, direction) {
+    const loaded = loadModelSwitchConfig();
+    if (!loaded.ok) {
+        ctx.ui.notify(loaded.error, 'warning');
+        return;
+    }
+    const activeSection = findActiveSection(loaded.config.sections, ctx.model);
+    if (!activeSection) {
+        ctx.ui.notify(`No configured models are available in ${modelCycleConfigPath()}`, 'warning');
+        return;
+    }
+    const available = await resolveSectionModels(activeSection.models, ctx);
+    if (available.length === 0) {
+        ctx.ui.notify(`No usable models in section "${activeSection.name}" (${modelCycleConfigPath()})`, 'warning');
+        return;
+    }
+    const target = selectCycleTarget(ctx.model, available, direction);
+    if (target)
+        await switchModel(pi, ctx, target);
+}
+function buildSectionItems(models, current) {
+    return models.map((model) => {
+        const isCurrent = model.provider === current?.provider && model.id === current.id;
+        return {
+            value: `${model.provider}/${model.id}`,
+            label: `${isCurrent ? '●' : ' '} ${model.provider}/${model.id}`,
+        };
+    });
+}
+async function showModelPicker(pi, ctx) {
+    if (!ctx.hasUI)
+        return;
+    const loaded = loadModelSwitchConfig();
+    if (!loaded.ok) {
+        ctx.ui.notify(loaded.error, 'warning');
+        return;
+    }
+    const pickerSections = [];
+    const modelByReference = new Map();
+    for (const section of loaded.config.sections) {
+        const available = await resolveSectionModels(section.models, ctx);
+        if (available.length > 0) {
+            pickerSections.push({
+                name: section.name,
+                items: buildSectionItems(available, ctx.model),
+            });
+            for (const model of available) {
+                modelByReference.set(`${model.provider}/${model.id}`, model);
+            }
+        }
+    }
+    if (pickerSections.length === 0) {
+        ctx.ui.notify(`No configured models are available in ${modelCycleConfigPath()}`, 'warning');
+        return;
+    }
+    const selected = await ctx.ui.custom((tui, theme, _keybindings, done) => {
+        return new SectionPicker(pickerSections, theme, done);
+    });
+    if (!selected)
+        return;
+    const target = modelByReference.get(selected);
+    if (target)
+        await switchModel(pi, ctx, target);
+}
+export default function modelCycle(pi) {
+    const keybindings = loadModelSwitchKeybindings();
+    pi.registerShortcut(keybindings.forward, {
+        description: 'Cycle configured models forward',
+        handler: async (ctx) => cycleConfiguredModel(pi, ctx, 'forward'),
+    });
+    pi.registerShortcut(keybindings.backward, {
+        description: 'Cycle configured models backward',
+        handler: async (ctx) => cycleConfiguredModel(pi, ctx, 'backward'),
+    });
+    pi.registerShortcut(keybindings.select, {
+        description: 'Select a configured model',
+        handler: async (ctx) => showModelPicker(pi, ctx),
+    });
+    pi.registerCommand('model-switch', {
+        description: 'Select from configured models',
+        handler: async (_args, ctx) => showModelPicker(pi, ctx),
+    });
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,199 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import modelCycle from './index.js';
+const tempDirs = [];
+const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
+function model(provider, id) {
+    return { provider, id };
+}
+function tempAgentDir() {
+    const dir = mkdtempSync(join(tmpdir(), 'pi-model-switch-handler-'));
+    tempDirs.push(dir);
+    process.env.PI_CODING_AGENT_DIR = dir;
+    return dir;
+}
+function writeConfig(sections) {
+    const dir = tempAgentDir();
+    const configDir = join(dir, 'configs');
+    mkdirSync(configDir);
+    writeFileSync(join(configDir, 'model-switch.json'), JSON.stringify({ sections }));
+    return dir;
+}
+function writeKeybindings(value) {
+    const dir = tempAgentDir();
+    writeFileSync(join(dir, 'keybindings.json'), JSON.stringify(value));
+    return dir;
+}
+function harness(options = {}) {
+    if (!process.env.PI_CODING_AGENT_DIR)
+        tempAgentDir();
+    const shortcuts = new Map();
+    const commands = new Map();
+    const setModel = vi.fn(async () => options.switchResult ?? true);
+    const notify = vi.fn();
+    const custom = vi.fn(async () => options.customResult ?? null);
+    const models = options.models ?? [];
+    const byReference = new Map(models.map((item) => [`${item.provider}/${item.id}`, item]));
+    const unauthenticated = new Set(options.unauthenticated ?? []);
+    const pi = {
+        registerShortcut(key, shortcut) {
+            shortcuts.set(key, shortcut.handler);
+        },
+        registerCommand(name, command) {
+            commands.set(name, command.handler);
+        },
+        setModel,
+    };
+    const ctx = {
+        model: options.current,
+        hasUI: options.hasUI ?? true,
+        modelRegistry: {
+            find(provider, modelId) {
+                return byReference.get(`${provider}/${modelId}`);
+            },
+            async getApiKeyAndHeaders(item) {
+                const reference = `${item.provider}/${item.id}`;
+                return unauthenticated.has(reference)
+                    ? { ok: false, error: 'not authenticated' }
+                    : { ok: true, apiKey: 'test' };
+            },
+        },
+        ui: { notify, custom },
+    };
+    modelCycle(pi);
+    return { shortcuts, commands, setModel, notify, custom, ctx };
+}
+beforeEach(() => {
+    delete process.env.PI_CODING_AGENT_DIR;
+});
+afterEach(() => {
+    if (originalAgentDir === undefined)
+        delete process.env.PI_CODING_AGENT_DIR;
+    else
+        process.env.PI_CODING_AGENT_DIR = originalAgentDir;
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('model-switch extension', () => {
+    it('registers default cycle and picker shortcuts plus the picker command', () => {
+        const { shortcuts, commands } = harness();
+        expect([...shortcuts.keys()]).toEqual(['ctrl+shift+m', 'ctrl+shift+alt+m', 'ctrl+shift+l']);
+        expect([...commands.keys()]).toEqual(['model-switch']);
+    });
+    it('registers extension-owned shortcuts from keybindings.json', () => {
+        writeKeybindings({
+            'model-switch.cycleForward': 'ctrl+alt+n',
+            'model-switch.cycleBackward': 'ctrl+alt+b',
+            'model-switch.select': 'ctrl+alt+l',
+        });
+        const { shortcuts } = harness();
+        expect([...shortcuts.keys()]).toEqual(['ctrl+alt+n', 'ctrl+alt+b', 'ctrl+alt+l']);
+    });
+    it('cycles within the section containing the current model', async () => {
+        const current = model('provider', 'work-a');
+        const next = model('provider', 'work-b');
+        const personalModel = model('provider', 'personal-a');
+        writeConfig({
+            work: ['provider/work-a', 'provider/work-b'],
+            personal: ['provider/personal-a'],
+        });
+        const { shortcuts, setModel, ctx } = harness({ current, models: [current, next, personalModel] });
+        await shortcuts.get('ctrl+shift+m')(ctx);
+        expect(setModel).toHaveBeenCalledWith(next);
+        expect(setModel).not.toHaveBeenCalledWith(personalModel);
+    });
+    it('enters the first section at the boundary when current is outside all sections', async () => {
+        const outside = model('other', 'outside');
+        const first = model('provider', 'work-a');
+        const last = model('provider', 'work-b');
+        writeConfig({ work: ['provider/work-a', 'provider/work-b'] });
+        const { shortcuts, setModel, ctx } = harness({ current: outside, models: [first, last] });
+        await shortcuts.get('ctrl+shift+m')(ctx);
+        expect(setModel).toHaveBeenLastCalledWith(first);
+        await shortcuts.get('ctrl+shift+alt+m')(ctx);
+        expect(setModel).toHaveBeenLastCalledWith(last);
+    });
+    it('skips unavailable models before switching', async () => {
+        const first = model('provider', 'first');
+        const second = model('provider', 'second');
+        writeConfig({ work: ['provider/first', 'provider/second'] });
+        const { shortcuts, setModel, ctx } = harness({
+            models: [first, second],
+            unauthenticated: ['provider/first'],
+        });
+        await shortcuts.get('ctrl+shift+m')(ctx);
+        expect(setModel).toHaveBeenCalledWith(second);
+    });
+    it('warns when cycling through a section with no usable models', async () => {
+        writeConfig({ work: ['missing/model'] });
+        const { shortcuts, setModel, notify, ctx } = harness();
+        await shortcuts.get('ctrl+shift+m')(ctx);
+        expect(setModel).not.toHaveBeenCalled();
+        expect(notify).toHaveBeenCalledWith(expect.stringContaining('No usable models in section "work"'), 'warning');
+    });
+    it('warns for invalid config or empty sections', async () => {
+        const dir = tempAgentDir();
+        const configDir = join(dir, 'configs');
+        mkdirSync(configDir);
+        writeFileSync(join(configDir, 'model-switch.json'), '{ nope');
+        const invalid = harness();
+        await invalid.shortcuts.get('ctrl+shift+m')(invalid.ctx);
+        expect(invalid.setModel).not.toHaveBeenCalled();
+        expect(invalid.notify).toHaveBeenCalledWith(expect.stringContaining(join(dir, 'configs', 'model-switch.json')), 'warning');
+        writeConfig({});
+        const empty = harness();
+        await empty.shortcuts.get('ctrl+shift+m')(empty.ctx);
+        expect(empty.setModel).not.toHaveBeenCalled();
+    });
+    it('opens the fuzzy picker via command and switches the selected model', async () => {
+        const target = model('provider', 'target');
+        writeConfig({ work: ['provider/target'] });
+        const { commands, setModel, custom, ctx } = harness({
+            models: [target],
+            customResult: 'provider/target',
+        });
+        await commands.get('model-switch')('', ctx);
+        expect(custom).toHaveBeenCalledTimes(1);
+        expect(setModel).toHaveBeenCalledWith(target);
+    });
+    it('opens the fuzzy picker via the configured select shortcut', async () => {
+        const target = model('provider', 'target');
+        writeConfig({ work: ['provider/target'] });
+        const { shortcuts, custom, ctx } = harness({ models: [target], customResult: 'provider/target' });
+        await shortcuts.get('ctrl+shift+l')(ctx);
+        expect(custom).toHaveBeenCalledTimes(1);
+    });
+    it('does not switch when the picker is cancelled or UI is unavailable', async () => {
+        const target = model('provider', 'target');
+        writeConfig({ work: ['provider/target'] });
+        const cancelled = harness({ models: [target], customResult: null });
+        await cancelled.commands.get('model-switch')('', cancelled.ctx);
+        expect(cancelled.setModel).not.toHaveBeenCalled();
+        const noUi = harness({ models: [target], hasUI: false, customResult: 'provider/target' });
+        await noUi.commands.get('model-switch')('', noUi.ctx);
+        expect(noUi.custom).not.toHaveBeenCalled();
+        expect(noUi.setModel).not.toHaveBeenCalled();
+    });
+    it('warns when the picker has no usable models across all sections', async () => {
+        writeConfig({ work: ['missing/model'], personal: ['also/missing'] });
+        const { commands, setModel, notify, custom, ctx } = harness();
+        await commands.get('model-switch')('', ctx);
+        expect(custom).not.toHaveBeenCalled();
+        expect(setModel).not.toHaveBeenCalled();
+        expect(notify).toHaveBeenCalledWith(expect.stringContaining('No configured models are available'), 'warning');
+    });
+    it('warns when Pi rejects a picker selection', async () => {
+        const target = model('provider', 'target');
+        writeConfig({ work: ['provider/target'] });
+        const { commands, notify, ctx } = harness({
+            models: [target],
+            customResult: 'provider/target',
+            switchResult: false,
+        });
+        await commands.get('model-switch')('', ctx);
+        expect(notify).toHaveBeenCalledWith('Could not switch to provider/target', 'warning');
+    });
+});

package/dist/section-picker.d.ts

@@ -0,0 +1,26 @@
+import { type Component, type SelectItem } from '@earendil-works/pi-tui';
+import type { Theme } from '@earendil-works/pi-coding-agent';
+export interface PickerSection {
+    name: string;
+    items: SelectItem[];
+}
+export declare class SectionPicker implements Component {
+    private readonly sections;
+    private readonly theme;
+    private readonly done;
+    private container;
+    private tabBar;
+    private searchInput;
+    private selectList;
+    private activeSectionIndex;
+    private readonly selectTheme;
+    constructor(sections: PickerSection[], theme: Theme, done: (value: string | null) => void);
+    private renderTabBar;
+    private wireSelectList;
+    private switchSection;
+    private filteredItems;
+    private rebuildList;
+    render(width: number): string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+}

package/dist/section-picker.js

@@ -0,0 +1,104 @@
+import { Container, Input, SelectList, Text, getKeybindings, matchesKey, } from '@earendil-works/pi-tui';
+export class SectionPicker {
+    sections;
+    theme;
+    done;
+    container = new Container();
+    tabBar = new Text('', 0, 0);
+    searchInput = new Input();
+    selectList;
+    activeSectionIndex = 0;
+    selectTheme;
+    constructor(sections, theme, done) {
+        this.sections = sections;
+        this.theme = theme;
+        this.done = done;
+        this.selectTheme = {
+            selectedPrefix: (text) => theme.fg('accent', text),
+            selectedText: (text) => theme.fg('accent', text),
+            description: (text) => theme.fg('muted', text),
+            scrollInfo: (text) => theme.fg('dim', text),
+            noMatch: (text) => theme.fg('warning', text),
+        };
+        this.selectList = new SelectList(sections[0]?.items ?? [], 10, this.selectTheme);
+        this.wireSelectList();
+        this.container.addChild(this.tabBar);
+        this.container.addChild(this.searchInput);
+        this.container.addChild(this.selectList);
+        this.renderTabBar();
+    }
+    renderTabBar() {
+        const parts = this.sections.map((section, index) => {
+            const label = section.name;
+            return index === this.activeSectionIndex
+                ? this.theme.fg('accent', this.theme.bold(`[${label}]`))
+                : this.theme.fg('dim', ` ${label} `);
+        });
+        this.tabBar.setText(parts.join(''));
+    }
+    wireSelectList() {
+        this.selectList.onSelect = (item) => this.done(item.value);
+        this.selectList.onCancel = () => this.done(null);
+    }
+    switchSection(direction) {
+        this.activeSectionIndex = (this.activeSectionIndex + direction + this.sections.length) % this.sections.length;
+        this.searchInput.setValue('');
+        this.rebuildList();
+    }
+    filteredItems() {
+        const query = this.searchInput.getValue().trim().toLowerCase();
+        if (query.length === 0)
+            return this.sections[this.activeSectionIndex]?.items ?? [];
+        // SelectList.setFilter only matches value.startsWith(query), which can never
+        // match a model name inside "provider/modelId" — filter here instead, with a
+        // substring match across every section.
+        const seen = new Set();
+        const matches = [];
+        for (const section of this.sections) {
+            for (const item of section.items) {
+                if (seen.has(item.value) || !item.value.toLowerCase().includes(query))
+                    continue;
+                seen.add(item.value);
+                matches.push({ ...item, description: section.name });
+            }
+        }
+        return matches;
+    }
+    rebuildList() {
+        // Size the primary column to the content so section descriptions never
+        // truncate long provider/modelId labels (SelectList caps it at 32 otherwise).
+        this.selectList = new SelectList(this.filteredItems(), 10, this.selectTheme, {
+            minPrimaryColumnWidth: 1,
+            maxPrimaryColumnWidth: Number.MAX_SAFE_INTEGER,
+        });
+        this.wireSelectList();
+        this.container.clear();
+        this.container.addChild(this.tabBar);
+        this.container.addChild(this.searchInput);
+        this.container.addChild(this.selectList);
+        this.renderTabBar();
+    }
+    render(width) {
+        return this.container.render(width);
+    }
+    invalidate() {
+        this.container.invalidate();
+    }
+    handleInput(data) {
+        if (matchesKey(data, 'tab')) {
+            this.switchSection(1);
+            return;
+        }
+        const kb = getKeybindings();
+        if (kb.matches(data, 'tui.select.up') ||
+            kb.matches(data, 'tui.select.down') ||
+            kb.matches(data, 'tui.select.confirm') ||
+            kb.matches(data, 'tui.select.cancel')) {
+            this.selectList.handleInput(data);
+        }
+        else {
+            this.searchInput.handleInput(data);
+            this.rebuildList();
+        }
+    }
+}

package/dist/section-picker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/section-picker.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest';
+import { SectionPicker } from './section-picker.js';
+const theme = {
+    fg: (_color, text) => text,
+    bold: (text) => text,
+};
+function sections() {
+    return [
+        {
+            name: 'work',
+            items: [
+                { value: 'cloudflare-ai-gateway/gpt-5.6-sol', label: '  cloudflare-ai-gateway/gpt-5.6-sol' },
+                { value: 'cloudflare-ai-gateway/claude-opus-5', label: '  cloudflare-ai-gateway/claude-opus-5' },
+                {
+                    value: 'fireworks/accounts/fireworks/models/kimi-k3',
+                    label: '  fireworks/accounts/fireworks/models/kimi-k3',
+                },
+            ],
+        },
+        {
+            name: 'personal',
+            items: [
+                {
+                    value: 'fireworks/accounts/fireworks/models/kimi-k3',
+                    label: '  fireworks/accounts/fireworks/models/kimi-k3',
+                },
+            ],
+        },
+    ];
+}
+function render(picker) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping ANSI escape codes
+    return picker
+        .render(240)
+        .join('\n')
+        .replace(/\x1b\[[0-9;]*m/g, '');
+}
+function type(picker, text) {
+    for (const char of text)
+        picker.handleInput(char);
+}
+describe('SectionPicker filtering', () => {
+    it('matches a model name substring inside provider/modelId', () => {
+        const picker = new SectionPicker(sections(), theme, vi.fn());
+        type(picker, 'claude');
+        const output = render(picker);
+        expect(output).toContain('cloudflare-ai-gateway/claude-opus-5');
+        expect(output).not.toContain('gpt-5.6-sol');
+        expect(output).not.toContain('kimi-k3');
+    });
+    it('searches across all sections and dedupes models present in multiple sections', () => {
+        const picker = new SectionPicker(sections(), theme, vi.fn());
+        type(picker, 'kimi');
+        const output = render(picker);
+        const occurrences = output.split('kimi-k3').length - 1;
+        expect(occurrences).toBe(1);
+    });
+    it('shows only the active section when the query is empty', () => {
+        const picker = new SectionPicker(sections(), theme, vi.fn());
+        type(picker, 'claude');
+        type(picker, '\x7f'.repeat(7)); // backspace away the query
+        const output = render(picker);
+        expect(output).toContain('cloudflare-ai-gateway/claude-opus-5');
+        expect(output).toContain('cloudflare-ai-gateway/gpt-5.6-sol');
+    });
+    it('confirms the highlighted filtered match on enter', () => {
+        const done = vi.fn();
+        const picker = new SectionPicker(sections(), theme, done);
+        type(picker, 'kimi');
+        picker.handleInput('\r');
+        expect(done).toHaveBeenCalledWith('fireworks/accounts/fireworks/models/kimi-k3');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-model-switch",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Cycle or fuzzy-pick from a machine-local, sectioned list of preferred Pi models",
   "keywords": [
     "pi",

package/section-picker.ts

@@ -38,8 +38,7 @@ export class SectionPicker implements Component {
     };
 
     this.selectList = new SelectList(sections[0]?.items ?? [], 10, this.selectTheme);
-    this.selectList.onSelect = (item) => this.done(item.value);
-    this.selectList.onCancel = () => this.done(null);
+    this.wireSelectList();
 
     this.container.addChild(this.tabBar);
     this.container.addChild(this.searchInput);
@@ -57,12 +56,44 @@ export class SectionPicker implements Component {
     this.tabBar.setText(parts.join(''));
   }
 
+  private wireSelectList(): void {
+    this.selectList.onSelect = (item) => this.done(item.value);
+    this.selectList.onCancel = () => this.done(null);
+  }
+
   private switchSection(direction: 1 | -1): void {
     this.activeSectionIndex = (this.activeSectionIndex + direction + this.sections.length) % this.sections.length;
     this.searchInput.setValue('');
-    this.selectList = new SelectList(this.sections[this.activeSectionIndex]?.items ?? [], 10, this.selectTheme);
-    this.selectList.onSelect = (item) => this.done(item.value);
-    this.selectList.onCancel = () => this.done(null);
+    this.rebuildList();
+  }
+
+  private filteredItems(): SelectItem[] {
+    const query = this.searchInput.getValue().trim().toLowerCase();
+    if (query.length === 0) return this.sections[this.activeSectionIndex]?.items ?? [];
+
+    // SelectList.setFilter only matches value.startsWith(query), which can never
+    // match a model name inside "provider/modelId" — filter here instead, with a
+    // substring match across every section.
+    const seen = new Set<string>();
+    const matches: SelectItem[] = [];
+    for (const section of this.sections) {
+      for (const item of section.items) {
+        if (seen.has(item.value) || !item.value.toLowerCase().includes(query)) continue;
+        seen.add(item.value);
+        matches.push({ ...item, description: section.name });
+      }
+    }
+    return matches;
+  }
+
+  private rebuildList(): void {
+    // Size the primary column to the content so section descriptions never
+    // truncate long provider/modelId labels (SelectList caps it at 32 otherwise).
+    this.selectList = new SelectList(this.filteredItems(), 10, this.selectTheme, {
+      minPrimaryColumnWidth: 1,
+      maxPrimaryColumnWidth: Number.MAX_SAFE_INTEGER,
+    });
+    this.wireSelectList();
     this.container.clear();
     this.container.addChild(this.tabBar);
     this.container.addChild(this.searchInput);
@@ -94,7 +125,7 @@ export class SectionPicker implements Component {
       this.selectList.handleInput(data);
     } else {
       this.searchInput.handleInput(data);
-      this.selectList.setFilter(this.searchInput.getValue());
+      this.rebuildList();
     }
   }
 }