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

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

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

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

{harness_sdk_python-0.29.1 → harness_sdk_python-0.30.0}/src/harness_sdk/__init__.py

@@ -20,6 +20,7 @@ from .voice import (
     VoiceProvider,
     end_voice,
     start_voice,
+    temp_frontend_tool_result,
     voice_manager,
 )
 
@@ -45,5 +46,6 @@ __all__ = [
     "linear_thread",
     "run_manager",
     "start_voice",
+    "temp_frontend_tool_result",
     "voice_manager",
 ]

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

@@ -7,10 +7,15 @@ 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}`` — the SDP answer rides only the command's result payload
-``{answer}``. The session is bound to the issuing client's connection: ``voice/end`` from the owner, a
+``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
+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,
+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
 events render live in ``state["messages"]`` through
 ``Host.upsert_ephemeral_message`` (message id = turn id), tagged
@@ -18,7 +23,17 @@ events render live in ``state["messages"]`` through
 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.
+flushes the remaining done turns, then commits in-progress turns with
+their partial text; in-progress turns with no text yet are dropped.
+
+Delegated work: provider ``task_requested`` (free-text unit) and
+``tool_requested`` (named call) events route to ``Host.handle_voice_task``,
+deduped by id. Tasks run one at a time and each carries an incremental
+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).
 
 Rejections: ``voice-active`` (a session is already live), ``no-voice``
 (no voice manager declared, or ``voice/end`` with no session),
@@ -29,9 +44,10 @@ Rejections: ``voice-active`` (a session is already live), ``no-voice``
 import asyncio
 import functools
 import inspect
+import json
 import logging
 from dataclasses import dataclass
-from typing import Any, Callable, Literal, Protocol, TypedDict
+from typing import Any, Awaitable, Callable, Literal, Protocol, TypedDict
 from uuid import uuid4
 
 from pinned.trays import Tray, TrayDescriptor, TrayMapNamespace
@@ -48,6 +64,30 @@ def _reject(reason: str, message: str) -> StatewireReject:
     return StatewireReject(message, payload={"reason": reason})
 
 
+def _validated_tools(tools: Any) -> "list[VoiceManager.ToolDef]":
+    if tools is None:
+        return []
+    if not isinstance(tools, list):
+        raise _reject("invalid-message", "tools must be a list")
+    names: set[str] = set()
+    for tool in tools:
+        if (
+            not isinstance(tool, dict)
+            or not isinstance(tool.get("name"), str)
+            or tool["name"] == ""
+            or not isinstance(tool.get("description"), str)
+            or not isinstance(tool.get("parameters"), dict)
+        ):
+            raise _reject(
+                "invalid-message",
+                f"tools entries must be {{name, description, parameters}}, got {tool!r}",
+            )
+        if tool["name"] in names:
+            raise _reject("invalid-message", f"duplicate tool name {tool['name']!r}")
+        names.add(tool["name"])
+    return tools
+
+
 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}")
@@ -70,11 +110,13 @@ class VoiceManager(Tray):
 
     clientId = observable(None)
     status = observable("connecting")
+    toolCalls = observable([])
 
     state = observable(
         {
             "clientId": clientId,
             "status": status,
+            "toolCalls": toolCalls,
         }
     )
 
@@ -85,6 +127,11 @@ class VoiceManager(Tray):
         self._flushing = asyncio.Lock()
         self._ended = False
         self._watcher: "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()
 
     def items(self):
         yield from ()
@@ -95,12 +142,41 @@ class VoiceManager(Tray):
         role: Literal["user", "assistant", "system"]
         text: str
 
+    class ToolDef(TypedDict):
+        """One frontend function tool the client declares at ``voice/start``."""
+
+        name: str
+        description: str
+        parameters: dict[str, Any]
+
     @dataclass(frozen=True)
     class ToolRequest:
         call_id: str
         name: str
         arguments: str
 
+    @dataclass(frozen=True)
+    class TaskRequest:
+        """One delegated free-text work unit plus its transcript delta."""
+
+        task_id: str
+        text: str
+        transcript: str
+        follow_up: bool
+
+        def handoff(self) -> str:
+            """Render the task and its transcript delta as one delegate-facing prompt."""
+            window = (
+                "the voice conversation since the previous delegated task"
+                if self.follow_up
+                else "the voice conversation so far"
+            )
+            transcript = self.transcript or "(No new conversation was captured.)"
+            return (
+                f"This is the transcript of {window}:\n\n{transcript}\n\n"
+                f"The voice model delegated this task:\n{self.text}"
+            )
+
     @dataclass(frozen=True)
     class SessionContext:
         """The provider factory's per-session context."""
@@ -118,6 +194,8 @@ class VoiceManager(Tray):
 
         def tool_requested(self, request: "VoiceManager.ToolRequest") -> None: ...
 
+        def task_requested(self, task_id: str, text: str) -> None: ...
+
         def rollover_approaching(self, rollover_id: str, deadline: float) -> None: ...
 
         def closed(self, reason: str) -> None: ...
@@ -141,18 +219,29 @@ class VoiceManager(Tray):
             """Remove an in-flight turn from the ``state["messages"]`` projection."""
             ...
 
+        async def handle_voice_task(
+            self,
+            task: "VoiceManager.TaskRequest | VoiceManager.ToolRequest",
+            *,
+            speak: Callable[[str], Awaitable[None]],
+        ) -> str:
+            """Fulfill one delegated work unit; ``speak`` streams interim spoken updates and the return value is the result."""
+            ...
+
     # ─── Session lifecycle ──────────────────────────────────
 
     async def _begin(
-        self, offer: str, seed: "list[VoiceManager.SeedMessage]", caller: Any,
+        self, offer: str, seed: "list[VoiceManager.SeedMessage]",
+        tools: "list[VoiceManager.ToolDef]", caller: Any,
         applied: Callable[[], None],
     ) -> Any:
         self.clientId.value = caller.client_id
+        self._client_tools = {tool["name"] for tool in tools}
         try:
             provider = await self.handler(
                 VoiceManager.SessionContext(client_id=caller.client_id)
             )
-            answer = await provider.start(offer, seed=seed, events=self)
+            answer = await provider.start(offer, seed=seed, tools=tools, 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:
@@ -189,6 +278,10 @@ class VoiceManager(Tray):
                 await provider.close()
             except Exception:
                 logger.exception("voice provider close failed for session %r", self.id)
+        self._turns.sort(key=lambda turn: not turn["done"])
+        for turn in self._turns:
+            if turn["text"]:
+                turn["done"] = True
         await self._flush()
         turns, self._turns = self._turns, []
         for turn in turns:
@@ -253,11 +346,101 @@ class VoiceManager(Tray):
         turn = self._turn(turn_id)
         turn["text"] = text
         turn["done"] = True
+        self._handoff_pending.append({"role": turn["role"], "text": text})
         self._render(turn)
         self._spawn(self._flush())
 
+    def _claim(self, request_id: str) -> bool:
+        if request_id in self._seen_requests:
+            return False
+        self._seen_requests.add(request_id)
+        return True
+
+    async def _append(
+        self, text: str, *, channel: Literal["speakable", "commentary"]
+    ) -> None:
+        provider = self._provider
+        if provider is not None:
+            await provider.append_context(text, channel=channel)
+
+    async def _speak(self, text: str) -> None:
+        await self._append(text, channel="speakable")
+
+    def task_requested(self, task_id: str, text: str) -> None:
+        if self._ended or not self._claim(task_id):
+            return
+        self._spawn(self._run_delegated_task(task_id, text))
+
+    async def _run_delegated_task(self, task_id: str, text: str) -> None:
+        # the lock orders transcript drains and keeps one delegation in flight
+        async with self._delegating:
+            pending, self._handoff_pending = self._handoff_pending, []
+            task = VoiceManager.TaskRequest(
+                task_id=task_id,
+                text=text,
+                transcript="\n".join(f"[{t['role']}] {t['text']}" for t in pending),
+                follow_up=self._tasks_run > 0,
+            )
+            self._tasks_run += 1
+            try:
+                answer = await self._host.handle_voice_task(task, speak=self._speak)
+                if not isinstance(answer, str) or answer == "":
+                    raise TypeError(
+                        f"handle_voice_task must return the result text, got {answer!r}"
+                    )
+            except Exception as exc:
+                logger.exception("voice session %r task %r failed", self.id, task_id)
+                await self._append(
+                    f"The delegated work could not be completed: {exc}",
+                    channel="commentary",
+                )
+                return
+            await self._append(answer, channel="speakable")
+
     def tool_requested(self, request: "VoiceManager.ToolRequest") -> None:
-        logger.info("voice session %r tool request ignored: %r", self.id, request)
+        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,
+                },
+            ]
+            return
+        self._spawn(self._run_tool_call(request))
+
+    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):
+            raise _reject(
+                "unknown-tool-call", f"no pending frontend tool call {call_id!r}"
+            )
+        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
+        ]
+
+    async def _run_tool_call(self, request: "VoiceManager.ToolRequest") -> None:
+        try:
+            output = await self._host.handle_voice_task(request, speak=self._speak)
+            if not isinstance(output, str):
+                raise TypeError(
+                    f"handle_voice_task must return the result text, got {output!r}"
+                )
+        except Exception as exc:
+            logger.exception(
+                "voice session %r tool call %r failed", self.id, request.call_id
+            )
+            output = json.dumps({"error": f"{type(exc).__name__}: {exc}"})
+        provider = self._provider
+        if provider is not None:
+            await provider.return_tool_result(request.call_id, output)
 
     def rollover_approaching(self, rollover_id: str, deadline: float) -> None:
         logger.info(
@@ -277,6 +460,7 @@ class VoiceProvider(Protocol):
     async def start(
         self, offer: str, *,
         seed: "list[VoiceManager.SeedMessage]",
+        tools: "list[VoiceManager.ToolDef]",
         events: "VoiceManager.Events",
     ) -> str:
         """Open the session from an SDP offer and return the SDP answer; events flow into the sink."""
@@ -306,6 +490,7 @@ class VoiceManagerNamespace(TrayMapNamespace):
             "commit_voice_turns",
             "upsert_ephemeral_message",
             "drop_ephemeral_message",
+            "handle_voice_task",
         ):
             if not callable(getattr(api, name, None)):
                 raise TypeError(
@@ -338,6 +523,7 @@ class VoiceManagerNamespace(TrayMapNamespace):
         offer = params.get("offer")
         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:
             raise _reject("voice-active", "a voice session is already live")
         self._starting = True
@@ -345,19 +531,38 @@ class VoiceManagerNamespace(TrayMapNamespace):
             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)
+            return await tray._begin(offer, seed, tools, ctx.caller, ctx.applied)
         finally:
             self._starting = False
 
-    async def end(self, *, ctx: Any) -> None:
+    def _owned_session(self, ctx: Any, command: str) -> VoiceManager:
         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")
+            raise _reject(
+                "not-voice-owner", f"{command} must come from the session owner"
+            )
+        return session
+
+    async def end(self, *, ctx: Any) -> None:
+        session = self._owned_session(ctx, "voice/end")
         await session._end("client")
         ctx.applied()
 
+    async def temp_frontend_tool_result(self, params: Any, *, ctx: Any) -> None:
+        session = self._owned_session(ctx, "voice/temp-frontend-tool-result")
+        if not isinstance(params, dict):
+            raise _reject("invalid-message", "params must be an object")
+        call_id = params.get("call_id")
+        output = params.get("output")
+        if not isinstance(call_id, str) or call_id == "" or not isinstance(output, str):
+            raise _reject(
+                "invalid-message", "call_id and output must be non-empty strings"
+            )
+        await session._answer_client_call(call_id, output)
+        ctx.applied()
+
 
 class VoiceManagerDescriptor(TrayDescriptor):
     namespace_cls = VoiceManagerNamespace
@@ -414,3 +619,11 @@ async def end_voice(host: Any, *, ctx: Any) -> None:
     if namespace is None:
         raise _reject("no-voice", "this host declares no voice manager")
     return await namespace.end(ctx=ctx)
+
+
+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)
+    if namespace is None:
+        raise _reject("no-voice", "this host declares no voice manager")
+    return await namespace.temp_frontend_tool_result(params, ctx=ctx)

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

@@ -36,10 +36,10 @@ async def test_start_seeds_provider_and_projects_session():
         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)]
+        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"}
+        assert voice == {"clientId": drv.client_id, "status": "live", "toolCalls": []}
         assert bench.contexts[0].client_id == drv.client_id
 
 
@@ -186,7 +186,7 @@ async def test_commit_failure_retries_in_order_with_the_next_turn():
         ]
 
 
-async def test_end_drops_in_progress_turns():
+async def test_end_commits_in_progress_turns_with_partial_text():
     bench = Bench()
     async with voice_host(bench) as (drv, _app):
         await drv.command("voice/start", {"offer": OFFER})
@@ -199,15 +199,41 @@ async def test_end_drops_in_progress_turns():
         rsp = await drv.command("voice/end")
         assert rsp["type"] == "accepted", rsp
         assert bench.provider.closed
-        assert bench.commits == [[{"id": "t1", "role": "user", "text": "question"}]]
+        assert bench.commits == [
+            [{"id": "t1", "role": "user", "text": "question"}],
+            [{"id": "t2", "role": "assistant", "text": "half an ans"}],
+        ]
+        # the durable entries replaced the ephemeral ones under the same ids
         await drv.wait(
             lambda s: voice_of(s) is None
             and messages_of(s)
-            == [{"id": "t1", "type": "human", "content": "question"}]
+            == [
+                {"id": "t1", "type": "human", "content": "question"},
+                {"id": "t2", "type": "ai", "content": "half an ans"},
+            ]
         )
 
 
-async def test_end_with_no_done_turns_commits_nothing():
+async def test_end_commits_partial_turns_after_kept_done_turns():
+    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_delta("t2", "half an ans")
+        await drv.command("voice/end")
+        assert bench.commits == [
+            [
+                {"id": "t1", "role": "user", "text": "question"},
+                {"id": "t2", "role": "assistant", "text": "half an ans"},
+            ]
+        ]
+
+
+async def test_end_drops_started_turns_with_no_text():
     bench = Bench()
     async with voice_host(bench) as (drv, _app):
         await drv.command("voice/start", {"offer": OFFER})
@@ -234,9 +260,14 @@ async def test_provider_closed_event_ends_and_commits():
         events = bench.events()
         events.turn_started("t1", "assistant")
         events.turn_done("t1", "goodbye")
+        events.turn_started("t2", "user")
+        events.turn_delta("t2", "wai")
         events.closed("server")
         await drv.wait(lambda s: voice_of(s) is None)
-        assert bench.commits == [[{"id": "t1", "role": "assistant", "text": "goodbye"}]]
+        assert bench.commits == [
+            [{"id": "t1", "role": "assistant", "text": "goodbye"}],
+            [{"id": "t2", "role": "user", "text": "wai"}],
+        ]
         assert_rejected(await drv.command("voice/end"), "no-voice")
 
 
@@ -267,7 +298,7 @@ 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]
+        _, _, seed, _tools = bench.provider.calls[0]
         assert len(seed) == 128
         assert seed == bench.transcript[-128:]
 

harness_sdk_python-0.30.0/tests/test_voice_delegation.py

@@ -0,0 +1,164 @@
+"""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."""
+
+import asyncio
+import json
+
+from voice_helpers import OFFER, Bench, voice_host
+
+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 appends(bench: Bench):
+    return [call for call in bench.provider.calls if call[0] == "append_context"]
+
+
+async def test_task_routes_to_handler_and_result_appends_speakable():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        bench.events().task_requested("d1", "check the weather")
+        await until(
+            lambda: ("append_context", "done:d1", "speakable") in bench.provider.calls
+        )
+        assert bench.tasks == [
+            VoiceManager.TaskRequest(
+                task_id="d1", text="check the weather", transcript="", follow_up=False
+            )
+        ]
+
+
+async def test_handoff_carries_first_full_then_delta_transcript():
+    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")
+        events.turn_started("t2", "assistant")
+        events.turn_done("t2", "hi!")
+        events.task_requested("d1", "first task")
+        await until(lambda: len(bench.tasks) == 1)
+        first = bench.tasks[0]
+        assert first.transcript == "[user] hello\n[assistant] hi!"
+        assert first.follow_up is False
+        assert "the voice conversation so far" in first.handoff()
+        assert first.handoff().endswith(
+            "The voice model delegated this task:\nfirst task"
+        )
+        events.turn_started("t3", "user")
+        events.turn_done("t3", "and now?")
+        events.task_requested("d2", "second task")
+        await until(lambda: len(bench.tasks) == 2)
+        second = bench.tasks[1]
+        assert second.transcript == "[user] and now?"
+        assert second.follow_up is True
+        assert "since the previous delegated task" in second.handoff()
+
+
+async def test_empty_handoff_renders_a_placeholder():
+    task = VoiceManager.TaskRequest(
+        task_id="d1", text="go", transcript="", follow_up=False
+    )
+    assert "(No new conversation was captured.)" in task.handoff()
+
+
+async def test_speak_streams_interim_updates_before_the_result():
+    bench = Bench()
+
+    async def handler(task, speak):
+        await speak("working on it")
+        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", "dig in")
+        await until(
+            lambda: ("append_context", "all done", "speakable") in bench.provider.calls
+        )
+        assert appends(bench) == [
+            ("append_context", "working on it", "speakable"),
+            ("append_context", "all done", "speakable"),
+        ]
+
+
+async def test_named_call_answers_via_return_tool_result():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        request = VoiceManager.ToolRequest(call_id="c1", name="get_time", arguments="{}")
+        bench.events().tool_requested(request)
+        await until(
+            lambda: ("return_tool_result", "c1", "done:c1") in bench.provider.calls
+        )
+        assert bench.tasks == [request]
+        assert appends(bench) == []
+
+
+async def test_repeated_request_ids_run_once():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER})
+        events = bench.events()
+        events.task_requested("d1", "one")
+        events.task_requested("d1", "one")
+        request = VoiceManager.ToolRequest(call_id="c1", name="get_time", arguments="{}")
+        events.tool_requested(request)
+        events.tool_requested(request)
+        await until(
+            lambda: ("append_context", "done:d1", "speakable") in bench.provider.calls
+            and ("return_tool_result", "c1", "done:c1") in bench.provider.calls
+        )
+        assert len(bench.tasks) == 2
+
+
+async def test_task_failure_surfaces_as_commentary():
+    bench = Bench()
+
+    async def handler(task, speak):
+        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 until(lambda: appends(bench) != [])
+        assert appends(bench) == [
+            (
+                "append_context",
+                "The delegated work could not be completed: boom",
+                "commentary",
+            )
+        ]
+
+
+async def test_tool_failure_returns_an_error_output():
+    bench = Bench()
+
+    async def handler(task, speak):
+        raise RuntimeError("boom")
+
+    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 until(
+            lambda: any(c[0] == "return_tool_result" for c in bench.provider.calls)
+        )
+        [(_, call_id, output)] = [
+            c for c in bench.provider.calls if c[0] == "return_tool_result"
+        ]
+        assert call_id == "c1"
+        assert json.loads(output) == {"error": "RuntimeError: boom"}

harness_sdk_python-0.30.0/tests/test_voice_frontend_tools.py

@@ -0,0 +1,109 @@
+"""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."""
+
+from run_helpers import assert_rejected
+from voice_helpers import (
+    OFFER,
+    Bench,
+    side_command,
+    voice_host,
+    voice_of,
+)
+
+from harness_sdk import VoiceManager
+
+TOOL = {
+    "name": "get_local_time",
+    "description": "Read the user's local date and time.",
+    "parameters": {"type": "object", "properties": {}},
+}
+
+
+def call_of(events, call_id: str = "call-1") -> None:
+    events.tool_requested(
+        VoiceManager.ToolRequest(
+            call_id=call_id, name="get_local_time", arguments="{}"
+        )
+    )
+
+
+async def test_start_passes_tools_to_the_provider():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        rsp = await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        assert rsp["type"] == "accepted", rsp
+        assert bench.provider.calls[0] == ("start", OFFER, [], [TOOL])
+
+
+async def test_malformed_tools_reject_invalid_message():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        for tools in (
+            "not-a-list",
+            [{"name": "", "description": "", "parameters": {}}],
+            [{"name": "a", "description": "d"}],
+            [TOOL, TOOL],
+        ):
+            assert_rejected(
+                await drv.command("voice/start", {"offer": OFFER, "tools": tools}),
+                "invalid-message",
+            )
+        assert bench.provider.calls == []
+
+
+async def test_client_tool_call_projects_into_state():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        call_of(bench.events())
+        await drv.wait(
+            lambda s: (voice_of(s) or {}).get("toolCalls")
+            == [{"callId": "call-1", "name": "get_local_time", "arguments": "{}"}]
+        )
+        # the call surfaced to the client instead of the host handler
+        assert bench.tasks == []
+
+
+async def test_tool_result_forwards_and_clears_the_pending_call():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        call_of(bench.events())
+        await drv.wait(lambda s: (voice_of(s) or {}).get("toolCalls") != [])
+        rsp = await drv.command(
+            "voice/temp-frontend-tool-result",
+            {"call_id": "call-1", "output": "12:30"},
+        )
+        assert rsp["type"] == "accepted", rsp
+        assert ("return_tool_result", "call-1", "12:30") in bench.provider.calls
+        await drv.wait(lambda s: (voice_of(s) or {}).get("toolCalls") == [])
+
+
+async def test_unknown_call_id_rejects_unknown_tool_call():
+    bench = Bench()
+    async with voice_host(bench) as (drv, _app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        assert_rejected(
+            await drv.command(
+                "voice/temp-frontend-tool-result",
+                {"call_id": "call-9", "output": "x"},
+            ),
+            "unknown-tool-call",
+        )
+
+
+async def test_tool_result_from_other_client_rejects_not_voice_owner():
+    bench = Bench()
+    async with voice_host(bench) as (drv, app):
+        await drv.command("voice/start", {"offer": OFFER, "tools": [TOOL]})
+        call_of(bench.events())
+        await drv.wait(lambda s: (voice_of(s) or {}).get("toolCalls") != [])
+        rsp = await side_command(
+            app,
+            drv._client,
+            "voice/temp-frontend-tool-result",
+            {"call_id": "call-1", "output": "x"},
+        )
+        assert_rejected(rsp, "not-voice-owner")
+        assert ("return_tool_result", "call-1", "x") not in bench.provider.calls

{harness_sdk_python-0.29.1 → harness_sdk_python-0.30.0}/tests/voice_helpers.py

@@ -11,7 +11,13 @@ 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
+from harness_sdk import (
+    VoiceManager,
+    end_voice,
+    start_voice,
+    temp_frontend_tool_result,
+    voice_manager,
+)
 
 OFFER = "v=0 fake-offer"
 ANSWER = "v=0 fake-answer"
@@ -27,8 +33,8 @@ class FakeVoiceProvider:
         self.events: VoiceManager.Events | None = None
         self.closed = False
 
-    async def start(self, offer, *, seed, events):
-        self.calls.append(("start", offer, list(seed)))
+    async def start(self, offer, *, seed, tools, events):
+        self.calls.append(("start", offer, list(seed), list(tools)))
         if self.fail is not None:
             raise self.fail
         self.events = events
@@ -64,6 +70,8 @@ class Bench:
     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)
+    tasks: list[Any] = field(default_factory=list)
+    task_handler: Any = None
 
     def events(self) -> VoiceManager.Events:
         assert self.provider.events is not None, "provider.start never ran"
@@ -108,6 +116,13 @@ 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):
+            bench.tasks.append(task)
+            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
+            return f"done:{request_id}"
+
         @command("voice/start")
         async def voice_start(self, params, *, ctx):
             return await start_voice(self, params, ctx=ctx)
@@ -116,6 +131,10 @@ def make_voice_host(bench: Bench, *, declare: bool = True):
         async def voice_end(self, params=None, *, ctx):
             return await end_voice(self, ctx=ctx)
 
+        @command("voice/temp-frontend-tool-result")
+        async def voice_tool_result(self, params, *, ctx):
+            return await temp_frontend_tool_result(self, params, ctx=ctx)
+
     if not declare:
         return Host