Expand description
The Blitz agent-control and diagnostics surface: one vocabulary, one core, two transports.
§The shape of this crate
This module is the vocabulary: the request, response and event types, and the MCP framing that carries them. It is what a client needs and all it needs, it costs serde and endpoint-libs, and it is what you get with no features enabled.
document is the core, behind engine. It answers a request against
a blitz-dom document: the semantic tree, the capture surface, input
injection. It knows nothing about sockets.
in_process and server are the two transports over that core. An
embedder holding the document calls the first one directly; a harness or an
agent outside the process reaches the second one over a Unix socket.
client is the connecting half of that socket, and it is a sibling of the
server rather than a layer on top of it, because a peer can be both: an
application driven by agents while it drives a browser it embeds is a client
and a server at once.
lifecycle is the one answer neither transport nor core can give.
Relaunch and Quit are about the process, so the embedder that started it
registers what they mean; it is here rather than in a host because more than
one host serves the same request.
There were three copies of this vocabulary before, in three repositories, and two of them were transports rather than duplicates: an in-process interface in the browser and a socket in the Tauri runtime, each with its own spelling of the same commands. The transports are both still here. The spelling is not.
§Typed local debugging protocol carried by endpoint-libs framing.
This is deliberately not WebDriver. It models the native renderer and app
lifecycle directly, supports observation by more than one client, and has
no authentication handshake. Agent control binds only to a local transport;
expensive diagnostics collection remains an explicit compile-time feature
of the server, izumo/diagnostics.
§Why this is its own crate
These are the server’s own definitions, and a client that hand-rolls the
JSON gets them wrong in ways that do not look like encoding mistakes.
AgentAction is adjacently tagged, so {"action":"click","nodeId":9} is
malformed where {"action":"click","params":{"nodeId":9}} is correct, and
the difference used to present as a hung application. Sharing the types
makes that a compile error.
Speaking the protocol must not cost a renderer. izumo pulls
in tauri, winit, wgpu and blitz, so a measurement tool that depended on it
for these types would build a browser engine to send a wheel event. Nothing
here needs any of that: it is serde plus endpoint-libs’ framing.
§No diagnostics feature, on purpose
The types are inert data definitions and cost nothing to compile, whereas
gating them creates feature skew: cargo unifies features across a build, so
one workspace member asking for diagnostics types while the server crate is
built without them turned DebugResponse into a non-exhaustive match in
code nobody had touched. What stays gated in the server is collection,
which is where the expense actually is. A build that cannot serve
diagnostics says so by omitting the tool from tools/list; see
encode_tools_list_response.
Re-exports§
Modules§
- client
- The socket transport, connecting half. The socket transport, connecting half: finding a running host, and talking to it.
- condense
- Condensing a settled page into levels a caller can widen from.
- document
- The core: reading, capturing and driving a document. Inspecting, capturing and driving a document, with no window involved.
- guarded_
writer - Secret-aware file output shared by every workspace crate. The only file-byte writer in this workspace.
- in_
process - The in-process transport. The in-process transport: a request in, a response out, no socket.
- journal
- latest
- Latest-value and one-shot handoffs built on nagoya, replacing tokio channels. Latest-value handoffs, without a channel.
- lifecycle
- The embedder’s answer to a request about the process, not the document. The embedder’s answer to a request about the process, not the document.
- server
- The socket transport, listening half.
- target
- webgpu
- Page-owned WebGPU diagnostic reports.
Structs§
- Agent
Snapshot - Capture
Request - What to draw, and how large.
- Captured
Image - An RGBA8 image, as the renderer actually drew it.
- Console
Entry - Debug
Descriptor - Debug
Error - Debug
Snapshot - Frame
Metrics - Timings of one real presented frame, in milliseconds.
- Frame
Window Metrics - Aggregate statistics over the recently presented frames.
- Json
RpcError - Json
RpcRequest - Json
RpcResponse - Layout
Bounds - A node’s live border box, encoded on the wire as
[x, y, width, height]. - Layout
Diagnostic Row - One node’s renderer-computed geometry.
- Layout
Edges - Computed CSS edges, encoded in shorthand order
[top, right, bottom, left]. - Layout
Offset - A live scroll offset, encoded as
[x, y]. - Layout
Size - A two-dimensional layout size, encoded as
[width, height]. - Modifiers
- Nagoya
Stream - The framing the control socket speaks, and the socket type it speaks over.
- Renderer
Metrics - Revision
Set - Runtime
Error Entry - Script
Metrics - Script execution cost, in milliseconds, over the retained poll window.
- Script
Source - One attributed source of script time.
- Semantic
Node - Snapshot
Cost - What it cost to answer this diagnostics request.
- Snapshot
Request - Timing
Stats - Mean, 95th percentile and worst case for one timing series, in milliseconds.
- Transport
Stream - Adapts any
TransportofWireMessageinto aMessageStream. - Window
Composition - Effective native composition selected for the application window.
Enums§
- Agent
Action - Agent
Control Event - Agent
Control Request - Debug
Event - Debug
Protocol Error - Debug
Response - Debug
Stream - Diagnostics
Request - Framed
Error - Errors from the framed transport.
- Incoming
Request - Input
Command - Json
RpcId - Json
RpcMessage - KeyPhase
- Lifecycle
Event - Pointer
Phase - Wheel
Phase - Wire
Message - A protocol-level message, independent of any WebSocket backend.
Constants§
- AGENT_
CONTROL_ TOOL - AGENT_
EVENT_ NOTIFICATION - DEBUG_
PROTOCOL_ VERSION - Version 2 names every field inside a command camelCase (
nodeId,maxDepth,deltaX). Version 1 field names are still accepted on input, so a version 2 host serves version 1 clients; a version 2 client refuses a version 1 descriptor instead of sending names that host cannot read. - DIAGNOSTICS_
EVENT_ NOTIFICATION - DIAGNOSTICS_
TOOL - MAX_
DEBUG_ FRAME_ BYTES - Largest single frame either side may send or accept. Shared by every host, client and relay, so a supervisor never forwards a frame its peer would refuse.
- MCP_
INITIALIZE - MCP_
INITIALIZED_ NOTIFICATION - MCP_
PROTOCOL_ VERSION - MCP_
TOOLS_ CALL - MCP_
TOOLS_ LIST
Traits§
- Control
Script Backend - A script-capable backend for the control protocol.
- Message
Stream - An object-safe, bidirectional message channel — what the session loop consumes.
- Transport
- A bidirectional, typed message channel.
Functions§
- decode_
agent_ event - decode_
agent_ request - decode_
diagnostics_ event - decode_
diagnostics_ event_ value - decode_
diagnostics_ request - decode_
incoming - decode_
incoming_ value - Decode an incoming request from a JSON value that the transport already parsed.
- decode_
response - decode_
response_ value - decode_
rpc - decode_
rpc_ value - decode_
wire_ value - encode_
agent_ event - encode_
agent_ request - encode_
diagnostic_ overflow - encode_
diagnostics_ event - encode_
diagnostics_ request - encode_
initialize_ response - The MCP handshake, answered on behalf of whichever host is serving.
- encode_
response - encode_
rpc - encode_
rpc_ error - encode_
target_ event - encode_
tools_ list_ response - The tool list, which is the one place a build’s capability shows.
- framed_
json_ neutral - Wrap a
futures-iobyte stream in the framing described in this module’s docs. - peek_
request_ id - The request id of an incoming frame, recovered without consuming it.
- peek_
value_ request_ id - Recover a request id from an already parsed JSON value.