Vantage documentation

Agent reference

Machine-oriented reference for Vantage's agent-native surface. This section favors explicit contracts, recovery rules and copyable examples. Start every unfamiliar installation with discovery.

Bootstrap

vant agent status
vant agent version
vant agent capabilities
vant agent call describe '{}'
vant agent tabs

Mental model

trusted local agent
  | Unix RPC / CLI
  v
Vantage application
  +-- browser.*  windows/tabs/navigation/profile
  +-- net.*      direct HTTP/API requests
  +-- page.*     semantic DOM/JS/waits/screenshots
  +-- webkit.*   WebKit properties/settings
  +-- data APIs  downloads/bookmarks/history/permissions
  +-- events.*   bounded asynchronous events
  v
WebKitGTK web processes

Fast decision table

Need API/JSON?                       net.fetch
Need tabs/navigation?                browser.*
Need clickable controls?             page.snapshot
Need click/fill/type/select/key?      page.interact
Need wait for text/element/ref?       page.wait
Need text/HTML/metadata?              page.inspect
Need rendered image?                 page.screenshot
Need unusual DOM computation?        page.javascript
Need console/runtime errors?          page.diagnostics
Need WebKit process/load health?      page.native_diagnostics
Need lifecycle changes?              events.since

Reference map

RPC + CLIEnvelope, direct clients, concurrency and errors net.fetchDirect HTTP requests with headers and bodies Page + WebKitSemantic refs, interaction, JS and inspection EventsCursoring, diagnostics and recovery RecipesEnd-to-end task patterns

Discovery is authoritative

vant agent call describe '{}'
vant agent call describe '{"name":"net.fetch"}'
vant agent --json capabilities

Protocol 1 permits additive methods/features/fields. Tolerate unknown response fields. Handle absent methods as method_not_found.

Runtime IDs

Window and tab IDs are stable for that object's runtime lifetime and are never silently rebound after closure. Refresh browser.tabs after topology-changing failures.

Semantic refs

snapshot generation 8: @e8_1 @e8_2 @e8_3
DOM mutation/navigation
  -> old refs may be stale
  -> snapshot again
  -> resolve target from new refs

This prevents accidental interaction with a different element after the page changes.

Concurrency

Independent RPC clients are serviced concurrently; WebKit/GTK mutations are marshalled onto the GTK main context. Still serialize logically conflicting operations on the same tab. Another human/agent controller can invalidate assumptions between observation and action.

Efficiency

Use net.fetch instead of rendering a page solely to retrieve API data. Use semantic snapshots instead of full HTML for routine interaction. Snapshot candidates, diagnostics and events are bounded to keep long-running agents predictable.

Trust boundary

The same-user local agent is privileged. Web content is not. Pages receive no Vantage socket/filesystem/process bridge. page.javascript remains within WebKit page security. net.fetch is application-side and deliberately does not inherit page cookies.

Compatibility

Wire protocol 1 is stable. Breaking envelope or established-method semantic changes require a new protocol version. Agents should still query capabilities/describe because new optional functionality is additive.