@robhowley/pi-openrouter 0.8.3 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # pi-openrouter
 
-A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic `session_id` tagging, and user-scoped model catalog sync.
+A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic `session_id` tagging, user-scoped model catalog sync, and local model field overrides.
 
 ## Installation
 
@@ -12,13 +12,18 @@ pi install npm:@robhowley/pi-openrouter
 
 Set one of these environment variables:
 
-- `OPENROUTER_MANAGEMENT_KEY` (preferred), provides full usage data including model breakdowns
-- `OPENROUTER_API_KEY`, basic usage data plus user-scoped model sync
+- `OPENROUTER_MANAGEMENT_KEY` (preferred) — provides full usage/analytics and can be used for model sync
+- `OPENROUTER_API_KEY` — basic usage data and user-scoped model sync
 
 ```shell
 export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 ```
 
+**Key selection:**
+
+- Usage/account commands prefer `OPENROUTER_MANAGEMENT_KEY` for full analytics, falling back to `OPENROUTER_API_KEY`
+- Model sync prefers `OPENROUTER_API_KEY` but will attempt `OPENROUTER_MANAGEMENT_KEY` if only that is set
+
 ## Commands
 
 ```bash
@@ -28,6 +33,9 @@ export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 /openrouter models-sync              # sync user-scoped OpenRouter models into Pi
 /openrouter models-status            # show model sync/cache status
 /openrouter models-status --skipped  # show skipped model reasons
+/openrouter model-override-set       # set local model field overrides
+/openrouter model-override-list      # list local model field overrides
+/openrouter model-override-clear     # clear local model field overrides
 ```
 
 ## Model catalog sync
@@ -36,7 +44,7 @@ export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 
 `/openrouter models-sync`
 
-The sync uses OpenRouter’s authenticated user model catalog, so Pi can see the models available to your account instead of only the default provider list.
+The sync uses OpenRouter’s authenticated user model catalog, so Pi can see the models available to your account instead of only the default provider list. This intentionally replaces Pi's OpenRouter provider model list with your user-scoped catalog plus OpenRouter's built-in router aliases (`openrouter/auto`, `openrouter/free`, and `openrouter/owl-alpha`). It does not merge in every built-in model unless that model is returned by your OpenRouter account catalog.
 
 `/openrouter models-status`
 
@@ -51,6 +59,8 @@ To see why models were skipped:
 
 `/openrouter models-status --skipped`
 
+Skipped output may include a grouped suggestion when Pi can offer a safe next step, such as adding a local `contextWindow` override for incomplete metadata.
+
 Skipped models do not make the sync fail; models are skipped when required metadata cannot be safely mapped into Pi’s provider model config. The last successful catalog is cached so Pi can keep using it if a later refresh fails, and the cache persists across sessions. If a session starts with a cached catalog that has not been registered yet, status will show:
 
 ```text
@@ -64,6 +74,7 @@ Run '/openrouter models-sync' to register models
 Type `/openrouter usage` in Pi to open the usage overlay.
 
 The overlay shows:
+
 - **Month spend** vs cap with percentage
 - **7-day spend** with burn rate projection
 - **Today's spend** from live tracked turns while Activity API data catches up
@@ -98,6 +109,8 @@ Select a key from the list to inspect its limit, usage, reset cadence, and BYOK
 
 `pi-openrouter` automatically tags OpenRouter requests with a `session_id` derived from the Pi session ID.
 
+Request detection is intentionally broad: the extension checks provider metadata, `openrouter/...` model ids, configured OpenRouter base URLs, Shopify's ZDR provider flag, and request URLs/endpoints so tagging still works across different Pi event shapes.
+
 View the OpenRouter session tag with:
 
 ```bash
@@ -107,6 +120,76 @@ View the OpenRouter session tag with:
 pi:[uuid]
 ```
 
+## Local usage tracking
+
+The extension logs completed OpenRouter turns to local JSONL files in `~/.pi/openrouter/usage/` to provide near-real-time usage data for "Today's spend" in the usage overlay. This supplements the OpenRouter Activity API, which typically has a delay.
+
+**Retention:** Local usage files are automatically cleaned up after 90 days.
+
+**Debug logging:** By default, file operations are quiet (fail-open). To enable verbose logging for troubleshooting:
+
+```bash
+export PI_OPENROUTER_DEBUG_USAGE=1
+```
+
+This logs write/read errors, malformed lines, and cleanup operations to the console.
+
+## Model field overrides
+
+Some OpenRouter models don't have complete metadata in Pi's built-in registry or the OpenRouter model catalog. You can manually configure supported `PiModelConfig` fields using scoped syntax:
+
+```bash
+# Override thinking levels for DeepSeek V4 Pro
+/openrouter model-override-set deepseek/deepseek-v4-pro thinking.high=high thinking.xhigh=max
+
+# Same thing with exact field names
+/openrouter model-override-set deepseek/deepseek-v4-pro thinkingLevelMap.high=high thinkingLevelMap.xhigh=max
+
+# Override context window or max tokens
+/openrouter model-override-set custom/model contextWindow=128000 maxTokens=8192
+```
+
+**Scoped field names:**
+
+- `thinking.off`, `thinking.minimal`, `thinking.low`, `thinking.medium`, `thinking.high`, `thinking.xhigh` → map to `thinkingLevelMap.*`
+- `contextWindow` → `contextWindow` (number)
+- `maxTokens` → `maxTokens` (number)
+- `reasoning` → `reasoning` (boolean)
+
+For CLI `thinking.*` / `thinkingLevelMap.*` assignments, `pi-openrouter` only accepts the conservative documented value set: `off`, `minimal`, `low`, `medium`, `high`, `max`, `xhigh`, or `null`.
+
+Use `null` to hide a level from Pi's UI:
+
+```bash
+/openrouter model-override-set deepseek/deepseek-v4-pro thinking.off=null
+```
+
+If you need an advanced or experimental thinking value outside that CLI set, edit `~/.pi/openrouter/model-overrides.json` directly. The JSON file is the escape hatch; the CLI intentionally stays conservative.
+
+List your overrides:
+
+```bash
+/openrouter model-override-list                    # all models
+/openrouter model-override-list --fields           # available fields
+/openrouter model-override-list deepseek/deepseek-v4-pro  # specific model
+```
+
+Clear overrides:
+
+```bash
+/openrouter model-override-clear deepseek/deepseek-v4-pro
+```
+
+Overrides are stored in `~/.pi/openrouter/model-overrides.json`.
+
+Precedence is:
+
+1. Pi's built-in registry
+2. OpenRouter's user-scoped model catalog
+3. Local overrides from `~/.pi/openrouter/model-overrides.json`
+
+That means local overrides win. Run `/openrouter models-sync` after changing overrides to apply them to the registered OpenRouter model list.
+
 ## License
 
 MIT