import type { CdpPage, ElementInfo, PageInfo, PageText, PageLink } from './cdp'; import { type NetworkEntry, type ConsoleEntry, type WebSocketFrame, type NetworkLogStatus } from './network-log'; import { type ReadStagedResult, type FillExcelResult } from './xlsx-template'; import { type LoginResult, type PerformLoginOptions, type TypeResult } from './login'; import { type FillOtpOptions, type FillOtpResult } from './otp'; import { type NativeDialogState, type PagePaginationState, type PageSnapshot, type WaitForKind } from './page-context'; import { type PageEvent } from './page-events'; import { type RefElement } from './refs'; import { type ChallengeResolution, type ChallengeState } from './challenge'; /** * Persistent Chrome profile for the AUTO-ANSWER browser (research reads, * `browse --auto-answer`, the web-auto-answer tool). * * That browser is long-lived and human-facing: the human watches it work and * answers on-screen questions in it, so it must never be closed by the bridge. */ export declare const DEFAULT_BROWSER_PROFILE_DIR: string; /** CDP port for the AUTO-ANSWER browser (unchanged — it is the one we keep). */ export declare const AUTO_ANSWER_CDP_PORT = 9222; /** * CDP port for the DEBUG browser (MCP `browser_open`/`browser_action`). * * SEPARATION (2026-09): the debug browser and the auto-answer browser used to * share port 9222 AND the same profile dir, so they were the SAME Chrome * process. That made "close the debug browser when the task ends" impossible to * implement safely — it would have killed the auto-answer run the human was * watching. They now live on separate ports with separate profiles, so the * debug browser can be closed without touching the auto-answer one. */ export declare const DEBUG_CDP_PORT = 9333; /** Separate user-data-dir for the debug browser (see DEBUG_CDP_PORT). */ export declare const DEBUG_PROFILE_DIR: string; export interface BrowserSessionOptions { /** CDP port (default DEBUG_CDP_PORT = 9333). */ port?: number; /** * Launch Chrome when nothing is listening (default true). * * Auto-launch is now the DEFAULT: an agent calling `browser_open` on a PC with * no debug Chrome got "not reachable" and could do nothing about it. When * autoLaunch is explicitly false we still auto-launch on a failed probe — an * explicit false must not be a dead end, it is only a hint. */ autoLaunch?: boolean; /** Run headless when auto-launching (default false: a visible window). */ headless?: boolean; /** Persistent user-data-dir when auto-launching (default the debug profile). */ profileDir?: string; /** Test-account label this window belongs to (2026-11, one window per identity). */ actor?: string | null; /** Force an isolated per-session profile, never shared (2026-11). */ isolated?: boolean; /** Extra Chrome args for auto-launch. */ chromeArgs?: string[]; /** * OPT-IN (2026-10): reduce the automation fingerprint. Drops the * Puppeteer-style launch flags, disables `AutomationControlled` and injects * the pre-document shims before any page script runs. Off by default. */ stealth?: boolean; /** * OPT-IN (default false): permit typing into password/credential fields. * * The debug/MCP browser is an agent-driven QA browser, so a QA task that * needs a sign-in must be able to enter credentials. This is a deliberate * opt-in - `browser_open({ allowCredentials: true })` - never a default, and * the auto-answer browser (a different code path) is unaffected. When false, * `type()` keeps throwing `LOGIN_BLOCKED` for a credential field. */ allowCredentials?: boolean; /** * OPT-IN (default false): QA VISION mode (2026-10). * * When on, every mutating action result carries an inline screenshot (the * bridge handler captures it) and `snapshot({refs:true})` can hand back an * accessibility-style ref list. Only a QA run turns it on * (`browser_open({ qaVision: true })`, instructed by the QA brief), so the * interactive browser and the auto-answer path are unchanged. */ qaVision?: boolean; } export declare class BrowserSession { private readonly id; private page; private chrome; private _port; private _autoLaunch; private _headless; private _profileDir; private _chromeArgs; /** Opt-in fingerprint reduction (see BrowserSessionOptions.stealth). */ private _stealth; private _connected; /** Opt-in credential entry (see BrowserSessionOptions.allowCredentials). */ private _allowCredentials; /** Opt-in QA vision mode (see BrowserSessionOptions.qaVision). */ private _qaVision; /** * The last ref scan (2026-10). Kept so a stale ref can be explained and, * when a unique same-role/same-name element exists in the fresh scan, * transparently re-pointed - instead of failing with a mute miss. */ private _lastRefs; /** * True when THIS bridge process launched the Chrome this session is attached * to. Only such a browser may be terminated by the bridge; one the human * started (or the auto-answer browser) is never killed by us. */ private _ownedByBridge; /** Test-account label this window is tagged for (2026-11). Never changes hands. */ private _actor; /** * Request/response + console evidence for the whole session (QA). Attached * on both connect paths; the agent reads it with `browser_action * { 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; /** * Per-host challenge cooldown (2026-10): after a failed bounded attempt the * same host is NOT re-attempted for 10 minutes. Without this an agent loop * could sit on a challenge page forever, which is exactly what the human * sees as "stuck trying Cloudflare". */ private _challengeCooldown; 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; /** Whether this session launched with the opt-in stealth shims. */ get stealth(): boolean; /** * Turn on the opt-in stealth shims for a LIVE session (2026-10). The launch * flags cannot change after Chrome started, but the pre-document shims can be * registered now (future navigations) and applied to the current document. */ enableStealth(): Promise; /** The test-account label this window is tagged for (2026-11). */ get actor(): string | null; /** Tag an untagged window. A tagged window never changes hands. */ setActor(actor: string | null | undefined): void; /** * 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; /** * Toggle QA vision mode (2026-10). Persists across actions, exactly like * allowCredentials: `browser_open({ qaVision: true })` sets it once. */ setQaVision(on: boolean): void; get qaVision(): 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. */ get lastUsedAt(): number; /** Stamp activity. Called by the manager on every browser command. */ touch(): void; /** Whether the session has an active CDP connection. */ get connected(): boolean; /** The CDP port this session targets. */ get port(): number; /** The underlying page handle (for advanced use). */ get cdpPage(): CdpPage | null; /** * True when the bridge launched this session's Chrome and may therefore close * it. False for a Chrome the human started — the single most important * invariant here, because the human may be watching/using that window. */ get ownedByBridge(): boolean; /** * Connect to Chrome, launching a VISIBLE instance when nothing is listening. * * Auto-launch is the default (2026-09): `browser_open` on a PC with no debug * Chrome used to fail with "not reachable", which an agent could do nothing * about. `autoLaunch: false` is now a hint, not a dead end — we still launch, * because the alternative is a browser tool that simply cannot work. * * OWNERSHIP: a Chrome we launch is ours to close (`ownedByBridge`); one the * human started is NOT — we connect to it and never terminate it. */ connect(port?: number): Promise; /** * Connect to a specific tab by targetId. */ connectToTab(targetId: string): Promise; /** * 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; }>; /** * Current pagination state (controls, page, page size, total, rows). * Scoped to the top dialog by the page-state script. */ pagination(): Promise; /** Stable-ish signature used to prove a page actually changed. */ private paginationSignature; private waitPaginationChange; private clickPagination; /** Move to the next page (or Load more) and wait for the content to change. */ nextPage(timeoutMs?: number): Promise<{ moved: boolean; elapsedMs: number; state: PagePaginationState; reason?: string; }>; /** Move to the previous page. */ prevPage(timeoutMs?: number): Promise<{ moved: boolean; elapsedMs: number; state: PagePaginationState; reason?: string; }>; /** Go to a numbered page; walks next if the page control is not rendered. */ gotoPage(page: number, timeoutMs?: number): Promise<{ moved: boolean; elapsedMs: number; state: PagePaginationState; reason?: string; }>; /** Select a native page-size option (custom comboboxes use click + waitFor). */ setPageSize(size: number): Promise<{ ok: boolean; state: PagePaginationState; error?: string; }>; /** * Read the current table (headers + rows), then walk every page and return * the deduplicated rows. Bounded by maxPages/maxRows; stops on a repeated * page signature, a disabled pager, or an unchanged table. */ collectTable(opts?: { selector?: string; maxPages?: number; maxRows?: number; pageSize?: number; }): Promise<{ headers: string[]; rows: string[][]; rowCount: number; pagesVisited: number; total?: number; complete: boolean; duplicates: number; truncated: boolean; stoppedBecause: string; }>; navigate(url: string, opts?: { autoChallenge?: boolean; challengeTimeoutMs?: number; }): Promise; /** Detect a Cloudflare / CAPTCHA challenge on the live page (cheap, safe). */ detectChallenge(): Promise; /** * One bounded challenge attempt (2026-10): a single click for a Turnstile * widget, passive wait for a managed challenge, nothing for a block/image * CAPTCHA. Callers stop and ask a human when `passed` is false. */ resolveChallenge(opts?: { attempt?: boolean; timeoutMs?: number; }): Promise; /** * Poll only (no click). Used after a human answered a `CHALLENGE_REQUIRED` * pause: the human solved it in the visible window; this waits for the page * to clear and returns the new screen. */ waitForChallenge(opts?: { timeoutMs?: number; attempt?: boolean; }): Promise; /** * Set the browser viewport before a design-verification screenshot * (2026-11): the design's viewport IS the contract — a pixel diff at any * other size measures the window, not the design. Applies * Emulation.setDeviceMetricsOverride on the live target and reads the * viewport back, so the caller knows what the page actually reports * (a clamped value is still a successful, truthful set). */ setViewport(width: number, height: number, deviceScaleFactor?: number): Promise<{ width: number; height: number; deviceScaleFactor: number; }>; /** * Capture a screenshot. Returns base64-encoded data. */ screenshot(format?: 'jpeg' | 'png', quality?: number): Promise; /** * Capture a screenshot with numbered ref labels drawn over the interactive * elements, then remove the overlay (2026-10). One image shows the page AND * names every target; the page is never left modified. */ annotatedScreenshot(format?: 'jpeg' | 'png', quality?: number): Promise; /** * Read the network + console evidence collected for this session (QA). * `onlyProblems` narrows to failures/redirects; `clear` advances the read * cursor (history is never deleted); `since`/`afterId`/`offset` page it. */ networkLog(opts?: { limit?: number; clear?: boolean; onlyProblems?: boolean; maxBodyChars?: number; offset?: number; since?: number; afterId?: string; }): Promise<{ requests: NetworkEntry[]; console: ConsoleEntry[]; websockets: WebSocketFrame[]; status: NetworkLogStatus; truncated?: boolean; bodyCap?: number; }>; /** * Bounded per-action network delta (2026-10): the API requests that started * at/after `since`, newest last. Attached to every mutating action result * so the agent sees the rejected OTP POST (or any API mismatch) without a * second `networkLog` call. */ networkDelta(since: number, limit?: number): Promise<{ requests: Array<{ method: string; url: string; status?: number; failed?: string; blockedReason?: string; durationMs?: number; requestBody?: string; responseBody?: string; }>; pendingRequests: number; }>; /** * Click at (x, y) CSS pixels. Coordinates OUTSIDE the current viewport are * refused loudly — a screenshot pixel is not a CSS pixel (the capture is * device-scale), so clicking one lands on the wrong element. */ click(x: number, y: number): Promise; /** * Click by reference instead of raw coordinates: an element REF (`e7`, from * getRefs / snapshot refs:true), explicit x/y, a fresh `getElements` index, * or a CSS selector resolved in-page. Coordinates from a screenshot image are * NEVER accepted here — they are device-scale. */ clickRef(ref: { ref?: string; x?: number; y?: number; elementIndex?: number; selector?: string; }): Promise<{ x: number; y: number; refreshedFrom?: string; }>; /** * Fresh element-ref scan (2026-10). * * Returns the interactive elements of the CURRENT page as `e1 … eN` with * role, accessible name, state and CSS-pixel centre. Includes elements * inside portalled menus/popovers/dialogs, which is the whole point: a kebab * menu that just opened is findable without guessing a selector. * * `filter` (2026-11) narrows by substring over role + name + tag, so * `getRefs {filter:"button"}` answers "all buttons" without a second scan. * Refs are ALWAYS the full-scan numbering — a filtered view never renumbers, * or a ref from the list would not resolve. */ getRefs(filter?: string): Promise<{ at: number; count: number; refs: RefElement[]; lines: string[]; filter?: string; }>; /** * Resolve a ref to a clickable point. A ref whose node left the DOM is * either re-pointed at a UNIQUE same-role/same-name element from a fresh * scan (the common case: a re-render replaced the node), or refused with * `REF_STALE` - never silently clicked at stale coordinates. */ private resolveRefPoint; /** Move the pointer to (x, y) without clicking (hover menus/tooltips). */ hover(x: number, y: number): Promise; /** Hover an element by ref (preferred) or CSS selector. */ hoverRef(ref: { ref?: string; selector?: string; }): Promise<{ x: number; y: number; refreshedFrom?: string; }>; /** * Click a ref'd element with the IN-PAGE pointer sequence instead of a CDP * coordinate click (2026-10). This is the rescue for a control that ignores * a normal click (the Radix lesson from the web tours: some activators only * react to a full pointerdown/mousedown gesture). Explicit, never automatic: * a blind second click after "nothing happened" could double-submit a form. */ clickPointerRef(ref: string): Promise<{ x: number; y: number; }>; /** * Focus an element by ref (2026-10). Reports whether focus actually moved: * a plain div without tabindex cannot take focus, and claiming `ok:true` * while the active element is unchanged is how a QA step "passes" having * done nothing. */ focusRef(ref: string): Promise<{ ok: boolean; alive: boolean; tag?: string; contentEditable?: boolean; refreshedFrom?: string; }>; /** * Close whatever menu/popover layer is open (2026-10): Escape first (Radix * DismissableLayer), then a document-level outside pointer sequence for * layers that ignore Escape. Reports what is left, so a "still open" menu is * visible instead of silently swallowing the next click. */ closePopup(): Promise<{ closed: boolean; popoversLeft: number; }>; private countPopovers; /** * Type text at the current cursor position, VERIFYING it landed. * * A password/credential field is refused with `LOGIN_BLOCKED` unless the * caller opted in (`browser_open({ allowCredentials: true })`) AND passed a * credential for the run - the debug browser is the QA surface, the * auto-answer loop is a separate path that still never touches credentials. * * An insert the page does not reflect is refused with `TYPE_NOT_VERIFIED` * (carrying the observed field state) — never reported as success. */ type(text: string, opts?: { clearFirst?: boolean; }): Promise; /** * Fill a segmented OTP / one-time-code widget digit-by-digit (2026-10). * * Detects the group by shape (N visible single-char inputs), clears every * cell, types one digit per cell with verification, waits for the site's * auto-submit sensor, and only clicks submit when it did not fire. */ fillOtp(opts: FillOtpOptions): Promise; /** * Deterministically fill a login form (username + password) and submit. * Handles the common two-step email -> Continue -> password flow. Requires * `allowCredentials` (opt-in). The password is never logged or returned. */ login(opts: PerformLoginOptions): Promise; /** * Reset the session between test accounts (2026-11): clears cookies + * storage for the current origin so the next `login` starts signed out. * Same session, no reconnect — deterministic account switching for * invitation flows. */ clearSession(): Promise<{ ok: boolean; error?: string; }>; /** * Press a keyboard key (Enter, Tab, Escape, etc.). */ press(key: string): Promise; /** * Scroll the page by delta (positive = down). */ scroll(delta: number): Promise; /** * Read the current page's text (prefers article/main). Text-only: cheap * token-wise, works on JS-heavy/blocked pages where web_fetch fails. */ getText(maxChars?: number): Promise; /** Extract links (href + text) - used to find downloadable document URLs. */ getLinks(): Promise; /** Read title + url + text + links in one round trip (research default). */ readPage(maxChars?: number): Promise; /** * Evaluate JavaScript in the page context. */ evaluate(expression: string): Promise; /** * Attach a staged file to a file input on the page. * * The path MUST live inside the run's staging directory - see * `stage-file.ts`. `DOM.setFileInputFiles` hands an absolute path to Chrome, * so without that confinement a caller could attach ANY file on the user's * disk. * * Generator form (QA, 2026-10): when `filePath` is absent but `generate` * carries bytes, the file is staged first and attached in the same call — * the agent never handles a path at all. */ attachFile(runId: string, filePath: string, selector?: string, generate?: { fileName?: string; html?: string; pdf?: boolean; text?: string; data?: string; }): Promise<{ ok: boolean; path?: string; error?: string; }>; /** * Manufacture a file inside the run's staging directory (QA, 2026-10). * * Exactly one source wins: `html` (rendered to PNG, or PDF with * `pdf: true`, in the debug browser itself), `text` (CSV/TSV/JSON written * verbatim), or `data` (base64 bytes, e.g. a screenshot the agent just * took). The agent never writes to the user's disk directly — every byte * lands in `~/.teamshare/runs//`, the only place `attachFile` reads * from. */ stageFile(opts: { runId: string; fileName?: string; html?: string; pdf?: boolean; text?: string; data?: string; }): Promise<{ ok: boolean; path?: string; fileName?: string; bytes?: number; error?: string; }>; /** * Download a template file into the run's staging directory (QA, 2026-10). * With `url`: a throwaway tab (same profile, login holds) fetches it while * the driven page stays put. Without `url`: waits for a download the agent * already triggered on the driven page. */ downloadFile(opts: { runId: string; url?: string; timeoutMs?: number; }): Promise<{ ok: boolean; path?: string; fileName?: string; bytes?: number; error?: string; }>; /** * Read a staged file back (QA, 2026-10): spreadsheets as header-keyed * rows, text formats as text. The agent reads the template BEFORE filling * it, so column names come from the file, never from a guess. */ readStagedFile(opts: { runId: string; filePath: string; sheet?: string; maxRows?: number; }): Promise; /** * Fill a COPY of a staged spreadsheet template (QA, 2026-10): `cells` * writes exact addresses, `rows` appends header-keyed objects after the * last used row. The original download is untouched, so a retry starts * clean; styles, formulas and validation survive. */ fillExcel(opts: { runId: string; templatePath: string; fileName?: string; cells?: Record; rows?: Array>; sheet?: string; }): Promise; /** * Submit the form on the page (the form that has a submit control). */ submit(selector?: string): Promise<{ ok: boolean; error?: string; }>; /** * Get the list of interactive DOM elements. */ getElements(): Promise; /** * Get current page info. */ pageInfo(): Promise; /** * 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; /** Also return the interactive element refs (QA vision, 2026-10). */ refs?: boolean; }): Promise; /** * 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 | 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 | null; nativeDialog: NativeDialogState | null; }>; /** * Wait for the screen to settle after an action (2026-11, qaVision only). * * The auto-answer loop re-captures context + screenshot on every iteration * and aborts its vision call on material change; the QA browser used to * return the screen MID-TRANSITION (click → compactSnapshot immediately). * This waits for a real navigation, an SPA route change, or a material DOM * change, then for a short quiet window (no new mutations, network idle-ish) * before the caller reads the screen. Bounded (~4 s default) and * best-effort: a timeout resolves with what is known, never a failure. */ waitForScreenSettle(opts?: { since?: number; quietMs?: number; timeoutMs?: number; fromUrl?: string; }): Promise<{ changed: boolean; navigated: boolean; fromUrl: string | null; toUrl: string | null; elapsedMs: number; }>; /** * Re-attach to the debug Chrome after the page died (2026-10). * * Same as `connect()` with the session's stored port/profile: reuses a * live Chrome when one is listening, auto-launches otherwise (honouring * the session's own autoLaunch/headless/profileDir). Called at most ONCE * per batch by `executeBatch` — never in a loop, so a dead Chrome cannot * turn one tool call into a relaunch storm. */ reconnect(): Promise; /** * Detect the active code editor on the page. */ detectEditor(): Promise<{ type: string; selector: string; } | null>; /** * Focus an element by CSS selector. */ focus(selector: string): Promise; /** * Release the CDP connection. The Chrome window stays open — the human may be * looking at it or signed into it. */ disconnect(): void; /** * Close the debug browser this session OWNS. * * Terminates the Chrome process only when the bridge launched it * (`_ownedByBridge`); a Chrome the human started is left running and only * disconnected. Now async and VERIFIED: the kill goes through * `killChromeOnPort` (graceful, then forced, then "is the port quiet?") and * the return value says whether the browser actually went away. A bare * `child.kill()` on the detached launcher used to report success while the * browser carried on running. */ closeOwned(): Promise; private ensureConnected; }