introspection-remote-proto

Python bindings for the introspection dev tunnel wire protocol.

The canonical schema is crates/protocol/proto/remote.proto in this repository — the single source of truth for the WebSocket tunnel between the introspection dev CLI and the cloud-side Data Plane. The Rust CLI codegens it via prost (crates/protocol); this package carries the generated Python protobuf module so the cloud consumes exactly the same contract instead of hand-syncing its own copy.

from introspection_remote_proto import remote_pb2, SCHEMA_VERSION

frame = remote_pb2.Frame()
frame.heartbeat.SetInParent()
wire = frame.SerializeToString()

Regenerating

remote_pb2.py is generated from the canonical .proto — never hand-edited. After changing crates/protocol/proto/remote.proto, regenerate from this directory:

./gen.sh

The script runs protoc --python_out against the canonical proto and writes src/introspection_remote_proto/remote_pb2.py. Keep the protobuf protoc version aligned with the runtime pin in pyproject.toml (protobuf>=5.29,<6); the generated header records the version it was produced with.

Versioning

The package version tracks the schema. SCHEMA_VERSION (mirroring the Rust crate's constant) bumps only on breaking envelope changes; additive, proto3-default-compatible field changes are a minor/patch release that both the CLI and the Data Plane can adopt independently.

Published to PyPI from this repo's release workflow. The Data Plane depends on it (introspection-remote-proto) and re-exports remote_pb2 through introspection_common.remote.

Releases are change-gated: the package publishes a new version only when the schema (or this package) actually changes — it is versioned independently of the CLI, starting at 0.1.0, not on every CLI release.