harness-sdk-python 0.9.0__tar.gz → 0.10.1__tar.gz

{harness_sdk_python-0.9.0 → harness_sdk_python-0.10.1}/.gitignore

@@ -22,3 +22,5 @@ __pycache__
 /doc_*.md
 apps/docs/.docs
 /.agentdoc/
+.vercel
+.env*

{harness_sdk_python-0.9.0 → harness_sdk_python-0.10.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: harness-sdk-python
-Version: 0.9.0
+Version: 0.10.1
 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.11
-Requires-Dist: statewire<0.5,>=0.4.0
+Requires-Dist: statewire<0.6,>=0.5.0
 Provides-Extra: deepagents
 Requires-Dist: deepagents>=0.6.12; extra == 'deepagents'
 Requires-Dist: langchain-core>=0.3; extra == 'deepagents'

harness_sdk_python-0.10.1/examples/runs_app.py

@@ -0,0 +1,203 @@
+"""Minimal RunManager backend: a no-tools deepagents agent behind statewire.
+
+Run from python/harness-sdk-python:
+
+    uv run --extra deepagents uvicorn examples.runs_app:app --port 8000
+
+State is ``{"messages": [...]}`` in langchain format; rewind truncates the
+list. Threads live at /threads/{id}: ``GET .../stream`` (SSE), ``.../ws``,
+``POST .../commands``, and ``POST .../assistant-transport/api/chat``.
+
+Set PINBOARD_URL, PINBOARD_TOKEN, and ADVERTISE_URL to register with a
+pinboard control plane instead of local placement.
+"""
+
+import asyncio
+import contextlib
+import os
+from typing import Any
+
+from fastapi import FastAPI
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+from pinned import PinnedHost
+from statewire import AssistantTransport, command, plain
+from statewire.langgraph import append_langgraph_event
+
+from harness_sdk import RunManager, linear_thread
+
+
+def select_model() -> str:
+    if model := os.environ.get("DEEPAGENTS_MODEL"):
+        return model
+    if os.environ.get("OPENAI_API_KEY"):
+        return "openai:gpt-4o"
+    return "anthropic:claude-opus-4-8"
+
+
+def build_agent() -> Any:
+    from deepagents import create_deep_agent
+    from langgraph.checkpoint.memory import MemorySaver
+
+    return create_deep_agent(
+        model=select_model(),
+        tools=[],
+        system_prompt="You are a concise assistant.",
+        checkpointer=MemorySaver(),
+    )
+
+
+def to_langchain(message: dict[str, Any]) -> Any:
+    match message["type"]:
+        case "human":
+            return HumanMessage(id=message["id"], content=message["content"])
+        case "ai":
+            return AIMessage(
+                id=message["id"],
+                content=message["content"],
+                tool_calls=message.get("tool_calls") or [],
+            )
+        case "tool":
+            return ToolMessage(
+                id=message["id"],
+                content=message["content"],
+                tool_call_id=message["tool_call_id"],
+            )
+        case other:
+            raise ValueError(f"unsupported message type: {other}")
+
+
+def user_text(message: dict[str, Any]) -> str:
+    return "\n\n".join(
+        part["text"] for part in message["parts"] if part["type"] == "text"
+    )
+
+
+class RunsHost(AssistantTransport):
+    assistant_transport_protocol = "assistant-transport"
+
+    async def lifespan(self):
+        self.agent = build_agent()
+        self.state = {"messages": []}
+        self.thread = linear_thread(
+            messages=lambda: plain(self.state["messages"]),
+            role=lambda m: "user" if m["type"] == "human" else "assistant",
+        )
+        self.turn = 0
+        self.runs = RunManager(
+            state=self.state,
+            run=self.run,
+            thread=self.thread,
+            create_task=self.create_task,
+            schedule=self.schedule,
+            capabilities=("rewind",),
+        )
+        yield
+
+    async def get_message_child_id(self, parent_id: str) -> str | None:
+        return await self.thread.get_message_child_id(parent_id)
+
+    async def run(self, ctx: RunManager.RunContext) -> Any:
+        if ctx.has_rollback:
+            self.truncate(ctx.rollback_to)
+        pending = list(ctx.messages)
+        while True:
+            for message in pending:
+                self.state["messages"].append(
+                    {
+                        "id": message["id"],
+                        "type": "human",
+                        "content": user_text(message),
+                    }
+                )
+            ctx.ack()
+            outcome = await self.stream_turn(ctx)
+            if outcome is not None:
+                return outcome
+            pending = list(ctx.steering.take())
+            if not pending:
+                return RunManager.Complete()
+
+    def truncate(self, message_id: str | None) -> None:
+        messages = self.state["messages"]
+        keep = 0
+        if message_id is not None:
+            items = plain(messages)
+            keep = 1 + next(
+                index for index, m in enumerate(items) if m["id"] == message_id
+            )
+        while len(plain(messages)) > keep:
+            messages.pop()
+
+    async def stream_turn(self, ctx: RunManager.RunContext) -> Any:
+        history = [to_langchain(m) for m in plain(self.state["messages"])]
+        self.turn += 1
+        stream = self.agent.astream(
+            {"messages": history},
+            config={"configurable": {"thread_id": f"{self.id}:{self.turn}"}},
+            stream_mode=["messages", "updates"],
+            subgraphs=True,
+        )
+        iterator = stream.__aiter__()
+        stop = asyncio.ensure_future(ctx.stop_requested.wait())
+        try:
+            while True:
+                step = asyncio.ensure_future(anext(iterator))
+                await asyncio.wait({step, stop}, return_when=asyncio.FIRST_COMPLETED)
+                if stop.done() and not step.done():
+                    step.cancel()
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await step
+                    return RunManager.Stop(dispatch_queue=True)
+                try:
+                    namespace, mode, payload = await step
+                except StopAsyncIteration:
+                    return None
+                append_langgraph_event(self.state, namespace, mode, payload)
+        finally:
+            stop.cancel()
+            with contextlib.suppress(Exception):
+                await stream.aclose()
+
+    @command("run/enqueue")
+    async def run_enqueue(self, params, *, ctx):
+        return await self.runs.enqueue(params, ack=ctx.ack)
+
+    @command("run/steer")
+    async def run_steer(self, params, *, ctx):
+        return await self.runs.steer(params, ack=ctx.ack)
+
+    @command("run/dequeue")
+    async def run_dequeue(self, params):
+        return await self.runs.dequeue(params)
+
+    @command("run/edit")
+    async def run_edit(self, params, *, ctx):
+        return await self.runs.edit(params, ack=ctx.ack)
+
+    @command("run/reload")
+    async def run_reload(self, params, *, ctx):
+        return await self.runs.reload(params, ack=ctx.ack)
+
+    @command("run/stop")
+    async def run_stop(self, params=None, *, ctx):
+        return await self.runs.stop(params, ack=ctx.ack)
+
+    @command("run/continue")
+    async def run_continue(self, params=None, *, ctx):
+        return await self.runs.continue_run(ack=ctx.ack)
+
+    @command("run/input")
+    async def run_input(self, params):
+        return await self.runs.input(params)
+
+
+_pinboard_url = os.environ.get("PINBOARD_URL")
+router = PinnedHost(
+    RunsHost,
+    pinboard_url=_pinboard_url,
+    token=os.environ.get("PINBOARD_TOKEN"),
+    advertise_url=os.environ.get("ADVERTISE_URL"),
+    namespace="/threads" if _pinboard_url else None,
+)
+app = FastAPI(lifespan=router.lifespan)
+app.include_router(router, prefix="/threads")

{harness_sdk_python-0.9.0 → harness_sdk_python-0.10.1}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.9.0"
+version = "0.10.1"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11,<4.0"
-dependencies = ["statewire>=0.4.0,<0.5"]
+dependencies = ["statewire>=0.5.0,<0.6"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]

{harness_sdk_python-0.9.0 → harness_sdk_python-0.10.1}/src/harness_sdk/run_manager.py

@@ -8,11 +8,10 @@ reduces the whole intake in order, then takes exactly one action based on
 status and net effect (interrupt, dispatch, or continue). A dispatchable send
 appends straight into ``dispatching`` — it never transits a queue lane — and
 everything staged there by the end of the drain dispatches as one run. Every
-send acks and settles accepted with its state-visible insert (lane or
-``dispatching``); edit, reload, and continue initiators ack at their dispatch
-and settle when their run ends — accepted once the run has acked its
-messages, rejected otherwise; ``run/stop`` awaits a future the drain resolves
-once the in-flight run has ended.
+initiator acks and settles accepted with its state-visible application —
+sends with their insert (lane or ``dispatching``), edit/reload/continue at
+their dispatch; ``run/stop`` awaits a future the drain resolves once the
+in-flight run has ended.
 
 ``entry["dispatching"]`` is the dispatch record (or None): the payload the
 run callback receives. ``ctx.ack()`` clears it; ``steering.take()`` may
@@ -23,7 +22,6 @@ the front of the queue, rewind replacements dropped.
 """
 
 import asyncio
-import uuid
 from dataclasses import dataclass, field
 from typing import Any, Awaitable, Callable, Iterable, Protocol
 
@@ -62,6 +60,13 @@ def _reject(reason: str, message: str) -> StatewireReject:
     return StatewireReject(message, payload={"reason": reason})
 
 
+def _run_id_of(params: Any) -> str:
+    run_id = params.get("runId") if isinstance(params, dict) else None
+    if not isinstance(run_id, str) or run_id == "":
+        raise _reject("invalid-message", "runId must be a non-empty string")
+    return run_id
+
+
 def _future() -> "asyncio.Future[Any]":
     return asyncio.get_running_loop().create_future()
 
@@ -75,6 +80,7 @@ class _Send:
     source_meta: dict[str, Any] | None
     meta: Any
     ack: Callable[[], None]
+    run_id: str = ""
     anchor: Any = _ABSENT
     anchor_meta: dict[str, Any] | None = None
     thread_empty: bool = False
@@ -94,6 +100,7 @@ class _Edit:
     message: dict[str, Any]
     meta: Any
     ack: Callable[[], None]
+    run_id: str
     future: "asyncio.Future[Any]" = field(default_factory=_future)
 
 
@@ -102,6 +109,7 @@ class _Reload:
     source_meta: dict[str, Any]
     meta: Any
     ack: Callable[[], None]
+    run_id: str
     future: "asyncio.Future[Any]" = field(default_factory=_future)
 
 
@@ -131,6 +139,7 @@ class _Rewind:
     rollback_to: Any
     ack: Callable[[], None]
     future: "asyncio.Future[Any]"
+    run_id: str
     root_meta: Any = None
 
 
@@ -139,7 +148,7 @@ class _Effects:
     steer_added: bool = False
     continue_requested: bool = False
     continue_meta: Any = None
-    staged_sends: list[tuple["asyncio.Future[Any]", Callable[[], None]]] = field(
+    staged_sends: list[tuple["asyncio.Future[Any]", Callable[[], None], Any]] = field(
         default_factory=list
     )
     continues: list["asyncio.Future[Any]"] = field(default_factory=list)
@@ -195,8 +204,6 @@ class RunManager:
         self._stop_reason: str | None = None
         self._staged_rewinds: list[_Rewind] = []
         self._dispatching: list[tuple[str, dict[str, Any]]] = []
-        self._run_acked = False
-        self._run_futures: list["asyncio.Future[Any]"] = []
         self._input_requests: list[dict[str, Any]] = []
         self._input_answers: dict[str, Any] = {}
         self._idle = asyncio.Event()
@@ -302,6 +309,9 @@ class RunManager:
                 self._clear_input()
                 if self._dispatching:
                     self._revert_dispatching()
+                entry = self._ensure_entry()
+                if entry["runId"] is None:
+                    entry["runId"] = rewind.run_id
                 self._dispatch(
                     rewind.type,
                     rewind.messages,
@@ -310,7 +320,7 @@ class RunManager:
                 )
                 rewind.ack()
                 if not rewind.future.done():
-                    self._run_futures.append(rewind.future)
+                    rewind.future.set_result(None)
             elif outcome is not None:
                 self._settle_outcome(outcome)
             else:
@@ -318,10 +328,10 @@ class RunManager:
         if self._task is not None and (self._staged_stops or self._staged_rewinds):
             assert self._ctx is not None
             self._ctx.stop_requested.set()
-        for future, ack in fx.staged_sends:
+        for future, ack, result in fx.staged_sends:
             ack()
             if not future.done():
-                future.set_result(None)
+                future.set_result(result)
         for future in fx.continues:
             if not future.done():
                 future.set_result(None)
@@ -364,8 +374,6 @@ class RunManager:
         elif status in ("error", "stopped"):
             if fx.continue_requested or fx.steer_added:
                 self._dispatch(self._continue_type(), [], root_meta=fx.continue_meta)
-                self._run_futures.extend(fx.continues)
-                fx.continues.clear()
             elif self._dispatching:
                 self._dispatch_staged()
         elif status == "input-required":
@@ -398,7 +406,6 @@ class RunManager:
         if outcome.dispatch_queue and self._pop_dispatchable():
             return
         self._set_status(status)
-        self._entry()["runId"] = None
 
     # ─── Dispatch and settle ────────────────────────────────
 
@@ -445,13 +452,11 @@ class RunManager:
             ]
         self._dispatch_record = dict(record)
         self._stop_reason = None
-        self._run_acked = False
         entry = self._ensure_entry()
         entry["dispatching"] = record
         entry["error"] = None
         if messages:
             self._dispatched_ids = tuple(m["id"] for m in messages)
-        entry["runId"] = uuid.uuid4().hex
         self._set_status("running")
         ctx = RunManager.RunContext(
             trigger=trigger,
@@ -487,10 +492,6 @@ class RunManager:
         except asyncio.CancelledError:
             self._settle(ctx)
             self._set_status("stopped")
-            self._entry()["runId"] = None
-            self._settle_initiators(
-                None if self._run_acked else _reject("stopped", "run cancelled")
-            )
             self._revert_dispatching()
             self._idle.set()
             raise  # no drain, no freeze
@@ -499,25 +500,12 @@ class RunManager:
             message = str(exc) or type(exc).__name__
             if isinstance(exc, StatewireReject):
                 self._freeze(exc.message, exc.payload)
-                self._settle_initiators(None if self._run_acked else exc)
             else:
                 self._freeze(message)
-                self._settle_initiators(
-                    None if self._run_acked else _reject("run-error", message)
-                )
             self._revert_dispatching()
             self._drain()
             return
         self._settle(ctx)
-        if self._run_acked:
-            error = None
-        elif isinstance(outcome, RunManager.Error):
-            error = _reject("run-error", "run ended in error")
-        elif isinstance(outcome, RunManager.Stop):
-            error = _reject("stopped", "run stopped before the ack")
-        else:
-            error = None
-        self._settle_initiators(error)
         self._revert_dispatching()
         self._outcome = outcome
         self._drain()
@@ -528,16 +516,6 @@ class RunManager:
             self._task = None
         self._dispatch_record = None
 
-    def _settle_initiators(self, error: StatewireReject | None) -> None:
-        futures, self._run_futures = self._run_futures, []
-        for future in futures:
-            if future.done():
-                continue
-            if error is None:
-                future.set_result(None)
-            else:
-                future.set_exception(error)
-
     def _ack(self) -> None:
         entry = self._entry()
         record = plain(entry["dispatching"])
@@ -545,7 +523,6 @@ class RunManager:
             raise RuntimeError("ack() with no unacked batch")
         self._dispatching = []
         entry["dispatching"] = None
-        self._run_acked = True
 
     def _revert_dispatching(self) -> None:
         taken, self._dispatching = self._dispatching, []
@@ -621,7 +598,6 @@ class RunManager:
     def _freeze(self, message: str, payload: Any = None) -> None:
         self._set_status("error")
         entry = self._entry()
-        entry["runId"] = None
         if isinstance(payload, dict):
             entry["error"] = {**payload, "message": message}
         elif payload is not None:
@@ -761,6 +737,20 @@ class RunManager:
         if not e.anchor_meta["onActiveBranch"]:
             raise _reject("wrong-anchor", f"anchor {e.anchor} is off the active branch")
 
+    def _check_rewind_anchor(self, params: Any, source_meta: dict[str, Any]) -> None:
+        anchor = params.get("runAnchorMessageId", _ABSENT)
+        if anchor is _ABSENT:
+            raise _reject("invalid-message", "runAnchorMessageId is required")
+        if anchor is not None and not isinstance(anchor, str):
+            raise _reject(
+                "invalid-message", "runAnchorMessageId must be an id or null"
+            )
+        if anchor != source_meta["parentId"]:
+            raise _reject(
+                "wrong-anchor",
+                f"runAnchorMessageId {anchor!r} is not the source's parent",
+            )
+
     # ─── Queue mutations ────────────────────────────────────
 
     def _stamped(self, message: dict[str, Any], meta: Any) -> dict[str, Any]:
@@ -829,16 +819,28 @@ class RunManager:
             return self._park_dispatched_edit(e)
         if e.source_meta is not None:
             raise _reject("duplicate-id", f"message id {e.message_id} is already used")
+        entry = self._entry()
+        live_run_id = plain(entry["runId"]) if entry is not None else None
         if e.anchor is _ABSENT:
-            raise _reject("invalid-message", "anchorMessageId is required")
-        self._check_anchor(e)
+            if live_run_id is None:
+                raise _reject("invalid-message", "runAnchorMessageId is required")
+        else:
+            self._check_anchor(e)
         if self._dispatchable(e.lane):
             self._stage_dispatch(e)
         else:
             self._insert_new(e.lane, e.message, e.params, e.meta)
             if e.lane == "steerQueue":
                 fx.steer_added = True
-        fx.staged_sends.append((e.future, e.ack))
+        if live_run_id is None:
+            self._ensure_entry()["runId"] = e.run_id
+        # A mint racing a live run merges into it; settle carries the surviving id.
+        result = (
+            {"runId": live_run_id}
+            if live_run_id is not None and e.anchor is not _ABSENT
+            else None
+        )
+        fx.staged_sends.append((e.future, e.ack, result))
         return _PARKED
 
     def _apply_move(self, e: _Send, fx: _Effects) -> Any:
@@ -880,6 +882,7 @@ class RunManager:
                 e.source_meta["parentId"],
                 e.ack,
                 e.future,
+                e.run_id,
             )
         )
         return _PARKED
@@ -931,6 +934,7 @@ class RunManager:
                 e.source_meta["parentId"],
                 e.ack,
                 e.future,
+                e.run_id,
             )
         )
         return _PARKED
@@ -943,6 +947,7 @@ class RunManager:
                 e.source_meta["parentId"],
                 e.ack,
                 e.future,
+                e.run_id,
                 root_meta=e.meta,
             )
         )
@@ -959,13 +964,14 @@ class RunManager:
     ) -> Any:
         if not isinstance(params, dict):
             raise _reject("invalid-message", "params must be an object")
+        run_id = _run_id_of(params)
         has_message = "message" in params
         has_message_id = "messageId" in params
         if has_message == has_message_id:
             raise _reject(
                 "invalid-message", "exactly one of message and messageId is required"
             )
-        anchor = params.get("anchorMessageId", _ABSENT)
+        anchor = params.get("runAnchorMessageId", _ABSENT)
         anchor_meta: dict[str, Any] | None = None
         thread_empty = False
         if anchor is None:
@@ -975,7 +981,7 @@ class RunManager:
         elif anchor is not _ABSENT:
             if not isinstance(anchor, str):
                 raise _reject(
-                    "invalid-message", "anchorMessageId must be an id or null"
+                    "invalid-message", "runAnchorMessageId must be an id or null"
                 )
             anchor_meta = await self._thread.get_message_meta(anchor)
         if not has_message:
@@ -991,6 +997,7 @@ class RunManager:
                     None,
                     None,
                     ack,
+                    run_id=run_id,
                     anchor=anchor,
                     anchor_meta=anchor_meta,
                     thread_empty=thread_empty,
@@ -1007,6 +1014,7 @@ class RunManager:
                 source_meta,
                 meta,
                 ack,
+                run_id=run_id,
                 anchor=anchor,
                 anchor_meta=anchor_meta,
                 thread_empty=thread_empty,
@@ -1043,6 +1051,7 @@ class RunManager:
         self, params: Any, *, meta: Any = None, ack: Callable[[], None]
     ) -> Any:
         self._check_rewind_gate("run/edit")
+        run_id = _run_id_of(params)
         source_id = params.get("sourceId") if isinstance(params, dict) else None
         if not isinstance(source_id, str):
             raise _reject("invalid-message", "sourceId must be a string")
@@ -1053,6 +1062,7 @@ class RunManager:
             raise _reject(
                 "capability-missing", "the assistant-edit capability is not enabled"
             )
+        self._check_rewind_anchor(params, source_meta)
         message = self._validated_message(
             params.get("message") if isinstance(params, dict) else None
         )
@@ -1061,12 +1071,15 @@ class RunManager:
             and await self._thread.get_message_meta(message["id"]) is not None
         ):
             raise _reject("duplicate-id", f"message id {message['id']} is already used")
-        return await self._stage(_Edit(source_id, source_meta, message, meta, ack))
+        return await self._stage(
+            _Edit(source_id, source_meta, message, meta, ack, run_id)
+        )
 
     async def reload(
         self, params: Any, *, meta: Any = None, ack: Callable[[], None]
     ) -> Any:
         self._check_rewind_gate("run/reload")
+        run_id = _run_id_of(params)
         source_id = params.get("sourceId") if isinstance(params, dict) else None
         if not isinstance(source_id, str):
             raise _reject("invalid-message", "sourceId must be a string")
@@ -1075,6 +1088,7 @@ class RunManager:
             raise _reject("unknown-id", f"message {source_id} is unknown")
         if source_meta["role"] != "assistant":
             raise _reject("invalid-message", "sourceId must name an assistant message")
+        self._check_rewind_anchor(params, source_meta)
         if source_meta["parentId"] is not None:
             parent = await self._thread.get_message_meta(source_meta["parentId"])
             if (
@@ -1086,7 +1100,7 @@ class RunManager:
                     "capability-missing",
                     "the assistant-continuation capability is not enabled",
                 )
-        return await self._stage(_Reload(source_meta, meta, ack))
+        return await self._stage(_Reload(source_meta, meta, ack, run_id))
 
     async def stop(self, params: Any = None, *, ack: Callable[[], None]) -> Any:
         if params is not None and not isinstance(params, dict):
@@ -1097,7 +1111,7 @@ class RunManager:
         status = self._status()
         if status != "running":
             raise _reject("wrong-state", f"run/stop is rejected in {status}")
-        run_id = (params or {}).get("runId")
+        run_id = _run_id_of(params)
         if run_id != plain(self._entry()["runId"]):
             raise _reject(
                 "wrong-state", f"runId {run_id!r} does not name the live run"