harness-sdk-python 0.30.1__tar.gz → 0.31.1__tar.gz

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.30.1
+Version: 0.31.1
 Summary: RunManager: the harness-sdk runs subsystem for Python Statewire hosts
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT
 Requires-Python: <4.0,>=3.12
 Requires-Dist: pinned<0.15,>=0.14.0
-Requires-Dist: statewire<0.13,>=0.12.0
+Requires-Dist: statewire<0.13,>=0.12.3
 Provides-Extra: deepagents
 Requires-Dist: deepagents>=0.6.12; extra == 'deepagents'
 Requires-Dist: langchain-core>=0.3; extra == 'deepagents'

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.30.1"
+version = "0.31.1"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12,<4.0"
-dependencies = ["statewire>=0.12.0,<0.13", "pinned>=0.14.0,<0.15"]
+dependencies = ["statewire>=0.12.3,<0.13", "pinned>=0.14.0,<0.15"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/src/harness_sdk/__init__.py

@@ -21,6 +21,7 @@ from .voice import (
     end_voice,
     start_voice,
     temp_frontend_tool_result,
+    voice_client_departed,
     voice_manager,
 )
 
@@ -47,5 +48,6 @@ __all__ = [
     "run_manager",
     "start_voice",
     "temp_frontend_tool_result",
+    "voice_client_departed",
     "voice_manager",
 ]

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/src/harness_sdk/voice.py

@@ -16,7 +16,11 @@ projects into ``toolCalls`` as ``{callId, name, arguments}``; the owning
 client answers it with ``voice/temp-frontend-tool-result {call_id,
 output}``, which forwards through ``provider.return_tool_result`` and
 clears the entry. 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
+provider ``closed`` event, or the owner staying detached past the
+``departure_grace`` window (the host's ``client_departed`` hook starts the
+timer, the re-check runs at expiry) ends it; ``voice/start`` while the live
+session's owner is detached ends the orphan and starts the new session.
+Provider turn
 events render live in ``state["messages"]`` through
 ``Host.upsert_ephemeral_message`` (message id = turn id), tagged
 ``ephemeral: true`` on the wire; each completed
@@ -34,9 +38,14 @@ turns since the previous task. Interim ``speak`` text and the returned
 result flow back as speakable context appends; a named call's result
 returns via ``provider.return_tool_result``; a failed handler surfaces to
 the model as commentary (task) or an error output (call). The running unit
-projects as ``activeTask`` = ``{taskId, text}``, ``None`` at rest.
-
-Rejections: ``voice-active`` (a session is already live), ``no-voice``
+projects as ``activeTask`` = ``{taskId, text}``, ``None`` at rest. The
+handler's ``call_frontend_tool`` invokes a client-declared tool through the
+same ``toolCalls`` projection: the client's ``voice/temp-frontend-tool-result``
+resolves the await instead of forwarding to the provider, and session end
+fails outstanding awaits.
+
+Rejections: ``voice-active`` (a session is already live and its owner
+attached), ``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).
@@ -107,7 +116,7 @@ class VoiceManager(Tray):
     buffer rendered live in ``state["messages"]``; completed turns commit
     per turn and ended sessions flush and self-delete."""
 
-    connection_poll = 0.5
+    departure_grace = 10.0
 
     clientId = observable(None)
     status = observable("connecting")
@@ -129,12 +138,13 @@ class VoiceManager(Tray):
         self._turns: list[dict[str, Any]] = []
         self._flushing = asyncio.Lock()
         self._ended = False
-        self._watcher: "asyncio.Task[Any] | None" = None
+        self._grace: "asyncio.Task[Any] | None" = None
         self._handoff_pending: list[dict[str, str]] = []
         self._seen_requests: set[str] = set()
         self._delegating = asyncio.Lock()
         self._tasks_run = 0
-        self._client_tools: set[str] = set()
+        self._client_tools: "list[VoiceManager.ToolDef]" = []
+        self._executor_waits: dict[str, asyncio.Future[str]] = {}
 
     def items(self):
         yield from ()
@@ -227,8 +237,10 @@ class VoiceManager(Tray):
             task: "VoiceManager.TaskRequest | VoiceManager.ToolRequest",
             *,
             speak: Callable[[str], Awaitable[None]],
+            call_frontend_tool: Callable[[str, str], Awaitable[str]],
+            tools: "list[VoiceManager.ToolDef]",
         ) -> str:
-            """Fulfill one delegated work unit; ``speak`` streams interim spoken updates and the return value is the result."""
+            """Fulfill one delegated work unit; ``speak`` streams interim spoken updates, ``call_frontend_tool(name, arguments)`` runs a client-declared tool (``tools``) on the owning client, and the return value is the result."""
             ...
 
     # ─── Session lifecycle ──────────────────────────────────
@@ -239,7 +251,7 @@ class VoiceManager(Tray):
         applied: Callable[[], None],
     ) -> Any:
         self.clientId.value = caller.client_id
-        self._client_tools = {tool["name"] for tool in tools}
+        self._client_tools = tools
         try:
             provider = await self.handler(
                 VoiceManager.SessionContext(client_id=caller.client_id)
@@ -254,12 +266,18 @@ class VoiceManager(Tray):
         self._provider = provider
         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)
+    def client_departed(self) -> None:
+        if self._ended or self._grace is not None:
+            return
+        self._grace = self._spawn(self._departure_expired())
+
+    async def _departure_expired(self) -> None:
+        await asyncio.sleep(self.departure_grace)
+        self._grace = None
+        if self._host.has_subscriber(self.clientId.value):
+            return
         await self._background_end("connection-drop")
 
     async def _background_end(self, reason: str) -> None:
@@ -272,9 +290,9 @@ class VoiceManager(Tray):
         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()
+        grace, self._grace = self._grace, None
+        if grace is not None and grace is not asyncio.current_task():
+            grace.cancel()
         provider, self._provider = self._provider, None
         if provider is not None:
             try:
@@ -289,6 +307,11 @@ class VoiceManager(Tray):
         turns, self._turns = self._turns, []
         for turn in turns:
             self._host.drop_ephemeral_message(turn["id"])
+        waits, self._executor_waits = self._executor_waits, {}
+        for wait in waits.values():
+            if not wait.done():
+                wait.set_exception(RuntimeError("the voice session ended"))
+                wait.exception()
         self.status.value = "closed"
         self.delete()
 
@@ -387,7 +410,7 @@ class VoiceManager(Tray):
             self._tasks_run += 1
             self.activeTask.value = {"taskId": task_id, "text": text}
             try:
-                answer = await self._host.handle_voice_task(task, speak=self._speak)
+                answer = await self._delegate(task)
                 if not isinstance(answer, str) or answer == "":
                     raise TypeError(
                         f"handle_voice_task must return the result text, got {answer!r}"
@@ -403,39 +426,72 @@ class VoiceManager(Tray):
                 self.activeTask.value = None
             await self._append(answer, channel="speakable")
 
+    async def _delegate(
+        self, task: "VoiceManager.TaskRequest | VoiceManager.ToolRequest"
+    ) -> str:
+        return await self._host.handle_voice_task(
+            task,
+            speak=self._speak,
+            call_frontend_tool=self._call_frontend_tool,
+            tools=self._client_tools,
+        )
+
+    def _project_call(self, call_id: str, name: str, arguments: str) -> None:
+        self.toolCalls.value = [
+            *self.toolCalls.value,
+            {"callId": call_id, "name": name, "arguments": arguments},
+        ]
+
+    def _clear_call(self, call_id: str) -> None:
+        if self._ended:
+            return
+        self.toolCalls.value = [
+            call for call in self.toolCalls.value if call["callId"] != call_id
+        ]
+
     def tool_requested(self, request: "VoiceManager.ToolRequest") -> None:
         if self._ended or not self._claim(request.call_id):
             return
-        if request.name in self._client_tools:
-            self.toolCalls.value = [
-                *self.toolCalls.value,
-                {
-                    "callId": request.call_id,
-                    "name": request.name,
-                    "arguments": request.arguments,
-                },
-            ]
+        if any(tool["name"] == request.name for tool in self._client_tools):
+            self._project_call(request.call_id, request.name, request.arguments)
             return
         self._spawn(self._run_tool_call(request))
 
+    async def _call_frontend_tool(self, name: str, arguments: str) -> str:
+        if all(tool["name"] != name for tool in self._client_tools):
+            raise ValueError(f"{name!r} is not a client-declared frontend tool")
+        if self._ended:
+            raise RuntimeError("the voice session ended")
+        call_id = uuid4().hex
+        wait: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+        self._executor_waits[call_id] = wait
+        self._project_call(call_id, name, arguments)
+        try:
+            return await wait
+        finally:
+            self._executor_waits.pop(call_id, None)
+            self._clear_call(call_id)
+
     async def _answer_client_call(self, call_id: str, output: str) -> None:
-        pending = self.toolCalls.value
-        if not any(call["callId"] == call_id for call in pending):
+        if not any(call["callId"] == call_id for call in self.toolCalls.value):
             raise _reject(
                 "unknown-tool-call", f"no pending frontend tool call {call_id!r}"
             )
+        wait = self._executor_waits.get(call_id)
+        if wait is not None:
+            if not wait.done():
+                wait.set_result(output)
+            return
         provider = self._provider
         if provider is None:
             raise _reject("no-voice", "the voice session is not live")
         await provider.return_tool_result(call_id, output)
-        self.toolCalls.value = [
-            call for call in pending if call["callId"] != call_id
-        ]
+        self._clear_call(call_id)
 
     async def _run_tool_call(self, request: "VoiceManager.ToolRequest") -> None:
         self.activeTask.value = {"taskId": request.call_id, "text": request.name}
         try:
-            output = await self._host.handle_voice_task(request, speak=self._speak)
+            output = await self._delegate(request)
             if not isinstance(output, str):
                 raise TypeError(
                     f"handle_voice_task must return the result text, got {output!r}"
@@ -515,6 +571,11 @@ class VoiceManagerNamespace(TrayMapNamespace):
         session = self._session
         return session if session is not None and not session._ended else None
 
+    def client_departed(self, client_id: str) -> None:
+        session = self.live()
+        if session is not None and session.clientId.value == client_id:
+            session.client_departed()
+
     def _mount(self, tray: VoiceManager) -> None:
         if tray.storage._restored:
             return  # a crash's leftover row: the pump finishes its delete unmounted
@@ -533,8 +594,13 @@ class VoiceManagerNamespace(TrayMapNamespace):
         if not isinstance(offer, str) or offer == "":
             raise _reject("invalid-message", "offer must be a non-empty SDP string")
         tools = _validated_tools(params.get("tools"))
-        if self._starting or self.live() is not None:
+        if self._starting:
             raise _reject("voice-active", "a voice session is already live")
+        session = self.live()
+        if session is not None:
+            if self._api.has_subscriber(session.clientId.value):
+                raise _reject("voice-active", "a voice session is already live")
+            await session._end("connection-drop")
         self._starting = True
         try:
             seed = _capped_seed(await self._api.get_voice_seed())
@@ -630,6 +696,13 @@ async def end_voice(host: Any, *, ctx: Any) -> None:
     return await namespace.end(ctx=ctx)
 
 
+def voice_client_departed(host: Any, client_id: str) -> None:
+    """The Statewire ``client_departed`` hook body: routes to the host's declared voice manager."""
+    namespace = _voice_of(host)
+    if namespace is not None:
+        namespace.client_departed(client_id)
+
+
 async def temp_frontend_tool_result(host: Any, params: Any, *, ctx: Any) -> None:
     """The ``voice/temp-frontend-tool-result`` command body: routes to the host's declared voice manager."""
     namespace = _voice_of(host)

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/tests/test_voice.py

@@ -276,19 +276,23 @@ async def test_provider_closed_event_ends_and_commits():
         assert_rejected(await drv.command("voice/end"), "no-voice")
 
 
-async def test_connection_drop_ends_session(monkeypatch):
-    monkeypatch.setattr(VoiceManager, "connection_poll", 0.02)
+async def start_from_second_client(drv, stream, *, client_id="c2"):
+    await stream.next_event()
+    response = await post_frame(
+        drv._client,
+        {"cmd": [_statement("voice/start", {"offer": OFFER}, 1)]},
+        client_id=client_id,
+    )
+    assert response.status_code == 200, response.text
+    await drv.wait(lambda s: (voice_of(s) or {}).get("clientId") == client_id)
+
+
+async def test_connection_drop_ends_session_after_grace(monkeypatch):
+    monkeypatch.setattr(VoiceManager, "departure_grace", 0.05)
     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")
+            await start_from_second_client(drv, stream)
             events = bench.events()
             events.turn_started("t1", "user")
             events.turn_done("t1", "dropped mid-call")
@@ -299,6 +303,46 @@ async def test_connection_drop_ends_session(monkeypatch):
         ]
 
 
+async def test_reattach_within_grace_keeps_the_session(monkeypatch):
+    monkeypatch.setattr(VoiceManager, "departure_grace", 0.2)
+    bench = Bench()
+    async with voice_host(bench) as (drv, app):
+        async with stream_of(app, client_id="c2") as stream:
+            await start_from_second_client(drv, stream)
+        async with stream_of(app, client_id="c2") as stream:
+            await stream.next_event()
+            await asyncio.sleep(0.4)
+            await drv.wait(lambda s: (voice_of(s) or {}).get("status") == "live")
+            assert not bench.provider.closed
+
+
+async def test_start_over_a_detached_owner_replaces_the_session():
+    bench = Bench()
+    async with voice_host(bench) as (drv, app):
+        async with stream_of(app, client_id="c2") as stream:
+            await start_from_second_client(drv, stream)
+        orphaned = bench.provider
+        bench.provider = FakeVoiceProvider()
+        rsp = await drv.command("voice/start", {"offer": OFFER})
+        assert rsp["type"] == "accepted", rsp
+        assert orphaned.closed
+        await drv.wait(
+            lambda s: (voice_of(s) or {}).get("clientId") == drv.client_id
+            and (voice_of(s) or {}).get("status") == "live"
+        )
+
+
+async def test_start_over_an_attached_owner_still_rejects_voice_active():
+    bench = Bench()
+    async with voice_host(bench) as (drv, app):
+        async with stream_of(app, client_id="c2") as stream:
+            await start_from_second_client(drv, stream)
+            assert_rejected(
+                await drv.command("voice/start", {"offer": OFFER}), "voice-active"
+            )
+            assert not bench.provider.closed
+
+
 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):

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/tests/test_voice_frontend_tools.py

@@ -1,6 +1,9 @@
 """Frontend function tools contract: ``voice/start {tools}`` reaches the
-provider, matching calls project into ``state["voice"]["toolCalls"]``, and
-``voice/temp-frontend-tool-result`` answers them."""
+provider, matching calls project into ``state["voice"]["toolCalls"]``,
+``voice/temp-frontend-tool-result`` answers them, and the delegated-task
+handler's ``call_frontend_tool`` rides the same projection."""
+
+import asyncio
 
 from run_helpers import assert_rejected
 from voice_helpers import (
@@ -13,6 +16,13 @@ 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)
+
 TOOL = {
     "name": "get_local_time",
     "description": "Read the user's local date and time.",
@@ -93,6 +103,83 @@ async def test_unknown_call_id_rejects_unknown_tool_call():
         )
 
 
+async def test_executor_call_projects_and_the_result_resolves_the_await():
+    bench = Bench()
+    outputs: list[str] = []
+
+    async def handler(task, speak):
+        outputs.append(await bench.call_frontend_tool("get_local_time", "{}"))
+        return "wrapped it up"
+
+    bench.task_handler = handler
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        bench.events().task_requested("d1", "what time is it locally?")
+        await drv.wait(lambda s: (voice_of(s) or {}).get("toolCalls") != [])
+        [call] = drv.replica["voice"]["toolCalls"]
+        assert call["name"] == "get_local_time"
+        assert call["arguments"] == "{}"
+        assert bench.tool_defs == [TOOL]
+        rsp = await drv.command(
+            "voice/temp-frontend-tool-result",
+            {"call_id": call["callId"], "output": "12:30"},
+        )
+        assert rsp["type"] == "accepted", rsp
+        await until(
+            lambda: ("append_context", "wrapped it up", "speakable")
+            in bench.provider.calls
+        )
+        assert outputs == ["12:30"]
+        assert all(c[0] != "return_tool_result" for c in bench.provider.calls)
+        await drv.wait(lambda s: (voice_of(s) or {}).get("toolCalls") == [])
+
+
+async def test_executor_call_with_undeclared_tool_raises_in_the_handler():
+    bench = Bench()
+
+    async def handler(task, speak):
+        return await bench.call_frontend_tool("open_pod_bay_doors", "{}")
+
+    bench.task_handler = handler
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        bench.events().task_requested("d1", "open up")
+        await until(
+            lambda: any(
+                c[0] == "append_context" and c[2] == "commentary"
+                for c in bench.provider.calls
+            )
+        )
+        [(_, text, _channel)] = [
+            c for c in bench.provider.calls if c[0] == "append_context"
+        ]
+        assert "'open_pod_bay_doors' is not a client-declared frontend tool" in text
+        assert drv.replica["voice"]["toolCalls"] == []
+
+
+async def test_session_end_fails_a_pending_executor_call():
+    bench = Bench()
+    failures: list[Exception] = []
+
+    async def handler(task, speak):
+        try:
+            return await bench.call_frontend_tool("get_local_time", "{}")
+        except Exception as exc:
+            failures.append(exc)
+            raise
+
+    bench.task_handler = handler
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        bench.events().task_requested("d1", "what time is it?")
+        await drv.wait(lambda s: (voice_of(s) or {}).get("toolCalls") != [])
+        rsp = await drv.command("voice/end")
+        assert rsp["type"] == "accepted", rsp
+        await until(lambda: failures != [])
+        assert isinstance(failures[0], RuntimeError)
+        assert all(c[0] != "return_tool_result" for c in bench.provider.calls)
+
+
 async def test_tool_result_from_other_client_rejects_not_voice_owner():
     bench = Bench()
     async with voice_host(bench) as (drv, app):

{harness_sdk_python-0.30.1 → harness_sdk_python-0.31.1}/tests/voice_helpers.py

@@ -16,6 +16,7 @@ from harness_sdk import (
     end_voice,
     start_voice,
     temp_frontend_tool_result,
+    voice_client_departed,
     voice_manager,
 )
 
@@ -72,6 +73,8 @@ class Bench:
     contexts: list[VoiceManager.SessionContext] = field(default_factory=list)
     tasks: list[Any] = field(default_factory=list)
     task_handler: Any = None
+    call_frontend_tool: Any = None
+    tool_defs: list[Any] = field(default_factory=list)
 
     def events(self) -> VoiceManager.Events:
         assert self.provider.events is not None, "provider.start never ran"
@@ -116,8 +119,10 @@ def make_voice_host(bench: Bench, *, declare: bool = True):
             del self._ephemeral[message_id]
             self._project_messages()
 
-        async def handle_voice_task(self, task, *, speak):
+        async def handle_voice_task(self, task, *, speak, call_frontend_tool, tools):
             bench.tasks.append(task)
+            bench.call_frontend_tool = call_frontend_tool
+            bench.tool_defs = tools
             if bench.task_handler is not None:
                 return await bench.task_handler(task, speak)
             request_id = getattr(task, "task_id", None) or task.call_id
@@ -135,6 +140,9 @@ def make_voice_host(bench: Bench, *, declare: bool = True):
         async def voice_tool_result(self, params, *, ctx):
             return await temp_frontend_tool_result(self, params, ctx=ctx)
 
+        def client_departed(self, client_id):
+            voice_client_departed(self, client_id)
+
     if not declare:
         return Host