Metadata-Version: 2.5
Name: pp-rpc-protocol
Version: 0.1.0
Summary: Transport-neutral CBOR protocol for remote pi sessions (Python port of @earendil-works/pi-protocol)
Project-URL: Homepage, https://github.com/HSPK/pp
Project-URL: Repository, https://github.com/HSPK/pp
Project-URL: Issues, https://github.com/HSPK/pp/issues
Project-URL: Upstream, https://github.com/earendil-works/pi/tree/main/packages/protocol
Author: Earendil Works
Maintainer-email: Hangxing Wei <HSPK@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: binary,cbor,framing,pi,protocol,rpc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.23
Description-Content-Type: text/markdown

# pi-protocol

Runtime-neutral schemas, CBOR encoding, and byte-stream framing for the experimental pi protocol.

Protocol version `1` uses binary messages with this wire layout:

1. A four-byte unsigned big-endian payload length.
2. One definite-length CBOR item containing the message.

The first client message is always `hello`, containing `PROTOCOL_VERSION`. Subsequent messages use correlated request/response envelopes and server event envelopes. Session and server snapshots are authoritative. Progress events are transient UI hints and must not be reduced into authoritative state. Transports complete authentication before protocol bytes are exchanged.

Session lists contain `SessionMetadata`, the normalized durable metadata available without acquiring a session runtime. Only `id` and `createdAt` are required; `updatedAt`, `parentSessionId`, `sessionName`, and `cwd` are included when supported by the backing store. Runtime state such as phase, model, thinking level, attachment, and locking appears only in an acquired `SessionSnapshot`.

This package does not implement JSONL session files. JSONL session persistence belongs to `pi_coding_agent`; `pi_protocol` frames CBOR messages for the socket protocol.

## Validated message API

`encode_client_message()` and `encode_server_message()` validate a message and return a complete framed `bytes` object. The incremental decoders accept arbitrary fragmentation or coalescing, so they work with streams, sockets, and custom byte transports.

```python
from pi_protocol import (
    PROTOCOL_VERSION,
    create_server_message_decoder,
    encode_client_message,
)

hello = {
    "type": "hello",
    "version": PROTOCOL_VERSION,
}

outbound = encode_client_message(hello)

decoder = create_server_message_decoder(max_frame_length=1024 * 1024)
for message in decoder.push(incoming_chunk):
    handle_server_message(message)
decoder.end()
```

`ClientMessageDecoder` and `ServerMessageDecoder` are also available directly. Schema violations, malformed CBOR, and invalid framing throw `ProtocolValidationError`. Validation errors do not retain rejected payloads.

`parse_client_message()` and `parse_server_message()` only validate already-decoded Python values. They do not parse JSON strings.

The TypeScript package builds TypeBox schemas. The Python port expresses those schemas as JSON Schema draft 2020-12 dictionaries in `src/pi_protocol/schemas.py` and validates them with `jsonschema.Draft202012Validator` in `src/pi_protocol/codec.py`. Field names are on-the-wire names and stay camelCase.

## Transport support

Every transport carries the same complete bytes: `[uint32-be CBOR length][CBOR payload]`. Transports may split or coalesce those bytes arbitrarily.

This package does not bundle a transport. Consumers provide a byte-stream transport that preserves byte order and reports stream closure. Custom transports must handle arbitrary frame fragmentation and coalescing.

All transports are untrusted. Configure matching frame limits and enforce access controls appropriate for the transport before exposing a connection to the protocol. Unix sockets can use filesystem permissions, while network transports can authenticate during connection establishment.

## Encoding and framing

`encode_cbor()` and `decode_cbor()` implement the protocol's strict RFC 8949 subset. `encode_frame()` and `FrameDecoder` handle framing independently of schemas and CBOR.

The CBOR subset supports:

- `None` and booleans
- finite numbers, with integers restricted to JavaScript's safe range and non-integers encoded as float64
- UTF-8 strings
- `bytes` byte strings
- definite-length arrays
- definite-length maps represented by `dict` objects with unique string keys

JSON-valued protocol fields reject CBOR byte strings and non-plain objects. Top-level non-values, non-finite or unsafe numbers, malformed UTF-8, tags, indefinite-length items, trailing data, excessive nesting, oversized values, cycles, and unknown object properties are rejected.

Default limits are 16 MiB per CBOR payload/frame, 1,000,000 array elements or map entries, and 64 nested item levels. Options can configure these limits. A frame decoder validates the declared length before buffering payload bytes.

All schemas reject unknown object properties. The protocol is experimental and has no compatibility guarantees.

## Development

From the repository root:

```bash
uv sync --all-packages
uv run pytest packages/pi-protocol
uv run ruff check packages/pi-protocol
```
