harness-sdk-python 0.37.1__tar.gz → 0.38.0__tar.gz

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/.gitignore

@@ -28,3 +28,10 @@ apps/docs/.docs
 
 MAINTAIN_EPOCH.md
 DOCS_EPOCH.md
+
+# terraform
+.terraform/
+*.tfstate
+*.tfstate.*
+*.tfvars
+!*.tfvars.example

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.37.1
+Version: 0.38.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
 Requires-Python: <4.0,>=3.12
 Requires-Dist: pinned<0.16,>=0.15.2
-Requires-Dist: statewire<0.19,>=0.18.1
+Requires-Dist: statewire<0.20,>=0.19.0
 Provides-Extra: deepagents
 Requires-Dist: deepagents>=0.6.12; extra == 'deepagents'
 Requires-Dist: langchain-core>=0.3; extra == 'deepagents'
@@ -15,6 +15,9 @@ Requires-Dist: langgraph>=1.0.0; extra == 'deepagents'
 Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'deepagents'
 Provides-Extra: postgres
 Requires-Dist: langgraph-checkpoint-postgres>=2.0.0; extra == 'postgres'
+Provides-Extra: voice
+Requires-Dist: httpx>=0.27; extra == 'voice'
+Requires-Dist: websockets>=13; extra == 'voice'
 Description-Content-Type: text/markdown
 
 # harness-sdk-python

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/pyproject.toml

@@ -1,14 +1,15 @@
 [project]
 name = "harness-sdk-python"
-version = "0.37.1"
+version = "0.38.0"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12,<4.0"
-dependencies = ["statewire>=0.18.1,<0.19", "pinned>=0.15.2,<0.16"]
+dependencies = ["statewire>=0.19.0,<0.20", "pinned>=0.15.2,<0.16"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]
+voice = ["httpx>=0.27", "websockets>=13"]
 deepagents = [
     "deepagents>=0.6.12",
     "langgraph>=1.0.0",

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/src/harness_sdk/__init__.py

@@ -22,21 +22,21 @@ from .parts import PartsAssembler
 from .linear_thread import linear_thread
 from .run_manager import RunManager, RunManagerDescriptor, run_manager
 from .threads import DuplicateThread, HarnessThreads, MemoryThreadStore, ThreadRecord, ThreadStatus, ThreadStore, UnknownThread
-from .wire import CONTEXT, INTEREST, HarnessMessages
+from .wire import INTEREST, HarnessMessages
 from .voice import (
     VoiceManager,
     VoiceManagerDescriptor,
     VoiceProvider,
     VoiceTurnCommitDeferred,
     end_voice,
+    set_voice_mic,
     start_voice,
-    temp_frontend_tool_result,
     voice_client_departed,
     voice_manager,
 )
+from .voice_thread import VoiceThread
 
 __all__ = [
-    "CONTEXT",
     "HARNESS_PROTOCOL",
     "HARNESS_THREADS_PROTOCOL",
     "HarnessThreads",
@@ -66,6 +66,7 @@ __all__ = [
     "VoiceManager",
     "VoiceManagerDescriptor",
     "VoiceProvider",
+    "VoiceThread",
     "VoiceTurnCommitDeferred",
     "checkpoint_thread",
     "check_request",
@@ -80,8 +81,8 @@ __all__ = [
     "linear_thread",
     "resolve",
     "run_manager",
+    "set_voice_mic",
     "start_voice",
-    "temp_frontend_tool_result",
     "voice_client_departed",
     "voice_manager",
 ]

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/src/harness_sdk/deepagents.py

@@ -2,7 +2,9 @@
 langgraph checkpointer is the agent's resumption source; the checkpoint
 index rows carry the harness messages (``value``) the wire projects. A
 rewind forks the graph at the anchor message's checkpoint; a send off the
-head chain forks the same way.
+head chain forks the same way. ``run_subagent`` runs a turn in a subagent
+namespace on the langgraph thread ``<thread_id>/<ns>``, concurrent with the
+main run; its rows persist under ``checkpoint_ns == ns``.
 """
 
 from typing import Any, Callable
@@ -17,6 +19,7 @@ from .checkpoints import (
 )
 from .messages import MAIN_NS, MessageTree
 from .parts import PartsAssembler, text_of
+from .voice_thread import upsert_voice_turn
 
 _TYPE_TO_ROLE = {"human": "user", "ai": "assistant", "tool": "assistant", "system": "assistant"}
 
@@ -41,6 +44,10 @@ def _checkpoint_ns(ns: str) -> str:
     return "" if ns == MAIN_NS else ns
 
 
+def _root_of(ns: str) -> str:
+    return ns.split("|", 1)[0]
+
+
 class DeepagentsThread:
     """One thread's harness messages over a compiled deepagents graph: boot, turn planning, stream folding, ingest, subagents."""
 
@@ -67,7 +74,7 @@ class DeepagentsThread:
         self._input_checkpoint_seen = False
         self._assemblers: dict[str, PartsAssembler] = {}
         self._touched: set[tuple[str, str]] = set()
-        self._pending_subagents: dict[str, str] = {}
+        self._subagents: set[str] = set()
         self.interrupt: dict[str, Any] | None = None
 
     async def boot(self) -> None:
@@ -84,7 +91,9 @@ class DeepagentsThread:
                 thread.head = max(thread.messages.values(), key=lambda m: m["seq"])["id"]
                 self._thread_state(ns)
         if self._thread.transcript:
-            self.tree.set_head(MAIN_NS, self._harness_id(self._thread.transcript[-1]["id"]))
+            # voice turns commit after the run they preceded: the checkpoint tail may sit above the tree leaf
+            last = self._harness_id(self._thread.transcript[-1]["id"])
+            self.tree.set_head(MAIN_NS, self.tree.thread(MAIN_NS).leaf_of(last))
         else:
             self.tree.thread(MAIN_NS)
         self._thread_state(MAIN_NS)
@@ -105,18 +114,7 @@ class DeepagentsThread:
         self._threads[ns] = {**current, **fields, "headId": thread.head}
 
     async def get_message_meta(self, message_id: str | None) -> dict[str, Any] | None:
-        thread = self.tree.thread(MAIN_NS)
-        if message_id is None:
-            return {"isLeaf": thread.head is None}
-        message = thread.messages.get(message_id)
-        if message is None:
-            return None
-        return {
-            "parentId": message["parentId"],
-            "role": message["role"],
-            "isLeaf": not thread.children.get(message_id),
-            "onActiveBranch": True,
-        }
+        return self.tree.meta(MAIN_NS, message_id)
 
     def config(self) -> dict[str, Any]:
         return {"configurable": {"thread_id": self._thread_id}}
@@ -248,8 +246,8 @@ class DeepagentsThread:
         if langchain_id not in plain(ids):
             ids.append(langchain_id)
 
-    def _spawn(self, ns: str, description: str) -> None:
-        main = self._assemblers.get(MAIN_NS)
+    def _spawn(self, parent: str, ns: str, description: str) -> None:
+        main = self._assemblers.get(parent)
         if main is None:
             return
         for part in plain(main.parts):
@@ -289,7 +287,7 @@ class DeepagentsThread:
                 )
                 self._touched.add((ns, first.id))
                 self._thread_state(ns, status="streaming")
-                self._spawn(ns, text_of(first.content))
+                self._spawn(_ns_of(namespace[:-1]), ns, text_of(first.content))
                 self._changed()
             return
         if mode == "messages":
@@ -303,8 +301,8 @@ class DeepagentsThread:
                 assembler = self._assemblers.get(ns)
                 if assembler is not None:
                     self._fold_id(assembler, message.id)
-                    sub_ns = meta.get("langgraph_checkpoint_ns")
-                    if ns == MAIN_NS and sub_ns in self.tree.threads:
+                    sub_ns = _ns_of((*namespace, *meta.get("langgraph_checkpoint_ns", "").split("|")))
+                    if sub_ns in self.tree.threads:
                         assembler.amend(message.tool_call_id, metadata={"ns": sub_ns})
                         self._finish(sub_ns)
                     assembler.tool_result(message)
@@ -336,15 +334,53 @@ class DeepagentsThread:
             await self._thread.ingest(langgraph_snapshot(captured))
         if self._input_checkpoint_seen:
             self._confirm_admission()
-        for ns in list(self._assemblers):
+        for ns in self._turn_namespaces():
             if self.interrupt is None or ns != MAIN_NS:
                 self._finish(ns)
         for ns in self.tree.threads:
-            if ns != MAIN_NS:
+            if ns != MAIN_NS and _root_of(ns) not in self._subagents:
                 self._thread_state(ns, status="idle")
         await self._persist()
         self._changed()
 
+    def _turn_namespaces(self) -> list[str]:
+        return [ns for ns in self._assemblers if _root_of(ns) not in self._subagents]
+
+    async def run_subagent(self, ns: str, message: dict[str, Any]) -> None:
+        """Run a harness user ``message`` as a turn in subagent namespace ``ns``: its reply streams into the tree and persists under ``checkpoint_ns == ns``."""
+        from langchain_core.messages import HumanMessage
+
+        if ns == MAIN_NS or "|" in ns:
+            raise ValueError(f"subagent namespace must be a root namespace other than {MAIN_NS!r}, got {ns!r}")
+        if ns in self._subagents:
+            raise RuntimeError(f"subagent {ns!r} is already running")
+        thread = self.tree.thread(ns)
+        self.tree.add(ns, {**message, "parentId": thread.head})
+        self._touched.add((ns, message["id"]))
+        self._thread_state(ns, status="streaming")
+        self._subagents.add(ns)
+        self._changed()
+        config = {"configurable": {"thread_id": f"{self._thread_id}/{ns}"}}
+        payload = {"messages": [HumanMessage(id=message["id"], content=_user_text(message))]}
+        try:
+            async for namespace, mode, event in self._agent.astream(
+                payload, config=config, stream_mode=["messages", "updates", "checkpoints"], subgraphs=True
+            ):
+                self.append_event((ns, *namespace), mode, event)
+        finally:
+            self._subagents.discard(ns)
+            for sub in [sub for sub in self._assemblers if _root_of(sub) == ns]:
+                self._finish(sub)
+            for sub in [sub for sub in self.tree.threads if _root_of(sub) == ns]:
+                self._thread_state(sub, status="idle")
+            await self._persist()
+            self._changed()
+
+    async def persist_message(self, ns: str, message_id: str) -> None:
+        """Write one tree message's index row."""
+        self._touched.add((ns, message_id))
+        await self._persist()
+
     async def _persist(self) -> None:
         touched, self._touched = self._touched, set()
         rows = [
@@ -361,13 +397,32 @@ class DeepagentsThread:
         if rows:
             await self._index.upsert_messages(rows)
 
+    async def append_turns(self, turns: list[dict[str, Any]]) -> None:
+        """Commit ``{id, role, text}`` voice turns: one state update on the main tip carries them as messages and the tree entries turn durable."""
+        from langchain_core.messages import AIMessage, HumanMessage
+
+        if not turns:
+            raise ValueError("turns must be non-empty")
+        entries = [
+            (HumanMessage if turn["role"] == "user" else AIMessage)(id=turn["id"], content=turn["text"])
+            for turn in turns
+        ]
+        await self._agent.aupdate_state(self.config(), {"messages": entries}, as_node="__start__")
+        for turn in turns:
+            upsert_voice_turn(self.tree, turn, ephemeral=False)
+            self._touched.add((MAIN_NS, turn["id"]))
+        await self._thread.ingest_latest()
+        self._thread_state(MAIN_NS)
+        await self._persist()
+        self._changed()
+
     def abandon_turn(self) -> None:
         """Discard a stream capture and any fork planned for the abandoned turn."""
         self._captured = None
         self._admission = None
         self._input_checkpoint_seen = False
         self.interrupt = None
-        for ns in list(self._assemblers):
+        for ns in self._turn_namespaces():
             self._finish(ns)
         self._thread.abandon_plan()
 

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/src/harness_sdk/deepagents_host.py

@@ -1,52 +1,44 @@
 """DeepagentsHost: a Statewire host serving one deepagents thread over the
 harness protocol. Subclasses implement ``build_agent`` and the app assigns
-``checkpointer`` and ``index`` before serving.
+``checkpointer`` and ``index`` before serving. A ``@voice_manager()`` on the
+subclass enables the ``voice/*`` commands: voice turns commit as one
+checkpoint each flush once no run is in flight, delegated tasks run as
+subagent turns through ``run_subagent``.
 """
 
 import asyncio
 import contextlib
+import logging
 from typing import Any
 
 from statewire import Statewire, command
 
 from .checkpoints import CheckpointIndex
 from .deepagents import DeepagentsThread
-from .langgraph import FrontierCheckpointer
-from .protocol import HARNESS_PROTOCOL
 from .messages import MAIN_NS
+from .protocol import HARNESS_PROTOCOL
 from .run_manager import RunManager, run_manager
+from .voice import VoiceTurnCommitDeferred, end_voice, set_voice_mic, start_voice, voice_client_departed
+from .voice_thread import VoiceThread, is_ephemeral
 from .wire import HarnessMessages
 
-TITLE_LENGTH = 80
-
+logger = logging.getLogger(__name__)
+_HALTED = ("stopped", "error")
 
-def first_user_text(tree: Any) -> str | None:
-    """Text of the first user message on the main head chain, cut to ``TITLE_LENGTH``."""
-    thread = tree.threads.get(MAIN_NS)
-    if thread is None or thread.head is None:
-        return None
-    for message_id in thread.chain(thread.head):
-        message = thread.messages[message_id]
-        if message["role"] != "user":
-            continue
-        text = " ".join(p["text"] for p in message["parts"] if p.get("type") == "text").strip()
-        return text[:TITLE_LENGTH] if text else None
-    return None
 
-
-class DeepagentsHost(HarnessMessages, Statewire):
+class DeepagentsHost(VoiceThread, HarnessMessages, Statewire):
     """One thread: ``build_agent(checkpointer)`` returns the compiled deepagents graph."""
 
     protocols = (HARNESS_PROTOCOL,)
     checkpointer: Any = None
     index: CheckpointIndex | None = None
-    #: Path of the ``HarnessThreads`` instance this thread lists itself on, e.g. ``"/thread-lists/default"``. Alpha.
-    thread_list: str | None = None
 
     def build_agent(self, checkpointer: Any) -> Any:
         raise NotImplementedError(f"{type(self).__name__}.build_agent")
 
     async def lifespan(self):
+        from .langgraph import FrontierCheckpointer
+
         if type(self).checkpointer is None or type(self).index is None:
             raise RuntimeError(f"{type(self).__name__}.checkpointer and .index must be assigned before serving")
         checkpointer = FrontierCheckpointer(
@@ -65,11 +57,77 @@ class DeepagentsHost(HarnessMessages, Statewire):
             changed=self.refresh_messages,
         )
         await self.messages.boot()
+        self._voice_journal: dict[str, dict[str, Any]] = {}
         yield
 
     async def get_message_meta(self, message_id: str | None) -> dict[str, Any] | None:
         return await self.messages.get_message_meta(message_id)
 
+    # ─── Voice ──────────────────────────────────────────────
+
+    def _runs_quiet(self) -> bool:
+        live = self.run.live()
+        return live is None or live.status.value in ("ready", *_HALTED)
+
+    async def commit_voice_turns(self, turns: list[dict[str, Any]]) -> None:
+        for turn in turns:
+            message = self.tree.get(MAIN_NS, turn["id"])
+            if message is None or is_ephemeral(message):
+                self._voice_journal[turn["id"]] = turn
+        if not self._runs_quiet():
+            raise VoiceTurnCommitDeferred(f"run {self.state['status']}")
+        await self._commit_voice_journal()
+
+    async def _commit_voice_journal(self) -> None:
+        turns, self._voice_journal = list(self._voice_journal.values()), {}
+        if turns:
+            await self.messages.append_turns(turns)
+
+    async def _deliver_voice_journal(self) -> None:
+        # a run dispatched between the settle and this write would race the checkpoint; the journal keeps the turns until the next settle.
+        # a journaled turn keeps its tree position; the graph state appends it after the run's messages
+        if not self._runs_quiet():
+            return
+        try:
+            await self._commit_voice_journal()
+        except Exception:
+            logger.exception("voice turns failed to commit after the run settled")
+
+    def drop_ephemeral_message(self, message_id: str) -> None:
+        if message_id not in self._voice_journal:
+            super().drop_ephemeral_message(message_id)
+
+    async def run_subagent(self, ns: str, message: dict[str, Any]) -> None:
+        await self.messages.run_subagent(ns, message)
+
+    async def delegate(self, task_id: str, text: str) -> str:
+        try:
+            return await super().delegate(task_id, text)
+        finally:
+            await self.messages.persist_message(MAIN_NS, f"voicetask_{task_id}")
+
+    def run_status_changed(self, status: str) -> None:
+        super().run_status_changed(status)
+        if status in ("ready", *_HALTED) and self._voice_journal:
+            self.create_task(self._deliver_voice_journal())
+
+    @command("voice/start")
+    async def voice_start(self, params, *, ctx):
+        return await start_voice(self, params, ctx=ctx)
+
+    @command("voice/end")
+    async def voice_end(self, params=None, *, ctx):
+        return await end_voice(self, ctx=ctx)
+
+    @command("voice/mic")
+    async def voice_mic(self, params, *, ctx):
+        return await set_voice_mic(self, params, ctx=ctx)
+
+    def client_departed(self, client_id: str) -> None:
+        voice_client_departed(self, client_id)
+
+    # ─── Runs ───────────────────────────────────────────────
+
     @run_manager(capabilities=("rewind",))
     async def run(self, ctx: RunManager.RunContext) -> Any:
         payload, config = await self.messages.plan_turn(ctx)
@@ -80,7 +138,6 @@ class DeepagentsHost(HarnessMessages, Statewire):
             except BaseException:
                 self.messages.abandon_turn()
                 raise
-            await self._touch_thread_list()
             if outcome is not None:
                 return outcome
             interrupt = self.messages.interrupt
@@ -95,17 +152,6 @@ class DeepagentsHost(HarnessMessages, Statewire):
             payload = {"messages": steered}
             config = self.messages.config()
 
-    async def _touch_thread_list(self) -> None:
-        if self.thread_list is None:
-            return
-        body: dict[str, Any] = {"threadId": self.id}
-        title = first_user_text(self.tree)
-        if title is not None:
-            body["title"] = title
-        response = await self.cluster.post(f"{self.thread_list}/touch", json=body)
-        if response.status_code != 200:
-            raise RuntimeError(f"{self.thread_list}/touch answered {response.status_code}: {response.text}")
-
     async def _stream_turn(self, ctx: RunManager.RunContext, payload: Any, config: dict[str, Any]) -> Any:
         stream = self.agent.astream(
             payload, config=config, stream_mode=["messages", "updates", "checkpoints"], subgraphs=True

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/src/harness_sdk/messages.py

@@ -73,6 +73,21 @@ class MessageTree:
         thread = self.threads.get(ns)
         return None if thread is None else thread.messages.get(message_id)
 
+    def meta(self, ns: str, message_id: str | None) -> dict[str, Any] | None:
+        """``get_message_meta`` over the tree: the root's leafness for None, else the message's parent, role, leafness."""
+        thread = self.thread(ns)
+        if message_id is None:
+            return {"isLeaf": thread.head is None}
+        message = thread.messages.get(message_id)
+        if message is None:
+            return None
+        return {
+            "parentId": message["parentId"],
+            "role": message["role"],
+            "isLeaf": not thread.children.get(message_id),
+            "onActiveBranch": True,
+        }
+
     def add(self, ns: str, message: dict[str, Any], *, head: bool = True) -> dict[str, Any]:
         """Add a message; ``seq`` is assigned unless present; the head moves to it by default."""
         _check_message(message)
@@ -103,6 +118,20 @@ class MessageTree:
             raise KeyError(f"message {message_id!r} is not in {ns!r}")
         thread.messages[message_id] = value
 
+    def remove(self, ns: str, message_id: str) -> None:
+        """Remove a message; its children re-parent to its parent, and a head on it moves to the parent."""
+        thread = self.thread(ns)
+        if message_id not in thread.messages:
+            raise KeyError(f"message {message_id!r} is not in {ns!r}")
+        parent = thread.messages.pop(message_id)["parentId"]
+        thread.children[parent].remove(message_id)
+        for child in thread.children.pop(message_id, []):
+            thread.messages[child]["parentId"] = parent
+            thread.children[parent].append(child)
+        thread.children[parent].sort(key=lambda i: thread.messages[i]["seq"])
+        if thread.head == message_id:
+            thread.head = parent
+
     def set_head(self, ns: str, message_id: str | None) -> None:
         thread = self.thread(ns)
         if message_id is not None and message_id not in thread.messages:

{harness_sdk_python-0.37.1 → harness_sdk_python-0.38.0}/src/harness_sdk/protocol.py

@@ -3,11 +3,10 @@ from statewire.protocol import Subprotocol
 
 HARNESS_PROTOCOL = Statewire.Protocol(
     "harness-sdk",
-    version="2026-09-13",
-    min_version="2026-09-13",
+    version="2026-09-30",
+    min_version="2026-09-30",
     subprotocols=(
         Subprotocol("interest", record="ephemeral"),
-        Subprotocol("context", record="ephemeral"),
     ),
 )
 

harness_sdk_python-0.38.0/src/harness_sdk/providers/__init__.py

@@ -0,0 +1 @@
+"""Voice providers: ``VoiceProvider`` implementations over vendor APIs."""