harness-sdk-python 0.29.2__py3-none-any.whl → 0.30.0__py3-none-any.whl

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/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
@@ -21,6 +26,15 @@ same id, a failed commit keeps its turns for the next flush; session end
 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),
 ``not-voice-owner`` (``voice/end`` from another client),
@@ -30,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
@@ -49,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}")
@@ -71,11 +110,13 @@ class VoiceManager(Tray):
 
     clientId = observable(None)
     status = observable("connecting")
+    toolCalls = observable([])
 
     state = observable(
         {
             "clientId": clientId,
             "status": status,
+            "toolCalls": toolCalls,
         }
     )
 
@@ -86,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 ()
@@ -96,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."""
@@ -119,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: ...
@@ -142,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:
@@ -258,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(
@@ -282,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."""
@@ -311,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(
@@ -343,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
@@ -350,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
@@ -419,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.2.dist-info → harness_sdk_python-0.30.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.29.2
+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.2.dist-info → harness_sdk_python-0.30.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-harness_sdk/__init__.py,sha256=N9gOUKqe0_eM7cIA9sfA_lH1FBw1MN8U-zerwGAPVHE,1094
+harness_sdk/__init__.py,sha256=EO0rTCg1NmWPNlnip81KjkvKYoc0dGLULKv2ton3tG8,1158
 harness_sdk/checkpoints.py,sha256=L02l1IyLDj2b-GD7_HGrck7uenALeI4kg8yJSzoNVmc,25999
 harness_sdk/deepagents.py,sha256=cMipZ9ndZ3zUR3-VqOMf5CiPVMmym74ytIeguQAjYZo,12280
 harness_sdk/fenced_postgres.py,sha256=hbbrMR1WaqrHTNgd4wFrXfRrzQFGnyim-c8nZXgwWp4,13235
 harness_sdk/linear_thread.py,sha256=laDRXKLFsMlyWS4snqNAM6t38wO26gevLWXRNivhHSM,1810
 harness_sdk/run_manager.py,sha256=CbY_4dpFeqGx3kJNI1ffsu3uIvzVc-Tc1UB6Nr9SiHY,77654
-harness_sdk/voice.py,sha256=oVmfxltjyV9ylATIpAszaM6MOS9TC3Haksgf6I7c4v8,15863
-harness_sdk_python-0.29.2.dist-info/METADATA,sha256=-4c6JdBIpkP6td3WlIcpnbUOX9ntoTM5dG6vcwoD55k,2200
-harness_sdk_python-0.29.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-harness_sdk_python-0.29.2.dist-info/RECORD,,
+harness_sdk/voice.py,sha256=ng2w22tk8aaC1h_x0K4ng7mbaTNXPQwCwFllErhkMOM,24616
+harness_sdk_python-0.30.0.dist-info/METADATA,sha256=JNDcDwcIICNMqvUvczSqIk1SDUjsWBpA1ROrs6L95HM,2200
+harness_sdk_python-0.30.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+harness_sdk_python-0.30.0.dist-info/RECORD,,