harness-sdk-python 0.5.0__tar.gz → 0.7.0__tar.gz

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/.gitignore

@@ -20,3 +20,4 @@ __pycache__
 # agentdoc mounted docs
 /d[0-9]*.md
 /doc_*.md
+apps/docs/.docs

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: harness-sdk-python
-Version: 0.5.0
+Version: 0.7.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
@@ -23,7 +23,7 @@ class MyHost(Statewire):
         self.runs = RunManager(
             state=self.state,
             start=self._start,
-            get_message_meta=self._get_message_meta,
+            thread=self._thread,
             create_task=self.create_task,
             capabilities=("rewind",),
         )

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/README.md

@@ -11,7 +11,7 @@ class MyHost(Statewire):
         self.runs = RunManager(
             state=self.state,
             start=self._start,
-            get_message_meta=self._get_message_meta,
+            thread=self._thread,
             create_task=self.create_task,
             capabilities=("rewind",),
         )

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/pyproject.toml

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

harness_sdk_python-0.7.0/src/harness_sdk/__init__.py

@@ -0,0 +1,4 @@
+from .linear_thread import linear_thread
+from .run_manager import RunManager
+
+__all__ = ["RunManager", "linear_thread"]

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/src/harness_sdk/fenced_postgres.py

@@ -7,7 +7,7 @@ try:
     from langchain_core.runnables import RunnableConfig
     from langgraph.checkpoint.base import SerializerProtocol
     from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver, _ainternal
-    from psycopg import AsyncPipeline, errors
+    from psycopg import AsyncConnection, AsyncPipeline, errors
     from psycopg.pq import TransactionStatus
     from psycopg.cursor_async import AsyncCursor
     from psycopg.rows import DictRow, dict_row
@@ -126,6 +126,57 @@ class AsyncFencedPostgresSaver(AsyncPostgresSaver):
         self.on_fence_lost = on_fence_lost
         self._fence_lost_notified = False
 
+    @staticmethod
+    async def _validate_and_bump(
+        cur: "AsyncCursor[DictRow]",
+        thread_id: str,
+        *,
+        create_fence_table: bool,
+        fence_table: str,
+    ) -> int:
+        if create_fence_table:
+            await cur.execute(_create_sql(fence_table))
+            await cur.execute(_create_fn_sql(fence_table))
+        else:
+            await cur.execute(
+                "SELECT to_regclass(%s) AS tbl, to_regprocedure(%s) AS fn",
+                (fence_table, f"{_assert_fn(fence_table)}(text, bigint)"),
+            )
+            row = await cur.fetchone()
+            if row["tbl"] is None:
+                raise _missing_fence_error(f"fence table {fence_table!r}")
+            if row["fn"] is None:
+                raise _missing_fence_error(
+                    f"fence function {_assert_fn(fence_table)!r}"
+                )
+        await cur.execute(_bump_sql(fence_table), (thread_id,))
+        return (await cur.fetchone())["epoch"]
+
+    @classmethod
+    async def bump_epoch(
+        cls,
+        conn: "AsyncConnection[Any]",
+        thread_id: str,
+        *,
+        create_fence_table: bool,
+        fence_table: str = DEFAULT_FENCE_TABLE,
+    ) -> int:
+        """Bump ``thread_id``'s epoch inside the caller's open transaction; the epoch is effective only once the caller commits, which must happen before it is used for writes."""
+        _require_thread_id(thread_id)
+        _require_fence_table(fence_table)
+        if conn.info.transaction_status != TransactionStatus.INTRANS:
+            raise RuntimeError(
+                "bump_epoch requires a connection with a transaction in "
+                "progress; use acquire for idle connections"
+            )
+        async with conn.cursor(binary=True, row_factory=dict_row) as cur:
+            return await cls._validate_and_bump(
+                cur,
+                thread_id,
+                create_fence_table=create_fence_table,
+                fence_table=fence_table,
+            )
+
     @classmethod
     async def acquire(
         cls,
@@ -149,23 +200,12 @@ class AsyncFencedPostgresSaver(AsyncPostgresSaver):
                 c.transaction(),
                 c.cursor(binary=True, row_factory=dict_row) as cur,
             ):
-                if create_fence_table:
-                    await cur.execute(_create_sql(fence_table))
-                    await cur.execute(_create_fn_sql(fence_table))
-                else:
-                    await cur.execute(
-                        "SELECT to_regclass(%s) AS tbl, to_regprocedure(%s) AS fn",
-                        (fence_table, f"{_assert_fn(fence_table)}(text, bigint)"),
-                    )
-                    row = await cur.fetchone()
-                    if row["tbl"] is None:
-                        raise _missing_fence_error(f"fence table {fence_table!r}")
-                    if row["fn"] is None:
-                        raise _missing_fence_error(
-                            f"fence function {_assert_fn(fence_table)!r}"
-                        )
-                await cur.execute(_bump_sql(fence_table), (thread_id,))
-                epoch = (await cur.fetchone())["epoch"]
+                epoch = await cls._validate_and_bump(
+                    cur,
+                    thread_id,
+                    create_fence_table=create_fence_table,
+                    fence_table=fence_table,
+                )
         if pipe is not None:
             await pipe.sync()
         return cls(

harness_sdk_python-0.7.0/src/harness_sdk/linear_thread.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class LinearThread:
+    _messages: Callable[[], list[dict[str, Any]]]
+    _role: Callable[[dict[str, Any]], str]
+
+    async def get_message_meta(self, message_id: str | None) -> dict[str, Any] | None:
+        items = self._messages()
+        if message_id is None:
+            return {"isLeaf": not items}
+        for index, message in enumerate(items):
+            if message.get("id") == message_id:
+                return {
+                    "parentId": items[index - 1].get("id") if index > 0 else None,
+                    "role": self._role(message),
+                    "isLeaf": index == len(items) - 1,
+                    "onActiveBranch": True,
+                }
+        return None
+
+    async def get_leaf_message_id(self) -> str | None:
+        items = self._messages()
+        return items[-1].get("id") if items else None
+
+    async def get_message_child_id(self, parent_id: str) -> str | None:
+        """The id of the first non-tool message after parent_id; None when parent_id is unknown or only tools follow."""
+        items = self._messages()
+        index = next(
+            (i for i, m in enumerate(items) if m.get("id") == parent_id), None
+        )
+        if index is None:
+            return None
+        for message in items[index + 1 :]:
+            if message.get("type") != "tool":
+                return message.get("id")
+        return None
+
+
+def linear_thread(
+    *,
+    messages: Callable[[], list[dict[str, Any]]],
+    role: Callable[[dict[str, Any]], str],
+) -> LinearThread:
+    """RunManager thread projection over a linear message list: ``messages`` returns the current list, ``role`` maps a message to its role."""
+    if not callable(messages):
+        raise TypeError("messages must be callable")
+    if not callable(role):
+        raise TypeError("role must be callable")
+    return LinearThread(messages, role)

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/src/harness_sdk/run_manager.py

@@ -19,7 +19,7 @@ initiators settle rejected (``stopped`` or the failure).
 import asyncio
 import uuid
 from dataclasses import dataclass, field
-from typing import Any, Awaitable, Callable, Iterable
+from typing import Any, Awaitable, Callable, Iterable, Protocol
 
 from statewire import StatewireReject
 from statewire.state import plain
@@ -51,10 +51,6 @@ _TRIGGERS = (
 
 _DECISIONS = ("approve", "reject", "edit", "respond")
 
-# Called with None it answers for the thread root: isLeaf True iff the thread is empty.
-GetMessageMeta = Callable[[str | None], Awaitable[dict[str, Any] | None]]
-
-
 def _reject(reason: str, message: str) -> StatewireReject:
     return StatewireReject(message, payload={"reason": reason})
 
@@ -129,7 +125,6 @@ class _Rewind:
     ack: Callable[[], None]
     future: "asyncio.Future[Any]"
     root_meta: Any = None
-    acked: bool = False
 
 
 @dataclass
@@ -138,21 +133,38 @@ class _Effects:
     new_added: bool = False
     continue_requested: bool = False
     continue_meta: Any = None
-    staged_sends: list[tuple[str, "asyncio.Future[Any]"]] = field(default_factory=list)
+    staged_sends: list[tuple[str, "asyncio.Future[Any]", Callable[[], None]]] = field(
+        default_factory=list
+    )
     continues: list["asyncio.Future[Any]"] = field(default_factory=list)
 
 
 class RunManager:
+    class Thread(Protocol):
+        """The thread projection RunManager reads; the host owns the tree."""
+
+        async def get_message_meta(
+            self, message_id: str | None
+        ) -> dict[str, Any] | None:
+            """Meta for a known id ({parentId, role, isLeaf, onActiveBranch}), None for an unknown one; a None id probes the root ({isLeaf})."""
+            ...
+
+        async def get_leaf_message_id(self) -> str | None:
+            """The active branch's current leaf id, None while the thread is empty."""
+            ...
+
     def __init__(
         self,
         *,
         state: Any,
         run: Callable[["RunManager.RunContext"], Awaitable[Any]],
-        get_message_meta: GetMessageMeta,
+        thread: "RunManager.Thread",
         create_task: Callable[[Any], "asyncio.Task[Any]"],
         schedule: Callable[[Callable[[], None]], None],
         capabilities: Iterable[str] = (),
         max_queued: int = 50,
+        prepare_message: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+        prepare_input: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
     ) -> None:
         caps = frozenset(capabilities)
         unknown = caps - _CAPABILITIES
@@ -164,11 +176,13 @@ class RunManager:
             raise ValueError("max_queued must be >= 1")
         self._state = state
         self._run = run
-        self._get_message_meta = get_message_meta
+        self._thread = thread
         self._capabilities = caps
         self._create_task = create_task
         self._schedule = schedule
         self._max_queued = max_queued
+        self._prepare_message = prepare_message
+        self._prepare_input = prepare_input
         self._task: "asyncio.Task[Any] | None" = None
         self._ctx: "RunManager.RunContext | None" = None
         self._dispatched_ids: tuple[str, ...] = ()
@@ -179,6 +193,10 @@ class RunManager:
         self._stop_reason: str | None = None
         self._staged_rewinds: list[_Rewind] = []
         self._dispatching: list[tuple[str, dict[str, Any]]] = []
+        # Deferred covering acks: they only ride an envelope whose state shows
+        # the command's effect (message-ack append, or the revert re-insert).
+        self._deferred_acks: dict[str, Callable[[], None]] = {}
+        self._dispatch_ack: Callable[[], None] | None = None
         self._run_acked = True
         self._leaf_confirmed: str | None = None
         self._send_futures: list["asyncio.Future[Any]"] = []
@@ -294,7 +312,7 @@ class RunManager:
                     rollback_to=rewind.rollback_to,
                     root_meta=rewind.root_meta,
                 )
-                rewind.ack()
+                self._dispatch_ack = rewind.ack
                 if not rewind.future.done():
                     self._run_futures.append(rewind.future)
             elif outcome is not None:
@@ -304,16 +322,15 @@ 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 rewind in self._staged_rewinds:
-                if not rewind.acked:
-                    rewind.ack()
-                    rewind.acked = True
         dispatching = {item["id"] for _, item in self._dispatching}
-        for message_id, future in fx.staged_sends:
+        for message_id, future, ack in fx.staged_sends:
             if message_id in dispatching:
+                self._deferred_acks[message_id] = ack
                 self._send_futures.append(future)
-            elif not future.done():
-                future.set_result(None)
+            else:
+                ack()
+                if not future.done():
+                    future.set_result(None)
         for future in fx.continues:
             if not future.done():
                 future.set_result(None)
@@ -480,6 +497,7 @@ class RunManager:
                     "run settled without acking its messages (call ctx.ack_messages())"
                 )
         except asyncio.CancelledError:
+            await self._pull_leaf()
             self._settle(ctx)
             self._set_status("stopped")
             self._entry()["runId"] = None
@@ -488,6 +506,7 @@ class RunManager:
             self._idle.set()
             raise  # no drain, no freeze
         except Exception as exc:
+            await self._pull_leaf()
             self._settle(ctx)
             message = str(exc) or type(exc).__name__
             if isinstance(exc, StatewireReject):
@@ -499,6 +518,7 @@ class RunManager:
             self._revert_dispatching()
             self._drain()
             return
+        await self._pull_leaf()
         self._settle(ctx)
         if isinstance(outcome, RunManager.Error):
             error = _reject("run-error", "run ended in error")
@@ -511,11 +531,18 @@ class RunManager:
         self._outcome = outcome
         self._drain()
 
+    async def _pull_leaf(self) -> None:
+        # An unacked end reverts instead of recording a leaf.
+        if self._dispatching or not self._run_acked:
+            return
+        self._entry()["runLeafMessageId"] = await self._thread.get_leaf_message_id()
+
     def _settle(self, ctx: "RunManager.RunContext") -> None:
         if self._ctx is ctx:
             self._ctx = None
             self._task = None
         self._dispatch_record = None
+        self._dispatch_ack = None
 
     def _settle_initiators(self, error: StatewireReject | None) -> None:
         futures, self._run_futures = self._run_futures, []
@@ -534,6 +561,13 @@ class RunManager:
                 future.set_result(None)
 
     def _ack_messages(self) -> None:
+        if self._dispatch_ack is not None:
+            self._dispatch_ack()
+            self._dispatch_ack = None
+        for _, item in self._dispatching:
+            ack = self._deferred_acks.pop(item["id"], None)
+            if ack is not None:
+                ack()
         self._dispatching = []
         self._run_acked = True
         self._leaf_confirmed = plain(self._entry()["runLeafMessageId"])
@@ -550,6 +584,10 @@ class RunManager:
             front = [item for taken_lane, item in taken if taken_lane == lane]
             if front:
                 entry[lane] = front + self._lane_items(lane)
+        for _, item in taken:
+            ack = self._deferred_acks.pop(item["id"], None)
+            if ack is not None:
+                ack()
         ids = {item["id"] for _, item in taken}
         self._dispatched_ids = tuple(id for id in self._dispatched_ids if id not in ids)
         if plain(entry["runLeafMessageId"]) in ids:
@@ -585,7 +623,22 @@ class RunManager:
 
     # ─── Message and placement validation ───────────────────
 
+    def _prepared(
+        self,
+        hook: Callable[[dict[str, Any]], dict[str, Any]] | None,
+        name: str,
+        value: Any,
+    ) -> Any:
+        # Non-dict input skips the hook and falls through to validation's reject.
+        if hook is None or not isinstance(value, dict):
+            return value
+        result = hook(value)
+        if not isinstance(result, dict):
+            raise _reject("invalid-message", f"{name} must return an object")
+        return result
+
     def _validated_message(self, message: Any) -> dict[str, Any]:
+        message = self._prepared(self._prepare_message, "prepare_message", message)
         if not isinstance(message, dict):
             raise _reject("invalid-message", "message must be an object")
         if not isinstance(message.get("id"), str) or message["id"] == "":
@@ -772,8 +825,7 @@ class RunManager:
             raise _reject("invalid-message", "anchorMessageId is required")
         self._check_anchor(e)
         self._insert_new(e.lane, e.message, e.params, e.meta)
-        fx.staged_sends.append((e.message_id, e.future))
-        e.ack()
+        fx.staged_sends.append((e.message_id, e.future, e.ack))
         fx.new_added = True
         if e.lane == "steerQueue":
             fx.steer_added = True
@@ -907,7 +959,7 @@ class RunManager:
         anchor_meta: dict[str, Any] | None = None
         thread_empty = False
         if anchor is None:
-            root = await self._get_message_meta(None)
+            root = await self._thread.get_message_meta(None)
             assert root is not None, "get_message_meta(None) must answer for the root"
             thread_empty = bool(root["isLeaf"])
         elif anchor is not _ABSENT:
@@ -915,7 +967,7 @@ class RunManager:
                 raise _reject(
                     "invalid-message", "anchorMessageId must be an id or null"
                 )
-            anchor_meta = await self._get_message_meta(anchor)
+            anchor_meta = await self._thread.get_message_meta(anchor)
         if not has_message:
             message_id = params["messageId"]
             if not isinstance(message_id, str):
@@ -935,7 +987,7 @@ class RunManager:
                 )
             )
         message = self._validated_message(params["message"])
-        source_meta = await self._get_message_meta(message["id"])
+        source_meta = await self._thread.get_message_meta(message["id"])
         return await self._stage(
             _Send(
                 lane,
@@ -984,7 +1036,7 @@ class RunManager:
         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")
-        source_meta = await self._get_message_meta(source_id)
+        source_meta = await self._thread.get_message_meta(source_id)
         if source_meta is None:
             raise _reject("unknown-id", f"message {source_id} is unknown")
         if source_meta["role"] != "user" and "assistant-edit" not in self._capabilities:
@@ -996,7 +1048,7 @@ class RunManager:
         )
         if (
             message["id"] != source_id
-            and await self._get_message_meta(message["id"]) is not None
+            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))
@@ -1008,13 +1060,13 @@ class RunManager:
         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")
-        source_meta = await self._get_message_meta(source_id)
+        source_meta = await self._thread.get_message_meta(source_id)
         if source_meta is None:
             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")
         if source_meta["parentId"] is not None:
-            parent = await self._get_message_meta(source_meta["parentId"])
+            parent = await self._thread.get_message_meta(source_meta["parentId"])
             if (
                 parent is not None
                 and parent["role"] == "assistant"
@@ -1049,6 +1101,7 @@ class RunManager:
         return await entry.future
 
     def _validated_response(self, request_type: str, response: Any) -> dict[str, Any]:
+        response = self._prepared(self._prepare_input, "prepare_input", response)
         if not isinstance(response, dict):
             raise _reject("invalid-message", "response must be an object")
         if request_type == "tool-call":
@@ -1230,14 +1283,6 @@ class RunManager:
             self._ensure_active()
             self._manager._ack_messages()
 
-        def set_leaf_message_id(self, message_id: str) -> None:
-            self._ensure_active()
-            if not isinstance(message_id, str) or message_id == "":
-                raise ValueError("message_id must be a non-empty string")
-            if self._manager._dispatching or not self._manager._run_acked:
-                raise RuntimeError("ack_messages must precede set_leaf_message_id")
-            self._manager._entry()["runLeafMessageId"] = message_id
-
         def set_recovery_state(self, value: Any) -> None:
             self._ensure_active()
             record = self._manager._dispatch_record

{harness_sdk_python-0.5.0 → harness_sdk_python-0.7.0}/tests/run_helpers.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from statewire import Statewire, command
-from statewire_helpers import apply_ops, post_command, statewire_client, stream_of
+from statewire_helpers import apply_ops, attach, post_command, statewire_client, stream_of
 
 from harness_sdk import RunManager
 
@@ -32,6 +32,7 @@ class Script:
     def __init__(self) -> None:
         self.calls: asyncio.Queue[Call] = asyncio.Queue()
         self.thread: dict[str, dict[str, Any]] = {}
+        self.leaf: str | None = None
 
     async def run(self, ctx: RunManager.RunContext) -> Any:
         call = Call(ctx, asyncio.get_running_loop().create_future())
@@ -43,6 +44,9 @@ class Script:
             return {"isLeaf": not self.thread}
         return self.thread.get(message_id)
 
+    async def get_leaf_message_id(self) -> str | None:
+        return self.leaf
+
     async def next_call(self, timeout: float = 5) -> Call:
         return await asyncio.wait_for(self.calls.get(), timeout)
 
@@ -55,7 +59,14 @@ def _meta(params: Any) -> Any:
     return params.pop("meta", None) if isinstance(params, dict) else None
 
 
-def make_host(script: Script, capabilities=(), initial_runs=None, max_queued=50):
+def make_host(
+    script: Script,
+    capabilities=(),
+    initial_runs=None,
+    max_queued=50,
+    prepare_message=None,
+    prepare_input=None,
+):
     class Host(Statewire):
         live: "Host | None" = None
 
@@ -67,11 +78,13 @@ def make_host(script: Script, capabilities=(), initial_runs=None, max_queued=50)
             self.runs = RunManager(
                 state=self.state,
                 run=script.run,
-                get_message_meta=script.get_message_meta,
+                thread=script,
                 create_task=self.create_task,
                 schedule=self.schedule,
                 capabilities=capabilities,
                 max_queued=max_queued,
+                prepare_message=prepare_message,
+                prepare_input=prepare_input,
             )
             yield
 
@@ -114,20 +127,47 @@ class RunDriver:
     """One SSE-attached statewire client: sends commands, mirrors the state
     replica from ops, and returns each command's settled response."""
 
-    def __init__(self, client, stream) -> None:
+    def __init__(self, client, stream, app=None) -> None:
         self._client = client
         self._stream = stream
+        self._app = app
+        self._side_seqs: dict[str, int] = {}
         self._seq = 0
         self._acked = 0
         self._res: dict[int, list[dict[str, Any]]] = {}
+        self._posts: list["asyncio.Task[None]"] = []
         self.replica: dict[str, Any] = {}
         self.envelopes: list[dict[str, Any]] = []
 
+    def _spawn(self, body: dict[str, Any], seq: int) -> None:
+        async def _post() -> None:
+            response = await post_command(self._client, body, seq=seq)
+            assert response.status_code == 200, response.text
+
+        self._posts.append(asyncio.create_task(_post()))
+
+    def post(self, method: str, params: Any = None) -> int:
+        """Background POST for a command whose receipt is held until its effect
+        publishes (a dispatching send or rewind); settle via ``res(seq)``."""
+        self._seq += 1
+        body = {"method": method, "params": [] if params is None else [params]}
+        self._spawn(body, self._seq)
+        return self._seq
+
+    async def side(self, method: str, params: Any = None, *, client_id: str = "c2"):
+        """A second client's command: its own seq stream stays admissible while
+        this client's receipt is deferred; its verdicts ride the other stream."""
+        await attach(self._app, client_id=client_id)
+        seq = self._side_seqs[client_id] = self._side_seqs.get(client_id, 0) + 1
+        body = {"method": method, "params": [] if params is None else [params]}
+        response = await post_command(self._client, body, seq=seq, client_id=client_id)
+        assert response.status_code == 200, response.text
+
     async def pump(self, timeout: float = 5) -> None:
         env = await self._stream.next_event(timeout=timeout)
         assert env is not None, "stream ended unexpectedly"
         self.envelopes.append(env)
-        apply_ops(self.replica, env)
+        apply_ops(self.replica, copy.deepcopy(env))
         if "ack" in env:
             self._acked = max(self._acked, env["ack"])
         for rsp in env.get("res", []):
@@ -143,9 +183,9 @@ class RunDriver:
         assert response.status_code == 200, response.text
         return await self.res(seq, terminal=terminal)
 
-    async def batch(self, commands: list[tuple[str, Any]]) -> int:
-        """POST one batch; returns the first member's seq (members are
-        consecutive). Responses via ``res(first + i)``."""
+    def batch(self, commands: list[tuple[str, Any]]) -> int:
+        """Background POST of one batch; returns the first member's seq
+        (members are consecutive). Responses via ``res(first + i)``."""
         first = self._seq + 1
         self._seq += len(commands)
         body = {
@@ -154,8 +194,7 @@ class RunDriver:
                 for method, params in commands
             ]
         }
-        response = await post_command(self._client, body, seq=first)
-        assert response.status_code == 200, response.text
+        self._spawn(body, first)
         return first
 
     async def context(self, value: dict[str, Any]) -> dict[str, Any]:
@@ -218,19 +257,38 @@ class RunDriver:
 
 
 @asynccontextmanager
-async def run_host(script: Script, capabilities=(), initial_runs=None, max_queued=50):
+async def run_host(
+    script: Script,
+    capabilities=(),
+    initial_runs=None,
+    max_queued=50,
+    prepare_message=None,
+    prepare_input=None,
+):
     host_cls = make_host(
         script,
         capabilities=capabilities,
         initial_runs=initial_runs,
         max_queued=max_queued,
+        prepare_message=prepare_message,
+        prepare_input=prepare_input,
     )
     async with statewire_client(host_cls) as (app, client):
         async with stream_of(app) as stream:
             snapshot = await stream.next_event()
-            driver = RunDriver(client, stream)
-            apply_ops(driver.replica, snapshot)
-            yield driver, host_cls
+            driver = RunDriver(client, stream, app)
+            driver.envelopes.append(snapshot)
+            apply_ops(driver.replica, copy.deepcopy(snapshot))
+            try:
+                yield driver, host_cls
+            finally:
+                for task in driver._posts:
+                    task.cancel()
+                for result in await asyncio.gather(
+                    *driver._posts, return_exceptions=True
+                ):
+                    if isinstance(result, AssertionError):
+                        raise result
 
 
 def msg(id: str, text: str | None = None) -> dict[str, Any]: