statewire 0.0.0.dev0__tar.gz → 0.1.1__tar.gz

statewire-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+uv.lock

statewire-0.1.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: statewire
+Version: 0.1.1
+Summary: Replicate one JSON object over an SSE op stream + a command endpoint
+Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
+License-Expression: MIT
+Requires-Python: <4.0,>=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pinned<0.2,>=0.1.0
+Description-Content-Type: text/markdown
+
+# statewire
+
+The Statewire protocol for Python, on top of [pinned](https://github.com/Yonom/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.
+
+```python
+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:
+
+```python
+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
+
+```sh
+uv sync
+uv run pytest
+```

statewire-0.1.1/README.md

@@ -0,0 +1,117 @@
+# statewire
+
+The Statewire protocol for Python, on top of [pinned](https://github.com/Yonom/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.
+
+```python
+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:
+
+```python
+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
+
+```sh
+uv sync
+uv run pytest
+```

statewire-0.1.1/examples/demo_app.py

@@ -0,0 +1,60 @@
+"""Runnable Statewire demo backend for examples/vite-statewire-example.
+
+Run from python/statewire/statewire:
+
+    uv run --with 'uvicorn[standard]' uvicorn examples.demo_app:app --port 8000
+
+Instances are served under /threads/{id}: GET /threads/{id}/stream for the
+state stream, POST /threads/{id}/commands for commands. The demo
+exercises the whole frontend surface: a slow `increment` (visible optimistic
+window), a hard limit that rejects with a message (StatewireSendError), a
+`write_haiku` that streams text via text-insert `add` ops, and a transient
+`event` op.
+"""
+
+import asyncio
+
+from fastapi import FastAPI
+from pinned import PinnedHost
+from statewire import StatewireReject, Statewire, command
+
+MAX_COUNT = 10
+
+HAIKU = "state flows as one stream —\nevery client, every tab,\nthe same truth appears\n"
+
+
+class Counter(Statewire):
+    async def lifespan(self):
+        self.state = {"count": 0, "haiku": ""}
+        yield
+
+    @command
+    async def increment(self):
+        if self.state["count"] >= MAX_COUNT:
+            raise StatewireReject(
+                f"the counter is full (max {MAX_COUNT})", payload={"max": MAX_COUNT}
+            )
+        await asyncio.sleep(0.4)  # a slow handler makes the optimistic window visible
+        self.state["count"] += 1
+        if self.state["count"] == MAX_COUNT:
+            self.emit({"kind": "toast", "text": "the counter is full — reset to keep going"})
+
+    @command
+    async def reset(self):
+        self.state["count"] = 0
+        self.state["haiku"] = ""
+
+    @command
+    async def write_haiku(self):
+        self.state["haiku"] = ""
+        self.create_task(self._stream_haiku())
+
+    async def _stream_haiku(self):
+        for char in HAIKU:
+            self.state["haiku"] += char
+            await asyncio.sleep(0.03)
+
+
+router = PinnedHost(Counter)
+app = FastAPI(lifespan=router.lifespan)
+app.include_router(router, prefix="/threads")

statewire-0.1.1/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "statewire"
+version = "0.1.1"
+description = "Replicate one JSON object over an SSE op stream + a command endpoint"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "pinned>=0.1.0,<0.2",
+    "fastapi>=0.115",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/assistant-ui/harness-sdk"
+
+[tool.uv.sources]
+pinned = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/statewire"]

statewire-0.1.1/src/statewire/__init__.py

@@ -0,0 +1,20 @@
+from .api import (
+    CommandExecution,
+    CommandExecutionResolvers,
+    Statewire,
+    StatewireReject,
+    command,
+)
+from .assistant_transport import AssistantTransport
+from .state import StateProxy, plain
+
+__all__ = [
+    "Statewire",
+    "AssistantTransport",
+    "command",
+    "CommandExecution",
+    "CommandExecutionResolvers",
+    "StatewireReject",
+    "StateProxy",
+    "plain",
+]