@hyperdreamer/pi-webui 1.11.0-beta.9 → 1.11.0

package/docs/config.md

@@ -11,7 +11,7 @@ PI WEBUI uses two config files:
 - **Global PI WEBUI config:** `$PI_WEBUI_CONFIG`, or `$XDG_CONFIG_HOME/pi-webui/config.json`, or `~/.config/pi-webui/config.json`.
 - **Project-local PI WEBUI config:** `<project>/.pi-webui/config.json` for commit-able project settings.
 
-Each PI WEBUI machine has its own config. When using Fleet/machine federation, Settings uses the selected machine for config that affects work running there: the Pi-compatible agent profile and companion CLI, session daemon tools, model tier routing ladder, PI WEBUI plugin enablement, external path access, and upload defaults. Gateway/browser-only settings stay local to the gateway: keyboard shortcuts, remote machine registry/tokens, and gateway host/port/allowed-hosts. Remote servers that do not advertise selected-machine settings support report those settings as unavailable instead of silently falling back to the gateway.
+Each PI WEBUI machine has its own config. When using Fleet/machine federation, Settings uses the selected machine for config that affects work running there: the Pi-compatible agent profile and companion CLI, session daemon tools, model tier routing ladder, utility model routing, PI WEBUI plugin enablement, external path access, and upload defaults. Gateway/browser-only settings stay local to the gateway: keyboard shortcuts, remote machine registry/tokens, and gateway host/port/allowed-hosts. Remote servers that do not advertise selected-machine settings support report those settings as unavailable instead of silently falling back to the gateway.
 
 Pi package settings are separate from PI WEBUI config. They live in Pi's package-manager settings on the target machine and are managed by Pi (`pi install`, `pi remove`, `pi update`) or **Settings → Pi packages**. In a federated setup, **Settings → Pi packages** targets the currently selected machine. The PI WEBUI `plugins` config key only enables or disables discovered PI WEBUI browser plugins on the machine whose config you are editing; it does not install, remove, or update Pi packages.
 
@@ -41,6 +41,7 @@ Process restarts depend on the key:
 - `maxUploadBytes`: restart both the web/API process and the session daemon on that machine.
 - `agent.command` / `agent.dir` / `spawnSessions` / `subsessions`: restart the session daemon on that machine.
 - `modelTiers`: saved settings apply immediately in **Settings → Model tiers**; validates all six ladder rows atomically.
+- `utilityModels`: saved settings apply immediately in **Settings → Utility models**; existing sessions use updated values on their next utility operation.
 - `pathAccess`: applies on the next request; existing file views may need a browser refresh.
 - `uploads.defaultFolder`: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.
 - `plugins`: reload the browser tab after changing PI WEBUI plugin enablement.
@@ -72,6 +73,17 @@ Process restarts depend on the key:
     "capable": { "provider": "anthropic", "modelId": "claude-3-7-sonnet-20250219", "thinkingLevel": "high" },
     "frontier": { "provider": "openai", "modelId": "o3-mini", "thinkingLevel": "high" }
   },
+  "utilityModels": {
+    "lightweight": {
+      "provider": "anthropic",
+      "id": "claude-haiku",
+      "thinkingLevel": "low"
+    },
+    "context": {
+      "provider": "anthropic",
+      "id": "claude-sonnet"
+    }
+  },
   "spawnSessions": true,
   "subsessions": false,
   "plugins": {
@@ -110,7 +122,7 @@ Plugins may own separate project files, such as `.pi-webui/tasks.json` for the b
 
 ## Configuration matrix
 
-Rows with JSON key `—` are runtime-only environment variables, not config-file keys. `Global` means machine-global. In Settings, selected-machine-safe global keys (`pathAccess`, `uploads`, `maxUploadBytes`, `agent`, `spawnSessions`, `subsessions`, `modelTiers`, and `plugins`) are edited for the selected machine; gateway host/port/allowed-hosts, keyboard shortcuts, and machine registry/tokens stay local.
+Rows with JSON key `—` are runtime-only environment variables, not config-file keys. `Global` means machine-global. In Settings, selected-machine-safe global keys (`pathAccess`, `uploads`, `maxUploadBytes`, `agent`, `spawnSessions`, `subsessions`, `modelTiers`, `utilityModels`, and `plugins`) are edited for the selected machine; gateway host/port/allowed-hosts, keyboard shortcuts, and machine registry/tokens stay local.
 
 | Config | JSON key | Env var | Scope | Project-local behavior | Applies / restart |
 | --- | --- | --- | --- | --- | --- |
@@ -126,6 +138,7 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
 | Agent can spawn sessions | `spawnSessions` | `PI_WEBUI_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon on that machine |
 | Tracked subsessions (beta) | `subsessions` | `PI_WEBUI_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon on that machine |
 | Model tier routing ladder | `modelTiers` | — | Global | Not supported locally | Saved settings apply immediately on save; requires remote peer capability `settings.modelTiers` |
+| Utility model routing | `utilityModels` | — | Global | Not supported locally | Saved settings apply immediately on the next utility operation; requires remote peer capability `settings.utilityModels` |
 | Plugin enablement/settings | `plugins.<id>.enabled`, `plugins.<id>.settings` | — | Global | Not core local config; plugins may read their own project files | Reload browser tab |
 | Keyboard shortcuts | `shortcuts.<actionId>` | — | Global | Not supported locally | Applies after settings save/config refresh |
 | Project config version | `version` | — | Project | Project-local only; must be `1` when present | Next project-config read |
@@ -224,6 +237,22 @@ The navigation footer exposes **Models** for the selected machine and **Skills**
 
 **Skills** lists the skills available to the selected workspace. It can toggle the `disable-model-invocation` frontmatter setting in a `SKILL.md`, search skills.sh, and install or update skills at global or project scope. Review third-party skill sources before installing them. After changing, installing, or updating a skill, use `/reload` in each idle session that should pick up the changed resource.
 
+### Utility models
+
+`utilityModels` is a machine-global setting stored in `$PI_WEBUI_CONFIG` or `~/.config/pi-webui/config.json`. In **Settings → Utility models**, configure models and thinking levels for utility work on the selected machine. This is separate from **Settings → Model tiers**, which controls session model routing.
+
+- `lightweight` handles automatic titles and requested branch summaries. `context` handles compaction.
+- Each row selects one model and one thinking level for every operation routed through that row.
+- The UI displays the automatic choice as lowercase `auto`; it is represented by an omitted `thinkingLevel` in config rather than a literal `auto` value.
+- `auto` uses `minimal` when the exact selected model supports it, otherwise `off`.
+- Explicit options are derived from the selected model's supported levels and may include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
+- Changing a model resets that row to `auto`. A saved explicit level that the model no longer supports remains visible, blocks save, and causes only that utility slot to be skipped until repaired.
+- Title generation and branch summaries try `lightweight`, then the active session model. Compaction tries `context`, then `lightweight`, then the active session model; the Context-to-Lightweight fallback uses each row's own configured level.
+- When both settings are unset, existing active-session behavior is preserved. An unset, malformed, unavailable, unauthenticated, authentication-failing, or call-failing candidate advances to the next fallback in its order. The active-session fallback keeps its existing behavior.
+- Utility calls never change the selected session model, its thinking level, or Pi's remembered default.
+- Version 1 remotes remain model-configurable but require an upgraded runtime for explicit thinking levels.
+- Settings target the selected machine. Existing sessions read saved changes on their next utility operation; remote editing requires the additive `settings.utilityModels` capability.
+
 ### Model tiers
 
 `modelTiers` is a machine-global setting stored in `$PI_WEBUI_CONFIG` or `~/.config/pi-webui/config.json` that configures tier-based model routing for sessions.
@@ -240,17 +269,17 @@ In **Settings → Model tiers**, you edit one complete six-rung ladder: `economy
 Sessions can also use a per-session model policy from the composer:
 
 - **Composer controls:** The composer action row has three cascading controls: a mode pill, a mode-dependent second control, and an Exact-only thinking menu. The mode pill opens a two-item mode menu: **Exact model** with the hint "Choose a model and thinking level", and **Tiered** with the hint "Use a configured model tier". A checkmark marks the current mode. There is no policy panel or Save button.
-- **Exact fallback:** With no remembered starter preference, a new root starts in Exact mode using Pi's persisted model and thinking defaults. Selecting Exact remembers the mode while retaining the last selected tier for a later switch back.
+- **Default and restoration:** On a fully capable peer, a fresh workspace starts in Tiered mode at Standard. The starter model policy preference restores the full policy for the selected machine and normalized workspace: mode, Exact provider/model/thinking, and remembered tier.
 - **Exact controls:** The second control is the searchable model picker, and the third is a thinking level menu whose trigger is a bar gauge showing the current level's rank, with the level name in its tooltip. The menu lists levels relevant to the selected model in canonical ascending order: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. A level the model does not support stays visible but dimmed, says `unsupported by this model`, and cannot be selected. An Exact change applies once both a model and a supported thinking level are selected.
-- **Remembered starter policy:** A valid starter mode and tier are remembered per workspace on the selected machine. Starter selections update this personal managed state immediately; changes inside an existing session do not change future-session defaults.
+- **Remembered starter policy:** Only a root created successfully through **SESSIONS +** owns future full-policy updates to this personal managed state. Imported, prompt-created, spawned, and tracked sessions never become preference sources. Selecting Exact retains the remembered tier for a later switch back.
 - **Tiered:** In Tiered mode, the second control is a tier menu listing all six ladder tiers. An unusable tier stays visible with its specific reason inline instead of being hidden, and selecting a valid tier applies immediately. No thinking control renders in Tiered mode; it is absent rather than disabled. Switching modes is non-destructive in both directions: the remembered tier and the remembered Exact model/thinking selection stay intact.
-- **Validation and recovery:** A remembered Tiered choice whose current mapping is unavailable remains selected and blocks Start until the user chooses a valid tier, switches to a complete Exact branch, or repairs the ladder. PI WEBUI never substitutes another tier or Exact mode. A refused Start reports its reason without closing the new-session screen, and the reason is shown whether or not a session is currently selected in that workspace. The message follows the current reason and disappears once the block is repaired.
-- **Persistence failures:** If PI WEBUI cannot read the preference, a complete Exact starter remains usable and the composer shows the preference error. If a write fails, the current session still starts with the selected in-memory policy but PI WEBUI warns that the choice was not remembered.
+- **Validation and recovery:** Unavailable active intent remains selected, blocks Start, and shows its specific reason until the user repairs that active branch. Intent remembered in the inactive branch is retained and non-blocking until that branch becomes active. PI WEBUI never substitutes another tier or Exact mode. A refused Start reports its reason without closing the new-session screen, and the reason is shown whether or not a session is currently selected in that workspace. The message follows the current reason and disappears once the block is repaired.
+- **Persistence failures:** If PI WEBUI cannot read the preference, it shows the preference error without discarding the in-memory policy. A writeback failure is non-blocking: the current session retains its selected policy, and PI WEBUI warns that the choice was not remembered.
 - **When changes are available:** You can change a policy only while its session is idle and writable. During active work and for archived sessions, the current policy and any block reason remain visible but the controls are disabled. Once the session is idle and writable, a blocked policy remains repairable through an explicit update.
-- **Availability and compatibility:** Per-session policy uses `sessions.modelPolicy`; persisted starter mode/tier additionally requires `sessions.modelPolicyDefaults` on both web and session daemon. Older peers keep the previous in-memory starter behavior.
+- **Availability and compatibility:** Per-session policy uses `sessions.modelPolicy`; restoring and writing back the full starter preference additionally requires `sessions.modelPolicyStarterSelection` on both web and session daemon. `sessions.modelPolicyDefaults` remains the version-one mode/tier preference path. Older peers retain version-one behavior.
 - **Managed state and concurrency:** Preferences live in `$PI_WEBUI_DATA_DIR/starter-model-policy-preferences.json` on the selected machine. One daemon serializes complete read-modify-write operations; atomic file replacement prevents partial JSON. Concurrent tabs therefore use last-successful-write-wins semantics in daemon queue order, not browser click order or cross-process locking.
 - **Starting and persistence:** The selected policy is carried into root-session creation from both the first-prompt and **New Session** paths, persists with that session, and remains selected after a failed creation so a retry uses the same choice.
-- **Scope and installation:** This release does not add `/tier-*` commands, and editing the tier ladder later does not automatically remap an existing Tiered session. After installing this release, restart `pi-webui-sessiond.service` manually once; ordinary UI/API autoreload does not load session-daemon changes.
+- **Scope and installation:** This release does not add `/tier-*` commands, and editing the tier ladder later does not automatically remap an existing Tiered session. Installing this change requires one manual `pi-webui-sessiond.service` restart; ordinary UI/API autoreload does not load session-daemon changes.
 
 ### Session daemon tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdreamer/pi-webui",
-  "version": "1.11.0-beta.9",
+  "version": "1.11.0",
   "description": "Web UI for persistent Pi Coding Agent sessions in real workspaces.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez and HyperDreamer",