// tool-globals.d.ts — generated by axon prepare, do not edit // Every tool the capsule can call, declared as it is callable. // Mirrors the block the model receives — same source, same members. declare global { type BrowserStatus = { readonly running: boolean readonly channel: string readonly headed: boolean readonly tabs: readonly (TabMetadata & { readonly dialog?: { readonly dialogId: string readonly type: string readonly message: string } })[] readonly downloads: number /** Notices produced while reading browser state during this call. */ readonly diagnostics: readonly DocumentDiagnostic[] /** Queued browser activity outside completed operations. Drained once on a successful status call. */ readonly backgroundDiagnostics: readonly ActivityDiagnostic[] } type TabMetadata = { /** Identifies the tab for subsequent browser tool calls. Persists across navigation; unusable after the tab closes. */ readonly tabId: string /** Current tab URL with credentials, fragment, and query values redacted. */ readonly url: string } & ({ /** The current page URL matches an effective permission rule. Omitted rules permit every URL. Embedded frames have separate authorization checks. */ readonly authorized: true /** Current page title; present only when authorized is true. */ readonly title: string /** Identifies the current main-page document/navigation state; present only when authorized is true. * Changes on main-frame navigation, including same-URL reloads and history URL changes. Child-frame changes do not affect it. */ readonly documentId: string } | { /** The current page URL does not match a configured permission rule. Page title and documentId are withheld. */ readonly authorized: false }) type DocumentDiagnostic = { /** Explanation of the notice. */ readonly message: string /** Redacted page/frame authorization context for this notice. */ readonly details: AccessDetails readonly request?: never readonly omissions?: never readonly maskedElements?: never } type AccessDetails = { /** Optional identifier of the associated tab. */ readonly tabId?: string /** URL involved in the notice, with credentials, fragment, and query values redacted. */ readonly attemptedUrl: string /** Documents whose URLs fail the configured permission rules. */ readonly blockedDocuments: readonly { /** Whether the document is the main page or a frame. */ readonly kind: "page" | "frame" /** Document URL with credentials, fragment, and query values redacted. */ readonly url: string /** Zero-based child-frame positions from the main page; [] denotes the main page. * For example, [0, 1] is the second child of the first frame. Positions can change. * Omitted when the document cannot be located in the current frame tree. */ readonly frameIndexPath?: readonly number[] }[] } type ActivityDiagnostic = DocumentDiagnostic | ActivityRequestDiagnostic type ActivityRequestDiagnostic = RequestDiagnostic & { /** Authorization context is always available for browser-activity request notices. */ readonly details: AccessDetails } type RequestDiagnostic = { /** Explanation of the notice. */ readonly message: string /** Redacted page/frame authorization context, when the request's tab is available. */ readonly details?: AccessDetails /** Metadata of the omitted request. */ readonly request: { /** Request URL with credentials, fragment, and query values redacted. */ readonly url: string /** HTTP request method. */ readonly method: string } readonly omissions?: never readonly maskedElements?: never } type NavigationResult = TabMetadata & ActionResult type ActionResult = { /** Notices generated during this operation. Later asynchronous notices are queued for browserStatus. */ readonly diagnostics: readonly ActivityDiagnostic[] } type Scope = { /** Existing tab ID returned by openTab or browserStatus. */ tabId: string /** Optional ordered selectors for frame elements, from the main document into nested frames; * omitted means the main document. Each selector uses Target syntax and must match exactly one frame element. * Every selected frame and its ancestors must have an allowed URL. */ framePath?: Target[] /** Optional selector for one container inside the selected frame. The target is searched inside that container. * Uses Target syntax and must match exactly one container. */ within?: Target } type Target = { /** CSS element selector, for example {css: "#submit"}. CSS engine chaining with >> is not supported. * Set exactly one of css, role, text, label, or placeholder on each Target. */ css?: string /** Accessible role, for example {role: "button", name: "Submit"}. name optionally filters the role by accessible name. */ role?: string /** Accessible name used to filter a role selector: the label exposed to assistive technology. */ name?: string /** Whether role/name, text, label, and placeholder matching requires the whole text (true, the default) * or permits substring matching (false). Does not affect CSS selectors or the role itself. */ exact?: boolean /** Select an element by its text. */ text?: string /** Select a form control by its associated label. */ label?: string /** Select an element by its placeholder text. */ placeholder?: string } type InspectionResult = TabMetadata & { readonly content: string readonly truncated: boolean /** Notices about embedded-host inspection or removed content from this read. */ readonly diagnostics: readonly InspectionDiagnostic[] } type InspectionDiagnostic = DocumentDiagnostic | SanitizationDiagnostic type SanitizationDiagnostic = { /** Explanation of the notice. */ readonly message: string /** Redacted page/frame authorization context for this notice. */ readonly details: AccessDetails /** Counts of content removed during text/HTML inspection. */ readonly omissions: { /** Number of removed elements. */ readonly elements: number /** Number of removed attributes. */ readonly attributes: number /** Number of removed comments. */ readonly comments: number } readonly request?: never readonly maskedElements?: never } type ScreenshotOptions = { tabId: string mode?: "viewport" | "fullPage" framePath?: never within?: never target?: never } | (Scope & { mode: "element" target: Target }) type ScreenshotResult = TabMetadata & { readonly captureId: string /** PNG bytes encoded as raw base64, without a data-URI prefix. No image file is saved. */ readonly base64: string readonly width: number readonly height: number readonly timestamp: string readonly offset: {readonly x: number; readonly y: number} /** Notices about password inputs masked in this screenshot. */ readonly diagnostics: readonly MaskingDiagnostic[] } type MaskingDiagnostic = { /** Explanation of the notice. */ readonly message: string /** Redacted page/frame authorization context for this notice. */ readonly details: AccessDetails /** Number of password inputs selected for masking in this screenshot. */ readonly maskedElements: number readonly request?: never readonly omissions?: never } type ActionOptions = WithoutDiscriminator> type ActionArgs = { discriminator: "typeText" tabId: string text: string } | (Scope & (({ discriminator: "click" button?: "left" | "right" | "middle" count?: 1 | 2 } & Destination) | ({ discriminator: "hover" } & Destination) | { discriminator: "fill" target: Target value: string } | { discriminator: "selectOptions" target: Target values: string[] } | { discriminator: "setChecked" target: Target checked: boolean } | { discriminator: "pressKey" target?: Target key: string } | ({ discriminator: "scroll" target?: Target } & ({ deltaX: number deltaY?: number } | { deltaX?: number deltaY: number })) | ({ discriminator: "drag" } & ({ from: ElementDestination to: ElementDestination } | { from: CoordinateDestination to: CoordinateDestination framePath?: never within?: never })) | ({ discriminator: "waitFor" } & ({ target: Target state?: "attached" | "detached" | "visible" | "hidden" urlPattern?: never } | { urlPattern: string target?: never state?: never framePath?: never within?: never })))) type Destination = ElementDestination | CoordinateDestination type ElementDestination = { point?: never captureId?: never /** Selector for one element inside the resolved scope. Must match exactly one element. */ target: Target } type CoordinateDestination = { target?: never framePath?: never within?: never point: { x: number y: number } captureId: string } type WithoutDiscriminator = T extends unknown ? Omit : never type DownloadRecord = { readonly id: string readonly tabId: string readonly url: string } & ({ readonly state: "completed" readonly path: string readonly filename: string } | { readonly state: "pending" } | { readonly state: "denied" | "failed" readonly diagnostic: DocumentDiagnostic }) type NetworkLogResult = { readonly events: readonly NetworkEvent[] readonly nextSequence: number readonly droppedEvents: number /** Notices about stored request metadata omitted by this read. */ readonly diagnostics: readonly RequestDiagnostic[] } type NetworkEvent = Readonly & { readonly sequence: number readonly timestamp: string readonly state: NetworkState } type RequestMetadata = { readonly requestId: string readonly tabId: string readonly url: string readonly method: string readonly resourceType: string status: number | null } type NetworkState = "started" | "responded" | "completed" | "failed" /** * Describes which website URLs this browser session permits to be viewed by you and which transfers are allowed. * The browser may contact other URLs, but you will be unable to inspect or interact with unauthorized documents. * Omitting rules disables URL-based restrictions. Otherwise, the first matching rule wins; permissions are not merged. Patterns match HTTP(S) scheme, hostname, port, and path. * A leading *. matches subdomains only; path * matches within one segment and ** spans segments. Queries and fragments do not affect matching. * @returns An ordered array of effective URL permission rules. When rules are omitted, returns one implicit "*" rule allowing every URL; uploads/downloads are enabled when the * corresponding module-level directory is configured. Each rule contains: * - `urlPattern`: Website URL pattern to which this rule applies; the first matching rule wins. * - `uploads`: Whether this rule allows uploading local files. * - `downloads`: Whether this rule allows saving downloaded files. * - `uploadRoot`: Resolved absolute upload directory, including an inherited module default; absent when uploads are disabled. * - `downloadDir`: Resolved absolute download directory, including an inherited module default; absent when downloads are disabled. * - `actionTimeoutMs`: Time limit in milliseconds for element actions and waits. * - `navigationTimeoutMs`: Time limit in milliseconds for explicit navigation. * @throws If the browser module configuration cannot be read or is invalid. */ function listBrowserRules(): Promise /** * Report this Axon session's browser state, existing tab IDs, and background browser diagnostics. * A successful call drains the background diagnostic queue separately. * @returns An object containing: * - `running`: Whether the browser is currently open. * - `channel`: Configured browser channel: chromium, chrome, or msedge. * - `headed`: Whether the browser is configured to have a visible window. * - `tabs`: Existing tabs, each containing TabMetadata and an optional pending dialog: * - `dialog`: Optional pending JavaScript dialog on an authorized tab. Use handleDialog before continuing actions in that tab. * Contains `dialogId` (identifier for handleDialog), `type` (alert, confirm, prompt, or beforeunload), and `message` (the displayed text). * - `downloads`: Number of recorded download attempts, including pending, denied, and failed attempts. * - `diagnostics`: Notices produced by this status call, such as withholding pending-dialog content on an unauthorized page. * - `backgroundDiagnostics`: Drained background notices about unauthorized documents, suppressed UI, denied/failed transfers, or omitted requests. * @throws If the browser state cannot be read. The thrown error includes only this call's diagnostic context; background notices remain queued for a successful status call. */ function browserStatus(): Promise /** * Close all tabs and the browser owned by this Axon session, releasing its running browser process. * The browsing profile (cookies, storage, and sign-in state) is retained until the Axon session ends. * A later {@link openTab} call in the same session reopens the browser using that profile. * Existing tab IDs and screenshot captures no longer identify usable tabs. Completed downloads are retained. * Closing an already closed browser is harmless. * @returns Nothing. * @throws If the browser cannot be closed. */ function closeBrowser(): Promise /** * Start this Axon session's browser if necessary and create a new tab, optionally navigating to a permitted website. * @param url - Optional absolute URL allowed by the effective URL policy (as described by {@link listBrowserRules}). Omit it to create an empty about:blank tab; that tab * can be inspected immediately when rules are omitted; with explicit rules, it must first navigate to an allowed URL. Redirects may land on an unauthorized page, whose * contents remain inaccessible. * @returns TabMetadata after opening the tab and completing requested navigation, plus diagnostics. An empty about:blank tab is authorized when rules are omitted. * - `diagnostics`: Array of notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed downloads, or omitted requests. * @throws If the URL is not allowed, the tab limit is reached, navigation fails, or browser startup fails. A failed navigation may leave the new tab open; browserStatus lists it. */ function openTab(url?: string): Promise /** * Close one existing tab, including a tab on a URL the agent is not permitted to inspect. * In headed mode this closes the tab for the user as well. It does not run beforeunload confirmation handlers. * The tab ID and its screenshot captures become unusable. * @param tabId - ID of the tab to close, obtained from openTab or browserStatus. * @returns Nothing. * @throws If the tab is unavailable or cannot be closed. */ function closeTab(tabId: string): Promise /** * Bring any existing tab to the foreground, making it the selected tab for the user in headed mode. * Does not navigate or inspect the page. Unauthorized tabs may be shown to the user. * In headless mode there is no reason to use this tool. * @param tabId - Existing tab ID returned by openTab or browserStatus. * @returns TabMetadata after bringing the tab forward. Unauthorized tabs return restricted metadata. * @throws If the tab is unavailable or cannot be brought forward. */ function showTab(tabId: string): Promise /** * Navigate an existing tab to an allowed website, or traverse/reload its browser history. * With explicit rules, destination URLs must match the user's configured browser URL permissions; omitted rules permit every URL (see {@link listBrowserRules}. * Redirects or history navigation may end at an unauthorized URL; the tab may remain there, but its content cannot be read or interacted with. * Completion waits for DOMContentLoaded, not for every image, request, or application update; use {@link waitFor} for a specific readiness condition. * @param tabId - Existing tab ID returned by openTab or browserStatus. * @param destination - An absolute URL allowed by the effective policy, or the literal "back", "forward", or "reload". * These commands move one history entry back/forward or reload the current document. * @returns TabMetadata after navigation reaches DOMContentLoaded, plus diagnostics. * - `diagnostics`: Array of activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function navigate(tabId: string, destination: string): Promise /** * Read an authorized web document or selected element as an accessibility snapshot, plain text, or sanitized HTML. * - ARIA describes accessible roles, names, states, and hierarchy, useful for finding controls to interact with. * - Text returns DOM textContent. * - HTML returns sanitized markup including the selected root tag. * @param options - Document scope, output format, and optional element selection. * @param options.target - Optional selector for one element to read. Must match exactly one element. If omitted, reads the within container itself when provided; otherwise reads the selected frame’s document body. * @param options.format - aria (default), text, or html. * ARIA requires all frames it may expose to be authorized as well. * Text/HTML remove nested scripts, styles, frames, embeds, objects, input[type=hidden] and input[type=password], comments, value/srcdoc attributes, and configured standard * event-handler attributes. Explicitly selected inline script/style elements may be read in text/HTML; nested script/style elements remain omitted. In HTML mode explicitly * selected, unauthorized iframe/frame/embed elements return the targets sanitized host tag/attributes with redacted source URL. * Text may include other hidden DOM text; it is not limited to visibly rendered text. * @param options.maxChars - Positive integer output character limit; default 20000, maximum 100000. Excess content is truncated. * @returns TabMetadata captured after reading the content, plus: * - `content`: Requested ARIA snapshot, plain text, or sanitized HTML string. * - `truncated`: Whether maxChars cut the content short. * - `diagnostics`: Array of notices produced by this inspection: embedded-host notices or text/HTML sanitization counts. * @throws If the target is missing/ambiguous, content is unauthorized, inspection times out, or the document changes. The thrown error includes this call's diagnostic context. */ function inspectPage(options: Scope & { format?: "aria" | "text" | "html"; target?: Target; maxChars?: number; }): Promise /** * Capture an authorized browser page or element and return its PNG bytes as a base64 string. * All page frames must be authorized under the configured URL rules (see {@link listBrowserRules}. * Password inputs are masked. * Captures exceeding 16 million pixels or 10 MiB fail. * @param options - Tab and screenshot mode; only element mode accepts frame/container scope and requires a target. Coordinates are measured in CSS pixels. * @param options.mode - viewport (default) captures the visible main-page viewport; fullPage captures the main page's scrollable area; element captures one selected element * and may scroll it into view. * @param options.framePath - Element mode only; see Scope for frame traversal and authorization. * @param options.within - Element mode only; narrows the target search as described by Scope. * @param options.target - Required and allowed only in element mode. Must match exactly one element. * @returns TabMetadata captured after taking the screenshot, plus: * - `captureId`: Identifies this observation. Only a current viewport captureId may be used for coordinate actions on the same tab. * Navigation, scrolling, or resizing invalidates it. * - `base64`: Raw base64-encoded PNG bytes without a data-URI prefix. * - `width`: Image width in pixels. * - `height`: Image height in pixels. * - `timestamp`: Capture time in ISO format. * - `offset`: Element bounding-box position in the viewport for element mode, or the recorded page scroll position otherwise. Contains: * - `x`: Horizontal position in CSS pixels. * - `y`: Vertical position in CSS pixels. * - `diagnostics`: Password-masking notices produced by this screenshot. * @throws If authorization fails, the capture is too large, the page changes, or capture fails. The thrown error includes this call's diagnostic context. */ function screenshot(options: ScreenshotOptions): Promise /** * Click an element or a point in a recently captured browser viewport. Can trigger navigation, downloads, popups, or dialogs. * The page and selected frame must be authorized. * Provide either target or both point and captureId. point is {x, y} measured in CSS pixels from the top-left of the main page viewport. * captureId must come from a current viewport screenshot of this same tab; navigation, scrolling, or resizing invalidates it. * Coordinate actions require every page frame to be authorized. * Clicking a file input requires uploadFiles to select files * @param options - Tab/frame scope, one target form, and optional mouse settings. * @param options.target - Element form only. Must match exactly one element; it is scrolled into view and waited on for click actionability. * @param options.point - Coordinate form only: {x,y} in the main-page viewport. Do not combine with target, framePath, or within. * @param options.captureId - Required with point; use captureId returned by a current viewport screenshot, not an arbitrary string. * @param options.button - left (default), right, or middle mouse button. * @param options.count - 1 (default) for a single click, or 2 for a double click. * @returns TabMetadata when the click finishes, plus diagnostics. Use waitFor for application readiness. * - `diagnostics`: Array of notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed downloads, or omitted requests. * @throws If the action fails. DIALOG_PENDING means a dialog must be handled using browserStatus and handleDialog; the click may already have happened. The thrown error includes * this call's diagnostic context. */ function click(options: ActionOptions<"click">): Promise /** * Replace all text in one authorized input, textarea, or contenteditable element. * The element is focused and its existing contents replaced. File inputs require uploadFiles instead. * @param options - Tab/frame scope, editable element, and replacement string. The page/frame must match * configured URL permissions. * @param options.target - Required editable-element selector. Must match exactly one element. * @param options.value - Complete replacement text; may be an empty string. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function fill(options: ActionOptions<"fill">): Promise /** * Insert literal text into the browser's currently focused editable control without clearing its existing contents. * This uses the current keyboard focus; it does not find or focus a target. The current page and every frame must be authorized. * @param options - Existing tab and literal text. Focus the intended control first, for example with click. * @param options.text - Literal string to insert at the current caret/selection. It does not clear the entire field or simulate per-character key presses. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function typeText(options: ActionOptions<"typeText">): Promise /** * Send one keyboard key or key chord to the authorized tab, optionally focusing an element first. * Useful for Enter to submit, Tab to move focus, arrow keys, Escape, or shortcuts such as Control+A. * Unlike {@link typeText}, key names are interpreted as keyboard input rather than inserted literally. * The current page and all frames must be authorized. * @param options - Tab/frame scope, optional focus target, and key/chord. * @param options.target - Optional element to focus before pressing the key; omit to use the current focus. Must match exactly one element when provided. * @param options.key - Key name, single character, or modifier chord. Each call presses and releases the key or chord. * - Common keys: Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown. * - Key ranges: F1-F12, KeyA-KeyZ, Digit0-Digit9. Punctuation and other supported key names are also accepted. * - Modifiers: Control, Alt, Shift, Meta, ControlOrMeta. ControlOrMeta selects Control on Windows/Linux and Meta on macOS. * - Chords: join modifiers and the final key with +, for example ControlOrMeta+A, Shift+Tab, or Control+Shift+T. * - Single characters are case-sensitive: a and A produce different text. * For an exhaustive list. See https://playwright.dev/docs/api/class-keyboard#keyboard-press. * @returns TabMetadata when the key action finishes, plus diagnostics. * - `diagnostics`: Array of activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed downloads, or omitted requests. * @throws If the action fails. DIALOG_PENDING can mean the key was already sent; inspect browserStatus and handle the dialog before retrying. The thrown error includes this * call's diagnostic context. */ function pressKey(options: ActionOptions<"pressKey">): Promise /** * Send mouse-wheel input to scroll the authorized page or the area under a selected element. * If target is given, the pointer is moved over it before sending wheel input. Without target, the wheel is sent at the pointer's current location. * The action may finish before smooth scrolling settles. * All page frames must be authorized. * @param options - Tab/frame scope, optional hover target, and wheel deltas. Supply at least one of deltaX or * deltaY. * @param options.target - Optional element to hover before scrolling. Must match exactly one element when provided. * @param options.deltaX - Horizontal wheel delta in CSS pixels: positive scrolls right, negative left; default 0. * @param options.deltaY - Vertical wheel delta in CSS pixels: positive scrolls down, negative up; default 0. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function scroll(options: ActionOptions<"scroll">): Promise /** * Move the mouse over an authorized element or a point from a recent viewport screenshot without clicking. * Can reveal menus, tooltips, and hover controls. Provide either target or both point and captureId. * point is {x, y} measured in CSS pixels from the top-left of the main page viewport. * captureId must come from a current viewport screenshot of this same tab; navigation, scrolling, or resizing invalidates it. * Coordinate actions require every page frame to be authorized. * @param options - Tab/frame scope and either element or screenshot-coordinate target. * @param options.target - Element form only. Must match exactly one element; it may be scrolled into view. * @param options.point - Coordinate form only: {x,y} in the main-page viewport. Do not combine with target, framePath, or within. * @param options.captureId - Required with point; use a current viewport screenshot's captureId for this same tab. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function hover(options: ActionOptions<"hover">): Promise /** * Choose options in one authorized native HTML select element using option values. * For a multi-select, provide several values; an empty array clears the selection where the control allows it. * Use {@link click}/{@link pressKey} for custom dropdown widgets. * @param options - Tab/frame scope, native select target, and requested values. The page/frame must be authorized. * @param options.target - Required selector for exactly one select element. * @param options.values - Array of option value strings (the option's value, not necessarily its visible label). A single-select normally takes one value. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function selectOptions(options: ActionOptions<"selectOptions">): Promise /** * Set an authorized checkbox or radio control to a requested checked state. If the control already has the desired state, it is left unchanged. * @param options - Tab/frame scope, checkbox/radio target, and desired state. The page/frame must be authorized. * @param options.target - Required selector for exactly one supported checkbox/radio control. * @param options.checked - true to check/select the control; false to uncheck a checkbox, does not work on radio inputs. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function setChecked(options: ActionOptions<"setChecked">): Promise /** * Drag from one authorized element to another, or between two points in the main-page viewport. * Use either two element destinations or two coordinate destinations; mixed forms are not supported. * Element mode uses drag-and-drop behavior between resolved elements. * Coordinate mode presses the mouse at the source, moves it to the destination, and releases it; every page frame must be authorized. * @param options - Existing tab, two destinations, and optional element-mode scope. * @param options.within - Optional container in which both element destinations are searched. * @param options.from - Source destination: {target: Target} in element mode, or {point:{x,y}, captureId} in coordinate mode. Element selectors must resolve uniquely. * @param options.to - Destination using the same form as from. * Each coordinate destination needs a current viewport captureId for this tab; x/y are CSS pixels from the main viewport's top-left. * Coordinate mode cannot use framePath or within. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function drag(options: ActionOptions<"drag">): Promise /** * Wait until an authorized element reaches a specified state, or until the main tab URL matches a pattern. Use target with optional state, or use urlPattern alone. * Waiting is bounded by the selected URL rule's actionTimeoutMs. * @param options - Existing tab and exactly one wait condition. * @param options.target - Element-wait form only. Select one intended element; the selector may match no element while waiting for hidden/detached. * @param options.state - Element-wait form only: attached means present in the DOM; detached means absent; visible (default) means present with a nonempty bounding box and not * visibility:hidden; hidden means detached or not visible. Opacity alone does not make an element hidden for this check. * @param options.urlPattern - URL-wait form only: absolute HTTP(S) pattern matching scheme, host, port, and path. * Leading *. matches subdomains only, path * stays within a segment, and ** spans segments; query/fragment values are ignored. * Do not combine with target, state, framePath, or within. * This checks only the main tab URL, not an iframe URL. It may finish immediately if the URL already matches. * The wait must begin on an authorized page but may succeed at an unauthorized destination without exposing its contents. * @returns TabMetadata when the wait finishes. * @throws On timeout or authorization failure. Element waits also throw if the document changes (navigation, url changes, frames attaching/detaching) while waiting. */ function waitFor(options: ActionOptions<"waitFor">): Promise /** * Accept or dismiss a pending JavaScript alert, confirm, prompt, or beforeunload dialog in an authorized tab. * Get dialogId, type, and message from {@link browserStatus}. * A pending dialog blocks further actions in that tab. * The tab and all its frames must be authorized. * This tool does not operate native OS file pickers, HTTP authentication prompts, or ordinary HTML modal elements. * Use {@link uploadFiles} for HTML file inputs and normal interaction tools for HTML modals. * @param tabId - Existing tab ID containing the pending dialog. * @param dialogId - Current dialog ID from {@link browserStatus}, not an arbitrary identifier. Stale or already handled IDs fail. * @param action - "accept" to confirm/close the dialog, or "dismiss" to cancel it. * @param text - Optional reply string used when accepting a prompt dialog; other dialog kinds do not use it. * @returns TabMetadata after handling the dialog. Page scripts or navigation may resume. * @throws If authorization fails, the dialog ID is stale/unavailable, or the dialog cannot be handled. */ function handleDialog(tabId: string, dialogId: string, action: "accept" | "dismiss", text?: string): Promise /** * Select local files in an authorized HTML input[type=file] control, making those file contents available to the website. * With explicit rules, the matching rule must enable uploads and provide uploadRoot directly or through the module default. * When rules are omitted, configuring module-level uploadRoot enables uploads for every page. See {@link listBrowserRules}. Files must be regular files inside that existing * directory, including after resolving symlinks; paths outside it are rejected. This does not support native File System Access pickers such as showOpenFilePicker or a button * that only opens a native chooser. * @param options - Tab/frame scope, an HTML file-input target, and local file paths. * @param options.target - Required selector for exactly one input[type=file] itself. * @param options.paths - File paths relative to the configured uploadRoot, or absolute paths that remain inside it. * Use several paths only if the input supports multiple files. An empty array clears the input's selected files. * @returns An object with a diagnostics array containing activity notices belonging to this call: unauthorized documents, suppressed dialogs/file choosers, denied/failed * downloads, or omitted requests. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function uploadFiles(options: Scope & { target: Target; paths: string[]; }): Promise /** * List file-download attempts observed during this browser session and discover saved local file paths. * Successful downloading requires downloads enabled for the owning tab's current page URL and the download URL itself. Embedded-frame downloads use the owning tab's * policy. Same-origin blob files use the owning page's download permission. downloadDir is the configured local destination directory and is created if missing. Saved files keep * their browser-suggested filename; an existing file causes failure. Human-triggered and delayed downloads use the same page permissions; no active tool call is required. * @param after - Optional download record ID from an earlier result; return records after that record. Omit to list from the beginning. * An unknown ID also starts from the beginning. * @param limit - Positive integer maximum number of records; default 100, maximum 500. * @returns An array of download attempts. Repeated calls can observe state changes. Each record contains: * - `id`: Identifies the download attempt; may be passed as after in a later listing. * - `tabId`: Identifies the tab that owns the download. * - `url`: Download URL with credentials, fragment, and query values redacted. * - `state`: pending while processing, completed after saving, denied for permission rejection, or failed for another error. * - `path`: Saved local file path; present only when state is completed. * - `filename`: Saved file name; present only when state is completed. * - `diagnostic`: Stored rejection/failure reason, present only when state is denied or failed. Reading records does not consume diagnostic events. * @throws If the listing limit is invalid. */ function listDownloads(after?: string, limit?: number): Promise /** * Read a bounded history of HTTP request lifecycle metadata from authorized browser documents. * URLs redact userinfo, query values, and fragments. * Requests from unauthorized or unattributable frames/workers are omitted, and records from tabs that are closed or currently unauthorized are hidden. * Omissions detected by this read appear in diagnostics; browserStatus collects notices from background network activity. This filtering does not block the browser's * actual network traffic. * @param options - Optional filters and pagination settings; omit to read retained events across all tabs. * @param options.tabId - Optional tab ID to filter events; omitted includes all currently eligible tabs. * @param options.after - Optional numeric event sequence, exclusive; default 0. Pass the previous result's nextSequence to request newer events. * This identifies a network event, not a mouse cursor or download record. * @param options.limit - Positive integer maximum number of events; default 100, maximum 500. * @returns An object containing: * - `events`: Eligible request events. One request may produce several events. Each event contains: * - `sequence`: Increasing network event identifier. * - `timestamp`: Time the event was recorded, in ISO format. * - `requestId`: Identifies the request, linking its lifecycle events. * - `tabId`: Identifies the request's tab. * - `url`: Request URL with credentials, fragment, and query values redacted. * - `method`: HTTP request method. * - `resourceType`: Request category, such as document, script, or fetch. * - `status`: HTTP response code when known; otherwise null. * - `state`: Request lifecycle state: started, responded, completed, or failed. * - `nextSequence`: Continuation position to pass as after in the next read. * - `droppedEvents`: Global history lost before the requested position because networkLogLimit was exceeded. * - `diagnostics`: Array of notices about stored request metadata omitted by this read. Authorization details may be absent when the tab is unavailable. * @throws If the operation fails. The thrown error includes this call's diagnostic context. */ function getNetworkLog(options?: { tabId?: string; after?: number; limit?: number; }): Promise } export {}

@lanthan/browser