statewire

The Statewire protocol for Python, on top of pinned.

Statewire is a PinnedAPI (one live instance per id cluster-wide) that replicates one JSON object — any State — over envelope streams:

  • GET /stream (SSE) and /ws (WebSocket twin) — every message is an envelope {"ops"?, "res"?, "ack"?, "syn"?, "fin"?}. The first envelope on attach is a full snapshot (ops: [{"op": "replace", "path": [], "value": <state>}]) with the syn handshake {"lastSeq", "lease"?}: the client's last admitted command seq (-1 unknown client) and the attach's writer-lease token. Sessions are single-writer per client id: attaching takes the lease, and any other live stream of that client id ends with fin {"reason": "superseded"}.
  • POST /commands — one command at a time, a method call {"method": <name>, "params": [...]} routed to the @command handler registered under that name. Commands carry Statewire-Client-Id, a monotonic Statewire-Command-Seq, and the current Statewire-Lease. The HTTP response is receipt only (200 {} | 400 malformed | 409 seq gap | 412 unknown client | 423 stale lease); the protocol statuses carry a discriminator body ({"error": "seq-gap" | "unknown-client" | "stale-lease", "message"?}) so clients can tell statewire's verdict from a middleware-minted bare status; verdicts ride the stream. Over WS the same commands arrive as {"method": <name>, "params": [...], "seq": <int>} frames — no lease header, holding the connection is the lease.

ops are Immer-style deltas with array paths (object keys as strings, list indices as ints): replace sets a value, add splices — its final int segment indexes into the parent, so a list parent gains an element and a string parent gains text at that offset — remove deletes, and event is transient (never in snapshots). ack is the cumulative watermark for the issuing client, emitted after the command's effect ops. res carries responses ({"seq", "type": "accepted" | "rejected" | "pending" | "crashed" | "result-unavailable", "message"?, "payload"?}): the envelope that first covers a seq states the command's fate — a terminal response, a pending response (result follows in a later envelope), or nothing = void. fin ({"reason": "evicted" | "error" | "gone" | "superseded", "message"?}) is always the last envelope.

Handler outcomes: the return value becomes the terminal accepted payload; raise StatewireReject becomes rejected; returning a CommandExecution keeps the command open past the handler's return — its ack() flushes the covering ack with a pending response, its resolve/reject produce the late terminal response (post-ack failures are terminal rejected, not stream faults). Duplicate seqs never re-run: they are answered from a ~30s result cache / in-flight registry — in the POST body over HTTP (200 {"res": ...}), as a res on the stream over WS.

The protocol is generic: it says nothing about messages, queues, or agents — it only replicates whatever self.state dict you assign and dispatches whatever commands you declare. Domain-specific layers (see the harness-sdk package) sit on top.

from statewire import Statewire, command


class Thread(Statewire):
    async def lifespan(self):
        self.state = {"messages": []}  # yielding without setting self.state throws
        yield

    @command
    async def addMessage(self, message_id: str, content: str):
        self.state["messages"].append({"id": message_id, "content": content})
        self.create_task(self.run())  # long work outside the inbox; returning here => ack

@command registers the handler under the method's own name; @command("name") registers it under an explicit wire name. Params are positional. An unknown method or a params/signature mismatch is a rejected response on the stream, not an HTTP error.

self.state is a change-tracking proxy: mutate it plainly and the ops replicate to every attached stream. += on a string becomes an end-offset text-insert add op of the suffix; other mutations become narrow replace / add / remove ops. Mutations within one synchronous segment coalesce into a single envelope.

Extra routes

Need an endpoint beyond the protocol trio (a health check, a file upload)? Decorate a method with pinned's route escape hatch:

from pinned import route
from statewire import Statewire


class Thread(Statewire):
    @route.get("/health")
    async def health(self, request):
        return {"ok": True}

The reserved protocol paths /statewire, /stream, /commands, and /ws are Statewire's own; a subclass that decorates a @route onto any of them raises at class-definition time rather than silently shadowing the protocol.

GET /statewire is the meta endpoint: {"protocol": 1, "commands": [<names>]}. Setting envelope_ts = True on the subclass stamps every non-empty envelope (snapshot included) with "ts" (epoch ms) for debuggability.

Layering

pinned        one live instance per id, with an HTTP surface
  └─ statewire   the Statewire protocol: /stream + /ws (envelopes) + /commands
       └─ harness-sdk   HarnessState types, queueing, deepagents

Develop

uv sync
uv run pytest

Project links

Data verified by PyPI on Aug 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.16.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Yonom from gravatar.com Yonom

GitHub Statistics

Data verified by PyPI on Aug 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <4.0, >=3.12

Provides Extra

langgraph

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

statewire-0.4.3.tar.gz (75.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

statewire-0.4.3-py3-none-any.whl (45.4 kB view details)

Uploaded Python 3

File details

Details for the file statewire-0.4.3.tar.gz.

File metadata

  • Download URL: statewire-0.4.3.tar.gz
  • Upload date:
  • Size: 75.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for statewire-0.4.3.tar.gz
Algorithm Hash digest
SHA256 a84309bf1c27d5ec23f3a040d9a82734b7b75962596b518f93728b4b399e13fa
MD5 65cfc9cae9c56dd73c31faaa8e718ec8
BLAKE2b-256 3021cdf1256c2b8eebb88a6f8b44e961975eca52a8f96e92cf0878c04faf0994

See more details on using hashes here.

Provenance

The following attestation bundles were made for statewire-0.4.3.tar.gz:

Publisher: pypi-publish.yaml on assistant-ui/harness-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file statewire-0.4.3-py3-none-any.whl.

File metadata

  • Download URL: statewire-0.4.3-py3-none-any.whl
  • Upload date:
  • Size: 45.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for statewire-0.4.3-py3-none-any.whl
Algorithm Hash digest
SHA256 d1a276f160c7c257fde5cd64c9f91f6f5dcef0a6625d8f629b2c49adae5cdd8f
MD5 294d373832b98a43d442065b21f1f291
BLAKE2b-256 f63f75e483b9cc4170f511ade2fe5a6e671dec11ba4196a937cb95a154196dbc

See more details on using hashes here.

Provenance

The following attestation bundles were made for statewire-0.4.3-py3-none-any.whl:

Publisher: pypi-publish.yaml on assistant-ui/harness-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.5

2 files

0.12.4

2 files

0.12.3

2 files

0.12.2

2 files

0.12.1

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.7

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

This release

0.4.3 This release

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.0

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Pre-release

0.0.0.dev0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page