NB - Native Browser Bridge

@@ -1802,6 +1802,8 @@ const VERB_META = {   nbrowser_demo: { hint: 'ONE-CALL SHOWCASE of layer 2: picks a live profile, opens a representative page in the user\'s REAL signed-in browser (background + badged), and returns that exact window\'s hwnd/tabId plus a screenshot delivered as a file (fullPath; ab pulls it to you) with per-step progress. Built for embedding "drive my real browser" in a web demo without any window hunting.', related: ['nbrowser_state', 'nbrowser_open_window', 'nbrowser_close_window'], pitfalls: ['it OPENS a real window on the user\'s desktop - clean up with nbrowser_close_window {sessionId} (default "nbdemo") when the demo ends', 'idempotent: re-running closes its previous demo window first', 'needs nbe connected in some profile - if readiness says needs-extension it returns no drivable profile'] },   nbrowser_uninstall: { hint: 'CASCADE HOOK, not for normal use: ab calls this itself during bridge_uninstall (ab 2.0.35+) with {cascade:true} BEFORE deleting the bridge cache, so nb can remove artifacts that live outside it - above all the HKCU native-messaging host registration, which would otherwise leave every profile dialing a deleted binary forever ("Native host has exited"). Also clears ~/.adom/bridges/native-browser, the activity trail, and the icon cache.', related: ['nbrowser_readiness'], pitfalls: ['you almost never call this directly - run ab\'s bridge_uninstall and let it cascade', 'it deliberately does NOT remove the nbe extension from the user\'s browser (their profile, their choice) - it only stops working; use uninstalling-the-extension to remove it properly', 'best-effort by contract: a failure here still lets ab delete the cache, so check removed[]/failed[] rather than assuming'] },   nbrowser_dev_reload: { hint: 'MAINTAINER-only: reload the extension to pick up on-disk code changes (2-pass, reconnects in ~10s).', related: ['nbrowser_status'], pitfalls: ['throttled to 1/90s (a reload restarts the SW + native host)', 'not for normal driving - only after editing the extension source', 'reloads ONE profile; other profiles pick up the new code on their own next reload'] },+  nbrowser_export_site_session: { hint: "Carry ONE site's live session out of the user's REAL signed-in browser so another tool ON THE SAME MACHINE (pup) can act as them there, without a password and without a fresh sign-in (adom/nb-bridge#54). Needs {domain, confirm:true, reason}. The cookie VALUES are never in the reply: they are written owner-only to a machine-local file and you get a handoffPath plus counts, because a secret in a reply is a secret in an AI transcript. Pass the path to the local tool, then nbrowser_drop_handoff.", related: ['nbrowser_login_state', 'nbrowser_profiles', 'nbrowser_drop_handoff'], pitfalls: ['ASK THE USER FIRST, naming the site: this lets another tool act as them there. confirm:true is your attestation that they said yes', 'ONE registrable domain per call - there is deliberately no "export everything"', 'the handoff file lives on the USER\'S machine, not in your container: do not try to read it from an AI thread, hand the path to the local tool', 'if the profile has no cookies for the domain you get no_session - the user may be signed in under a DIFFERENT profile (nbrowser_profiles)', 'it expires in 10 minutes and nbrowser_drop_handoff removes it sooner - do that as soon as the import is done'] },+  nbrowser_drop_handoff: { hint: 'Delete a secret-handoff file created by nbrowser_export_site_session, as soon as the local tool has read it. Read-only otherwise; it never returns the contents.', related: ['nbrowser_export_site_session'], pitfalls: ['dropped:false just means it was already consumed or expired, which is the safe outcome', 'this is the cleanup half of the export - call it rather than leaving a session file sitting on the user\'s disk'] },   nbrowser_clear_cookies: { hint: 'Background logout: drop a site\'s cookies (incl. httpOnly) for ONE registrable domain, leaving other sites (e.g. Google SSO) intact.', related: ['nbrowser_login_state'], pitfalls: ['scoped to one domain so it never nukes unrelated sessions', '⚠️ do NOT use this to log OUT of a site that ties device-trust to cookies (e.g. Gusto) - it forces a fresh 2FA; use the site\'s own Sign out'] },   nbrowser_caption: { hint: 'Paint an on-page caption (subtitle or red alert banner) for demos/narration.', related: ['nbrowser_cursor'], pitfalls: ['only on a window you opened', 'pass action:"hide" or empty text to dismiss'] },   nbrowser_focus: { hint: 'Select a tab within its window + flash its taskbar button. Does NOT raise the window unless you justify a foreground (userRequestedForeground:true + foregroundReason).', related: ['nbrowser_flash', 'nbrowser_screenshot'], pitfalls: ['does NOT foreground by design - the user\'s focus is never stolen; capture in place with nbrowser_screenshot', 'to actually raise it you must justify + warn the user (ab notify) first'] },@@ -2015,6 +2017,16 @@ function dispatch(verb, args) {     // nbrowser_chrome_status - READ-ONLY: is native Chrome installed / how's an in-flight install going?     // nbrowser_prewarm - ab calls this once per installed version (~20s after the first boot after an install     // or update; adom/nb-bridge#50). nb has no assets to fetch; what is worth doing early is the tally.+    // nb-bridge#54: delete a handoff the moment the local tool has read it, instead of waiting for the TTL.+    if (verb === 'nbrowser_drop_handoff') {+      const id = String((args && args.handoffId) || '');+      if (!/^[a-z]+-\d+-[0-9a-f]{12}$/.test(id)) return resolve({ success: false, errorCode: 'bad_handoff_id', error: 'handoffId required, as returned by the verb that created it' });+      const file = path.join(SECRET_DIR, `${id}.json`);+      let existed = false; try { existed = fs.existsSync(file); if (existed) fs.unlinkSync(file); } catch {}+      sweepSecrets();+      return resolve({ success: true, output: JSON.stringify({ ok: true, dropped: existed, handoffId: id,+        _hint: existed ? 'The handoff file is gone. Do this as soon as the local tool has imported it; otherwise it self-deletes on its TTL.' : 'Nothing to drop: it was already consumed or expired. That is the safe outcome.' }) });+    }     if (verb === 'nbrowser_prewarm') {       let inv; try { inv = nbeInventory(); } catch (e) { return resolve({ success: false, error: 'inventory failed: ' + String((e && e.message) || e) }); }       const t = inv.tally;@@ -2140,6 +2152,8 @@ function dispatch(verb, args) {         d('nbrowser_login_form', 'Detect a login form\'s state (already autofilled? SSO? 2FA?) and recommend the smartest path. ALWAYS call this before driving a login.', { sessionId: S }, { ok: 'bool', hasForm: 'bool', autofilled: 'bool', sso: 'bool', needs2FA: 'bool', recommendation: 'str' }, 30, { statusVerb: null, example: { sessionId: 's1' } }),         d('nbrowser_autologin', 'Fill and submit a saved-credential login. The bridge injects the laptop-decrypted secret directly; the agent NEVER sees it. Gated on confirm:true + host.', { sessionId: S, host: 'required str (e.g. "gusto.com")', confirm: 'required true', username: 'optional str' }, { ok: 'bool', loggedIn: 'bool', needs2FA: 'bool' }, 60, { example: { sessionId: 's1', host: 'gusto.com', confirm: true } }),         d('nbrowser_download', 'Download a URL to the user\'s real Downloads folder via chrome.downloads (lands on the LAPTOP, not the container).', { sessionId: S, url: 'required str', filename: 'optional str', saveAs: 'optional bool' }, { ok: 'bool', downloadId: 'int', filename: 'str?' }, 60, { statusVerb: 'nbrowser_download_wait', example: { sessionId: 's1', url: 'https://example.com/datasheet.pdf' } }),+        d('nbrowser_export_site_session', "Carry ONE site's live session out of the user's real browser for another tool on the SAME machine (pup). Values are written machine-locally, never returned.", { domain: 'required str (e.g. "x.com")', confirm: 'required true (the user said yes)', reason: 'required str (what it is for)', profile: P }, { ok: 'bool', domain: 'str', cookieCount: 'int', authCookieCount: 'int', handoffId: 'str', handoffPath: 'str (on the USER\'s machine)', expiresInSec: 'int' }, 30, { example: { domain: 'x.com', confirm: true, reason: 'carry the signed-in session into pup so it can post as the user' } }),+        d('nbrowser_drop_handoff', 'Delete a handoff file once the local tool has imported it.', { handoffId: 'required str' }, { ok: 'bool', dropped: 'bool' }, 15, { example: { handoffId: 'session-1790000000000-0a1b2c3d4e5f' } }),         d('nbrowser_clear_cookies', 'Background logout: drop one registrable domain\'s cookies (incl. httpOnly), leaving other sites (e.g. Google SSO) intact.', { host: 'required str (e.g. "gusto.com"; url/domain also accepted)' }, { ok: 'bool', removed: 'int', hosts: '[str]' }, 30, { example: { host: 'gusto.com' } }),         d('nbrowser_caption', 'Paint an on-page caption (subtitle, or red alert banner) for demos and narration.', { sessionId: S, text: 'required str (or action:"hide")', style: 'optional "subtitle"(default)|"alert"', position: 'optional str', fontSize: 'optional int', pulse: 'optional bool', durationMs: 'optional int (default 5000)', action: 'optional "hide"' }, { ok: 'bool', tabId: 'str', style: 'str' }, 20, { example: { sessionId: 's1', text: 'Signing in to DigiKey' } }),         d('nbrowser_cursor', 'Show or move the gliding Adom cursor with an intent label (demo narration). Visual only, it does not click.', { sessionId: S, action: 'optional "move"(default)|"hide"', x: 'optional int', y: 'optional int', label: 'optional str (or intent)' }, { ok: 'bool', tabId: 'str', action: 'str', label: 'str' }, 20, { example: { sessionId: 's1', x: 400, y: 300, label: 'Clicking Sign in' } }),@@ -3058,8 +3072,48 @@ function identityOf(key) {   return { profile: key, email: (c.profile && c.profile.email) || '', displayName: (kp && kp.displayName) || profileLabel(c.profile) || null,     profileDir: (kp && kp.profileDir) || av.profileDir || null, browser: (c.profile && c.profile.browser) || 'chrome' }; }+// SECRET HANDOFF (adom/nb-bridge#54). A session carried out of the user's real browser must reach the+// OTHER LOCAL TOOL (pup) WITHOUT crossing the relay: the AI that asked usually runs in a container, and+// the moment a cookie value lands in a tool result it is in a transcript, a log and a context window.+// So the bridge writes the values to a machine-local file, owner-only, and returns a HANDLE plus counts.+// The file self-deletes after SECRET_TTL_MS, and nbrowser_consume_session deletes it on read.+const SECRET_DIR = path.join(os.homedir(), '.adom', 'bridges', BRIDGE, 'handoff');+const SECRET_TTL_MS = 10 * 60 * 1000;+function sweepSecrets() {+  try {+    for (const f of fs.readdirSync(SECRET_DIR)) {+      const fp = path.join(SECRET_DIR, f);+      try { if (Date.now() - fs.statSync(fp).mtimeMs > SECRET_TTL_MS) fs.unlinkSync(fp); } catch {}+    }+  } catch {}+}+function writeSecretHandoff(kind, meta, secret) {+  fs.mkdirSync(SECRET_DIR, { recursive: true, mode: 0o700 });+  sweepSecrets();+  const id = `${kind}-${Date.now()}-${crypto.randomBytes(6).toString('hex')}`;+  const file = path.join(SECRET_DIR, `${id}.json`);+  fs.writeFileSync(file, JSON.stringify({ id, kind, ...meta, createdAt: new Date().toISOString(), ...secret }), { mode: 0o600 });+  try { fs.chmodSync(file, 0o600); } catch {}+  setTimeout(() => { try { fs.unlinkSync(file); } catch {} }, SECRET_TTL_MS).unref?.();+  return { handoffId: id, handoffPath: file, expiresInSec: Math.round(SECRET_TTL_MS / 1000) };+} async function decorateReply(p, frame, payloadIn, setPayload) {   let payload = payloadIn;+      // A verb that carries a secret hands it to the machine, not to the caller (nb-bridge#54).+      if (payload && payload._secret) {+        const secret = payload._secret;+        const out = { ...payload }; delete out._secret;+        try {+          const h = writeSecretHandoff(p.verb === 'nbrowser_export_site_session' ? 'session' : 'secret',+            { verb: p.verb, domain: out.domain || null, profile: p.profileKey || null, reason: (p.args && p.args.reason) || null }, secret);+          payload = { ...out, ...h,+            _hint: `The session for ${out.domain} was written to a file on the USER'S MACHINE, owner-only, and is NOT in this reply: cookie values must never cross the relay into an AI transcript. ` ++              `Hand handoffPath to the tool that runs on that machine (pup reads it and imports), then it is gone - the file self-deletes in ${h.expiresInSec}s or when nbrowser_consume_session reads it. ` ++              `You can see ${out.cookieCount} cookie(s), ${out.authCookieCount} of them auth-shaped, and nothing else.` };+        } catch (e) {+          payload = { ...out, ok: false, errorCode: 'handoff_failed', error: `could not write the local handoff file: ${String((e && e.message) || e)}` };+        }+      }       // The identity this call acted as, on every window/tab open (nb-bridge#53).       if ((p.verb === 'nbrowser_open_window' || p.verb === 'nbrowser_open_tab' || p.verb === 'nbrowser_open_os_window') && payload && payload.ok !== false) {         const id = identityOf(p.profileKey);