Use msgspec models for the server-side wire protocol - #8
Draft
messa wants to merge 1 commit into
Draft
Conversation
Introduce msgspec models (protocol.py) for the JSON metadata exchanged with the agent and decode/encode them on the server instead of working with untyped dicts. recv_command now returns the raw metadata bytes, which handle_client decodes into a typed Header / DataMeta through a new decode_message() helper; msgspec validation errors are turned into ProtocolError, replacing the manual field checks. The wire format stays plain JSON, so the stdlib-only agent — which must keep running on Debian 11/12 without a venv, where python3-msgspec is unavailable — interoperates unchanged. Only the server gains the msgspec dependency. As a side effect the server no longer logs the raw metadata (which included the client token from the header): recv_command now logs only the metadata byte length. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Musim si to jeste promyslet, jestli je toto cesta. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Decode and encode the agent↔server wire-protocol JSON with typed msgspec models on the server side, instead of working with untyped dicts and hand-rolled validation.
Why server-only
The agent is designed to run on Debian 11/12 without a venv — on the system Python with apt packages only — where
python3-msgspecdoes not exist (it only landed in Debian 13). So the agent stays stdlib-only and keeps usingjson. The wire format remains plain JSON, so the json-encoding agent and the msgspec-decoding server interoperate unchanged; only the server (which runs in Docker with a uv venv) gains themsgspecdependency.Changes
protocol.pywith msgspec models:Header,Prefix,Auth,DataMeta,OkLengthReply.recv_commandnow returns the raw metadata bytes;handle_clientdecodes them into typed models via a newdecode_message()helper that turns msgspec validation/decode errors intoProtocolError(replacing the manual field checks).send_replyencodes via msgspec;check_client_authworks on theAuthmodel.msgspecto the server dependencies and re-locked (server/uv.lock, ande2e_tests/uv.locksince e2e installs the server).Side effect: client token no longer logged
The server previously logged parsed metadata at debug level (
Received %s %r), which included the client token from the header.recv_commandnow logs only the metadata byte length.Testing
make checkis green for all three components: agent (2, unchanged/stdlib), server (12), e2e (7 — including the real TLS round-trip, which exercises the json-agent ↔ msgspec-server path end to end).Note: msgspec is a compiled package; this was verified locally on Python 3.13. Whether a wheel exists for Python 3.14 (the top of the CI matrix) will be confirmed by CI. The agent is unaffected (stdlib only).
🤖 Generated with Claude Code