Skip to main content

Crate blitz_control_protocol

Crate blitz_control_protocol 

Source
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§

pub use target::*;
pub use webgpu::*;

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§

AgentSnapshot
CaptureRequest
What to draw, and how large.
CapturedImage
An RGBA8 image, as the renderer actually drew it.
ConsoleEntry
DebugDescriptor
DebugError
DebugSnapshot
FrameMetrics
Timings of one real presented frame, in milliseconds.
FrameWindowMetrics
Aggregate statistics over the recently presented frames.
JsonRpcError
JsonRpcRequest
JsonRpcResponse
LayoutBounds
A node’s live border box, encoded on the wire as [x, y, width, height].
LayoutDiagnosticRow
One node’s renderer-computed geometry.
LayoutEdges
Computed CSS edges, encoded in shorthand order [top, right, bottom, left].
LayoutOffset
A live scroll offset, encoded as [x, y].
LayoutSize
A two-dimensional layout size, encoded as [width, height].
Modifiers
NagoyaStream
The framing the control socket speaks, and the socket type it speaks over.
RendererMetrics
RevisionSet
RuntimeErrorEntry
ScriptMetrics
Script execution cost, in milliseconds, over the retained poll window.
ScriptSource
One attributed source of script time.
SemanticNode
SnapshotCost
What it cost to answer this diagnostics request.
SnapshotRequest
TimingStats
Mean, 95th percentile and worst case for one timing series, in milliseconds.
TransportStream
Adapts any Transport of WireMessage into a MessageStream.
WindowComposition
Effective native composition selected for the application window.

Enums§

AgentAction
AgentControlEvent
AgentControlRequest
DebugEvent
DebugProtocolError
DebugResponse
DebugStream
DiagnosticsRequest
FramedError
Errors from the framed transport.
IncomingRequest
InputCommand
JsonRpcId
JsonRpcMessage
KeyPhase
LifecycleEvent
PointerPhase
WheelPhase
WireMessage
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§

ControlScriptBackend
A script-capable backend for the control protocol.
MessageStream
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-io byte 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.