harness-sdk-python 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

harness_sdk/__init__.py

@@ -14,6 +14,14 @@ from .checkpoints import (
 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",
@@ -26,10 +34,16 @@ __all__ = [
     "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

@@ -66,6 +66,7 @@ class DeepagentsMessages:
             )
         self._checkpointer = checkpointer
         self._captured: dict[str, Any] | None = None
+        self._ephemeral: dict[str, dict[str, Any]] = {}
 
     async def boot(
         self, state: Any, *, index: CheckpointIndex, thread_id: str
@@ -150,6 +151,56 @@ class DeepagentsMessages:
         """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)
@@ -191,6 +242,26 @@ class DeepagentsMessages:
             )
         return snapshot
 
+    def upsert_ephemeral_message(self, message: dict[str, Any]) -> None:
+        """Render an in-flight ``{id, role, text}`` entry in ``state["messages"]``; an ``append_messages`` of the same id replaces it durably."""
+        if message["role"] not in ("user", "assistant"):
+            raise ValueError(f"unsupported message role: {message['role']!r}")
+        if message["id"] not in self._ephemeral and any(
+            m["id"] == message["id"] for m in self._thread.transcript
+        ):
+            raise ValueError(f"message {message['id']!r} is already durable")
+        self._ephemeral[message["id"]] = {
+            "id": message["id"],
+            "type": "human" if message["role"] == "user" else "ai",
+            "content": message["text"],
+        }
+        self._restamp()
+
+    def drop_ephemeral_message(self, message_id: str) -> None:
+        """Remove an in-flight entry from the ``state["messages"]`` projection."""
+        del self._ephemeral[message_id]
+        self._restamp()
+
     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"])):
@@ -207,4 +278,8 @@ class DeepagentsMessages:
         for message in self._thread.transcript:
             branch, siblings = self._thread.sibling_info(message["id"])
             stamped.append({**message, "branch": {"id": branch, "siblings": siblings}})
+        durable = {message["id"] for message in stamped}
+        stamped.extend(
+            entry for id_, entry in self._ephemeral.items() if id_ not in durable
+        )
         self._replace(stamped)

harness_sdk/voice.py

@@ -0,0 +1,418 @@
+"""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}`` — 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 render live in ``state["messages"]`` through
+``Host.upsert_ephemeral_message`` (message id = turn id); each completed
+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.
+
+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 and the in-memory turn
+    buffer rendered live in ``state["messages"]``; completed turns commit
+    per turn and ended sessions flush and self-delete."""
+
+    connection_poll = 0.5
+
+    clientId = observable(None)
+    status = observable("connecting")
+    answer = observable(None)
+
+    state = observable(
+        {
+            "clientId": clientId,
+            "status": status,
+            "answer": answer,
+        }
+    )
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._provider: "VoiceProvider | None" = None
+        self._turns: list[dict[str, Any]] = []
+        self._flushing = asyncio.Lock()
+        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, live and 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."""
+            ...
+
+        def upsert_ephemeral_message(self, message: dict[str, Any]) -> None:
+            """Render an in-flight ``{id, role, text}`` turn in ``state["messages"]``; same id updates in place."""
+            ...
+
+        def drop_ephemeral_message(self, message_id: str) -> None:
+            """Remove an in-flight turn from the ``state["messages"]`` projection."""
+            ...
+
+    # ─── 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)
+        await self._flush()
+        turns, self._turns = self._turns, []
+        for turn in turns:
+            self._host.drop_ephemeral_message(turn["id"])
+        self.status.value = "closed"
+        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")
+
+    @property
+    def _host(self) -> Any:
+        return self.handler.__self__
+
+    def _render(self, turn: dict[str, Any]) -> None:
+        self._host.upsert_ephemeral_message(
+            {"id": turn["id"], "role": turn["role"], "text": turn["text"]}
+        )
+
+    async def _flush(self) -> None:
+        # the lock serializes commits in done-order across turn-done and end
+        async with self._flushing:
+            done = [t for t in self._turns if t["done"]]
+            if not done:
+                return
+            try:
+                await self._host.commit_voice_turns(
+                    [{"id": t["id"], "role": t["role"], "text": t["text"]} for t in done]
+                )
+            except Exception:
+                logger.exception("voice session %r turn commit failed", self.id)
+                return
+            committed = {t["id"] for t in done}
+            self._turns = [t for t in self._turns if t["id"] not in committed]
+            for turn_id in committed:
+                self._host.drop_ephemeral_message(turn_id)
+
+    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")
+        turn = {"id": turn_id, "role": role, "text": "", "done": False}
+        self._turns.append(turn)
+        self._render(turn)
+
+    def turn_delta(self, turn_id: str, text: str) -> None:
+        if self._ended:
+            return
+        turn = self._turn(turn_id)
+        turn["text"] += text
+        self._render(turn)
+
+    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._render(turn)
+        self._spawn(self._flush())
+
+    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",
+            "upsert_ephemeral_message",
+            "drop_ephemeral_message",
+        ):
+            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.26.0.dist-info → harness_sdk_python-0.28.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.26.0
+Version: 0.28.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.28.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=nnpJ65NeVXcpZNoFOSq6brVYrKdEqSjWgf6wz_WlHiw,12145
+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=e9aw3hwgOq9l34VSyySxhfK3RY1WErPtZ_kVlBHtuHE,15663
+harness_sdk_python-0.28.0.dist-info/METADATA,sha256=Vut2SI_mn0FFCWh8n_cLh4lJp_ICPIbkUgoxjPEg3pU,2200
+harness_sdk_python-0.28.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+harness_sdk_python-0.28.0.dist-info/RECORD,,

harness_sdk_python-0.26.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-harness_sdk/__init__.py,sha256=ehKf5P2F8tmWWGJDdxKB082dGV7GWlxXSo-GAhH3Ne4,827
-harness_sdk/checkpoints.py,sha256=L02l1IyLDj2b-GD7_HGrck7uenALeI4kg8yJSzoNVmc,25999
-harness_sdk/deepagents.py,sha256=Zl5n8Xu8LVQZEwmDnG1sfNzLhiNH5Miv1__bjZPb_bE,8741
-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_python-0.26.0.dist-info/METADATA,sha256=2nu-IellMnPO7WAGwWMEm2kYIPfqwFo3HXKQG6cs3kE,2200
-harness_sdk_python-0.26.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-harness_sdk_python-0.26.0.dist-info/RECORD,,