Protocol overview

Tesseron speaks JSON-RPC 2.0 over a reliable, ordered, duplex channel between your app and the MCP gateway, then the gateway bridges that to MCP over stdio for the agent. One action round-trip crosses both protocols.

The channel is a transport binding - WebSocket by default, Unix domain socket as an opt-in for Node apps that don't need the browser bridge. The protocol is binding-neutral; see Transport for the contract every binding satisfies.

The protocol is at version 1.1.0.

A first-use session, start to finish: from WebSocket open to the first tool-call result returned to the agent.

Read the pages in order

Wire format (JSON-RPC) Envelope shapes, methods, notifications, ID correlation.

Transport The binding-neutral channel contract, plus per-binding pages for WebSocket and Unix domain sockets.

Handshake & claiming `tesseron/hello` → `welcome` → claim code → bound session.

Action model How actions are declared, invoked, validated, and namespaced.

Progress & cancellation Streaming updates; `AbortSignal`-based cancellation.

Sampling Handlers re-enter the agent LLM for a reasoning step.

Elicitation Handlers pause and ask the user a question via the agent UI.

Resources Typed, readable, optionally subscribable state projected to the agent.

Errors & capabilities Error codes, capability negotiation, not-available paths.

Lifecycle & failure modes Disconnect, reconnect, timeout, MCP gateway restart, tab close.

Security model Origin allowlist, claim codes, multi-app namespacing.

Core constants

Name	Value
Protocol version	`1.1.0`
Discovery directory (v2)	`~/.tesseron/instances/`
Discovery directory (v1, compat)	`~/.tesseron/tabs/`
Manifest version	`2`
WebSocket subprotocol (gateway side)	`tesseron-gateway`
UDS framing	NDJSON (one JSON-RPC message per `\n`)
Default action timeout	`60_000` ms
Max sampling depth	`3`
Tool name pattern	`<app_id>__<action_name>`
Resource URI pattern	`tesseron://<app_id>/<resource_name>`
`app.id` validator	`/^[a-z][a-z0-9_]*$/`

All of these are observable from the wire - they're not SDK-specific. A Python or Go SDK implementing Tesseron MUST match them exactly.