@nicknisi/pi-model-switch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Nisi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @nicknisi/pi-model-switch
+
+Cycle or fuzzy-pick from a machine-local, sectioned list of preferred Pi models.
+
+This package is useful when the same Pi configuration is shared across machines but each machine has different providers, credentials, or model preferences. The extension reads an untracked local config instead of using `enabledModels`, skips unavailable entries, and leaves Pi's normal `/model` and Ctrl+L picker unchanged.
+
+## Install
+
+From npm after the package is published:
+
+```bash
+pi install npm:@nicknisi/pi-model-switch
+```
+
+From a local checkout:
+
+```bash
+pi install ~/Developer/pi-extensions/packages/model-switch
+```
+
+## Configure shortcuts
+
+The defaults are Ctrl+Shift+M forward, Ctrl+Shift+Alt+M backward, and Ctrl+Shift+L for the fuzzy picker. Override any of them in Pi's existing `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "model-switch.cycleForward": "ctrl+shift+m",
+  "model-switch.cycleBackward": "ctrl+shift+alt+m",
+  "model-switch.select": "ctrl+shift+l"
+}
+```
+
+These extension-owned action IDs are ignored by Pi's built-in keybinding manager and read by model-switch during extension load. Run `/reload` or restart Pi after changing them. Each value must be one non-empty Pi key string; a missing or invalid value falls back to its default.
+
+## Configure models
+
+Copy the example config:
+
+```bash
+mkdir -p ~/.pi/agent/configs
+cp model-switch.example.json ~/.pi/agent/configs/model-switch.json
+```
+
+Or create `~/.pi/agent/configs/model-switch.json` directly with named sections:
+
+```json
+{
+  "sections": {
+    "work": ["cloudflare-ai-gateway/gpt-5.6-sol", "cloudflare-ai-gateway/claude-opus-5"],
+    "personal": ["fireworks/accounts/fireworks/models/kimi-k3"]
+  }
+}
+```
+
+Section names are arbitrary — define as many as you want. The legacy flat format also works:
+
+```json
+{
+  "models": ["cloudflare-ai-gateway/gpt-5.6-sol"]
+}
+```
+
+The file is read on every interaction, so edits take effect without reloading Pi.
+
+### Config schema
+
+| Field      | Type                       | Default | Description                                                                        |
+| ---------- | -------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `sections` | `Record<string, string[]>` | —       | Named sections of ordered `provider/model-id` references. Preferred over `models`. |
+| `models`   | `string[]`                 | —       | Legacy flat list. Treated as a single unnamed section when `sections` is absent.   |
+
+The first `/` separates the provider from the model ID. Additional slashes belong to the model ID, so references such as `fireworks/accounts/fireworks/models/kimi-k3` work as expected.
+
+Keep this config machine-local and untracked. A personal machine and work machine can each provide their own sections while sharing the installed extension and the rest of your Pi dotfiles.
+
+## Behavior
+
+### Cycling
+
+- **Ctrl+Shift+M** moves forward through usable models in the active section.
+- **Ctrl+Shift+Alt+M** moves backward.
+- The active section is the one containing the current model. If the current model is not in any section, the first section is used.
+- Cycling wraps at both ends within the active section.
+
+### Fuzzy picker
+
+- **Ctrl+Shift+L** or `/model-switch` opens a fuzzy-searchable TUI picker.
+- **Tab** cycles between sections within the picker.
+- Type to fuzzy-filter models within the active section.
+- The picker preserves config order, marks the current model with `●`, switches the chosen entry, and treats cancellation as a no-op.
+- Sections with no usable models are hidden from the picker.
+
+### General
+
+- Missing models and models without working provider authentication are skipped while preserving config order.
+- If no configured model is usable, Pi keeps the current model and shows a warning.
+- Invalid JSON or invalid config values produce a warning containing the config path.
+- The extension never changes the model at startup.
+
+`enabledModels` is not read or modified. Pi's `/model` command and Ctrl+L picker continue to expose the normal available catalog.
+
+## Troubleshooting
+
+### The custom shortcuts do not respond
+
+Check the `model-switch.cycleForward`, `model-switch.cycleBackward`, and `model-switch.select` values in `~/.pi/agent/keybindings.json`, then run `/reload`. Check Pi's startup diagnostics for another extension using the same physical keys, and verify that your terminal reports the configured combinations as distinct modified key events. No built-in Pi keybinding changes are required.
+
+### A configured model is skipped
+
+Check that Pi knows the exact reference and that its provider is authenticated:
+
+```bash
+pi --list-models
+```
+
+Model entries must use the full `provider/model-id` shown by Pi. Authentication is machine-specific and can be managed with `/login` and `/logout`.
+
+### No configured models are available
+
+The config may be missing, empty, malformed, or contain only missing/unauthenticated entries. Pi's warning includes the active config path. `PI_CODING_AGENT_DIR` changes that path along with the rest of the agent configuration.
+
+## Caveats
+
+- This extension owns only its custom cycle and fuzzy picker; it cannot and does not mutate Pi's read-only scoped model list.
+- The picker uses a custom search + list component with `ctx.ui.custom()`; native `/model` and Ctrl+L remain available for the full catalog.
+- Terminal support for multi-modifier keys varies; configure simpler non-conflicting keys or use a terminal with the Kitty keyboard protocol when modified keys are not distinguishable.
+- Availability is checked on each interaction, which may resolve provider credentials before switching.
+- Duplicate references within a section are preserved as written; avoid them unless repeated cycle positions are intentional.
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm vitest run packages/model-switch
+pnpm typecheck
+pnpm lint
+pnpm format:check
+pnpm build
+```
+
+Smoke-test extension loading with a scratch agent directory:
+
+```bash
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+PI_CODING_AGENT_DIR="$tmp" pi --no-extensions -e packages/model-switch/index.ts --list-models
+```

package/config.ts

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+
+export interface ModelSwitchSection {
+  name: string;
+  models: string[];
+}
+
+export interface ModelSwitchConfig {
+  sections: ModelSwitchSection[];
+}
+
+export interface ModelSwitchKeybindings {
+  forward: string;
+  backward: string;
+  select: string;
+}
+
+export const DEFAULT_MODEL_CYCLE_KEYBINDINGS: ModelSwitchKeybindings = {
+  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 type ConfigLoadResult = { ok: true; config: ModelSwitchConfig } | { ok: false; error: string };
+
+export function modelCycleConfigPath(): string {
+  return join(getAgentDir(), 'configs', 'model-switch.json');
+}
+
+export function modelCycleKeybindingsPath(): string {
+  return join(getAgentDir(), 'keybindings.json');
+}
+
+export function loadModelSwitchKeybindings(path = modelCycleKeybindingsPath()): ModelSwitchKeybindings {
+  if (!existsSync(path)) return { ...DEFAULT_MODEL_CYCLE_KEYBINDINGS };
+
+  let value: unknown;
+  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 as Record<string, unknown>;
+  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: unknown, path: string, context: string): string[] | { error: string } {
+  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()): ConfigLoadResult {
+  if (!existsSync(path)) {
+    return { ok: true, config: { sections: [] } };
+  }
+
+  let value: unknown;
+  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 as Record<string, unknown>;
+
+  // 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 as Record<string, unknown>;
+    const sections: ModelSwitchSection[] = [];
+
+    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/cycle.ts

@@ -0,0 +1,83 @@
+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 function parseModelReference(value: string): ModelReference | undefined {
+  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: readonly string[],
+  registry: ModelRegistryLike,
+): Promise<Model<Api>[]> {
+  const available: Model<Api>[] = [];
+
+  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: readonly ModelSwitchSection[],
+  current: Model<Api> | undefined,
+): ModelSwitchSection | undefined {
+  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: Model<Api> | undefined,
+  available: readonly Model<Api>[],
+  direction: CycleDirection,
+): Model<Api> | undefined {
+  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/index.ts

@@ -0,0 +1,114 @@
+import type { Api, Model } from '@earendil-works/pi-ai';
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { SelectItem } from '@earendil-works/pi-tui';
+import { loadModelSwitchConfig, loadModelSwitchKeybindings, modelCycleConfigPath } from './config.js';
+import { findActiveSection, resolveAvailableModels, selectCycleTarget, type CycleDirection } from './cycle.js';
+import { SectionPicker, type PickerSection } from './section-picker.js';
+
+async function resolveSectionModels(references: readonly string[], ctx: ExtensionContext): Promise<Model<Api>[]> {
+  return resolveAvailableModels(references, ctx.modelRegistry);
+}
+
+async function switchModel(pi: ExtensionAPI, ctx: ExtensionContext, target: Model<Api>): Promise<void> {
+  if (!(await pi.setModel(target))) {
+    ctx.ui.notify(`Could not switch to ${target.provider}/${target.id}`, 'warning');
+  }
+}
+
+async function cycleConfiguredModel(pi: ExtensionAPI, ctx: ExtensionContext, direction: CycleDirection): Promise<void> {
+  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: Model<Api>[], current: Model<Api> | undefined): SelectItem[] {
+  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: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI) return;
+
+  const loaded = loadModelSwitchConfig();
+  if (!loaded.ok) {
+    ctx.ui.notify(loaded.error, 'warning');
+    return;
+  }
+
+  const pickerSections: PickerSection[] = [];
+  const modelByReference = new Map<string, Model<Api>>();
+
+  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<string | null>((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: ExtensionAPI) {
+  const keybindings = loadModelSwitchKeybindings();
+  type ShortcutKey = Parameters<ExtensionAPI['registerShortcut']>[0];
+
+  pi.registerShortcut(keybindings.forward as ShortcutKey, {
+    description: 'Cycle configured models forward',
+    handler: async (ctx) => cycleConfiguredModel(pi, ctx, 'forward'),
+  });
+
+  pi.registerShortcut(keybindings.backward as ShortcutKey, {
+    description: 'Cycle configured models backward',
+    handler: async (ctx) => cycleConfiguredModel(pi, ctx, 'backward'),
+  });
+
+  pi.registerShortcut(keybindings.select as ShortcutKey, {
+    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/model-switch.example.json

@@ -0,0 +1,11 @@
+{
+  "sections": {
+    "work": [
+      "cloudflare-ai-gateway/gpt-5.6-sol",
+      "cloudflare-ai-gateway/claude-opus-5",
+      "cloudflare-ai-gateway/grok-4.5",
+      "fireworks/accounts/fireworks/models/kimi-k3"
+    ],
+    "personal": ["fireworks/accounts/fireworks/models/kimi-k3"]
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nicknisi/pi-model-switch",
+  "version": "0.1.0",
+  "description": "Cycle or fuzzy-pick from a machine-local, sectioned list of preferred Pi models",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/nicknisi/pi-extensions/tree/main/packages/model-switch#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicknisi/pi-extensions.git",
+    "directory": "packages/model-switch"
+  },
+  "files": [
+    "dist",
+    "index.ts",
+    "config.ts",
+    "cycle.ts",
+    "section-picker.ts",
+    "README.md",
+    "model-switch.example.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/section-picker.ts

@@ -0,0 +1,100 @@
+import {
+  Container,
+  Input,
+  SelectList,
+  Text,
+  getKeybindings,
+  matchesKey,
+  type Component,
+  type SelectItem,
+  type SelectListTheme,
+} from '@earendil-works/pi-tui';
+import type { Theme } from '@earendil-works/pi-coding-agent';
+
+export interface PickerSection {
+  name: string;
+  items: SelectItem[];
+}
+
+export class SectionPicker implements Component {
+  private container = new Container();
+  private tabBar = new Text('', 0, 0);
+  private searchInput = new Input();
+  private selectList: SelectList;
+  private activeSectionIndex = 0;
+  private readonly selectTheme: SelectListTheme;
+
+  constructor(
+    private readonly sections: PickerSection[],
+    private readonly theme: Theme,
+    private readonly done: (value: string | null) => void,
+  ) {
+    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.selectList.onSelect = (item) => this.done(item.value);
+    this.selectList.onCancel = () => this.done(null);
+
+    this.container.addChild(this.tabBar);
+    this.container.addChild(this.searchInput);
+    this.container.addChild(this.selectList);
+    this.renderTabBar();
+  }
+
+  private renderTabBar(): void {
+    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(''));
+  }
+
+  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.container.clear();
+    this.container.addChild(this.tabBar);
+    this.container.addChild(this.searchInput);
+    this.container.addChild(this.selectList);
+    this.renderTabBar();
+  }
+
+  render(width: number): string[] {
+    return this.container.render(width);
+  }
+
+  invalidate(): void {
+    this.container.invalidate();
+  }
+
+  handleInput(data: string): void {
+    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.selectList.setFilter(this.searchInput.getValue());
+    }
+  }
+}