harness-sdk-python 0.30.0__tar.gz → 0.31.0__tar.gz

{harness_sdk_python-0.30.0 → harness_sdk_python-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.30.0
+Version: 0.31.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.30.0 → harness_sdk_python-0.31.0}/pyproject.toml

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

{harness_sdk_python-0.30.0 → harness_sdk_python-0.31.0}/src/harness_sdk/voice.py

@@ -10,7 +10,7 @@ and the turn commit both stay host-owned.
 ``voice/start {offer, tools?}`` seeds the provider from the thread
 transcript (at most 128 messages, tail taken), hands the client's frontend
 function tool definitions to the provider, and projects ``state["voice"] =
-{clientId, status, toolCalls}`` — the SDP answer rides only the command's
+{clientId, status, toolCalls, activeTask}`` — the SDP answer rides only the command's
 result payload ``{answer}``. A named call matching a client-declared tool
 projects into ``toolCalls`` as ``{callId, name, arguments}``; the owning
 client answers it with ``voice/temp-frontend-tool-result {call_id,
@@ -33,7 +33,12 @@ transcript handoff — the first task the conversation so far, follow-ups the
 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 model as commentary (task) or an error output (call). The running unit
+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), ``no-voice``
 (no voice manager declared, or ``voice/end`` with no session),
@@ -111,12 +116,14 @@ class VoiceManager(Tray):
     clientId = observable(None)
     status = observable("connecting")
     toolCalls = observable([])
+    activeTask = observable(None)
 
     state = observable(
         {
             "clientId": clientId,
             "status": status,
             "toolCalls": toolCalls,
+            "activeTask": activeTask,
         }
     )
 
@@ -131,7 +138,8 @@ class VoiceManager(Tray):
         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 ()
@@ -224,8 +232,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 ──────────────────────────────────
@@ -236,7 +246,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)
@@ -286,6 +296,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()
 
@@ -382,8 +397,9 @@ class VoiceManager(Tray):
                 follow_up=self._tasks_run > 0,
             )
             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}"
@@ -395,40 +411,76 @@ class VoiceManager(Tray):
                     channel="commentary",
                 )
                 return
+            finally:
+                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}"
@@ -438,6 +490,8 @@ class VoiceManager(Tray):
                 "voice session %r tool call %r failed", self.id, request.call_id
             )
             output = json.dumps({"error": f"{type(exc).__name__}: {exc}"})
+        finally:
+            self.activeTask.value = None
         provider = self._provider
         if provider is not None:
             await provider.return_tool_result(request.call_id, output)

{harness_sdk_python-0.30.0 → harness_sdk_python-0.31.0}/tests/test_voice.py

@@ -39,7 +39,12 @@ async def test_start_seeds_provider_and_projects_session():
         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", "toolCalls": []}
+        assert voice == {
+            "clientId": drv.client_id,
+            "status": "live",
+            "toolCalls": [],
+            "activeTask": None,
+        }
         assert bench.contexts[0].client_id == drv.client_id
 
 

{harness_sdk_python-0.30.0 → harness_sdk_python-0.31.0}/tests/test_voice_delegation.py

@@ -1,12 +1,12 @@
 """Voice delegation contract: work units route to ``Host.handle_voice_task``,
 handoffs drain the transcript incrementally, results flow back as speakable
-context appends, named calls answer via ``return_tool_result``, and repeated
-request ids run once."""
+context appends, named calls answer via ``return_tool_result``, repeated
+request ids run once, and the running unit projects as ``activeTask``."""
 
 import asyncio
 import json
 
-from voice_helpers import OFFER, Bench, voice_host
+from voice_helpers import OFFER, Bench, voice_host, voice_of
 
 from harness_sdk import VoiceManager
 
@@ -142,6 +142,66 @@ async def test_task_failure_surfaces_as_commentary():
         ]
 
 
+async def test_active_task_projects_while_a_task_runs_and_clears_after():
+    bench = Bench()
+    gate = asyncio.Event()
+
+    async def handler(task, speak):
+        await gate.wait()
+        return "all done"
+
+    bench.task_handler = handler
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        bench.events().task_requested("d1", "check the weather")
+        await drv.wait(
+            lambda s: (voice_of(s) or {}).get("activeTask")
+            == {"taskId": "d1", "text": "check the weather"}
+        )
+        gate.set()
+        await drv.wait(lambda s: (voice_of(s) or {}).get("activeTask") is None)
+
+
+async def test_active_task_projects_a_named_call_and_clears_after():
+    bench = Bench()
+    gate = asyncio.Event()
+
+    async def handler(task, speak):
+        await gate.wait()
+        return "{}"
+
+    bench.task_handler = handler
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        bench.events().tool_requested(
+            VoiceManager.ToolRequest(call_id="c1", name="get_time", arguments="{}")
+        )
+        await drv.wait(
+            lambda s: (voice_of(s) or {}).get("activeTask")
+            == {"taskId": "c1", "text": "get_time"}
+        )
+        gate.set()
+        await drv.wait(lambda s: (voice_of(s) or {}).get("activeTask") is None)
+
+
+async def test_active_task_clears_when_the_handler_fails():
+    bench = Bench()
+    gate = asyncio.Event()
+
+    async def handler(task, speak):
+        await gate.wait()
+        raise RuntimeError("boom")
+
+    bench.task_handler = handler
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        bench.events().task_requested("d1", "dig in")
+        await drv.wait(lambda s: (voice_of(s) or {}).get("activeTask") is not None)
+        gate.set()
+        await drv.wait(lambda s: (voice_of(s) or {}).get("activeTask") is None)
+        assert (voice_of(drv.replica) or {}).get("status") == "live"
+
+
 async def test_tool_failure_returns_an_error_output():
     bench = Bench()
 

{harness_sdk_python-0.30.0 → harness_sdk_python-0.31.0}/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.0 → harness_sdk_python-0.31.0}/tests/voice_helpers.py

@@ -72,6 +72,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 +118,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