@firstpick/pi-package-webui 0.11.1 → 0.11.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/DEVELOPMENT.md +151 -12
- package/README.md +34 -6
- package/TECHNICAL.md +75 -8
- package/bin/pi-webui.mjs +5390 -11423
- package/index.ts +10 -3
- package/lib/component-update-state.mjs +2 -2
- package/lib/git-workflow-preference-values.mjs +122 -0
- package/lib/git-workflow-preferences.mjs +35 -563
- package/lib/package-updates.mjs +260 -0
- package/lib/rpc-supervisor-client.mjs +8 -4
- package/lib/server/app-runners.mjs +1667 -0
- package/lib/server/codex-fast-mode.mjs +161 -0
- package/lib/server/conversation-mode.mjs +218 -0
- package/lib/server/conversation-voice.mjs +318 -0
- package/lib/server/extension-ui-requests.mjs +114 -0
- package/lib/server/git-generation.mjs +459 -0
- package/lib/server/git-mutations.mjs +1827 -0
- package/lib/server/git-reads.mjs +608 -0
- package/lib/server/git-worktree-sessions.mjs +408 -0
- package/lib/server/helper-requests.mjs +82 -0
- package/lib/server/no-project-workspaces.mjs +103 -0
- package/lib/server/rpc-transports.mjs +394 -0
- package/lib/server/settings-store.mjs +544 -0
- package/lib/server/sse-delivery.mjs +138 -0
- package/lib/server/workspace-files.mjs +563 -0
- package/lib/update/supervisor.mjs +4 -0
- package/lib/webui-workspaces.mjs +2 -0
- package/package.json +4 -4
- package/public/activity-agents-controller.mjs +269 -0
- package/public/activity-events-controller.mjs +236 -0
- package/public/activity-intercom-controller.mjs +627 -0
- package/public/activity-queue-controller.mjs +534 -0
- package/public/activity-todo-view.mjs +89 -0
- package/public/activity-usage-controller.mjs +589 -0
- package/public/app.js +3761 -3886
- package/public/conversation-overview.css +84 -0
- package/public/conversation-overview.mjs +193 -0
- package/public/draft-conversations.mjs +135 -0
- package/public/focused-composer-controls.css +111 -0
- package/public/focused-composer-controls.mjs +143 -0
- package/public/focused-composer-disclosure.mjs +223 -0
- package/public/focused-shell-adapter.css +264 -0
- package/public/focused-shell-adapter.mjs +257 -0
- package/public/index.html +137 -80
- package/public/model-catalog-order.mjs +63 -0
- package/public/platform-event-stream.mjs +64 -0
- package/public/project-artifact-controller.mjs +218 -0
- package/public/project-file-viewer-controller.mjs +383 -0
- package/public/project-git-tools-controller.mjs +181 -0
- package/public/project-runners-controller.mjs +220 -0
- package/public/service-worker.js +52 -1
- package/public/session-attention-scheduler.mjs +182 -0
- package/public/session-composer-store.mjs +56 -0
- package/public/session-context.mjs +51 -0
- package/public/session-extension-requests.mjs +63 -0
- package/public/session-shelf-state.mjs +151 -0
- package/public/session-shelves.css +171 -0
- package/public/session-shelves.mjs +95 -0
- package/public/settings-navigation-controller.mjs +249 -0
- package/public/settings-navigation.css +61 -0
- package/public/settings-resource-controller.mjs +232 -0
- package/public/settings-workspace.css +19 -0
- package/public/settings-workspace.mjs +175 -0
- package/public/shell-actions.mjs +87 -0
- package/public/shell-attention-inbox.css +72 -0
- package/public/shell-attention-inbox.mjs +198 -0
- package/public/shell-context-actions.css +61 -0
- package/public/shell-context-actions.mjs +168 -0
- package/public/shell-inspector-resize.mjs +124 -0
- package/public/shell-navigation-resize.mjs +107 -0
- package/public/shell-navigation.mjs +127 -0
- package/public/shell-preferences.mjs +108 -0
- package/public/shell-surfaces.mjs +99 -0
- package/public/shell-tools-launcher.css +97 -0
- package/public/shell-tools-launcher.mjs +222 -0
- package/public/shell-view-host.mjs +115 -0
- package/public/shell-workspace.css +266 -0
- package/public/shell-workspace.mjs +402 -0
- package/public/sidebar-update-menu.css +190 -0
- package/public/sidebar-update-menu.mjs +512 -0
- package/public/styles.css +320 -169
- package/public/subagent-launch-slot-state.mjs +2 -2
- package/public/themed-selects.css +156 -0
- package/public/workspace-choices.mjs +104 -0
- package/tests/activity-agents-controller.test.mjs +652 -0
- package/tests/activity-events-controller.test.mjs +511 -0
- package/tests/app-runner-terminal-static.test.mjs +3 -3
- package/tests/append-system-http.test.mjs +7 -6
- package/tests/append-system-selector-static.test.mjs +6 -6
- package/tests/aur-review-widget-static.test.mjs +11 -3
- package/tests/boot-failure-diagnostics.test.mjs +8 -3
- package/tests/browser/activity-intercom-controller.spec.mjs +457 -0
- package/tests/browser/activity-navigation-integration.spec.mjs +45 -0
- package/tests/browser/activity-owner-integration.spec.mjs +201 -0
- package/tests/browser/activity-queue-controller.spec.mjs +405 -0
- package/tests/browser/activity-section-picker.spec.mjs +294 -0
- package/tests/browser/activity-todo-view.spec.mjs +60 -0
- package/tests/browser/activity-usage-controller.spec.mjs +416 -0
- package/tests/browser/compact-layout-integration.spec.mjs +58 -0
- package/tests/browser/composer-action-grid-reorder.spec.mjs +16 -0
- package/tests/browser/composer-disclosure.spec.mjs +389 -0
- package/tests/browser/composer-toolbar-polish.spec.mjs +343 -0
- package/tests/browser/control-deck-component-updates.spec.mjs +5 -14
- package/tests/browser/control-deck-side-panels.spec.mjs +27 -12
- package/tests/browser/control-visibility.spec.mjs +5 -0
- package/tests/browser/controls-layout.spec.mjs +21 -2
- package/tests/browser/conversation-overview.spec.mjs +251 -0
- package/tests/browser/draft-conversations.spec.mjs +276 -0
- package/tests/browser/empty-startup-fixture.mjs +135 -0
- package/tests/browser/empty-startup.spec.mjs +282 -0
- package/tests/browser/events-tree-context-menu.spec.mjs +1 -0
- package/tests/browser/focused-composer-more.spec.mjs +127 -0
- package/tests/browser/focused-model-shortcuts.spec.mjs +120 -0
- package/tests/browser/focused-navigation-fixture.mjs +32 -0
- package/tests/browser/focused-project-activity.spec.mjs +111 -0
- package/tests/browser/focused-shell-integration.spec.mjs +208 -0
- package/tests/browser/folder-picker-layout-fixture.mjs +13 -0
- package/tests/browser/folder-picker-layout.spec.mjs +302 -0
- package/tests/browser/footer-model-advanced-layout.spec.mjs +27 -14
- package/tests/browser/git-setup-cancel.spec.mjs +251 -0
- package/tests/browser/guided-git-fallback.spec.mjs +40 -21
- package/tests/browser/inspector-header.spec.mjs +221 -0
- package/tests/browser/inspector-overview-integration.spec.mjs +104 -0
- package/tests/browser/inspector-resize.spec.mjs +227 -0
- package/tests/browser/inspector-topic-overflow.spec.mjs +56 -0
- package/tests/browser/interaction-action-discovery.spec.mjs +332 -0
- package/tests/browser/interaction-attention-inbox.spec.mjs +364 -0
- package/tests/browser/interaction-attention-integration.spec.mjs +53 -0
- package/tests/browser/interaction-composer-controls.spec.mjs +267 -0
- package/tests/browser/interaction-composer-integration.spec.mjs +175 -0
- package/tests/browser/interaction-continuity.spec.mjs +50 -26
- package/tests/browser/interaction-model-picker.spec.mjs +86 -0
- package/tests/browser/last-terminal-close.spec.mjs +280 -0
- package/tests/browser/mobile-foundation.spec.mjs +172 -20
- package/tests/browser/model-catalog-groups.spec.mjs +104 -0
- package/tests/browser/more-row-menus.spec.mjs +258 -0
- package/tests/browser/new-tab-hit-target.spec.mjs +228 -0
- package/tests/browser/no-project-conversation.spec.mjs +113 -0
- package/tests/browser/optimistic-prompt.spec.mjs +3 -0
- package/tests/browser/overhaul-w7-accessibility.spec.mjs +227 -0
- package/tests/browser/overhaul-w7-capabilities.spec.mjs +298 -0
- package/tests/browser/overhaul-w7-companions.spec.mjs +290 -0
- package/tests/browser/overhaul-w7-focus-repairs.spec.mjs +210 -0
- package/tests/browser/overhaul-w7-layout-repairs.spec.mjs +183 -0
- package/tests/browser/overhaul-w7-parent-repairs.spec.mjs +97 -0
- package/tests/browser/overhaul-w7-pwa.spec.mjs +247 -0
- package/tests/browser/overhaul-w7-responsive.spec.mjs +450 -0
- package/tests/browser/overhaul-w7-update.spec.mjs +215 -0
- package/tests/browser/overhaul-w7-zoom.spec.mjs +243 -0
- package/tests/browser/overview-agent-ownership.spec.mjs +45 -0
- package/tests/browser/persistent-ui-layout.spec.mjs +3 -0
- package/tests/browser/project-artifact-controller.spec.mjs +324 -0
- package/tests/browser/project-artifact-integration.spec.mjs +103 -0
- package/tests/browser/project-file-buffer-integration.spec.mjs +230 -0
- package/tests/browser/project-git-tools-integration.spec.mjs +369 -0
- package/tests/browser/session-fixture.mjs +118 -0
- package/tests/browser/session-ownership.spec.mjs +175 -0
- package/tests/browser/session-shelves-integration.spec.mjs +219 -0
- package/tests/browser/session-shelves.spec.mjs +340 -0
- package/tests/browser/session-sidebar-resize.spec.mjs +138 -0
- package/tests/browser/session-summary.spec.mjs +17 -12
- package/tests/browser/settings-complete-home.spec.mjs +463 -0
- package/tests/browser/settings-entrypoint.spec.mjs +104 -0
- package/tests/browser/settings-navigation-controller.spec.mjs +383 -0
- package/tests/browser/settings-navigation-integration.spec.mjs +348 -0
- package/tests/browser/settings-resource-lifetime.spec.mjs +349 -0
- package/tests/browser/settings-workspace-integration.spec.mjs +132 -0
- package/tests/browser/shell-ownership.spec.mjs +398 -0
- package/tests/browser/shell-rollout-fixture.mjs +259 -0
- package/tests/browser/shell-rollout.spec.mjs +357 -0
- package/tests/browser/shell-tools-launcher.spec.mjs +260 -0
- package/tests/browser/shell-workspace.spec.mjs +433 -0
- package/tests/browser/side-panel-section-reorder.spec.mjs +3 -1
- package/tests/browser/sidebar-floating-tooltips.spec.mjs +37 -0
- package/tests/browser/sidebar-update-integration.spec.mjs +277 -0
- package/tests/browser/sidebar-update-menu.spec.mjs +402 -0
- package/tests/browser/sidebar-update-progress.spec.mjs +472 -0
- package/tests/browser/stream-output-isolation.spec.mjs +6 -3
- package/tests/browser/themed-selects.spec.mjs +297 -0
- package/tests/browser/thread-start-flow.spec.mjs +481 -0
- package/tests/browser/ui-polish-activity-controls.spec.mjs +177 -0
- package/tests/browser/ui-polish-features.spec.mjs +85 -0
- package/tests/browser/ui-polish-file-header.spec.mjs +43 -0
- package/tests/browser/ui-polish-local-git.spec.mjs +183 -0
- package/tests/browser/ui-polish-mobile-recovery.spec.mjs +36 -0
- package/tests/browser/ui-polish-navigation.spec.mjs +127 -0
- package/tests/browser/ui-polish-session-actions.spec.mjs +282 -0
- package/tests/browser/user-noticeable-fixes.spec.mjs +10 -3
- package/tests/browser/windows-drive-parent.spec.mjs +4 -2
- package/tests/browser/workspace-draft-selection.spec.mjs +266 -0
- package/tests/codex-fast-mode-static.test.mjs +16 -11
- package/tests/codex-speed-mode-browser-state.test.mjs +6 -3
- package/tests/codex-usage-source.test.mjs +4 -3
- package/tests/component-update-api-static.test.mjs +2 -2
- package/tests/composer-action-grid-reorder-static.test.mjs +3 -3
- package/tests/control-deck-component-updates-static.test.mjs +9 -4
- package/tests/control-visibility-static.test.mjs +3 -3
- package/tests/controls-layout-static.test.mjs +5 -5
- package/tests/conversation-overview-adapter.test.mjs +100 -0
- package/tests/document-artifact-static.test.mjs +2 -1
- package/tests/draft-conversations.test.mjs +205 -0
- package/tests/empty-startup-launcher.test.mjs +197 -0
- package/tests/events-tree-context-menu-static.test.mjs +22 -18
- package/tests/fake-pi-session-ownership.test.mjs +302 -0
- package/tests/fast-mode-client-static.test.mjs +1 -1
- package/tests/feature-decision-output-popup-static.test.mjs +2 -2
- package/tests/feature-system-prompt-optional-feature-static.test.mjs +1 -1
- package/tests/file-viewer-image-static.test.mjs +15 -11
- package/tests/file-viewer-search-static.test.mjs +5 -5
- package/tests/fixtures/fake-pi.mjs +41 -9
- package/tests/footer-provider-usage-visual-static.test.mjs +7 -6
- package/tests/foreground-transcript-catch-up-static.test.mjs +7 -4
- package/tests/git-footer-context-menu-static.test.mjs +1 -1
- package/tests/git-panel-file-preview-static.test.mjs +41 -48
- package/tests/git-panel-live-updates-static.test.mjs +2 -1
- package/tests/git-workflow-dispatch.test.mjs +66 -0
- package/tests/git-workflow-preferences.test.mjs +9 -1
- package/tests/guided-git-activation-static.test.mjs +14 -11
- package/tests/guided-git-fallback-ui-static.test.mjs +8 -5
- package/tests/guided-git-message-reliability-static.test.mjs +10 -6
- package/tests/guided-git-publication-backend-static.test.mjs +16 -11
- package/tests/http-endpoints-harness.test.mjs +21 -9
- package/tests/interaction-state-stability-static.test.mjs +4 -3
- package/tests/intercom-conversation-viewer-static.test.mjs +29 -17
- package/tests/intercom-tag-layout-static.test.mjs +13 -12
- package/tests/intercom-tag-overflow-layout.test.mjs +11 -10
- package/tests/main-output-loading-static.test.mjs +4 -4
- package/tests/middle-button-drag-scroll-static.test.mjs +3 -3
- package/tests/mobile-compact-layout.test.mjs +2 -2
- package/tests/mobile-continuity-tablet-static.test.mjs +3 -3
- package/tests/mobile-foundation-static.test.mjs +10 -7
- package/tests/mobile-phone-experience-static.test.mjs +3 -2
- package/tests/mobile-static.test.mjs +173 -135
- package/tests/model-catalog-order.test.mjs +103 -0
- package/tests/native-parity.test.mjs +6 -4
- package/tests/native-session-choice-owner.test.mjs +102 -0
- package/tests/native-update-lifecycle.test.mjs +10 -5
- package/tests/no-project-http-harness.test.mjs +328 -0
- package/tests/no-project-navigation.test.mjs +54 -0
- package/tests/no-project-workspaces.test.mjs +77 -0
- package/tests/open-issue-wizard-static.test.mjs +1 -1
- package/tests/optional-feature-migration-frontend.test.mjs +4 -4
- package/tests/optional-feature-prompt-impact-static.test.mjs +3 -3
- package/tests/package-updates.test.mjs +630 -0
- package/tests/persistent-ui-layout-static.test.mjs +3 -3
- package/tests/platform-event-stream.test.mjs +253 -0
- package/tests/project-file-viewer-controller.test.mjs +652 -0
- package/tests/project-git-tools-adapter.test.mjs +103 -0
- package/tests/project-git-tools-controller.test.mjs +577 -0
- package/tests/project-runners-controller.test.mjs +453 -0
- package/tests/prompt-input-vertical-scroll-static.test.mjs +3 -3
- package/tests/prompt-routing-input-clear-static.test.mjs +2 -2
- package/tests/questionnaire-dialog.test.mjs +6 -6
- package/tests/queue-edit-reorder-static.test.mjs +48 -51
- package/tests/rpc-supervisor-host.test.mjs +4 -1
- package/tests/safety-guard-auto-review-static.test.mjs +1 -1
- package/tests/sampling-native-controls-user-flow.test.mjs +7 -1
- package/tests/server-app-runners.test.mjs +536 -0
- package/tests/server-codex-fast-mode.test.mjs +346 -0
- package/tests/server-conversation-mode.test.mjs +386 -0
- package/tests/server-conversation-voice.test.mjs +426 -0
- package/tests/server-extension-ui-requests.test.mjs +357 -0
- package/tests/server-git-generation.test.mjs +558 -0
- package/tests/server-git-mutations.test.mjs +729 -0
- package/tests/server-git-reads.test.mjs +381 -0
- package/tests/server-git-worktree-sessions.test.mjs +502 -0
- package/tests/server-helper-requests.test.mjs +364 -0
- package/tests/server-rpc-transports.test.mjs +553 -0
- package/tests/server-settings-store.test.mjs +132 -0
- package/tests/server-shell-rollout.test.mjs +478 -0
- package/tests/server-sse-delivery.test.mjs +410 -0
- package/tests/server-workspace-files.test.mjs +546 -0
- package/tests/session-attention-scheduler.test.mjs +514 -0
- package/tests/session-composer-store.test.mjs +153 -0
- package/tests/session-context.test.mjs +134 -0
- package/tests/session-extension-requests.test.mjs +193 -0
- package/tests/session-ownership-adapter.test.mjs +130 -0
- package/tests/session-sampling-ui-static.test.mjs +10 -4
- package/tests/session-send-lifetime.test.mjs +140 -0
- package/tests/session-shelf-state.test.mjs +348 -0
- package/tests/session-shelves-adapter.test.mjs +79 -0
- package/tests/session-summary-lifetime.test.mjs +54 -0
- package/tests/settings-resource-controller.test.mjs +548 -0
- package/tests/shell-action-adapter.test.mjs +169 -0
- package/tests/shell-actions.test.mjs +182 -0
- package/tests/shell-navigation.test.mjs +348 -0
- package/tests/shell-preferences.test.mjs +367 -0
- package/tests/side-panel-section-height-removal-static.test.mjs +3 -3
- package/tests/stream-output-isolation-static.test.mjs +1 -1
- package/tests/subagent-gate-visibility.test.mjs +1 -1
- package/tests/subagent-launch-slot-state.test.mjs +2 -2
- package/tests/subagent-launch-slots-static.test.mjs +1 -1
- package/tests/subagent-observability-static.test.mjs +2 -2
- package/tests/subagent-reliability-integration.test.mjs +13 -30
- package/tests/syntax-highlighting-static.test.mjs +3 -3
- package/tests/tab-close-continuity-static.test.mjs +1 -1
- package/tests/tab-metadata-ordering.test.mjs +99 -0
- package/tests/terminal-cwd-grouping-static.test.mjs +2 -2
- package/tests/terminal-tab-prompt-tooltip-static.test.mjs +2 -0
- package/tests/terminal-tab-workspace-static.test.mjs +5 -4
- package/tests/terminal-tabs-resize-static.test.mjs +1 -1
- package/tests/theme-customizer-static.test.mjs +1 -1
- package/tests/thread-display-title.test.mjs +44 -0
- package/tests/update-api-harness.test.mjs +15 -14
- package/tests/update-tab-restore-harness.test.mjs +3 -0
- package/tests/webui-settings-locking.test.mjs +2 -2
- package/tests/windows-drive-cwd-picker-static.test.mjs +7 -9
- package/tests/workspace-choices.test.mjs +114 -0
- package/tests/workspace-save-load-static.test.mjs +7 -4
package/DEVELOPMENT.md
CHANGED
|
@@ -4,6 +4,72 @@ Contributor-only implementation, API, architecture, testing, and maintenance inf
|
|
|
4
4
|
|
|
5
5
|
[Back to README](README.md) · [Advanced user technical reference](TECHNICAL.md)
|
|
6
6
|
|
|
7
|
+
## Compact interaction controls
|
|
8
|
+
|
|
9
|
+
`focused-composer-controls.mjs` projects effective model/effort and busy submission state. `app.js` retains draft, attachment, request-ID and dispatch ownership. Busy normal submissions remain prompt requests with `streamingBehavior`; the UI does not replace that path with direct steer/follow-up calls. Classic controls remain in their original DOM homes.
|
|
10
|
+
|
|
11
|
+
`nativeSessionChoiceOwner` captures the session lifetime and native-dialog generation. It admits one request at a time and prevents late success/error handlers from changing a replacement session or dialog. Effort uses the server's pending-value response; model changes use the existing native RPC. These pickers do not persist global defaults.
|
|
12
|
+
|
|
13
|
+
`shell-context-actions.mjs` renders a bounded selection from the same records used by `shell-tools-launcher.mjs`. More actions changes the initial category without limiting full-catalog search. Native slash aliases share one focused entry, and old alias pins resolve to its canonical ID. Dispatch still recomputes target validity and availability.
|
|
14
|
+
|
|
15
|
+
`shell-attention-inbox.mjs` renders caller-owned snapshots without polling or changing seen state. The adapter moves canonical run controls into the foreground native dialog. The app validates the selected tab lifetime, folder and completion serial, then uses normal tab switching and blocking-request replay. It never constructs response payloads from metadata counts.
|
|
16
|
+
|
|
17
|
+
Run the `interaction-*` browser specs together with existing focused-shell, session-ownership, launcher and mobile coverage. `native-session-choice-owner.test.mjs` exercises deferred responses against the actual application function. Browser fixtures use disposable state and fake Pi; the busy-submission test records HTTP delivery metadata while holding a real fixture stream, because fake Pi does not implement upstream busy prompt delivery.
|
|
18
|
+
|
|
19
|
+
## No Project lifecycle and compact layout
|
|
20
|
+
|
|
21
|
+
`draft-conversations.mjs` owns versioned browser-only records under `pi-webui-draft-conversations-v1`. `draft:` IDs never enter server tab catalogs, RPC, SSE or restore payloads. The store validates records, rejects oversized writes without truncating memory, and preserves unreadable storage unchanged. Opening No Project selects a client blank; leaving nonempty text saves an Inbox entry. First submission creates a real tab and retires only the captured draft identity, preserving later edits and navigation. Failed dispatch recovers text into that real session. Per-page activation prevents duplicate submissions; durable creation idempotency after a lost response and reload is not provided by the existing endpoint.
|
|
22
|
+
|
|
23
|
+
`POST /api/tabs` accepts `{workspaceKind:"no-project"}` without a client cwd or session selector. `lib/server/no-project-workspaces.mjs` allocates a private exclusive UUID directory under the resolved agent root's `webui/no-project`, validates its canonical identity, and filters inherited session-selection and initial-input arguments before launch. Tab metadata carries `workspaceKind` and `noProjectId` alongside the physical cwd. Supervisor metadata, private restart handoffs and saved workspaces preserve those fields. Resume retains the original directory. Missing or mismatched owned directories fail validation; closing a tab never deletes its directory.
|
|
24
|
+
|
|
25
|
+
For No Project tabs, `/api/new-session` and exact `/new` return `data.nextTabId`, the fresh `data.tab`, all `data.tabs`, and `data.sourceTab`. The outer response tab remains the source request context. The frontend adopts the new tab only while that originating context is current. The source process, session, draft and files remain intact. Normal project resets retain their existing behavior. Concurrent resets, active work, compaction and natural-conversation admission remain guarded. These directories isolate working files, not shell permissions.
|
|
26
|
+
|
|
27
|
+
`shell-inspector-resize.mjs` reports committed widths through the shell callback; the app persists the existing browser-local `inspectorWidth`. Effective viewport clamping does not overwrite the saved value. Cancellation restores the pre-drag width, including Escape after focus moves. `focused-composer-disclosure.mjs` positions the original More tray and Options menu without taking over dispatch or visibility. Tooltip portals keep invisible legacy pseudo-elements from extending the tray. The overview uses natural card height and a two-column layout where needed; constrained windows scroll the whole card host instead of clipping its content.
|
|
28
|
+
|
|
29
|
+
The compact application hides its duplicate model/effort strip and retains the busy submission selector. Footer controls and options have stable focus keys across footer replacement. The effort picker focuses its selected value before falling back to the first enabled option. Classic and mobile retain their established settings controls.
|
|
30
|
+
|
|
31
|
+
Verification lives in `no-project-workspaces.test.mjs`, `no-project-http-harness.test.mjs`, `update-tab-restore-harness.test.mjs`, and the No Project, compact-layout, composer-disclosure, More, footer and inspector-resize browser specs. All use disposable state and fake Pi; they do not establish real-provider or Windows filesystem parity.
|
|
32
|
+
|
|
33
|
+
## Shell ownership
|
|
34
|
+
|
|
35
|
+
Classic and mobile adapters in `public/app.js` share five flat ES modules:
|
|
36
|
+
|
|
37
|
+
- `shell-actions.mjs` preserves palette matching and checks captured session/project targets before dispatch. Stable action IDs identify entries across catalog refreshes. The app rebuilds the catalog at execution. Captured session identity rejects same-tab replacements without changing stream ownership; successful New session replies invalidate actions before refreshed state arrives. Compact availability includes both authoritative busy state and locally pending requests. Existing handlers retain asynchronous guards and server authorization remains authoritative.
|
|
38
|
+
- `shell-navigation.mjs` owns the browser history listener and writes. Mobile navigation commits history before changing the rendered state, so a failed write leaves the current view intact. Unrelated history fields and URL parameters survive.
|
|
39
|
+
- `shell-preferences.mjs` reads the versioned browser preference without repairing unknown records. The pure effectiveShellPreferences resolver selects Focused only for an absent browser record and exact fresh server cohort; corrupt or unavailable storage stays Classic. Phone and tablet mode choices remain independent; `shell=classic` takes precedence. A valid explicit browser choice always wins, including when cohort metadata arrives after that choice. Pins use bounded printable catalog IDs; inspector navigation keeps its stricter ID grammar.
|
|
40
|
+
- `shell-view-host.mjs` moves canonical DOM nodes and restores their original homes, focus, selection and scroll. The app retains section visibility and disclosure attributes. Moving or restoring a view never owns its session, runner or stream lifetime.
|
|
41
|
+
- `shell-surfaces.mjs` owns one drawer keyboard listener and restores prior attributes. Native modal dialogs retain keyboard ownership. Replacing a drawer invalidates pending focus returns without closing feature resources.
|
|
42
|
+
|
|
43
|
+
The modules ship with the package and participate in the service-worker cache. Keep module imports, cache versions, browser entry URLs and pinned asset tests coherent. Node contracts cover action targets, preferences and history. `tests/browser/shell-ownership.spec.mjs` exercises real DOM ownership; `mobile-foundation.spec.mjs` checks app integration. These checks do not replace the overhaul plan's later parity and platform gates.
|
|
44
|
+
|
|
45
|
+
## Compact desktop integration
|
|
46
|
+
|
|
47
|
+
Project and Activity are inspector destination tabs. `shell-workspace.mjs` keeps their section selector in the inspector header and exposes a conversation-local overview slot. `conversation-overview.mjs` only renders keyed snapshots; `app.js` reads existing owners, validates tab/session/folder identity and dispatches canonical catalog actions. It introduces no transport or polling owner. `overviewOpen` is an optional boolean browser preference; Home and Settings temporarily hide the card. Closing the card never stops feature resources.
|
|
48
|
+
|
|
49
|
+
`themed-selects.css` uses native customizable-select support behind a CSS feature query. Options, disabled states, optgroups and change events remain browser-owned. Unsupported engines retain a themed native control. Shared styled tooltips use a manual popover when supported so clipped containers and native dialogs cannot cover them; the existing fixed portal remains the fallback. The scoped model picker records whether its opener was the footer or composer and resolves the current button after footer rerenders.
|
|
50
|
+
|
|
51
|
+
`focused-shell-adapter.mjs` places canonical views in `shell-workspace.mjs` and restores them with the shared view host. It moves the existing model/effort rows, footer administration controls and Abort/End buttons; feature controllers retain request targets and resource lifetimes independently of view placement. The original Control Deck visibility and order are retained for Classic. Desktop preview preferences never write the durable layout schema.
|
|
52
|
+
|
|
53
|
+
`shell-tools-launcher.mjs` renders caller-supplied action records, categories and pins in a native dialog. The app rebuilds the catalog and rechecks captured session/project targets before execution. Native modal ownership remains with the browser. History writes precede view changes and preserve unrelated state and URL identity.
|
|
54
|
+
|
|
55
|
+
`tests/browser/focused-shell-integration.spec.mjs` uses the shared disposable `session-fixture.mjs` to exercise actual drafts, controls, history, rollback, responsive mode transitions and Abort inside the launcher. Worker component fixtures cover layout and keyboard contracts; they do not establish whole-app parity. New files ship as flat assets and participate in the PWA cache.
|
|
56
|
+
|
|
57
|
+
### Session shelves
|
|
58
|
+
|
|
59
|
+
`session-shelf-state.mjs` owns bounded browser-local settlement and expansion under `pi-webui-session-shelves-v1`. The app supplies stable creation/session-file identity, completion serial, and activity with input taking priority over work. Complete metadata snapshots may prune closed IDs; rendering alone never prunes missing IDs. Reconciliation also runs outside the mounted sidebar. Settlement does not mark completion as seen or call any mutation route.
|
|
60
|
+
|
|
61
|
+
`session-shelves.mjs` owns stable headers and body slots. The app owns the rows and renders shelf-qualified group fragments while preserving canonical custom group IDs. Settle/Restore callbacks revalidate session lifetime and identity; group close uses only the fragment's tab IDs. The canonical tablist owns selection controls, separate from action buttons. Classic, top navigation, and mobile use the original list.
|
|
62
|
+
|
|
63
|
+
Run `node --test tests/session-shelf-state.test.mjs` and the Chromium `session-shelves.spec.mjs` and `session-shelves-integration.spec.mjs` scenarios for storage, activity wake, keyboard focus, draft continuity, grouped membership and layout fallback. All actual-app fixtures use fake Pi and isolated settings.
|
|
64
|
+
|
|
65
|
+
## Settings ownership
|
|
66
|
+
|
|
67
|
+
`settings-workspace.mjs` places the original settings groups in categorized pages through `shell-view-host.mjs`. `settings-navigation-controller.mjs` owns only search, result presentation and keyboard navigation. The app remains the sole history writer and action dispatcher. Settings URLs use the existing `view=settings` and `inspector=settings:<category>` fields plus an optional stable `setting` anchor; invalid entries are dropped and unknown categories recover to Appearance without applying preferences. Existing Theme focus opens its searchable picker. Classic restores original groups and disclosure state.
|
|
68
|
+
|
|
69
|
+
`settings-resource-controller.mjs` owns tools/skills resources, scope and exact provider/model selection. The app supplies existing HTTP calls and captured tab, session lifetime and native-dialog generation guards. Reads and writes retain their original scope; detached controls and late completions cannot target a replacement. Empty enabled lists and inheritance remain distinct. Companion availability comes from the existing catalog and package state; the Settings search index adds placement metadata, not a second package policy.
|
|
70
|
+
|
|
71
|
+
The actual-app `settings-navigation-integration.spec.mjs` and `settings-resource-lifetime.spec.mjs` use disposable servers and test canonical controls, history, drafts, retained selections and deferred HTTP boundaries. The existing `resource-profiles.spec.mjs` complements those intercepted race cases with server persistence checks. The navigator’s component fixtures cover keyboard and accessibility semantics. New modules and styles are included in the package and offline cache.
|
|
72
|
+
|
|
7
73
|
## Pi 1.2 theme compatibility
|
|
8
74
|
|
|
9
75
|
Bundled native theme JSON now uses `https://pi.dev/schemas/theme.schema.json`. Pi 1.2 rejects WebUI-only fields inside a native theme's `export` object at startup. The theme bundle publishes those fields separately in `webui-backgrounds.json`, outside its `pi.themes` directory. `readBundledThemes()` reads that optional file next to the themes directory and merges only `WEBUI_THEME_EXPORT_FIELDS` into catalog exports. Native export colors cannot be overridden by this metadata. Older bundles with inline background fields still load through the existing bundled-only compatibility path.
|
|
@@ -54,16 +120,43 @@ node tests/append-system-http.test.mjs
|
|
|
54
120
|
node tests/append-system-selector-static.test.mjs
|
|
55
121
|
```
|
|
56
122
|
|
|
123
|
+
## Shell rollout initialization
|
|
124
|
+
|
|
125
|
+
Immediately after CLI and startup-CWD validation, before service construction, registry initialization or restore reads, the server calls initializeWebuiShellRollout from the canonical settings store. Prior-use evidence includes the default settings root, legacy config root, XDG Web UI state, configured agent Web UI state and explicit fast-pick, optional-feature migration and restore paths. Only absence proven under the bounded sibling initialization lock can qualify a default root as fresh. Custom settings targets and ambiguous evidence cannot establish freshness. The existing settings lock and private atomic writer persist the raw-preserving version-1 shellRollout marker without changing settings schema 8, layout v3 or layout revisions. Generic settings reads never initialize the marker.
|
|
126
|
+
|
|
127
|
+
GET /api/interface-preferences adds only validated shellRolloutCohort metadata. The existing PUT allowlist rejects cohort and marker fields. Browser hydration is outside the layout revision/generation fences and performs no preference write; the original read status remains separate from the effective layout. Late metadata cannot override an explicit choice. Existing startup migration of missing durable layout fields remains independent. Recovery URLs and independent mobile modes retain precedence.
|
|
128
|
+
|
|
129
|
+
The initializer preserves valid markers, leaves invalid/future own markers untouched, migrates applicable legacy data before any marker-only write, and returns unknown after failed proof or persistence. A crash after root creation leaves conservative established state on the next startup. Unit fault/race tests live in server-shell-rollout.test.mjs; whole-app startup, browser hydration and platform acceptance remain separate gates.
|
|
130
|
+
|
|
57
131
|
## Web UI settings write lock
|
|
58
132
|
|
|
133
|
+
`lib/server/settings-store.mjs` owns generic normalization, migration, locking and atomic persistence. `lib/git-workflow-preference-values.mjs` owns pure Git preference values. The former `lib/git-workflow-preferences.mjs` path retains its Git read/write wrappers and re-exports the same store bindings, so mixed imports share one update queue. The server imports generic settings directly from the store. Storage paths, schema 8 and layout v3 remain unchanged.
|
|
134
|
+
|
|
59
135
|
`updateWebuiSettings` serializes same-process updates and uses per-writer records under `<settings-file>.lock` for cross-process writes. A process can exit after creating its record but before writing valid JSON, leaving an empty file. Lock acquisition removes incomplete records immediately when their PID is dead. It gives a live writer a one-second grace period, then removes records that are still empty or malformed so one interrupted write cannot block every later settings save.
|
|
60
136
|
|
|
61
137
|
Focused contributor validation:
|
|
62
138
|
|
|
63
139
|
```bash
|
|
140
|
+
node tests/server-settings-store.test.mjs
|
|
64
141
|
node tests/webui-settings-locking.test.mjs
|
|
65
142
|
```
|
|
66
143
|
|
|
144
|
+
## Backend service ownership
|
|
145
|
+
|
|
146
|
+
`lib/server/workspace-files.mjs` owns workspace containment, tree/search limits, file reads and mutations, strict AUR report reads, and editor selection. The entrypoint retains route authorization, body limits, requested-tab selection and error envelopes. A single factory receives the validated default directory and shared Git read functions.
|
|
147
|
+
|
|
148
|
+
`lib/server/git-reads.mjs` owns bounded Git reads, porcelain parsing, change/commit payloads and Files status/ignore decorations. Its read commands preserve optional-lock suppression and output bounds; mutations and watcher ownership remain separate. Both services retain their previous payloads and error behavior. Focused contracts live in `server-workspace-files.test.mjs` and `server-git-reads.test.mjs`; the HTTP harness and Project browser scenarios verify their integration.
|
|
149
|
+
|
|
150
|
+
`lib/server/app-runners.mjs` owns runner detection, configuration, process execution, stdin, output and context transfer. Its one service instance keeps caches while each real tab retains its run record and timers. HTTP guards and tab/working-directory/shutdown call sites remain in the entrypoint. The service uses the existing process-tree and terminal-reducer modules; hiding a view does not stop a runner. `server-app-runners.test.mjs` covers disposable processes, and `app-runner-process-tree-harness.test.mjs` checks lifecycle integration.
|
|
151
|
+
|
|
152
|
+
`lib/server/git-mutations.mjs` owns staged-content approval hashing, Git/gh command serialization and mutation payloads. `git-worktree-sessions.mjs` owns worktree/session handoffs, staged transfer and live-tab removal refusals. `git-generation.mjs` owns generation reservations, artifact readiness, fallback settlement and replay. The entrypoint awaits each extracted workflow mutation inside its existing error-envelope boundary. Both generation and command cancellation run before their results are combined. The original tab records and explicit RPC event order remain authoritative.
|
|
153
|
+
|
|
154
|
+
`conversation-mode.mjs`, `conversation-voice.mjs` and `codex-fast-mode.mjs` adapt the existing companion command/status contracts. The server retains route authentication, originating-tab selection and body limits. Voice keeps consent checks, provider bounds and command-only shared Piper configuration writes; speed changes require the extension's confirmed status.
|
|
155
|
+
|
|
156
|
+
`rpc-transports.mjs` supplies one stable direct/supervised class pair. `sse-delivery.mjs` owns bounded writes, backpressure and output-mode barriers on the original client records. `helper-requests.mjs` owns correlated helper acknowledgments on real tab maps, and `extension-ui-requests.mjs` owns blocking approval tracking/replay/cancellation with original request IDs. Factories create no processes or listeners until used. Supervisor discovery, replay reconciliation, update admission, shutdown policy, HTTP routing and the explicit event pipeline remain in their existing owners. The upstream helper's resource/subagent hooks are unchanged.
|
|
157
|
+
|
|
158
|
+
The `server-*.test.mjs` suites verify these service contracts. `git-workflow-dispatch.test.mjs` covers asynchronous mutation error envelopes and cancellation ordering. The HTTP, staged-content, durable-supervisor, transport-hardening and SSE-backpressure harnesses verify the composed server. Extraction changes no storage path, wire protocol or browser asset revision.
|
|
159
|
+
|
|
67
160
|
## File viewer image contract
|
|
68
161
|
|
|
69
162
|
`GET /api/files/content` keeps workspace-path confinement and the shared 2 MiB `FILE_VIEWER_MAX_BYTES` cap before reading either text or images. Text responses use `kind: "text"` with UTF-8 `content` and `language`. The explicit extension allowlist maps `.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`, and `.avif` to fixed MIME types; those responses use `kind: "image"`, `mimeType`, and base64 `data` without decoding the bytes as UTF-8. SVG and all unlisted binary formats continue to return `415` through the text/binary guard.
|
|
@@ -178,13 +271,23 @@ The separate `WS3 paced cadence and slow-renderer queue pressure remain bounded`
|
|
|
178
271
|
|
|
179
272
|
`tests/stream-markdown-tail.test.mjs` reference semantics are the authoritative specification of the streaming boundary behavior going forward, anchored by the browser exact-output hash gate.
|
|
180
273
|
|
|
274
|
+
## Project and Activity ownership
|
|
275
|
+
|
|
276
|
+
The app composes flat native modules around the existing HTTP/SSE contracts. Project controllers own file buffers and guarded requests (`project-file-viewer-controller.mjs`), Git tool cache and mutations (`project-git-tools-controller.mjs`), runner data and stdin drafts (`project-runners-controller.mjs`), and the canonical document viewer (`project-artifact-controller.mjs`). Targets capture tab ID, session lifetime and working directory before asynchronous work. Navigation never owns process shutdown.
|
|
277
|
+
|
|
278
|
+
Activity modules own queue presentation and mutation tokens, Agents overview/polling/cancellation selection, Intercom summaries/detail, Events history/filter/unread state, and provider usage refresh/render timers. The queue snapshot cache remains in the app; its controller reads and writes through callbacks. The todo view is a pure parser/renderer with expansion stored by the parent. Agent terminal projections and explicit cancellation remain separate owners.
|
|
279
|
+
|
|
280
|
+
Focused widget placement moves original nodes to their domain host. Hidden heavy widgets retain their nodes and state without full reconstruction; revealing a topic renders current data. Classic restoration rebuilds all applicable widgets at their original home. Lightweight runner output patches may update retained nodes while hidden. Provider visibility suppresses DOM ticks without changing refresh ownership.
|
|
281
|
+
|
|
282
|
+
Actual-app scenarios in `activity-owner-integration.spec.mjs`, `focused-project-activity.spec.mjs`, and the Project integration specs cover canonical navigation, dirty buffers, original request identities, queue mutations, runner continuity and explicit agent cancellation. Controller fixtures cover stale completions, conflict snapshots, disposal and locks. Source-shape tests follow extracted owners rather than retaining duplicate implementations in the app.
|
|
283
|
+
|
|
181
284
|
## Intercom conversation projection and viewer
|
|
182
285
|
|
|
183
286
|
`GET /api/intercom/conversations?tab=<tab-id>` projects bounded summaries from `SessionManager.getBranch()` for the selected server-owned session. Adding `conversation=<opaque-id>` returns one sanitized detail. Browser values never select a session path. The pure projector in `lib/intercom-conversations.mjs` accepts only structured generic Intercom records and matched native supervisor request/reply records, deduplicates protocol identities, excludes synthetic relays and attachments, and applies conversation/message/text/response bounds before serialization.
|
|
184
287
|
|
|
185
288
|
`lib/intercom-transcript-filter.mjs` is the separate normal-transcript boundary. Before HTTP delta slicing, it removes structured `intercom_message` records, generic `intercom` tool-call parts, and results paired by explicit call ID or tool name. It copies only changed mixed assistant records and preserves unrelated meaningful content without mutating the RPC response. Live stream and execution guards in `public/app.js` prevent an Intercom card or event-log line from flashing before the filtered authoritative refresh; unrelated supervisor and tool activity keeps the existing path. The conversation endpoint still reads raw active-branch records independently.
|
|
186
289
|
|
|
187
|
-
`public/
|
|
290
|
+
`public/activity-intercom-controller.mjs` owns in-memory per-tab summaries and the single detail selection. Summary requests use captured tab generation and session lifetime; detail requests add a separate serial plus a five-second open-dialog refresh. Activity Conversations and the composer tags open the same native dialog. Switching tabs or closing the native dialog invalidates pending detail responses and cancels its timer. The renderer rebuilds message bubbles only from normalized `direction`, participant name/ID, text, and timestamp fields, assigning text with safe DOM APIs. It never renders server records wholesale. The footer tag group uses a reversed inline strip capped at 50 percent of the desktop prompt row, so the newest conversation starts at the right edge and older tags extend toward the middle. Direct tags are capped at 13rem. A `ResizeObserver` measures complete tag widths and reserves space for `+X`; tags that do not fit move into a bounded popup above the composer. Narrow layouts give the strip the full row and keep 44-pixel targets in the popup. Escape, outside clicks, and focus changes close the popup. Each reused direct or popup button stores a compact label/count signature, so unchanged tags retain their children instead of retriggering the polite live region.
|
|
188
291
|
|
|
189
292
|
### Tagged local-model thinking
|
|
190
293
|
|
|
@@ -293,7 +396,7 @@ Run focused validation with `node --check public/app.js`, the static tests above
|
|
|
293
396
|
|
|
294
397
|
The native update API has two single-target planning requests, `{ "targets": ["pi"] }` and `{ "targets": ["webui"] }`. `POST /api/update/plan` returns an immutable plan with `transactionId`, `digest`, `requested`, `active`, `pathPi`, `context`, `targets`, `refusals` and `warning`. `pathPi` records the independently proven PATH driver's version, package root, executable and CLI, or eligibility/guidance when unproven. Each target carries `id`, `installedRoot`, `effectRoot`, `beforeVersion`, and an absolute `command` with argument array. `POST /api/update/apply` accepts only `{ transactionId, planDigest }` and returns `202` with a running job ID. It revalidates the bound context before launch. No release version or command originates in the browser. `GET /api/update/transactions/<id>` returns phase, bounded per-command receipts, verified targets, outcome and error; a missing completion receipt cannot establish success. A shared private state root fences affected work across server processes. The detached runner writes per-command receipts after native child close, and finalization selectively restarts only verified healthy changed active components after idle. Neither process exit alone nor an exit code alone certifies a healthy installation.
|
|
295
398
|
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`. Schema v3 adds `controlVisibility.hiddenIds`: `null` means package defaults, `[]` means explicit show-all, and a bounded sorted string list stores hidden stable catalog IDs while retaining unknown future IDs. The browser applies those IDs through a preference-only CSS class and never mutates capability-owned `hidden` state. The `terminalTabs` layout record owns tab placement, custom groups, and the bounded desktop `sidebarWidth`; the client journals those subfields independently so resizing cannot overwrite concurrent group or placement changes. 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.
|
|
296
|
-
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**,
|
|
399
|
+
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**, `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.
|
|
297
400
|
- Use `/webui-status detailed`, `GET /api/health`, or `GET /api/webui-status?detailed=1` for diagnostics. Public supervisor diagnostics are limited to enabled/attached state and managed-tab count; private credentials and paths are intentionally omitted. A browser warning about incomplete buffered output means authoritative tabs/state/messages were requested, not that missing live deltas were reconstructed.
|
|
298
401
|
- Use the side-panel **Stop** action or localhost-only `POST /api/shutdown` for an explicit full stop. Explicit tab close terminates only that managed Pi child; explicit shutdown and `SIGINT` terminate the scope's managed Pi children. Do not use restart/update when the intent is to terminate active work.
|
|
299
402
|
- Normal authenticated shutdown removes the private scope state. Do not manually delete runtime files, sockets, pipes, journals, or PID records while managed tabs may be live. For cleanup, explicitly shut down first, verify the Web UI/scope has no managed tabs, and let normal startup clean stale empty state; removing private state for a live supervisor destroys the safe attachment path and can risk duplicate processes.
|
|
@@ -305,7 +408,7 @@ Compact mode keeps live output lightweight, coalesces sustained live DOM/scroll
|
|
|
305
408
|
- `PI_VOICE_TTS_PROVIDER=openai` selects hosted OpenAI TTS when no request provider is supplied; set `OPENAI_API_KEY` server-side.
|
|
306
409
|
- `PI_VOICE_GROQ_STT_MODEL`, `PI_VOICE_OPENAI_STT_MODEL`, `PI_VOICE_OPENAI_TTS_MODEL`, `PI_VOICE_OPENAI_TTS_VOICE`, `PI_VOICE_OPENAI_TTS_FORMAT`, `PI_VOICE_TTS_VOICE`, and `PI_VOICE_TTS_FORMAT` tune fallback models/voices/formats.
|
|
307
410
|
- `PI_VOICE_PROVIDER_TIMEOUT_MS` controls outbound fallback-provider timeout. API keys are never sent from the browser; remote/LAN raw-audio STT uploads must include explicit per-request microphone-streaming consent.
|
|
308
|
-
-
|
|
411
|
+
- Default `pi-webui` and `/webui-start` startup: without explicit `--cwd`, managed tabs, or restore descriptors, the server starts with zero tabs and no Pi child. The browser shows an empty No Project conversation. Its first nonempty submission creates an owned No Project tab before dispatching the captured input. Explicit project startup and session restoration retain precedence.
|
|
309
412
|
- Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, activity state, per-tab settings, and a workspace dashboard for common actions.
|
|
310
413
|
- The Subagents side panel includes a separate **Agent models** editor above the live monitor. It stores WebUI-owned launch slots for the eight builtin roles (`context-builder`, `delegate`, `oracle`, `planner`, `researcher`, `reviewer`, `scout`, and `worker`): every role keeps a non-removable base slot, while added same-role slots copy a model/thinking draft but retain independent stable IDs. Choose **User default** or **This project**; projects inherit user defaults until saved, and **Use user defaults** removes a project override. Select `Default / inherit` to inherit both values, or an active-tab provider-qualified model and its supported thinking levels. Saves are revision-checked and localhost-only; the helper loads one immutable assignment snapshot after **Reload active tab**, never changes running children, and uses a `tool_call` hook to fill omitted model fields on `subagent` and `subagent_gate` launches. Explicit non-reviewer models remain unchanged; explicit reviewer mismatches block unless a matching bounded deviation permit is admitted. `workflowScript` receives an idempotent local `runs` adapter that applies role defaults and reviewer admission to `runs.run` and `runs.all` child params at execution time without parsing call sites. The configuration form has independent load/draft/error state, so its controls are not reset by live subagent monitoring.
|
|
311
414
|
- 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; a model-less `pi-subagents` workflow controller becomes a collapsible run header with its child-agent rows nested beneath it and excluded from agent counts. 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.
|
|
@@ -329,9 +432,9 @@ Compact mode keeps live output lightweight, coalesces sustained live DOM/scroll
|
|
|
329
432
|
- 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. Stream chunks pass through a terminal-line reducer: LF/CRLF commit scrollback, bare CR replaces the current live line, backspace edits that line, and ANSI sequences remain intact for the browser's safe SGR renderer. This is line-oriented terminal behavior rather than a full VT100 cursor grid. 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.
|
|
330
433
|
- Extension-launched 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. `/git-guided-workflow` emits a transient tab-scoped activation request that the browser validates and consumes before generic status rendering; the browser requires the extension-owned native generation commands and has no prompt-only launch fallback. The HTTP server authoritatively rejects the exact command admission while the tab is streaming, compacting, has pending messages, or already has a pending Guided Git launch, bypassing generic compaction queueing. A browser-generated UUID is stored in one short-lived server record and added only to the trusted live event envelope; the canonical four-field extension payload remains unchanged, and only the browser holding the matching one-shot permit can consume the event. 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.
|
|
331
434
|
- 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.
|
|
332
|
-
- Localhost-only
|
|
435
|
+
- Localhost-only update choices for Pi, WebUI, or Pi and extensions plus WebUI. Installation detection selects fixed commands; preview tokens bind confirmation to server-held commands. Results report command exits and request a manual restart.
|
|
333
436
|
- Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, which can ask Pi to create or update a LEARNING.
|
|
334
|
-
- Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay for ordinary server restart.
|
|
437
|
+
- Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay for ordinary server restart. Package updates show progress and command results for the lifetime of the server process.
|
|
335
438
|
Web UI keeps a packaged parity matrix at `lib/WEBUI_TUI_NATIVE_PARITY.json` and exposes it at `GET /api/native-parity`.
|
|
336
439
|
Discovery-path rules: at most 24 paths and direct children only (no recursive walk). Shell discovery supports `.sh`, `.bash`, `.zsh`, `.fish`, and matching extensionless shebang files. Python discovery supports `.py` and extensionless Python-shebang files, exposing `uv run` and/or the available `python3`/`python` interpreter. Required interpreters must be installed locally; duplicates and built-in overlaps do not duplicate menu entries. Absolute, drive/UNC, `..`, null-byte, missing, non-directory, or symlinked-outside-the-project paths are rejected. Stale or invalid stored paths surface diagnostics in the dialog instead of being scanned. `POST /api/app-runner-config` accepts either `{ "runner": { ... } }` or `{ "searchPaths": [...] }` (not both in one request) and preserves the other field.
|
|
337
440
|
|
|
@@ -373,7 +476,7 @@ Focused checks are `node tests/session-tree-event-targets.test.mjs`, `node tests
|
|
|
373
476
|
- 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.
|
|
374
477
|
- 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.
|
|
375
478
|
- `GET /api/git-workflow/staged-content?tab=<tabId>` for the read-only bounded staged-content hash used by Guided Git approval binding.
|
|
376
|
-
- `GET /api/update-status`, localhost-only `POST /api/update/plan`, `POST /api/update/apply`, and `GET /api/update/transactions/<transactionId>` for
|
|
479
|
+
- `GET /api/update-status`, localhost-only `POST /api/update/plan`, `POST /api/update/apply`, and `GET /api/update/transactions/<transactionId>` for fixed command previews, token-bound apply, and in-memory command results. The retired rollback route returns `410 Gone`; native package changes cannot be undone by switching a pointer. Legacy `POST /api/update` and `POST /api/component-update` mutation return `410 Gone`.
|
|
377
480
|
- `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.
|
|
378
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.
|
|
379
482
|
When enabled, each click obtains a fresh Turnstile token and UUID-v4, then posts only `{ schemaVersion, idempotencyKey, turnstileToken, issue }` to `POST /v1/submissions`. `issue` is the selected structured wizard state (`categoryId`, `componentId`, `templateId`, `summary`, and declared fields); editable canonical title/body, repository, labels, verdicts, callback URLs, and credentials are never sent. The returned status capability remains only in an opaque in-memory refresh handle for the open dialog. Nothing in this flow uses `localStorage`, `sessionStorage`, cookies, or draft persistence.
|
|
@@ -461,9 +564,13 @@ The extension launches its JavaScript bootstrap with the current Node executable
|
|
|
461
564
|
|
|
462
565
|
### Native Pi and Web UI updates
|
|
463
566
|
|
|
464
|
-
The
|
|
567
|
+
The sidebar menu and existing component buttons share `POST /api/update/plan`, `POST /api/update/apply` and `GET /api/update/transactions/<id>`. A plan accepts exactly one fixed target: `all`, `webui` or `pi`. Selecting an update scope requests the server-generated plan and immediately applies its validated ID and token, without a confirmation dialog. It never sends an arbitrary command. Normal localhost authorization and request validation still apply.
|
|
568
|
+
|
|
569
|
+
The package-update service detects installed WebUI manifests under the global npm root and the Pi agent npm directory. Commands are fixed argument arrays. It runs `pi update --all`, which also covers the Pi-managed copy, followed by an update of any separate global WebUI copy. It does not run version/capability probes, ownership checks, idle admission, context fingerprints, effect locks, health probes or automatic restarts. One job runs per server, with bounded execution and output; receipts report command exit results. Native lifecycle scripts are not sandboxed. Job state belongs to the current server process, so reconnect can recover it but a process restart does not preserve a new job's history.
|
|
570
|
+
|
|
571
|
+
Job snapshots include current-step bounded/redacted output, start timestamps, total and completed step counts. The browser displays these through a persistent update card and labels its elapsed-time heuristic as estimated progress. It never reaches 100 while a command runs or converts an error into completion. Explicit successful Pi/npm no-change summaries produce unchanged receipts; all-unchanged jobs omit restart guidance. Unknown output remains ordinary command success, with no additional version probes. Details shows the same job’s command results and returns to its progress card without opening scope selection. Terminal summaries avoid repeating logs; an unchanged compact card omits output, timing and the completion bar. Read-only installation guidance is derived from failed receipts, not a new preflight check.
|
|
465
572
|
|
|
466
|
-
|
|
573
|
+
The older native-update modules and their standalone tests remain for historical recovery compatibility. Their executable/context digests, physical-root exclusion, detached runner, verification and selective-restart contracts do not govern new menu jobs. Existing journal files are not deleted or replayed by the new path.
|
|
467
574
|
|
|
468
575
|
The launcher can migrate legacy `current.json` and `previous.json` pointers only to a canonical compatible equal-or-newer installed candidate after an isolated real startup and restored-tab probe. A subsequent candidate upgrade must pass the same probe and advances the accepted version floor atomically without replacing the original pointer backups. Both pointers receive immutable backups; old files and runtimes remain for fallback. An incompatible, unhealthy or older candidate retains legacy startup and needs manual attention. This migration is not native-update rollback. Ordinary tab restoration still uses the retained restart descriptor. Startup retries transient `EADDRINUSE` with bounded backoff.
|
|
469
576
|
|
|
@@ -582,7 +689,7 @@ Continuity is scoped to the resolved private Pi agent/config root and Web UI por
|
|
|
582
689
|
|
|
583
690
|
Updates preserve already-running supervised Pi processes, so an active tab continues with the Pi/runtime code it already loaded. Newly created or explicitly reloaded tabs use the newly installed versions. Additive supervisor protocol-minor changes are compatible; a protocol-major mismatch with live children fails closed instead of replacing the supervisor or spawning duplicates. Roll forward to a compatible Web UI rather than killing a healthy supervisor that owns active work.
|
|
584
691
|
|
|
585
|
-
Continuity deliberately excludes app runners: restart
|
|
692
|
+
Continuity deliberately excludes app runners: server restart stops their process trees, and they must be started again after reconnection. Package update commands do not restart the server automatically. It also does not preserve browser drafts, SSE connections, arbitrary extension memory, or an active request across supervisor failure, OS reboot, power loss, or machine restart. Session files can still restore durable transcript history after those failures, but they cannot resume the same in-flight model request.
|
|
586
693
|
|
|
587
694
|
### Compact live output mode
|
|
588
695
|
|
|
@@ -957,7 +1064,7 @@ Keep this browser configuration disabled until the gateway's exact-origin CORS p
|
|
|
957
1064
|
- `--host 0.0.0.0` also exposes the Web UI to the local network; pass `--remote-auth` to start with PIN auth already enabled.
|
|
958
1065
|
- 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.
|
|
959
1066
|
- Remote PIN auth is a simple trusted-LAN HTTP gate, not hardened multi-user authentication; do not expose it to untrusted networks.
|
|
960
|
-
- The Web UI update endpoint is restricted to localhost, because it runs package update commands
|
|
1067
|
+
- The Web UI update endpoint is restricted to localhost, because it runs package update commands.
|
|
961
1068
|
- Treat Pi Web UI as a local companion, not a hardened multi-user web service.
|
|
962
1069
|
|
|
963
1070
|
## Troubleshooting
|
|
@@ -969,9 +1076,9 @@ Keep this browser configuration disabled until the gateway's exact-origin CORS p
|
|
|
969
1076
|
- **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.
|
|
970
1077
|
- **PWA install or notifications are unavailable:** use `localhost` or HTTPS; browser support varies on LAN HTTP URLs.
|
|
971
1078
|
|
|
972
|
-
##
|
|
1079
|
+
## Legacy native update workflow
|
|
973
1080
|
|
|
974
|
-
|
|
1081
|
+
The following diagram and command table document the retained legacy journal/runner code. New menu actions use the simpler package-update service described above and do not enter this flow. This diagram describes the former native-command update flow. Durable job discovery keeps the original target and receipts through reconnects; confirmed PATH Pi details remain separate from the active session runtime. The [compact workspace implementation record](docs/overhaul/implementation-record.md) records the current integration checks. Browser coverage includes target confirmation, partial/unknown outcomes, PWA recovery and reconnect continuity; it uses disposable state and simulated updates rather than installing packages.
|
|
975
1082
|
|
|
976
1083
|
```mermaid
|
|
977
1084
|
flowchart TD
|
|
@@ -1064,3 +1171,35 @@ Restarting only the Web UI normally keeps managed Pi tabs, working directories,
|
|
|
1064
1171
|
## Settings and private data
|
|
1065
1172
|
|
|
1066
1173
|
Web UI settings are stored under `~/.pi/webui/` by default. Private runtime state, update records, authentication data, and supervisor details are not exposed to browsers. Do not delete private runtime files while managed tabs are still active.
|
|
1174
|
+
|
|
1175
|
+
|
|
1176
|
+
### Session owners during the compact workspace migration
|
|
1177
|
+
|
|
1178
|
+
The browser uses flat native modules for session identity, composer state, attention reconciliation, EventSource lifetime and extension request queuing. Their adapter contract is maintained in [the overhaul capability ledger](docs/overhaul/capability-ledger.md#w2-ownership-under-integration). HTTP/SSE shapes, supervisor ownership and settings storage are unchanged.
|
|
1179
|
+
|
|
1180
|
+
A captured tab context becomes stale when that tab replaces its session, as well as when the active tab changes. Replacement clears conversation projections, reconnects the single stream and schedules authoritative refresh. It preserves drafts, attachment objects and project editor buffers. Scoped GET deduplication cannot share a request across context generations. Extension responses continue to use the originating tab and request ID. Per-tab lifetime captures protect prompt preparation, completion and dialog responders across replacement without cancelling valid source-tab sends during navigation. Replacement retires old dialogs locally; successful sends release only their captured attachment objects.
|
|
1181
|
+
|
|
1182
|
+
The attention owner reconciles multiple idle tabs every ten seconds to discover later blockers. It forwards an AbortSignal through metadata fetches, limits each scheduled request to ten seconds, defers open group menus and backs off failures. Ordinary bootstrap and explicit user refreshes remain separate; their result serial protects against older responses. Authoritative tab mutation responses advance that serial as well, so an old poll cannot restore a closed tab or erase a newly created one.
|
|
1183
|
+
|
|
1184
|
+
Focused ownership checks are the `session-*.test.mjs`, `platform-event-stream.test.mjs` and `shell-action-adapter.test.mjs` tests. Browser adoption uses the opt-in `FAKE_PI_SESSION_OWNERSHIP=1` fixture; this is a test-only switch and makes no provider calls. The complete package check and separate Chromium tests remain integration gates.
|
|
1185
|
+
|
|
1186
|
+
## Compact control integration
|
|
1187
|
+
|
|
1188
|
+
`model-catalog-order.mjs` groups model catalog records without changing their identities or the saved scoped-model order. Only explicit `releaseDate` and `release_date` values establish chronology; invalid or absent dates use display-name/ID sorting. The grouped native selector retains origin-session guards and keyboard selection.
|
|
1189
|
+
|
|
1190
|
+
`settings-workspace.mjs` indexes configuration destinations and hosts canonical controls. Sampling and Codex speed reads on Settings entry must not mutate settings. Sampling, runner, summary and Git-footer dialogs retain their session/project target through asynchronous work. Footer context actions share the captured command target without requiring the Settings dialog to be open.
|
|
1191
|
+
|
|
1192
|
+
The compact composer permits vertical focus recovery in short windows and contains horizontal overflow within its action row. The minimized workflow pair occupies two action cells. `shell-navigation-resize.mjs` owns pointer capture, active-drag Escape handling and effective width bounds; only changed user widths are persisted. Viewport clamping must not overwrite the preferred width.
|
|
1193
|
+
|
|
1194
|
+
Coverage includes `composer-toolbar-polish.spec.mjs`, `settings-complete-home.spec.mjs`, `model-catalog-groups.spec.mjs` and `session-sidebar-resize.spec.mjs`. Run these with the package's Chromium browser configuration and isolated test state.
|
|
1195
|
+
|
|
1196
|
+
### Deferred workspace selection
|
|
1197
|
+
|
|
1198
|
+
Browser draft records retain optional `cwd` in the existing version-1 envelope. It is bounded to 4096 UTF-16 code units and rejects NUL; absent or empty values keep No Project behavior. The empty-screen workspace picker captures its originating draft identity, and first-send promotion captures cwd alongside text/revision. Selection cannot reassign a promoted draft or create a Pi child early.
|
|
1199
|
+
|
|
1200
|
+
The shared path-fast-pick and directory-creation routes allow absent tab context only when there are zero tabs and no explicit tab identifier. Explicit unknown identifiers still fail, and real-tab Natural Conversation guards retain their existing behavior. `tests/browser/workspace-draft-selection.spec.mjs` covers these route contracts and browser draft selection/promotion races.
|
|
1201
|
+
|
|
1202
|
+
|
|
1203
|
+
### Thread start flow
|
|
1204
|
+
|
|
1205
|
+
`public/workspace-choices.mjs` is the pure list builder for the New thread palette and the draft folder dropdown (`tests/workspace-choices.test.mjs`). `tests/browser/thread-start-flow.spec.mjs` covers palette and dropdown choices with zero `POST /api/tabs`, first-prompt creation in the chosen folder, a dropdown change during a pending first send, keyboard navigation and Branch worktree. `#newTabButton` keeps its ID for existing hooks; the old `+ Tab` menu items are gone.
|
package/README.md
CHANGED
|
@@ -17,16 +17,18 @@ Pi Web UI keeps the normal Pi agent experience while giving you more room to man
|
|
|
17
17
|
|
|
18
18
|
| Area | Highlights |
|
|
19
19
|
| --- | --- |
|
|
20
|
-
| **Sessions and workspaces** |
|
|
20
|
+
| **Sessions and workspaces** | Start a No Project conversation in its own folder, run several isolated Pi sessions, resume prior work in a new terminal without replacing the current one, switch projects, save unfinished No Project conversations as browser drafts, preserve per-tab drafts, add another tab directly from the tab strip, and create branch worktrees. Organize the compact sidebar into Inbox, Working, and Settled. |
|
|
21
21
|
| **Live agent work** | Follow streaming Markdown with syntax highlighting for code blocks, grouped consecutive thinking, tool output, queues, todo progress, managed agent runs, and direct agent-to-agent conversations without leaving the browser. |
|
|
22
22
|
| **Models and controls** | Change models and thinking effort, check Codex CLI subscription usage, manage scoped models, configure tools and skills, and use the command palette. |
|
|
23
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
24
|
| **Git workflows** | Inspect changes, switch branches, review diffs, stage work, generate commit messages with an optional one-shot fallback model, push, and prepare pull requests through guided steps. |
|
|
25
|
-
| **Project utilities** |
|
|
25
|
+
| **Project utilities** | Inspect Project and Activity from one right panel, open a floating session overview, launch detected app runners, manage working directories, search files and transcripts, and customize themes. |
|
|
26
26
|
| **Companion features** | Add stats, remote access, voice, `/btw`, richer Git status, themes, release tools, and other supported Pi packages. |
|
|
27
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
28
|
| **Customizable controls** | Hide optional workspace, Control Deck, composer, workflow, attachment, and input-tag controls while keeping Send available. |
|
|
29
29
|
|
|
30
|
+
In the compact layout, use **Inspector** in the conversation header to open Project or Activity. Use **Overview** for a floating summary of the current session and its work.
|
|
31
|
+
|
|
30
32
|
## Quick start
|
|
31
33
|
|
|
32
34
|
### Requirements
|
|
@@ -49,6 +51,8 @@ Restart Pi, then run:
|
|
|
49
51
|
|
|
50
52
|
Open the printed address, usually <http://127.0.0.1:31415/>. The browser normally opens automatically.
|
|
51
53
|
|
|
54
|
+
A fresh start shows **No Project** with no active session. Send your first message to start a conversation in its own folder, or choose a project. To start in a specific folder immediately, use `/webui-start --cwd /path/to/project`.
|
|
55
|
+
|
|
52
56
|
Check the server at any time with:
|
|
53
57
|
|
|
54
58
|
```text
|
|
@@ -56,14 +60,36 @@ Check the server at any time with:
|
|
|
56
60
|
/webui-status detailed
|
|
57
61
|
```
|
|
58
62
|
|
|
63
|
+
### Choose your desktop layout
|
|
64
|
+
|
|
65
|
+
Fresh installations start with the compact desktop layout when the Web UI can confirm there is no earlier Web UI state. Existing installations keep Classic until you choose **Controls → Interface → Desktop layout → Compact preview**. Use **Inspector** in the header for Project and Activity, and the lower-left rail for **Attention**, **All tools**, and **Settings**. All tools searches commands and panels; pin frequent actions there. The footer's **Model** and **Effort** controls open their pickers. **All tools → /model** opens the full model catalog; **Model shortcuts** opens your saved scoped models. In Settings, search or choose a category to open the original control or Setup dialog.
|
|
66
|
+
|
|
67
|
+
Press **Pi** at the top left, or press the **New thread** (pencil) button and choose **No project**, to open an empty conversation. Its thread and folder are created when you send the first message. If you type and switch away, your text appears as a **Draft** in Inbox. Reopen it to continue, or close it to discard the text. Drafts cannot be settled. Existing sessions stay open; resuming one reuses its folder. From the empty screen, **Open workspace** or a recent folder chooses where your first prompt will run without opening a terminal. A saved Draft keeps both its text and selected folder.
|
|
68
|
+
|
|
69
|
+
The **New thread** button opens a searchable folder list: the current folder, No project, pinned and recent folders, **Browse…** and **Branch worktree…**. Picking a folder opens an empty draft there; nothing starts until your first prompt. On the empty screen, click the **Workspace** value to switch the draft's folder from the same list. Branch worktree still creates its thread right away.
|
|
70
|
+
|
|
71
|
+
In the folder picker, **Pinned folders** appears above **Current location**, and **Create a folder** appears above the folder list. Both sections start expanded and can be collapsed.
|
|
72
|
+
|
|
73
|
+
The compact left sidebar keeps idle, finished, and input-waiting sessions in **Inbox**, with active work in **Working**. Choose **Settle** (✓) on a finished session to move it into **Settled**, collapsed by default. Expand it and choose **Restore** (↥) to bring a session back. New work or a request for input brings it back automatically. Settling does not close the session.
|
|
74
|
+
|
|
75
|
+
In the compact layout, **Ctrl/Cmd+K** opens the same **All tools** search. Session and Project menus offer a short list of actions; **More actions** opens the full catalog. The **Attention** button separates decisions waiting for you, running sessions, and finished work. Select a decision to open its session's response dialog.
|
|
76
|
+
|
|
77
|
+
Drag the right edge of the compact session sidebar or the left edge of the inspector to resize it. Open Settings with the gear beside Home at the bottom left.
|
|
78
|
+
|
|
79
|
+
Select the model or effort in the footer to open its picker. The full model catalog groups models by provider, then sorts dated models newest first and undated models alphabetically. A choice applies to that session without a separate Apply button. While Pi is working, **During this run** chooses whether the single submission button steers the run or queues your message afterward. Enter follows that choice; Abort remains separate.
|
|
80
|
+
|
|
81
|
+
**Project** groups Files, Changes, Runners, Releases, and Documents. **Activity** groups Agents, Queues, Progress, Conversations, Events, and provider usage. Use the inspector header to choose a section without scrolling sideways. Open a section when you need it; changing views keeps running work and unsaved drafts. A queue count beside the draft opens pending follow-ups for editing and reordering.
|
|
82
|
+
|
|
83
|
+
Choose **Classic** in Settings to return. Your open sessions, drafts, and saved Classic arrangement remain available. Phone and tablet modes have separate preferences.
|
|
84
|
+
|
|
59
85
|
### Your first session
|
|
60
86
|
|
|
61
87
|
1. Start the Web UI with `/webui-start`.
|
|
62
88
|
2. Confirm the working directory in the footer or choose another project. You can paste or type a full path in the picker; on Windows, use a rooted drive path such as `C:/` or `D:/project`. From a drive root, choose **Parent** to open **This PC** and select another available drive.
|
|
63
89
|
3. Select a model and thinking effort.
|
|
64
90
|
4. Enter a prompt, attach context if needed, and follow the live response. The prompt grows to a bounded height, then scrolls vertically so every line stays reachable.
|
|
65
|
-
5.
|
|
66
|
-
6.
|
|
91
|
+
5. In the compact layout, use **Project**, **Activity**, **Settings**, or **All tools**. In Classic, open the Control Deck for sessions, Git, app runners, themes, updates, and optional features. Under **Controls → Interface**, choose **Top bar** or **Sidebar** for threads, 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.
|
|
92
|
+
6. In Classic 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.
|
|
67
93
|
|
|
68
94
|
The completed response replaces the live draft, including thinking the provider corrects or removes. On older Pi releases, tool arguments may appear only after the tool is identified, so Intercom content stays out of the main transcript.
|
|
69
95
|
|
|
@@ -83,6 +109,8 @@ Independent Pi processes do not appear automatically. Start them through `pi-web
|
|
|
83
109
|
|
|
84
110
|
When agents exchange direct Intercom messages or use native subagent-supervisor coordination, one compact tag per conversation appears beneath the composer. The tags start at the right edge and extend toward the middle, using up to half of the prompt width. Each tag has a bounded width. If they do not fit, WebUI keeps complete tags visible and replaces the rest with a **+X** tag. Select **+X** to open the remaining conversations above the composer. Long names still shorten with an ellipsis when one name exceeds the available space, while the full name remains available to assistive technology and on hover. Select a conversation to open a read-only chat view showing the two agent names or IDs and their messages. Generic Intercom transport calls and received Intercom records stay out of the main agent-output transcript, while attachments, tool output, and reasoning remain excluded from the chat view.
|
|
85
111
|
|
|
112
|
+
If preview navigation gets in your way, add `?shell=classic` to the Web UI address to return to the standard layout without resetting your preferences. See [the technical reference](TECHNICAL.md) for the surrounding layout options.
|
|
113
|
+
|
|
86
114
|
Useful shortcuts:
|
|
87
115
|
|
|
88
116
|
- `Ctrl/Cmd+K` opens the command palette.
|
|
@@ -291,7 +319,7 @@ Choose a project immediately:
|
|
|
291
319
|
pi-webui --cwd ~/src/my-project
|
|
292
320
|
```
|
|
293
321
|
|
|
294
|
-
|
|
322
|
+
Without `--cwd`, a fresh start opens **No Project** with no active session. Type your first message to create a conversation in its own folder, or choose a project. Previously running or explicitly restored sessions remain available.
|
|
295
323
|
|
|
296
324
|
## Keep it private
|
|
297
325
|
|
|
@@ -302,7 +330,7 @@ Use the optional Remote Web UI package when you need trusted-LAN access and PIN
|
|
|
302
330
|
|
|
303
331
|
## Technical details
|
|
304
332
|
|
|
305
|
-
|
|
333
|
+
Use the **Updates** button beside Settings to update **Pi and extensions + WebUI**, **WebUI only**, or **Pi only**. WebUI checks its Pi-managed and global npm installation locations and uses the matching update command. Selecting a scope starts the update immediately. A progress card shows the current step, elapsed time, and an estimated percentage while commands run. It says **Already up to date** when the commands explicitly report no changes. Open **Details** for command results, then **Back to progress** while running or **Back to result** when finished. Otherwise, restart WebUI after a successful update to load the updated code. Updates can only be started from localhost. Package scripts run under your existing configuration, and package updates cannot be automatically rolled back.
|
|
306
334
|
|
|
307
335
|
> **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.
|
|
308
336
|
|