@jmfederico/pi-web 1.202606.3 → 1.202606.5

package/docs/config.md

@@ -0,0 +1,166 @@
+# PI WEB configuration reference
+
+PI WEB configuration covers the machine-local and project-local settings you usually need: the web/API bind address, trusted development-host settings, UI preferences, plugin enablement, file-explorer path access, upload limits, and session-daemon tools.
+
+This file is the markdown reference for agents and package consumers. The website page is <https://pi-web.dev/config>.
+
+## Config files
+
+PI WEB uses two config files:
+
+- **Global PI WEB config:** `$PI_WEB_CONFIG`, or `$XDG_CONFIG_HOME/pi-web/config.json`, or `~/.config/pi-web/config.json`.
+- **Project-local PI WEB config:** `<project>/.pi-web/config.json` for commit-able project settings.
+
+Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's config by opening that machine directly or changing files on that machine.
+
+If you installed services with a custom config path, rerun `pi-web install --config /path/to/config.json` after changing that path or after upgrading from a version that only applied the custom path to the web service. This regenerates service files so the web/API and session daemon use the same `PI_WEB_CONFIG`.
+
+## Precedence and reloads
+
+Runtime values are resolved as:
+
+```text
+defaults → config file → environment overrides
+```
+
+Environment overrides include `PI_WEB_HOST`, `PI_WEB_PORT` / `PORT`, `PI_WEB_ALLOWED_HOSTS`, `PI_WEB_MAX_UPLOAD_BYTES`, `PI_WEB_SPAWN_SESSIONS`, and `PI_WEB_SUBSESSIONS`.
+
+Process restarts depend on the key:
+
+- `host` / `port`: restart the web/API service or process.
+- `maxUploadBytes`: restart both the web/API process and the session daemon.
+- `spawnSessions` / `subsessions`: restart the session daemon.
+- `pathAccess`: applies on the next request; existing file views may need a browser refresh.
+- `plugins`: reload the browser tab after changing plugin enablement.
+- `shortcuts`: saved settings apply in the browser after config refresh/save.
+
+## Global config example
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8504,
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  },
+  "maxUploadBytes": 67108864,
+  "spawnSessions": true,
+  "subsessions": false,
+  "plugins": {
+    "workspace-tasks": { "enabled": true },
+    "updates": { "enabled": true },
+    "info": { "enabled": false }
+  },
+  "shortcuts": {
+    "core:view.chat": "mod+1",
+    "core:session.stop": null
+  }
+}
+```
+
+## Project-local config
+
+Project-local config lives at `<project>/.pi-web/config.json`. Use it for settings that should follow a repository.
+
+```json
+{
+  "version": 1,
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  }
+}
+```
+
+Project-local `pathAccess.allowedPaths` entries are merged after the global list and deduplicated. Paths must still be host-absolute or `~`-prefixed; relative roots are not supported.
+
+Plugins may own separate project files, such as `.pi-web/tasks.json` for the built-in Workspace Tasks plugin.
+
+## Configuration matrix
+
+Rows with JSON key `—` are runtime-only environment variables, not config-file keys.
+
+| Config | JSON key | Env var | Scope | Project-local behavior | Applies / restart |
+| --- | --- | --- | --- | --- | --- |
+| **Config-file keys** |  |  |  |  |  |
+| Web/API bind host | `host` | `PI_WEB_HOST` | Global | Not supported locally | Restart web/API |
+| Web/API port | `port` | `PI_WEB_PORT`, `PORT` | Global | Not supported locally | Restart web/API |
+| Dev-server allowed hosts | `allowedHosts` | `PI_WEB_ALLOWED_HOSTS` | Global | Not supported locally | Restart dev web/UI |
+| External filesystem roots | `pathAccess.allowedPaths` | — | Global + project | **Merges**: global roots first, then project roots; duplicates removed | Next file request; refresh existing views if needed |
+| Upload/body limit | `maxUploadBytes` | `PI_WEB_MAX_UPLOAD_BYTES` | Global | Not supported locally | Restart web/API and session daemon |
+| Agent can spawn sessions | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon |
+| Tracked subsessions (beta) | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon |
+| 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 |
+| **Runtime-only environment variables** |  |  |  |  |  |
+| Global config file path | — | `PI_WEB_CONFIG` (`XDG_CONFIG_HOME` affects the default path) | Process/env | Selects the global config file; not a project config | Restart services/processes after changing env |
+| Managed data directory | — | `PI_WEB_DATA_DIR` | Process/env | Not supported locally | Restart services before changing; moves managed state location |
+| Session daemon socket | — | `PI_WEB_SESSIOND_SOCKET` | Web/API + session daemon env | Not supported locally | Restart daemon and web/API; both must match |
+| Session daemon TCP port | — | `PI_WEB_SESSIOND_PORT` | Session daemon env | Not supported locally | Restart session daemon; set `PI_WEB_SESSIOND_URL` for web/API too |
+| Session daemon TCP host | — | `PI_WEB_SESSIOND_HOST` | Session daemon env | Not supported locally | Restart session daemon |
+| Web-to-daemon URL | — | `PI_WEB_SESSIOND_URL` | Web/API env | Not supported locally | Restart web/API |
+| Projects storage file | — | `PI_WEB_PROJECTS_FILE` | Web/API + session daemon env | Not supported locally | Restart services; advanced state override |
+| Remote machines storage file | — | `PI_WEB_MACHINES_FILE` | Web/API env | Not supported locally | Restart web/API; advanced state override |
+| Pi session storage directory | — | `PI_CODING_AGENT_SESSION_DIR` | Pi/session daemon env | Not supported locally | Restart session daemon; follows Pi session priority |
+| Pi agent config directory | — | `PI_CODING_AGENT_DIR` | Pi/Web/API/session daemon env | Not supported locally | Restart services |
+| Skip update checks | — | `PI_WEB_SKIP_VERSION_CHECK`, `PI_WEB_OFFLINE`, `PI_SKIP_VERSION_CHECK`, `PI_OFFLINE` | Web/API env | Not supported locally | Restart web/API after env changes |
+
+## Key details
+
+### External path access
+
+`pathAccess.allowedPaths` grants PI WEB's file explorer and absolute `@` path completions access to specific filesystem roots outside the current workspace.
+
+By default, workspace-relative file reads stay inside the workspace and absolute paths are denied. Add only roots you trust PI WEB to list and read through the browser UI.
+
+Accepted root forms:
+
+- Unix absolute paths: `/opt/reference`
+- Home-relative paths: `~/SDKs`
+- Windows absolute paths on Windows hosts: `C:\Users\dev\SDKs`
+
+When an absolute request is served, PI WEB expands `~`, canonicalizes the configured roots with `realpath`, requires roots to be existing directories, and rejects symlink escapes outside the allowed roots.
+
+This is not a sandbox for the underlying Pi Coding Agent or your OS user. It only controls PI WEB UI/API file exposure outside a workspace.
+
+### Session daemon tools
+
+`spawnSessions` controls whether agents receive the `spawn_session` tool. It defaults to `true`; set it to `false` if you do not want an agent to start independent PI WEB sessions.
+
+`subsessions` is beta and controls whether agents receive the tracked-subsession tools: `spawn_subsession`, `list_subsessions`, `check_subsession`, and `read_subsession`. It defaults to `false` and also requires `spawnSessions` to be enabled.
+
+Tracked subsessions let an agent delegate work to child sessions, get notified when children stop working, and inspect their transcripts.
+
+### Plugin config
+
+Plugins are enabled by default. Set `plugins.<id>.enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` before the browser imports it.
+
+```json
+{
+  "plugins": {
+    "workspace-tasks": { "enabled": true, "settings": {} },
+    "updates": { "enabled": false }
+  }
+}
+```
+
+Reload the browser tab after changing plugin enablement. Already-loaded plugin JavaScript is not unloaded from the current page.
+
+### Shortcut config
+
+Shortcut values are keyed by action id. Values are shortcut strings such as `mod+k` or `mod+g p`; `null` disables that action's shortcut.
+
+```json
+{
+  "shortcuts": {
+    "core:view.chat": "mod+1",
+    "core:session.stop": null
+  }
+}
+```
+
+Prefer Settings → Keyboard for editing shortcuts interactively.
+
+## Optional completion tools
+
+File and path `@` completions work without extra tools. If `fzf` is available on the PI WEB server's `PATH`, PI WEB uses it to improve completion filtering/ranking; otherwise it falls back to built-in ranking.

package/docs/plugins.md

@@ -42,7 +42,7 @@ Copy-paste prompt for creating a plugin:
 Build a PI WEB plugin for this project.
 Goal: <describe the UI behavior>.
 Before coding, read the PI WEB plugin docs:
-https://pi-web.dev/plugins.html
+https://pi-web.dev/plugins
 Full API reference:
 https://pi-web.dev/plugins.md
 Create it as a local plugin under ~/.pi-web/plugins/<plugin-id>.
@@ -56,7 +56,7 @@ Copy-paste prompt for modifying a plugin:
 ```text
 Improve the PI WEB plugin at <path>.
 Before coding, read the PI WEB plugin docs:
-https://pi-web.dev/plugins.html
+https://pi-web.dev/plugins
 Full API reference:
 https://pi-web.dev/plugins.md
 Keep the plugin compatible with the documented v1 API.
@@ -131,7 +131,7 @@ Reload the PI WEB browser tab. PI WEB serves plugin modules with an mtime-based
 
 ## Remote machine plugins
 
-When [machine federation](https://pi-web.dev/machines.html) is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
+When [machine federation](https://pi-web.dev/machines) is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
 
 - actions, workspace panels, and workspace labels only appear while that machine is selected;
 - plugin file and terminal helpers run against that machine;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmfederico/pi-web",
-  "version": "1.202606.3",
-  "description": "Remote web UI and browser control plane for persistent Pi Coding Agent sessions.",
+  "version": "1.202606.5",
+  "description": "Web UI for persistent Pi Coding Agent sessions in real workspaces.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez",
   "type": "module",
@@ -17,6 +17,7 @@
     "LICENSE",
     "extensions",
     "docs/plugins.md",
+    "docs/config.md",
     "docs/assets",
     "plugin-api.d.ts",
     "plugin-api/unstable.d.ts"
@@ -31,10 +32,12 @@
     "build": "tsc -p tsconfig.build.json && npm run build:plugin-api && npm run build:plugins && vite build",
     "build:plugin-api": "tsc -p tsconfig.plugin-api.json",
     "build:plugins": "tsc -p tsconfig.plugins.json && node scripts/build-plugins.mjs",
+    "capture:screenshots": "node scripts/capture-screenshots.mjs",
     "typecheck": "tsc --noEmit",
+    "knip": "knip",
     "lint": "eslint \"src/**/*.ts\" \"extensions/**/*.ts\" \"pi-web-plugins/**/*.ts\" vite.config.ts vitest.config.ts",
     "test": "vitest run --config vitest.config.ts",
-    "verify": "npm run typecheck && npm run lint && npm test",
+    "verify": "npm run typecheck && npm run lint && npm run knip && npm test",
     "start": "tsx src/server/index.ts",
     "start:sessiond": "tsx src/server/sessiond.ts",
     "clean": "rm -rf dist",
@@ -48,6 +51,7 @@
     "changelog:status": "changeset status"
   },
   "dependencies": {
+    "@codemirror/commands": "^6.10.3",
     "@codemirror/lang-css": "^6.3.1",
     "@codemirror/lang-go": "^6.0.1",
     "@codemirror/lang-html": "^6.4.11",
@@ -56,33 +60,38 @@
     "@codemirror/lang-markdown": "^6.5.0",
     "@codemirror/lang-python": "^6.2.1",
     "@codemirror/lang-rust": "^6.0.2",
+    "@codemirror/language": "^6.12.3",
     "@codemirror/legacy-modes": "^6.5.2",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.42.1",
     "@fastify/static": "^9.1.3",
     "@fastify/websocket": "^11.2.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
-    "codemirror": "^6.0.2",
     "diff": "^8.0.4",
     "fastify": "^5.6.1",
     "lit": "^3.3.1",
     "marked": "^18.0.3",
     "node-pty": "^1.1.0",
+    "typebox": "1.1.38",
     "ws": "^8.20.1"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
+    "@earendil-works/pi-agent-core": "^0.79.1",
+    "@earendil-works/pi-ai": "^0.79.1",
     "@earendil-works/pi-coding-agent": "^0.79.1",
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.10.1",
     "@types/ws": "^8.18.1",
     "eslint": "^10.3.0",
     "globals": "^17.6.0",
+    "knip": "^6.16.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.59.2",
     "vite": "^7.2.4",
-    "vitest": "^4.1.5",
-    "@earendil-works/pi-ai": "^0.79.1"
+    "vitest": "^4.1.5"
   },
   "publishConfig": {
     "access": "public"
@@ -100,22 +109,26 @@
   "homepage": "https://pi-web.dev/",
   "packageManager": "npm@11.11.0",
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.78.0 <1",
-    "@earendil-works/pi-ai": ">=0.78.0 <1"
+    "@earendil-works/pi-agent-core": ">=0.78.0 <1",
+    "@earendil-works/pi-ai": ">=0.78.0 <1",
+    "@earendil-works/pi-coding-agent": ">=0.78.0 <1"
   },
   "keywords": [
     "pi-package",
     "pi",
+    "pi-web",
+    "pi-web-ui",
+    "pi-webui",
     "pi-coding-agent",
+    "pi-coding-agent-web-ui",
     "coding-agent",
-    "agent",
-    "web",
-    "ui",
+    "ai-coding-agent",
+    "agentic-development",
+    "developer-tools",
     "web-ui",
     "webui",
-    "remote",
-    "browser",
-    "control-plane",
+    "browser-ui",
+    "remote-development",
     "persistent-sessions"
   ],
   "pi": {