Browser and source tools

A user can browse manually without giving a plugin browser access. Plugin actions use task-owned sessions and host review.

Open and read a page

const observed = await Hay.browser.open('https://example.com');

This needs browser.read and approval for the URL. It opens the page visibly and returns its visible text. Source capture and saved sources belong to the host; plugins do not get a raw HTTP client.

Observe and act

let page = await Hay.browser.create('https://example.com');
page = await Hay.browser.observe(page.sessionId);
const button = page.elements.find(item => item.label === 'Continue');
if (button?.actions.includes('click')) {
  await Hay.browser.act(page.sessionId, {
    snapshotId: page.snapshotId,
    kind: 'click', target: button.id
  });
  page = await Hay.browser.observe(page.sessionId);
}

Interactive methods need browser.control. create asks to open a task tab. Each action is reviewed against fresh observed state. Never invent element references or reuse a snapshot after an action.

act supports click, fill, key, and scroll. Keys are limited to Enter, Tab, Escape, the four arrow keys, Backspace and Space. Fill accepts plain text up to 4,000 characters. Private fields, credentials, and consequential account actions require the user to take over.

Sessions and images

browser.sessions() lists only the current workspace/plugin/task’s agent tabs. A task can open up to three. browser.screenshot(id) returns a bounded PNG data URL with width, height and capture time. browser.close(id) closes the agent tab.

Subscribe with browser.onChange(listener) and dispose the returned unsubscribe function. A slow operation in one tab does not queue unrelated chat or another tab.

Sign-ins and isolation

Cookies and site storage persist in a browser profile for each workspace. Closing an agent tab or stopping a task does not sign out. Tabs themselves are not restored after restart. The profile is separate from the user’s everyday browser, and some sites may restrict embedded sign-in.

Plugins do not receive cookies, passwords, browser storage, or the native bridge. Downloads, device permissions, invalid certificates, non-web protocols, and native desktop-control APIs are not exposed to plugins.

GitHub PR snapshots

Hay.github.readPullRequest(url) reads bounded GitHub.com PR metadata and patches with github.read plus approval. {authenticated:true} also needs github.private.read, an account connection managed in Hay Settings, and an allowed repository. Credentials remain in the host.

The result includes source URL, head/base commit IDs, capture time, changed files and available patches. Missing or truncated patches are incomplete evidence. This API has no comment, merge, push or generic GitHub-write method.