statewire 0.3.3__tar.gz → 0.4.1__tar.gz

{statewire-0.3.3 → statewire-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statewire
-Version: 0.3.3
+Version: 0.4.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

{statewire-0.3.3 → statewire-0.4.1}/pyproject.toml

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

{statewire-0.3.3 → statewire-0.4.1}/src/statewire/__init__.py

@@ -6,12 +6,14 @@ from .api import (
     command,
 )
 from .assistant_transport import AssistantTransport, add_assistant_transport_facade
+from .legacy import upgrade_legacy_commands
 from .state import StateProxy, plain
 
 __all__ = [
     "Statewire",
     "AssistantTransport",
     "add_assistant_transport_facade",
+    "upgrade_legacy_commands",
     "command",
     "StatewireClientHandle",
     "StatewireCommandContext",

{statewire-0.3.3 → statewire-0.4.1}/src/statewire/assistant_transport.py

@@ -17,8 +17,9 @@ the legacy commands, which are normalized to the canonical ``run/*`` dialect
 (a host-registered handler of the same legacy name always wins and receives
 the command whole):
 
-- ``add-message`` becomes ``run/steer`` with ``{"message": <wire message>}``:
-  a fresh ``legacy_`` id is synthesized, image parts become
+- ``add-message`` becomes ``run/steer`` with ``{"message": <wire message>,
+  "anchorMessageId": <body parentId>}`` (body ``parentId`` null or absent →
+  ``null``): a fresh ``legacy_`` id is synthesized, image parts become
   ``{"type": "file", "mediaType": "image/*", "url"}`` parts, and command-level
   anchors are dropped. A command-level non-null ``sourceId`` makes it
   ``run/edit`` with that ``sourceId`` directly; otherwise, when the body
@@ -31,8 +32,8 @@ the command whole):
   unanswered tool-call request in ``state["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``
-  (None rejects).
+  ``run/reload`` with ``{"sourceId": <child>, "messageId": <fresh legacy_
+  id>}`` via ``get_message_child_id`` (None rejects).
 
 A host without the target ``run/*`` handler rejects the batch via the
 ordinary unknown-command path. The response streams state changes as legacy
@@ -80,7 +81,6 @@ import json
 import secrets
 import time
 from typing import Any, AsyncIterator, Coroutine
-from uuid import uuid4
 
 import httpx
 from fastapi import FastAPI, HTTPException, Request
@@ -89,6 +89,7 @@ from starlette.background import BackgroundTask
 from starlette.responses import Response, StreamingResponse
 
 from .api import _LAGGARD, Statewire
+from .legacy import upgrade_legacy_commands
 from .state import _frozen, plain
 
 _STREAM_HEADERS = {
@@ -195,28 +196,6 @@ class _RunError(Exception):
         self.payload = payload
 
 
-def _legacy_wire_message(message: Any) -> dict[str, Any]:
-    if not isinstance(message, dict):
-        raise _RunError("add-message: message must be an object")
-    parts = message.get("parts")
-    if not isinstance(parts, list):
-        raise _RunError("add-message: message.parts must be an array")
-    converted = []
-    for part in parts:
-        if isinstance(part, dict) and part.get("type") == "image":
-            image = part.get("image")
-            if not isinstance(image, str):
-                raise _RunError("add-message: image part requires a string image field")
-            converted.append({"type": "file", "mediaType": "image/*", "url": image})
-        else:
-            converted.append(part)
-    return {
-        "id": f"legacy_{uuid4().hex}",
-        "role": message.get("role"),
-        "parts": converted,
-    }
-
-
 _Item = tuple[str, Any]
 
 
@@ -429,7 +408,11 @@ class AssistantTransport(Statewire):
         if not commands:
             if parent_id is None:
                 return
-            members = [await self._legacy_reload(parent_id)]
+            members = await upgrade_legacy_commands(
+                [],
+                parent_id=parent_id,
+                get_message_child_id=self.get_message_child_id,
+            )
         else:
             members = [
                 await self._assistant_transport_member(command, parent_id)
@@ -452,49 +435,15 @@ class AssistantTransport(Statewire):
     ) -> dict[str, Any]:
         kind = command["type"]
         registered = type(self)._statewire_commands
-        if kind == "add-message" and "add-message" not in registered:
-            message = _legacy_wire_message(command.get("message"))
-            source_id = command.get("sourceId")
-            if source_id is not None and not isinstance(source_id, str):
-                raise _RunError("add-message: sourceId must be a string or null")
-            if source_id is None and parent_id is not None:
-                source_id = await self.get_message_child_id(parent_id)
-            if source_id is not None:
-                return {
-                    "method": "run/edit",
-                    "params": [{"sourceId": source_id, "message": message}],
-                }
-            return {"method": "run/steer", "params": [{"message": message}]}
-        if kind == "add-tool-result" and "add-tool-result" not in registered:
-            return {
-                "method": "run/input",
-                "params": [await self._legacy_input(command)],
-            }
-        return {"method": kind, "params": [command]}
-
-    async def _legacy_input(self, command: dict[str, Any]) -> dict[str, Any]:
-        if command.get("modelContent") is not None:
-            raise _RunError("add-tool-result: modelContent is not supported")
-        tool_call_id = command.get("toolCallId")
-        if not isinstance(tool_call_id, str):
-            raise _RunError("add-tool-result: toolCallId must be a string")
-        request_id = await self.get_input_request_id(tool_call_id)
-        if request_id is None:
-            raise _RunError(
-                f"add-tool-result: no input request for toolCallId {tool_call_id!r}"
+        if kind in ("add-message", "add-tool-result") and kind not in registered:
+            [member] = await upgrade_legacy_commands(
+                [command],
+                parent_id=parent_id,
+                get_message_child_id=self.get_message_child_id,
+                get_input_request_id=self.get_input_request_id,
             )
-        response: dict[str, Any] = {"output": command.get("result")}
-        if command.get("isError"):
-            response["isError"] = True
-        if "artifact" in command:
-            response["artifact"] = command["artifact"]
-        return {"requestId": request_id, "response": response}
-
-    async def _legacy_reload(self, parent_id: str) -> dict[str, Any]:
-        source_id = await self.get_message_child_id(parent_id)
-        if source_id is None:
-            raise _RunError(f"reload: no child message for parentId {parent_id!r}")
-        return {"method": "run/reload", "params": [{"sourceId": source_id}]}
+            return member
+        return {"method": kind, "params": [command]}
 
     async def _assistant_transport_dispatch(self, method: str, identity: Any) -> None:
         client_id = "at-" + secrets.token_urlsafe(9)

statewire-0.4.1/src/statewire/legacy.py

@@ -0,0 +1,114 @@
+"""Upgrade legacy assistant-transport commands to the canonical ``run/*`` dialect."""
+
+from typing import Any, Awaitable, Callable
+from uuid import uuid4
+
+_Resolver = Callable[[str], Awaitable[str | None]]
+
+
+async def _unresolved(_: str) -> None:
+    return None
+
+
+def _wire_message(message: Any) -> dict[str, Any]:
+    if not isinstance(message, dict):
+        raise ValueError("add-message: message must be an object")
+    parts = message.get("parts")
+    if not isinstance(parts, list):
+        raise ValueError("add-message: message.parts must be an array")
+    converted = []
+    for part in parts:
+        if isinstance(part, dict) and part.get("type") == "image":
+            image = part.get("image")
+            if not isinstance(image, str):
+                raise ValueError("add-message: image part requires a string image field")
+            converted.append({"type": "file", "mediaType": "image/*", "url": image})
+        else:
+            converted.append(part)
+    return {
+        "id": f"legacy_{uuid4().hex}",
+        "role": message.get("role"),
+        "parts": converted,
+    }
+
+
+async def _add_message(
+    command: dict[str, Any], parent_id: str | None, resolve_child: _Resolver
+) -> dict[str, Any]:
+    message = _wire_message(command.get("message"))
+    source_id = command.get("sourceId")
+    if source_id is not None and not isinstance(source_id, str):
+        raise ValueError("add-message: sourceId must be a string or null")
+    if source_id is None and parent_id is not None:
+        source_id = await resolve_child(parent_id)
+    if source_id is not None:
+        return {
+            "method": "run/edit",
+            "params": [{"sourceId": source_id, "message": message}],
+        }
+    return {
+        "method": "run/steer",
+        "params": [{"message": message, "anchorMessageId": parent_id}],
+    }
+
+
+async def _add_tool_result(
+    command: dict[str, Any], resolve_request: _Resolver
+) -> dict[str, Any]:
+    if command.get("modelContent") is not None:
+        raise ValueError("add-tool-result: modelContent is not supported")
+    tool_call_id = command.get("toolCallId")
+    if not isinstance(tool_call_id, str):
+        raise ValueError("add-tool-result: toolCallId must be a string")
+    request_id = await resolve_request(tool_call_id)
+    if request_id is None:
+        raise ValueError(
+            f"add-tool-result: no input request for toolCallId {tool_call_id!r}"
+        )
+    response: dict[str, Any] = {"output": command.get("result")}
+    if command.get("isError"):
+        response["isError"] = True
+    if "artifact" in command:
+        response["artifact"] = command["artifact"]
+    return {"requestId": request_id, "response": response}
+
+
+async def upgrade_legacy_commands(
+    commands: list[dict[str, Any]],
+    *,
+    parent_id: str | None = None,
+    get_message_child_id: _Resolver | None = None,
+    get_input_request_id: _Resolver | None = None,
+) -> list[dict[str, Any]]:
+    """Upgrade a legacy assistant-transport body (``commands`` + optional ``parentId``) into ``run/*`` command members."""
+    resolve_child = get_message_child_id or _unresolved
+    resolve_request = get_input_request_id or _unresolved
+    if not commands:
+        if parent_id is None:
+            return []
+        source_id = await resolve_child(parent_id)
+        if source_id is None:
+            raise ValueError(f"reload: no child message for parentId {parent_id!r}")
+        return [
+            {
+                "method": "run/reload",
+                "params": [
+                    {"sourceId": source_id, "messageId": f"legacy_{uuid4().hex}"}
+                ],
+            }
+        ]
+    members = []
+    for command in commands:
+        kind = command.get("type")
+        if kind == "add-message":
+            members.append(await _add_message(command, parent_id, resolve_child))
+        elif kind == "add-tool-result":
+            members.append(
+                {
+                    "method": "run/input",
+                    "params": [await _add_tool_result(command, resolve_request)],
+                }
+            )
+        else:
+            raise ValueError(f"unknown legacy command type: {kind!r}")
+    return members

{statewire-0.3.3 → statewire-0.4.1}/tests/test_assistant_transport.py

@@ -27,7 +27,7 @@ class Harness(AssistantTransport):
         self.state = {"messages": [], "text": "", "meta": {"title": None}}
         yield
 
-    @command("message/add")
+    @command("demo/echo")
     async def add_message(self, cmd):
         self.seen.append(cmd)
         self.state["messages"].append(cmd["message"])
@@ -120,7 +120,7 @@ async def test_data_stream_response_streams_snapshot_then_ops_until_idle():
             {
                 "commands": [
                     {
-                        "type": "message/add",
+                        "type": "demo/echo",
                         "message": {
                             "role": "user",
                             "parts": [{"type": "text", "text": "hi"}],
@@ -229,7 +229,7 @@ async def test_splice_and_remove_fall_back_to_parent_set():
             {
                 "commands": [
                     {
-                        "type": "message/add",
+                        "type": "demo/echo",
                         "message": {
                             "role": "user",
                             "parts": [{"type": "text", "text": "hi"}],
@@ -266,7 +266,7 @@ async def test_assistant_transport_sse_mode():
             {
                 "commands": [
                     {
-                        "type": "message/add",
+                        "type": "demo/echo",
                         "message": {
                             "role": "user",
                             "parts": [{"type": "text", "text": "hi"}],
@@ -428,7 +428,7 @@ async def test_resume_after_completed_run_replays_with_completed_header():
             {
                 "commands": [
                     {
-                        "type": "message/add",
+                        "type": "demo/echo",
                         "message": {
                             "role": "user",
                             "parts": [{"type": "text", "text": "hi"}],
@@ -453,7 +453,7 @@ async def test_resume_rejects_commands_and_malformed_bodies():
     async with statewire_client(Harness) as (app, client):
         response = await client.post(
             "/threads/t1/assistant-transport/api/resume",
-            json={"commands": [{"type": "message/add"}]},
+            json={"commands": [{"type": "demo/echo"}]},
         )
         assert response.status_code == 400
         assert (
@@ -840,7 +840,8 @@ async def test_add_message_is_normalized_to_run_steer():
         assert response.status_code == 200
         instance = (await app.state.pinned_host.directory.get("t1")).instance
         [(params, caller_id)] = instance.steered
-        assert set(params) == {"message"}
+        assert set(params) == {"message", "anchorMessageId"}
+        assert params["anchorMessageId"] is None
         message = params["message"]
         assert message["id"].startswith("legacy_")
         assert message["role"] == "user"
@@ -1094,7 +1095,9 @@ async def test_parent_id_without_commands_is_normalized_to_run_reload():
         frames = data_stream_frames(response.text)
         assert all(prefix == "aui-state" for prefix, _ in frames)
         instance = (await app.state.pinned_host.directory.get("t1")).instance
-        assert instance.reloaded == [{"sourceId": "m2"}]
+        [params] = instance.reloaded
+        assert params["sourceId"] == "m2"
+        assert params["messageId"].startswith("legacy_")
 
 
 async def test_reload_without_a_resolvable_child_is_an_error_frame():
@@ -1184,7 +1187,8 @@ async def test_add_message_with_a_null_source_id_and_no_parent_is_run_steer():
         instance = (await app.state.pinned_host.directory.get("t1")).instance
         assert instance.edited == []
         [(params, _)] = instance.steered
-        assert set(params) == {"message"}
+        assert set(params) == {"message", "anchorMessageId"}
+        assert params["anchorMessageId"] is None
 
 
 async def test_add_message_with_an_unresolvable_parent_falls_back_to_run_steer():
@@ -1209,4 +1213,5 @@ async def test_add_message_with_an_unresolvable_parent_falls_back_to_run_steer()
         instance = (await app.state.pinned_host.directory.get("t1")).instance
         assert instance.edited == []
         [(params, _)] = instance.steered
-        assert set(params) == {"message"}
+        assert set(params) == {"message", "anchorMessageId"}
+        assert params["anchorMessageId"] == "unknown"

{statewire-0.3.3 → statewire-0.4.1}/tests/test_assistant_transport_client.py

@@ -124,11 +124,11 @@ async def test_client_posts_the_legacy_body_and_applies_state_ops():
             body={"system": "be nice"},
             on_chunk=seen.append,
         )
-        assert await client.send([{"type": "message/add", "message": "hi"}]) is True
+        assert await client.send([{"type": "demo/echo", "message": "hi"}]) is True
         assert client.state == {"text": "hello"}
     assert received == [
         {
-            "commands": [{"type": "message/add", "message": "hi"}],
+            "commands": [{"type": "demo/echo", "message": "hi"}],
             "state": {"text": ""},
             "threadId": "t1",
             "system": "be nice",

statewire-0.4.1/tests/test_legacy.py

@@ -0,0 +1,110 @@
+import pytest
+
+from statewire import upgrade_legacy_commands
+
+
+async def child_of(parent_id: str) -> str | None:
+    return {"m1": "m2"}.get(parent_id)
+
+
+async def request_of(tool_call_id: str) -> str | None:
+    return {"call_1": "req_1"}.get(tool_call_id)
+
+
+async def test_add_message_without_anchor_is_steer():
+    [member] = await upgrade_legacy_commands(
+        [{"type": "add-message", "message": {"role": "user", "parts": [{"type": "text", "text": "hi"}]}}]
+    )
+    assert member["method"] == "run/steer"
+    params = member["params"][0]
+    assert params["anchorMessageId"] is None
+    assert params["message"]["role"] == "user"
+    assert params["message"]["parts"] == [{"type": "text", "text": "hi"}]
+    assert params["message"]["id"].startswith("legacy_")
+
+
+async def test_add_message_with_resolved_child_is_edit():
+    [member] = await upgrade_legacy_commands(
+        [{"type": "add-message", "message": {"role": "user", "parts": []}}],
+        parent_id="m1",
+        get_message_child_id=child_of,
+    )
+    assert member["method"] == "run/edit"
+    assert member["params"][0]["sourceId"] == "m2"
+
+
+async def test_add_message_with_unresolved_child_is_steer_with_anchor():
+    [member] = await upgrade_legacy_commands(
+        [{"type": "add-message", "message": {"role": "user", "parts": []}}],
+        parent_id="unknown",
+        get_message_child_id=child_of,
+    )
+    assert member["method"] == "run/steer"
+    assert member["params"][0]["anchorMessageId"] == "unknown"
+
+
+async def test_add_message_explicit_source_id_wins():
+    [member] = await upgrade_legacy_commands(
+        [{"type": "add-message", "sourceId": "m9", "message": {"role": "user", "parts": []}}],
+        parent_id="m1",
+        get_message_child_id=child_of,
+    )
+    assert member["method"] == "run/edit"
+    assert member["params"][0]["sourceId"] == "m9"
+
+
+async def test_add_message_converts_image_parts():
+    [member] = await upgrade_legacy_commands(
+        [{"type": "add-message", "message": {"role": "user", "parts": [{"type": "image", "image": "https://x/i.png"}]}}]
+    )
+    assert member["params"][0]["message"]["parts"] == [
+        {"type": "file", "mediaType": "image/*", "url": "https://x/i.png"}
+    ]
+
+
+async def test_add_tool_result_is_input():
+    [member] = await upgrade_legacy_commands(
+        [{"type": "add-tool-result", "toolCallId": "call_1", "result": {"ok": True}, "isError": True, "artifact": "a"}],
+        get_input_request_id=request_of,
+    )
+    assert member == {
+        "method": "run/input",
+        "params": [
+            {
+                "requestId": "req_1",
+                "response": {"output": {"ok": True}, "isError": True, "artifact": "a"},
+            }
+        ],
+    }
+
+
+async def test_add_tool_result_without_request_raises():
+    with pytest.raises(ValueError, match="no input request"):
+        await upgrade_legacy_commands(
+            [{"type": "add-tool-result", "toolCallId": "nope", "result": 1}],
+            get_input_request_id=request_of,
+        )
+
+
+async def test_parent_id_without_commands_is_reload():
+    [member] = await upgrade_legacy_commands(
+        [], parent_id="m1", get_message_child_id=child_of
+    )
+    assert member["method"] == "run/reload"
+    params = member["params"][0]
+    assert params["sourceId"] == "m2"
+    assert params["messageId"].startswith("legacy_")
+
+
+async def test_reload_without_child_raises():
+    with pytest.raises(ValueError, match="no child message"):
+        await upgrade_legacy_commands([], parent_id="unknown", get_message_child_id=child_of)
+
+
+async def test_empty_body_is_empty():
+    assert await upgrade_legacy_commands([]) == []
+
+
+async def test_unknown_type_raises():
+    with pytest.raises(ValueError, match="unknown legacy command type"):
+        await upgrade_legacy_commands([{"type": "set-title", "title": "x"}])