phi_ext/pxb/
mod.rs

1//! The Phi eXtension Binary wire protocol — a Rust port of `ext/go/pxb`.
2//!
3//! # Frame
4//!
5//! Every message is one length-prefixed binary frame on a duplex byte stream
6//! (typically a child process stdin/stdout). No JSON, no newlines.
7//!
8//! ```text
9//! ┌──────── header (16 bytes, little-endian) ────────┐
10//! │ magic[4]="PXB\x01" │ typ u16 │ flags u16 │ id u32│
11//! │ payload_len u32                                  │
12//! └──────────────────────────────────────────────────┘
13//! │ payload: tagged fields                           │
14//! ```
15//!
16//! # Evolution rules
17//!
18//! 1. New message fields: allocate a new tag (≥1). Never reuse a tag.
19//! 2. New lifecycle events: allocate a new `Ev*` code. Never reuse a code.
20//! 3. New frame types: allocate a `Type*` in the Ext→Host (1–99) or
21//!    Host→Ext (100–199) range; peers skip unknown types by length.
22//! 4. Incompatible renames / semantic breaks: bump
23//!    [`PROTOCOL_VERSION`](crate::pxb::PROTOCOL_VERSION) and refuse old peers.
24//! 5. Experimental tags use 128+ and must remain skippable.
25//!
26//! These rules keep host and extension binaries independently upgradable
27//! without a shared JSON schema or lockstep release.
28
29mod codec;
30mod fields;
31mod msg;
32mod types;
33
34pub use codec::{decode_header, encode_header, read_frame, write_frame, Error, Frame, Header};
35pub use fields::{walk_fields, FieldReader, FieldWriter, WIRE_BYTES, WIRE_U64};
36pub use msg::{
37    decode_command_invoked, decode_command_response, decode_event_notify, decode_hello,
38    decode_hello_ack, decode_host_request, decode_host_result, decode_intercept_req,
39    decode_intercept_resp, decode_notify, decode_register_command, decode_register_tool,
40    decode_session_meta, decode_subscribe, decode_tool_detail_result, decode_tool_invoke,
41    decode_tool_result, encode_command_invoked, encode_command_response, encode_event_notify,
42    encode_hello, encode_hello_ack, encode_host_request, encode_host_result, encode_intercept_req,
43    encode_intercept_resp, encode_notify, encode_register_command, encode_register_tool,
44    encode_session_meta, encode_subscribe, encode_tool_detail_result, encode_tool_invoke,
45    encode_tool_result, CommandInvoked, CommandResponse, EventNotify, Hello, HelloAck, HostRequest,
46    HostResult, InterceptReq, InterceptResp, NotifyMsg, RegisterCommand, RegisterTool, SessionMeta,
47    Subscribe, ToolDetailResult, ToolInvoke, ToolResultMsg,
48};
49pub use types::{
50    Event, FrameType, CAP_COMMANDS, CAP_EVENTS, CAP_INTERCEPT, CAP_TOOLS, FLAG_HAS_ID, HEADER_SIZE,
51    MAGIC, MAX_PAYLOAD, PROTOCOL_VERSION, TYPE_COMMAND_INVOKED, TYPE_COMMAND_RESPONSE, TYPE_EVENT,
52    TYPE_HELLO, TYPE_HELLO_ACK, TYPE_HOST_REQUEST, TYPE_HOST_RESULT, TYPE_INTERCEPT,
53    TYPE_INTERCEPT_RESPONSE, TYPE_NOTIFY, TYPE_READY, TYPE_REGISTER_COMMAND, TYPE_REGISTER_TOOL,
54    TYPE_SESSION_META, TYPE_SHUTDOWN, TYPE_SHUTDOWN_ACK, TYPE_SUBSCRIBE, TYPE_TOOL_DETAIL_INVOKE,
55    TYPE_TOOL_DETAIL_RESULT, TYPE_TOOL_INVOKE, TYPE_TOOL_RESULT,
56};
phi_ext/pxb/mod.rs

phi_ext/pxb/
mod.rs
