@firstpick/pi-package-webui 0.9.0 → 0.9.2
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 +236 -24
- package/bin/pi-webui-launcher.mjs +23 -12
- package/bin/pi-webui.mjs +493 -65
- package/lib/agent-run-adapters.mjs +500 -0
- package/lib/agent-run-protocol.mjs +262 -0
- package/lib/agent-run-registry.mjs +339 -0
- package/lib/app-runner-terminal.mjs +40 -0
- package/lib/git-workflow-preferences.mjs +11 -4
- package/lib/trust-boundaries.mjs +2 -0
- package/lib/ui-layout-settings.mjs +172 -28
- package/lib/update/package-layout.mjs +50 -0
- package/lib/update/plan.mjs +11 -0
- package/package.json +2 -2
- package/public/app.js +1376 -337
- package/public/index.html +113 -68
- package/public/service-worker.js +1 -1
- package/public/styles.css +371 -93
- package/tests/agent-run-adapters.test.mjs +217 -0
- package/tests/agent-run-launcher.test.mjs +41 -0
- package/tests/agent-run-protocol.test.mjs +82 -0
- package/tests/agent-run-registry.test.mjs +102 -0
- package/tests/app-runner-terminal-static.test.mjs +28 -0
- package/tests/app-runner-terminal.test.mjs +65 -0
- package/tests/boot-failure-diagnostics.test.mjs +3 -3
- package/tests/browser/control-deck-side-panels.spec.mjs +354 -0
- package/tests/browser/controls-layout.spec.mjs +122 -0
- package/tests/browser/file-tree-git-ignored.spec.mjs +113 -0
- package/tests/browser/interaction-continuity.spec.mjs +159 -0
- package/tests/browser/mobile-foundation.spec.mjs +26 -0
- package/tests/browser/model-search-focus.spec.mjs +96 -0
- package/tests/browser/optimistic-prompt.spec.mjs +22 -0
- package/tests/browser/persistent-ui-layout.spec.mjs +224 -66
- package/tests/browser/subagent-observability.spec.mjs +87 -0
- package/tests/chat-scroll-intent-static.test.mjs +1 -1
- package/tests/codex-fast-mode-static.test.mjs +2 -2
- package/tests/component-update-api-static.test.mjs +2 -1
- package/tests/composer-action-grid-reorder-static.test.mjs +3 -3
- package/tests/control-deck-component-updates-static.test.mjs +2 -0
- package/tests/control-deck-side-panels-static.test.mjs +68 -0
- package/tests/controls-layout-static.test.mjs +22 -0
- package/tests/fast-mode-client-static.test.mjs +1 -1
- package/tests/feature-decision-output-popup-static.test.mjs +2 -2
- package/tests/file-tree-git-ignored-static.test.mjs +152 -0
- package/tests/file-tree-search-layout-static.test.mjs +2 -1
- package/tests/fixtures/fake-pi.mjs +43 -7
- package/tests/footer-provider-usage-visual-static.test.mjs +10 -8
- package/tests/git-workflow-preferences.test.mjs +55 -6
- package/tests/http-endpoints-harness.test.mjs +173 -14
- package/tests/middle-button-drag-scroll-static.test.mjs +3 -3
- 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 +18 -5
- package/tests/open-issue-wizard-static.test.mjs +2 -2
- package/tests/persistent-ui-layout-static.test.mjs +13 -13
- package/tests/questionnaire-dialog.test.mjs +3 -3
- package/tests/remote-auth-settings-harness.test.mjs +1 -1
- package/tests/session-sampling-ui-static.test.mjs +3 -3
- package/tests/side-panel-context-menu-static.test.mjs +1 -1
- package/tests/side-panel-resize-static.test.mjs +26 -16
- package/tests/side-panel-section-height-removal-static.test.mjs +4 -4
- package/tests/side-panel-section-reorder-static.test.mjs +16 -70
- package/tests/subagent-gate-visibility.test.mjs +2 -1
- package/tests/subagent-launch-slots.test.mjs +1 -1
- package/tests/subagent-observability-static.test.mjs +32 -0
- package/tests/subagent-reliability-integration.test.mjs +161 -0
- package/tests/subagents-helper.test.mjs +344 -4
- package/tests/terminal-tabs-resize-static.test.mjs +35 -0
- package/tests/theme-customizer-static.test.mjs +1 -1
- package/tests/ui-layout-settings.test.mjs +104 -32
- package/tests/update-api-harness.test.mjs +24 -10
- package/tests/update-package-layout.test.mjs +38 -0
- package/tests/update-plan.test.mjs +11 -1
- package/tests/webui-settings-locking.test.mjs +33 -3
- package/webui-rpc-helper.mjs +417 -28
package/README.md
CHANGED
|
@@ -1,60 +1,272 @@
|
|
|
1
1
|
# Pi Web UI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Run Pi in a local browser with multi-session tabs, streaming output, model controls, file uploads, Git workflows, and optional companion features.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@firstpick/pi-package-webui)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
|
|
4
9
|
|
|
5
10
|

|
|
6
11
|
|
|
12
|
+
**Optional feature needed:** None — the main window is included in Pi Web UI core. Companion widgets appear only when their packages are installed.
|
|
13
|
+
|
|
14
|
+
Pi Web UI keeps the normal Pi agent experience while giving you more room to manage sessions, inspect work, and control common workflows. It listens on localhost by default, runs alongside Pi, and can be opened from Pi or with a standalone launcher.
|
|
15
|
+
|
|
7
16
|
## What you can do
|
|
8
17
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
18
|
+
| Area | Highlights |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| **Sessions and workspaces** | Run several isolated Pi sessions, resume prior work, switch projects, preserve per-tab drafts, and create branch worktrees. |
|
|
21
|
+
| **Live agent work** | Follow streaming Markdown, thinking, tool output, queues, todo progress, and managed or registered Pi agent runs without leaving the browser. |
|
|
22
|
+
| **Models and controls** | Change models and thinking effort, manage scoped models, configure tools and skills, and use the command palette. |
|
|
23
|
+
| **Files and prompts** | Upload or paste files and images, edit text attachments, use slash-command suggestions, browse project files, and reference project paths with `@`. |
|
|
24
|
+
| **Git workflows** | Inspect changes, switch branches, review diffs, stage work, generate commit messages, push, and prepare pull requests through guided steps. |
|
|
25
|
+
| **Project utilities** | Launch detected app runners, manage working directories, search files and transcripts, and customize themes. |
|
|
26
|
+
| **Companion features** | Add stats, remote access, voice, `/btw`, richer Git status, themes, release tools, and other supported Pi packages. |
|
|
27
|
+
| **Desktop and mobile** | Use a full desktop workspace with resizable left and right side panels, or a compact phone layout with touch-friendly navigation and controls. |
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
16
30
|
|
|
17
|
-
|
|
31
|
+
### Requirements
|
|
32
|
+
|
|
33
|
+
- Node.js 22.19 or newer
|
|
34
|
+
- [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) installed and configured
|
|
35
|
+
- A modern browser
|
|
36
|
+
|
|
37
|
+
### Install into Pi
|
|
18
38
|
|
|
19
39
|
```bash
|
|
20
40
|
pi install npm:@firstpick/pi-package-webui
|
|
21
41
|
```
|
|
22
42
|
|
|
23
|
-
Restart Pi
|
|
43
|
+
Restart Pi, then run:
|
|
24
44
|
|
|
25
|
-
|
|
45
|
+
```text
|
|
46
|
+
/webui-start
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Open the printed address, usually <http://127.0.0.1:31415/>. The browser normally opens automatically.
|
|
26
50
|
|
|
27
|
-
|
|
51
|
+
Check the server at any time with:
|
|
28
52
|
|
|
29
53
|
```text
|
|
30
|
-
/webui-
|
|
54
|
+
/webui-status
|
|
55
|
+
/webui-status detailed
|
|
31
56
|
```
|
|
32
57
|
|
|
33
|
-
|
|
58
|
+
### Your first session
|
|
59
|
+
|
|
60
|
+
1. Start the Web UI with `/webui-start`.
|
|
61
|
+
2. Confirm the working directory in the footer or choose another project.
|
|
62
|
+
3. Select a model and thinking effort.
|
|
63
|
+
4. Enter a prompt, attach context if needed, and follow the live response.
|
|
64
|
+
5. Open the Control Deck for sessions, Git, app runners, themes, updates, and optional features. Under **Controls → Interface**, choose **Top bar** or **Sidebar** for terminal tabs, then choose **Right**, **Left**, or **Both** for the Control Deck. In **Sidebar**, **Both** is unavailable; choosing **Right** or **Left** swaps the Control Deck and terminal/tabs rails across the chat.
|
|
65
|
+
6. On desktop, drag the workspace-facing edge of any visible Control Deck—or the terminal/tabs rail in **Sidebar**—to choose a comfortable width. In **Both**, resize the left and right Control Decks independently; widths return on your next visit.
|
|
66
|
+
|
|
67
|
+
Open **Subagents** to follow agent runs launched by managed extensions or registered SDK, RPC, JSON, print, interactive, tmux, workflow, schedule, gate, and custom integrations. Runs linked to an open WebUI terminal stay in that terminal’s group; other registered runs appear under **External agents**. Each row shows its launch source and lifecycle, and only offers output or controls that its owner supports.
|
|
68
|
+
|
|
69
|
+
Independent Pi processes do not appear automatically. Start them through `pi-webui agent run`, attach a persisted session with `pi-webui agent attach`, or use a cooperating registration adapter. See [TECHNICAL.md](TECHNICAL.md#subagent-observability) for supported commands and limitations.
|
|
70
|
+
|
|
71
|
+
Useful shortcuts:
|
|
72
|
+
|
|
73
|
+
- `Ctrl/Cmd+K` opens the command palette.
|
|
74
|
+
- `Ctrl/Cmd+L` opens the model selector.
|
|
75
|
+
- `Ctrl/Cmd+F` searches the active file, transcript, or subagent output and highlights every match.
|
|
76
|
+
- `Alt+Enter` queues the composer as a follow-up.
|
|
77
|
+
- Hold `Esc` to abort active work.
|
|
78
|
+
- In the Control Deck, use `Alt+Up` / `Alt+Down` to reorder a section. In **Both**, use `Alt+Left` / `Alt+Right` to move it between sides.
|
|
79
|
+
|
|
80
|
+
## Feature gallery
|
|
81
|
+
|
|
82
|
+
Screenshots below show the v0.4.8 interface. Newer releases may contain additional controls while keeping the same core workflows.
|
|
83
|
+
|
|
84
|
+
### Sessions and workspace
|
|
85
|
+
|
|
86
|
+
#### Workspace dashboard
|
|
87
|
+
|
|
88
|
+

|
|
89
|
+
|
|
90
|
+
**Optional feature needed:** None — included in Pi Web UI core.
|
|
91
|
+
|
|
92
|
+
See the active project, model, context, Git state, queue, sessions, and common actions in one place.
|
|
93
|
+
|
|
94
|
+
#### Control panel
|
|
95
|
+
|
|
96
|
+

|
|
97
|
+
|
|
98
|
+
**Optional feature needed:** None — the control panel is included in Pi Web UI core. Companion-specific sections require their corresponding packages.
|
|
99
|
+
|
|
100
|
+
Manage the current session, workspace, model, theme, notifications, updates, usage, and optional packages. The **Controls** section keeps each setting on one compact name/value row; point to or focus a setting name for plain-language help.
|
|
101
|
+
|
|
102
|
+
#### Working-directory picker
|
|
103
|
+
|
|
104
|
+

|
|
105
|
+
|
|
106
|
+
**Optional feature needed:** None — included in Pi Web UI core.
|
|
107
|
+
|
|
108
|
+
Browse, search, save, or create project directories and open them in the active Pi tab.
|
|
109
|
+
|
|
110
|
+
#### Files panel
|
|
111
|
+
|
|
112
|
+
**Optional feature needed:** None — the Files panel is included in Pi Web UI core.
|
|
113
|
+
|
|
114
|
+
Browse and search the files of the active project, open them in the viewer, and use the row menu for file actions. In a Git repository, files and folders that Git ignores stay listed and fully usable, but appear greyed out so generated output such as `node_modules` or build folders is easy to tell apart. Point at a greyed row to see the “Ignored by Git” hint in its tooltip.
|
|
115
|
+
|
|
116
|
+
#### Queue manager
|
|
117
|
+
|
|
118
|
+

|
|
119
|
+
|
|
120
|
+
**Optional feature needed:** None — queues and prompt lists are included in Pi Web UI core.
|
|
121
|
+
|
|
122
|
+
Review follow-ups, steering messages, user-bash work, and prompt lists while a tab is busy.
|
|
123
|
+
|
|
124
|
+
### Models, tools, and skills
|
|
125
|
+
|
|
126
|
+
#### Thinking effort
|
|
127
|
+
|
|
128
|
+

|
|
129
|
+
|
|
130
|
+
**Optional feature needed:** None — included in Pi Web UI core.
|
|
131
|
+
|
|
132
|
+
Choose the supported reasoning effort before sending the next prompt.
|
|
133
|
+
|
|
134
|
+
#### Scoped models
|
|
135
|
+
|
|
136
|
+

|
|
137
|
+
|
|
138
|
+
**Optional feature needed:** None — included in Pi Web UI core.
|
|
139
|
+
|
|
140
|
+
Search available models and control project or global model scope and cycling order.
|
|
141
|
+
|
|
142
|
+
#### Tools setup
|
|
143
|
+
|
|
144
|
+

|
|
145
|
+
|
|
146
|
+
**Optional feature needed:** None — the browser tools setup is included in Pi Web UI core.
|
|
34
147
|
|
|
35
|
-
|
|
148
|
+
Enable tools for the current session or save the allowlist inherited by future sessions.
|
|
36
149
|
|
|
37
|
-
|
|
150
|
+
#### Skills setup
|
|
38
151
|
|
|
39
|
-
|
|
152
|
+

|
|
153
|
+
|
|
154
|
+
**Optional feature needed:** None — the browser skills setup is included in Pi Web UI core.
|
|
155
|
+
|
|
156
|
+
Find installed skills and manage session-specific or global activation.
|
|
157
|
+
|
|
158
|
+
### Project automation and Git
|
|
159
|
+
|
|
160
|
+
#### App runners
|
|
161
|
+
|
|
162
|
+

|
|
163
|
+
|
|
164
|
+
**Optional feature needed:** None — app runners are included in Pi Web UI core.
|
|
165
|
+
|
|
166
|
+
Launch detected development servers, tests, builds, scripts, and project-defined runners with pinned live output. ANSI colors are rendered safely, while progress written with carriage returns updates in place instead of filling the log with duplicate status lines.
|
|
167
|
+
|
|
168
|
+
#### Guided Git workflow
|
|
169
|
+
|
|
170
|
+

|
|
171
|
+
|
|
172
|
+
**Optional feature needed:** `@firstpick/pi-prompts-git-pr` for generated commit messages, branch names, and pull-request content. `@firstpick/pi-extension-aur-review` optionally adds the staged-review gate.
|
|
173
|
+
|
|
174
|
+
Move through review, staging, commit-message generation, commit, push, and pull-request steps with explicit confirmations.
|
|
175
|
+
|
|
176
|
+
#### Git branch picker
|
|
177
|
+
|
|
178
|
+

|
|
179
|
+
|
|
180
|
+
**Optional feature needed:** None — branch and worktree controls are included in Pi Web UI core.
|
|
181
|
+
|
|
182
|
+
Switch branches, create a branch, or create a parallel branch worktree for isolated work.
|
|
183
|
+
|
|
184
|
+
#### Git diff viewer
|
|
185
|
+
|
|
186
|
+

|
|
187
|
+
|
|
188
|
+
**Optional feature needed:** None — the Git status and diff viewer are included in Pi Web UI core.
|
|
189
|
+
|
|
190
|
+
Inspect staged, unstaged, untracked, and incoming changes before asking Pi to commit or publish them.
|
|
191
|
+
|
|
192
|
+
### Optional companions and usage
|
|
193
|
+
|
|
194
|
+
#### Optional features
|
|
195
|
+
|
|
196
|
+

|
|
197
|
+
|
|
198
|
+
**Optional feature needed:** None — the package manager panel is included in Pi Web UI core; each listed companion is installed separately.
|
|
199
|
+
|
|
200
|
+
Install, update, enable, disable, or configure supported companion packages from one panel.
|
|
201
|
+
|
|
202
|
+
#### `/btw` side questions
|
|
203
|
+
|
|
204
|
+

|
|
205
|
+
|
|
206
|
+
**Optional feature needed:** `@firstpick/pi-extension-btw`.
|
|
207
|
+
|
|
208
|
+
Ask a quick side question without derailing the main agent flow, then transfer useful context back when needed.
|
|
209
|
+
|
|
210
|
+
#### Codex usage
|
|
211
|
+
|
|
212
|
+

|
|
213
|
+
|
|
214
|
+
**Optional feature needed:** None for usage reporting — included in Pi Web UI core for supported Codex authentication. The Normal/Fast selector requires `@firstpick/pi-extension-codex-fast-mode`.
|
|
215
|
+
|
|
216
|
+
Monitor subscription usage windows and reset times for supported Codex models.
|
|
217
|
+
|
|
218
|
+
#### Pi stats
|
|
219
|
+
|
|
220
|
+

|
|
221
|
+
|
|
222
|
+
**Optional feature needed:** `@firstpick/pi-extension-stats`.
|
|
223
|
+
|
|
224
|
+
Explore token, cost, cache, model, session, and daily usage through the optional stats companion.
|
|
225
|
+
|
|
226
|
+
## Optional features
|
|
227
|
+
|
|
228
|
+
Open **Optional features** in the side panel to discover Web UI-aware companions. Configurable companions expose separate **Enable/Disable** and **Setup** actions, so configuration remains available without forcing a feature on.
|
|
229
|
+
|
|
230
|
+
Popular additions include:
|
|
231
|
+
|
|
232
|
+
- Remote Web UI for trusted-LAN access and PIN protection
|
|
233
|
+
- Pi stats and richer Git/footer status
|
|
234
|
+
- Natural Conversation Mode and voice controls
|
|
235
|
+
- `/btw` side questions
|
|
236
|
+
- Additional themes, release workflows, safety controls, and prompt tools
|
|
237
|
+
|
|
238
|
+
Optional companions are installed separately and remain governed by normal Pi package settings.
|
|
239
|
+
|
|
240
|
+
## Standalone launcher
|
|
241
|
+
|
|
242
|
+
You can start the browser UI without opening terminal Pi first:
|
|
40
243
|
|
|
41
244
|
```bash
|
|
42
245
|
npm install -g @firstpick/pi-package-webui
|
|
43
246
|
pi-webui
|
|
44
247
|
```
|
|
45
248
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
To create a parallel checkout, click the Git branch box in the footer and use **Create branch worktree**. After the worktree is created, the browser asks whether to open it in a separate Pi tab and switch there; choosing **Cancel** keeps the current tab active and leaves the new worktree available for later.
|
|
249
|
+
Choose a project immediately:
|
|
49
250
|
|
|
50
|
-
|
|
251
|
+
```bash
|
|
252
|
+
pi-webui --cwd ~/src/my-project
|
|
253
|
+
```
|
|
51
254
|
|
|
52
|
-
|
|
255
|
+
If you omit `--cwd`, the browser asks which project to open first.
|
|
53
256
|
|
|
54
257
|
## Keep it private
|
|
55
258
|
|
|
56
|
-
|
|
259
|
+
> [!WARNING]
|
|
260
|
+
> Pi Web UI can do anything the connected Pi session is allowed to do. It listens only on `127.0.0.1` by default. Do not expose it directly to an untrusted network.
|
|
261
|
+
|
|
262
|
+
Use the optional Remote Web UI package when you need trusted-LAN access and PIN protection. Treat that PIN as a convenience for a trusted network, not as hardened multi-user authentication.
|
|
57
263
|
|
|
58
264
|
## Technical details
|
|
59
265
|
|
|
60
|
-
|
|
266
|
+
Core updates use a persisted exact-target plan bound to a plan digest. The server verifies package ownership before mutation, supports npm-hoisted bundled Pi installs, and refuses plans with no accepted targets without entering the restart flow.
|
|
267
|
+
|
|
268
|
+
> **Before downgrading:** stop the Web UI and back up `~/.pi/webui/settings.json`. Older releases do not understand the two-sided Control Deck layout and can overwrite it. Re-upgrade before restoring the backup.
|
|
269
|
+
|
|
270
|
+
See [TECHNICAL.md](TECHNICAL.md) for complete commands, configuration, update and rollback behavior, session continuity, security, compatibility, mobile behavior, and troubleshooting.
|
|
271
|
+
|
|
272
|
+
Contributor-only architecture, API, and testing information lives in [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
@@ -8,15 +8,26 @@ import { readRuntimePointer } from "../lib/update/supervisor.mjs";
|
|
|
8
8
|
const bootstrapRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
|
|
9
9
|
const bootstrapServer = path.join(bootstrapRoot, "bin", "pi-webui.mjs");
|
|
10
10
|
const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(homedir(), ".pi", "agent");
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
});
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
11
|
+
|
|
12
|
+
if (process.argv[2] === "agent") {
|
|
13
|
+
try {
|
|
14
|
+
const { runAgentCli } = await import("../lib/agent-run-adapters.mjs");
|
|
15
|
+
process.exitCode = await runAgentCli(process.argv.slice(3), { agentDir });
|
|
16
|
+
} catch (error) {
|
|
17
|
+
console.error(`Pi Web UI agent command failed: ${error?.message || error}`);
|
|
18
|
+
process.exitCode = 1;
|
|
19
|
+
}
|
|
20
|
+
} else {
|
|
21
|
+
const pointer = await readRuntimePointer(agentDir, "current");
|
|
22
|
+
const serverEntry = pointer?.serverEntry || bootstrapServer;
|
|
23
|
+
const child = spawn(process.execPath, [serverEntry, ...process.argv.slice(2)], {
|
|
24
|
+
cwd: process.cwd(), env: process.env, stdio: "inherit", windowsHide: true,
|
|
25
|
+
});
|
|
26
|
+
child.once("error", (error) => { console.error(`Pi Web UI launcher failed: ${error.message || error}`); process.exitCode = 1; });
|
|
27
|
+
child.once("exit", (code, signal) => {
|
|
28
|
+
if (signal) {
|
|
29
|
+
try { process.kill(process.pid, signal); } catch { process.exitCode = 1; }
|
|
30
|
+
} else process.exitCode = code ?? 1;
|
|
31
|
+
});
|
|
32
|
+
for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => { try { child.kill(signal); } catch {} });
|
|
33
|
+
}
|