pum-agent 0.1.2-beta.1 → 0.2.0-beta.2

package/README.md

@@ -45,7 +45,7 @@ The following screens are real OpenTUI renders captured through `tmux`. A local
 - **Parallel subagents:** Persistent agents work in isolated Git worktrees, communicate durably, and report lifecycle transitions to their direct spawners.
 - **Prompt control:** Steer active work, answer model questionnaires, use an ownership-aware message cache, attach clipboard images, and resume sessions with metadata-rich history.
 - **External triggers:** Supervise background commands such as `gh run watch` and automatically wake the exact target agent when they exit.
-- **Provider choice:** Use the login methods exposed by pi, or add an OpenAI-compatible custom endpoint.
+- **Provider choice:** Search the providers exposed by pi, or add an OpenAI-compatible custom endpoint.
 - **Optional safeguards:** Use strict, balanced, or ask Check mode for `bash`, `edit`, `apply_patch`, and external-trigger process proposals.
 - **Terminal-first appearance:** Nine themes, semantic color overrides, Unicode glyphs, and optional animation.
 
@@ -74,7 +74,7 @@ bun run login
 bun run start
 ```
 
-PUM opens the login panel automatically when no provider is available. Use `/login` later to add or update a provider.
+PUM opens the login panel automatically when no provider is available. Use `/login` later to add or update a provider. During browser-based login, PUM opens credential-free HTTP(S) authentication URLs with the platform browser. The URL remains selectable when automatic launch is unavailable.
 
 Resume the latest session for the current directory:
 
@@ -91,11 +91,30 @@ pum
 
 The package is named `pum-agent` because the bare `pum` name is already owned. The installed command is still `pum`.
 
+## Command-line options
+
+```text
+pum [options]
+pum login [options]
+```
+
+| Option or command | Action |
+|---|---|
+| `-h`, `--help` | Print the command-line manual and exit |
+| `-v`, `--version` | Print the exact `pum-agent` package version and exit |
+| `-r`, `--resume` | Resume the latest session for the current directory |
+| `login` | Start PUM with the provider login panel open |
+
+Help and version handling do not initialize the TUI, configuration, credentials, or sessions. Unknown options and commands return an error and a help hint.
+
+Set `PUM_DIR` to override PUM's complete configuration and data directory. Run `pum --help` for a concise directory summary. Enter `?` on an empty in-app prompt to see all controls.
+
 ## Essential controls
 
 | Key | Action |
 |---|---|
 | `Enter` | Send a prompt, or steer the selected working agent |
+| `↑` on an empty prompt | Recall the newest queued user message for the selected agent |
 | `Ctrl+Enter` / `Shift+Enter` | Insert a new line |
 | `Alt+Enter` | Stash the prompt without sending |
 | `Tab` | Open the prompt stash on an empty input |
@@ -112,6 +131,28 @@ The package is named `pum-agent` because the bare `pum` name is already owned. T
 
 Useful commands include `/login`, `/history`, `/triggers`, `/clear`, `/compress`, and `/worktree`.
 
+### Copy transcript text
+
+Drag across transcript text with the left mouse button. PUM copies the completed selection when you release the button.
+
+- On local Windows, PUM first uses the native clipboard module. PUM then tries `clip.exe`.
+- On local macOS, PUM first uses the native clipboard module. PUM then tries `pbcopy`.
+- On local Linux, PUM tries `wl-copy`, `xclip`, or `xsel` when the matching display is available.
+- Over SSH or Mosh, PUM sends OSC 52 through OpenTUI. OpenTUI wraps OSC 52 for detected `tmux` sessions.
+
+Windows Terminal accepts OSC 52 from remote sessions. The terminal can still ask for clipboard-write approval.
+
+For `tmux`, enable clipboard integration and passthrough when the server configuration blocks OSC 52:
+
+```tmux
+set -g set-clipboard on
+set -g allow-passthrough on
+```
+
+Reload the `tmux` configuration after this change. Use the terminal's Shift-drag selection as a manual fallback.
+
+PUM limits remote OSC 52 payloads to 100,000 Base64 characters. This limit prevents large selections from corrupting terminal output.
+
 ## Parallel subagents
 
 PUM runs up to 10 active subagents by default. Configure a limit from 1 through 25 in Settings. Only starting and running agents count toward the limit. Each subagent has these resources:
@@ -125,6 +166,10 @@ Select a range of stashed prompts and press `Enter`. The main agent can group re
 
 Use `Ctrl+L` to select an agent transcript. Input then goes to that agent. Finished or interrupted agents remain available until PUM merges or removes them.
 
+The public `spawn_subagent` tool accepts `preview: true`. PUM then shows the exact child task before it creates any worktree or session. Press `Enter` to approve. An optional note becomes a separate visible user instruction to the new child. Press `Esc` to cancel without creating a child. Cancellation discards the preview note because no child exists. PUM preserves the existing parent transcript draft.
+
+Press `↑` on an empty single-line prompt to recall the newest queued user-authored message for the selected transcript. PUM removes the message from the authoritative queue before restoring its text. PUM does not recall inter-agent, trigger, lifecycle, cache, delivered, or image-bearing messages.
+
 Idle notices report settled work cycles to the direct spawner. They are not completion notices. PUM persists completion intent and delivery state so interrupted notification delivery can resume without duplicate completion messages.
 
 ## Tools and safeguards
@@ -145,9 +190,9 @@ The `message_cache_send` tool accepts stable entry IDs. Single entries use the s
 
 ### External triggers
 
-The trigger tools create process-local supervised commands with an executable and argument array. Trigger definitions can be listed, inspected, paused, resumed, cancelled, run manually, or fired synthetically. Definitions disappear when PUM exits.
+The trigger tools create process-local supervised commands with an executable and argument array. Trigger definitions can be listed, inspected, paused, resumed, cancelled, or run manually. Definitions disappear when PUM exits.
 
-Use `Ctrl+T` or `/triggers` to inspect active definitions. PUM limits definitions, pending deliveries, output size, fire counts, repeat frequency, and lifetime. Output goes to a private temporary file and is removed after the triggered turn settles.
+Use `Ctrl+T` or `/triggers` to inspect active definitions. PUM limits definitions, pending deliveries, output size, run counts, repeat frequency, and lifetime. Output goes to a private temporary file and is removed after the triggered turn settles.
 
 Trigger events target one exact main or retained child session. A missing session or child cancels its definitions instead of redirecting them. Check mode evaluates each process proposal without flattening its argument boundaries into shell text.
 
@@ -160,16 +205,18 @@ Trigger events target one exact main or retained child session. A missing sessio
 Select a Check mode profile in `Ctrl+P`. It applies to `bash`, `edit`, `apply_patch`, and external-trigger process execution:
 
 - **Strict:** Run deterministic hard rules, then require a clear verifier approval.
-- **Balanced:** Permit only narrow, recognized project-local operations after hard rules. Send all other calls to the verifier.
-- **Ask:** Send ambiguous calls to the verifier. If the result stays unclear or the verifier fails, ask the user.
+- **Balanced:** Block deterministic hard-rule or suspicious findings. Allow ordinary complete project-local calls. Verifier review is non-blocking unless the verifier returns explicit `UNSAFE`.
+- **Ask:** Show the approval popup for every checked call that passes hard rules, unless an exact session or project approval already matches. A verifier `SAFE`, unclear, error, or unavailable result still requires approval.
+
+Every active profile hard-blocks project escape, escaping links, credential access, privilege escalation, persistence, remote-script execution, destructive Git operations, and broad deletion. These hard blocks cannot be overridden and do not open the popup. An explicit verifier `UNSAFE` verdict also blocks without a popup. The only exception is a deterministic match for direct main-agent `npm publish` or `npm dist-tag add`. The verifier category does not control this exception. The exception still requires explicit popup approval. Managed subagents cannot use the exception.
 
-Every active profile hard-blocks project escape, escaping links, credential access, privilege escalation, persistence, remote-script execution, destructive Git operations, and broad deletion. These hard blocks cannot be overridden. An explicit verifier `UNSAFE` verdict also cannot be overridden.
+For `edit` and `apply_patch`, PUM validates the complete proposed change before any mutation. Review data includes the unified diff, changed paths, line counts, sensitivity flags, project containment, and full-content SHA-256. Invalid, stale, malformed, escaping, or incompletely analyzed input blocks the call. Patch length alone does not block a valid Balanced call.
 
-For `edit` and `apply_patch`, PUM validates the proposed change and sends a unified diff, changed paths, line counts, sensitivity flags, and project containment. PUM does not mutate files before the decision. Invalid or stale edit context blocks the call.
+Ask mode can allow an exact call once, for the current session, or for the current project. Approvals match the authoritative main or child identity, tool, verifier model, project, and canonical complete input. Chat text is not approval. Use **Clear approvals** in Settings to remove project approvals.
 
-Ask mode can allow an exact call once, for the current session, or for the current project. Project approvals match the tool, verifier model, project, and canonical complete input. Use **Clear approvals** in Settings to remove project approvals.
+The verifier uses a structured decision schema. One unclear response can receive one adjudication under the shared 15-second watchdog. Strict blocks malformed replies, errors, aborts, and timeouts. Balanced allows a fully validated call after an unclear, unavailable, failed, or timed-out review. Balanced still blocks explicit verifier `UNSAFE`, aborts, deterministic suspicious findings, malformed structures, and incomplete analysis. Ask requires the popup after hard rules for verifier `SAFE`, unclear, error, and unavailable results. Check mode is off by default and is not a sandbox.
 
-The verifier uses a structured decision schema. One unclear response can receive one adjudication under the shared 15-second watchdog. Strict and balanced block malformed replies, errors, aborts, and timeouts. Ask can present unresolved results to the user. Check mode is off by default and is not a sandbox.
+Verifier prompts stay bounded. For an oversized Balanced review, PUM sends complete validation metadata, counts, findings, and SHA-256 digests. PUM does not send a raw prefix or suffix as if it were complete. Strict and Ask keep their fail-closed oversized-input behavior.
 
 ### Hosted web search
 
@@ -239,7 +286,7 @@ Use a throwaway `PUM_DIR` for local integration tests. Capture TUI output throug
 
 ## Release status
 
-PUM `0.1` is in beta. Interfaces and persisted formats can still change before the stable release. Review the release notes before upgrading sessions or custom configuration.
+PUM `0.2` is in beta. Interfaces and persisted formats can still change before the stable release. Review the release notes before upgrading sessions or custom configuration.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.1.2-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",

package/src/agent-selector.tsx

@@ -10,6 +10,7 @@ import {
   type StatusMetadataValues,
 } from "./status-metadata";
 import type { Theme } from "./theme";
+import { PopupFrame } from "./popup-frame";
 import type { SubagentSnapshot } from "./subagents/types";
 
 export type AgentTreeRow = {
@@ -125,12 +126,19 @@ export function AgentSelectorPopup({
   const { width, height } = useTerminalDimensions();
   const scrollRef = useRef<ScrollBoxRenderable>(null);
   const narrow = width < 50;
-  const popupWidth = narrow ? Math.max(12, width - 2) : Math.floor(width * 0.7);
+  const popupWidth = narrow ? Math.max(1, width - 2) : Math.max(1, Math.floor(width * 0.7));
   const popupColumns = Math.max(8, popupWidth - 5);
-  const popupHeight = Math.min(
+  const popupHeight = Math.max(1, Math.min(
+    height,
     rows.length + (narrow ? 10 : 7),
     Math.max(7, Math.floor(height * (narrow ? 0.85 : 0.7))),
-  );
+  ));
+  const geometry = {
+    top: narrow ? Math.min(1, Math.max(0, height - popupHeight)) : Math.max(0, Math.floor(height * 0.15)),
+    left: narrow ? Math.min(1, Math.max(0, width - popupWidth)) : Math.max(0, Math.floor(width * 0.15)),
+    width: popupWidth,
+    height: popupHeight,
+  };
 
   useEffect(() => {
     const timer = setTimeout(() => {
@@ -140,21 +148,13 @@ export function AgentSelectorPopup({
   }, [cursor]);
 
   return (
-    <box
+    <PopupFrame
+      theme={theme}
+      terminalWidth={width}
+      terminalHeight={height}
+      geometry={geometry}
+      zIndex={100}
       title=" Agents "
-      style={{
-        position: "absolute",
-        top: narrow ? 1 : "15%",
-        left: narrow ? 1 : "15%",
-        width: popupWidth,
-        height: popupHeight,
-        zIndex: 100,
-        border: true,
-        borderColor: theme.border,
-        backgroundColor: theme.popupBg,
-        flexDirection: "column",
-        padding: 1,
-      }}
     >
       <scrollbox
         ref={scrollRef}
@@ -212,6 +212,6 @@ export function AgentSelectorPopup({
         wrapMode="word"
         style={{ flexShrink: 0, width: "100%" }}
       />
-    </box>
+    </PopupFrame>
   );
 }

package/src/app.tsx

@@ -80,6 +80,9 @@ import {
   type PendingImage,
 } from "./image-paste";
 import type { SubagentManager } from "./subagents/manager";
+import type { SpawnPreviewManager } from "./subagents/spawn-preview";
+import { SpawnPreviewPopup } from "./subagents/spawn-preview-popup";
+import { recallNewestQueuedUserMessage } from "./queue-recall";
 import { runWorktreeCommand } from "./worktree-command";
 import { CANCEL_WINDOW_MS, confirmsCancellation } from "./cancel-confirmation";
 import { buildStashBatchPrompt, selectedRange } from "./stash-batch";
@@ -329,6 +332,7 @@ export function App({
   searchProviders,
   subagentManager,
   questionnaireManager,
+  spawnPreviewManager,
   loginRequired = false,
   promptHistoryStore = DEFAULT_PROMPT_HISTORY_STORE,
   promptStashStore = DEFAULT_PROMPT_STASH_STORE,
@@ -349,6 +353,7 @@ export function App({
   searchProviders: string[];
   subagentManager: SubagentManager;
   questionnaireManager?: QuestionnaireManager;
+  spawnPreviewManager?: SpawnPreviewManager;
   loginRequired?: boolean;
   promptHistoryStore?: PromptHistoryStore;
   promptStashStore?: PromptStashStore;
@@ -406,10 +411,14 @@ export function App({
   const [agentElapsedSec, setAgentElapsedSec] = useState(0);
   const [loginOpen, setLoginOpen] = useState(loginRequired);
   const [, setQuestionnaireRevision] = useState(0);
+  const [, setSpawnPreviewRevision] = useState(0);
   const [loginPage, setLoginPage] = useState<LoginPage>(() => ({
     kind: "providers",
     methods: providerLoginMethods((modelRuntime as any).getProviders?.() ?? []),
     cursor: 0,
+    query: "",
+    searchFocused: true,
+    customVisible: true,
   }));
   const [modelQuery, setModelQuery] = useState("");
   const [modelSearchFocused, setModelSearchFocused] = useState(false);
@@ -429,6 +438,7 @@ export function App({
     ? agents.find((agent) => agent.id === activeAgentId)
     : undefined;
   const questionnaire = questionnaireManager?.current();
+  const spawnPreview = spawnPreviewManager?.current();
   const visibleTx = activeAgent?.transcript ?? tx;
   const visibleBusy = activeAgent
     ? activeAgent.status === "starting" || activeAgent.status === "running"
@@ -460,6 +470,7 @@ export function App({
 
   const inputRef = useRef<TextareaRenderable>(null);
   const questionnaireInputRef = useRef<TextareaRenderable>(null);
+  const spawnPreviewInputRef = useRef<TextareaRenderable>(null);
   const settingsOpenRef = useRef(settingsOpen);
   const triggersOpenRef = useRef(false);
   const settingsPageRef = useRef(page);
@@ -480,6 +491,10 @@ export function App({
   const imagePasteBusy = useRef(false);
   const viewDrafts = useRef(new Map<string, string>());
   const viewEditingStashIndices = useRef(new Map<string, number | null>());
+  const spawnPreviewRestoreView = useRef<{ active: boolean; agentId: string | null }>({
+    active: false,
+    agentId: null,
+  });
   /** Cache row currently checked out into the selected transcript input. */
   const editingStashIndex = useRef<number | null>(null);
   const quitTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
@@ -801,6 +816,10 @@ export function App({
     [subagentManager],
   );
 
+  useEffect(() => spawnPreviewManager?.subscribe(() => {
+    setSpawnPreviewRevision((revision) => revision + 1);
+  }), [spawnPreviewManager]);
+
   useEffect(() => {
     if (!questionnaireManager) return;
     return questionnaireManager.subscribe(() => {
@@ -937,8 +956,9 @@ export function App({
       clearTimeout(cancelTimer.current);
       clearPendingImages();
       cleanupPendingImages();
+      spawnPreviewManager?.cancelAll("shutdown");
     },
-    [],
+    [spawnPreviewManager],
   );
 
   useEffect(() => {
@@ -1161,6 +1181,22 @@ export function App({
     session.abort().finally(() => setWorking(false));
   };
 
+  const recallQueuedUserMessage = async (target: string | null) => {
+    const recalled = target
+      ? await subagentManager.recallQueuedUserMessage(target)
+      : await recallNewestQueuedUserMessage(session, tx.pending);
+    if (!recalled) return;
+    if (!target) dropPending(recalled.id);
+    const key = target ?? "main";
+    viewDrafts.current.set(key, recalled.text);
+    if (activeAgentIdRef.current === target) {
+      setEditorText(recalled.text);
+      histCursor.current = null;
+      draft.current = "";
+      inputRef.current?.focus();
+    }
+  };
+
   /** Up walks back through sent prompts, down returns to the current draft. */
   const recall = (direction: -1 | 1) => {
     const input = inputRef.current;
@@ -1276,6 +1312,7 @@ export function App({
     promptText: string,
     displayText: string,
     images: ReturnType<typeof imageContent>[] = [],
+    recallable = images.length === 0,
   ) => {
     const userLine: Extract<Line, { kind: "text" }> = {
       kind: "text",
@@ -1290,6 +1327,7 @@ export function App({
         id: randomUUID().slice(0, 12),
         line: userLine,
         deliveryText: promptText,
+        recallable,
       };
       addPending(pending);
       withSearchRoute(session.sessionId, () => session.steer(promptText, images)).catch((error) => {
@@ -1386,7 +1424,7 @@ export function App({
     setStash(next);
     refreshHistoryAfterStashMutation();
     resetAfterCacheExecution();
-    deliverMainPrompt(buildStashBatchPrompt(prompts), cachedBatchDisplay(prompts));
+    deliverMainPrompt(buildStashBatchPrompt(prompts), cachedBatchDisplay(prompts), [], false);
   };
 
   useEffect(() => {
@@ -1411,15 +1449,15 @@ export function App({
         );
         const prompts = entries.map((entry) => entry.text);
         if (prompts.length > 1) {
-          deliverMainPrompt(buildStashBatchPrompt(prompts), cachedBatchDisplay(prompts));
+          deliverMainPrompt(buildStashBatchPrompt(prompts), cachedBatchDisplay(prompts), [], false);
           return { count: prompts.length, route: "main" };
         }
         const prompt = prompts[0]!;
         if (request.requester.kind === "subagent") {
-          await subagentManager.sendUserMessage(request.requester.id, prompt, [], prompt);
+          await subagentManager.sendUserMessage(request.requester.id, prompt, [], prompt, false);
           return { count: 1, route: "subagent" };
         }
-        deliverMainPrompt(prompt, prompt);
+        deliverMainPrompt(prompt, prompt, [], false);
         return { count: 1, route: "main" };
       },
     );
@@ -1436,7 +1474,7 @@ export function App({
     if (action === "pause") result = triggerManager.pause(trigger.id);
     else if (action === "resume") result = triggerManager.resume(trigger.id);
     else if (action === "cancel") result = triggerManager.cancel(trigger.id);
-    else result = triggerManager.invoke(trigger.id, action);
+    else result = triggerManager.invoke(trigger.id);
     Promise.resolve(result).catch((error) => append({
       kind: "text",
       role: "error",
@@ -1550,6 +1588,36 @@ export function App({
     return true;
   };
 
+  useEffect(() => {
+    if (spawnPreview) {
+      if (!spawnPreviewRestoreView.current.active) {
+        spawnPreviewRestoreView.current = {
+          active: true,
+          agentId: activeAgentIdRef.current,
+        };
+      }
+      settingsOpenRef.current = false;
+      setSettingsOpen(false);
+      setHelpOpen(false);
+      setHistoryOpen(false);
+      setAgentSelectorOpen(false);
+      setTriggerPopup(false, false);
+      setLoginOpen(false);
+      const target = spawnPreview.requester.agentId;
+      if (target && !agents.some((agent) => agent.id === target)) {
+        spawnPreviewManager?.cancel("unavailable");
+      } else if (!selectAgentView(target)) {
+        spawnPreviewManager?.cancel("unavailable");
+      }
+      return;
+    }
+    if (!spawnPreviewRestoreView.current.active) return;
+    const target = spawnPreviewRestoreView.current.agentId;
+    spawnPreviewRestoreView.current.active = false;
+    if (!target || agents.some((agent) => agent.id === target)) selectAgentView(target);
+    else selectAgentView(null);
+  }, [spawnPreview?.id]);
+
   const cycleAgentView = (direction: -1 | 1) => {
     const ids: Array<string | null> = [null, ...agents.map((agent) => agent.id)];
     if (ids.length === 1) return;
@@ -1582,11 +1650,27 @@ export function App({
       return;
     }
 
+    if (spawnPreview) {
+      const isPreviewReturn = ["return", "enter", "kpenter", "linefeed"].includes(key.name);
+      if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+        key.stopPropagation();
+        spawnPreviewInputRef.current?.setText("");
+        spawnPreviewManager?.cancel();
+      } else if (isPreviewReturn && !key.shift && !key.ctrl && !key.meta && !key.option) {
+        key.stopPropagation();
+        const note = spawnPreviewInputRef.current?.plainText ?? "";
+        spawnPreviewInputRef.current?.setText("");
+        spawnPreviewManager?.approve(note);
+      }
+      return;
+    }
+
     if (key.ctrl && key.name === "c") {
       key.stopPropagation();
       resetCancelArm();
       const promptOwnsInput =
         !questionnaire &&
+        !spawnPreview &&
         !loginOpen &&
         !triggersOpenRef.current &&
         !agentSelectorOpen &&
@@ -1658,8 +1742,7 @@ export function App({
     }
 
     if (loginOpen) {
-      key.stopPropagation();
-      loginControllerRef.current?.handleKey(key);
+      if (loginControllerRef.current?.handleKey(key)) key.stopPropagation();
       return;
     }
 
@@ -2015,7 +2098,6 @@ export function App({
         moveStash(key.name === "up" ? -1 : 1, key.shift);
         return;
       }
-      if (activeAgentId) return;
       if (commandMatches.length > 0) {
         key.stopPropagation();
         const next = moveCommandSelection(
@@ -2029,6 +2111,22 @@ export function App({
       }
       // Keep arrow navigation inside multiline or visually wrapped prompts.
       if ((inputRef.current?.editorView.getTotalVirtualLineCount() ?? 1) > 1) return;
+      if (key.name === "up" && !inputValue && pendingImages.current.length === 0) {
+        const queued = visibleTx.pending.some((pending) =>
+          !pending.delivered &&
+          pending.line.kind === "text" &&
+          pending.line.role === "user" &&
+          Boolean(pending.deliveryText),
+        );
+        if (queued) {
+          key.stopPropagation();
+          void recallQueuedUserMessage(activeAgentIdRef.current).catch((error) =>
+            append({ kind: "text", role: "error", text: String(error) }),
+          );
+          return;
+        }
+      }
+      if (activeAgentId) return;
       key.stopPropagation();
       recall(key.name === "up" ? -1 : 1);
       return;
@@ -2267,7 +2365,7 @@ export function App({
             selectionBg={theme.selectionBg}
             wrapMode="char"
             scrollMargin={1}
-            focused={!settingsOpen && !helpOpen && !historyOpen && !agentSelectorOpen && !triggersOpen && !loginOpen && !questionnaire && !checkApproval}
+            focused={!settingsOpen && !helpOpen && !historyOpen && !agentSelectorOpen && !triggersOpen && !loginOpen && !questionnaire && !spawnPreview && !checkApproval}
             onContentChange={handleTextareaChange}
             onCursorChange={scheduleInputMetrics}
             onSubmit={() => submitPrompt()}
@@ -2287,7 +2385,23 @@ export function App({
           role="inputBottom"
         />
         {loginOpen ? (
-          <LoginPopup theme={theme} page={loginPage} terminalWidth={width} terminalHeight={height} />
+          <LoginPopup
+            theme={theme}
+            page={loginPage}
+            terminalWidth={width}
+            terminalHeight={height}
+            onProviderSearchChange={(value) => loginControllerRef.current?.setProviderQuery(value)}
+          />
+        ) : null}
+        {spawnPreview ? (
+          <SpawnPreviewPopup
+            theme={theme}
+            syntaxStyle={syntaxStyle}
+            request={spawnPreview}
+            terminalWidth={width}
+            terminalHeight={height}
+            inputRef={spawnPreviewInputRef}
+          />
         ) : null}
         {questionnaire ? (
           <QuestionnairePopup

package/src/browser-launch.ts

@@ -0,0 +1,68 @@
+import { spawn } from "node:child_process";
+
+export type BrowserLaunchCommand = {
+  executable: string;
+  args: string[];
+};
+
+export type BrowserProcessSpawner = (
+  executable: string,
+  args: readonly string[],
+) => Promise<void>;
+
+export function credentialFreeHttpUrl(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.username || url.password) return null;
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+export function browserLaunchCommand(
+  platform: NodeJS.Platform,
+  url: string,
+): BrowserLaunchCommand | null {
+  if (platform === "win32") {
+    return {
+      executable: "rundll32.exe",
+      args: ["url.dll,FileProtocolHandler", url],
+    };
+  }
+  if (platform === "darwin") return { executable: "open", args: [url] };
+  if (platform === "linux") return { executable: "xdg-open", args: [url] };
+  return null;
+}
+
+const spawnBrowserProcess: BrowserProcessSpawner = (executable, args) =>
+  new Promise<void>((resolve, reject) => {
+    const child = spawn(executable, [...args], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.once("spawn", resolve);
+    child.once("error", reject);
+    child.unref();
+  });
+
+export async function launchBrowserUrl(
+  value: string,
+  options: {
+    platform?: NodeJS.Platform;
+    spawn?: BrowserProcessSpawner;
+  } = {},
+): Promise<boolean> {
+  const url = credentialFreeHttpUrl(value);
+  if (!url) return false;
+  const command = browserLaunchCommand(options.platform ?? process.platform, url);
+  if (!command) return false;
+  try {
+    await (options.spawn ?? spawnBrowserProcess)(command.executable, command.args);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/check-approval-popup.tsx

@@ -1,4 +1,5 @@
 import type { Theme } from "./theme";
+import { PopupFrame } from "./popup-frame";
 
 export type CheckApprovalDecision =
   | "allowOnce"
@@ -149,21 +150,19 @@ export function CheckApprovalPopup(props: CheckApprovalPopupProps) {
   const previewLabel = request.preview.kind === "command" ? "Command" : "Diff";
 
   return (
-    <box
-      title=" Approval required "
-      style={{
-        position: "absolute",
+    <PopupFrame
+      theme={theme}
+      terminalWidth={terminalWidth}
+      terminalHeight={terminalHeight}
+      geometry={{
         top: Math.max(0, Math.floor((terminalHeight - layout.popupHeight) / 2)),
         left: layout.margin,
         width: layout.popupWidth,
         height: layout.popupHeight,
-        zIndex: 140,
-        border: true,
-        borderColor: theme.warn,
-        backgroundColor: theme.popupBg,
-        flexDirection: "column",
-        padding: 1,
       }}
+      zIndex={140}
+      title=" Approval required "
+      borderColor={theme.warn}
     >
       <box style={{ height: 1, flexShrink: 0, flexDirection: "row" }}>
         <text content={request.tool} fg={theme.warn} bg={theme.popupBg} wrapMode="none" />
@@ -220,6 +219,6 @@ export function CheckApprovalPopup(props: CheckApprovalPopupProps) {
         wrapMode="none"
         style={{ height: 1, flexShrink: 0 }}
       />
-    </box>
+    </PopupFrame>
   );
 }