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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.26.0
+Version: 0.27.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.26.0 → harness_sdk_python-0.27.0}/pyproject.toml

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

{harness_sdk_python-0.26.0 → harness_sdk_python-0.27.0}/src/harness_sdk/__init__.py

@@ -14,6 +14,14 @@ from .checkpoints import (
 from .deepagents import DeepagentsMessages
 from .linear_thread import linear_thread
 from .run_manager import RunManager, RunManagerDescriptor, run_manager
+from .voice import (
+    VoiceManager,
+    VoiceManagerDescriptor,
+    VoiceProvider,
+    end_voice,
+    start_voice,
+    voice_manager,
+)
 
 __all__ = [
     "CheckpointIndex",
@@ -26,10 +34,16 @@ __all__ = [
     "RunManager",
     "RunManagerDescriptor",
     "Snapshot",
+    "VoiceManager",
+    "VoiceManagerDescriptor",
+    "VoiceProvider",
     "checkpoint_thread",
+    "end_voice",
     "langgraph_checkpoints",
     "langgraph_snapshot",
     "langgraph_switch_values",
     "linear_thread",
     "run_manager",
+    "start_voice",
+    "voice_manager",
 ]

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

@@ -150,6 +150,56 @@ class DeepagentsMessages:
         """Append harness user messages to the wire state as human entries, deduplicated by id; returns the langgraph turn entries."""
         return [self._append_user(message) for message in messages]
 
+    async def append_messages(self, messages: list[dict[str, Any]]) -> None:
+        """Append ``{id, role, text}`` entries as a new checkpoint on the current tip and restamp; the voice commit path."""
+        from langchain_core.messages import AIMessage, HumanMessage
+        from langgraph.checkpoint.base import empty_checkpoint
+        from langgraph.checkpoint.base.id import uuid6
+
+        if not messages:
+            raise ValueError("messages must be non-empty")
+        for message in messages:
+            if message["role"] not in ("user", "assistant"):
+                raise ValueError(f"unsupported message role: {message['role']!r}")
+        entries = [
+            (HumanMessage if m["role"] == "user" else AIMessage)(
+                id=m["id"], content=m["text"]
+            )
+            for m in messages
+        ]
+        parent = {"configurable": {"thread_id": self._thread_id, "checkpoint_ns": ""}}
+        saved = await self._checkpointer.aget_tuple(parent)
+        if saved is None:
+            checkpoint = empty_checkpoint()
+            step = -1
+        else:
+            checkpoint = {**saved.checkpoint}
+            step = (saved.metadata or {}).get("step", -1)
+            parent["configurable"]["checkpoint_id"] = saved.checkpoint["id"]
+        version = self._checkpointer.get_next_version(
+            checkpoint["channel_versions"].get("messages"), None
+        )
+        checkpoint = {
+            **checkpoint,
+            "id": str(uuid6(clock_seq=-2)),
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "channel_values": {
+                **checkpoint["channel_values"],
+                "messages": [
+                    *checkpoint["channel_values"].get("messages", []),
+                    *entries,
+                ],
+            },
+            "channel_versions": {
+                **checkpoint["channel_versions"],
+                "messages": version,
+            },
+        }
+        metadata = {"source": "update", "step": step + 1, "parents": {}}
+        await self._checkpointer.aput(parent, checkpoint, metadata, {"messages": version})
+        await self._thread.ingest_latest()
+        self._restamp()
+
     async def switch_branch(self, branch_id: int) -> None:
         """Switch to ``branch_id``: its tip becomes the checkpointer's latest checkpoint and the wire state rebaselines."""
         transcript, lineage = await self._thread.switch_state(branch_id)

harness_sdk_python-0.27.0/src/harness_sdk/voice.py

@@ -0,0 +1,382 @@
+"""VoiceManager: the harness-sdk voice subsystem, one tray per live session.
+
+``@voice_manager()`` on a Statewire host method declares the subsystem: the
+decorated method is the provider factory (``def voice(self, ctx) ->
+VoiceProvider``), ``self.<name>`` is the command surface, and each session
+lives in its own ephemeral tray, minted by ``voice/start`` and deleted when
+the session ends. The host implements ``VoiceManager.Host``: the seed read
+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.
+
+Rejections: ``voice-active`` (a session is already live), ``no-voice``
+(no voice manager declared, or ``voice/end`` with no session),
+``not-voice-owner`` (``voice/end`` from another client),
+``voice-unavailable`` (the factory or ``provider.start`` raised).
+"""
+
+import asyncio
+import functools
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, Protocol, TypedDict
+from uuid import uuid4
+
+from pinned.trays import Tray, TrayDescriptor, TrayMapNamespace
+from statepatch import observable
+from statewire import StatewireReject
+
+logger = logging.getLogger(__name__)
+
+_SEED_LIMIT = 128
+_SEED_ROLES = ("user", "assistant", "system")
+
+
+def _reject(reason: str, message: str) -> StatewireReject:
+    return StatewireReject(message, payload={"reason": reason})
+
+
+def _capped_seed(seed: Any) -> "list[VoiceManager.SeedMessage]":
+    if not isinstance(seed, list):
+        raise TypeError(f"get_voice_seed must return a list, got {seed!r}")
+    for message in seed:
+        if (
+            not isinstance(message, dict)
+            or message.get("role") not in _SEED_ROLES
+            or not isinstance(message.get("text"), str)
+        ):
+            raise TypeError(f"seed messages must be {{role, text}}, got {message!r}")
+    return seed[-_SEED_LIMIT:]
+
+
+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."""
+
+    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,
+        }
+    )
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._provider: "VoiceProvider | None" = None
+        self._turns: list[dict[str, Any]] = []
+        self._ended = False
+        self._watcher: "asyncio.Task[Any] | None" = None
+
+    def items(self):
+        yield from ()
+
+    class SeedMessage(TypedDict):
+        """One transcript message handed to the provider as session history."""
+
+        role: Literal["user", "assistant", "system"]
+        text: str
+
+    @dataclass(frozen=True)
+    class ToolRequest:
+        call_id: str
+        name: str
+        arguments: str
+
+    @dataclass(frozen=True)
+    class SessionContext:
+        """The provider factory's per-session context."""
+
+        client_id: str
+
+    class Events(Protocol):
+        """The sink a provider drives; the subsystem hands it to ``start``."""
+
+        def turn_started(self, turn_id: str, role: Literal["user", "assistant"]) -> None: ...
+
+        def turn_delta(self, turn_id: str, text: str) -> None: ...
+
+        def turn_done(self, turn_id: str, text: str) -> None: ...
+
+        def tool_requested(self, request: "VoiceManager.ToolRequest") -> None: ...
+
+        def rollover_approaching(self, rollover_id: str, deadline: float) -> None: ...
+
+        def closed(self, reason: str) -> None: ...
+
+    class Host(Protocol):
+        """The host seam: the thread transcript in, committed turns out."""
+
+        async def get_voice_seed(self) -> "list[VoiceManager.SeedMessage]":
+            """The transcript as ``{role, text}`` seed messages, tool/system noise skipped."""
+            ...
+
+        async def commit_voice_turns(self, turns: list[dict[str, Any]]) -> None:
+            """Write completed ``{id, role, text}`` turns to the thread's durable transcript."""
+            ...
+
+    # ─── Session lifecycle ──────────────────────────────────
+
+    async def _begin(
+        self, offer: str, seed: "list[VoiceManager.SeedMessage]", caller: Any,
+        applied: Callable[[], None],
+    ) -> Any:
+        self.clientId.value = caller.client_id
+        try:
+            provider = await self.handler(
+                VoiceManager.SessionContext(client_id=caller.client_id)
+            )
+            answer = await provider.start(offer, seed=seed, events=self)
+            if not isinstance(answer, str) or answer == "":
+                raise TypeError(f"provider.start must return an SDP answer, got {answer!r}")
+        except Exception as exc:
+            self._ended = True
+            self.delete()
+            raise _reject("voice-unavailable", f"voice session failed to start: {exc}")
+        self._provider = provider
+        self.answer.value = answer
+        self.status.value = "live"
+        applied()
+        self._watcher = self._spawn(self._watch(caller))
+        return {"answer": answer}
+
+    async def _watch(self, caller: Any) -> None:
+        while caller.is_connected:
+            await asyncio.sleep(self.connection_poll)
+        await self._background_end("connection-drop")
+
+    async def _background_end(self, reason: str) -> None:
+        try:
+            await self._end(reason)
+        except Exception:
+            logger.exception("voice session %r failed to end cleanly", self.id)
+
+    async def _end(self, reason: str) -> None:
+        if self._ended:
+            return
+        self._ended = True
+        watcher, self._watcher = self._watcher, None
+        if watcher is not None and watcher is not asyncio.current_task():
+            watcher.cancel()
+        provider, self._provider = self._provider, None
+        if provider is not None:
+            try:
+                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 = []
+        self.status.value = "closed"
+        try:
+            if done:
+                await self.handler.__self__.commit_voice_turns(done)
+        finally:
+            self.delete()
+
+    # ─── Events sink ────────────────────────────────────────
+
+    def _turn(self, turn_id: str) -> dict[str, Any]:
+        for turn in self._turns:
+            if turn["id"] == turn_id:
+                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]
+
+    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()
+
+    def turn_delta(self, turn_id: str, text: str) -> None:
+        if self._ended:
+            return
+        self._turn(turn_id)["text"] += text
+        self._project_turns()
+
+    def turn_done(self, turn_id: str, text: str) -> None:
+        if self._ended:
+            return
+        turn = self._turn(turn_id)
+        turn["text"] = text
+        turn["done"] = True
+        self._project_turns()
+
+    def tool_requested(self, request: "VoiceManager.ToolRequest") -> None:
+        logger.info("voice session %r tool request ignored: %r", self.id, request)
+
+    def rollover_approaching(self, rollover_id: str, deadline: float) -> None:
+        logger.info(
+            "voice session %r rollover %r ignored (deadline %s)",
+            self.id, rollover_id, deadline,
+        )
+
+    def closed(self, reason: str) -> None:
+        if self._ended:
+            return
+        self._spawn(self._background_end(reason))
+
+
+class VoiceProvider(Protocol):
+    """The vendor seam: one live voice session's transport and control plane."""
+
+    async def start(
+        self, offer: str, *,
+        seed: "list[VoiceManager.SeedMessage]",
+        events: "VoiceManager.Events",
+    ) -> str:
+        """Open the session from an SDP offer and return the SDP answer; events flow into the sink."""
+        ...
+
+    async def append_context(
+        self, text: str, *, channel: Literal["speakable", "commentary", "developer"]
+    ) -> None: ...
+
+    async def return_tool_result(self, call_id: str, output: str) -> None: ...
+
+    async def select_rollover(
+        self, rollover_id: str, seed: "list[VoiceManager.SeedMessage]"
+    ) -> None: ...
+
+    async def close(self) -> None: ...
+
+
+class VoiceManagerNamespace(TrayMapNamespace):
+    """The subsystem's command surface: at most one live session, its tray
+    mounted as ``state["voice"]``."""
+
+    def __init__(self, api: Any, spec: TrayDescriptor) -> None:
+        super().__init__(api, spec)
+        for name in ("get_voice_seed", "commit_voice_turns"):
+            if not callable(getattr(api, name, None)):
+                raise TypeError(
+                    f"{type(api).__name__} must implement {name} "
+                    "(VoiceManager.Host) to host @voice_manager"
+                )
+        self._session: VoiceManager | None = None
+        self._starting = False
+        api.state["voice"] = None
+
+    def live(self) -> VoiceManager | None:
+        """The live session's tray; None at rest."""
+        session = self._session
+        return session if session is not None and not session._ended else None
+
+    def _mount(self, tray: VoiceManager) -> None:
+        if tray.storage._restored:
+            return  # a crash's leftover row: the pump finishes its delete unmounted
+        self._session = tray
+        self._api.state["voice"] = tray.state
+
+    def _unmount(self, tray: VoiceManager) -> None:
+        if self._session is tray:
+            self._session = None
+            self._api.state["voice"] = None
+
+    async def start(self, params: Any, *, ctx: Any) -> Any:
+        if not isinstance(params, dict):
+            raise _reject("invalid-message", "params must be an object")
+        offer = params.get("offer")
+        if not isinstance(offer, str) or offer == "":
+            raise _reject("invalid-message", "offer must be a non-empty SDP string")
+        if self._starting or self.live() is not None:
+            raise _reject("voice-active", "a voice session is already live")
+        self._starting = True
+        try:
+            seed = _capped_seed(await self._api.get_voice_seed())
+            tray = await self.get_or_create(uuid4().hex)
+            assert isinstance(tray, VoiceManager)
+            return await tray._begin(offer, seed, ctx.caller, ctx.applied)
+        finally:
+            self._starting = False
+
+    async def end(self, *, ctx: Any) -> None:
+        session = self.live()
+        if session is None:
+            raise _reject("no-voice", "no voice session is live")
+        if session.clientId.value != ctx.caller.client_id:
+            raise _reject("not-voice-owner", "voice/end must come from the session owner")
+        await session._end("client")
+        ctx.applied()
+
+
+class VoiceManagerDescriptor(TrayDescriptor):
+    namespace_cls = VoiceManagerNamespace
+
+    def __init__(self, handler: Any) -> None:
+        super().__init__(VoiceManager, handler, always_open=False)
+
+        async def mount(api: Any, id: str, tray: VoiceManager):
+            ns: VoiceManagerNamespace = getattr(api, self.name)
+            ns._mount(tray)
+            yield
+            ns._unmount(tray)
+
+        self._on_activate.append(mount)
+
+
+def voice_manager() -> Callable[[Callable[..., Any]], VoiceManagerDescriptor]:
+    """Declare the voice subsystem on a Statewire host: the decorated method
+    is the per-session provider factory and ``self.<name>`` is the command
+    surface."""
+
+    def decorate(fn: Callable[..., Any]) -> VoiceManagerDescriptor:
+        if inspect.iscoroutinefunction(fn):
+            return VoiceManagerDescriptor(fn)
+
+        @functools.wraps(fn)
+        async def factory(self: Any, ctx: "VoiceManager.SessionContext") -> Any:
+            return fn(self, ctx)
+
+        return VoiceManagerDescriptor(factory)
+
+    return decorate
+
+
+def _voice_of(host: Any) -> VoiceManagerNamespace | None:
+    for cls in type(host).__mro__:
+        for name, member in vars(cls).items():
+            if isinstance(member, VoiceManagerDescriptor):
+                return getattr(host, name)
+    return None
+
+
+async def start_voice(host: Any, params: Any, *, ctx: Any) -> Any:
+    """The ``voice/start`` command body: routes to the host's declared voice manager."""
+    namespace = _voice_of(host)
+    if namespace is None:
+        raise _reject("no-voice", "this host declares no voice manager")
+    return await namespace.start(params, ctx=ctx)
+
+
+async def end_voice(host: Any, *, ctx: Any) -> None:
+    """The ``voice/end`` command body: routes to the host's declared voice manager."""
+    namespace = _voice_of(host)
+    if namespace is None:
+        raise _reject("no-voice", "this host declares no voice manager")
+    return await namespace.end(ctx=ctx)

harness_sdk_python-0.27.0/tests/test_voice.py

@@ -0,0 +1,192 @@
+"""VoiceManager contract: session lifecycle, wire projection, and the commit
+of completed turns at session end."""
+
+from run_helpers import _statement, assert_rejected
+from statewire_helpers import post_frame, stream_of
+from voice_helpers import (
+    ANSWER,
+    OFFER,
+    Bench,
+    FakeVoiceProvider,
+    seed_message,
+    side_command,
+    voice_host,
+    voice_of,
+)
+
+from harness_sdk import VoiceManager
+
+
+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):
+        rsp = await drv.command("voice/start", {"offer": OFFER})
+        assert rsp["type"] == "accepted", rsp
+        assert rsp["payload"] == {"answer": ANSWER}
+        assert bench.provider.calls == [("start", OFFER, bench.transcript)]
+        await drv.wait(lambda s: (voice_of(s) or {}).get("status") == "live")
+        voice = voice_of(drv.replica)
+        assert voice == {
+            "clientId": drv.client_id,
+            "status": "live",
+            "answer": ANSWER,
+            "turns": [],
+        }
+        assert bench.contexts[0].client_id == drv.client_id
+
+
+async def test_start_while_active_rejects_voice_active():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        assert_rejected(
+            await drv.command("voice/start", {"offer": OFFER}), "voice-active"
+        )
+
+
+async def test_undeclared_host_rejects_no_voice():
+    bench = Bench()
+    async with voice_host(bench, declare=False) as (drv, _app):
+        assert_rejected(await drv.command("voice/start", {"offer": OFFER}), "no-voice")
+        assert_rejected(await drv.command("voice/end"), "no-voice")
+
+
+async def test_end_with_no_session_rejects_no_voice():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        assert_rejected(await drv.command("voice/end"), "no-voice")
+
+
+async def test_provider_failure_rejects_voice_unavailable():
+    bench = Bench(provider=FakeVoiceProvider(fail=RuntimeError("no api key")))
+    async with voice_host(bench) as (drv, _app):
+        assert_rejected(
+            await drv.command("voice/start", {"offer": OFFER}), "voice-unavailable"
+        )
+        await drv.wait(lambda s: voice_of(s) is None)
+        # the failed session left nothing behind: a fresh start succeeds
+        bench.provider.fail = None
+        rsp = await drv.command("voice/start", {"offer": OFFER})
+        assert rsp["type"] == "accepted", rsp
+
+
+async def test_turn_events_project_into_state():
+    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_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}]
+        )
+        events.turn_done("t1", "hello there!")
+        await drv.wait(
+            lambda s: (voice_of(s) or {}).get("turns")
+            == [{"id": "t1", "role": "user", "text": "hello there!", "done": True}]
+        )
+
+
+async def test_end_commits_done_turns_and_drops_in_progress():
+    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")
+        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)
+
+
+async def test_end_with_no_done_turns_commits_nothing():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        bench.events().turn_started("t1", "assistant")
+        await drv.command("voice/end")
+        assert bench.commits == []
+        await drv.wait(lambda s: voice_of(s) is None)
+
+
+async def test_end_from_other_client_rejects_not_voice_owner():
+    bench = Bench()
+    async with voice_host(bench) as (drv, app):
+        await drv.command("voice/start", {"offer": OFFER})
+        rsp = await side_command(app, drv._client, "voice/end")
+        assert_rejected(rsp, "not-voice-owner")
+        # the session survived the stranger's end
+        await drv.wait(lambda s: (voice_of(s) or {}).get("status") == "live")
+
+
+async def test_provider_closed_event_ends_and_commits():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        events = bench.events()
+        events.turn_started("t1", "assistant")
+        events.turn_done("t1", "goodbye")
+        events.closed("server")
+        await drv.wait(lambda s: voice_of(s) is None)
+        assert bench.commits == [[{"id": "t1", "role": "assistant", "text": "goodbye"}]]
+        assert_rejected(await drv.command("voice/end"), "no-voice")
+
+
+async def test_connection_drop_ends_session(monkeypatch):
+    monkeypatch.setattr(VoiceManager, "connection_poll", 0.02)
+    bench = Bench()
+    async with voice_host(bench) as (drv, app):
+        async with stream_of(app, client_id="c2") as stream:
+            await stream.next_event()
+            response = await post_frame(
+                drv._client,
+                {"cmd": [_statement("voice/start", {"offer": OFFER}, 1)]},
+                client_id="c2",
+            )
+            assert response.status_code == 200, response.text
+            await drv.wait(lambda s: (voice_of(s) or {}).get("clientId") == "c2")
+            events = bench.events()
+            events.turn_started("t1", "user")
+            events.turn_done("t1", "dropped mid-call")
+        await drv.wait(lambda s: voice_of(s) is None)
+        assert bench.provider.closed
+        assert bench.commits == [
+            [{"id": "t1", "role": "user", "text": "dropped mid-call"}]
+        ]
+
+
+async def test_seed_takes_the_128_tail():
+    bench = Bench(transcript=[seed_message(i) for i in range(130)])
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        _, _, seed = bench.provider.calls[0]
+        assert len(seed) == 128
+        assert seed == bench.transcript[-128:]
+
+
+async def test_restart_after_end_gets_a_fresh_session():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        await drv.command("voice/end")
+        await drv.wait(lambda s: voice_of(s) is None)
+        bench.provider = FakeVoiceProvider()
+        rsp = await drv.command("voice/start", {"offer": OFFER})
+        assert rsp["type"] == "accepted", rsp
+        await drv.wait(lambda s: (voice_of(s) or {}).get("status") == "live")
+
+
+async def test_invalid_offer_rejects():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        assert_rejected(await drv.command("voice/start", {}), "invalid-message")
+        assert_rejected(
+            await drv.command("voice/start", {"offer": ""}), "invalid-message"
+        )
+        assert bench.provider.calls == []

harness_sdk_python-0.27.0/tests/voice_helpers.py

@@ -0,0 +1,145 @@
+import asyncio
+import copy
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from pinned import PinnedWorker
+from pinned.testing import MemoryStateStore
+from run_helpers import RunDriver, _statement
+from statewire import Statewire, command
+from statewire_helpers import apply_ops, post_frame, statewire_client, stream_of
+
+from harness_sdk import VoiceManager, end_voice, start_voice, voice_manager
+
+OFFER = "v=0 fake-offer"
+ANSWER = "v=0 fake-answer"
+
+
+class FakeVoiceProvider:
+    """Records calls and hands the test the events sink to drive."""
+
+    def __init__(self, *, answer: str = ANSWER, fail: Exception | None = None) -> None:
+        self.answer = answer
+        self.fail = fail
+        self.calls: list[tuple[Any, ...]] = []
+        self.events: VoiceManager.Events | None = None
+        self.closed = False
+
+    async def start(self, offer, *, seed, events):
+        self.calls.append(("start", offer, list(seed)))
+        if self.fail is not None:
+            raise self.fail
+        self.events = events
+        return self.answer
+
+    async def append_context(self, text, *, channel):
+        self.calls.append(("append_context", text, channel))
+
+    async def return_tool_result(self, call_id, output):
+        self.calls.append(("return_tool_result", call_id, output))
+
+    async def select_rollover(self, rollover_id, seed):
+        self.calls.append(("select_rollover", rollover_id, list(seed)))
+
+    async def close(self):
+        self.closed = True
+
+
+@dataclass
+class Bench:
+    """The test's host seams: the seed transcript in, 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)
+    contexts: list[VoiceManager.SessionContext] = field(default_factory=list)
+
+    def events(self) -> VoiceManager.Events:
+        assert self.provider.events is not None, "provider.start never ran"
+        return self.provider.events
+
+
+def make_voice_host(bench: Bench, *, declare: bool = True):
+    class Host(Statewire):
+        async def lifespan(self):
+            self.state = {"messages": []}
+            yield
+
+        async def get_voice_seed(self):
+            return [dict(message) for message in bench.transcript]
+
+        async def commit_voice_turns(self, turns):
+            bench.commits.append(turns)
+
+        @command("voice/start")
+        async def voice_start(self, params, *, ctx):
+            return await start_voice(self, params, ctx=ctx)
+
+        @command("voice/end")
+        async def voice_end(self, params=None, *, ctx):
+            return await end_voice(self, ctx=ctx)
+
+    if not declare:
+        return Host
+
+    class Declared(Host):
+        @voice_manager()
+        def voice(self, ctx):
+            bench.contexts.append(ctx)
+            return bench.provider
+
+    return Declared
+
+
+@asynccontextmanager
+async def voice_host(bench: Bench, *, declare: bool = True):
+    host_cls = make_voice_host(bench, declare=declare)
+    worker = PinnedWorker(state_store=MemoryStateStore())
+    async with statewire_client(host_cls, worker=worker) as (app, client):
+        client_id = f"c-{uuid4().hex[:8]}"
+        async with stream_of(app, client_id=client_id) as stream:
+            snapshot = await stream.next_event()
+            driver = RunDriver(client, stream, app, client_id=client_id)
+            driver.envelopes.append(snapshot)
+            apply_ops(driver.replica, copy.deepcopy(snapshot))
+            try:
+                yield driver, app
+            finally:
+                for task in driver._posts:
+                    task.cancel()
+                for result in await asyncio.gather(
+                    *driver._posts, return_exceptions=True
+                ):
+                    if isinstance(result, AssertionError):
+                        raise result
+
+
+async def side_command(
+    app, client, method: str, params: Any = None, *, client_id: str = "c2"
+) -> dict[str, Any]:
+    """One command from a second client on its own attach; returns the settled verdict."""
+    async with stream_of(app, client_id=client_id) as stream:
+        await stream.next_event()
+        response = await post_frame(
+            client,
+            {"cmd": [_statement(method, params, 1)]},
+            client_id=client_id,
+        )
+        assert response.status_code == 200, response.text
+        while True:
+            envelope = await stream.next_event()
+            assert envelope is not None, "stream ended unexpectedly"
+            for rsp in envelope.get("cmd", []):
+                if rsp.get("type") not in (None, "applied"):
+                    return rsp
+
+
+def voice_of(replica: dict[str, Any]) -> dict[str, Any] | None:
+    return replica.get("voice")
+
+
+def seed_message(index: int) -> dict[str, Any]:
+    role = "user" if index % 2 == 0 else "assistant"
+    return {"role": role, "text": f"m{index}"}