$worker
browser
v0.1.1Interactive Chromium sessions on the iii bus. Navigate, act, read the page console, pick elements.
iiiverifiedinstall
$iii worker add browser@0.1.1
- macOS: arm64 · x64
- Linux: arm64 · armv7 · x64
- Windows: arm64 · x64 · x86
repoiii-hq/workers
exact versions are immutable; binary and bundle artifacts are digest-pinned.
agent-ready brief for v0.1.1
install + config + dependencies + readme + api reference, all in one place. fetch as agent-context.md for an llm to consume.
full markdown
the same content rendered as discrete blocks below is exposed as a single markdown document at
/workers/browser.md?version=0.1.1. paste it into an llm prompt or pipe it through curl from a worker.install
install
$iii worker add browser@0.1.1
dependencies
no dependencies for v0.1.1
readme
README.md
browser
Interactive Chromium sessions on the iii engine
bus. Agents start a session, read the page as an accessibility-tree outline,
click and type against element refs, and read the page's own console and
network history back as data. The single most important thing it gives you:
"why is my dev server page blank?" becomes answerable, because the page's
console errors are one browser::console::read away. The console
worker adds the human window: a live Browser page with a streaming viewport
(Chromium-pushed screencast frames), the console feed, and click-to-pick
elements into chat.
In the console
An agent reads a page as an accessibility outline (browser::snapshot) while
you watch the live viewport and console feed:
browser::screenshot renders the captured image inline in the chat card:
Pick mode highlights the element under the cursor and drops it into the chat composer as an actionable ref:
Install
iii worker add browseriii worker add fetches the binary, writes a config block into
~/.iii/config.yaml, and the engine starts the worker on the next
iii start. The worker drives a Chromium/Chrome already installed on the
machine; point executable at a specific binary if auto-detection picks the
wrong one.
To watch sessions live, pick elements into chat, and follow the agent's browsing from a UI, add the console worker as well:
iii worker add consoleQuickstart
Start a session, read the page, act on it, then read the console:
use iii_sdk::protocol::TriggerRequest;
use iii_sdk::{register_worker, InitOptions};
use serde_json::json;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let iii = register_worker("ws://localhost:49134", InitOptions::default());
let started = iii.trigger(TriggerRequest {
function_id: "browser::sessions::start".into(),
payload: json!({ "url": "http://localhost:3000" }),
action: None,
timeout_ms: Some(30_000),
}).await?;
let session_id = started["session_id"].as_str().unwrap();
// The page as text: an a11y outline with [ref=eN] handles.
let snapshot = iii.trigger(TriggerRequest {
function_id: "browser::snapshot".into(),
payload: json!({ "session_id": session_id }),
action: None,
timeout_ms: Some(15_000),
}).await?;
println!("{}", snapshot["tree"].as_str().unwrap());
// What did the page log? Errors only, no dump.
let console = iii.trigger(TriggerRequest {
function_id: "browser::console::read".into(),
payload: json!({ "session_id": session_id, "level": "error" }),
action: None,
timeout_ms: Some(10_000),
}).await?;
println!("{console:#}");
Ok(())
}The rest of the surface: browser::act (click/hover/type/press/scroll by
ref or coordinates, left/right/middle and double-click), browser::evaluate
(JS expression), browser::screenshot (viewable JPEG), browser::history
(back/forward/reload), browser::network::read (requests + failures),
browser::dom::read (DOM tree with refs), browser::styles::read /
browser::styles::write (computed styles + live inline edits, the design
panel backing), and browser::sessions::list / browser::sessions::stop.
Function ids and schemas live in the code and iii worker info browser.
Configuration
Stored in the configuration worker under the browser key; every field is
editable live from the console. Caps and timeouts hot-reload; executable,
headless, and the viewport apply to sessions started after the change.
browser:
executable: '' # empty = auto-detect Chrome/Chromium/Edge
user_data_dir: '' # set a path to persist cookies/logins across sessions
headless: true # false shows a real window locally
max_sessions: 4 # concurrent Chromium processes
console_buffer: 500 # per-session console ring buffer (entries)
network_buffer: 500 # per-session network ring buffer (entries)
viewport_width: 1280
viewport_height: 800
default_timeout_ms: 30000 # navigation/act/evaluate default
max_timeout_ms: 120000 # ceiling; caller timeout_ms clamped DOWN to this
idle_stop_ms: 300000 # stop sessions idle this long; 0 disables
screenshot_quality: 60 # JPEG quality 1-100
allowed_schemes: [http, https]
max_snapshot_nodes: 2000 # a11y outline size capCustom trigger types
Sibling workers (and the console UI) can subscribe to session activity. All
bindings accept an optional { "session_id": "..." } filter.
| Trigger type | Fires when | Payload to subscribers |
|---|---|---|
browser::session-started |
A session is up and ready | { session_id, url, headless, timestamp } |
browser::session-stopped |
A session ended | { session_id, reason: "stopped" | "idle" | "crashed", timestamp } |
browser::navigated |
The page committed a navigation | { session_id, url, timestamp } |
browser::console-event |
A console/log/exception entry was captured | { session_id, entry } |
browser::picked |
The human picked an element in inspect mode | { session_id, element, timestamp } |
browser::console-event is high-volume; bind it with a session_id filter
and treat browser::console::read as the durable record. browser::picked
elements carry a ref that browser::act accepts directly, so a human pick
flows straight into agent action.
Element picking
browser::pick::start puts the page in DevTools inspect mode (native hover
highlight); the human's click resolves to tag, attributes, outer HTML, text,
bounds, and recent console errors, emitted as browser::picked. The pick,
hint, screencast, and frame functions are internal: console-UI plumbing, not
agent surface, and they stay out of agent tool lists.
api reference (json)
agent-api-reference.json
{
"functions": [
{
"description": "Interact with the page: click (left/right/middle, single or double), hover, type, press, or scroll. Address elements with a [ref=eN] handle from browser::snapshot (or a pick), or raw viewport coordinates.",
"metadata": {},
"name": "browser::act",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"description": "`click`, `hover`, `type`, `press`, or `scroll`.",
"type": "string"
},
"button": {
"default": null,
"description": "Mouse button for `click`: `left` (default), `right`, or `middle`.",
"type": [
"string",
"null"
]
},
"click_count": {
"default": null,
"description": "Clicks in the gesture: 2 double-clicks (`click` only, default 1).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"delta_y": {
"default": null,
"description": "Scroll distance in pixels; positive scrolls down (`scroll`).",
"format": "double",
"type": [
"number",
"null"
]
},
"key": {
"default": null,
"description": "Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.",
"type": [
"string",
"null"
]
},
"ref": {
"default": null,
"description": "Element ref from `browser::snapshot` (`e3`) or `browser::picked` (`p1`). Refs die on navigation; re-snapshot after.",
"type": [
"string",
"null"
]
},
"session_id": {
"type": "string"
},
"text": {
"default": null,
"description": "Text to insert (`type`).",
"type": [
"string",
"null"
]
},
"x": {
"default": null,
"description": "Viewport x, when acting by coordinates instead of ref.",
"format": "double",
"type": [
"number",
"null"
]
},
"y": {
"default": null,
"description": "Viewport y, when acting by coordinates instead of ref.",
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"action",
"session_id"
],
"title": "ActInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"detail": {
"description": "What was done, for the transcript.",
"type": "string"
},
"ok": {
"type": "boolean"
}
},
"required": [
"detail",
"ok"
],
"title": "ActOutput",
"type": "object"
}
},
{
"description": "Read the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.",
"metadata": {},
"name": "browser::console::read",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"level": {
"default": null,
"description": "Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.",
"type": [
"string",
"null"
]
},
"limit": {
"default": null,
"description": "Maximum entries returned, newest kept (default 100).",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"pattern": {
"default": null,
"description": "Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.",
"type": [
"string",
"null"
]
},
"session_id": {
"type": "string"
},
"since_seq": {
"default": null,
"description": "Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"session_id"
],
"title": "ConsoleReadInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ConsoleEntry": {
"description": "One captured console/log/exception entry.",
"properties": {
"level": {
"description": "`log`, `info`, `warning`, `error`, `debug`, or `exception`.",
"type": "string"
},
"seq": {
"description": "Monotonic per-session cursor; pass back as `since_seq`.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"source": {
"description": "`url:line` of the emitting frame, when known.",
"type": [
"string",
"null"
]
},
"text": {
"type": "string"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"level",
"seq",
"text",
"timestamp"
],
"type": "object"
}
},
"properties": {
"dropped": {
"description": "Entries evicted from the ring buffer since session start.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"entries": {
"items": {
"$ref": "#/definitions/ConsoleEntry"
},
"type": "array"
},
"last_seq": {
"description": "Cursor for the next `since_seq`.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"dropped",
"entries",
"last_seq"
],
"title": "ConsoleReadOutput",
"type": "object"
}
},
{
"description": "Read the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.",
"metadata": {},
"name": "browser::dom::read",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"depth": {
"default": null,
"description": "Levels of children to include (default 3).",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"ref": {
"default": null,
"description": "Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.",
"type": [
"string",
"null"
]
},
"session_id": {
"type": "string"
}
},
"required": [
"session_id"
],
"title": "DomReadInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"DomNode": {
"description": "One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.",
"properties": {
"child_count": {
"description": "Total children in the document, which may exceed `children` returned at this depth.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"children": {
"items": {
"$ref": "#/definitions/DomNode"
},
"type": "array"
},
"classes": {
"type": [
"string",
"null"
]
},
"id": {
"type": [
"string",
"null"
]
},
"ref": {
"type": "string"
},
"tag": {
"description": "Lowercase tag (`div`, `button`) or node name (`#text`).",
"type": "string"
},
"text": {
"description": "Trimmed text content for text nodes.",
"type": [
"string",
"null"
]
}
},
"required": [
"child_count",
"ref",
"tag"
],
"type": "object"
}
},
"properties": {
"root": {
"$ref": "#/definitions/DomNode"
},
"truncated": {
"description": "True when the node cap cut the tree short; read a subtree via `ref`.",
"type": "boolean"
}
},
"required": [
"root",
"truncated"
],
"title": "DomReadOutput",
"type": "object"
}
},
{
"description": "Evaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.",
"metadata": {},
"name": "browser::evaluate",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"expression": {
"description": "JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.",
"type": "string"
},
"session_id": {
"type": "string"
},
"timeout_ms": {
"default": null,
"description": "Upper bound on evaluation; clamped to `max_timeout_ms`.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"expression",
"session_id"
],
"title": "EvaluateInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"error": {
"description": "Exception text when not `ok`.",
"type": [
"string",
"null"
]
},
"ok": {
"type": "boolean"
},
"value": {
"description": "JSON completion value when `ok`."
}
},
"required": [
"ok"
],
"title": "EvaluateOutput",
"type": "object"
}
},
{
"description": "Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip; poll fast. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::frame",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
},
"since_frame": {
"default": null,
"description": "Frame cursor from the previous read; when the newest frame still has this seq the response omits `frame` (nothing changed, nothing to redraw).",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"session_id"
],
"title": "FrameInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"active": {
"description": "False when no screencast is running (call screencast::start first).",
"type": "boolean"
},
"frame": {
"description": "Base64 JPEG of the newest frame; absent when `since_frame` is still current or no frame has arrived yet.",
"type": [
"string",
"null"
]
},
"frame_seq": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"height": {
"description": "Page-viewport height the frame maps to.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"timestamp": {
"format": "int64",
"type": "integer"
},
"width": {
"description": "Page-viewport width the frame maps to (input coordinate space).",
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"active",
"frame_seq",
"height",
"timestamp",
"width"
],
"title": "FrameOutput",
"type": "object"
}
},
{
"description": "Go back, go forward, or reload the session's page. Back/forward at the history edge is a no-op with moved=false.",
"metadata": {},
"name": "browser::history",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"description": "`back`, `forward`, or `reload`.",
"type": "string"
},
"session_id": {
"type": "string"
}
},
"required": [
"action",
"session_id"
],
"title": "HistoryInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"moved": {
"description": "False when back/forward had no entry to move to.",
"type": "boolean"
},
"ok": {
"type": "boolean"
},
"url": {
"description": "URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.",
"type": "string"
}
},
"required": [
"moved",
"ok",
"url"
],
"title": "HistoryOutput",
"type": "object"
}
},
{
"description": "Navigate a session to a URL and wait for the page to load. Element refs from earlier snapshots are invalidated by navigation.",
"metadata": {},
"name": "browser::navigate",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
},
"timeout_ms": {
"default": null,
"description": "Upper bound on the navigation wait; clamped to `max_timeout_ms`.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"url": {
"description": "Absolute URL; scheme must be on the configured allowlist.",
"type": "string"
}
},
"required": [
"session_id",
"url"
],
"title": "NavigateInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"ok": {
"type": "boolean"
},
"timed_out": {
"description": "True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.",
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"url": {
"description": "URL after redirects.",
"type": "string"
}
},
"required": [
"ok",
"timed_out",
"url"
],
"title": "NavigateOutput",
"type": "object"
}
},
{
"description": "Read the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.",
"metadata": {},
"name": "browser::network::read",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"failed_only": {
"default": null,
"description": "Only failed requests (network error or status >= 400).",
"type": [
"boolean",
"null"
]
},
"limit": {
"default": null,
"description": "Maximum entries returned, newest kept (default 100).",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"pattern": {
"default": null,
"description": "Regex applied to the request URL.",
"type": [
"string",
"null"
]
},
"session_id": {
"type": "string"
},
"since_seq": {
"default": null,
"description": "Only entries with `seq` greater than this.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"session_id"
],
"title": "NetworkReadInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"NetworkEntry": {
"description": "One captured network request.",
"properties": {
"error": {
"type": [
"string",
"null"
]
},
"failed": {
"type": "boolean"
},
"method": {
"type": "string"
},
"mime_type": {
"type": [
"string",
"null"
]
},
"seq": {
"description": "Monotonic per-session cursor; pass back as `since_seq`.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"status": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"timestamp": {
"format": "int64",
"type": "integer"
},
"url": {
"type": "string"
}
},
"required": [
"failed",
"method",
"seq",
"timestamp",
"url"
],
"type": "object"
}
},
"properties": {
"dropped": {
"description": "Entries evicted from the ring buffer since session start.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"entries": {
"items": {
"$ref": "#/definitions/NetworkEntry"
},
"type": "array"
},
"last_seq": {
"description": "Cursor for the next `since_seq`.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"dropped",
"entries",
"last_seq"
],
"title": "NetworkReadOutput",
"type": "object"
}
},
{
"description": "Internal: reload browser settings from the authoritative configuration on change.",
"metadata": {
"internal": true
},
"name": "browser::on-config-change",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "OnConfigChangeRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "OnConfigChangeResponse",
"type": "object"
}
},
{
"description": "Internal: element preview at a viewport point (tag, id, classes, bounds) so the console UI can draw a hover highlight in pick mode. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::pick::hint",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
},
"x": {
"description": "Viewport x of the cursor.",
"format": "double",
"type": "number"
},
"y": {
"description": "Viewport y of the cursor.",
"format": "double",
"type": "number"
}
},
"required": [
"session_id",
"x",
"y"
],
"title": "PickHintInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Bounds": {
"properties": {
"height": {
"format": "double",
"type": "number"
},
"width": {
"format": "double",
"type": "number"
},
"x": {
"format": "double",
"type": "number"
},
"y": {
"format": "double",
"type": "number"
}
},
"required": [
"height",
"width",
"x",
"y"
],
"type": "object"
}
},
"properties": {
"bounds": {
"anyOf": [
{
"$ref": "#/definitions/Bounds"
},
{
"type": "null"
}
],
"description": "Viewport-space box to draw the highlight over."
},
"classes": {
"type": [
"string",
"null"
]
},
"hit": {
"description": "False when no element sits at the point.",
"type": "boolean"
},
"id": {
"type": [
"string",
"null"
]
},
"tag": {
"description": "Lowercase tag name.",
"type": [
"string",
"null"
]
}
},
"required": [
"hit"
],
"title": "PickHintOutput",
"type": "object"
}
},
{
"description": "Internal: resolve the element at a clicked viewport point and emit browser::picked. The console calls this on a pick-mode click. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::pick::resolve",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
},
"x": {
"description": "Viewport x of the click.",
"format": "double",
"type": "number"
},
"y": {
"description": "Viewport y of the click.",
"format": "double",
"type": "number"
}
},
"required": [
"session_id",
"x",
"y"
],
"title": "PickResolveInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Neutral acknowledgement returned by the fire-and-forget internal functions (pick start/stop/resolve, screencast start/stop): they emit their result as a trigger event, so the direct return is just `{ ok }`.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "AckOutput",
"type": "object"
}
},
{
"description": "Internal: enter pick mode so the human can select an element in the console UI. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::pick::start",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
}
},
"required": [
"session_id"
],
"title": "PickStartInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Neutral acknowledgement returned by the fire-and-forget internal functions (pick start/stop/resolve, screencast start/stop): they emit their result as a trigger event, so the direct return is just `{ ok }`.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "AckOutput",
"type": "object"
}
},
{
"description": "Internal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::pick::stop",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"description": "Cancelling pick mode on an unknown session succeeds.",
"type": "string"
}
},
"required": [
"session_id"
],
"title": "PickStopInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Neutral acknowledgement returned by the fire-and-forget internal functions (pick start/stop/resolve, screencast start/stop): they emit their result as a trigger event, so the direct return is just `{ ok }`.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "AckOutput",
"type": "object"
}
},
{
"description": "Internal: start pushing live viewport frames for browser::frame. Console-UI plumbing; agents use browser::screenshot. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::screencast::start",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
}
},
"required": [
"session_id"
],
"title": "ScreencastStartInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Neutral acknowledgement returned by the fire-and-forget internal functions (pick start/stop/resolve, screencast start/stop): they emit their result as a trigger event, so the direct return is just `{ ok }`.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "AckOutput",
"type": "object"
}
},
{
"description": "Internal: stop the live frame push. Idempotent. Not an agent function.",
"metadata": {
"internal": true
},
"name": "browser::screencast::stop",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"description": "Stopping the screencast on an unknown session succeeds.",
"type": "string"
}
},
"required": [
"session_id"
],
"title": "ScreencastStopInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Neutral acknowledgement returned by the fire-and-forget internal functions (pick start/stop/resolve, screencast start/stop): they emit their result as a trigger event, so the direct return is just `{ ok }`.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "AckOutput",
"type": "object"
}
},
{
"description": "Capture the session viewport as a viewable JPEG. Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.",
"metadata": {},
"name": "browser::screenshot",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"full_page": {
"default": null,
"description": "Capture the full scrollable page instead of the viewport.",
"type": [
"boolean",
"null"
]
},
"session_id": {
"type": "string"
}
},
"required": [
"session_id"
],
"title": "ScreenshotInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ContentBlock": {
"description": "One block of a viewable response: an image block plus a text line.",
"properties": {
"data": {
"type": [
"string",
"null"
]
},
"mime": {
"type": [
"string",
"null"
]
},
"text": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"ScreenshotDetails": {
"properties": {
"height": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"session_id": {
"type": "string"
},
"url": {
"type": "string"
},
"width": {
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"height",
"session_id",
"url",
"width"
],
"type": "object"
}
},
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"details": {
"$ref": "#/definitions/ScreenshotDetails"
}
},
"required": [
"content",
"details"
],
"title": "ScreenshotOutput",
"type": "object"
}
},
{
"description": "List live browser sessions with their current URL and activity.",
"metadata": {},
"name": "browser::sessions::list",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ListInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SessionInfo": {
"properties": {
"console_entries": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"created_ms": {
"format": "int64",
"type": "integer"
},
"headless": {
"type": "boolean"
},
"last_used_ms": {
"format": "int64",
"type": "integer"
},
"session_id": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"url": {
"type": "string"
}
},
"required": [
"console_entries",
"created_ms",
"headless",
"last_used_ms",
"session_id",
"url"
],
"type": "object"
}
},
"properties": {
"sessions": {
"items": {
"$ref": "#/definitions/SessionInfo"
},
"type": "array"
}
},
"required": [
"sessions"
],
"title": "ListOutput",
"type": "object"
}
},
{
"description": "Start an interactive Chromium session and return its session_id. Sessions keep console and network history; stop them with browser::sessions::stop when done.",
"metadata": {},
"name": "browser::sessions::start",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"headful": {
"default": null,
"description": "Force a visible window for this session, overriding the configured `headless` default.",
"type": [
"boolean",
"null"
]
},
"url": {
"default": null,
"description": "URL to open immediately. Omit to start on about:blank.",
"type": [
"string",
"null"
]
}
},
"title": "StartInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"headless": {
"type": "boolean"
},
"session_id": {
"description": "Pass this to every other browser function.",
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"headless",
"session_id",
"url"
],
"title": "StartOutput",
"type": "object"
}
},
{
"description": "Stop a browser session and its Chromium process. Idempotent: stopping an unknown or already-stopped session succeeds with was_running=false.",
"metadata": {},
"name": "browser::sessions::stop",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"description": "Session to stop. Stopping an unknown or already-stopped id succeeds.",
"type": "string"
}
},
"required": [
"session_id"
],
"title": "StopInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"ok": {
"type": "boolean"
},
"was_running": {
"description": "False when the session was already gone.",
"type": "boolean"
}
},
"required": [
"ok",
"was_running"
],
"title": "StopOutput",
"type": "object"
}
},
{
"description": "Read the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.",
"metadata": {},
"name": "browser::snapshot",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"session_id": {
"type": "string"
}
},
"required": [
"session_id"
],
"title": "SnapshotInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"title": {
"type": [
"string",
"null"
]
},
"tree": {
"description": "Indented outline; lines carry `[ref=eN]` handles for `browser::act`.",
"type": "string"
},
"truncated": {
"description": "True when the tree hit `max_snapshot_nodes` and was cut short.",
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"tree",
"truncated",
"url"
],
"title": "SnapshotOutput",
"type": "object"
}
},
{
"description": "Read an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.",
"metadata": {},
"name": "browser::styles::read",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"properties": {
"default": null,
"description": "Computed property names to return. Omit for a curated design-panel set; pass `[\"*\"]` for every computed property.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"ref": {
"description": "Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.",
"type": "string"
},
"session_id": {
"type": "string"
}
},
"required": [
"ref",
"session_id"
],
"title": "StylesReadInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"StyleProperty": {
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"name",
"value"
],
"type": "object"
}
},
"properties": {
"inline_style": {
"description": "The element's inline `style` attribute, when present.",
"type": [
"string",
"null"
]
},
"properties": {
"items": {
"$ref": "#/definitions/StyleProperty"
},
"type": "array"
},
"ref": {
"type": "string"
}
},
"required": [
"properties",
"ref"
],
"title": "StylesReadOutput",
"type": "object"
}
},
{
"description": "Set one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.",
"metadata": {},
"name": "browser::styles::write",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"important": {
"default": null,
"description": "Apply with `!important`.",
"type": [
"boolean",
"null"
]
},
"property": {
"description": "CSS property name (`background-color`).",
"type": "string"
},
"ref": {
"description": "Element ref to edit.",
"type": "string"
},
"session_id": {
"type": "string"
},
"value": {
"description": "CSS value (`#101418`). Empty string removes the inline property.",
"type": "string"
}
},
"required": [
"property",
"ref",
"session_id",
"value"
],
"title": "StylesWriteInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"inline_style": {
"description": "The element's inline `style` attribute after the edit.",
"type": "string"
},
"ok": {
"type": "boolean"
}
},
"required": [
"inline_style",
"ok"
],
"title": "StylesWriteOutput",
"type": "object"
}
}
],
"triggers": [
{
"description": "A console/log/exception entry was captured on a session's page.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by every `browser::*` trigger binding. The only filter is an optional session-id equality match; unknown fields fail at registration so a misspelled filter key fails loudly instead of silently receiving nothing.",
"properties": {
"session_id": {
"description": "Only deliver events for this browser session.",
"type": [
"string",
"null"
]
}
},
"title": "BindingConfig",
"type": "object"
},
"metadata": {},
"name": "browser::console-event",
"return_schema": {}
},
{
"description": "The session's page committed a navigation.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by every `browser::*` trigger binding. The only filter is an optional session-id equality match; unknown fields fail at registration so a misspelled filter key fails loudly instead of silently receiving nothing.",
"properties": {
"session_id": {
"description": "Only deliver events for this browser session.",
"type": [
"string",
"null"
]
}
},
"title": "BindingConfig",
"type": "object"
},
"metadata": {},
"name": "browser::navigated",
"return_schema": {}
},
{
"description": "A network request was captured (completed or failed) on a session's page.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by every `browser::*` trigger binding. The only filter is an optional session-id equality match; unknown fields fail at registration so a misspelled filter key fails loudly instead of silently receiving nothing.",
"properties": {
"session_id": {
"description": "Only deliver events for this browser session.",
"type": [
"string",
"null"
]
}
},
"title": "BindingConfig",
"type": "object"
},
"metadata": {},
"name": "browser::network-event",
"return_schema": {}
},
{
"description": "The human picked an element in inspect mode.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by every `browser::*` trigger binding. The only filter is an optional session-id equality match; unknown fields fail at registration so a misspelled filter key fails loudly instead of silently receiving nothing.",
"properties": {
"session_id": {
"description": "Only deliver events for this browser session.",
"type": [
"string",
"null"
]
}
},
"title": "BindingConfig",
"type": "object"
},
"metadata": {},
"name": "browser::picked",
"return_schema": {}
},
{
"description": "A Chromium session is up and ready.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by every `browser::*` trigger binding. The only filter is an optional session-id equality match; unknown fields fail at registration so a misspelled filter key fails loudly instead of silently receiving nothing.",
"properties": {
"session_id": {
"description": "Only deliver events for this browser session.",
"type": [
"string",
"null"
]
}
},
"title": "BindingConfig",
"type": "object"
},
"metadata": {},
"name": "browser::session-started",
"return_schema": {}
},
{
"description": "A Chromium session ended (stopped, idle, or crashed).",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by every `browser::*` trigger binding. The only filter is an optional session-id equality match; unknown fields fail at registration so a misspelled filter key fails loudly instead of silently receiving nothing.",
"properties": {
"session_id": {
"description": "Only deliver events for this browser session.",
"type": [
"string",
"null"
]
}
},
"title": "BindingConfig",
"type": "object"
},
"metadata": {},
"name": "browser::session-stopped",
"return_schema": {}
}
]
}