statewire 0.4.3__tar.gz → 0.4.4__tar.gz

{statewire-0.4.3 → statewire-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statewire
-Version: 0.4.3
+Version: 0.4.4
 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

{statewire-0.4.3 → statewire-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "statewire"
-version = "0.4.3"
+version = "0.4.4"
 description = "Replicate one JSON object over an SSE op stream + a command endpoint"
 readme = "README.md"
 license = "MIT"

{statewire-0.4.3 → statewire-0.4.4}/src/statewire/assistant_transport.py

@@ -29,7 +29,8 @@ the command whole):
 - ``add-tool-result`` becomes ``run/input`` with ``{"requestId": <resolved>,
   "response": {"output": <result>, "isError"?, "artifact"?}}``; the requestId
   comes from ``get_input_request_id(toolCallId)``, whose default peeks the
-  unanswered tool-call request in ``state["inputRequests"]`` (None rejects),
+  unanswered tool-call request in ``state["runs"][0]["inputRequests"]``
+  (None rejects),
   and a ``modelContent`` field rejects (unsupported in ``run/input``).
 - A body with a ``parentId`` and no commands is the legacy reload: it becomes
   ``run/reload`` with ``{"sourceId": <child>}`` via ``get_message_child_id``
@@ -39,7 +40,8 @@ A host without the target ``run/*`` handler rejects the batch via the
 ordinary unknown-command path. The response streams state changes as legacy
 frames until the instance is idle — every submitted command settled and no
 live instance task (``create_task`` minus ``unref``) — then EOF. A run error
-recorded into state (``get_run_error``; default ``state["error"]``) becomes
+recorded into state (``get_run_error``; default
+``state["runs"][0]["error"]``) becomes
 an error frame before EOF, its fields beyond ``message`` carried as the
 frame's structured payload where the format allows; a rejection or crash
 becomes an error frame followed by EOF. Client disconnect before EOF
@@ -189,6 +191,11 @@ def _translate_op(replica: Any, op: dict[str, Any]) -> tuple[Any, str | None]:
 _AT_CONSUMED_FIELDS = {"commands", "threadId", "state"}
 
 
+def _run_entry(state: Any) -> Any:
+    runs = state.get("runs") if isinstance(state, dict) else None
+    return runs[0] if isinstance(runs, list) and runs else None
+
+
 class _RunError(Exception):
     def __init__(self, message: str, *, payload: Any = None) -> None:
         super().__init__(message)
@@ -228,12 +235,12 @@ class AssistantTransport(Statewire):
         """The run error to surface as the end-of-stream error frame.
 
         The default peeks the RunManager root-state mount: a non-null
-        ``state["error"]`` object with a string ``message`` is the recorded
-        run error; its fields beyond ``message`` travel as the frame's
-        structured payload where the format carries one. None ends the
-        stream cleanly."""
-        state = plain(self.state)
-        error = state.get("error") if isinstance(state, dict) else None
+        ``state["runs"][0]["error"]`` object with a string ``message`` is the
+        recorded run error; its fields beyond ``message`` travel as the
+        frame's structured payload where the format carries one. None ends
+        the stream cleanly."""
+        entry = _run_entry(plain(self.state))
+        error = entry.get("error") if isinstance(entry, dict) else None
         if isinstance(error, dict) and isinstance(error.get("message"), str):
             return error
         return None
@@ -242,11 +249,12 @@ class AssistantTransport(Statewire):
         """Resolve a legacy toolCallId to the pending run/input requestId.
 
         The default peeks the RunManager root-state mount:
-        ``state["inputRequests"]`` holds ``{..., "response": null}`` entries;
-        the unanswered tool-call request matching ``tool_call_id`` wins. None
-        rejects the legacy ``add-tool-result`` command."""
-        state = plain(self.state)
-        requests = state.get("inputRequests") if isinstance(state, dict) else None
+        ``state["runs"][0]["inputRequests"]`` holds ``{..., "response":
+        null}`` entries; the unanswered tool-call request matching
+        ``tool_call_id`` wins. None rejects the legacy ``add-tool-result``
+        command."""
+        entry = _run_entry(plain(self.state))
+        requests = entry.get("inputRequests") if isinstance(entry, dict) else None
         if not isinstance(requests, list):
             return None
         for request in requests:

statewire-0.4.4/src/statewire/testing.py

@@ -0,0 +1,61 @@
+"""Test helpers: real command contexts for driving @command handlers directly."""
+
+import json
+from typing import Any, Callable
+
+from pinned.host import invalid_id_reason
+
+from .api import (
+    _LAGGARD,
+    _UNSET,
+    Statewire,
+    StatewireClientHandle,
+    StatewireCommandContext,
+    _Invocation,
+)
+from .state import _frozen
+
+
+def command_context(
+    sw: Statewire,
+    *,
+    client_id: str = "test",
+    identity: Any = None,
+    context: dict[str, Any] | None = None,
+    seq: int = 1,
+) -> tuple[StatewireCommandContext, Callable[[], list[dict[str, Any]]]]:
+    """A real ``StatewireCommandContext`` for calling a ``@command`` handler
+    directly, plus ``effects()``: each call flushes the host and returns every
+    envelope delivered to the client so far, decoded (attach snapshot excluded)."""
+    if not isinstance(sw, Statewire):
+        raise TypeError("command_context() requires a Statewire instance")
+    if sw._state is _UNSET:
+        raise RuntimeError(
+            "state is not set; assign sw.state (or enter lifespan) first"
+        )
+    reason = invalid_id_reason(client_id)
+    if reason is not None:
+        raise ValueError(f"invalid client_id: {reason}")
+    if seq < 1:
+        raise ValueError("seq must be >= 1")
+    if context is not None and not isinstance(context, dict):
+        raise TypeError("context must be a dict")
+    q, _snapshot = sw._register(client_id, identity)
+    client = sw._clients[client_id]
+    client.context = _frozen(context) if context is not None else None
+    inv = _Invocation(client, seq)
+    client.inflight[seq] = inv
+    ctx = StatewireCommandContext(StatewireClientHandle(sw, client), inv)
+    captured: list[dict[str, Any]] = []
+
+    def effects() -> list[dict[str, Any]]:
+        sw.flush()
+        while not q.empty():
+            item = q.get_nowait()
+            if item is _LAGGARD:
+                raise RuntimeError("test client fell behind its stream queue")
+            data, _finish = item
+            captured.append(json.loads(data))
+        return captured
+
+    return ctx, effects

{statewire-0.4.3 → statewire-0.4.4}/tests/test_assistant_transport.py

@@ -588,7 +588,7 @@ class BackgroundHarness(AssistantTransport):
         self.fail_with = None
 
     async def lifespan(self):
-        self.state = {"text": "", "error": None}
+        self.state = {"text": "", "runs": []}
         yield
 
     @command("run/steer")
@@ -599,7 +599,7 @@ class BackgroundHarness(AssistantTransport):
         self.state["text"] += "a"
         await self.release.wait()
         if self.fail_with is not None:
-            self.state["error"] = self.fail_with
+            self.state["runs"] = [{"error": self.fail_with}]
         else:
             self.state["text"] += "b"
 
@@ -652,7 +652,7 @@ async def test_run_error_recorded_into_state_is_an_error_frame_before_eof():
         frames = data_stream_frames(buffer.decode())
         assert frames[-1] == ("3", "payment required")
         replica = apply_legacy_ops({}, state_ops(frames))
-        assert replica["error"] == {
+        assert replica["runs"][0]["error"] == {
             "message": "payment required",
             "reason": "payment-required",
         }
@@ -752,7 +752,7 @@ class InputHarness(RunHarness):
     async def lifespan(self):
         self.state = {
             "messages": [],
-            "inputRequests": [
+            "runs": [{"inputRequests": [
                 {
                     "type": "tool-call",
                     "id": "req-old",
@@ -771,7 +771,7 @@ class InputHarness(RunHarness):
                     "toolCallId": "call-2",
                     "response": None,
                 },
-            ],
+            ]}],
         }
         yield
 

statewire-0.4.4/tests/test_testing.py

@@ -0,0 +1,64 @@
+import pytest
+from statewire import Statewire, StatewireCommandContext, command, plain
+from statewire.testing import command_context
+from statewire_helpers import make_instance
+
+
+class Board(Statewire):
+    async def lifespan(self):
+        self.state = {"posts": []}
+        yield
+
+    @command
+    async def post(self, text: str, *, ctx):
+        self.state["posts"].append({"text": text, "by": ctx.caller.identity})
+
+
+def make_board():
+    sw = make_instance(Board)
+    sw.state = {"posts": []}
+    return sw
+
+
+async def test_returns_real_context_backed_by_a_real_client():
+    sw = make_board()
+    ctx, _effects = command_context(
+        sw, client_id="c9", identity="alice", context={"tz": "utc"}
+    )
+    assert type(ctx) is StatewireCommandContext
+    assert ctx.caller.client_id == "c9"
+    assert ctx.caller.identity == "alice"
+    assert ctx.caller.context == {"tz": "utc"}
+    assert ctx.caller.is_connected
+
+
+async def test_handler_sees_state_and_effects_capture_its_ops():
+    sw = make_board()
+    ctx, effects = command_context(sw, identity="alice")
+    await sw.post("hi", ctx=ctx)
+    assert plain(sw.state) == {"posts": [{"text": "hi", "by": "alice"}]}
+    (envelope,) = effects()
+    assert envelope["ops"] == [
+        {"op": "add", "path": ["posts", 0], "value": {"text": "hi", "by": "alice"}}
+    ]
+
+
+async def test_ack_is_captured_as_pending_res_and_ack_watermark():
+    sw = make_board()
+    ctx, effects = command_context(sw, seq=3)
+    ctx.ack()
+    assert effects() == [{"res": [{"seq": 3, "type": "pending"}], "ack": 3}]
+
+
+async def test_rejects_invalid_input():
+    with pytest.raises(TypeError, match="Statewire instance"):
+        command_context(object())  # type: ignore[arg-type]
+    with pytest.raises(RuntimeError, match="state is not set"):
+        command_context(make_instance(Board))
+    sw = make_board()
+    with pytest.raises(ValueError, match="invalid client_id"):
+        command_context(sw, client_id="")
+    with pytest.raises(ValueError, match="seq must be >= 1"):
+        command_context(sw, seq=0)
+    with pytest.raises(TypeError, match="context must be a dict"):
+        command_context(sw, context="nope")  # type: ignore[arg-type]