@mevsgame/pi-model-alias-profiles 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: deterministic `tier/large`, `tier/medium`, and `tier/small`
+  aliases backed by explicitly switchable profiles.
+- Manage profiles in Pi's terminal UI, with branch-local selection and
+  persistent profile definitions.
+- Preserve physical model choice for continuations and retries; no classifier
+  or automatic fallback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mevsgame
+
+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

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# Pi Model Alias
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stable native Pi virtual models: `tier/large`, `tier/medium`, and `tier/small`.
+Each resolves to exactly one configured physical model in the active profile.
+No classifier, fallback, proxy, provider replacement, or core modifications.
+Unlike classifier-based routers, the alias always uses the mapping you choose;
+switch profiles explicitly to change those mappings. Other Pi model-alias
+packages exist; this extension additionally provides switchable profiles.
+
+## Installation
+
+Requires a Pi version supporting virtual models (tested with Pi 1.5.0).
+Configure and authenticate each physical model's provider in Pi before
+activating a profile. An alias does not supply provider credentials.
+
+```sh
+pi install npm:@mevsgame/pi-model-alias-profiles
+```
+
+## First use
+
+Run `/model-profiles`, choose **Create**, enter a name, and select a physical
+model for each alias. The model picker searches readable names and exact
+provider/model IDs, supports multiple search terms and pagination, and marks
+authentication availability. Models from different providers can share a profile.
+Choose **Save**, then **Activate**. No example model IDs are installed.
+
+```text
+/model-profile work
+/tier large
+/model tier/medium
+/model-profile personal
+```
+
+Switching profiles never changes the selected alias. Requests beginning a new
+user turn use the new mapping. Tool continuations keep their previous physical
+model; retries retain the failed physical model. Thinking selection is preserved
+and Pi clamps it to the physical model's capabilities.
+
+### Commands and keys
+
+| Command | Action |
+|---|---|
+| `/model-profile` | Quick picker, active profile marked |
+| `/model-profile NAME` | Activate immediately |
+| `/model-profile next` | Cycle sorted profile names, wrap and skip invalid profiles |
+| `/model-profile status` | Active profile and mappings |
+| `/model-profiles` | Create, edit, duplicate, rename, delete, set default, explicit disk reload |
+| `/tier [large\|medium\|small]` | Select alias, or open alias picker |
+
+`Ctrl+Alt+P` opens the quick picker; `Ctrl+Alt+Shift+P` cycles profiles.
+Dialogs support up/down, Enter to select, and Escape to cancel and restore the
+editor. These bindings do not replace Pi's built-in model-selection shortcuts.
+Modifier reporting varies by terminal: use `/hotkeys` to inspect conflicts, and
+use the commands if your terminal cannot distinguish these combinations. No
+global keybindings are modified.
+
+Management uses nested native dialogs rather than a bespoke full-screen editor.
+Edits remain private until Save. Cancelling creation/editing does not write.
+Incomplete drafts may be saved but cannot activate. Active profiles must remain
+valid when edited, and deleting the active profile requires a valid replacement
+and confirmation. Profile names are case-sensitive, 1–64 ASCII letters/digits/
+`._-`, starting with a letter/digit; `next`, `status`, and prototype names are
+reserved.
+
+Direct physical-model selection is unaffected; the profile status indicator is
+hidden in that case. Named activation, cycling, status, and named `/tier`
+selection work without a terminal. Management and profile pickers require TUI.
+
+## Persistence and safety
+
+Configuration lives at `<agent-dir>/model-profiles.json`, resolved with Pi's
+`getAgentDir()` (including `PI_CODING_AGENT_DIR`). Format:
+
+```json
+{
+  "version": 1,
+  "defaultProfile": "work",
+  "lastActiveProfile": "work",
+  "profiles": {
+    "work": {
+      "large": "provider/exact-large-model-id",
+      "medium": "provider/exact-medium-model-id",
+      "small": "another-provider/exact-small-model-id"
+    }
+  }
+}
+```
+
+These are illustrative placeholders, **not valid installed mappings**. Use the
+in-Pi registry picker to choose actual configured models. No credentials are
+stored here. Availability checks detect configured authentication, not whether a
+remote server will accept an expired/revoked credential; provider errors remain
+visible and never trigger fallback.
+
+Global definitions and last-used selection are separate from branch-local
+`model-profiles.selection` custom session entries (not sent to the LLM).
+New sessions choose the valid last-used profile, then valid default; existing
+branches restore their own selection, including an explicit no-profile state.
+A missing/renamed saved profile is reported, not silently substituted: select a
+replacement explicitly. Definitions remain global; editing them affects future
+requests in sessions that load those definitions.
+
+Writes use exclusive locks, content-based conflict detection, and atomic rename.
+Failed writes do not update runtime selection. Malformed/unsupported config is
+preserved and blocks writes/routing. Repair the file, then use management's
+**Reload configuration from disk**. The same explicit reload accepts external
+changes after a conflict; there is no automatic cross-process synchronization.
+Other processes do not change this process's active profile. After a process
+crash, a stale `.lock` may require removal after confirming no writer is active.
+Local atomic-rename/lock semantics are assumed; network filesystems may differ.
+
+## Known limitations and troubleshooting
+
+- Another extension registering `tier/large`, `tier/medium`, or `tier/small`
+  can replace these virtual models. The `/model-profile`, `/model-profiles`,
+  `/tier` commands and shortcuts may also conflict with other extensions.
+- If activation fails, check all three mappings exist in Pi's model registry and
+  their providers are authenticated. Provider errors do not trigger fallback.
+- If shortcuts do not work, inspect `/hotkeys` and use the slash commands; some
+  terminals cannot distinguish the required modifiers.
+- Profile management requires Pi's interactive terminal UI. End-to-end paid
+  inference and some interactive scenarios remain unverified; see
+  [VERIFICATION.md](VERIFICATION.md).
+
+## Development and verification
+
+```sh
+npm ci
+npm test
+npm run typecheck
+```
+
+Tests cover configuration validation/conflicts/malformed data, atomic CRUD
+cancellation, routing and authentication errors, sticky continuations/retries,
+branch restoration, commands, shortcuts, and stable selection identity.
+Installed Pi-Bolt smoke checks confirm extension loading, `--model tier/medium`,
+and all three aliases in `--list-models tier` without sending model requests.
+See `VERIFICATION.md` for exact results and remaining manual checks.
+
+## License and links
+
+MIT. [Source and issues](https://github.com/mevsgame/pi-model-alias-profiles).

package/VERIFICATION.md

@@ -0,0 +1,56 @@
+# Verification
+
+Host: Pi 1.5.0, Pi-Bolt 1.1.3, Linux x64.
+Development types: `@earendil-works/pi-coding-agent` and `pi-tui` 1.5.0.
+
+- `npm test`: **23 passed**, 0 failed.
+- `npm run typecheck`: passed.
+- `npm pack --dry-run`: passed; extension entry point and all source modules included.
+- Isolated temporary agent directory, explicit extension load:
+  `pi-bolt -ne --no-mcp -ns -np -nc --offline -e ./index.ts --model tier/medium --no-session -p '/model-profile status'`
+  selected the virtual model and printed unconfigured mappings without inference.
+- `--list-models tier` listed large, medium, small.
+
+Real interactive smoke used Python PTY/subprocess, temporary HOME and agent
+directory, no credential environment, and a watchdog:
+
+```sh
+pi-bolt -ne --no-mcp -ns -np -nc --offline \
+  -e /absolute/path/to/index.ts --model tier/large
+```
+
+Confirmed:
+
+- Extension starts, selects tier/large, shows first-run guidance.
+- Ctrl+Alt+P encoded as `ESC[112;7u` invokes quick picker behavior and reports no
+  profiles; the next command works, confirming editor focus.
+- `/model-profiles` → Create opens name input. Escape cancels creation, then
+  Escape closes management. No configuration file is written.
+- Native `/model` lists all three tier models and marks large selected.
+  Filtering and Escape work.
+- Child was terminated and reaped; no process remained.
+
+The host printed catalog-refresh messages even with offline flags; absence of
+network traffic was not independently traced.
+
+## Remaining manual checks
+
+Automated tests exercise profile CRUD, activation, cycling, wraparound,
+branch persistence, errors and routing through mocks. Actual paid inference,
+authenticated Codex/Anthropic switching, live tool/retry sequences, real session
+resume/tree navigation, and a populated quick picker/cycling shortcut were not
+tested end-to-end. Other terminals' modifier encoding and user-defined shortcut
+conflicts remain environment-dependent.
+
+For final acceptance in your terminal:
+
+1. Create two authenticated profiles with all three mappings using management.
+2. Select tier/large through `/model`, switch with Ctrl+Alt+P, and send a prompt.
+   Verify the native footer dispatch changes but the selected alias does not.
+3. Repeat with medium/small and Ctrl+Alt+Shift+P; verify sorted wraparound.
+4. Switch during a tool sequence: continuations must keep the previous physical
+   model; the next user request must use the new profile.
+5. Save edits, duplicate/rename/delete, and cancel an edit.
+6. Restart, resume, and navigate session branches with different saved profiles.
+7. Remove credentials or invalidate a target and verify an explicit error with
+   no fallback. Restore valid configuration afterward.

package/index.ts

@@ -0,0 +1,142 @@
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { ALIASES, ConfigStore, type Config, type Alias } from "./src/config.ts";
+import { route, validateProfile } from "./src/profiles.ts";
+import { branchProfile, STATE_ENTRY } from "./src/state.ts";
+import { manage, quickPicker, type Controller } from "./src/ui.ts";
+
+export default function modelProfiles(pi: ExtensionAPI) {
+  const store = new ConfigStore(join(getAgentDir(), "model-profiles.json"));
+  let config: Config = { version: 1, profiles: {} };
+  let active: string | undefined;
+  let loadError: unknown;
+  try { config = store.load(); } catch (error) { loadError = error; }
+  const report = (ctx: ExtensionContext, message: string, error = false) => {
+    if (ctx.hasUI) ctx.ui.notify(message, error ? "error" : "info");
+    else console.error(`[model-profiles] ${message}`);
+  };
+  const status = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    const alias = ctx.model?.provider === "tier" ? ctx.model.id as Alias : undefined;
+    ctx.ui.setStatus("model-profiles", alias
+      ? `${active ?? "no profile"} · ${alias} → ${active && config.profiles[active]?.[alias] || "(unconfigured)"}`
+      : undefined);
+  };
+  const record = () => pi.appendEntry(STATE_ENTRY, { profile: active ?? null });
+  const controller: Controller = {
+    getConfig: () => config,
+    getActive: () => active,
+    activate(name, ctx) {
+      validateProfile(name, config, ctx.modelRegistry);
+      const next = { ...config, lastActiveProfile: name };
+      store.save(next);
+      config = next;
+      active = name;
+      record();
+      status(ctx);
+      const alias = ctx.model?.provider === "tier" ? ctx.model.id as Alias : undefined;
+      report(ctx, `Profile: ${name}${alias ? `\ntier/${alias} → ${config.profiles[name]![alias]}` : ""}`);
+    },
+    commit(next, selection, ctx) {
+      if (selection) validateProfile(selection, next, ctx.modelRegistry);
+      if (selection) next.lastActiveProfile = selection;
+      store.save(next);
+      const changed = active !== selection;
+      config = next;
+      active = selection;
+      if (changed) record();
+      status(ctx);
+    },
+    reload(ctx) {
+      config = store.load();
+      loadError = undefined;
+      status(ctx);
+    },
+  };
+  const restore = (ctx: ExtensionContext) => {
+    const saved = branchProfile(ctx.sessionManager.getBranch());
+    if (saved !== undefined) {
+      active = saved ?? undefined; // Never silently replace a missing session profile.
+      try { if (saved) validateProfile(saved, config, ctx.modelRegistry); }
+      catch (error) { report(ctx, String(error), true); }
+    } else {
+      active = undefined;
+      for (const name of [config.lastActiveProfile, config.defaultProfile]) {
+        if (!name) continue;
+        try { validateProfile(name, config, ctx.modelRegistry); active = name; break; } catch {}
+      }
+      record(); // Pin the initial selection to this branch, independent of future global changes.
+    }
+    status(ctx);
+  };
+  pi.on("session_start", (_event, ctx) => {
+    restore(ctx);
+    if (loadError) report(ctx, String(loadError), true);
+    else if (!Object.keys(config.profiles).length) report(ctx, "No model profiles configured. Run /model-profiles to create your first profile.");
+  });
+  pi.on("session_tree", (_event, ctx) => restore(ctx));
+  pi.on("model_select", (_event, ctx) => status(ctx));
+  for (const alias of ALIASES) pi.registerVirtualModel({
+    provider: "tier", id: alias, name: `Tier ${alias}`,
+    thinkingLevels: ["off", "minimal", "low", "medium", "high", "xhigh"],
+    route(request, ctx) {
+      if (loadError) throw loadError;
+      return route(alias, active, config, ctx.modelRegistry, request);
+    },
+  });
+  const guarded = (fn: (args: string, ctx: ExtensionContext) => Promise<void> | void) =>
+    async (args: string, ctx: ExtensionContext) => {
+      try { await fn(args.trim(), ctx); } catch (error) { report(ctx, String(error), true); }
+    };
+  const cycle = (ctx: ExtensionContext) => {
+    const names = Object.keys(config.profiles).sort();
+    const start = names.indexOf(active ?? "");
+    for (let offset = 1; offset <= names.length; offset++) {
+      const name = names[(start + offset) % names.length]!;
+      try { validateProfile(name, config, ctx.modelRegistry); } catch { continue; }
+      controller.activate(name, ctx);
+      return;
+    }
+    throw new Error("No valid profiles to cycle to. Configure mappings and credentials using /model-profiles.");
+  };
+  pi.registerCommand("model-profile", {
+    description: "Pick, activate, cycle or inspect model profiles",
+    getArgumentCompletions: prefix => [...Object.keys(config.profiles).sort(), "next", "status"]
+      .filter(name => name.startsWith(prefix)).map(name => ({ value: name, label: name })),
+    handler: guarded(async (args, ctx) => {
+      if (!args) return quickPicker(ctx, controller);
+      if (args === "next") return cycle(ctx);
+      if (args === "status") {
+        report(ctx, `Profile: ${active ?? "(none)"}\n${ALIASES.map(alias => `tier/${alias} → ${active && config.profiles[active]?.[alias] || "(missing)"}`).join("\n")}`);
+        return;
+      }
+      controller.activate(args, ctx);
+    }),
+  });
+  pi.registerCommand("model-profiles", {
+    description: "Create, edit, duplicate, rename and delete model profiles",
+    handler: guarded((_args, ctx) => manage(ctx, controller)),
+  });
+  pi.registerCommand("tier", {
+    description: "Select a stable model alias",
+    handler: guarded(async (args, ctx) => {
+      if (!args) {
+        if (!ctx.hasUI) throw new Error("Use /tier large, medium or small in non-interactive modes.");
+        args = await ctx.ui.select("Select model alias", [...ALIASES]) ?? "";
+        if (!args) return;
+      }
+      if (!(ALIASES as readonly string[]).includes(args)) throw new Error(`Unknown alias "${args}". Choose large, medium or small.`);
+      const model = ctx.modelRegistry.find("tier", args);
+      if (!model || !await pi.setModel(model)) throw new Error(`Could not select tier/${args}.`);
+      status(ctx);
+    }),
+  });
+  pi.registerShortcut("ctrl+alt+p", {
+    description: "Switch model profile",
+    handler: ctx => quickPicker(ctx, controller),
+  });
+  pi.registerShortcut("ctrl+alt+shift+p", {
+    description: "Cycle model profile",
+    handler: ctx => guarded((_args, ctx) => cycle(ctx))("", ctx),
+  });
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@mevsgame/pi-model-alias-profiles",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Deterministic Pi model aliases with switchable, persistent profiles",
+  "license": "MIT",
+  "private": false,
+  "keywords": ["pi-package", "pi-extension", "model-alias", "model-profiles", "pi"],
+  "repository": { "type": "git", "url": "https://github.com/mevsgame/pi-model-alias-profiles.git" },
+  "homepage": "https://github.com/mevsgame/pi-model-alias-profiles#readme",
+  "bugs": { "url": "https://github.com/mevsgame/pi-model-alias-profiles/issues" },
+  "publishConfig": { "access": "public" },
+  "pi": { "extensions": ["./index.ts"] },
+  "files": ["index.ts", "src", "README.md", "LICENSE", "CHANGELOG.md", "VERIFICATION.md"],
+  "scripts": { "test": "tsx --test tests/*.test.ts", "typecheck": "tsc --noEmit" },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,122 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const ALIASES = ["large", "medium", "small"] as const;
+export type Alias = (typeof ALIASES)[number];
+export type Profile = Partial<Record<Alias, string>>;
+export interface Config {
+  version: 1;
+  defaultProfile?: string;
+  lastActiveProfile?: string;
+  profiles: Record<string, Profile>;
+}
+
+const reserved = new Set(["next", "status", ...Object.getOwnPropertyNames(Object.prototype)].map((name) => name.toLowerCase()));
+
+export function validateName(name: string): void {
+  if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name) || reserved.has(name.toLowerCase())) {
+    throw new Error(`Invalid or reserved profile name: ${JSON.stringify(name)}. Use 1–64 letters, digits, dots, underscores or hyphens, starting with a letter or digit.`);
+  }
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Validate without consulting the model registry: incomplete drafts are permitted. */
+function validateConfig(value: unknown): asserts value is Config {
+  if (!object(value) || value.version !== 1 || !object(value.profiles)) {
+    throw new Error("Invalid model profiles configuration: expected version 1 and a profiles object.");
+  }
+  for (const key of Object.keys(value)) {
+    if (!["version", "profiles", "defaultProfile", "lastActiveProfile"].includes(key)) {
+      throw new Error(`Unknown configuration field: ${key}`);
+    }
+  }
+  for (const key of ["defaultProfile", "lastActiveProfile"]) {
+    if (value[key] !== undefined) validateName(value[key] as string);
+  }
+  for (const [name, profile] of Object.entries(value.profiles)) {
+    validateName(name);
+    if (!object(profile)) throw new Error(`Invalid profile "${name}": expected an object.`);
+    for (const [alias, target] of Object.entries(profile)) {
+      if (!(ALIASES as readonly string[]).includes(alias) || typeof target !== "string" || !/^[^/\s]+\/\S+$/.test(target)) {
+        throw new Error(`Invalid mapping "${name}.${alias}": expected a physical provider/modelId.`);
+      }
+      if (target.startsWith("tier/")) throw new Error(`Invalid mapping "${name}.${alias}": virtual tier models cannot be targets.`);
+    }
+  }
+}
+
+function readContent(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/** One store per process. Call load again to explicitly accept an external change. */
+export class ConfigStore {
+  private baseline: string | undefined;
+  private loaded = false;
+  private blocked = false;
+
+  constructor(readonly path: string) {}
+
+  load(): Config {
+    try {
+      const content = readContent(this.path);
+      const config: unknown = content === undefined ? { version: 1, profiles: {} } : JSON.parse(content);
+      validateConfig(config);
+      this.baseline = content;
+      this.loaded = true;
+      this.blocked = false;
+      return config;
+    } catch (error) {
+      this.blocked = true;
+      throw new Error(`Cannot load ${this.path}; existing data was preserved: ${(error as Error).message}`, { cause: error });
+    }
+  }
+
+  save(config: Config): void {
+    if (this.blocked) throw new Error(`Cannot save ${this.path}: configuration load failed. Repair the file and load it again first.`);
+    if (!this.loaded) this.load();
+    validateConfig(config);
+    const content = `${JSON.stringify(config, null, 2)}\n`;
+    mkdirSync(dirname(this.path), { recursive: true });
+    const lockPath = `${this.path}.lock`;
+    let lock: number;
+    try {
+      lock = openSync(lockPath, "wx", 0o600);
+    } catch (error) {
+      throw new Error(`Cannot lock ${this.path}; another writer may be active. Retry after it finishes (inspect ${lockPath} if stale).`, { cause: error });
+    }
+    const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+    let tempCreated = false;
+    try {
+      if (readContent(this.path) !== this.baseline) {
+        throw new Error(`Configuration conflict: ${this.path} changed externally. Reload before saving.`);
+      }
+      const fd = openSync(temporary, "wx", 0o600);
+      tempCreated = true;
+      try {
+        writeFileSync(fd, content, "utf8");
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+      renameSync(temporary, this.path);
+      tempCreated = false;
+      this.baseline = content;
+    } finally {
+      try {
+        if (tempCreated) unlinkSync(temporary);
+      } finally {
+        try { closeSync(lock); } finally { unlinkSync(lockPath); }
+      }
+    }
+  }
+}

package/src/profiles.ts

@@ -0,0 +1,29 @@
+import type { ExtensionContext, ModelRouteRequest, ModelRoute } from "@earendil-works/pi-coding-agent";
+import { ALIASES, type Alias, type Config } from "./config.ts";
+
+export type Registry = Pick<ExtensionContext["modelRegistry"], "find" | "hasConfiguredAuth">;
+
+export function resolveTarget(name: string | undefined, alias: Alias, config: Config, registry: Registry) {
+  const target = name && config.profiles[name]?.[alias];
+  const prefix = `Profile "${name ?? "(none)"}", tier/${alias} → ${target || "(missing mapping)"}`;
+  if (!target) throw new Error(`${prefix}: configure this alias using /model-profiles.`);
+  const slash = target.indexOf("/");
+  const model = registry.find(target.slice(0, slash), target.slice(slash + 1));
+  if (!model) throw new Error(`${prefix}: physical model is no longer in Pi's catalog. Edit the mapping.`);
+  if (model.api === "pi-virtual") throw new Error(`${prefix}: virtual-to-virtual routing is unsupported.`);
+  if (!registry.hasConfiguredAuth(model)) throw new Error(`${prefix}: provider has no configured credentials. Use /login or configure provider authentication.`);
+  return model;
+}
+
+export function validateProfile(name: string, config: Config, registry: Registry): void {
+  if (!Object.hasOwn(config.profiles, name)) throw new Error(`Unknown profile "${name}". Use /model-profiles.`);
+  for (const alias of ALIASES) resolveTarget(name, alias, config, registry);
+}
+
+export function route(alias: Alias, name: string | undefined, config: Config, registry: Registry, request: ModelRouteRequest): ModelRoute {
+  const sticky = request.reason === "retry" ? request.failed ?? request.previous : request.previous;
+  if ((request.reason === "retry" || request.reason === "continuation") && sticky) {
+    return { model: sticky.model, thinkingLevel: sticky.thinkingLevel ?? request.thinkingLevel };
+  }
+  return { model: resolveTarget(name, alias, config, registry), thinkingLevel: request.thinkingLevel };
+}

package/src/state.ts

@@ -0,0 +1,12 @@
+export const STATE_ENTRY = "model-profiles.selection";
+export function branchProfile(entries: readonly { type: string; customType?: string; data?: unknown }[]): string | null | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i]!;
+    if (entry.type === "custom" && entry.customType === STATE_ENTRY) {
+      const data = entry.data as { profile?: unknown } | undefined;
+      if (typeof data?.profile === "string") return data.profile;
+      if (data?.profile === null) return null;
+    }
+  }
+  return undefined;
+}

package/src/ui.ts

@@ -0,0 +1,179 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ALIASES, type Config, type Profile, validateName } from "./config.ts";
+import { validateProfile } from "./profiles.ts";
+
+export interface Controller {
+  getConfig(): Config;
+  getActive(): string | undefined;
+  activate(name: string, ctx: ExtensionContext): void;
+  commit(config: Config, active: string | undefined, ctx: ExtensionContext): void;
+  reload(ctx: ExtensionContext): void;
+}
+
+function error(ctx: ExtensionContext, cause: unknown): void {
+  ctx.ui.notify(cause instanceof Error ? cause.message : String(cause), "error");
+}
+
+function interactive(ctx: ExtensionContext): boolean {
+  if (ctx.mode === "tui") return true;
+  throw new Error("Profile dialogs require an interactive TUI. Use /model-profile <name> instead.");
+}
+
+function names(config: Config): string[] {
+  return Object.keys(config.profiles).sort();
+}
+
+function valid(name: string, config: Config, ctx: ExtensionContext): boolean {
+  try { validateProfile(name, config, ctx.modelRegistry); return true; }
+  catch { return false; }
+}
+
+async function chooseProfile(ctx: ExtensionContext, config: Config, active: string | undefined, title: string, candidates = names(config)): Promise<string | undefined> {
+  const labels = candidates.map(name => `${name === active ? "●" : "○"} ${name}${valid(name, config, ctx) ? "" : " [incomplete/unavailable]"}`);
+  const picked = await ctx.ui.select(title, labels);
+  return picked === undefined ? undefined : candidates[labels.indexOf(picked)];
+}
+
+export async function quickPicker(ctx: ExtensionContext, controller: Controller): Promise<void> {
+  if (!interactive(ctx)) return;
+  try {
+    const config = controller.getConfig();
+    if (!names(config).length) {
+      ctx.ui.notify("No profiles yet. Use /model-profiles to create one.", "info");
+      return;
+    }
+    const name = await chooseProfile(ctx, config, controller.getActive(), "Switch model profile");
+    if (name !== undefined) {
+      validateProfile(name, config, ctx.modelRegistry);
+      controller.activate(name, ctx);
+    }
+  } catch (cause) { error(ctx, cause); }
+}
+
+async function newName(ctx: ExtensionContext, config: Config): Promise<string | undefined> {
+  for (;;) {
+    const name = await ctx.ui.input("Profile name (1–64 letters, digits, . _ -)");
+    if (name === undefined) return undefined;
+    try {
+      validateName(name);
+      if (Object.hasOwn(config.profiles, name)) throw new Error(`Profile "${name}" already exists.`);
+      return name;
+    } catch (cause) { error(ctx, cause); }
+  }
+}
+
+/** Built-in input + paged selection keeps even very large registries usable without a custom TUI. */
+async function modelPicker(ctx: ExtensionContext): Promise<string | undefined> {
+  const models = ctx.modelRegistry.getAll()
+    .filter(model => model.api !== "pi-virtual" && model.provider !== "tier")
+    .sort((a, b) => `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`));
+  const available = new Set(ctx.modelRegistry.getAvailable().map(model => `${model.provider}/${model.id}`));
+  for (;;) {
+    const query = await ctx.ui.input("Search physical models by provider, name or ID (blank = all)");
+    if (query === undefined) return undefined;
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const matches = models.filter(model => terms.every(term => `${model.provider}/${model.id} ${model.name}`.toLowerCase().includes(term)));
+    if (!matches.length) { ctx.ui.notify("No matching physical models. Try another search.", "info"); continue; }
+    let page = 0;
+    for (;;) {
+      const items = matches.slice(page * 15, (page + 1) * 15);
+      const labels = items.map(model => `${model.name} — ${model.provider}/${model.id} [${available.has(`${model.provider}/${model.id}`) ? "available/authenticated" : "unavailable/no credentials"}]`);
+      const options = [...labels, "Search again", ...(page > 0 ? ["Previous page"] : []), ...((page + 1) * 15 < matches.length ? ["Next page"] : [])];
+      const choice = await ctx.ui.select(`Physical models (${matches.length} matches, page ${page + 1})`, options);
+      if (choice === undefined) return undefined;
+      if (choice === "Search again") break;
+      if (choice === "Next page") { page++; continue; }
+      if (choice === "Previous page") { page--; continue; }
+      const model = items[labels.indexOf(choice)];
+      if (model) return `${model.provider}/${model.id}`;
+    }
+  }
+}
+
+async function edit(ctx: ExtensionContext, name: string, source: Profile): Promise<Profile | undefined> {
+  const draft = { ...source };
+  for (;;) {
+    const mappings = ALIASES.map(alias => `${alias} → ${draft[alias] ?? "(not set)"}`);
+    const choice = await ctx.ui.select(`Edit ${name} (unsaved)`, [...mappings, "Save", "Cancel"]);
+    if (choice === undefined || choice === "Cancel") return undefined;
+    if (choice === "Save") return draft;
+    const alias = ALIASES[mappings.indexOf(choice)];
+    if (alias) {
+      const target = await modelPicker(ctx);
+      if (target !== undefined) draft[alias] = target;
+    }
+  }
+}
+
+export async function manage(ctx: ExtensionContext, controller: Controller): Promise<void> {
+  if (!interactive(ctx)) return;
+  for (;;) {
+    try {
+      const config = structuredClone(controller.getConfig());
+      let active = controller.getActive();
+      const action = await ctx.ui.select(`Model profiles — Active: ${active ?? "(none)"}`, [
+        "Activate", "Create", "Edit", "Duplicate", "Rename", "Delete", "Set default", "Reload configuration from disk", "Close",
+      ]);
+      if (action === undefined || action === "Close") return;
+      if (action === "Reload configuration from disk") {
+        if (await ctx.ui.confirm("Reload configuration?", "Accept external file changes. This discards the current in-memory configuration.")) controller.reload(ctx);
+        continue;
+      }
+      if (action === "Create") {
+        const name = await newName(ctx, config);
+        if (name === undefined) continue;
+        const draft = await edit(ctx, name, {});
+        if (draft === undefined) continue;
+        config.profiles[name] = draft;
+      } else {
+        if (!names(config).length) { ctx.ui.notify("Create a profile first.", "info"); continue; }
+        const name = await chooseProfile(ctx, config, active, `${action} profile`);
+        if (name === undefined) continue;
+        if (action === "Activate") {
+          validateProfile(name, config, ctx.modelRegistry);
+          controller.activate(name, ctx);
+          continue;
+        }
+        if (action === "Edit") {
+          const draft = await edit(ctx, name, config.profiles[name]!);
+          if (draft === undefined) continue;
+          config.profiles[name] = draft;
+          if (active === name) validateProfile(name, config, ctx.modelRegistry);
+        } else if (action === "Duplicate" || action === "Rename") {
+          const next = await newName(ctx, config);
+          if (next === undefined) continue;
+          config.profiles[next] = { ...config.profiles[name] };
+          if (action === "Rename") {
+            delete config.profiles[name];
+            if (active === name) active = next;
+            if (config.defaultProfile === name) config.defaultProfile = next;
+            if (config.lastActiveProfile === name) config.lastActiveProfile = next;
+          }
+        } else if (action === "Delete") {
+          if (active === name) {
+            const candidates = names(config).filter(other => other !== name && valid(other, config, ctx));
+            if (!candidates.length) throw new Error("Cannot delete the active profile: create another valid profile first.");
+            const replacement = await chooseProfile(ctx, config, active, "Choose replacement active profile", candidates);
+            if (replacement === undefined) continue;
+            active = replacement;
+          }
+          if (!await ctx.ui.confirm(`Delete "${name}"?`, "This permanently removes the profile and its mappings.")) continue;
+          delete config.profiles[name];
+          if (config.defaultProfile === name) {
+            if (active) config.defaultProfile = active;
+            else delete config.defaultProfile;
+          }
+          if (config.lastActiveProfile === name) {
+            if (active) config.lastActiveProfile = active;
+            else delete config.lastActiveProfile;
+          }
+        } else if (action === "Set default") {
+          validateProfile(name, config, ctx.modelRegistry);
+          config.defaultProfile = name;
+        }
+      }
+      controller.commit(config, active, ctx);
+      ctx.ui.notify("Profile configuration saved.", "info");
+    } catch (cause) { error(ctx, cause); }
+  }
+}