pi-better-model-select 0.1.4 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.3.0
+
+### Added
+
+- `/bms-options` for direct access to result placement, write mode, and provider visibility.
+- Above-prompt result placement, with the best match nearest search. Below-prompt placement remains the default.
+- Ctrl+O Actions menu with access to model management, defaults, options, and usage reset.
+- Visible **Save configuration** and **Back** actions in forms, alongside Ctrl+S and Esc.
+
+### Changed
+
+- Replaced the model list with aligned MODEL, PROVIDER, CONTEXT, USES, and STATUS columns, a full-row selection highlight, and up to six visible results.
+- Moved search into a prompt-style field in Pi's editor area. Shortcut hints and the result count follow result placement.
+- Replaced model-edit questionnaires with draft forms. Changes are saved explicitly; leaving a modified form asks whether to discard them.
+- Organized Pi and subagent defaults into a table with model, effort, and source information.
+- Preserved search and selection across submenus. Returning from an Actions submenu restores the selected action.
+- Kept non-search menus top-to-bottom regardless of result placement.
+- Styled shortcut keys separately from action descriptions and omitted whole hints at narrow widths.
+- Made destructive confirmations cancel-first and explicit about write scope.
+
+### Fixed
+
+- Restored the same form draft and selection after closing a child dialog, without losing it when Pi restores its editor.
+
+## 0.2.0
+
+### Added
+
+- Default model and thinking effort configuration for Pi, the subagent fallback, and individual agent roles.
+- `/bms-defaults`, Ctrl+D for the Pi default, and Ctrl+G for the defaults menu.
+- User/project scope selection, effective-value sources, and warnings about higher-priority overrides.
+- Provider-reported effort capability hints, editable supported levels, and per-model preferred effort.
+- Active-model and saved-default markers in the picker.
+
+### Fixed
+
+- Discovery of pi-subagents roles with the newer bundled entry-point layout, checked against pi-subagents 0.82.1 after the original 0.79.0 integration.
+
+## 0.1.4
+
+- Added BMS options and provider filters.
+
+## 0.1.3
+
+- Renamed the package to `pi-better-model-select`.
+
+## 0.1.2
+
+- Persisted deletion of inherited models in the personal overlay.
+
+## 0.1.1
+
+- Added a personal model overlay so local edits can remain separate from Pi's model configuration.

package/README.md

@@ -1,12 +1,6 @@
 # pi-better-model-select
 
-A searchable, usage-ranked model picker for [pi](https://pi.dev).
-
-`/bms` opens the effective model list from `models.json` plus the optional BMS-owned
-`models.bms.json` overlay, sorted by how often you pick each model. Start
-typing to filter; press enter to switch the session to the highlighted model.
-Add, update and delete live on ctrl-chords so plain keystrokes always go to the
-search box.
+A searchable model picker for [Pi](https://pi.dev). Switch models, edit model definitions, and save default models and thinking effort. Models you pick most often appear first.
 
 ## Install
 
@@ -14,121 +8,92 @@ search box.
 pi install npm:pi-better-model-select
 ```
 
-If you installed the package under its old name, migrate with:
+Run `/bms`, type to filter by name, model ID, or provider, then press Enter to switch models for the current session.
 
-```bash
-pi remove npm:@msenebald/better-model-select
-pi install npm:pi-better-model-select
-```
+## Compact TUI
+
+![BMS model search, forms, defaults, and result placement](docs/demo/showcase.gif)
 
-## Commands
+The picker uses aligned model, provider, context, usage, and status columns. Type in the search field in Pi's editor area. Results appear below search by default, matching Pi command completion. Choose **Options → Result placement → Above prompt** for bottom-up results with the best match nearest the search line.
 
-| Command    | What it does                                        |
-| ---------- | --------------------------------------------------- |
-| `/bms`     | Open the searchable, usage-ranked picker            |
-| `/bms-add` | Jump straight to the add-a-model flow               |
+Add and edit use one form. Review the fields, press Enter to change a value, then choose **Save configuration** or press Ctrl+S to save. Text and numeric fields currently open a Pi input dialog; choices use the compact table. Esc goes back; unsaved changes require a discard confirmation. Options also stay in a draft until saved.
 
-## Keys
+## Commands and shortcuts
 
-| Key        | Action                                              |
-| ---------- | --------------------------------------------------- |
-| `↑` `↓`    | Move through the list                               |
-| *type*     | Fuzzy filter by display name, model id or provider  |
-| `enter`    | Load the highlighted model                          |
-| `ctrl+a`   | Add a model                                         |
-| `ctrl+u`   | Update the highlighted model                        |
-| `ctrl+x`   | Delete the highlighted model                        |
-| `ctrl+o`   | Open BMS options                                    |
-| `ctrl+r`   | Reset usage statistics                              |
-| `esc`      | Close                                               |
+| Command | Action |
+| --- | --- |
+| `/bms` | Open the model picker |
+| `/bms-add` | Add a model |
+| `/bms-options` | Open result placement, write mode, and provider options |
+| `/bms-defaults` | Configure Pi and subagent defaults |
 
-## Options
+Inside `/bms`:
 
-Press `ctrl+o` in `/bms` to configure:
+| Key | Action |
+| --- | --- |
+| ↑ / ↓ | Move through models |
+| Enter | Use the selected model for this session |
+| Ctrl+D | Choose effort, save as the Pi default, and use it now |
+| Ctrl+G | Open the defaults menu |
+| Ctrl+A / Ctrl+U / Ctrl+X | Add / update / delete a model |
+| Ctrl+O | Open actions, including options and defaults |
+| Ctrl+R | Reset usage ranking |
+| Esc | Close |
 
-- **Write mode.** Overlay mode keeps Pi's `models.json` unchanged and stores
-  BMS edits in `models.bms.json`. Direct mode writes add, update and delete
-  operations to `models.json`.
-- **Provider filters.** Enable or disable providers in the `/bms` model list.
-  These filters do not change Pi's `/model` picker or either model file.
+The status column identifies the active model and saved default. Only Enter selections count toward usage ranking. Returning from a submenu preserves your search and selection. Plain menus always browse top-to-bottom; only searchable result lists reverse in above-prompt mode. Esc goes back one level, including back to Actions when that is where you entered a submenu.
 
-BMS stores these choices in `<agent-dir>/bms-settings.json`.
+## Default models and effort
 
-## Ranking
+Save a model and thinking effort for Pi, a subagent fallback, or an individual agent role.
 
-Every model loaded through `/bms` increments a counter in
-`<agent-dir>/bms-usage.json`. The list sorts by count, then by most recent use,
-then alphabetically — so an unused config starts in plain alphabetical order and
-drifts toward your habits.
+- Use Ctrl+D in `/bms` for the main Pi default.
+- Use `/bms-defaults` for all defaults. The menu starts in user scope; select the scope row to switch to a trusted project's settings.
+- Agent model and effort overrides are independent. You can inherit the parent model while choosing a different effort.
 
-Only `/bms` selections count. Switching via `/model`, `ctrl+p` cycling, or a
-session restore does not, which keeps the ranking a record of deliberate choices
-rather than of how often you restart pi.
+Removing an override restores the agent's own definition and fallback rules. Effort `off` is explicit, not inheritance. The menu shows saved settings and their sources, not running-child state.
 
-Stats for models that disappear from the effective configuration are pruned
-when the picker opens. `ctrl+r` clears everything.
+Run `/reload` after changing agent defaults or per-model effort preferences. Existing children stay unchanged. Test Pi startup defaults in a fresh session, since resumed sessions restore their recorded model and effort.
 
-## Metadata discovery
+### Optional pi-subagents integration
 
-When adding or updating, the extension tries to fill in context window, output
-cap, reasoning support and input modalities from, in order:
+[pi-subagents](https://github.com/nicobailon/pi-subagents) is a separate extension. Install it only if you want subagents:
 
-1. `GET {baseUrl}/model/info` — LiteLLM proxies
-2. `GET {baseUrl}/models/{id}` — OpenAI-style, plus proxy-specific fields
-3. The public LiteLLM model cost map on GitHub
+```bash
+pi install npm:pi-subagents
+```
 
-Each step is best-effort. A plain OpenAI-compatible endpoint usually yields
-nothing from steps 1 and 2, and the flow falls back to name-based heuristics
-with editable defaults. Choose the default write mode from `ctrl+o` in `/bms`. Overlay mode writes to
-`models.bms.json`; direct mode edits Pi's `models.json`. The selected file is re-read immediately before the
-write so a concurrent edit in another pi session is not clobbered.
+BMS discovers its agent roles and edits their saved model and effort defaults. It does not install `pi-subagents` automatically. External runner roles are read-only because their model settings belong to the runner.
 
-## Paths
+If discovery fails, **Agent discovery details** shows the error. Pi defaults work without this integration. See the configuration reference for compatibility details.
 
-All files resolve through pi's `getAgentDir()`, so `PI_CODING_AGENT_DIR` and
-rebranded distributions work without special handling:
+### Supported effort levels
 
-- `<agent-dir>/models.json` is Pi's documented compatible-endpoint configuration.
-- `<agent-dir>/models.bms.json` is the optional overlay owned and loaded by BMS.
-- `<agent-dir>/bms-settings.json` stores the write mode and provider filters.
-- `<agent-dir>/bms-usage.json` stores selection counters.
+BMS uses provider-reported effort lists when available and Pi's capability restrictions where supplied. Otherwise it offers Pi's standard levels, marked as provider support unverified:
 
-Pi does not load `models.bms.json` itself. In overlay mode, BMS merges it over
-`models.json` by provider and model id, then registers the merged providers
-through Pi's extension API. If the same model exists in both files, fields from
-`models.bms.json` win. Existing `models.local.json` overlays from BMS 0.1.x are
-renamed to `models.bms.json` automatically.
+```text
+off · minimal · low · medium · high · xhigh · max
+```
 
-Deleting a model that exists only in `models.json` leaves that file untouched.
-BMS writes `{ "id": "...", "bmsDeleted": true }` to the overlay instead.
-This tombstone keeps generated or externally managed model entries hidden across
-restarts. Delete it from `models.bms.json` to restore the inherited model.
+Add/update also lets you edit supported levels and set a per-model preferred effort. These hints do not change Pi's provider adapters. If Pi clamps an effort, BMS asks before saving the applied level. No paid model probes are made.
 
-Writes are atomic using a temporary file and rename, so an interrupted write
-cannot truncate either configuration file.
+## Where changes are saved
 
-## Development
+Open Ctrl+O → Options to select the model write mode:
 
-```bash
-npm install
-npm run typecheck
-node --experimental-strip-types --test extensions/lib/picker.test.ts
-pi -e . -p "say OK"      # load the extension without installing it
-```
+| Mode | Behavior |
+| --- | --- |
+| Overlay, the default | Save model edits in `models.bms.json`; leave `models.json` unchanged |
+| Direct | Write model edits to Pi's `models.json` |
 
-## Publishing
+Defaults always go into native Pi `settings.json`, regardless of write mode. User files normally live in `~/.pi/agent`; project defaults use `.pi/settings.json`. BMS respects `PI_CODING_AGENT_DIR` and shows the selected settings paths.
 
-Set the new version in `package.json` and `package-lock.json`, then run:
+Provider filters hide entries only in `/bms`, not Pi's `/model` picker. Default-assignment menus also include authenticated Pi registry models.
 
-```bash
-make publish
-```
+## Further documentation
 
-The target runs the full package gate, checks npm authentication, opens npm's
-browser login when needed, skips the upload if that exact version already
-exists, publishes the public scoped package, and waits for npm to expose the
-new version. npm can take several minutes to process a package. If verification
-times out, rerun `make verify-publish`; do not publish the same version again.
+- [Changelog](CHANGELOG.md): changes by version.
+- [Configuration reference](docs/configuration.md): file paths, precedence, overlays, metadata, and integration limits.
+- [Development and testing](docs/development.md): local loading, isolated tests, checks, and publishing.
 
 ## License
 

package/docs/configuration.md

@@ -0,0 +1,111 @@
+# Configuration reference
+
+See the [README](../README.md) for installation and shortcuts.
+
+## Files
+
+`<agent-dir>` is normally `~/.pi/agent`. BMS uses Pi's `getAgentDir()`, so it respects `PI_CODING_AGENT_DIR`.
+
+| File | Contents |
+| --- | --- |
+| `<agent-dir>/models.json` | Pi model definitions |
+| `<agent-dir>/models.bms.json` | BMS model overlay |
+| `<agent-dir>/bms-settings.json` | Write mode, result placement, and provider filters |
+| `<agent-dir>/bms-usage.json` | Selection counts and recency |
+| `<agent-dir>/bms-model-metadata.json` | Effort capability hints and their source |
+| `<agent-dir>/settings.json` | User defaults and per-model effort preferences |
+| `<project>/.pi/settings.json` | Project defaults |
+
+## Model write modes
+
+Choose the write mode through Ctrl+O → Options in `/bms`, then Ctrl+S to save.
+
+- Overlay mode, the default, leaves `models.json` unchanged and writes edits to `models.bms.json`.
+- Direct mode writes add, update, and delete operations to `models.json`.
+
+Pi does not load the overlay itself. BMS merges it over `models.json` by provider and model ID, then registers the merged providers through Pi's extension API. Overlay fields win for duplicate models. BMS automatically renames its old `models.local.json` overlay to `models.bms.json`.
+
+Deleting an inherited model in overlay mode writes a tombstone:
+
+```json
+{ "id": "model-id", "bmsDeleted": true }
+```
+
+Remove that entry from `models.bms.json` to restore the inherited model. Model files are re-read before writes and saved through a temporary file and rename. This does not provide a shared lock against other applications.
+
+Provider filters affect only `/bms`. They do not change Pi's `/model` picker or model definitions. Default-assignment menus ignore the filters and also include authenticated Pi registry models.
+
+## Picker layout
+
+`bms-settings.json` accepts `resultPlacement: "below"` or `"above"`. Missing or invalid values use `"below"`, matching Pi command completion. In above mode the best match is the bottom row, immediately above search; arrow keys follow physical screen direction. Searchable assignment menus use the same preference. Forms retain their normal top-to-bottom field order.
+
+The search field is part of a temporary custom interaction in Pi's editor area. BMS does not replace the normal editor factory. Enter loads the selected model; Esc returns to the editor. Up to six results are shown at a time, with scrolling for the rest.
+
+## Defaults and precedence
+
+Default settings are independent of the model write mode.
+
+| Setting | Native Pi settings field |
+| --- | --- |
+| Pi model | `defaultProvider`, `defaultModel` |
+| Pi effort | `defaultThinkingLevel` |
+| Per-model preferred effort | `modelThinkingLevels["provider/model"]` |
+| Subagent fallback | `subagents.defaultModel`, `subagents.defaultThinking` |
+| Role override | `subagents.agentOverrides.<name>.model` and `.thinking` |
+
+The defaults menu starts in user scope. Project scope requires a trusted project. Pi defaults use the working directory's `.pi/settings.json`. Agent defaults use the project root resolved by `pi-subagents`, which may differ in nested repositories. The menu shows the paths.
+
+Project settings and provider-specific role overrides may take precedence. BMS shows override sources and warns when a saved Pi default would be shadowed. Saving a Pi default removes the selected model's per-model effort preference in the same scope, so it cannot override the new default.
+
+For agent roles:
+
+- **Inherit parent model** writes `model: "inherit"`.
+- **Remove model override** restores agent-definition and fallback rules.
+- **Automatic** or **Remove effort override** removes that scope's effort preference. It does not force parent effort inheritance. `pi-subagents` has no separate persistent setting for that.
+- **Off** is an explicit effort level, not inheritance.
+
+Changing the Pi default also switches the main session. Subagent assignments do not switch it or increment usage counts. Cancelled or failed model switches leave saved defaults unchanged. If Pi clamps an effort, BMS asks before saving the applied level.
+
+Run `/reload` after changing agent defaults or per-model effort preferences. Running children keep their existing configuration, and subagent model-scope policies still apply at launch. Resumed Pi sessions restore their recorded model and effort. Test startup defaults in a fresh session without CLI model or effort overrides.
+
+Settings writes preserve unrelated fields, reject malformed JSON, and use atomic rename. A `.bms-lock` file serializes BMS settings writers only. After a crash, remove a stale lock only after checking that no BMS writer is active. Updates across model definitions, settings, and capability metadata are not a multi-file transaction.
+
+## Effort levels and metadata
+
+BMS uses explicit provider effort lists when supplied, then native Pi capability restrictions where available. Otherwise it offers Pi's standard levels and labels provider support as unverified:
+
+```text
+off, minimal, low, medium, high, xhigh, max
+```
+
+The metadata adapter recognizes `supported_reasoning_efforts`, `supported_thinking_levels`, and `reasoning_efforts` containing Pi effort names. A generic reasoning flag or `supported_parameters: ["reasoning_effort"]` does not specify supported levels.
+
+Add/update lets you edit the available levels and choose an optional per-model preferred effort. Non-reasoning models offer only `off`; correct the reasoning flag first if the endpoint metadata is wrong. BMS makes no paid model probes.
+
+Capability hints guide menus. They do not change provider adapters or prove an endpoint honors a level. Pi may clamp effort or map it to a token budget. Provider errors remain visible rather than triggering a model fallback.
+
+BMS blocks capability edits that conflict with directly pinned defaults in the inspected user/project settings. Update those defaults first. This check does not audit every inherited agent definition or settings file elsewhere on disk.
+
+When adding or updating models, BMS tries these metadata sources in order:
+
+1. `GET {baseUrl}/model/info` for LiteLLM proxies.
+2. `GET {baseUrl}/models/{id}` for OpenAI-style and proxy-specific fields.
+3. The public LiteLLM model cost map on GitHub.
+
+These requests are best-effort. Missing metadata falls back to name-based heuristics and editable defaults for context window, output limit, reasoning support, and input types.
+
+## Optional pi-subagents integration
+
+[pi-subagents](https://github.com/nicobailon/pi-subagents) is a separate Pi extension. BMS configures its saved model and effort defaults; it does not install it or launch agents to discover roles.
+
+Discovery was originally tested with `0.79.0` and has now been checked against `0.82.1`. BMS supports both the older root entry point and the newer `bundle/index.js` package layout. Discovery still uses internal discovery/runtime modules because the public agents API does not expose role discovery. Future incompatible versions may need an adapter update.
+
+The package must be resolvable from BMS or `<agent-dir>/npm/node_modules`. Discovery includes built-in, package, user, project, and runtime roles when supported by the installed API. Untrusted project agents and settings are excluded. External runner roles are shown read-only; configure their models through the runner's own settings.
+
+If discovery fails, the menu offers **Agent discovery details** with the error. Main Pi defaults remain usable.
+
+## Usage ranking
+
+Only models loaded with Enter in `/bms` count toward ranking. BMS sorts by selection count, then recency, then alphabetically. Default assignments, `/model`, model cycling, and session restores do not count.
+
+BMS prunes statistics for models missing from the effective configuration when the picker opens. Ctrl+R clears all usage statistics.

package/docs/development.md

@@ -0,0 +1,104 @@
+# Development and testing
+
+Run these commands from the repository checkout:
+
+```bash
+npm ci
+npm run gate
+npm run test:smoke  # optional: installed Pi, Python 3 and a POSIX PTY required
+pi --no-extensions -e ./extensions/bms.ts  # temporary load; no install or publish
+```
+
+## Temporary local testing
+
+Use a fresh terminal in this checkout. The command above disables installed
+extensions to avoid loading two copies of BMS. It still uses your real Pi settings,
+so default changes persist. For an isolated test, use a scratch agent directory
+and project directory instead:
+
+```bash
+REPO="$PWD"
+SANDBOX="$(mktemp -d -t bms-local)"
+mkdir -p "$SANDBOX/agent" "$SANDBOX/project/.pi"
+printf '{}\n' > "$SANDBOX/project/.pi/settings.json"
+# Optional: copy your model definitions. Review literal credentials in this file.
+cp "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/models.json" "$SANDBOX/agent/models.json"
+cd "$SANDBOX/project"
+PI_CODING_AGENT_DIR="$SANDBOX/agent" pi --no-extensions -e "$REPO/extensions/bms.ts"
+```
+
+Provider API-key environment variables remain available. The isolated directory
+has no login credentials; use `/login` there if needed. Do not commit credentials
+or scratch settings. To test agent roles, load your installed pi-subagents entry
+explicitly with another `-e` and make the package resolvable in the scratch agent's
+`npm/node_modules`, or use your real agent directory with backups. For the standard
+Pi npm install layout with pi-subagents 0.82.1, before launching:
+
+```bash
+REAL_AGENT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+ln -s "$REAL_AGENT/npm" "$SANDBOX/agent/npm"
+PI_CODING_AGENT_DIR="$SANDBOX/agent" pi --no-extensions \
+  -e "$REPO/extensions/bms.ts" -e "$REAL_AGENT/npm/node_modules/pi-subagents/bundle/index.js"
+```
+
+This symlinks installed package code, not your settings or auth files. Do not run
+package installation/update commands in this sandbox, since they would modify the
+shared package directory.
+
+The automated `npm run test:smoke` uses an unreachable dummy endpoint and
+throwaway settings. It checks command registration, the real TUI default-save
+flow, the defaults shortcut, and restoration in a fresh Pi process. No model
+prompts are sent. The regular test suite uses mocked provider metadata and UI.
+
+Manual checks:
+
+1. `/bms`: filter and use Enter. Only the current session should change.
+2. Reopen `/bms`, press Ctrl+D, choose effort and confirm. Check both markers,
+   the footer effort, and the scratch `agent/settings.json`.
+3. Cancel the effort dialog and confirmation. Neither should change defaults.
+4. `/bms-defaults`: select a Pi model, then select the same model again to change
+   only its default effort. Test user and trusted-project scope.
+5. Configure a subagent fallback and a role model/effort. Confirm the parent
+   session stays unchanged. Test explicit model inheritance and removal of each
+   override, then `/reload` and inspect `/subagents-models reviewer`.
+6. Add/update a model. Check provider-reported effort lists, the unverified Pi
+   fallback, manual levels, and the preferred effort. Try removing a level that
+   a directly pinned default uses; BMS should block the conflicting edit.
+7. Exit and start a fresh Pi session with the same scratch paths. Confirm startup
+   model and effort. Do not use `--continue`, `--resume`, or CLI model/effort overrides.
+8. Test a narrow terminal and verify the list, wrapped hints, and search still work.
+
+Quit Pi before deleting the sandbox with `rm -rf "$SANDBOX"`, then return to the
+checkout with `cd "$REPO"`. The test commands do not publish or install BMS.
+
+## Publishing
+
+Publish from `main` after the feature PR is reviewed and merged. Do not publish from the unmerged feature branch.
+
+For the current `0.2.0` release:
+
+```bash
+git switch main
+git pull --ff-only origin main
+npm ci
+npm run gate
+npm run test:smoke
+npm pack --dry-run
+```
+
+Check that the working tree is clean, both package manifests say `0.2.0`, and the package contains `README.md`, `docs/configuration.md`, and `docs/development.md`. Tests and the internal PR draft must not be included. The README links point to `main`, so merge the documentation before publishing.
+
+Then publish to the public npm registry:
+
+```bash
+make publish
+```
+
+For later releases, update both manifests with `npm version <version> --no-git-tag-version`, and include that change in a reviewed PR before publishing.
+
+The target runs the full package gate, checks npm authentication, opens npm's
+browser login when needed, skips the upload if that exact version already
+exists, publishes the public package, and waits for npm to expose the
+new version. npm can take several minutes to process a package. If verification
+times out, rerun `make verify-publish`; do not publish the same version again.
+