teamshare-bridge 0.26.11 → 0.26.13

package/dist/lib/browser/page-events.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Persistent page-event buffer for the debug browser (2026-10).
+ *
+ * WHY THIS EXISTS. The auto-answer browser scrapes toasts/errors at capture
+ * time, and the debug browser had NOTHING: a toast that appeared after a form
+ * submit and vanished two seconds later was invisible to an agent that only
+ * looked on its next tool call. In the live Soludesks QA run the agent spent
+ * minutes re-reading the DOM for a dialog/error that had already been shown.
+ *
+ * This module injects a tiny, idempotent MutationObserver into the page that
+ * records toast / alert / status / dialog events in a bounded ring buffer
+ * (`window.__tsPageEvents`). It is installed:
+ *   - immediately when a session connects,
+ *   - on every new document via `Page.addScriptToEvaluateOnNewDocument`,
+ *   - again after a main-frame navigation (belt and braces).
+ *
+ * The script is dependency-free and returns a string so it can be injected
+ * with `Runtime.evaluate` or registered as a new-document script. It never
+ * reads field values and never logs anything.
+ */
+/** Maximum events retained in the page ring buffer (oldest dropped). */
+export declare const PAGE_EVENT_LIMIT = 80;
+export interface PageEvent {
+    /** toast | alert | status | error | dialog | dialog-closed */
+    type: string;
+    text: string;
+    /** epoch ms, page clock */
+    at: number;
+    role?: string;
+    count?: number;
+}
+/**
+ * Build the injected page-event script.
+ *
+ * IMPORTANT: regex escapes must be DOUBLE-escaped inside this template literal
+ * (`\\s`), otherwise the injected JS receives `s` (the exact bug the bridge lint
+ * gate found in another injected script).
+ */
+export declare function buildPageEventScript(): string;

package/dist/lib/browser/page-events.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Persistent page-event buffer for the debug browser (2026-10).
+ *
+ * WHY THIS EXISTS. The auto-answer browser scrapes toasts/errors at capture
+ * time, and the debug browser had NOTHING: a toast that appeared after a form
+ * submit and vanished two seconds later was invisible to an agent that only
+ * looked on its next tool call. In the live Soludesks QA run the agent spent
+ * minutes re-reading the DOM for a dialog/error that had already been shown.
+ *
+ * This module injects a tiny, idempotent MutationObserver into the page that
+ * records toast / alert / status / dialog events in a bounded ring buffer
+ * (`window.__tsPageEvents`). It is installed:
+ *   - immediately when a session connects,
+ *   - on every new document via `Page.addScriptToEvaluateOnNewDocument`,
+ *   - again after a main-frame navigation (belt and braces).
+ *
+ * The script is dependency-free and returns a string so it can be injected
+ * with `Runtime.evaluate` or registered as a new-document script. It never
+ * reads field values and never logs anything.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAGE_EVENT_LIMIT = void 0;
+exports.buildPageEventScript = buildPageEventScript;
+/** Maximum events retained in the page ring buffer (oldest dropped). */
+exports.PAGE_EVENT_LIMIT = 80;
+/**
+ * Build the injected page-event script.
+ *
+ * IMPORTANT: regex escapes must be DOUBLE-escaped inside this template literal
+ * (`\\s`), otherwise the injected JS receives `s` (the exact bug the bridge lint
+ * gate found in another injected script).
+ */
+function buildPageEventScript() {
+    return `
+    (() => {
+      if (window.__tsEventInstalled) return 'already';
+      window.__tsEventInstalled = true;
+      const MAX = ${exports.PAGE_EVENT_LIMIT};
+      const events = [];
+      window.__tsPageEvents = events;
+      const clean = (v) => String(v == null ? '' : v).replace(/\\s+/g, ' ').trim().slice(0, 500);
+      const now = () => Date.now();
+      const vis = (el) => {
+        if (!el || el.nodeType !== 1) return false;
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 || r.height === 0) return false;
+        const cs = getComputedStyle(el);
+        return cs.visibility !== 'hidden' && cs.display !== 'none' && cs.opacity !== '0';
+      };
+      const push = (type, text, extra) => {
+        const t = clean(text);
+        if (!t || t.length < 2) return;
+        const last = events[events.length - 1];
+        if (last && last.type === type && last.text === t && now() - last.at < 1200) return;
+        const row = { type: type, text: t, at: now() };
+        if (extra) { if (extra.role) row.role = extra.role; if (extra.count != null) row.count = extra.count; }
+        events.push(row);
+        if (events.length > MAX) events.splice(0, events.length - MAX);
+      };
+      const TOAST_SEL = '[role="alert"],[role="status"],[aria-live],[data-sonner-toast],' +
+        '[class*="toast"],[class*="Toast"],[class*="snackbar"],[class*="Snackbar"],' +
+        '[class*="notification"],[class*="Notification"],[class*="alert"],[class*="Alert"],' +
+        '[class*="banner"],[class*="Banner"]';
+      const kindOf = (el) => {
+        const role = String((el.getAttribute && el.getAttribute('role')) || '').toLowerCase();
+        const cls = String((el.className && typeof el.className === 'string') ? el.className : '') + ' ' + String(el.id || '');
+        const live = String((el.getAttribute && el.getAttribute('aria-live')) || '').toLowerCase();
+        if (role === 'alert' || /error|danger|invalid/i.test(cls)) return 'error';
+        if (/toast|snackbar|notification/i.test(cls)) return 'toast';
+        if (role === 'status' || live === 'polite' || live === 'assertive') return 'status';
+        if (/alert|banner/i.test(cls)) return 'alert';
+        return null;
+      };
+      const record = (el) => {
+        if (!el || el.nodeType !== 1 || !vis(el)) return;
+        // A container that holds a nested toast should not be recorded as a
+        // second, duplicate event; use the deepest matching node.
+        const nested = el.querySelector && el.querySelector(TOAST_SEL);
+        if (nested && nested !== el) return;
+        const kind = kindOf(el);
+        if (!kind) return;
+        const text = el.innerText || el.textContent || el.getAttribute('aria-label') || '';
+        push(kind, text, { role: String((el.getAttribute && el.getAttribute('role')) || '') });
+      };
+      const scan = (root) => {
+        if (!root || root.nodeType !== 1) return;
+        if (root.matches && root.matches(TOAST_SEL)) record(root);
+        if (root.querySelectorAll) {
+          const nodes = root.querySelectorAll(TOAST_SEL);
+          for (let i = 0; i < nodes.length && i < 12; i++) record(nodes[i]);
+        }
+      };
+      const dialogs = () => [...document.querySelectorAll('dialog[open],[role="dialog"],[aria-modal="true"]')].filter(vis);
+      let dialogCount = dialogs().length;
+      const topDialogText = () => {
+        const list = dialogs();
+        const el = list[list.length - 1];
+        return el ? clean(el.innerText || el.textContent || '') : '';
+      };
+      const obs = new MutationObserver((mutations) => {
+        for (const m of mutations) {
+          if (m.type === 'childList') {
+            for (const n of m.addedNodes) if (n && n.nodeType === 1) scan(n);
+          } else if (m.type === 'characterData') {
+            const p = m.target && m.target.parentElement;
+            if (p) scan(p);
+          }
+        }
+        const count = dialogs().length;
+        if (count !== dialogCount) {
+          if (count > 0) push('dialog', topDialogText(), { count: count });
+          else push('dialog-closed', 'dialog closed', { count: 0 });
+          dialogCount = count;
+        }
+      });
+      const root = document.documentElement || document.body;
+      if (root) {
+        obs.observe(root, { childList: true, subtree: true, characterData: true });
+        // Record anything already on screen once (a login modal that opened
+        // before this script ran).
+        scan(document.body || root);
+      }
+      return 'ok';
+    })()
+  `;
+}
+//# sourceMappingURL=page-events.js.map

package/dist/lib/browser/page-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-events.js","sourceRoot":"","sources":["../../../src/lib/browser/page-events.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAsBH,oDA6FC;AAjHD,wEAAwE;AAC3D,QAAA,gBAAgB,GAAG,EAAE,CAAC;AAYnC;;;;;;GAMG;AACH,SAAgB,oBAAoB;IAClC,OAAO;;;;oBAIW,wBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFjC,CAAC;AACJ,CAAC"}

package/dist/lib/browser/screen-change.js

@@ -117,6 +117,9 @@ function buildObserverScript() {
         });
         lastText = getText();
         window[KEY] = { observer: obs, changed: 0, mutated: 0 };
+        // String-addressable alias for OTHER injected scripts (the debug
+        // browser's waitFor reads it; a Symbol is not reachable by name).
+        window.__tsScreenObs = window[KEY];
         obs.observe(document.body || document.documentElement, {
           childList: true, subtree: true, characterData: true
         });

package/dist/lib/browser/screen-change.js.map

@@ -1 +1 @@
-{"version":3,"file":"screen-change.js","sourceRoot":"","sources":["../../../src/lib/browser/screen-change.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAcH,kDAkBC;AAOD,sDAIC;AAQD,kDA8DC;AA/GD,0EAA0E;AAC7D,QAAA,uBAAuB,GAAG,EAAE,CAAC;AAE1C;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,QAAgB,EAChB,QAAgB;IAEhB,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACpB,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM;gBAAE,OAAO,EAAE,CAAC;;gBACpD,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/D,OAAO,KAAK,GAAG,EAAE,GAAG,OAAO,GAAG,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CACnC,MAA4D;IAE5D,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB;IACjC,OAAO;;;;;sCAK6B,mBAAmB,CAAC,QAAQ,EAAE;;;;;;;;;;;;;;;;qDAgBf,+BAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAuCvE,CAAC;AACN,CAAC"}
+{"version":3,"file":"screen-change.js","sourceRoot":"","sources":["../../../src/lib/browser/screen-change.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAcH,kDAkBC;AAOD,sDAIC;AAQD,kDAiEC;AAlHD,0EAA0E;AAC7D,QAAA,uBAAuB,GAAG,EAAE,CAAC;AAE1C;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,QAAgB,EAChB,QAAgB;IAEhB,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACpB,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM;gBAAE,OAAO,EAAE,CAAC;;gBACpD,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/D,OAAO,KAAK,GAAG,EAAE,GAAG,OAAO,GAAG,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CACnC,MAA4D;IAE5D,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB;IACjC,OAAO;;;;;sCAK6B,mBAAmB,CAAC,QAAQ,EAAE;;;;;;;;;;;;;;;;qDAgBf,+BAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0CvE,CAAC;AACN,CAAC"}

package/dist/lib/browser/session-pool.d.ts

@@ -0,0 +1,44 @@
+/** 9222 belongs to the auto-answer browser; the debug pool never uses it. */
+export declare const AUTO_ANSWER_PORT = 9222;
+/** Normalize an explicit session name, or null when it carries nothing. */
+export declare function normalizeSessionKey(raw: unknown): string | null;
+/**
+ * The session key a command runs against.
+ *
+ * Explicit name > the caller's identity (`agent:<userId>`), so two agents on one
+ * PC never collide and a later action without a sessionId still lands on the
+ * browser its own `browser_open` created.
+ */
+export declare function deriveSessionKey(explicit: unknown, agentUserId: string | null | undefined): string;
+/** Filesystem-safe, collision-resistant slug for a session's profile dir. */
+export declare function sessionSlug(key: string): string;
+/**
+ * The first free debug port at or above `preferred`.
+ *
+ * Returns null when the whole span is taken (a machine running that many
+ * browsers needs a human, not a guess).
+ */
+export declare function pickDebugPort(preferred: number, used: Iterable<number>, span?: number): number | null;
+export interface ProfileChoice {
+    dir: string;
+    /** True when this session got the shared debug profile. */
+    shared: boolean;
+    /** Set when a NAMED profile is already owned by another live session. */
+    conflict?: string;
+}
+/**
+ * Pick a user-data-dir for a session.
+ *
+ * `baseDir` is the shared debug profile (`~/.teamshare/chrome-profile-debug`).
+ * The FIRST live session keeps it (so logins persist exactly as before); any
+ * additional concurrent session gets `…-sessions/<slug>`, because Chrome cannot
+ * run two processes on one user-data-dir. A caller-supplied named profile is
+ * exclusive: a second session asking for the same name is refused rather than
+ * silently given different cookies.
+ */
+export declare function pickDebugProfileDir(opts: {
+    baseDir: string;
+    sessionKey: string;
+    usedDirs: Iterable<string>;
+    namedDir?: string;
+}): ProfileChoice;

package/dist/lib/browser/session-pool.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_ANSWER_PORT = void 0;
+exports.normalizeSessionKey = normalizeSessionKey;
+exports.deriveSessionKey = deriveSessionKey;
+exports.sessionSlug = sessionSlug;
+exports.pickDebugPort = pickDebugPort;
+exports.pickDebugProfileDir = pickDebugProfileDir;
+/**
+ * Browser session identity + port/profile allocation (2026-10).
+ *
+ * WHY THIS EXISTS. Every browser command used to default to ONE session named
+ * `'default'`, so two QA runs on the same PC shared a single Chrome: the second
+ * `browser_open` silently attached to the first run's browser, and a
+ * `browser_close` could release the other run's session. The backend cannot fix
+ * this alone - the bridge owns the Chrome processes and the CDP ports - so the
+ * bridge derives a session per caller identity and allocates a free debug port
+ * + a separate profile when a second browser is genuinely needed.
+ *
+ * The rules:
+ *  - A session key is a NAME, never a path. Anything outside a small charset is
+ *    replaced, and the value is bounded.
+ *  - The caller's explicit `sessionId` wins; otherwise the agent/user identity
+ *    is the key. Same identity ⇒ same browser (a re-open reuses it).
+ *  - Ports: the requested debug port is used when no OTHER session owns it;
+ *    otherwise the next free port is allocated. 9222 (auto-answer) is never
+ *    chosen.
+ *  - Profiles: two Chromes cannot share a user-data-dir (Chrome's
+ *    SingletonLock forwards to the running instance), so the first session gets
+ *    the shared debug profile and each extra concurrent session gets its own
+ *    persistent profile directory. Named profiles stay exclusive.
+ *
+ * Everything here is pure so it can be unit-tested without Chrome.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+/** 9222 belongs to the auto-answer browser; the debug pool never uses it. */
+exports.AUTO_ANSWER_PORT = 9222;
+const MAX_SESSION_KEY = 80;
+const PORT_SPAN = 20;
+/** Normalize an explicit session name, or null when it carries nothing. */
+function normalizeSessionKey(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const clean = trimmed
+        .replace(/[^a-zA-Z0-9:_.-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, MAX_SESSION_KEY);
+    return clean || null;
+}
+/**
+ * The session key a command runs against.
+ *
+ * Explicit name > the caller's identity (`agent:<userId>`), so two agents on one
+ * PC never collide and a later action without a sessionId still lands on the
+ * browser its own `browser_open` created.
+ */
+function deriveSessionKey(explicit, agentUserId) {
+    const named = normalizeSessionKey(explicit);
+    if (named)
+        return named;
+    const user = normalizeSessionKey(agentUserId);
+    return user ? `agent:${user}` : 'default';
+}
+/** Filesystem-safe, collision-resistant slug for a session's profile dir. */
+function sessionSlug(key) {
+    const safe = key
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40);
+    const hash = (0, node_crypto_1.createHash)('sha1').update(key).digest('hex').slice(0, 8);
+    return `${safe || 'session'}-${hash}`;
+}
+/**
+ * The first free debug port at or above `preferred`.
+ *
+ * Returns null when the whole span is taken (a machine running that many
+ * browsers needs a human, not a guess).
+ */
+function pickDebugPort(preferred, used, span = PORT_SPAN) {
+    const taken = new Set(used);
+    if (preferred !== exports.AUTO_ANSWER_PORT && !taken.has(preferred))
+        return preferred;
+    for (let i = 1; i <= span; i++) {
+        const candidate = preferred + i;
+        if (candidate > 65535)
+            break;
+        if (candidate === exports.AUTO_ANSWER_PORT)
+            continue;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Pick a user-data-dir for a session.
+ *
+ * `baseDir` is the shared debug profile (`~/.teamshare/chrome-profile-debug`).
+ * The FIRST live session keeps it (so logins persist exactly as before); any
+ * additional concurrent session gets `…-sessions/<slug>`, because Chrome cannot
+ * run two processes on one user-data-dir. A caller-supplied named profile is
+ * exclusive: a second session asking for the same name is refused rather than
+ * silently given different cookies.
+ */
+function pickDebugProfileDir(opts) {
+    const key = (p) => process.platform === 'win32' ? (0, node_path_1.resolve)(p).toLowerCase() : (0, node_path_1.resolve)(p);
+    const used = new Set([...opts.usedDirs].map(key));
+    if (opts.namedDir) {
+        if (used.has(key(opts.namedDir))) {
+            return { dir: opts.namedDir, shared: false, conflict: opts.namedDir };
+        }
+        return { dir: opts.namedDir, shared: false };
+    }
+    if (!used.has(key(opts.baseDir))) {
+        return { dir: opts.baseDir, shared: true };
+    }
+    const dir = (0, node_path_1.join)((0, node_path_1.dirname)(opts.baseDir), `${(0, node_path_1.basename)(opts.baseDir)}-sessions`, sessionSlug(opts.sessionKey));
+    if (used.has(key(dir))) {
+        return { dir, shared: false, conflict: dir };
+    }
+    return { dir, shared: false };
+}
+//# sourceMappingURL=session-pool.js.map

package/dist/lib/browser/session-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-pool.js","sourceRoot":"","sources":["../../../src/lib/browser/session-pool.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/session.d.ts

@@ -2,6 +2,8 @@ import type { CdpPage, ElementInfo, PageInfo, PageText, PageLink } from './cdp';
 import { type NetworkEntry, type ConsoleEntry } from './network-log';
 import { type ReadStagedResult, type FillExcelResult } from './xlsx-template';
 import { type LoginResult, type PerformLoginOptions } from './login';
+import { type NativeDialogState, type PageSnapshot, type WaitForKind } from './page-context';
+import { type PageEvent } from './page-events';
 /**
  * Persistent Chrome profile for the AUTO-ANSWER browser (research reads,
  * `browse --auto-answer`, the web-auto-answer tool).
@@ -78,13 +80,36 @@ export declare class BrowserSession {
      * { action: "networkLog" }` when it needs to prove an API mismatch.
      */
     private network;
+    /**
+     * The native alert/confirm/prompt/beforeunload currently blocking the page
+     * (2026-10). Captured from `Page.javascriptDialogOpening`; other actions are
+     * refused while it is set, and `browser_action({action:"dialog"})` resolves
+     * it. A native dialog blocks the renderer, so a page snapshot would hang.
+     */
+    private _nativeDialog;
     constructor(id: string, opts?: BrowserSessionOptions);
+    /** The stable session name the browser manager keys this session by. */
+    get sessionKey(): string;
+    /** The user-data-dir this session launches Chrome with. */
+    get profileDir(): string;
+    /**
+     * Reconfigure a DISCONNECTED session before reconnecting it (2026-10).
+     *
+     * The manager keeps one session per identity; a re-open after the browser died
+     * may need a different port (another agent took the old one) or a different
+     * profile (the shared debug profile is now owned by a concurrent session).
+     * Only launch-time options are touched - an open connection is never
+     * reconfigured underneath its page.
+     */
+    configure(opts: BrowserSessionOptions): void;
     /**
      * Toggle credential entry for this session. Persists across actions - a
      * `browser_open` sets it once and later `type`/`login` calls honour it.
      */
     setAllowCredentials(allow: boolean): void;
     get allowCredentials(): boolean;
+    /** The native JS dialog currently blocking the page, if any. */
+    get nativeDialog(): NativeDialogState | null;
     /** Last time a command actually used this session (drives idle close). */
     private _lastUsedAt;
     /** When this session was last used — the idle-close timer reads this. */
@@ -119,6 +144,37 @@ export declare class BrowserSession {
      * Connect to a specific tab by targetId.
      */
     connectToTab(targetId: string): Promise<PageInfo>;
+    /**
+     * Install the debug browser's page instrumentation (2026-10):
+     *
+     *  - the persistent toast/alert/dialog ring buffer (`page-events.ts`),
+     *    registered for FUTURE documents via
+     *    `Page.addScriptToEvaluateOnNewDocument` and injected into the current
+     *    one immediately;
+     *  - the screen-change observer (`__tsScreenObs.mutated`) so `waitFor
+     *    {for:"change"}` knows a click had an effect without a blind sleep;
+     *  - the native-dialog listener (`Page.javascriptDialogOpening`), because an
+     *    alert/confirm/prompt blocks the renderer and must be surfaced and
+     *    resolved explicitly.
+     *
+     * All pieces are idempotent in the page. The CDP listeners are bound once per
+     * page object (a reconnect creates a new one).
+     */
+    private instrumentPage;
+    /**
+     * Resolve a native JS dialog (alert/confirm/prompt/beforeunload).
+     * `accept:false` dismisses it; `promptText` is used by a prompt.
+     */
+    dialogAction(opts: {
+        accept?: boolean;
+        promptText?: string;
+    }): Promise<{
+        ok: boolean;
+        accepted?: boolean;
+        type?: string;
+        message?: string;
+        error?: string;
+    }>;
     /**
      * Navigate to a URL. Returns page info after navigation.
      */
@@ -153,7 +209,9 @@ export declare class BrowserSession {
      * credential for the run - the debug browser is the QA surface, the
      * auto-answer loop is a separate path that still never touches credentials.
      */
-    type(text: string): Promise<void>;
+    type(text: string, opts?: {
+        clearFirst?: boolean;
+    }): Promise<void>;
     /**
      * Deterministically fill a login form (username + password) and submit.
      * Handles the common two-step email -> Continue -> password flow. Requires
@@ -297,6 +355,62 @@ export declare class BrowserSession {
      * Get current page info.
      */
     pageInfo(): Promise<PageInfo>;
+    /**
+     * Full page state (2026-10): dialogs (topmost with buttons/fields), toasts
+     * (persistent buffer), visible errors, form fields (lengths only), focus,
+     * busy, headings, optional page text, pending requests and console errors.
+     *
+     * This is the debug browser's equivalent of the auto-answer loop's rich
+     * `extractPageContext` - and it is what lets an agent see a login modal
+     * instead of guessing with raw `evaluate`.
+     */
+    snapshot(opts?: {
+        includeText?: boolean;
+        maxTextChars?: number;
+        maxFields?: number;
+    }): Promise<PageSnapshot>;
+    /**
+     * Bounded state attached to every mutating action result. Never include the
+     * page text (that is what `snapshot` is for); a failure returns null so an
+     * action result is never failed by its own observation.
+     */
+    compactSnapshot(): Promise<Record<string, unknown> | null>;
+    /**
+     * Recent toast / alert / dialog events from the persistent page buffer.
+     * This is how a toast that disappeared before the next tool call is still
+     * visible.
+     */
+    events(opts?: {
+        limit?: number;
+        clear?: boolean;
+        since?: number;
+    }): Promise<{
+        events: PageEvent[];
+        count: number;
+    }>;
+    /**
+     * Wait until a page condition is true, then return the current screen.
+     *
+     * This replaces the manual `evaluate` polling loop the QA agent used to run
+     * (and which broke on "Inspected target navigated"). On timeout it returns
+     * `matched:false` WITH the current screen, so the caller can see why.
+     */
+    waitFor(opts: {
+        for: WaitForKind;
+        selector?: string;
+        text?: string;
+        urlIncludes?: string;
+        state?: 'open' | 'closed';
+        loginPhase?: 'username' | 'password' | 'otp' | 'done';
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<{
+        matched: boolean;
+        elapsedMs: number;
+        for: WaitForKind;
+        screen: Record<string, unknown> | null;
+        nativeDialog: NativeDialogState | null;
+    }>;
     /**
      * Is the page actually usable right now? (2026-10)
      *