harness-sdk-python 0.27.0__tar.gz → 0.28.0__tar.gz

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.27.0
+Version: 0.28.0
 Summary: RunManager: the harness-sdk runs subsystem for Python Statewire hosts
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "harness-sdk-python"
-version = "0.27.0"
+version = "0.28.0"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/src/harness_sdk/deepagents.py

@@ -66,6 +66,7 @@ class DeepagentsMessages:
             )
         self._checkpointer = checkpointer
         self._captured: dict[str, Any] | None = None
+        self._ephemeral: dict[str, dict[str, Any]] = {}
 
     async def boot(
         self, state: Any, *, index: CheckpointIndex, thread_id: str
@@ -241,6 +242,26 @@ class DeepagentsMessages:
             )
         return snapshot
 
+    def upsert_ephemeral_message(self, message: dict[str, Any]) -> None:
+        """Render an in-flight ``{id, role, text}`` entry in ``state["messages"]``; an ``append_messages`` of the same id replaces it durably."""
+        if message["role"] not in ("user", "assistant"):
+            raise ValueError(f"unsupported message role: {message['role']!r}")
+        if message["id"] not in self._ephemeral and any(
+            m["id"] == message["id"] for m in self._thread.transcript
+        ):
+            raise ValueError(f"message {message['id']!r} is already durable")
+        self._ephemeral[message["id"]] = {
+            "id": message["id"],
+            "type": "human" if message["role"] == "user" else "ai",
+            "content": message["text"],
+        }
+        self._restamp()
+
+    def drop_ephemeral_message(self, message_id: str) -> None:
+        """Remove an in-flight entry from the ``state["messages"]`` projection."""
+        del self._ephemeral[message_id]
+        self._restamp()
+
     def _append_user(self, message: dict[str, Any]) -> dict[str, Any]:
         entry = {"id": message["id"], "type": "human", "content": _user_text(message)}
         if not any(m["id"] == entry["id"] for m in plain(self._state["messages"])):
@@ -257,4 +278,8 @@ class DeepagentsMessages:
         for message in self._thread.transcript:
             branch, siblings = self._thread.sibling_info(message["id"])
             stamped.append({**message, "branch": {"id": branch, "siblings": siblings}})
+        durable = {message["id"] for message in stamped}
+        stamped.extend(
+            entry for id_, entry in self._ephemeral.items() if id_ not in durable
+        )
         self._replace(stamped)

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/src/harness_sdk/voice.py

@@ -9,12 +9,15 @@ and the turn commit both stay host-owned.
 
 ``voice/start {offer}`` seeds the provider from the thread transcript (at
 most 128 messages, tail taken) and projects ``state["voice"] = {clientId,
-status, answer, turns}`` — the SDP answer rides the applied state. The
-session is bound to the issuing client's connection: ``voice/end`` from the
-owner, a provider ``closed`` event, or a connection drop ends it. Provider
-turn events accumulate in the in-memory turn buffer projected as
-``state["voice"]["turns"]``; at session end the completed turns commit
-through ``Host.commit_voice_turns`` and in-progress turns drop.
+status, answer}`` — the SDP answer rides the applied state. The session is
+bound to the issuing client's connection: ``voice/end`` from the owner, a
+provider ``closed`` event, or a connection drop ends it. Provider turn
+events render live in ``state["messages"]`` through
+``Host.upsert_ephemeral_message`` (message id = turn id); each completed
+turn commits through ``Host.commit_voice_turns`` (serialized, in
+done-order) and the durable entry replaces the ephemeral one under the
+same id, a failed commit keeps its turns for the next flush; session end
+flushes the remaining done turns and drops in-progress turns.
 
 Rejections: ``voice-active`` (a session is already live), ``no-voice``
 (no voice manager declared, or ``voice/end`` with no session),
@@ -58,22 +61,21 @@ def _capped_seed(seed: Any) -> "list[VoiceManager.SeedMessage]":
 
 
 class VoiceManager(Tray):
-    """One live voice session: the provider handle, the in-memory turn
-    buffer, and its wire projection; ended sessions commit and self-delete."""
+    """One live voice session: the provider handle and the in-memory turn
+    buffer rendered live in ``state["messages"]``; completed turns commit
+    per turn and ended sessions flush and self-delete."""
 
     connection_poll = 0.5
 
     clientId = observable(None)
     status = observable("connecting")
     answer = observable(None)
-    turns = observable([])
 
     state = observable(
         {
             "clientId": clientId,
             "status": status,
             "answer": answer,
-            "turns": turns,
         }
     )
 
@@ -81,6 +83,7 @@ class VoiceManager(Tray):
         super().__init__(**kwargs)
         self._provider: "VoiceProvider | None" = None
         self._turns: list[dict[str, Any]] = []
+        self._flushing = asyncio.Lock()
         self._ended = False
         self._watcher: "asyncio.Task[Any] | None" = None
 
@@ -121,7 +124,7 @@ class VoiceManager(Tray):
         def closed(self, reason: str) -> None: ...
 
     class Host(Protocol):
-        """The host seam: the thread transcript in, committed turns out."""
+        """The host seam: the thread transcript in, live and committed turns out."""
 
         async def get_voice_seed(self) -> "list[VoiceManager.SeedMessage]":
             """The transcript as ``{role, text}`` seed messages, tool/system noise skipped."""
@@ -131,6 +134,14 @@ class VoiceManager(Tray):
             """Write completed ``{id, role, text}`` turns to the thread's durable transcript."""
             ...
 
+        def upsert_ephemeral_message(self, message: dict[str, Any]) -> None:
+            """Render an in-flight ``{id, role, text}`` turn in ``state["messages"]``; same id updates in place."""
+            ...
+
+        def drop_ephemeral_message(self, message_id: str) -> None:
+            """Remove an in-flight turn from the ``state["messages"]`` projection."""
+            ...
+
     # ─── Session lifecycle ──────────────────────────────────
 
     async def _begin(
@@ -180,19 +191,12 @@ class VoiceManager(Tray):
                 await provider.close()
             except Exception:
                 logger.exception("voice provider close failed for session %r", self.id)
-        done = [
-            {"id": t["id"], "role": t["role"], "text": t["text"]}
-            for t in self._turns
-            if t["done"]
-        ]
-        self._turns = []
-        self.turns.value = []
+        await self._flush()
+        turns, self._turns = self._turns, []
+        for turn in turns:
+            self._host.drop_ephemeral_message(turn["id"])
         self.status.value = "closed"
-        try:
-            if done:
-                await self.handler.__self__.commit_voice_turns(done)
-        finally:
-            self.delete()
+        self.delete()
 
     # ─── Events sink ────────────────────────────────────────
 
@@ -202,22 +206,48 @@ class VoiceManager(Tray):
                 return turn
         raise ValueError(f"turn {turn_id!r} was never started")
 
-    def _project_turns(self) -> None:
-        self.turns.value = [dict(turn) for turn in self._turns]
+    @property
+    def _host(self) -> Any:
+        return self.handler.__self__
+
+    def _render(self, turn: dict[str, Any]) -> None:
+        self._host.upsert_ephemeral_message(
+            {"id": turn["id"], "role": turn["role"], "text": turn["text"]}
+        )
+
+    async def _flush(self) -> None:
+        # the lock serializes commits in done-order across turn-done and end
+        async with self._flushing:
+            done = [t for t in self._turns if t["done"]]
+            if not done:
+                return
+            try:
+                await self._host.commit_voice_turns(
+                    [{"id": t["id"], "role": t["role"], "text": t["text"]} for t in done]
+                )
+            except Exception:
+                logger.exception("voice session %r turn commit failed", self.id)
+                return
+            committed = {t["id"] for t in done}
+            self._turns = [t for t in self._turns if t["id"] not in committed]
+            for turn_id in committed:
+                self._host.drop_ephemeral_message(turn_id)
 
     def turn_started(self, turn_id: str, role: str) -> None:
         if self._ended:
             return
         if any(turn["id"] == turn_id for turn in self._turns):
             raise ValueError(f"turn {turn_id!r} already started")
-        self._turns.append({"id": turn_id, "role": role, "text": "", "done": False})
-        self._project_turns()
+        turn = {"id": turn_id, "role": role, "text": "", "done": False}
+        self._turns.append(turn)
+        self._render(turn)
 
     def turn_delta(self, turn_id: str, text: str) -> None:
         if self._ended:
             return
-        self._turn(turn_id)["text"] += text
-        self._project_turns()
+        turn = self._turn(turn_id)
+        turn["text"] += text
+        self._render(turn)
 
     def turn_done(self, turn_id: str, text: str) -> None:
         if self._ended:
@@ -225,7 +255,8 @@ class VoiceManager(Tray):
         turn = self._turn(turn_id)
         turn["text"] = text
         turn["done"] = True
-        self._project_turns()
+        self._render(turn)
+        self._spawn(self._flush())
 
     def tool_requested(self, request: "VoiceManager.ToolRequest") -> None:
         logger.info("voice session %r tool request ignored: %r", self.id, request)
@@ -272,7 +303,12 @@ class VoiceManagerNamespace(TrayMapNamespace):
 
     def __init__(self, api: Any, spec: TrayDescriptor) -> None:
         super().__init__(api, spec)
-        for name in ("get_voice_seed", "commit_voice_turns"):
+        for name in (
+            "get_voice_seed",
+            "commit_voice_turns",
+            "upsert_ephemeral_message",
+            "drop_ephemeral_message",
+        ):
             if not callable(getattr(api, name, None)):
                 raise TypeError(
                     f"{type(api).__name__} must implement {name} "

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/tests/test_deepagents_messages.py

@@ -164,6 +164,57 @@ async def test_ingest_turn_refetch_discards_the_capture():
     assert ids(state) == ["u1", "a0", "u2", "a1"]
 
 
+# ─── Ephemeral messages ─────────────────────────────────────
+
+
+async def test_ephemeral_message_renders_and_updates_in_place():
+    _, _, _, messages, state = await seeded()
+    messages.upsert_ephemeral_message({"id": "v1", "role": "user", "text": "hel"})
+    assert state["messages"][-1] == {"id": "v1", "type": "human", "content": "hel"}
+    messages.upsert_ephemeral_message({"id": "v1", "role": "user", "text": "hello"})
+    assert ids(state) == ["u1", "a0", "u2", "a1", "v1"]
+    assert state["messages"][-1]["content"] == "hello"
+
+
+async def test_ephemeral_message_survives_a_turn_ingest():
+    _, _, graph, messages, state = await seeded()
+    messages.upsert_ephemeral_message({"id": "v1", "role": "assistant", "text": "hi"})
+    await turn(graph, messages, Ctx("message-send", (user("u3", "three"),)))
+    assert ids(state) == ["u1", "a0", "u2", "a1", "u3", "a2", "v1"]
+    assert state["messages"][-1] == {"id": "v1", "type": "ai", "content": "hi"}
+
+
+async def test_append_messages_replaces_the_ephemeral_entry_durably():
+    _, _, _, messages, state = await seeded()
+    messages.upsert_ephemeral_message({"id": "v1", "role": "user", "text": "spoken"})
+    await messages.append_messages([{"id": "v1", "role": "user", "text": "spoken"}])
+    assert ids(state) == ["u1", "a0", "u2", "a1", "v1"]
+    assert "branch" in state["messages"][-1]
+    messages.drop_ephemeral_message("v1")
+    assert ids(state) == ["u1", "a0", "u2", "a1", "v1"]
+
+
+async def test_drop_ephemeral_message_removes_the_entry():
+    _, _, _, messages, state = await seeded()
+    messages.upsert_ephemeral_message({"id": "v1", "role": "user", "text": "oops"})
+    messages.drop_ephemeral_message("v1")
+    assert ids(state) == ["u1", "a0", "u2", "a1"]
+    with pytest.raises(KeyError):
+        messages.drop_ephemeral_message("v1")
+
+
+async def test_upsert_ephemeral_rejects_a_durable_id():
+    _, _, _, messages, _ = await seeded()
+    with pytest.raises(ValueError, match="already durable"):
+        messages.upsert_ephemeral_message({"id": "u1", "role": "user", "text": "x"})
+
+
+async def test_upsert_ephemeral_rejects_an_unsupported_role():
+    _, _, _, messages, _ = await seeded()
+    with pytest.raises(ValueError, match="unsupported message role"):
+        messages.upsert_ephemeral_message({"id": "v1", "role": "system", "text": "x"})
+
+
 # ─── Rewind ─────────────────────────────────────────────────
 
 

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/tests/test_voice.py

@@ -1,5 +1,7 @@
-"""VoiceManager contract: session lifecycle, wire projection, and the commit
-of completed turns at session end."""
+"""VoiceManager contract: session lifecycle, the live turn projection in
+``state["messages"]``, and the per-turn commit at turn-done."""
+
+import asyncio
 
 from run_helpers import _statement, assert_rejected
 from statewire_helpers import post_frame, stream_of
@@ -17,6 +19,17 @@ from voice_helpers import (
 from harness_sdk import VoiceManager
 
 
+async def until(predicate, timeout: float = 5) -> None:
+    deadline = asyncio.get_running_loop().time() + timeout
+    while not predicate():
+        assert asyncio.get_running_loop().time() < deadline, "condition never held"
+        await asyncio.sleep(0.01)
+
+
+def messages_of(replica):
+    return replica.get("messages")
+
+
 async def test_start_seeds_provider_and_projects_session():
     bench = Bench(transcript=[seed_message(0), seed_message(1)])
     async with voice_host(bench) as (drv, _app):
@@ -30,7 +43,6 @@ async def test_start_seeds_provider_and_projects_session():
             "clientId": drv.client_id,
             "status": "live",
             "answer": ANSWER,
-            "turns": [],
         }
         assert bench.contexts[0].client_id == drv.client_id
 
@@ -70,7 +82,7 @@ async def test_provider_failure_rejects_voice_unavailable():
         assert rsp["type"] == "accepted", rsp
 
 
-async def test_turn_events_project_into_state():
+async def test_turn_streams_into_messages_ephemerally():
     bench = Bench()
     async with voice_host(bench) as (drv, _app):
         await drv.command("voice/start", {"offer": OFFER})
@@ -79,30 +91,110 @@ async def test_turn_events_project_into_state():
         events.turn_delta("t1", "hello ")
         events.turn_delta("t1", "there")
         await drv.wait(
-            lambda s: (voice_of(s) or {}).get("turns")
-            == [{"id": "t1", "role": "user", "text": "hello there", "done": False}]
+            lambda s: messages_of(s)
+            == [{"id": "t1", "type": "human", "content": "hello there"}]
         )
+        assert bench.commits == []
+
+
+async def test_turn_done_commits_promptly_under_the_same_id():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        events = bench.events()
+        events.turn_started("t1", "user")
         events.turn_done("t1", "hello there!")
+        await until(
+            lambda: bench.commits
+            == [[{"id": "t1", "role": "user", "text": "hello there!"}]]
+        )
+        await drv.wait(
+            lambda s: messages_of(s)
+            == [{"id": "t1", "type": "human", "content": "hello there!"}]
+        )
+        # the durable entry replaced the ephemeral one: end recommits nothing
+        await drv.command("voice/end")
+        assert len(bench.commits) == 1
+
+
+async def test_turns_commit_in_done_order():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        events = bench.events()
+        events.turn_started("t1", "user")
+        events.turn_done("t1", "question")
+        await until(lambda: len(bench.commits) == 1)
+        events.turn_started("t2", "assistant")
+        events.turn_done("t2", "answer")
+        await until(lambda: len(bench.commits) == 2)
+        assert bench.commits == [
+            [{"id": "t1", "role": "user", "text": "question"}],
+            [{"id": "t2", "role": "assistant", "text": "answer"}],
+        ]
+
+
+async def test_commit_failure_keeps_the_turn_until_the_next_flush():
+    bench = Bench(commit_failures=[RuntimeError("checkpointer down")])
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        events = bench.events()
+        events.turn_started("t1", "user")
+        events.turn_done("t1", "question")
+        await until(lambda: bench.commit_failures == [])
+        assert bench.commits == []
         await drv.wait(
-            lambda s: (voice_of(s) or {}).get("turns")
-            == [{"id": "t1", "role": "user", "text": "hello there!", "done": True}]
+            lambda s: messages_of(s)
+            == [{"id": "t1", "type": "human", "content": "question"}]
+        )
+        # session end retries the kept turn
+        await drv.command("voice/end")
+        assert bench.commits == [[{"id": "t1", "role": "user", "text": "question"}]]
+        await drv.wait(
+            lambda s: voice_of(s) is None
+            and messages_of(s)
+            == [{"id": "t1", "type": "human", "content": "question"}]
         )
 
 
-async def test_end_commits_done_turns_and_drops_in_progress():
+async def test_commit_failure_retries_in_order_with_the_next_turn():
+    bench = Bench(commit_failures=[RuntimeError("checkpointer down")])
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        events = bench.events()
+        events.turn_started("t1", "user")
+        events.turn_done("t1", "question")
+        await until(lambda: bench.commit_failures == [])
+        events.turn_started("t2", "assistant")
+        events.turn_done("t2", "answer")
+        await until(lambda: bench.commits != [])
+        assert bench.commits == [
+            [
+                {"id": "t1", "role": "user", "text": "question"},
+                {"id": "t2", "role": "assistant", "text": "answer"},
+            ]
+        ]
+
+
+async def test_end_drops_in_progress_turns():
     bench = Bench()
     async with voice_host(bench) as (drv, _app):
         await drv.command("voice/start", {"offer": OFFER})
         events = bench.events()
         events.turn_started("t1", "user")
         events.turn_done("t1", "question")
+        await until(lambda: len(bench.commits) == 1)
         events.turn_started("t2", "assistant")
         events.turn_delta("t2", "half an ans")
         rsp = await drv.command("voice/end")
         assert rsp["type"] == "accepted", rsp
         assert bench.provider.closed
         assert bench.commits == [[{"id": "t1", "role": "user", "text": "question"}]]
-        await drv.wait(lambda s: voice_of(s) is None)
+        await drv.wait(
+            lambda s: voice_of(s) is None
+            and messages_of(s)
+            == [{"id": "t1", "type": "human", "content": "question"}]
+        )
 
 
 async def test_end_with_no_done_turns_commits_nothing():
@@ -112,7 +204,7 @@ async def test_end_with_no_done_turns_commits_nothing():
         bench.events().turn_started("t1", "assistant")
         await drv.command("voice/end")
         assert bench.commits == []
-        await drv.wait(lambda s: voice_of(s) is None)
+        await drv.wait(lambda s: voice_of(s) is None and messages_of(s) == [])
 
 
 async def test_end_from_other_client_rejects_not_voice_owner():

{harness_sdk_python-0.27.0 → harness_sdk_python-0.28.0}/tests/voice_helpers.py

@@ -47,13 +47,22 @@ class FakeVoiceProvider:
         self.closed = True
 
 
+def wire_entry(turn: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": turn["id"],
+        "type": "human" if turn["role"] == "user" else "ai",
+        "content": turn["text"],
+    }
+
+
 @dataclass
 class Bench:
-    """The test's host seams: the seed transcript in, committed turns out."""
+    """The test's host seams: the seed transcript in, live and committed turns out."""
 
     provider: FakeVoiceProvider = field(default_factory=FakeVoiceProvider)
     transcript: list[dict[str, Any]] = field(default_factory=list)
     commits: list[list[dict[str, Any]]] = field(default_factory=list)
+    commit_failures: list[Exception] = field(default_factory=list)
     contexts: list[VoiceManager.SessionContext] = field(default_factory=list)
 
     def events(self) -> VoiceManager.Events:
@@ -65,13 +74,35 @@ def make_voice_host(bench: Bench, *, declare: bool = True):
     class Host(Statewire):
         async def lifespan(self):
             self.state = {"messages": []}
+            self._durable: list[dict[str, Any]] = []
+            self._ephemeral: dict[str, dict[str, Any]] = {}
             yield
 
+        # mirrors the DeepagentsMessages projection: durable transcript, ephemeral tail
+        def _project_messages(self):
+            durable_ids = {m["id"] for m in self._durable}
+            self.state["messages"] = [
+                *self._durable,
+                *(e for i, e in self._ephemeral.items() if i not in durable_ids),
+            ]
+
         async def get_voice_seed(self):
             return [dict(message) for message in bench.transcript]
 
         async def commit_voice_turns(self, turns):
+            if bench.commit_failures:
+                raise bench.commit_failures.pop(0)
             bench.commits.append(turns)
+            self._durable.extend(wire_entry(turn) for turn in turns)
+            self._project_messages()
+
+        def upsert_ephemeral_message(self, message):
+            self._ephemeral[message["id"]] = wire_entry(message)
+            self._project_messages()
+
+        def drop_ephemeral_message(self, message_id):
+            del self._ephemeral[message_id]
+            self._project_messages()
 
         @command("voice/start")
         async def voice_start(self, params, *, ctx):