feat(python): native Python server — parity with the Rust/C# server

[brentrager]

What

Adds python/server/ — a native async WebSocket server for the smooth-operator protocol, the Python parity of the Rust (rust/smooth-operator-server) and C# (dotnet/server) reference servers. Until now Python was a client only (python/src); this fills the gap. The client is untouched — all new code lives in python/server/.

It consumes the published in-process engine smooai-smooth-operator-core: each turn builds a SmoothAgent and maps its run_stream events onto the wire protocol — text deltas → stream_token, tool calls/results → stream_chunk, terminal → eventual_response (with the citations field).

Ported from the C# server (verified against the Rust reference)

Module	Ported from
protocol.py	ProtocolEvents.cs / protocol.rs — byte-for-byte event shapes incl. the triple-nested data.data and the duplicated error descriptor
session_store.py	SessionStore.cs / the Rust storage adapter session+message surface
turn_runner.py	TurnRunner.cs / runner.rs — streaming turn + prior-history replay for memory
dispatcher.py	FrameDispatcher.cs / handler.rs — ping / create_conversation_session / get_session / send_message routing
auth.py	Auth.cs / the Rust verifier seam — permissive default + local HS256-JWT verifier (LocalTokenVerifier), both fail-closed to anonymous
server.py	SmoothOperatorWebSocketExtensions.cs / server.rs + local.rs — per-connection read loop, single outbound writer (asyncio.Queue), graceful drain, serve_local()
backplane.py	the Rust backplane attach/detach seam (in-memory stub)

Graceful SIGTERM drain (per the spec)

A shared asyncio.Event cancel switch on ServerState is the single source of truth for "stop" (default unset). Each connection loop checks the cancel first every iteration (prefer cancel on ties), then races "cancel set" vs "next inbound frame" — with the turn dispatch awaited inside the frame branch so an in-flight turn finishes before the loop exits. SIGTERM/SIGINT handlers stop accepting + set the cancel. A backplane detach always runs after the loop (detach-after-loop).

Tests — pytest, 17 passing

• Protocol conformance — round-trips the spec/conformance/fixtures.json golden messages through the protocol builders + a JSON encode/decode.
• Boot — serve() starts on an ephemeral port and accepts a connection (ping→pong).
• Turn round-trip — real websockets client → create_conversation_session → send_message (engine on MockLlmProvider) → stream_token(s) + terminal eventual_response with the expected text (mirrors WebSocketProtocolIntegrationTests.cs).
• Graceful-drain — set the cancel mid-turn → in-flight turn finishes → loop exits → detach runs.
• Auth verifier seam — valid/expired/forged JWT + the ?token= resolution path.

Run it

cd python/server && uv sync && uv run pytest -q
python -m smooth_operator_server   # local flavor: in-memory, auth off, ws://127.0.0.1:8787/ws

MVP-stubbed seams (left open, not wired)

ACL-filtered retrieval / rerank, tool-confirm/HITL, and the Redis/NATS cross-pod backplane — each a documented seam mirroring the Rust server's later phases.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1935b85

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR