Skip to main content

Module pxb

phi_ext

Module pxb 

Source
Expand description

The Phi eXtension Binary wire protocol — a Rust port of ext/go/pxb.

§Frame

Every message is one length-prefixed binary frame on a duplex byte stream (typically a child process stdin/stdout). No JSON, no newlines.

┌──────── header (16 bytes, little-endian) ────────┐
│ magic[4]="PXB\x01" │ typ u16 │ flags u16 │ id u32│
│ payload_len u32                                  │
└──────────────────────────────────────────────────┘
│ payload: tagged fields                           │

§Evolution rules

  1. New message fields: allocate a new tag (≥1). Never reuse a tag.
  2. New lifecycle events: allocate a new Ev* code. Never reuse a code.
  3. New frame types: allocate a Type* in the Ext→Host (1–99) or Host→Ext (100–199) range; peers skip unknown types by length.
  4. Incompatible renames / semantic breaks: bump PROTOCOL_VERSION and refuse old peers.
  5. Experimental tags use 128+ and must remain skippable.

These rules keep host and extension binaries independently upgradable without a shared JSON schema or lockstep release.

Structs§

CommandInvoked
Host→ext when the user runs a slash command.
CommandResponse
Ext→host slash command outcome.
EventNotify
Fire-and-forget host→ext lifecycle event.
FieldReader
Walks a tagged-field payload.
FieldWriter
Builds a tagged-field payload.
Frame
One complete message: header plus payload bytes.
Header
The 16-byte frame prefix.
Hello
The first frame from an extension.
HelloAck
The host reply to Hello.
HostRequest
Ext→host capability RPC.
HostResult
Host→ext reply to a HostRequest.
InterceptReq
Host→ext for a blocking decision point.
InterceptResp
Ext→host intercept reply.
NotifyMsg
Ext→host UI toast / footer status.
RegisterCommand
Registers a slash command.
RegisterTool
Registers an LLM tool; schema_json is opaque JSON Schema bytes.
SessionMeta
Host→ext session identity push.
Subscribe
Declares event / intercept interests.
ToolInvoke
Host→ext for a registered tool.
ToolResultMsg
Ext→host tool outcome.

Enums§

Error
PXB protocol errors.
Event
Lifecycle event codes (compact on the wire; strings only at SDK edges). Append-only: never reuse a code. Unknown codes are ignored by peers that did not Subscribe to them.
FrameType
Frame types with an explicit Unknown arm so peers that do not understand a type still skip the frame by length.

Constants§

CAP_COMMANDS
Capability bits advertised in Hello.
CAP_EVENTS
CAP_INTERCEPT
CAP_TOOLS
FLAG_HAS_ID
Flag bits in the header.
HEADER_SIZE
Fixed frame header length.
MAGIC
Frame magic: P X B + version byte.
MAX_PAYLOAD
Maximum payload accepted from a peer (16 MiB).
PROTOCOL_VERSION
Negotiated in Hello / HelloAck; bump only for incompatible renames.
TYPE_COMMAND_INVOKED
TYPE_COMMAND_RESPONSE
TYPE_EVENT
TYPE_HELLO
TYPE_HELLO_ACK
TYPE_HOST_REQUEST
TYPE_HOST_RESULT
TYPE_INTERCEPT
TYPE_INTERCEPT_RESPONSE
TYPE_NOTIFY
TYPE_READY
TYPE_REGISTER_COMMAND
TYPE_REGISTER_TOOL
TYPE_SESSION_META
TYPE_SHUTDOWN
TYPE_SHUTDOWN_ACK
TYPE_SUBSCRIBE
TYPE_TOOL_INVOKE
TYPE_TOOL_RESULT
WIRE_BYTES
u32 length + bytes.
WIRE_U64
8-byte little-endian (u16/u32/bool/event codes share this kind).

Functions§

decode_command_invoked
decode_command_response
decode_event_notify
decode_header
Parses a 16-byte header.
decode_hello
decode_hello_ack
decode_host_request
decode_host_result
decode_intercept_req
decode_intercept_resp
decode_notify
decode_register_command
decode_register_tool
decode_session_meta
decode_subscribe
decode_tool_invoke
decode_tool_result
encode_command_invoked
encode_command_response
encode_event_notify
encode_header
Encodes a header into a fixed-size array.
encode_hello
encode_hello_ack
encode_host_request
encode_host_result
encode_intercept_req
encode_intercept_resp
encode_notify
encode_register_command
encode_register_tool
encode_session_meta
encode_subscribe
encode_tool_invoke
encode_tool_result
read_frame
Reads one frame from r into an owned body.
walk_fields
Calls f for each field; unknown tags should be skipped via the reader. f may call u64/bytes exactly once for the current field, or skip.
write_frame
Writes header + body to w, then flushes. Stdout is line-buffered, and PXB frames contain no newlines, so skipping the flush would leave small frames stuck in the buffer.