@firstpick/pi-package-webui 0.8.2 → 0.8.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -19
- package/bin/pi-webui.mjs +864 -140
- package/lib/WEBUI_TUI_NATIVE_PARITY.json +26 -0
- package/lib/git-workflow-preferences.mjs +246 -19
- package/lib/optional-feature-catalog.mjs +29 -0
- package/lib/optional-feature-migration.mjs +410 -0
- package/lib/session-summary-core.mjs +320 -0
- package/lib/session-summary-preferences.mjs +267 -0
- package/lib/thinking-stream-recovery.mjs +156 -0
- package/lib/ui-layout-settings.mjs +254 -0
- package/package.json +5 -40
- package/public/app.js +2898 -92
- package/public/index.html +77 -14
- package/public/service-worker.js +1 -1
- package/public/styles.css +669 -2
- package/session-summary.ts +403 -0
- package/tests/aur-review-widget-static.test.mjs +3 -2
- package/tests/boot-failure-diagnostics.test.mjs +3 -3
- package/tests/browser/composer-action-grid-reorder.spec.mjs +303 -0
- package/tests/browser/feature-decision-output-popup.spec.mjs +156 -0
- package/tests/browser/interaction-continuity.spec.mjs +29 -0
- package/tests/browser/persistent-ui-layout.spec.mjs +744 -0
- package/tests/browser/session-summary.spec.mjs +271 -0
- package/tests/codex-fast-mode-static.test.mjs +10 -9
- package/tests/composer-action-grid-reorder-static.test.mjs +63 -0
- package/tests/fast-mode-client-static.test.mjs +2 -2
- package/tests/feature-decision-output-popup-static.test.mjs +172 -0
- package/tests/fixtures/fake-pi.mjs +51 -1
- package/tests/git-workflow-preferences.test.mjs +4 -2
- package/tests/http-endpoints-harness.test.mjs +507 -4
- package/tests/interaction-state-stability-static.test.mjs +3 -0
- package/tests/mobile-continuity-tablet-static.test.mjs +3 -3
- package/tests/mobile-foundation-static.test.mjs +3 -3
- package/tests/mobile-phone-experience-static.test.mjs +1 -1
- package/tests/mobile-static.test.mjs +118 -103
- package/tests/native-parity-harness.test.mjs +9 -1
- package/tests/native-parity.test.mjs +23 -1
- package/tests/open-issue-wizard-static.test.mjs +1 -1
- package/tests/optional-feature-migration-frontend.test.mjs +72 -0
- package/tests/optional-feature-migration.test.mjs +142 -0
- package/tests/persistent-ui-layout-static.test.mjs +267 -0
- package/tests/questionnaire-dialog.test.mjs +511 -0
- package/tests/queue-edit-reorder-static.test.mjs +1 -0
- package/tests/remote-auth-settings-harness.test.mjs +1 -1
- package/tests/session-summary-core.test.mjs +491 -0
- package/tests/session-summary-preferences.test.mjs +103 -0
- package/tests/side-panel-resize-static.test.mjs +1 -0
- package/tests/side-panel-section-reorder-static.test.mjs +3 -3
- package/tests/subagent-launch-slots.test.mjs +1 -1
- package/tests/thinking-stream-recovery.test.mjs +88 -0
- package/tests/ui-layout-settings.test.mjs +92 -0
- package/tests/webui-settings-locking.test.mjs +159 -0
package/README.md
CHANGED
|
@@ -114,6 +114,8 @@ pi-webui [options] [-- <pi args...>]
|
|
|
114
114
|
--remote-auth Enable startup PIN authentication for non-local clients
|
|
115
115
|
--no-remote-auth Disable startup PIN authentication
|
|
116
116
|
--output-mode <mode> Web UI output default: normal or compact-v1
|
|
117
|
+
--migrate-optional-features Migrate audit-selected legacy optional features
|
|
118
|
+
--migration-dry-run Print the startup migration plan without package mutation
|
|
117
119
|
-h, --help Show help
|
|
118
120
|
-v, --version Print version
|
|
119
121
|
```
|
|
@@ -139,13 +141,58 @@ Environment variables:
|
|
|
139
141
|
- `PI_WEBUI_OUTPUT_MODE=normal|compact-v1` sets the server default for newly auto-negotiated browser connections.
|
|
140
142
|
- `PI_WEBUI_RPC_SUPERVISOR=0` opts out to the legacy server-owned Pi transport only when the current scope has no live managed tabs. Use explicit shutdown before disabling or downgrading; fallback startup refuses to create duplicate direct children for a live managed scope.
|
|
141
143
|
- Pi Web UI automatically injects a loopback `PI_WEBUI_RECOVERY_URL` and a bearer `PI_WEBUI_RECOVERY_TOKEN` into spawned Pi RPC processes. The authenticated endpoint can only create a separate plan-only recovery tab; keep any manually supplied token private.
|
|
142
|
-
- `PI_WEBUI_SETTINGS_FILE=/path/to/settings.json` overrides
|
|
143
|
-
- `
|
|
144
|
+
- `PI_WEBUI_SETTINGS_FILE=/path/to/settings.json` authoritatively overrides the private Web UI settings file (normally `~/.pi/webui/settings.json`) and disables automatic import from the old XDG location.
|
|
145
|
+
- `PI_SESSION_SUMMARY_CONFIG_FILE=/path/to/session-summary.json` overrides the private session-summary profile (normally `~/.pi/agent/session-summary.json`), primarily for isolated tests or managed deployments.
|
|
144
146
|
- `PI_WEBUI_FAST_PICKS_FILE=/path/to/paths.json` overrides saved cwd fast-pick storage.
|
|
145
|
-
-
|
|
147
|
+
- Optional feature install/update actions use the selected Pi executable (`--pi` or `PI_WEBUI_PI_BIN`) so registration and package storage stay owned by Pi.
|
|
148
|
+
- `--migrate-optional-features` is the explicit unattended opt-in for migrating every audit-selected legacy companion sequentially. Migration never starts implicitly from an environment variable.
|
|
149
|
+
- `--migration-dry-run` prints the sanitized startup audit/migration snapshot and performs no optional package or settings mutation. If both migration flags are supplied, dry-run wins.
|
|
146
150
|
- `PI_BANG_AUTOCOMPLETE_INCLUDE_HISTORY=1` lets optional bang-command autocomplete include local fish/bash/zsh history executables.
|
|
147
151
|
- `PI_BANG_AUTOCOMPLETE_RUNTIME_STORE_PATH=/path/to/runtime.json` overrides the runtime store shared with `@firstpick/pi-extension-bang-command-autocomplete`.
|
|
148
152
|
|
|
153
|
+
### Persistent session titles and summaries
|
|
154
|
+
|
|
155
|
+
The package registers `/summary` and `/summary-setup` in native Pi and explicitly loads the same extension in each Web UI tab. The feature is opt-in: loading the package makes no summary-model request until setup is reviewed and confirmed. Setup defaults to `openai-codex/gpt-5.6-luna` with `low` reasoning when that authenticated model is available; it never silently falls back to another provider or model.
|
|
156
|
+
|
|
157
|
+
`/summary-setup` selects the dedicated model/reasoning level, automatic generation, generated-title behavior, editable title and Markdown-summary prompts, and optional latest-summary context injection. Preferences are stored privately in `~/.pi/agent/session-summary.json`. The immutable code-owned system instruction is not editable. The browser exposes the same profile through **Common Pi options → Session Summary Setup**; the first Summary-button click opens setup, and confirmed setup immediately generates the first result.
|
|
158
|
+
|
|
159
|
+
After each true settled agent turn, enabled automatic generation runs as a bounded background request without starting another agent turn or delaying Pi's settled state. It sends active-branch user text, final assistant text, and tool names only. Thinking, images, tool arguments/results, credentials, hidden metadata, and previous summary control/display entries are excluded. One validated JSON response supplies both a title candidate and Markdown summary. Requests have a 90-second limit, no automatic retry, and a five-minute automatic-failure cooldown; manual **Refresh** may retry after the underlying problem is corrected.
|
|
160
|
+
|
|
161
|
+
Successful summaries are append-only, branch-aware Pi session state. Native `/summary` shows basic Markdown output. Web UI automatic updates remain silent; its header/composer Summary action opens a non-blocking sanitized Markdown overlay with copy and refresh controls. The last successful result survives provider, timeout, parse, and stale-branch failures. Generated names never overwrite explicit `/name`, `--name`, or browser tab names. The first eligible generated title applies immediately; later changed candidates require the configured cadence (three settled user turns by default) and the title prompt tells the model to retain the name unless the primary goal or scope changed substantially.
|
|
162
|
+
|
|
163
|
+
Main-agent context injection is off by default. When explicitly enabled, exactly one latest active-branch summary is added ephemerally as reference-only data; historical, display, and RPC summary messages are filtered out. Authenticated remote Web UI clients may configure and trigger summaries after the same privacy/cost confirmation. No credentials, raw transcript, or provider payload is returned through the summary HTTP APIs. To pause recurring calls without deleting prompts or prior results, turn off **Generate automatically** in setup. To roll back operationally, keep it off and use `/summary` only when needed.
|
|
164
|
+
|
|
165
|
+
Troubleshooting:
|
|
166
|
+
|
|
167
|
+
- If the configured model or authentication is unavailable, run `/login` or choose another explicitly available model in `/summary-setup`; the previous successful result is retained.
|
|
168
|
+
- A malformed or unsupported future config fails closed and is never overwritten automatically. Correct or move the private config, then rerun setup.
|
|
169
|
+
- In `--no-session` mode, generation can work in memory but is reported as non-durable.
|
|
170
|
+
- `/summary refresh` or the overlay **Refresh** action forces a bounded manual update without provider fallback.
|
|
171
|
+
|
|
172
|
+
### Optional-feature startup audit and migration
|
|
173
|
+
|
|
174
|
+
Every Web UI server start performs one bounded, read-only startup audit of optional features before the first normal Pi RPC tab starts. HTTP diagnostics and the browser are available immediately: the persistent status surface shows **Checking optional features…** and elapsed time while the browser reads the server-owned cached snapshot. The browser never scans package directories or Pi settings itself. A successful audit reports a truthful **Core ready · N optional features ready** summary; fresh minimal installs and upgrades whose companions are already registered or enabled as top-level resources require no confirmation.
|
|
175
|
+
|
|
176
|
+
When an older bundled Web UI feature needs restoration, the banner offers **Migrate…** and **Later**. **Migrate…** opens the single combined confirmation—there is no separate review screen. Previously enabled features are preselected, previously disabled features and features disabled in this browser are not, and the expandable **Choose features** area can adjust the batch. **Later** persists the dismissal so the migration banner does not return on every server start; a non-blocking **Migrate…** action remains in the Optional features panel.
|
|
177
|
+
|
|
178
|
+
Confirmed installs run one at a time through the selected Pi CLI. Progress is server-owned and reconnect-safe: the UI reports `Installing N of M: <name>`, elapsed time, ordered per-package results, and bounded localhost installer-output tails without inventing percentages. A browser refresh or SSE reconnect fetches the current cached snapshot rather than restarting the operation. Partial failure preserves successful rows and provides **Retry failed** plus **Copy commands**. On full success, an idle affected tab restarts automatically with a visible notice. If it is busy, work is not interrupted and a deferred **Restart tab** action appears.
|
|
179
|
+
|
|
180
|
+
Duplicate package/top-level ownership is never loaded twice. The audit safely excludes the top-level copy, and the conflict alert names only source kinds (`Pi package` and `top-level resource`), never raw host paths. **Copy recommended fix** copies the safe ownership recommendation: keep the registered package canonical, disable/remove the duplicate top-level extension/skill/prompt/theme alias, then **Recheck**. The current backend intentionally exposes no browser mutation route for alias removal.
|
|
181
|
+
|
|
182
|
+
Troubleshooting:
|
|
183
|
+
|
|
184
|
+
- **Recheck** reruns the bounded read-only audit after a timeout, malformed settings fix, or manual ownership repair. Degraded mode keeps the minimal core usable while optional companions stay excluded.
|
|
185
|
+
- **Retry failed** reruns only failed migration packages; successful registrations remain intact. **Copy commands** copies exact allowlisted `pi install npm:<package>` commands for manual host-side diagnostics.
|
|
186
|
+
- `pi-not-found`, permission, network, timeout, and post-install verification failures remain per-package terminal states with an actionable hint and bounded output tail.
|
|
187
|
+
- A stale confirmation is rejected with `409`; the browser silently refetches and retries when the candidate set is unchanged, or reopens the same combined confirmation when choices materially changed.
|
|
188
|
+
- Remote authenticated browsers may view sanitized audit status but cannot start installs, migration, dismissal, or recheck mutations; perform those actions from localhost.
|
|
189
|
+
|
|
190
|
+
### Persistent interface settings
|
|
191
|
+
|
|
192
|
+
Pi Web UI stores user-scoped settings in `~/.pi/webui/settings.json` by default. When that file is absent, a valid prior `$XDG_CONFIG_HOME/pi-webui/settings.json` (or `~/.config/pi-webui/settings.json`) is imported once without modifying or deleting the old file. An existing new file always wins, including when it is malformed, and `PI_WEBUI_SETTINGS_FILE` remains isolated from this migration. Writes use a private same-directory temporary file, atomic replacement, and a bounded same-host process lock; newly created settings files and directories use private permissions on supported platforms.
|
|
193
|
+
|
|
194
|
+
The authenticated `GET /api/interface-preferences` response includes normalized `preferences`, versioned `layout`, and an opaque `layoutRevision`. `PUT /api/interface-preferences` remains compatible with width-only `{ "sidePanelWidth": 612 }` writes. Layout patches require the latest revision in `expectedLayoutRevision`, merge only named fields, and are limited to 32 KiB; stale revisions return `409`, unsupported media types `415`, oversized bodies `413`, and invalid or unknown fields `400`. Browser local storage remains a non-destructive compatibility cache. Semantic file moves, prompt attachments, and follow-up queue mutations are not stored in the interface-layout envelope.
|
|
195
|
+
|
|
149
196
|
### Durable Pi session continuity
|
|
150
197
|
|
|
151
198
|
Pi Web UI normally runs Pi RPC tabs under a narrow detached supervisor. Restarting only the HTTP Web UI—through `/webui-start` on the same URL, **Restart**, a successful **Update & restart**, `POST /api/restart`, or a restart-safe service-manager `SIGTERM`—preserves each managed Pi PID, tab identity, cwd, session file, running state, and active model turn. Output produced while the HTTP server is absent is replayed in supervisor order. The browser rejects duplicate or older replay records; if the bounded live buffer has a gap, it refreshes tabs, state, and the durable transcript from Pi and warns that buffered live output may be incomplete.
|
|
@@ -196,12 +243,13 @@ Optional Natural Conversation server-side voice fallback variables:
|
|
|
196
243
|
- Tracked subagent output can open in the existing non-blocking overlay/widget or in a dedicated **Subagent** terminal tab, selected from the Subagents side-panel section and saved in the browser. The side-panel monitor keeps each status dot, agent type, provider/model, thinking effort, and run action on one compact line; run IDs, source/mode, elapsed state, and current-tool details live in the selected output view instead of being duplicated inline. Subagent tabs are view-only, reuse the bounded live transcript at the normal full terminal width, show the pulsing **Agent is running:** card with current child activity, and close without stopping or interrupting the child run; use the parent terminal for interaction. Dedicated **Subagent** terminal tabs show exactly six telemetry cards: PI, measured token speed, context, model, effort, and input/output tokens from a bounded recent session scan; unavailable or legacy evidence remains `—` or `unknown` rather than an estimate. The package also registers a generic `subagent_gate` tool that launches task slots through pi-subagents RPC v1, enforces a required success quorum, and performs bounded reason-aware retries only when declared safe; the side panel retains gate quorum, attempt, provider, and failure-class history after children finish.
|
|
197
244
|
- Unified command palette (`Ctrl/Cmd+K`) for commands, tabs, models, sessions, settings, app controls, and frequent Web UI actions.
|
|
198
245
|
- Automatic tab naming from the first prompt, with `--name <name>` still available for an explicit initial tab name.
|
|
246
|
+
- Opt-in branch-aware session titles and Markdown summaries through `/summary` and `/summary-setup`, with a dedicated background model, private persistent setup, silent post-settlement updates, explicit-name protection, optional latest-only context injection, and a non-blocking Web UI overlay.
|
|
199
247
|
- Streaming chat transcript with Markdown, copy buttons for fenced code blocks, rendered Mermaid diagrams from fenced `mermaid`/`mmd` code blocks, thinking output, tool/bash cards, queue and compaction events, edit-and-retry from user prompts, transcript search, copy buttons, and guarded abort controls that require holding Esc or the Abort button for 3 seconds.
|
|
200
248
|
- Prompt composer with uploads, drag/drop/paste, inline image support, generated text attachments for long input or clipboard text, editable text attachments, slash-command autocomplete, and `@` file/path references with live suggestions.
|
|
201
249
|
- Leading `!` and `!!` user-bash commands from the composer, serialized per tab; `!` keeps output in the next model context and `!!` excludes it. When the optional `@firstpick/pi-extension-bang-command-autocomplete` companion is loaded, the browser composer also suggests `!`/`!!` shell commands through `GET /api/bang-suggestions?tab=<tabId>&query=<command>`. When the optional `@firstpick/pi-extension-fish-user-bash` companion is loaded, Web UI user-bash execution emits the Pi `user_bash` event so the companion can provide the selected shell backend.
|
|
202
250
|
- Optional Natural Conversation Mode shell for the standalone `@firstpick/pi-package-natural-conversation` package: when `/talk` (or `/voice`/`/conversation`) is loaded in the active Pi tab, Web UI shows per-tab Start/End controls, a read-only voice-mode chip, and backend guards that keep thinking `off` while blocking unsafe Web UI actions.
|
|
203
251
|
- Browser voice loop for Natural Conversation Mode (`public/voice-conversation.mjs`): while the mode is active in a tab, the browser's Web Speech APIs listen for speech, send final transcripts as normal prompts, and speak Pi's final answers. The microphone pauses while answers are spoken (echo prevention), speech during final-output streaming becomes a steering interruption, speech during tool execution is queued until the tool phase ends, and silence after a spoken question sends a single structured silence event. Remote (non-localhost) sessions keep the microphone off until the per-tab `Allow remote microphone streaming` consent is granted; only text transcripts ever reach the Pi host on the browser-default path. Opt-in server-side fallback routes are available for local/Groq/OpenAI STT and local/OpenAI TTS when configured with server-side env vars; remote/LAN raw-audio STT fallback uploads require explicit per-request consent.
|
|
204
|
-
- Browser-native Pi dialogs for `/model`, `/settings`, `/safety-guard-setup`, `/git-workflow-setup`, `/theme`, `/fork`, `/clone`, `/name`, `/resume`, `/tree`, `/login`, `/logout`, `/scoped-models`, `/tools`, and `/skills`, plus native-command adapter output for `/copy`, `/session`, `/new`, `/compact`, `/reload`, and `/export`.
|
|
252
|
+
- Browser-native Pi dialogs for `/model`, `/settings`, `/summary-setup`, `/safety-guard-setup`, `/git-workflow-setup`, `/theme`, `/fork`, `/clone`, `/name`, `/resume`, `/tree`, `/login`, `/logout`, `/scoped-models`, `/tools`, and `/skills`, plus an on-demand `/summary` Markdown overlay and native-command adapter output for `/copy`, `/session`, `/new`, `/compact`, `/reload`, and `/export`.
|
|
205
253
|
- Runtime `/tools` and `/skills` selectors backed by the hidden Web UI RPC helper, with explicit **Session only** and **Global default** scopes. Session choices persist on the current branch and take precedence; global defaults are inherited by future sessions without rewriting existing branches. Disabled skills are removed from the system prompt, and tracked `SKILL.md` files can be opened/edited from skill tags.
|
|
206
254
|
- Session resume/switch, metadata rename, and localhost-only safe delete with active/open-tab/session-directory guards.
|
|
207
255
|
- Model, thinking, session, workspace, theme, optional-feature, Codex usage, optional Remote WebUI, update/restart/stop, event, notification, thinking-visibility, terminal-tab-layout, and custom-background controls in collapsible side-panel sections.
|
|
@@ -212,7 +260,7 @@ Optional Natural Conversation server-side voice fallback variables:
|
|
|
212
260
|
- Detected app runner dropdown for the active tab cwd, including Cargo, Bun, npm/npx/pnpm, Python/uv, Go/Golang, Zig, C/C++, Docker Compose, root/dev/scripts shell scripts, and other common project runners with live output pinned at the top of the terminal. Running app runners expose line-oriented stdin in the widget for interactive scripts. Projects can add browseable custom runners in `.pi-webui-runners.json` with a command (default `./`) plus a relative path to the file to run. The same dialog also configures project discovery paths: project-relative directories that are scanned one level deep (no subdirectories) for `.sh`, `.bash`, `.zsh`, `.fish`, and `.py` files plus extensionless files with a bash/sh, zsh, fish, or Python shebang. Python candidates use `uv run` and/or the available `python3`/`python` interpreter. Discovered scripts extend the built-in root, `dev/`, `scripts/`, and `dev/scripts/` detection and run from the resolved project root.
|
|
213
261
|
- Guided Git workflow for existing repos and new repos with persistent model/reasoning preferences, review-first staging, an optional manual staged repository-review gate from `aur-review`, generated or typed commit messages, explicit push/PR confirmation, and optional PR worktrees. When the review extension is loaded/enabled, both `git add .` and accepting the current staged set send `/aur-review start --scope staged --origin guided-git` to the same tab. Only its matching approval advances to message generation. The browser and server recheck the approved domain-separated staged-content hash before message generation, commit, and PR-worktree transfer; drift, missing hashes, or hash-check errors return to Stage and require a new review. A decline returns to staging and rejects an unchanged declined staged hash until corrected content is restaged. Guided Git never stages, commits, or pushes remediation automatically. The extension remains the decision authority; direct API callers are not granted an approval by this browser workflow.
|
|
214
262
|
- Browser support for Pi extension UI prompts, widgets, status updates, `/btw` side-question output widgets with optional context transfer/live steering, browser notifications when a tab needs an extension UI response, and an optional side-panel toggle for agent-done notifications.
|
|
215
|
-
- Localhost-only Pi/Web UI update checks with a top-right update notification and confirmed restart actions: **Update Pi & restart** runs `pi update --self` for Pi-only updates, while **Update Pi + Packages & Restart** first checks the selected Pi executable's `pi update --help`. It resolves that Pi installation and puts its bin directory first on the update task's `PATH`, so Pi and detected npm package roots use the npm bundled with the selected Pi instead of an unrelated stale shim. It uses `pi update --all` when advertised, otherwise falls back to `pi update --self` followed by `pi update --extensions
|
|
263
|
+
- Localhost-only Pi/Web UI update checks with a top-right update notification and confirmed restart actions: **Update Pi & restart** runs `pi update --self` for Pi-only updates, while **Update Pi + Packages & Restart** first checks the selected Pi executable's `pi update --help`. It resolves that Pi installation and puts its bin directory first on the update task's `PATH`, so Pi and detected npm package roots use the npm bundled with the selected Pi instead of an unrelated stale shim. It uses `pi update --all` when advertised, otherwise falls back to `pi update --self` followed by `pi update --extensions`. Pi owns configured Optional Feature updates; direct npm/Bun tasks are limited to detected core Pi/Web UI package roots.
|
|
216
264
|
- Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, which can ask Pi to create or update a LEARNING.
|
|
217
265
|
- Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay while confirmed restart/update actions run.
|
|
218
266
|
|
|
@@ -222,7 +270,7 @@ Web UI keeps a packaged parity matrix at `lib/WEBUI_TUI_NATIVE_PARITY.json` and
|
|
|
222
270
|
|
|
223
271
|
| Status | Commands and behavior |
|
|
224
272
|
| --- | --- |
|
|
225
|
-
| Implemented | `/model`, `/settings`, `/safety-guard-setup`, `/git-workflow-setup`, `/tools`, `/skills`, `/copy`, `/name`, `/session`, `/clone`, `/logout`, `/new`, `/compact`, and `/reload` use browser-native dialogs or structured native-command cards. |
|
|
273
|
+
| Implemented | `/model`, `/settings`, `/summary`, `/summary-setup`, `/safety-guard-setup`, `/git-workflow-setup`, `/tools`, `/skills`, `/copy`, `/name`, `/session`, `/clone`, `/logout`, `/new`, `/compact`, and `/reload` use browser-native dialogs, the summary overlay, or structured native-command cards. |
|
|
226
274
|
| Degraded / browser-specific | `/theme` changes the browser Web UI theme only; `/scoped-models` points to the footer scoped-model picker; `/export` supports no-path HTML downloads plus explicit new `.html`/`.jsonl` server paths; `/hotkeys` lists Web UI shortcuts; `/fork`, `/tree`, `/login`, and `/resume` have browser flows with documented gaps. |
|
|
227
275
|
| Unsupported in Web UI | `/import`, `/share`, `/changelog`, and `/quit` return structured unavailable output instead of raw HTTP errors. |
|
|
228
276
|
|
|
@@ -333,14 +381,14 @@ Discovery-path rules: at most 24 paths and direct children only (no recursive wa
|
|
|
333
381
|
- **What it is:** A browser-native `/skills` setup dialog for skills available in the active Pi tab.
|
|
334
382
|
- **What you can do:** Find skills by name or description, then use **Session only** to change automatic invocation on the current branch or **Global default** to save the skill allowlist inherited by future sessions.
|
|
335
383
|
|
|
336
|
-
Session-specific choices always win when their branch is resumed or selected in `/tree`. Saving a global default does not mutate currently open sessions. Global defaults are stored in the Pi Web UI settings file (normally `~/.
|
|
384
|
+
Session-specific choices always win when their branch is resumed or selected in `/tree`. Saving a global default does not mutate currently open sessions. Global defaults are stored in the Pi Web UI settings file (normally `~/.pi/webui/settings.json`).
|
|
337
385
|
|
|
338
386
|
### Optional features
|
|
339
387
|
|
|
340
388
|

|
|
341
389
|
|
|
342
|
-
- **What it is:** A
|
|
343
|
-
- **What you can do:** See whether each companion is enabled, disabled,
|
|
390
|
+
- **What it is:** A Pi package manager for Web UI-aware extensions, prompts, themes, and optional dashboards. Optional companions are separate from the Web UI core install.
|
|
391
|
+
- **What you can do:** See whether each companion is enabled, disabled, registered, local, migratable, missing, conflicting, or updateable; keep per-row Install/Update actions; restore previous companions through one combined confirmation; use panel-level **Install all** or section-level **Install missing** for missing/unregistered packages only; and recover partial failures with **Retry failed** or **Copy commands**. Batches run sequentially through Pi, continue after individual failures, and auto-restart an idle affected tab while deferring **Restart tab** when it is busy.
|
|
344
392
|
|
|
345
393
|
### `/btw` side questions
|
|
346
394
|
|
|
@@ -402,12 +450,15 @@ Useful browser endpoints exposed by the local server include:
|
|
|
402
450
|
- `GET /api/auth-providers` and localhost-only `POST /api/auth-logout` for provider-auth status and stored-credential removal.
|
|
403
451
|
- `GET /api/app-runners`, `POST /api/app-runner`, `POST /api/app-runner/input`, `POST /api/app-runner/stop`, `GET/POST/DELETE /api/app-runner-config`, and `GET /api/app-runner-files` for detected and custom project runners. `POST /api/app-runner-config` replaces project discovery paths with `{ "searchPaths": [...] }` or saves a custom runner with `{ "runner": { ... } }`; invalid path submissions fail atomically and leave the stored configuration unchanged.
|
|
404
452
|
- `GET /api/git-root`, `GET /api/git-panel`, and `GET /api/git-commit?hash=<full-hash>` for compact per-terminal-group repository discovery, local status/history snapshots, and bounded read-only commit diffs. `POST /api/git-changes/stage-all` and `POST /api/git-changes/unstage-all` complement the guarded path-level staging routes.
|
|
453
|
+
- Authenticated `GET`/`PUT /api/session-summary/preferences` for the allowlisted persistent profile projection and confirmed saves, plus authenticated `POST /api/session-summary/generate` for active-tab `/summary` dispatch. Mutations require same-origin JSON and bounded bodies; authenticated remote clients are allowed by the approved summary policy.
|
|
405
454
|
- `GET /api/git-changes`, `POST /api/git-changes/pull`, `GET /api/git-branches`, `POST /api/git-branch`, and `/api/git-workflow/*` for browser Git status, diff, branch, init, commit, push, and PR helpers.
|
|
406
455
|
- `POST /api/action-feedback?tab=<tabId>` for feedback on final assistant output and action cards.
|
|
407
|
-
- `GET /api/optional-features` for
|
|
408
|
-
- `POST /api/optional-feature-install` for installing or updating known optional companion
|
|
456
|
+
- `GET /api/optional-features` for the cached revisioned startup-audit snapshot, including phase, sanitized source/state, summary, reconnect-safe progress, and restart disposition.
|
|
457
|
+
- Localhost-only `POST /api/optional-feature-install` for installing or updating one known optional companion through Pi.
|
|
458
|
+
- Localhost-only `POST /api/optional-feature-install-batch` for a bounded allowlisted `featureIds` batch. It requires the current audit `revision`, installs sequentially, reports ordered per-feature and aggregate results, and accepts `migration: true` for the combined restore flow.
|
|
459
|
+
- Localhost-only `POST /api/optional-feature-migration/recheck` for a bounded read-only audit and `POST /api/optional-feature-migration/dismiss` for persisted **Later** state.
|
|
409
460
|
- `GET /api/git-workflow/staged-content?tab=<tabId>` for the read-only bounded staged-content hash used by Guided Git approval binding.
|
|
410
|
-
- `GET /api/update-status`, localhost-only `POST /api/restart`, and localhost-only `POST /api/update` for checking Pi/Web UI updates and restarting the Web UI. `POST /api/update?all=1` probes the selected Pi executable for `pi update --all`, uses the split `pi update --self` plus `pi update --extensions` fallback when unavailable,
|
|
461
|
+
- `GET /api/update-status`, localhost-only `POST /api/restart`, and localhost-only `POST /api/update` for checking Pi/Web UI updates and restarting the Web UI. `POST /api/update?all=1` probes the selected Pi executable for `pi update --all`, uses the split `pi update --self` plus `pi update --extensions` fallback when unavailable, lets Pi update registered Optional Features, and limits direct npm/Bun updates to detected core Pi/Web UI package roots.
|
|
411
462
|
- `GET /api/network`, localhost-only `POST /api/network/open`, localhost-only `POST /api/network/close`, `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for trusted-LAN exposure and optional 4-digit PIN authentication when serving non-local browser clients.
|
|
412
463
|
|
|
413
464
|
For local development, run the checkout helper directly, for example:
|
|
@@ -429,15 +480,21 @@ npm run test:browser
|
|
|
429
480
|
|
|
430
481
|
On hosts with WebKit's system libraries installed, provision it and include its project explicitly with `npx playwright install webkit && PI_WEBUI_TEST_WEBKIT=1 npm run test:browser`. The browser suite is intentionally separate from `npm test`; it covers browser-only geometry, flag/rollback, and scoped axe checks without making ordinary Node/static tests download browser engines.
|
|
431
482
|
|
|
432
|
-
|
|
483
|
+
When developing a companion package from this workspace, register that package with Pi from its absolute local path (for example, `pi install /path/to/pi-extension-stats`) and reload the affected native Pi/Web UI tabs. Optional companions are resolved from Pi settings rather than the Web UI manifest.
|
|
433
484
|
|
|
434
485
|
## Optional companion packages
|
|
435
486
|
|
|
436
|
-
|
|
487
|
+
Installing `npm:@firstpick/pi-package-webui` installs the Web UI core only; optional companions are independently registered Pi packages. Web UI tabs load enabled resources resolved from normal Pi settings, while excluding the Web UI package itself from re-loading. Startup checks loaded Pi capabilities directly through RPC-visible commands, tools, themes, and live widget events. The side panel separately reports physical installation and Pi registration, plus enabled top-level resources. A companion already enabled through `~/.pi/agent/extensions`, `skills`, `prompts`, or `themes` is treated as locally available and is excluded from install batches; attempting to register its npm package is blocked because both paths would load the same resource twice. Legacy/hoisted package files without either a Pi settings entry or an enabled top-level resource remain installable so Pi can register them canonically.
|
|
488
|
+
|
|
489
|
+
Use a per-row **Install** or **Update** action for one package. **Install all** selects every missing/unregistered feature, while each section's **Install missing** selects only missing/unregistered features in that group; neither bulk action installs updates. A batch has one confirmation, runs sequentially, continues after failures, and keeps bounded diagnostics in each row and the activity log. The server automatically restarts an idle affected tab after full success; a busy tab is never interrupted and instead exposes one deferred **Restart tab** action. All browser install and migration actions are localhost-only and limited to the server allowlist.
|
|
490
|
+
|
|
491
|
+
You can install any published companion separately from a terminal with its exact unpinned Pi source, then reload Pi/Web UI tabs:
|
|
437
492
|
|
|
438
|
-
|
|
493
|
+
```bash
|
|
494
|
+
pi install npm:@firstpick/pi-extension-stats
|
|
495
|
+
```
|
|
439
496
|
|
|
440
|
-
|
|
497
|
+
Replace the package name with the companion listed below. Re-running the same `pi install npm:<package>` command is the supported update path. `@firstpick/pi-extension-aur-review` is not published yet; from this workspace, use `pi install /home/firstpick/pi-coding-agent-forge/pi-extension-aur-review` until its npm source becomes available.
|
|
441
498
|
|
|
442
499
|
Optional companions:
|
|
443
500
|
|
|
@@ -463,7 +520,7 @@ Optional companions:
|
|
|
463
520
|
|
|
464
521
|
The Git workflow button runs local git commands in the active Pi working directory. It covers both empty/new projects and existing repositories.
|
|
465
522
|
|
|
466
|
-
Before first use, run `/git-workflow-setup` in Pi or choose **Common Pi Options → Guided Git Setup** in the browser. Select an exact authenticated `provider/modelId`, a supported reasoning effort, and the workflow defaults described below. The browser preselects the active tab model when possible, but saving is always explicit. Preferences are stored globally in the Pi Web UI settings file (normally `~/.
|
|
523
|
+
Before first use, run `/git-workflow-setup` in Pi or choose **Common Pi Options → Guided Git Setup** in the browser. Select an exact authenticated `provider/modelId`, a supported reasoning effort, and the workflow defaults described below. The browser preselects the active tab model when possible, but saving is always explicit. Preferences are stored globally in the Pi Web UI settings file (normally `~/.pi/webui/settings.json`), not in browser storage.
|
|
467
524
|
|
|
468
525
|
For a new project, the browser flow can:
|
|
469
526
|
|
|
@@ -551,7 +608,7 @@ Keep this browser configuration disabled until the gateway's exact-origin CORS p
|
|
|
551
608
|
|
|
552
609
|
- **`/webui-start` is missing:** restart Pi after installing the package.
|
|
553
610
|
- **Wrong port or existing server:** use `/webui-status detailed`, or start on another port with `/webui-start --port 31500`.
|
|
554
|
-
- **Optional feature is disabled or
|
|
555
|
-
-
|
|
611
|
+
- **Optional feature is disabled, missing, or unregistered:** check the side panel, use its Pi install action (or manually run the displayed `pi install npm:<package>` command), then run `/reload` in the active Pi tab.
|
|
612
|
+
- **Pi install/update fails:** copy the bounded row diagnostics and displayed Pi command. Run that command on the Web UI host to inspect full Pi/npm output and verify that the selected Pi executable can update user package settings.
|
|
556
613
|
- **Remote browser asks for a PIN:** read it from the optional **Remote WebUI** side-panel controls, `/webui-status`, `/remote status`, or the local Web UI server log. Disable the toggle from localhost to remove the PIN gate.
|
|
557
614
|
- **PWA install or notifications are unavailable:** use `localhost` or HTTPS; browser support varies on LAN HTTP URLs.
|