@firstpick/pi-package-webui 0.2.3 → 0.2.4

package/README.md

@@ -117,18 +117,34 @@ Environment variables:
 ## Main features
 
 - Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, and activity state.
+- Automatic tab naming from the first prompt, with `--name <name>` still available for an explicit initial tab name.
 - Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, and abort controls.
-- Prompt composer with uploads, drag/drop/paste, inline image support, slash-command autocomplete, and `@` file/path references.
+- Prompt composer with uploads, drag/drop/paste, inline image support, slash-command autocomplete, and `@` file/path references with live suggestions.
 - Browser dialogs for common Pi selectors such as `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/resume`, `/tree`, `/scoped-models`, `/tools`, and `/skills`.
 - Model, thinking, session, workspace, theme, optional-feature, Codex usage, network, event, and notification controls in the side panel.
-- Per-tab cwd changes, a clickable footer cwd picker, saved path fast picks, and restart-safe restoration of open tabs.
-- Browser support for Pi extension UI prompts, widgets, status updates, and notifications.
-- Feedback reactions (`👍`, `👎`, `?`) on assistant output and action cards, which can ask Pi to create or update a LEARNING.
+- Side-panel theme picker backed by optional `@firstpick/pi-themes-bundle` themes when loaded.
+- Per-tab cwd changes, a clickable footer cwd picker, saved path fast picks, server-persisted fast picks, and restart-safe restoration of open tabs.
+- Browser support for Pi extension UI prompts, widgets, status updates, browser notifications when a tab needs an extension UI response and an optional side-panel toggle for agent-done notifications.
+- Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, which can ask Pi to create or update a LEARNING.
 - Mobile-friendly layout and PWA install support where the browser allows it.
 
-## Optional companion features
+Useful browser endpoints exposed by the local server include:
 
-A normal Pi/npm install includes the optional companion packages unless optional dependencies are disabled. If a feature is missing, the side panel shows it as install-needed. Installing from the side panel is localhost-only, limited to known packages, and requires reloading the active Pi tab after installation.
+- `GET /api/path-suggestions?tab=<tabId>&query=<path>` for `@` file/path references with live suggestions.
+- `POST /api/action-feedback?tab=<tabId>` for feedback on final assistant output and action cards.
+- `POST /api/optional-feature-install` for installing known optional companion packages from the side panel.
+
+For local development, run the checkout helper directly, for example:
+
+```bash
+./start-webui.sh --dev --cwd /path/to/project
+```
+
+## Optional companion packages
+
+A normal Pi/npm install includes the optional companion packages unless optional dependencies are disabled. Startup checks loaded Pi capabilities directly through RPC-visible commands and live widget events, then the side panel shows each optional feature as enabled, disabled, or install-needed. Installing a missing feature is an explicit, warned action; it is localhost-only, limited to known packages, and requires reloading the active Pi tab after installation.
+
+When the standalone global `pi-webui` launcher is used, optional companion installs should target the Pi agent npm root instead of the global npm prefix. Override the target explicitly with `PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT=/path/to/package-root` when needed.
 
 Optional companions:
 
@@ -157,7 +173,7 @@ This requires `/git-staged-msg` from `@firstpick/pi-prompts-git-pr`. Review the
 ## Mobile and PWA notes
 
 - The mobile composer starts as a compact `Ask Pi…` input and grows as you type.
-- Installable PWA support and notifications depend on browser support and usually require `localhost` or HTTPS.
+- Installable PWA support, blocked-tab browser notifications, and optional agent-done notifications require browser service-worker/notification support and usually require `localhost` or HTTPS.
 - Plain `http://<LAN-IP>` can show the app, but some browsers disable PWA install and notifications there.
 
 ## Network safety

package/bin/pi-webui.mjs

@@ -17,6 +17,7 @@ const packageRoot = path.resolve(__dirname, "..");
 const publicDir = path.join(packageRoot, "public");
 const webuiHelperExtensionPath = path.join(packageRoot, "webui-rpc-helper.mjs");
 const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(homedir(), ".pi", "agent");
+const OPTIONAL_FEATURE_INSTALL_ROOT_ENV = "PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT";
 const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
 const nativeParityMatrix = JSON.parse(await readFile(path.join(packageRoot, "WEBUI_TUI_NATIVE_PARITY.json"), "utf8"));
 const webuiDevServer = isTruthyEnv(process.env.PI_WEBUI_DEV) || isSourceCheckout(packageRoot);
@@ -40,6 +41,7 @@ const ATTACHMENT_UPLOAD_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 const INLINE_IMAGE_MAX_BYTES = 8 * 1024 * 1024;
 const INLINE_IMAGE_TOTAL_MAX_BYTES = 16 * 1024 * 1024;
 const RPC_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const EVENT_HISTORY_LIMIT = 200;
 const EXTENSION_UI_BLOCKING_METHODS = new Set(["select", "confirm", "input", "editor"]);
 const STATUS_RPC_TIMEOUT_MS = 1_800;
@@ -768,14 +770,51 @@ function runCommand(command, args, { cwd, timeoutMs = 2000, maxOutputLength = 20
   });
 }
 
-function optionalDependencyInstallRoot() {
-  const parts = packageRoot.split(path.sep);
+function nodeModulesParentForPackageRoot(root = packageRoot) {
+  const parts = root.split(path.sep);
   const nodeModulesIndex = parts.lastIndexOf("node_modules");
   if (nodeModulesIndex >= 0) {
-    const root = parts.slice(0, nodeModulesIndex).join(path.sep);
-    return root || path.parse(packageRoot).root;
+    const parent = parts.slice(0, nodeModulesIndex).join(path.sep);
+    return parent || path.parse(root).root;
   }
-  return packageRoot;
+  return root;
+}
+
+function declaredDependencySpec(pkg, packageName) {
+  return firstDefined(
+    pkg?.dependencies?.[packageName],
+    pkg?.optionalDependencies?.[packageName],
+    pkg?.devDependencies?.[packageName],
+    pkg?.peerDependencies?.[packageName],
+  );
+}
+
+async function installRootDeclaresPackage(root, packageName) {
+  const pkg = await readJsonFileIfExists(path.join(root, "package.json"));
+  return declaredDependencySpec(pkg, packageName) !== undefined;
+}
+
+function configuredAgentNpmRoot() {
+  const root = process.env.PI_CODING_AGENT_DIR ? path.resolve(expandUserPath(process.env.PI_CODING_AGENT_DIR)) : agentDir;
+  return path.join(root, "npm");
+}
+
+async function optionalDependencyInstallRoot() {
+  const configuredRoot = process.env[OPTIONAL_FEATURE_INSTALL_ROOT_ENV];
+  if (configuredRoot) return path.resolve(expandUserPath(configuredRoot));
+
+  const installRoot = nodeModulesParentForPackageRoot(packageRoot);
+  if (await installRootDeclaresPackage(installRoot, "@firstpick/pi-package-webui")) return installRoot;
+
+  const agentNpmRoot = configuredAgentNpmRoot();
+  if (installRoot !== agentNpmRoot && await installRootDeclaresPackage(agentNpmRoot, "@firstpick/pi-package-webui")) return agentNpmRoot;
+
+  if (webuiDevServer) return installRoot;
+
+  throw makeHttpError(
+    500,
+    `Could not determine a safe optional feature install root. Set ${OPTIONAL_FEATURE_INSTALL_ROOT_ENV} to the Pi package root.`,
+  );
 }
 
 function formatCommandForDisplay(command, args) {
@@ -786,7 +825,7 @@ async function installOptionalFeaturePackage(featureId) {
   const packageName = OPTIONAL_FEATURE_PACKAGES.get(featureId);
   if (!packageName) throw makeHttpError(400, `Unknown optional feature: ${featureId}`);
 
-  const installRoot = optionalDependencyInstallRoot();
+  const installRoot = await optionalDependencyInstallRoot();
   const npmCommand = process.env.PI_WEBUI_NPM_BIN || "npm";
   const args = ["install", "--prefix", installRoot, packageName];
   const result = await runCommand(npmCommand, args, {
@@ -1958,7 +1997,7 @@ function commandFromPost(pathname, body) {
     }
     case "/api/thinking": {
       const level = String(body.level || "").trim();
-      if (!["off", "minimal", "low", "medium", "high", "xhigh"].includes(level)) {
+      if (!THINKING_LEVELS.includes(level)) {
         throw new Error("Invalid thinking level");
       }
       return { type: "set_thinking_level", level };
@@ -2121,10 +2160,21 @@ function rememberTabState(tab, state) {
   if (!options.noSession && Object.prototype.hasOwnProperty.call(state, "sessionFile")) tab.sessionFile = sessionFileFromState(state);
 }
 
+function stateWithPendingThinking(tab, state) {
+  if (!state || typeof state !== "object" || !tab?.pendingThinkingLevel) return state;
+  return { ...state, pendingThinkingLevel: tab.pendingThinkingLevel };
+}
+
+function responseWithPendingThinking(tab, response) {
+  if (!response || typeof response !== "object" || response.success === false || response.command !== "get_state") return response;
+  return { ...response, data: stateWithPendingThinking(tab, response.data) };
+}
+
 function forgetTabState(tab) {
   if (!tab) return;
   tab.lastState = null;
   tab.sessionFile = undefined;
+  tab.pendingThinkingLevel = undefined;
 }
 
 function tabRestorableSessionFile(tab) {
@@ -2481,6 +2531,7 @@ async function createTab({ id: requestedId, index, title, titleSource, conversat
     createdAt,
     sessionFile: options.noSession ? undefined : normalizedRestoreString(sessionFile, 4096),
     lastState: null,
+    pendingThinkingLevel: undefined,
     activity: createTabActivity(createdAt),
     pendingExtensionUiRequests: new Map(),
     webuiHelperRequests: new Map(),
@@ -2523,6 +2574,7 @@ function tabMeta(tab) {
     conversationStarted: !!tab.conversationStarted,
     cwd: tab.cwd,
     sessionFile: tabRestorableSessionFile(tab),
+    pendingThinkingLevel: tab.pendingThinkingLevel || null,
     createdAt: tab.createdAt,
     startedAt: tab.rpc.startedAt,
     pid: tab.rpc.child?.pid,
@@ -2767,10 +2819,10 @@ function fallbackRpcResponse(tab, command, error) {
 
 async function safeRpcResponse(tab, command, timeoutMs = REQUEST_TIMEOUT_MS) {
   try {
-    return await tab.rpc.send(command, timeoutMs);
+    return responseWithPendingThinking(tab, await tab.rpc.send(command, timeoutMs));
   } catch (error) {
     const message = sanitizeError(error);
-    if (/Pi RPC process is not running/i.test(message)) return fallbackRpcResponse(tab, command, error);
+    if (/Pi RPC process is not running/i.test(message)) return responseWithPendingThinking(tab, fallbackRpcResponse(tab, command, error));
     throw error;
   }
 }
@@ -3732,12 +3784,38 @@ async function safeRpcData(tab, command, timeoutMs = STATUS_RPC_TIMEOUT_MS) {
     const response = await tab.rpc.send(command, timeoutMs);
     if (response?.success === false) return { ok: false, error: response.error || `${command.type} failed` };
     if (command?.type === "get_state") rememberTabState(tab, response?.data);
-    return { ok: true, data: response?.data ?? null };
+    return { ok: true, data: command?.type === "get_state" ? stateWithPendingThinking(tab, response?.data) : response?.data ?? null };
   } catch (error) {
     return { ok: false, error: sanitizeError(error) };
   }
 }
 
+function stateIsBusyForSettings(state) {
+  return !!(state?.isStreaming || state?.isCompacting);
+}
+
+async function setThinkingLevelForTab(tab, level, { allowPending = true } = {}) {
+  if (!THINKING_LEVELS.includes(level)) throw makeHttpError(400, "Invalid thinking level");
+  const stateResult = allowPending ? await safeRpcData(tab, { type: "get_state" }, STATUS_RPC_TIMEOUT_MS) : { ok: false };
+  if (allowPending && stateResult.ok && stateIsBusyForSettings(stateResult.data)) {
+    tab.pendingThinkingLevel = level;
+    return rpcSuccess("set_thinking_level", { level, pending: true, message: `Thinking level ${level} will apply to the next prompt.` });
+  }
+  const response = await tab.rpc.send({ type: "set_thinking_level", level });
+  if (response.success !== false) tab.pendingThinkingLevel = undefined;
+  return response;
+}
+
+async function applyPendingThinkingBeforePrompt(tab) {
+  const level = tab?.pendingThinkingLevel;
+  if (!level) return null;
+  const stateResult = await safeRpcData(tab, { type: "get_state" }, STATUS_RPC_TIMEOUT_MS);
+  if (stateResult.ok && stateIsBusyForSettings(stateResult.data)) return null;
+  const response = await setThinkingLevelForTab(tab, level, { allowPending: false });
+  if (response.success === false) return response;
+  return { ...response, pendingApplied: true };
+}
+
 function providerList(models) {
   const providers = new Set();
   for (const model of Array.isArray(models) ? models : []) {
@@ -4132,6 +4210,11 @@ const server = createServer(async (req, res) => {
         return;
       }
       const command = commandFromPost(url.pathname, body);
+      const pendingThinkingResponse = await applyPendingThinkingBeforePrompt(tab);
+      if (pendingThinkingResponse?.success === false) {
+        sendJson(res, 400, responseWithTab(pendingThinkingResponse, tab));
+        return;
+      }
       const startsVisibleWork = commandStartsVisibleWork(command);
       if (startsVisibleWork) {
         maybeNameTabForConversation(tab, command);
@@ -4194,7 +4277,11 @@ const server = createServer(async (req, res) => {
           maybeNameTabForConversation(tab, command);
           markTabWorking(tab);
         }
-        const response = command.type === "bash" ? await sendQueuedBashCommand(tab, command) : await tab.rpc.send(command);
+        const response = command.type === "set_thinking_level"
+          ? await setThinkingLevelForTab(tab, command.level)
+          : command.type === "bash"
+            ? await sendQueuedBashCommand(tab, command)
+            : await tab.rpc.send(command);
         if (response.success === false && startsVisibleWork) markTabIdle(tab);
         if (response.success !== false && command.type === "new_session") {
           tab.conversationStarted = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-package-webui",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Pi Web UI companion package with a local browser UI CLI plus /webui-start and /webui-status commands.",
   "license": "MIT",
   "type": "module",

package/public/app.js

@@ -3982,10 +3982,15 @@ function renderStatus() {
   const compacting = state?.isCompacting ? " · compacting" : "";
 
   elements.stateDetails.replaceChildren();
+  const pendingThinkingLevel = state?.pendingThinkingLevel || null;
+  const shownThinkingLevel = pendingThinkingLevel || state?.thinkingLevel;
+  const thinkingDetail = pendingThinkingLevel && pendingThinkingLevel !== state?.thinkingLevel
+    ? `${state?.thinkingLevel || "unknown"} → ${pendingThinkingLevel} next prompt`
+    : state?.thinkingLevel || "unknown";
   const details = {
     Status: `${running}${compacting}`,
     Model: modelLabel(state?.model),
-    Thinking: state?.thinkingLevel || "unknown",
+    Thinking: thinkingDetail,
     Session: state?.sessionName || state?.sessionId || "unknown",
     File: state?.sessionFile || "in-memory",
     Messages: String(state?.messageCount ?? "?"),
@@ -3996,7 +4001,7 @@ function renderStatus() {
     elements.stateDetails.append(make("dt", undefined, key), make("dd", undefined, value));
   }
 
-  if (state?.thinkingLevel) elements.thinkingSelect.value = state.thinkingLevel;
+  if (shownThinkingLevel) elements.thinkingSelect.value = shownThinkingLevel;
   elements.compactButton.disabled = !!state?.isCompacting;
   elements.compactButton.textContent = state?.isCompacting ? "Compacting…" : "Compact";
   syncModelSelectToState();
@@ -9650,8 +9655,11 @@ elements.setModelButton.addEventListener("click", async () => {
 elements.setThinkingButton.addEventListener("click", async () => {
   const tabContext = activeTabContext();
   try {
-    await api("/api/thinking", { method: "POST", body: { level: elements.thinkingSelect.value }, tabId: tabContext.tabId });
-    if (isCurrentTabContext(tabContext)) await refreshState(tabContext);
+    const response = await api("/api/thinking", { method: "POST", body: { level: elements.thinkingSelect.value }, tabId: tabContext.tabId });
+    if (isCurrentTabContext(tabContext)) {
+      if (response.data?.pending) addEvent(response.data.message || `Thinking level ${response.data.level} will apply to the next prompt.`, "info");
+      await refreshState(tabContext);
+    }
   } catch (error) {
     if (isCurrentTabContext(tabContext)) addEvent(error.message, "error");
   }

package/tests/mobile-static.test.mjs

@@ -682,7 +682,7 @@ assert.match(app, /function triggerNativeDownload\(download\)/, "frontend should
 assert.match(server, /case "\/api\/bash": \{[\s\S]*?type: "bash", command, excludeFromContext: body\.excludeFromContext === true/, "server should expose user bash execution with exclude-from-context support");
 assert.match(server, /case "\/api\/abort-bash":[\s\S]*?type: "abort_bash"/, "server should expose user bash abort");
 assert.match(server, /function sendQueuedBashCommand\(tab, command\)/, "server should serialize user bash through a per-tab FIFO queue");
-assert.match(server, /command\.type === "bash" \? await sendQueuedBashCommand\(tab, command\) : await tab\.rpc\.send\(command\)/, "POST routing should use the bash FIFO queue before RPC send");
+assert.match(server, /command\.type === "bash"[\s\S]*?await sendQueuedBashCommand\(tab, command\)[\s\S]*?: await tab\.rpc\.send\(command\)/, "POST routing should use the bash FIFO queue before RPC send");
 assert.match(app, /function parseUserBashInput\(message\)/, "frontend should parse leading ! and !! bash commands");
 assert.match(app, /let userBashQueuesByTab = new Map\(\)/, "frontend should keep a per-tab user bash queue");
 assert.match(app, /enqueueUserBashCommand\(parsed, \{ usesPromptInput, targetTabId \}\)/, "frontend should queue additional bash commands while one is active");
@@ -720,6 +720,11 @@ assert.match(server, /const OPTIONAL_FEATURE_PACKAGES = new Map/, "server should
 assert.match(server, /\["tuiSkillsCommand", "@firstpick\/pi-extension-setup-skills"\]/, "server should allow installing the TUI skills optional feature");
 assert.match(server, /\["tuiToolsCommand", "@firstpick\/pi-extension-tools"\]/, "server should allow installing the TUI tools optional feature");
 assert.match(server, /function installOptionalFeaturePackage\(featureId\)/, "server should provide optional feature package installation helper");
+assert.match(server, /PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT/, "optional feature installs should support an explicit package-manager root override");
+assert.match(server, /function configuredAgentNpmRoot\(\)/, "global Web UI launches should install optional feature packages into Pi's agent npm root, not the npm global prefix");
+assert.match(server, /installRootDeclaresPackage\(.*?@firstpick\/pi-package-webui/s, "optional feature installs should only reuse a node_modules parent that declares the Web UI package dependency");
+assert.match(server, /if \(webuiDevServer\) return installRoot/, "source-checkout Web UI launches should still use the checkout root for optional feature installs");
+assert.match(server, /Could not determine a safe optional feature install root/, "optional feature installs should fail closed when no declared package root can be found");
 assert.match(server, /url\.pathname === "\/api\/optional-feature-install" && req\.method === "POST"/, "server should expose optional feature install endpoint");
 assert.match(server, /Installing optional Web UI features is only allowed from localhost/, "optional feature install endpoint should be localhost-only");
 assert.match(server, /url\.pathname === "\/api\/themes" && req\.method === "GET"/, "server should expose GET /api/themes");

package/tests/native-parity.test.mjs

@@ -146,6 +146,10 @@ assert.match(app, /api\("\/api\/abort-bash", \{ method: "POST", body: \{\}, tabI
 assert.match(server, /async function cycleTabModel\(tab, direction = "forward"\)/, "server should provide scoped\/all model cycling helper");
 assert.match(server, /url\.pathname === "\/api\/model-cycle" && req\.method === "POST"/, "server should expose model-cycle endpoint for shortcuts");
 assert.match(server, /case "\/api\/thinking-cycle":[\s\S]*?type: "cycle_thinking_level"/, "server should expose thinking-cycle endpoint for shortcuts");
+assert.match(server, /async function setThinkingLevelForTab\(tab, level, \{ allowPending = true \} = \{\}\)[\s\S]*?stateIsBusyForSettings\(stateResult\.data\)[\s\S]*?tab\.pendingThinkingLevel = level/, "server should queue side-panel thinking changes while a tab is running");
+assert.match(server, /const pendingThinkingResponse = await applyPendingThinkingBeforePrompt\(tab\)/, "server should apply queued thinking level before the next prompt");
+assert.match(app, /pendingThinkingLevel[\s\S]*?next prompt/, "frontend should show queued thinking changes as applying on the next prompt");
+assert.match(app, /response\.data\?\.pending[\s\S]*?will apply to the next prompt/, "frontend should announce queued side-panel thinking changes");
 assert.match(app, /function handleNativeAppShortcut\(event\)/, "frontend should centralize native app shortcut handling");
 assert.match(app, /openNativeModelSelector\(\)/, "Ctrl+L shortcut should open the native model selector");
 assert.match(app, /cycleModelFromShortcut\(event\.shiftKey \? "backward" : "forward"\)/, "Ctrl+P shortcuts should cycle models forward and backward");
@@ -157,6 +161,6 @@ assert.match(app, /event\.altKey && key === "ArrowUp"[\s\S]*?restoreQueuedMessag
 assert.match(app, /let userBashQueuesByTab = new Map\(\)/, "frontend should track per-tab user bash FIFO queues");
 assert.match(app, /enqueueUserBashCommand\(parsed, \{ usesPromptInput, targetTabId \}\)/, "user bash should enqueue while an active or queued bash command exists");
 assert.match(server, /function sendQueuedBashCommand\(tab, command\)/, "server should serialize user bash commands per tab");
-assert.match(server, /command\.type === "bash" \? await sendQueuedBashCommand\(tab, command\) : await tab\.rpc\.send\(command\)/, "generic POST handling should route bash through the FIFO queue");
+assert.match(server, /command\.type === "bash"[\s\S]*?await sendQueuedBashCommand\(tab, command\)[\s\S]*?: await tab\.rpc\.send\(command\)/, "generic POST handling should route bash through the FIFO queue");
 assert.ok(pkg.files.includes("WEBUI_TUI_NATIVE_PARITY.json"), "published package should include the native parity matrix");
 assert.ok(pkg.files.includes("webui-rpc-helper.mjs"), "published package should include the Web UI RPC helper extension");