Interaction

Interaction tools let your agent click buttons, fill forms, select dropdowns, type with realistic delays, upload files, and submit forms. All element targeting uses @ref IDs from the DOM snapshot. Some tools accept force: true to override hidden/disabled visibility checks when needed.

browse_click

Click an interactive element by its @ref ID from the snapshot. If the element is a link, follows it and returns the new page snapshot.

Looks up the element via __wraith_ref_index, calls focus(), click(), and dispatches a bubbling click Event. If the element has an href, reports the link URL. Falls back to basic click_element() on JS failure.

Parameters

Request

{
  "tool": "browse_click",
  "arguments": {
    "ref_id": 3
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "Clicked @e3 (button \"Submit\")\n\nPage: \"Thank You\" (https://example.com/thank-you)\n\n@e1   [link]   \"Return Home\" href=/\n\n1 interactive element"
    }
  ]
}

browse_fill

Fill a form field with text, replacing any existing content. React-compatible -- uses the native value setter, _valueTracker invalidation, and direct onChange dispatch through the React fiber tree.

Parameters

Behavior

1. Looks up element via __wraith_get_by_ref(ref_id)
2. Calls focus() on the element
3. Uses Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set to handle React-controlled inputs
4. Invalidates React's _valueTracker (forces React to see the change)
5. Dispatches focus, input, change, blur events (bubbling)
6. Walks the React fiber tree looking for __reactProps$ or __reactFiber$ to call onChange directly
7. Reads back the value to verify it persisted -- reports verified or UNVERIFIED

Request

{
  "tool": "browse_fill",
  "arguments": {
    "ref_id": 5,
    "text": "Jane Smith"
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "@e5: FILLED (native_events, verified): Jane Smith"
    }
  ]
}

browse_type

Type text with realistic per-character keystroke delays. Use this instead of browse_fill when the site watches for individual keydown/keyup events (e.g., autocomplete inputs, search-as-you-type fields).

Parameters

Behavior

Focuses the element, then for each character: appends to .value and dispatches an input event. After all characters: dispatches change and blur events.

Request

{
  "tool": "browse_type",
  "arguments": {
    "ref_id": 8,
    "text": "remote rust developer",
    "delay_ms": 75
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "@e8: TYPED 21 chars with 75ms delay: remote rust developer"
    }
  ]
}

browse_select

Select an option in a native <select> dropdown by its value.

Parameters

Behavior

Looks up the element, focuses it, sets .value, and dispatches change and input events.

Request

{
  "tool": "browse_select",
  "arguments": {
    "ref_id": 12,
    "value": "US"
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "@e12: SELECTED \"US\" (United States)"
    }
  ]
}

browse_hover

Hover over an element by its @ref ID. Triggers CSS :hover styles and JavaScript mouseover/mouseenter handlers. Useful for revealing hidden menus, tooltips, or dropdown panels.

Parameters

Request

{
  "tool": "browse_hover",
  "arguments": {
    "ref_id": 7
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "Hovered @e7 (div \"Account Menu\")"
    }
  ]
}

browse_key_press

Press a keyboard key on the current page. Dispatches keydown, keypress, and keyup events.

Parameters

Request

{
  "tool": "browse_key_press",
  "arguments": {
    "key": "Enter"
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "Pressed key: Enter"
    }
  ]
}

browse_scroll

Scroll the page viewport. See the Navigation reference for full details.

browse_scroll_to

Scroll to center a specific element. See the Navigation reference for full details.

browse_custom_dropdown

Interact with a non-native dropdown or combobox component (React, Greenhouse, MUI, etc.). Handles the open-type-click pattern that custom dropdowns use instead of native <select> elements.

Parameters

Behavior

1. Clicks the trigger element to open the dropdown panel
2. Types the value string to filter the options list
3. Finds the matching option element in the resulting listbox
4. Clicks it and reports whether an exact match was found

Request

{
  "tool": "browse_custom_dropdown",
  "arguments": {
    "ref_id": 14,
    "value": "United States"
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "@e14: SELECTED custom dropdown option \"United States\" (exact match)"
    }
  ]
}

browse_dismiss_overlay

Dismiss a modal, overlay, popup, or cookie banner that is blocking interaction. Automatically finds the close/dismiss/accept button within the overlay and clicks it.

Parameters

Request — auto-detect

{
  "tool": "browse_dismiss_overlay",
  "arguments": {}
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "Dismissed overlay: cookie consent banner (clicked \"Accept All\")\n\nPage: \"Careers\" (https://example.com/careers)\n\n@e1   [link]   \"Software Engineer\" href=/careers/12345\n@e2   [link]   \"Product Manager\" href=/careers/67890\n\n2 interactive elements"
    }
  ]
}

Request — specific overlay

{
  "tool": "browse_dismiss_overlay",
  "arguments": {
    "ref_id": 22
  }
}

browse_upload_file

Upload a file from disk to an <input type="file"> element on the current page. Reads the file, base64-encodes it, and injects it via JavaScript using the DataTransfer API. Handles hidden file inputs commonly used by modern web applications.

Parameters

Behavior

1. Reads file from disk and base64-encodes it
2. Looks up element by ref_id, or scans all input[type="file"] nodes (including hidden ones)
3. Creates File and DataTransfer objects in QuickJS
4. Sets input.files = dt.files
5. Dispatches change and input events

Request

{
  "tool": "browse_upload_file",
  "arguments": {
    "file_path": "/home/user/resume.pdf",
    "ref_id": 48
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "OK: uploaded resume.pdf (11403 bytes) to @e48"
    }
  ]
}

browse_submit_form

Submit a form by clicking its submit button or calling form.submit(). ATS-aware -- detects supported applicant tracking systems and POSTs to the correct API endpoint with the right content type.

Parameters

Behavior

• If ref_id points to a button: clicks it
• If ref_id points to a <form>: calls form.submit()
• If ref_id points to any element inside a form: submits the parent form
• For ATS platforms: serializes all form fields, constructs the correct API endpoint and content type (multipart, form-urlencoded, or JSON), and POSTs with proper Origin/Referer headers

Request

{
  "tool": "browse_submit_form",
  "arguments": {
    "ref_id": 25
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "Form submitted (7 fields) via POST to https://api.example.com/v1/applications\nContent-Type: multipart/form-data\nHTTP 200 OK\n\nPage: \"Application Received\" (https://example.com/thank-you)\n\n@e1   [link]   \"Return to Careers\" href=/careers\n\n1 interactive element"
    }
  ]
}

browse_solve_captcha

Solve a CAPTCHA on the current page using a third-party solving service (2captcha). Supports reCAPTCHA v3 and Cloudflare Turnstile. Auto-detects the site key from the page if not provided. Requires the TWOCAPTCHA_API_KEY environment variable.

Parameters

Request

{
  "tool": "browse_solve_captcha",
  "arguments": {
    "captcha_type": "turnstile"
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "CAPTCHA solved (turnstile). Token injected into page. Site key: 0x4AAAAAAABkMYinukE8nzYS (auto-detected). Solve time: 12.4s"
    }
  ]
}

Additional Interaction Tools

browse_fetch_scripts

Fetch and execute external <script src="..."> tags from the current page. Call this after browse_navigate when you need React/Vue/Angular to mount for form filling to work properly. Downloads JavaScript bundles and runs them in QuickJS so React's event system activates.

No parameters (accepts optional max_bytes to limit total download size, default 2MB).

browse_login

Full login flow with redirect chain following. Navigates to the login page, fills credentials, clicks submit, and follows the entire OAuth/auth redirect chain (302 -> 302 -> 200). Captures all Set-Cookie headers at every redirect hop.

browse_eval_js

Execute JavaScript code on the current page in the QuickJS context and return the result.