harness-sdk-python 0.25.2__py3-none-any.whl → 0.27.0__py3-none-any.whl

harness_sdk/__init__.py

@@ -11,23 +11,39 @@ from .checkpoints import (
     langgraph_snapshot,
     langgraph_switch_values,
 )
+from .deepagents import DeepagentsMessages
 from .linear_thread import linear_thread
 from .run_manager import RunManager, RunManagerDescriptor, run_manager
+from .voice import (
+    VoiceManager,
+    VoiceManagerDescriptor,
+    VoiceProvider,
+    end_voice,
+    start_voice,
+    voice_manager,
+)
 
 __all__ = [
     "CheckpointIndex",
     "CheckpointStore",
     "CheckpointThread",
+    "DeepagentsMessages",
     "MemoryCheckpointIndex",
     "Plan",
     "PostgresCheckpointIndex",
     "RunManager",
     "RunManagerDescriptor",
     "Snapshot",
+    "VoiceManager",
+    "VoiceManagerDescriptor",
+    "VoiceProvider",
     "checkpoint_thread",
+    "end_voice",
     "langgraph_checkpoints",
     "langgraph_snapshot",
     "langgraph_switch_values",
     "linear_thread",
     "run_manager",
+    "start_voice",
+    "voice_manager",
 ]

harness_sdk/deepagents.py

@@ -0,0 +1,260 @@
+"""DeepagentsMessages: the ``messages`` slice of a Statewire host, projected
+from a langgraph checkpointer in the deepagents dialect. The checkpointer is
+the source of truth and the wire state is its projection, restamped with
+``branch: {id, siblings}`` metadata after every ingest. A rewind restores the
+projection from the target message's anchor checkpoint; a branch switch clones
+the target branch's tip as the checkpointer's latest checkpoint, so resumption
+and reboot both land on the switched world.
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from statepatch import plain
+
+from .checkpoints import (
+    CheckpointIndex,
+    CheckpointStore,
+    Snapshot,
+    _values_snapshot,
+    checkpoint_thread,
+    langgraph_snapshot,
+)
+
+
+def _role(message: dict[str, Any]) -> str:
+    return "user" if message["type"] == "human" else "assistant"
+
+
+def _user_text(message: dict[str, Any]) -> str:
+    return "\n\n".join(
+        part["text"] for part in message["parts"] if part["type"] == "text"
+    )
+
+
+def _checkpointer_store(
+    checkpointer: Any, thread_id: str, checkpoint_ns: str
+) -> CheckpointStore:
+    class _Store:
+        async def get(self, checkpoint_id: str | None) -> Snapshot | None:
+            configurable: dict[str, Any] = {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+            }
+            if checkpoint_id is not None:
+                configurable["checkpoint_id"] = checkpoint_id
+            saved = await checkpointer.aget_tuple({"configurable": configurable})
+            if saved is None:
+                return None
+            return _values_snapshot(
+                saved.checkpoint["id"],
+                saved.checkpoint["channel_values"],
+                "messages",
+                "lineage",
+            )
+
+    return _Store()
+
+
+class DeepagentsMessages:
+    """A host's ``state["messages"]`` over a langgraph checkpointer: boot, turn streaming, rewind, and branch switching for the deepagents dialect."""
+
+    def __init__(self, checkpointer: Any) -> None:
+        if not hasattr(checkpointer, "aget_tuple") or not hasattr(checkpointer, "aput"):
+            raise TypeError(
+                f"checkpointer must be a langgraph checkpoint saver, got {checkpointer!r}"
+            )
+        self._checkpointer = checkpointer
+        self._captured: dict[str, Any] | None = None
+
+    async def boot(
+        self, state: Any, *, index: CheckpointIndex, thread_id: str
+    ) -> None:
+        """Adopt ``state["messages"]`` and load the thread's history into it with branch stamps."""
+        self._state = state
+        self._thread_id = thread_id
+        self._store = _checkpointer_store(self._checkpointer, thread_id, "")
+        self._thread = await checkpoint_thread(
+            store=self._store, index=index, thread_id=thread_id, role=_role
+        )
+        if self._thread.transcript:
+            # the graph carries no lineage channel: re-derive the world path from the tail row
+            row = await index.get_message(
+                thread_id, "", self._thread.transcript[-1]["id"]
+            )
+            if row is not None and row["branch_id"] != 0:
+                await self._thread.switch_state(row["branch_id"])
+        self._restamp()
+
+    async def get_message_meta(self, message_id: str | None) -> dict[str, Any] | None:
+        """The thread projection's message meta, for RunManager."""
+        return await self._thread.get_message_meta(message_id)
+
+    async def get_message_child_id(self, parent_id: str) -> str | None:
+        """The thread projection's child id, for RunManager."""
+        return await self._thread.get_message_child_id(parent_id)
+
+    def config(self) -> dict[str, Any]:
+        """The langgraph config addressing this thread."""
+        return {"configurable": {"thread_id": self._thread_id}}
+
+    async def plan_turn(
+        self, ctx: Any
+    ) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+        """The dispatch's langgraph (payload, config): plans the resumption, restores a rewind's window, appends the batch to the wire state, and confirms it applied."""
+        config = self.config()
+        if ctx.resume:
+            return None, config
+        plan = await self._thread.plan_run(ctx)
+        if ctx.has_rollback:
+            base = (
+                (await self._snapshot(plan.checkpoint_id)).messages
+                if plan.checkpoint_id is not None
+                else []
+            )
+            self._replace([*base, *plan.replay])
+        turn: list[Any] = [*plan.replay]
+        for message in ctx.messages:
+            turn.append(self._append_user(message))
+        ctx.applied()
+        if plan.fork:
+            if plan.checkpoint_id is not None:
+                config["configurable"]["checkpoint_id"] = plan.checkpoint_id
+            else:
+                from langchain_core.messages import RemoveMessage
+                from langgraph.graph.message import REMOVE_ALL_MESSAGES
+
+                turn = [RemoveMessage(id=REMOVE_ALL_MESSAGES), *turn]
+        return ({"messages": turn} if turn else None), config
+
+    def append_event(self, namespace: tuple, mode: str, event: Any) -> None:
+        """Fold one ``astream`` event into the wire state; the root checkpoint stream is captured for the turn's ingest."""
+        if mode == "checkpoints":
+            if namespace == ():
+                self._captured = event
+            return
+        from statewire.langgraph import append_langgraph_event
+
+        append_langgraph_event(self._state, namespace, mode, event)
+
+    async def ingest_turn(self, *, refetch: bool = False) -> None:
+        """Ingest the turn's captured checkpoint and restamp; ``refetch`` discards the capture and reads the checkpointer's latest instead."""
+        captured, self._captured = self._captured, None
+        if refetch or captured is None:
+            await self._thread.ingest_latest()
+        else:
+            await self._thread.ingest(langgraph_snapshot(captured))
+        self._restamp()
+
+    def append_users(self, messages: Any) -> list[dict[str, Any]]:
+        """Append harness user messages to the wire state as human entries, deduplicated by id; returns the langgraph turn entries."""
+        return [self._append_user(message) for message in messages]
+
+    async def append_messages(self, messages: list[dict[str, Any]]) -> None:
+        """Append ``{id, role, text}`` entries as a new checkpoint on the current tip and restamp; the voice commit path."""
+        from langchain_core.messages import AIMessage, HumanMessage
+        from langgraph.checkpoint.base import empty_checkpoint
+        from langgraph.checkpoint.base.id import uuid6
+
+        if not messages:
+            raise ValueError("messages must be non-empty")
+        for message in messages:
+            if message["role"] not in ("user", "assistant"):
+                raise ValueError(f"unsupported message role: {message['role']!r}")
+        entries = [
+            (HumanMessage if m["role"] == "user" else AIMessage)(
+                id=m["id"], content=m["text"]
+            )
+            for m in messages
+        ]
+        parent = {"configurable": {"thread_id": self._thread_id, "checkpoint_ns": ""}}
+        saved = await self._checkpointer.aget_tuple(parent)
+        if saved is None:
+            checkpoint = empty_checkpoint()
+            step = -1
+        else:
+            checkpoint = {**saved.checkpoint}
+            step = (saved.metadata or {}).get("step", -1)
+            parent["configurable"]["checkpoint_id"] = saved.checkpoint["id"]
+        version = self._checkpointer.get_next_version(
+            checkpoint["channel_versions"].get("messages"), None
+        )
+        checkpoint = {
+            **checkpoint,
+            "id": str(uuid6(clock_seq=-2)),
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "channel_values": {
+                **checkpoint["channel_values"],
+                "messages": [
+                    *checkpoint["channel_values"].get("messages", []),
+                    *entries,
+                ],
+            },
+            "channel_versions": {
+                **checkpoint["channel_versions"],
+                "messages": version,
+            },
+        }
+        metadata = {"source": "update", "step": step + 1, "parents": {}}
+        await self._checkpointer.aput(parent, checkpoint, metadata, {"messages": version})
+        await self._thread.ingest_latest()
+        self._restamp()
+
+    async def switch_branch(self, branch_id: int) -> None:
+        """Switch to ``branch_id``: its tip becomes the checkpointer's latest checkpoint and the wire state rebaselines."""
+        transcript, lineage = await self._thread.switch_state(branch_id)
+        checkpoint_id = await self._clone_tip(self._thread.checkpoint_id)
+        await self._thread.ingest(Snapshot(checkpoint_id, transcript, lineage))
+        self._restamp()
+
+    async def _clone_tip(self, checkpoint_id: str) -> str:
+        from langgraph.checkpoint.base.id import uuid6
+
+        parent = {
+            "configurable": {
+                "thread_id": self._thread_id,
+                "checkpoint_ns": "",
+                "checkpoint_id": checkpoint_id,
+            }
+        }
+        saved = await self._checkpointer.aget_tuple(parent)
+        if saved is None:
+            raise LookupError(f"checkpoint {checkpoint_id!r} is not in the checkpointer")
+        clone = {
+            **saved.checkpoint,
+            "id": str(uuid6(clock_seq=-2)),
+            "ts": datetime.now(timezone.utc).isoformat(),
+        }
+        metadata = {
+            "source": "update",
+            "step": (saved.metadata or {}).get("step", -1) + 1,
+            "parents": {},
+        }
+        written = await self._checkpointer.aput(parent, clone, metadata, {})
+        return written["configurable"]["checkpoint_id"]
+
+    async def _snapshot(self, checkpoint_id: str) -> Snapshot:
+        snapshot = await self._store.get(checkpoint_id)
+        if snapshot is None:
+            raise LookupError(
+                f"checkpoint {checkpoint_id!r} is not in the checkpointer"
+            )
+        return snapshot
+
+    def _append_user(self, message: dict[str, Any]) -> dict[str, Any]:
+        entry = {"id": message["id"], "type": "human", "content": _user_text(message)}
+        if not any(m["id"] == entry["id"] for m in plain(self._state["messages"])):
+            self._state["messages"].append(entry)
+        return entry
+
+    def _replace(self, messages: list[dict[str, Any]]) -> None:
+        from statewire.langgraph import replace_messages
+
+        replace_messages(self._state, messages)
+
+    def _restamp(self) -> None:
+        stamped = []
+        for message in self._thread.transcript:
+            branch, siblings = self._thread.sibling_info(message["id"])
+            stamped.append({**message, "branch": {"id": branch, "siblings": siblings}})
+        self._replace(stamped)

harness_sdk/run_manager.py

@@ -48,6 +48,7 @@ window.
 """
 
 import asyncio
+import contextlib
 import logging
 from dataclasses import dataclass, field
 from typing import Any, AsyncIterator, Callable, Coroutine, Iterable, Protocol
@@ -1610,7 +1611,7 @@ class RunManagerNamespace(TrayMapNamespace):
                 f"{type(api).__name__} must implement get_message_meta "
                 "(RunManager.Thread) to host @run_manager"
             )
-        self._mint_lock = asyncio.Lock()
+        self._mint: "asyncio.Task[Any] | None" = None
         self._mounted: list[RunManager] = []
         api.state["runs"] = []
         api.state["status"] = "ready"
@@ -1628,14 +1629,26 @@ class RunManagerNamespace(TrayMapNamespace):
         return tray
 
     async def _machine(self, run_id: str) -> tuple[RunManager, bool]:
-        tray = self.live()
-        if tray is not None:
-            return tray, False
-        async with self._mint_lock:
+        # No await between the live() check and the mint's publication, and no
+        # lock held across storage I/O: same-tick callers await the shared mint
+        # task and merge into the machine it mounts; the creator raises its
+        # mint's failure while followers re-mint and progress.
+        while True:
             tray = self.live()
             if tray is not None:
                 return tray, False
-            return await self.get_or_create(run_id), True  # type: ignore[return-value]
+            pending = self._mint
+            if pending is None:
+                pending = self._api.create_task(self.get_or_create(run_id))
+                self._mint = pending
+                pending.add_done_callback(self._mint_settled)
+                return await pending, True
+            with contextlib.suppress(Exception):
+                await pending
+
+    def _mint_settled(self, task: "asyncio.Task[Any]") -> None:
+        if self._mint is task:
+            self._mint = None
 
     # ─── Mounted view ───────────────────────────────────────
 

harness_sdk/voice.py

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

{harness_sdk_python-0.25.2.dist-info → harness_sdk_python-0.27.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.25.2
+Version: 0.27.0
 Summary: RunManager: the harness-sdk runs subsystem for Python Statewire hosts
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT

harness_sdk_python-0.27.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+harness_sdk/__init__.py,sha256=N9gOUKqe0_eM7cIA9sfA_lH1FBw1MN8U-zerwGAPVHE,1094
+harness_sdk/checkpoints.py,sha256=L02l1IyLDj2b-GD7_HGrck7uenALeI4kg8yJSzoNVmc,25999
+harness_sdk/deepagents.py,sha256=d7Vb1MhwU-UKSvsvuAKEEROxXf8mukEzqfEfCIlcxM4,10915
+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=LbFO8lpd3jzPuaj2RuxEHckP5TiVjKpQeMsxxaefDPg,14081
+harness_sdk_python-0.27.0.dist-info/METADATA,sha256=sA94429xkLoOYG23eysErRAPt00YaQemCcfnIgTPuYM,2200
+harness_sdk_python-0.27.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+harness_sdk_python-0.27.0.dist-info/RECORD,,

harness_sdk_python-0.25.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-harness_sdk/__init__.py,sha256=lHRu0sZVppfPjWawxEjXrcHIVSHCkdYQjCtIl5D2wmk,758
-harness_sdk/checkpoints.py,sha256=L02l1IyLDj2b-GD7_HGrck7uenALeI4kg8yJSzoNVmc,25999
-harness_sdk/fenced_postgres.py,sha256=hbbrMR1WaqrHTNgd4wFrXfRrzQFGnyim-c8nZXgwWp4,13235
-harness_sdk/linear_thread.py,sha256=laDRXKLFsMlyWS4snqNAM6t38wO26gevLWXRNivhHSM,1810
-harness_sdk/run_manager.py,sha256=xL6TsXJk_3SVyA5oNuGlPelDmCqCRmL-bWW5wsfiIBY,77028
-harness_sdk_python-0.25.2.dist-info/METADATA,sha256=zHAX5aTkYpynVaYAyhUfnapa_elP8vEonSz2bMXyRoA,2200
-harness_sdk_python-0.25.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-harness_sdk_python-0.25.2.dist-info/RECORD,,