Pup - the AI's own browser

@@ -3509,6 +3509,9 @@ async function getSessionInfo(sessionId, session) {     // v1.8.26: did background-by-default actually take? 'backgrounded' (good),     // 'still-foreground' (focus steal — a bug), 'no-window', or null (foreground open     // or non-Windows). Self-verified by re-reading the OS foreground window post-open.+    // v1.8.70: who put this window on the user's screen, when, and their stated reason —+    // the audit answer to "why did this foreground?" in one status query.+    lastForeground: session._lastForeground || null,     background: (() => {       try {         const bg = browsers.get(session.profileName)?.browser?._bgResult || null;@@ -3637,7 +3640,7 @@ const server = http.createServer(async (req, res) => {                      hint: m.hint || summary, related: m.related || [], pitfalls: m.pitfalls || [] };           };           sendJSON(res, { success: true, bridge: 'puppeteer', verbs: [-            V('browser_open_window', 'Open a generic pup window — a fresh isolated Chrome/Edge process (never your real signed-in browser), fully drivable via CDP. ALWAYS opens in the BACKGROUND (does not steal focus; never disturbs the user\'s main work; still fully screenshottable/drivable) UNLESS you pass foreground:true — do that ONLY when the user explicitly wants to watch. Pass width+height (+ optional x,y, screen px) to place it at a specific size/position for screenshot framing — this NO LONGER foregrounds it (sizing stays in the background too; default unsized is maximized). profile defaults to sessionId. OWNERSHIP: sessionIds are shared across ALL AI threads — use a task-prefixed sessionId + owner:"<your-task>" so pup can refuse other threads stealing your window (reusing an existing id with a new url navigates it away; declared cross-owner reuse errors with session_owned_by_another_thread unless takeover:true). (For the user\'s REAL Chrome/Edge, use the Adom extension\'s nbrowser_* verbs.)', { sessionId: 'required str — task-prefix it (e.g. "mytask-web"); generic ids collide across threads', url: 'optional str', profile: 'optional str — defaults to sessionId', owner: 'optional str — your thread/task label; lets pup protect this window from other threads', takeover: 'optional bool — claim a window owned by another thread (only when the user explicitly asks)', foreground: 'optional bool — the ONLY way to show the window (default false = background, always, even when sized)', width: 'optional int px — sizes for screenshot framing, stays background', height: 'optional int px', x: 'optional int px', y: 'optional int px', updateNote: 'optional str — a short "what I did" note, surfaced back in list_tabs/list_windows as lastAgentUpdate so the user knows what changed', autoFlash: 'optional bool (default true) — mutating verbs auto-flash this window\'s taskbar (debounced, never steals focus) so the user notices the agent touched it; pass false to make this window silent by default', silent: 'optional bool — suppress the auto-flash for just this call' }, 60, { sessionId: 'mytask-web', owner: 'mytask', url: 'https://example.com', width: 960, height: 540 }),+            V('browser_open_window', 'Open a generic pup window — a fresh isolated Chrome/Edge process (never your real signed-in browser), fully drivable via CDP. ALWAYS opens in the BACKGROUND (does not steal focus; never disturbs the user\'s main work; still fully screenshottable/drivable) UNLESS you pass foreground:true — do that ONLY when the user explicitly wants to watch. Pass width+height (+ optional x,y, screen px) to place it at a specific size/position for screenshot framing — this NO LONGER foregrounds it (sizing stays in the background too; default unsized is maximized). profile defaults to sessionId. OWNERSHIP: sessionIds are shared across ALL AI threads — use a task-prefixed sessionId + owner:"<your-task>" so pup can refuse other threads stealing your window (reusing an existing id with a new url navigates it away; declared cross-owner reuse errors with session_owned_by_another_thread unless takeover:true). (For the user\'s REAL Chrome/Edge, use the Adom extension\'s nbrowser_* verbs.)', { sessionId: 'required str — task-prefix it (e.g. "mytask-web"); generic ids collide across threads', url: 'optional str', profile: 'optional str — defaults to sessionId', owner: 'optional str — your thread/task label; lets pup protect this window from other threads', takeover: 'optional bool — claim a window owned by another thread (only when the user explicitly asks)', foreground: 'optional bool — request showing the window on the user\'s screen. GATED (v1.8.70): requires foregroundReason too, else the open succeeds but stays BACKGROUND with foregroundDenied set. Only when the USER explicitly asked to watch.', foregroundReason: 'required WITH foreground:true — quote/paraphrase what the user said that justifies putting a window on their screen (min 10 chars; logged + recorded in lastAgentUpdate, auditable)', width: 'optional int px — sizes for screenshot framing, stays background', height: 'optional int px', x: 'optional int px', y: 'optional int px', updateNote: 'optional str — a short "what I did" note, surfaced back in list_tabs/list_windows as lastAgentUpdate so the user knows what changed', autoFlash: 'optional bool (default true) — mutating verbs auto-flash this window\'s taskbar (debounced, never steals focus) so the user notices the agent touched it; pass false to make this window silent by default', silent: 'optional bool — suppress the auto-flash for just this call' }, 60, { sessionId: 'mytask-web', owner: 'mytask', url: 'https://example.com', width: 960, height: 540 }),             V('browser_open_tab', 'Open a new tab in an EXISTING session/window (returns {tabId, tabCount, activeTabId} — no need to diff list_tabs). This is the right verb for multi-URL work: ONE window with many tabs (one taskbar button), not many windows. The window stays in the background; the tab auto-flashes the taskbar (debounced) so the user notices. The USER can click the window\'s taskbar button at any time to view it — pup never pulls it back down.', { sessionId: 'required str', url: 'optional str', updateNote: 'optional str — short "what I did" note surfaced in list_tabs as lastAgentUpdate', silent: 'optional bool — suppress the auto-flash for this call' }, 30, { sessionId: 'work', url: 'https://example.com' }),             V('browser_close_tab', 'Close a tab.', { sessionId: 'required str', tabId: 'optional str (default active)' }, 15, { sessionId: 'work' }),             V('browser_close_window', 'Close a window/session (its tabs go too).', { sessionId: 'required str' }, 20, { sessionId: 'work' }),@@ -3666,7 +3669,7 @@ const server = http.createServer(async (req, res) => {             V('browser_prewarm', 'Install Chrome for Testing WITHOUT opening a window, and pin it as the default. Use when you specifically want CfT rather than the machine\'s installed Chrome/Edge.', { wait: 'optional bool — block until installed', setDefault: 'optional bool (default true) — pin CfT as the default' }, 240, {}),             V('browser_use', 'Pin (or clear) the browser pup drives by default: chrome | edge | cft | auto (or an explicit executablePath). "cft" fetches Chrome for Testing then pins it. With {browser:"chrome", install:true} it DOWNLOADS & INSTALLS real Google Chrome on an Edge-only box, then pins it — SILENT on a normal PC; on a locked-down box (VM/managed device) it needs a Windows approval, so the bridge pops a native "click YES on the UAC" notification and, if it expires, re-notifies with a one-tap "Approve now" (all autonomous — no AI turn). Poll browser_readiness.chromeStablePhase: installing → awaiting_uac → ready. Persists across restarts; launch still spawn-verifies + falls back.', { browser: '"chrome" | "edge" | "cft" | "auto"', install: 'optional bool — with browser:"chrome", install real Chrome if missing', elevate: 'optional "auto"(default)|true|false — auto: quiet install, prompt only if it needs admin; false: never prompt; true: go straight to the prompt', executablePath: 'optional — pin an exact browser binary' }, 240, {}),             V('browser_lower_os_window', 'Send a pup window to the BACKGROUND (behind the user\'s windows) without stealing focus — still fully drivable. The default for open; use this to re-hide a window you foregrounded.', { sessionId: 'optional str' }, 15, {}),-            V('browser_raise_os_window', 'Bring a pup window to the FOREGROUND (user\'s screen). Use SPARINGLY — only when the user EXPLICITLY must SEE it (a demo, recording, "show me"). It STEALS focus and can leak a mid-typed keystroke into the page — to just signal "I updated this window", use browser_alert_window (or rely on the auto-flash), NOT raise. pup blurs the page\'s focused element before raising to reduce the keystroke leak. Alias: browser_focus_window.', { sessionId: 'optional str' }, 15, {}),+            V('browser_raise_os_window', 'Bring a pup window to the FOREGROUND (user\'s screen). GATED (v1.8.70): REFUSED with foreground_reason_required unless you pass foregroundReason — a quote/paraphrase of what the user said that justifies it (min 10 chars; logged, recorded in lastAgentUpdate, auditable). Allowed ONLY when the user EXPLICITLY must SEE it (a demo, recording, "show me"). It STEALS focus — to just signal "I updated this window", use browser_alert_window (or the auto-flash), NOT raise. After the show-me: browser_lower_os_window to return it to the background. Alias: browser_focus_window.', { sessionId: 'optional str', foregroundReason: 'REQUIRED — why the user asked to see this window' }, 15, { foregroundReason: 'user said "show me the wiki page"' }),             V('browser_alert_window', 'Flash the taskbar icon for a pup window — a non-intrusive "it\'s ready/DONE" nudge that does NOT steal focus. NOTE (v1.8.23): mutating verbs already AUTO-FLASH (debounced, one per ~5s burst per window) so the user always knows the agent touched a window — use this for an explicit end-of-task "it\'s ready" nudge on top of that. STRONGLY prefer this (or the auto-flash) over browser_raise_os_window, which steals focus and can leak a mid-typed keystroke into the page.', { sessionId: 'optional str', stop: 'optional bool — CLEAR the highlight instead of flashing' }, 15, {}),             V('browser_render_html', 'Render a local HTML string in the tab via page.setContent — UTF-8-correct (a data: URL mojibakes accented chars without an explicit charset). Great for previewing generated markup without a temp file. Auto-flashes the window.', { sessionId: 'required str', html: 'required HTML string', waitUntil: 'optional (domcontentloaded default)', updateNote: 'optional note for lastAgentUpdate', silent: 'optional bool — suppress the auto-flash' }, 30, { sessionId: 'work', html: '<h1>Café</h1>' }),             // Session/tab/window management + probes (were routed but undocumented).@@ -3755,6 +3758,17 @@ const server = http.createServer(async (req, res) => {           const downloadPath = (args.downloadPath && typeof args.downloadPath === 'string')             ? args.downloadPath             : path.join(os.homedir(), 'Downloads');+          // v1.8.70: THE FOREGROUND GATE (open-time half; mirrors abe's dual key). The flag+          // alone is NOT enough — without foregroundReason the open still SUCCEEDS but the+          // window stays BACKGROUND (abe semantics: withhold the foregrounding, not the work),+          // and the response says exactly what was missing. A granted foreground is logged ++          // recorded in lastAgentUpdate so the user can always audit who put a window on their+          // screen and why. Also accepts abe's arg name userRequestedForeground.+          const fgRequested = !!(args.foreground || args.raise || args.show || args.userRequestedForeground);+          const fgReason = (typeof args.foregroundReason === 'string' && args.foregroundReason.trim().length >= 10) ? args.foregroundReason.trim() : null;+          const fgGranted = fgRequested && !!fgReason;+          const fgDenied = fgRequested && !fgReason;+          if (fgGranted) console.log(`[foreground] "${sessionId}" open GRANTED — reason: ${fgReason}`);           let session;           try {             session = await launchSession(sessionId, args.url, {@@ -3767,8 +3781,8 @@ const server = http.createServer(async (req, res) => {               takeover: !!args.takeover,               // v1.8.24: background-by-default is enforced DURING launch (focus handed               // back to the user's window the instant pup's window appears) unless the-              // caller explicitly wants it foreground.-              foreground: !!(args.foreground || args.raise || args.show),+              // caller explicitly wants it foreground (v1.8.70: AND supplied a reason).+              foreground: fgGranted,               silent: !!args.silent || args.autoFlash === false,             });           } catch (e) {@@ -3811,7 +3825,7 @@ const server = http.createServer(async (req, res) => {           // is background even after the bounds call.           const w = Number(args.width), h = Number(args.height), wx = Number(args.x), wy = Number(args.y);           const sized = Number.isFinite(w) && Number.isFinite(h);-          const foreground = !!(args.foreground || args.raise || args.show);+          const foreground = fgGranted; // v1.8.70: the gate's verdict, not the raw flag           if (sized) {             try { await setSessionWindowBounds(session, { x: wx, y: wy, width: w, height: h }); } catch (e) {}             // v1.8.21: ALSO pin the page VIEWPORT (CDP device-metrics) to width×height.@@ -3834,6 +3848,10 @@ const server = http.createServer(async (req, res) => {           // v1.8.26: record whether this window is meant to be on screen — gates every           // later bringToFront (navigate/reload/switch_tab must not raise a bg window).           if (session) session._foreground = foreground;+          if (session && fgGranted) {+            session._lastForeground = { ts: Date.now(), verb: 'browser_open_window', reason: fgReason };+            try { recordAgentUpdate(session, 'browser_open_window', { updateNote: `FOREGROUND: ${fgReason}` }, session.activeTabId); } catch (e) {}+          }           // v1.8.23: session-level auto-flash default (autoFlash:false → this window never           // auto-flashes, e.g. a chatty automation loop the user isn't watching).           if (session && args.autoFlash === false) session._flashSilent = true;@@ -3851,6 +3869,7 @@ const server = http.createServer(async (req, res) => {           }           // Verbose browser report: which browser we actually drove, what else is available.           const brep = browserPickReport();+          const fgDenyHint = fgDenied ? ' ⛔ FOREGROUND DENIED: you passed foreground:true WITHOUT a foregroundReason, so the window opened in the BACKGROUND (the open itself succeeded). Foregrounding steals the user\'s screen+keyboard and is allowed ONLY when the USER explicitly asked to SEE this window. If they did: re-call with foreground:true + foregroundReason:"<quote/paraphrase what the user said>" (min 10 chars — it is recorded and auditable). If they did not: leave it background; browser_alert_window is the correct "it\'s ready" signal.' : '';           const bgHint = foreground             ? 'Opened in the FOREGROUND as EXPLICITLY requested (foreground/raise/show:true). Return it to the background with browser_lower_os_window once the user is done watching.'             : `Opened in the BACKGROUND (behind the user's windows, did NOT steal focus)${sized ? ' — and placed at the requested size/position WITHOUT foregrounding, so framing it for a screenshot never disturbs the user' : ''}. This is the HARD default so pup never disrupts the user's main work. It is FULLY drivable here: browser_screenshot / browser_eval / browser_navigate all work while it stays hidden. ONLY bring it to the user's screen if they EXPLICITLY want to WATCH (a demo, a recording, a "show me") — pass foreground:true on open (or call browser_raise_os_window). Sizing alone does NOT foreground anymore.`;@@ -3893,7 +3912,8 @@ const server = http.createServer(async (req, res) => {               // v1.8.16: reuse/ownership verdict (null = fresh window).               reused: reuse ? { navigatedAway: reuse.navigatedAway, previousUrl: reuse.previousUrl, previousOwner: reuse.previousOwner, takeover: reuse.takeover } : null,               owner: session.owner || null,-              _hint: `${bgHint}${ownHint} ${brep._hint}${staleWindowsHint()}`,+              foregroundDenied: fgDenied ? 'foreground_reason_required' : undefined,+              _hint: `${fgDenyHint}${bgHint}${ownHint} ${brep._hint}${staleWindowsHint()}`,               ...info,             }),           });@@ -4219,6 +4239,25 @@ const server = http.createServer(async (req, res) => {             return;           }           const session = sessions.get(sessionId);+          // v1.8.70: THE FOREGROUND GATE (mirrors abe's userRequestedForeground+foregroundReason+          // dual key — same contract across Adom's browser surfaces). Raising steals the user's+          // screen and keyboard; it is allowed ONLY as a user-requested show-me, and the caller+          // must SAY SO in a recorded, auditable reason. Real incident: a thread raised a window+          // 2 minutes after a background open and the only forensics were a focus-latch+          // timestamp — never again.+          const fgReason = (typeof args.foregroundReason === 'string' && args.foregroundReason.trim().length >= 10) ? args.foregroundReason.trim() : null;+          if (!fgReason) {+            sendJSON(res, {+              success: false,+              errorCode: 'foreground_reason_required',+              error: 'Raise refused: foregroundReason is required.',+              _hint: 'Foregrounding steals the user\'s screen and keyboard focus. It is allowed ONLY when the USER explicitly asked to SEE this window (a "show me", a demo, a live recording). Call again with foregroundReason:"<quote or closely paraphrase what the user said that justifies this>" (min 10 chars) — the reason is logged, recorded in lastAgentUpdate, and auditable by the user. If the user did NOT ask to see it, do NOT raise: use browser_alert_window (taskbar nudge) or rely on the auto-flash. After a granted raise: do the one thing the user asked for, then browser_lower_os_window to return it to the background.',+            });+            return;+          }+          console.log(`[foreground] "${sessionId}" raise GRANTED — reason: ${fgReason}`);+          session._lastForeground = { ts: Date.now(), verb: command, reason: fgReason };+          try { recordAgentUpdate(session, command, { updateNote: `FOREGROUND: ${fgReason}` }, session.activeTabId); } catch (e) {}           try {             // v1.8.26: background windows launch OFF-SCREEN (-32000). To actually SHOW one,             // move it back onto the primary monitor + maximize it (via CDP, no OS activation)