@firstpick/pi-package-webui 0.4.0 → 0.4.2

package/README.md

@@ -6,7 +6,7 @@ Local browser UI for [Pi coding agent](https://www.npmjs.com/package/@earendil-w
 
 Pi Web UI gives you a local browser companion for Pi: multi-tab chat, streaming output, model controls, uploads, slash-command helpers, workspace navigation, and optional extension widgets.
 
-> **Security:** Pi Web UI has no authentication. It can control the spawned Pi session and run anything that session is allowed to run. It binds to `127.0.0.1` by default; only expose it on trusted networks.
+> **Security:** Pi Web UI can control the spawned Pi session and run anything that session is allowed to run. It binds to `127.0.0.1` by default. Remote PIN authentication is off by default; enable it in **Controls → Network → Remote PIN auth** before exposing it on trusted networks.
 
 ## Requirements
 
@@ -54,6 +54,8 @@ Check a running Web UI with:
   --no-open          Do not open the browser automatically
   --no-session       Start Pi RPC with --no-session
   --name <name>      Initial Web UI tab name
+  --remote-auth      Enable startup PIN authentication for non-local clients
+  --no-remote-auth   Disable startup PIN authentication
   -- <pi args...>    Extra arguments forwarded to Pi RPC
 ```
 
@@ -63,6 +65,7 @@ Examples:
 /webui-start
 /webui-start 31500
 /webui-start --port 31500 --no-open
+/webui-start --remote-auth --host 0.0.0.0
 /webui-start --name browser -- --model anthropic/claude-sonnet-4-5:high
 ```
 
@@ -74,7 +77,7 @@ Running `/webui-start` again on the same URL restarts the server and restores cu
 /webui-status [detailed] [port] [--port N] [--host HOST]
 ```
 
-`/webui-status` reports the URL, online state, and network exposure. `detailed` adds tabs, sessions, models/providers, and recent backend events.
+`/webui-status` reports the URL, online state, network exposure, and Remote PIN auth state. `detailed` adds tabs, sessions, models/providers, and recent backend events.
 
 ## Standalone CLI
 
@@ -96,6 +99,8 @@ pi-webui [options] [-- <pi args...>]
   --pi <command>      Pi executable to spawn (default: bundled dependency, then "pi")
   --no-session        Start Pi RPC with --no-session
   --name <name>       Initial Web UI tab name
+  --remote-auth       Enable startup PIN authentication for non-local clients
+  --no-remote-auth    Disable startup PIN authentication
   -h, --help          Show help
   -v, --version       Print version
 ```
@@ -107,6 +112,7 @@ Examples:
 ```bash
 pi-webui
 pi-webui --cwd ~/src/my-project
+pi-webui --host 0.0.0.0 --remote-auth --cwd ~/src/my-project
 pi-webui --port 3000 -- --model anthropic/claude-sonnet-4-5:high
 PI_WEBUI_PI_BIN=/path/to/pi pi-webui --no-session
 ```
@@ -116,16 +122,19 @@ Environment variables:
 - `PI_WEBUI_HOST`
 - `PI_WEBUI_PORT`
 - `PI_WEBUI_PI_BIN`
+- `PI_WEBUI_REMOTE_AUTH=1` to start with remote PIN authentication enabled
 
 ## Main features
 
 - Pathless `pi-webui` startup: the server opens first, then the browser prompts for the first terminal CWD.
-- Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, and activity state.
+- Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, activity state, and a workspace dashboard for common actions.
+- Unified command palette (`Ctrl/Cmd+K`) for commands, tabs, models, sessions, settings, and frequent Web UI actions.
 - Automatic tab naming from the first prompt, with `--name <name>` still available for an explicit initial tab name.
-- Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, and abort controls.
+- Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, edit-and-retry from user prompts, and abort controls.
 - Prompt composer with uploads, drag/drop/paste, inline image support, slash-command autocomplete, and `@` file/path references with live suggestions.
 - Browser dialogs for common Pi selectors such as `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/resume`, `/tree`, `/scoped-models`, `/tools`, and `/skills`.
 - Model, thinking, session, workspace, theme, optional-feature, Codex usage, network, update/restart, event, and notification controls in the side panel.
+- Persistent context-window meter with manual compact and auto-compaction controls near the composer.
 - Side-panel theme picker backed by optional `@firstpick/pi-themes-bundle` themes when loaded.
 - Per-tab cwd changes, a clickable footer cwd picker, saved path fast picks, server-persisted fast picks, and restart-safe restoration of open tabs.
 - 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. Projects can add browseable custom runners in `.pi-webui-runners.json` with a command (default `./`) plus a relative path to the file to run.
@@ -138,8 +147,10 @@ Useful browser endpoints exposed by the local server include:
 
 - `GET /api/path-suggestions?tab=<tabId>&query=<path>` for `@` file/path references with live suggestions.
 - `POST /api/action-feedback?tab=<tabId>` for feedback on final assistant output and action cards.
-- `POST /api/optional-feature-install` for installing known optional companion packages from the side panel.
+- `GET /api/optional-features` for optional companion package install/update status.
+- `POST /api/optional-feature-install` for installing or updating known optional companion packages from the side panel.
 - `GET /api/update-status` and localhost-only `POST /api/update` for checking Pi/Web UI updates and running `pi update` plus all detected local/global Web UI and Pi package-manager updates followed by a Web UI server restart.
+- `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for optional 4-digit PIN authentication when serving non-local browser clients.
 
 For local development, run the checkout helper directly, for example:
 
@@ -151,9 +162,9 @@ Run `../dev/scripts/sync-pi-package-symlinks.sh` first when developing companion
 
 ## Optional companion packages
 
-A normal Pi/npm install includes the optional companion packages unless optional dependencies are disabled. Each Web UI tab curates Pi resources from the Web UI package that started the server, while preserving unrelated user/project resources; separately installed Web UI companion packages are ignored to avoid loading two copies. Startup checks loaded Pi capabilities directly through RPC-visible commands and live widget events, then the side panel shows each optional feature as enabled, disabled, or install-needed. Installing a missing feature is an explicit, warned action; it is localhost-only, limited to known packages, and requires reloading the active Pi tab after installation.
+A normal Pi/npm install includes the optional companion packages unless optional dependencies are disabled. Each Web UI tab curates Pi resources from the Web UI package that started the server, while preserving unrelated user/project resources. Companion packages installed as global/npm-prefix siblings of the started Web UI package are reused when the Web UI package does not have its own nested optional dependency copy, avoiding duplicate loads while keeping global `pi-webui` launches working. Startup checks loaded Pi capabilities directly through RPC-visible commands and live widget events, then the side panel shows each optional feature as enabled, disabled, installed-but-not-loaded, update-available, or install-needed. Installing or updating a feature is an explicit, warned action with running/failure feedback in the row and activity log; it is localhost-only, limited to known packages, and requires reloading the active Pi tab after installation.
 
-When the standalone global `pi-webui` launcher is used, optional companion installs should target the Pi agent npm root instead of the global npm prefix. Override the target explicitly with `PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT=/path/to/package-root` when needed.
+When the standalone global `pi-webui` launcher is used, optional companion installs target the npm prefix containing the Web UI package when that prefix is safe, otherwise the Pi agent npm root if it contains Web UI. Override the target explicitly with `PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT=/path/to/package-root` when needed.
 
 Optional companions:
 
@@ -194,8 +205,11 @@ This requires `/git-staged-msg` and `/pr` from `@firstpick/pi-prompts-git-pr`; b
 
 - Default bind is localhost-only: `127.0.0.1:31415`.
 - The side-panel **Open to network** button rebinds the server to `0.0.0.0`, shows LAN URLs when available, and toggles to "Close for network".
-- `--host 0.0.0.0` also exposes the Web UI to the local network.
-- Any connected browser client can control Pi and run Web UI bash actions as the Web UI process user.
+- The side-panel **Remote PIN auth** toggle is off by default. When enabled, the server generates a random 4-digit PIN, shows it in Controls and `/webui-status`, and requires it from non-local browser clients.
+- Localhost clients stay frictionless and can toggle Remote PIN auth; changing the toggle disconnects existing event streams so remote clients must re-authenticate after enablement.
+- `--host 0.0.0.0` also exposes the Web UI to the local network; pass `--remote-auth` to start with PIN auth already enabled.
+- Any connected browser client with access (and the PIN, if enabled) can control Pi and run Web UI bash actions as the Web UI process user.
+- Remote PIN auth is a simple trusted-LAN HTTP gate, not hardened multi-user authentication; do not expose it to untrusted networks.
 - The Web UI update endpoint is restricted to localhost, because it runs package update commands and restarts the server.
 - Treat Pi Web UI as a local companion, not a hardened multi-user web service.
 
@@ -204,4 +218,5 @@ This requires `/git-staged-msg` and `/pr` from `@firstpick/pi-prompts-git-pr`; b
 - **`/webui-start` is missing:** restart Pi after installing the package.
 - **Wrong port or existing server:** use `/webui-status detailed`, or start on another port with `/webui-start --port 31500`.
 - **Optional feature is disabled or missing:** check the side panel, install the companion package if needed, then run `/reload` in the active Pi tab.
+- **Remote browser asks for a PIN:** read it from **Controls → Network → Remote PIN auth**, `/webui-status`, or the local Web UI server log. Disable the toggle from localhost to remove the PIN gate.
 - **PWA install or notifications are unavailable:** use `localhost` or HTTPS; browser support varies on LAN HTTP URLs.