Vantage documentation

Agent events and diagnostics

Use diagnostics for synchronous debugging and the event stream for asynchronous browser lifecycle observation. Both are bounded so long-running agents do not create unbounded browser state.

Page diagnostics

vant agent call page.diagnostics.clear '{"tab_id":1}'
vant agent call page.diagnostics '{"tab_id":1}'
vant agent call page.native_diagnostics '{"tab_id":1}'

The page diagnostics ring records console calls, JavaScript errors and unhandled rejections. Native diagnostics report the last top-level load error, web-process termination reason and WebKit's current process responsiveness signal.

Interpret responsiveness carefully

responsive:true means WebKit process IPC is responsive; it does not prove every arbitrary page JavaScript evaluation will terminate. A pathological evaluation can wedge while WebKit still reports the process responsive. A dead web process can be recovered by reload; a bounded RPC timeout contains a stuck evaluation.

Event cursor

vant agent call events.since '{"after":0,"limit":256}'
vant agent events
vant agent watch

Events have monotonically increasing sequence numbers. Persist the last consumed sequence and ask for events after it. The ring reports dropped events if a consumer falls behind. watch is a convenience polling loop; direct integrations can choose their cadence.

Published event types

page.load
page.load_failed
page.web_process_terminated
tab.created
tab.closed
window.created
window.closed
download.started
download.finished
download.failed

Recovery pattern

operation fails/times out
  -> page.native_diagnostics
  -> page.diagnostics
  -> browser.tabs (confirm target still exists)
  -> choose: fresh snapshot / wait / reload / abort
  -> never blindly replay non-idempotent actions

Security

Diagnostics expose page-visible state to the trusted local agent but do not expose a privileged host object to the page. Treat diagnostic content as untrusted website output.