Module protocol 

Wire protocol — server→client event envelopes built to match spec/.

Every constructor here produces a serde_json::Value whose field names and nesting match the JSON Schemas in smooth-operator/spec/events/*.json exactly, so the generated TS/Go/.NET/Python clients deserialize them unmodified.

All events are serialized as a flat envelope with a type discriminator plus the per-event fields documented in envelope.schema.json’s EventEnvelope (requestId, status, data, node, token, error, timestamp).

Structs

TurnUsage

Per-turn token-accounting + cost, captured from the engine’s terminal AgentEvent::Completed and surfaced on the eventual_response so clients can accumulate a live session cost. All fields are accumulated across every LLM call in the turn. Copy so it threads through the runner → handler → protocol by value.

Functions

error

error — an unrecoverable error. The { code, message } descriptor is duplicated at the envelope level and nested under data.error for wire backward-compatibility (per error.schema.json).

eventual_response

eventual_response — the terminal event of a streaming turn. The payload is double-nested (data.data) per eventual-response.schema.json.

immediate_response

immediate_response — synchronous ack. For non-streaming actions this also carries the full response payload in data.

now_ms

Current Unix epoch milliseconds (for the timestamp field).

otp_invalid

otp_invalid — emitted when a verify_otp attempt is rejected. error is an optional machine-readable reason (INVALID_CODE / MAX_ATTEMPTS / NOT_FOUND / EXPIRED); attempts_remaining of 0 means the code is locked and the client must restart the flow. Wire shape matches spec/events/otp-invalid.schema.json.

otp_sent

otp_sent — acknowledgement that a code was dispatched to the caller. Wire shape matches spec/events/otp-sent.schema.json. masked_destination is a partially masked address safe to display (e.g. j***@example.com).

otp_verification_required

otp_verification_required — emitted after a turn’s auth gate refused an end_user tool on an unverified session and the host has an OTP service installed. Tells the client to collect a one-time code. Wire shape matches spec/events/otp-verification-required.schema.json (double-nested data.data). available_channels are the delivery channels the server can offer given the session’s known contacts (email / sms).

otp_verified

otp_verified — emitted when a verify_otp attempt succeeds. The session is now identity-verified; the client re-sends its message to run the gated tool. Wire shape matches spec/events/otp-verified.schema.json.

pong

pong — reply to a ping. Carries the server timestamp both at the top level and inside data (per pong.schema.json).

stream_chunk

stream_chunk — a per-node state snapshot. node is mirrored at the envelope level and inside data (per stream-chunk.schema.json). state only carries safe-to-expose fields.

stream_reasoning

stream_reasoning — a single streamed reasoning token from a reasoning model’s separate thinking channel. Shaped exactly like stream_token, but on a distinct type so clients render it as “thinking” and never fold it into the answer. Clients that don’t know the type simply ignore it (the answer still streams via stream_token).

stream_token

stream_token — a single streamed LLM token. The token is mirrored both at the envelope level (token) and inside data (per stream-token.schema.json).

write_confirmation_required

write_confirmation_required — emitted mid-turn when the agent calls a state-mutating tool that requires explicit human approval before it runs. The turn is parked (the agent loop blocks inside the core ConfirmationHook::pre_call, corresponding to AgentEvent::HumanInputRequired { Confirm }) until the client replies with a confirm_tool_action action carrying the same requestId and an approved boolean.