harness-sdk-python 0.25.2__tar.gz → 0.27.0__tar.gz

{harness_sdk_python-0.25.2 → harness_sdk_python-0.27.0}/PKG-INFO

@@ -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.25.2 → harness_sdk_python-0.27.0}/pyproject.toml

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

{harness_sdk_python-0.25.2 → harness_sdk_python-0.27.0}/src/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_python-0.27.0/src/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_python-0.25.2 → harness_sdk_python-0.27.0}/src/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 ───────────────────────────────────────