statewire 0.4.4__tar.gz → 0.4.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statewire
-Version: 0.4.4
+Version: 0.4.6
 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.4 → statewire-0.4.6}/pyproject.toml

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

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

@@ -38,7 +38,12 @@ the command whole):
 
 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
+frames. A command-carrying request opens with a single full-state ``set``
+emitted once every submitted command is acked, so the first state frame
+carries all of the request's commands' effects; a rejection or run error
+before that point sends the error frame with no state frame ahead of it. A
+command-free request opens with the snapshot immediately. The stream runs
+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["runs"][0]["error"]``) becomes
@@ -206,8 +211,9 @@ _Item = tuple[str, Any]
 
 
 class _Run:
-    def __init__(self, replica: Any) -> None:
+    def __init__(self, replica: Any, *, holding: bool = False) -> None:
         self.replica = replica
+        self.holding = holding
         self.error: str | None = None
         self.error_payload: Any = None
         self.done = False
@@ -313,7 +319,10 @@ class AssistantTransport(Statewire):
         parent_id = body.get("parentId")
         if not isinstance(parent_id, str):
             parent_id = None
-        run = _Run(json.loads(snapshot)["ops"][0]["value"])
+        run = _Run(
+            json.loads(snapshot)["ops"][0]["value"],
+            holding=bool(commands) or parent_id is not None,
+        )
         self._at_run = run
         watcher = self.create_task(
             self._assistant_transport_run(
@@ -474,6 +483,10 @@ class AssistantTransport(Statewire):
             acked = 0
             open_pending: set[int] = set()
 
+            def release_hold() -> None:
+                run.holding = False
+                run.push(("state", [_legacy_op("set", [], run.replica)]))
+
             def idle() -> bool:
                 return (
                     submit.done()
@@ -493,7 +506,7 @@ class AssistantTransport(Statewire):
                     run.replica, frame = _translate_op(run.replica, op)
                     if frame is not None:
                         op_frames.append(frame)
-                if op_frames:
+                if op_frames and not run.holding:
                     run.push(("state", op_frames))
                 for res in envelope.get("res", []):
                     if res["type"] == "pending":
@@ -507,6 +520,8 @@ class AssistantTransport(Statewire):
                         )
                 if "ack" in envelope:
                     acked = envelope["ack"]
+                    if acked >= total and run.holding:
+                        release_hold()
                 if finish and not idle():
                     fin = envelope.get("fin", {})
                     raise _RunError(
@@ -566,7 +581,8 @@ class AssistantTransport(Statewire):
         if live is not None:
             live.attachments.append(aq)
         try:
-            yield fmt.state([_legacy_op("set", [], run.replica)])
+            if not (initial and run.holding):
+                yield fmt.state([_legacy_op("set", [], run.replica)])
             if live is not None:
                 while True:
                     try:

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

@@ -43,7 +43,9 @@ class Harness(AssistantTransport):
         raise StatewireReject("not allowed")
 
     @command("splice")
-    async def splice(self, cmd):
+    async def splice(self, cmd, *, ctx):
+        ctx.ack()
+        await asyncio.sleep(0)
         self.state["messages"].insert(0, {"first": True})
         del self.state["meta"]["title"]
 
@@ -109,7 +111,7 @@ async def post_run(client, body, thread="t1"):
     return await client.post(f"/threads/{thread}/assistant-transport/api/chat", json=body)
 
 
-async def test_data_stream_response_streams_snapshot_then_ops_until_idle():
+async def test_data_stream_first_frame_is_a_full_set_carrying_command_effects():
     async with statewire_client(Harness) as (app, client):
         response = await post_run(
             client,
@@ -137,18 +139,16 @@ async def test_data_stream_response_streams_snapshot_then_ops_until_idle():
         frames = data_stream_frames(response.text)
         assert all(prefix == "aui-state" for prefix, _ in frames)
         ops = state_ops(frames)
-        assert ops[0] == {
-            "type": "set",
-            "path": [],
-            "value": {"messages": [], "text": "", "meta": {"title": None}},
-        }
+        assert ops[0]["type"] == "set" and ops[0]["path"] == []
+        assert ops[0]["value"]["messages"] == [
+            {"role": "user", "parts": [{"type": "text", "text": "hi"}]}
+        ]
         replica = apply_legacy_ops({}, ops)
         assert replica == {
             "messages": [{"role": "user", "parts": [{"type": "text", "text": "hi"}]}],
             "text": "echo: hi",
             "meta": {"title": None},
         }
-        assert any(op["type"] == "append-text" and op["path"] == ["text"] for op in ops)
 
 
 async def test_unknown_fields_are_tolerated_and_commands_pass_through_whole():
@@ -189,13 +189,13 @@ async def test_unknown_command_type_is_an_error_frame_then_eof():
         assert "unknown method" in frames[-1][1]
 
 
-async def test_rejected_command_is_an_error_frame_then_eof():
+async def test_rejected_command_is_an_error_frame_with_no_state_frame():
     async with statewire_client(Harness) as (app, client):
         response = await post_run(
             client, {"commands": [{"type": "reject-me"}], "state": {}}
         )
         frames = data_stream_frames(response.text)
-        assert frames[-1] == ("3", "not allowed")
+        assert frames == [("3", "not allowed")]
 
 
 async def test_malformed_body_is_400():
@@ -287,8 +287,7 @@ async def test_sse_mode_rejections_ride_an_error_chunk():
     async with statewire_client(SSEHarness) as (app, client):
         response = await post_run(client, {"commands": [{"type": "reject-me"}]})
         frames = sse_frames(response.text)
-        assert frames[-1] == "[DONE]"
-        assert frames[-2] == {"type": "error", "error": "not allowed"}
+        assert frames == [{"type": "error", "error": "not allowed"}, "[DONE]"]
 
 
 class _PostStream:
@@ -451,7 +450,7 @@ async def test_mid_run_disconnect_then_resume_streams_snapshot_and_live_tail():
         ) as stream:
             assert stream.status == 200
             buffer = b""
-            while b'"append-text"' not in buffer:
+            while b'"a"' not in buffer:
                 buffer += await stream.next_chunk()
         instance = (await host.directory.get("t1")).instance
 
@@ -706,6 +705,102 @@ async def test_disconnect_before_idle_leaves_the_run_executing():
         assert ops[0]["value"]["text"] == "ab"
 
 
+class HeldHarness(Harness):
+    """Each command writes state eagerly but acks only when its gate opens."""
+
+    def __init__(self, ctx):
+        super().__init__(ctx)
+        self.releases = {"a": asyncio.Event(), "b": asyncio.Event()}
+
+    @command("held")
+    async def held(self, cmd, *, ctx):
+        self.state["text"] += cmd["value"]
+        await self.releases[cmd["value"]].wait()
+        ctx.ack()
+        self.state["text"] += cmd["value"].upper()
+
+    @command("held-reject")
+    async def held_reject(self, cmd, *, ctx):
+        self.state["text"] += cmd["value"]
+        await self.releases[cmd["value"]].wait()
+        raise StatewireReject("late reject")
+
+
+def post_held_chat(app, commands):
+    return _PostStream(
+        app,
+        "/threads/t1/assistant-transport/api/chat",
+        {"commands": commands, "state": {}, "threadId": "t1"},
+    )
+
+
+async def test_no_state_frame_until_every_command_is_acked():
+    async with statewire_client(HeldHarness) as (app, client):
+        commands = [
+            {"type": "held", "value": "a"},
+            {"type": "held", "value": "b"},
+        ]
+        async with post_held_chat(app, commands) as stream:
+            with pytest.raises(TimeoutError):
+                await stream.next_chunk(0.1)
+            instance = (await app.state.pinned_host.directory.get("t1")).instance
+            instance.releases["a"].set()
+            with pytest.raises(TimeoutError):
+                await stream.next_chunk(0.1)
+            instance.releases["b"].set()
+            buffer = await stream.until_closed()
+        ops = state_ops(data_stream_frames(buffer.decode()))
+        assert ops[0]["type"] == "set" and ops[0]["path"] == []
+        assert apply_legacy_ops({}, ops)["text"] == "abAB"
+
+
+async def test_held_deltas_fold_into_the_release_snapshot():
+    async with statewire_client(HeldHarness) as (app, client):
+        commands = [
+            {"type": "held", "value": "a"},
+            {"type": "held", "value": "b"},
+        ]
+        async with post_held_chat(app, commands) as stream:
+            instance = (await app.state.pinned_host.directory.get("t1")).instance
+            instance.releases["a"].set()
+            instance.releases["b"].set()
+            buffer = await stream.until_closed()
+        ops = state_ops(data_stream_frames(buffer.decode()))
+        assert ops[0]["type"] == "set" and ops[0]["path"] == []
+        appended = [op["value"] for op in ops if op["type"] == "append-text"]
+        assert "a" not in appended and "b" not in appended
+        assert apply_legacy_ops({}, ops)["text"] == "abAB"
+
+
+async def test_rejection_while_holding_is_an_error_frame_with_no_state_frame():
+    async with statewire_client(HeldHarness) as (app, client):
+        commands = [
+            {"type": "held", "value": "a"},
+            {"type": "reject-me"},
+        ]
+        async with post_held_chat(app, commands) as stream:
+            buffer = await stream.until_closed()
+        frames = data_stream_frames(buffer.decode())
+        assert frames == [("3", "not allowed")]
+
+
+async def test_partially_acked_commands_then_rejection_send_no_state_frame():
+    async with statewire_client(HeldHarness) as (app, client):
+        commands = [
+            {"type": "held", "value": "a"},
+            {"type": "held-reject", "value": "b"},
+        ]
+        async with post_held_chat(app, commands) as stream:
+            instance = (await app.state.pinned_host.directory.get("t1")).instance
+            instance.releases["a"].set()
+            with pytest.raises(TimeoutError):
+                await stream.next_chunk(0.1)
+            instance.releases["b"].set()
+            buffer = await stream.until_closed()
+        frames = data_stream_frames(buffer.decode())
+        assert frames == [("3", "late reject")]
+
+
 class RunHarness(AssistantTransport):
     """Host speaking the canonical run/* dialect; no legacy handlers."""