pi-interview 0.5.1 → 0.5.2

package/README.md

@@ -4,7 +4,7 @@
 
 # Interview Tool
 
-A custom tool for pi-agent that opens a web-based form to gather user responses to clarification questions.
+A custom tool for pi-agent that opens an interactive form to gather user responses to clarification questions. On macOS, uses [Glimpse](https://github.com/hazat/glimpse) to render in a native WKWebView window; falls back to a browser tab on other platforms.
 
 https://github.com/user-attachments/assets/52285bd9-956e-4020-aca5-9fbd82916934
 
@@ -18,6 +18,7 @@ Restart pi to load the extension.
 
 **Requirements:**
 - pi-agent v0.35.0 or later (extensions API)
+- For native macOS window: `pi install npm:glimpseui` (optional, falls back to browser if not installed)
 
 ## Features
 
@@ -43,7 +44,7 @@ Restart pi to load the extension.
 
 ```
 ┌─────────┐      ┌──────────────────────────────────────────┐      ┌─────────┐
-│  Agent  │      │              Browser Form                │      │  Agent  │
+│  Agent  │      │        Glimpse / Browser Form             │      │  Agent  │
 │ invokes ├─────►│                                          ├─────►│receives │
 │interview│      │  answer → answer → attach img → answer   │      │responses│
 └─────────┘      │     ↑                                    │      └─────────┘
@@ -52,7 +53,7 @@ Restart pi to load the extension.
 ```
 
 **Lifecycle:**
-1. Agent calls `interview()` → local server starts → browser opens form
+1. Agent calls `interview()` → local server starts → Glimpse window opens (macOS) or browser tab (elsewhere)
 2. User answers at their own pace; each change auto-saves and resets the timeout
 3. Session ends via:
    - **Submit** (`⌘+Enter`) → responses returned to agent
@@ -62,7 +63,7 @@ Restart pi to load the extension.
 
 **Timeout behavior:** The countdown (visible in corner) resets on any activity - typing, clicking, or mouse movement. When it expires, an overlay appears giving the user a chance to continue. Progress is never lost thanks to localStorage auto-save.
 
-**Multi-agent behavior:** When multiple agents run interviews simultaneously, only the first auto-opens the browser. Subsequent interviews are queued and shown as a URL in the tool output, preventing focus stealing. Active interviews also surface a top-right toast with a dropdown to open queued sessions. A session status bar at the top of each form shows the project path, git branch, and session ID for easy identification.
+**Multi-agent behavior:** When multiple agents run interviews simultaneously, only the first auto-opens the window. Subsequent interviews are queued and shown as a URL in the tool output, preventing focus stealing. Active interviews also surface a top-right toast with a dropdown to open queued sessions. A session status bar at the top of each form shows the project path, git branch, and session ID for easy identification.
 
 ## Usage
 

package/form/script.js

@@ -60,6 +60,14 @@
     heartbeat: null,
     queuePoll: null,
   };
+  function closeWindow() {
+    if (window.glimpse && typeof window.glimpse.close === "function") {
+      window.glimpse.close();
+    } else {
+      window.close();
+    }
+  }
+
   let filePickerOpen = false;
   const CLOSE_DELAY = 10;
   const RING_CIRCUMFERENCE = 100.53;
@@ -162,7 +170,7 @@
       
       if (closeIn <= 0) {
         clearInterval(timers.countdown);
-        cancelInterview("timeout").finally(() => window.close());
+        cancelInterview("timeout").finally(() => closeWindow());
       }
     }, 1000);
   }
@@ -1197,7 +1205,7 @@
     if (event.key === 'Escape') {
       if (!expiredOverlay.classList.contains('hidden')) {
         if (timers.countdown) clearInterval(timers.countdown);
-        cancelInterview("user").finally(() => window.close());
+        cancelInterview("user").finally(() => closeWindow());
         return;
       }
       showSessionExpired();
@@ -2421,7 +2429,7 @@
       session.ended = true;
       successOverlay.classList.remove("hidden");
       setTimeout(() => {
-        window.close();
+        closeWindow();
       }, 800);
     } catch (err) {
       if (isNetworkError(err)) {
@@ -2506,7 +2514,10 @@
         if (!url) return;
         const selectedOption = queueSessionSelect.options[queueSessionSelect.selectedIndex];
         if (selectedOption?.disabled) return;
-        window.open(url, "_blank", "noopener");
+        const opened = window.open(url, "_blank", "noopener");
+        if (!opened) {
+          window.location.href = url;
+        }
       });
     }
     window.addEventListener("pagehide", (event) => {
@@ -2539,7 +2550,7 @@
     closeTabBtn.addEventListener("click", async () => {
       if (timers.countdown) clearInterval(timers.countdown);
       await cancelInterview("user");
-      window.close();
+      closeWindow();
     });
 
     stayBtn.addEventListener("click", () => {

package/index.ts

@@ -6,11 +6,72 @@ import * as path from "node:path";
 import * as os from "node:os";
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { startInterviewServer, getActiveSessions, type ResponseItem } from "./server.js";
 import { validateQuestions, type QuestionsFile } from "./schema.js";
 import { loadSettings, type InterviewThemeSettings } from "./settings.js";
 
+interface GlimpseWindow {
+	on(event: "closed", handler: () => void): void;
+	close(): void;
+}
+
+let glimpseOpen: ((html: string, opts: Record<string, unknown>) => GlimpseWindow) | null | undefined;
+
+function findGlimpseMjs(): string | null {
+	// Local node_modules
+	try {
+		const req = createRequire(import.meta.url);
+		return req.resolve("glimpseui");
+	} catch {}
+	// Global npm install
+	try {
+		const globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8" }).trim();
+		const entry = path.join(globalRoot, "glimpseui", "src", "glimpse.mjs");
+		if (fs.existsSync(entry)) return entry;
+	} catch {}
+	return null;
+}
+
+async function getGlimpseOpen() {
+	if (glimpseOpen !== undefined) return glimpseOpen;
+	const resolved = findGlimpseMjs();
+	if (resolved) {
+		try {
+			glimpseOpen = (await import(resolved)).open;
+			return glimpseOpen;
+		} catch {}
+	}
+	glimpseOpen = null;
+	return glimpseOpen;
+}
+
+function escapeHtml(str: string): string {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function openInGlimpse(
+	open: (html: string, opts: Record<string, unknown>) => GlimpseWindow,
+	url: string,
+	title?: string,
+): GlimpseWindow {
+	const safeTitle = escapeHtml(title || "Interview");
+	const shellHTML = `<!DOCTYPE html>
+<html>
+<head><meta charset="UTF-8"><title>${safeTitle}</title></head>
+<body style="margin:0; background:#1a1a2e;">
+  <script>window.location.replace(${JSON.stringify(url)});</script>
+</body>
+</html>`;
+
+	return open(shellHTML, {
+		width: 800,
+		height: 700,
+		title: title || "Interview",
+	});
+}
+
 function formatTimeAgo(timestamp: number): string {
 	const seconds = Math.floor((Date.now() - timestamp) / 1000);
 	if (seconds < 0) return "just now";
@@ -70,7 +131,7 @@ interface SavedQuestionsFile extends QuestionsFile {
 }
 
 const InterviewParams = Type.Object({
-	questions: Type.String({ description: "Path to questions JSON or saved interview HTML file" }),
+	questions: Type.String({ description: "Inline JSON string with questions, or path to a questions JSON / saved interview HTML file" }),
 	timeout: Type.Optional(
 		Type.Number({ description: "Seconds before auto-timeout", default: 600 })
 	),
@@ -122,12 +183,23 @@ function mergeThemeConfig(
 	};
 }
 
-function loadQuestions(questionsPath: string, cwd: string): SavedQuestionsFile {
-	// Expand ~ first, then check if absolute
-	const expanded = expandHome(questionsPath);
+function loadQuestions(questionsInput: string, cwd: string): SavedQuestionsFile {
+	const trimmed = questionsInput.trimStart();
+	if (trimmed.startsWith("{")) {
+		let data: unknown;
+		try {
+			data = JSON.parse(trimmed);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new Error(`Invalid inline JSON: ${message}`);
+		}
+		return validateQuestions(data);
+	}
+
+	const expanded = expandHome(questionsInput);
 	const absolutePath = path.isAbsolute(expanded)
 		? expanded
-		: path.join(cwd, questionsPath); // Use original if relative (no ~)
+		: path.join(cwd, questionsInput);
 
 	if (!fs.existsSync(absolutePath)) {
 		throw new Error(`Questions file not found: ${absolutePath}`);
@@ -269,10 +341,12 @@ export default function (pi: ExtensionAPI) {
 		label: "Interview",
 		description:
 			"Present an interactive form to gather user responses. " +
+			"On macOS, opens in a native window (Glimpse); falls back to a browser tab elsewhere. " +
 			"Use proactively when: choosing between multiple approaches, gathering requirements before implementation, " +
 			"exploring design tradeoffs, or when decisions have multiple dimensions worth discussing. " +
 			"Provides better UX than back-and-forth chat for structured input. " +
 			"Image responses and attachments are returned as file paths - use read tool directly to display them. " +
+			"Pass questions as inline JSON string directly (preferred) or as a path to a JSON file. " +
 			'Questions JSON format: { "title": "...", "description": "...", "questions": [{ "id": "q1", "type": "single|multi|text|image|info", "question": "...", "options": ["A", "B"], "codeBlock": { "code": "...", "lang": "ts" }, "media": { "type": "image|chart|mermaid|table|html", ... } }] }. ' +
 			"Options can be strings or objects: { label: string, code?: { code, lang?, file?, lines?, highlights? } }. " +
 			"Always set recommended with context explaining your reasoning. Recommended options show a 'Recommended' badge and are pre-selected for the user. " +
@@ -295,7 +369,7 @@ export default function (pi: ExtensionAPI) {
 
 			if (!ctx.hasUI) {
 				throw new Error(
-					"Interview tool requires interactive mode with browser support. " +
+					"Interview tool requires interactive mode. " +
 						"Cannot run in headless/RPC/print mode."
 				);
 			}
@@ -327,6 +401,7 @@ export default function (pi: ExtensionAPI) {
 			const sessionId = randomUUID();
 			const sessionToken = randomUUID();
 			let server: { close: () => void } | null = null;
+			let glimpseWin: GlimpseWindow | null = null;
 			let resolved = false;
 			let url = "";
 
@@ -377,7 +452,13 @@ export default function (pi: ExtensionAPI) {
 					});
 				};
 
-				const handleAbort = () => finish("aborted");
+				const handleAbort = () => {
+					if (glimpseWin) {
+						try { glimpseWin.close(); } catch {}
+						glimpseWin = null;
+					}
+					finish("aborted");
+				};
 				signal?.addEventListener("abort", handleAbort, { once: true });
 
 				startInterviewServer(
@@ -403,6 +484,10 @@ export default function (pi: ExtensionAPI) {
 					}
 				)
 					.then(async (handle) => {
+						if (resolved) {
+							handle.close();
+							return;
+						}
 						server = handle;
 						url = handle.url;
 
@@ -412,7 +497,7 @@ export default function (pi: ExtensionAPI) {
 						if (otherActive.length > 0) {
 							const active = otherActive[0];
 							const queuedLines = [
-								"Interview already active in browser:",
+								"Interview already active:",
 								`  Title: ${active.title}`,
 								`  Project: ${active.cwd}${active.gitBranch ? ` (${active.gitBranch})` : ""}`,
 								`  Session: ${active.id.slice(0, 8)}`,
@@ -453,13 +538,27 @@ export default function (pi: ExtensionAPI) {
 								pi.ui.notify(queuedSummary, "info");
 							}
 						} else {
+							const glimpseOpenFn = os.platform() === "darwin" ? await getGlimpseOpen() : null;
+							if (glimpseOpenFn) {
+								try {
+									glimpseWin = openInGlimpse(glimpseOpenFn, url, questionsData.title || "Interview");
+									glimpseWin.on("closed", () => {
+										glimpseWin = null;
+										if (!resolved) {
+											finish("cancelled", [], "user");
+										}
+									});
+									return;
+								} catch {
+									glimpseWin = null;
+								}
+							}
 							try {
 								await openUrl(pi, url, settings.browser);
 							} catch (err) {
 								cleanup();
 								const message = err instanceof Error ? err.message : String(err);
 								reject(new Error(`Failed to open browser: ${message}`));
-								return;
 							}
 						}
 					})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interview",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Interactive interview form extension for pi coding agent",
   "author": "Nico Bailon",
   "license": "MIT",