Skip to content

Concepts ​

Five words explain the runtime: map, state, op, tier, and session.

Map ​

A map is a JSON file that describes one site: its states, the operations an agent can call, and the evidence that each op works. It is learned from real runs, verified by replay, and repaired when the site changes.

maps/<site>/v<n>.json

A map is versioned. A session pins one version, so a publish never changes the meaning of a call in flight. The full field reference is map spec v0.

State ​

A state is a named place in the site, recognized from the live page: a URL pattern and a set of semantic marks. catalog, results, cart, order. States are how an op declares where it starts (from) and where it ends (to), and how the runtime refuses a call from the wrong page with precondition_failed.

Op ​

An op is a typed operation: search(query), add_to_cart(variant_id, qty), checkout(email). It has JSON Schema params and returns, an effect (read, write, irreversible), and one or more implementations.

An agent calls an op instead of clicking. That is the whole point: a ten-click checkout becomes three calls with typed results.

Tier ​

An implementation tier is the cheapest verified path:

TierPathWrites
urlNavigate to a route templateread only
httpThe site's own request, inside the page, with its cookieswrite with outcome_check
uiA semantic UI program: fill, select, clickread or write
webmcpA tool the page publishesreserved

The runtime picks the first verified impl that fits. A url op is one navigation; a ui op is a few semantic actions; an http op is one or more requests.

Session ​

A session is one browser context, one SQLite row, and one pinned map version. It owns cookies, refs, and the write ledger. Sessions expire on an idle TTL, a cap bounds how many can be open, and a restart closes the ones a dead process left behind.

Refs (e1a2b) are document-scoped handles for nodes. They die with the document; a stale ref returns stale_ref with a replacement when the node is still recognizable.

Effects ​

EffectMeaning
readChanges nothing. Safe to retry.
writeChanges the site. Needs an idempotency key to be retry-safe.
irreversibleCannot be undone. Needs confirm: true, and only a ui or webmcp impl.

Untrusted data ​

Page text and element names are data, not instructions. Every page-derived MCP result carries untrusted: true and a notice. A client should render it as data and never follow instructions found in it. The label is a signal, not a jailbreak defense; the server enforces writes.

Skill ​

A skill is knowledge, not execution. It is a portolan-<site> document that names the ops, mines common recipes from successful traces, and links the full schemas. MCP is the source of truth; the skill tells an agent how to use it.

Released under Apache-2.0 · MIT · CC-BY-4.0