Skip to main content

Web broker protocol v1

A configured web broker supplies search, page reading and dedicated browser sessions. The runtime receives a broker credential, never an upstream provider credential. This contract is independent of any hosting operator or control plane. Operators can also configure supported upstream providers directly.

Trust and ownership

The broker authenticates its caller and derives its scope from the credential’s server-side record. Organization, instance, allowance and upstream account fields supplied by a client cannot change that scope. Credentials are individually revocable and can have a server-enforced expiry. Resource ownership survives credential rotation. Every paid POST includes X-Agent-Id, a runtime agent UUID, and Idempotency-Key, the persisted tool-call UUID. Browser reconnect and release also require the matching agent ID; authenticated capability probes need neither. These are attribution within an authenticated deployment, not authority to select a different deployment. Browser sessions belong to that deployment and agent. Sessions cannot be listed globally or attached by another agent. Website cookies, logins and profiles remain agent-owned; a shared payer connection grants no website acting identity. The broker reserves its maximum admitted usage before contacting a provider. Reservations and concurrency accounting survive process replacement and cannot be reset by changing credentials. Denied work makes no provider call. Browser lifetimes are enforced independently of the runtime and its WebSocket connection. Expired or revoked credentials cannot start or continue work. Cleanup continues when admission is disabled. Uncertain provider outcomes are not replayed blindly.

Transport

The configured endpoint is an HTTPS origin without credentials, query or fragment. Clients never follow redirects carrying a credential. All HTTP responses use Cache-Control: no-store. Errors contain a stable machine code and request ID; upstream errors, credentials, account IDs and connection URLs are not returned. Runtime notices to people are composed by a model from verified facts. Requests use Authorization: Bearer <broker credential>. JSON bodies are bounded and validated; unknown fields are rejected. The same idempotency key with a different request is a conflict, including after a timeout. Provider responses are normalized and bounded before returning them. Content, cookies, CDP messages and credentials must not enter operational logs.

Operations

The runtime constructs the WebSocket URL from its configured origin and the returned opaque ID. The broker can shorten the requested lifetime to its limit; the runtime persists that earlier expiry. A broker response cannot redirect browser credentials. Provider session identifiers or capability URLs are not part of the protocol. Provider-specific account/session management commands must not be reachable through CDP. A session is a dedicated browser, not an unfiltered connection to a browser containing other agents’ contexts. Every reconnect rechecks ownership, credential state and expiry. Disconnects do not renew the admitted lifetime. After credential rotation, the runtime can reconnect to its owned session using the current credential at the same configured origin. It never sends that new credential to a session’s previous origin when the configured service changes.

Availability and operator configuration

A missing credential, unknown stop state, unavailable reservation store or exhausted allowance fails closed. A capability probe must authenticate without launching a browser or making a paid search. BYO provider connections remain available independently of a broker. Runtime limits are additional protections; the broker must enforce its own limits against an untrusted client. Configure an origin and its scoped credential with MESH_WEB_BROKER_URL and MESH_WEB_BROKER_TOKEN, or save a broker vendor connection in settings. In automatic mode, stored operator accounts take precedence over environment fallbacks. An agent can inherit the payer connection while retaining its own website profile. Probes call only /v1/capabilities and incur no upstream usage.