harness-sdk-python 0.3.0__tar.gz → 0.4.0__tar.gz

{harness_sdk_python-0.3.0 → harness_sdk_python-0.4.0}/.gitignore

@@ -9,6 +9,9 @@ dist-test
 .dev.vars
 *.tsbuildinfo
 .harness-runs
+*.rdb
+.source
+next-env.d.ts
 __pycache__
 .venv
 .pytest_cache

{harness_sdk_python-0.3.0 → harness_sdk_python-0.4.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: harness-sdk-python
-Version: 0.3.0
+Version: 0.4.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.11
-Requires-Dist: statewire<0.4,>=0.3.0
+Requires-Dist: statewire<0.5,>=0.4.0
 Provides-Extra: postgres
 Requires-Dist: langgraph-checkpoint-postgres>=2.0.0; extra == 'postgres'
 Description-Content-Type: text/markdown

{harness_sdk_python-0.3.0 → harness_sdk_python-0.4.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.3.0"
+version = "0.4.0"
 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.3.0,<0.4"]
+dependencies = ["statewire>=0.4.0,<0.5"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]

{harness_sdk_python-0.3.0 → harness_sdk_python-0.4.0}/src/harness_sdk/run_manager.py

@@ -45,7 +45,8 @@ _ENTRY_TYPES = (
 
 _DECISIONS = ("approve", "reject", "edit", "respond")
 
-GetMessageMeta = Callable[[str], Awaitable[dict[str, Any] | None]]
+# 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:
@@ -65,6 +66,9 @@ class _Send:
     meta: dict[str, Any] | None
     caller: StatewireClientHandle | None
     ack: Callable[[], None]
+    anchor: Any = _ABSENT
+    anchor_meta: dict[str, Any] | None = None
+    thread_empty: bool = False
     future: "asyncio.Future[Any]" = field(default_factory=_future)
 
 
@@ -86,6 +90,7 @@ class _Edit:
 @dataclass
 class _Reload:
     source_meta: dict[str, Any]
+    message_id: str
     ack: Callable[[], None]
     future: "asyncio.Future[Any]" = field(default_factory=_future)
 
@@ -114,6 +119,7 @@ class _Rewind:
     rollback_to: Any
     ack: Callable[[], None]
     future: "asyncio.Future[Any]"
+    message_id: str | None = None
     acked: bool = False
 
 
@@ -154,6 +160,7 @@ class RunManager:
         self._task: "asyncio.Task[Any] | None" = None
         self._ctx: "RunManager.StartContext | None" = None
         self._dispatched_ids: tuple[str, ...] = ()
+        self._reload_message_id: str | None = None
         self._dispatch_record: dict[str, Any] | None = None
         self._callers: dict[str, StatewireClientHandle] = {}
         self._intake: list[Any] = []
@@ -161,6 +168,8 @@ class RunManager:
         self._staged_stops: list["asyncio.Future[Any]"] = []
         self._stop_reason: str | None = None
         self._staged_rewinds: list[_Rewind] = []
+        self._entity_futures: dict[str, "asyncio.Future[Any]"] = {}
+        self._run_futures: list["asyncio.Future[Any]"] = []
         self._input_requests: list[dict[str, Any]] = []
         self._input_answers: dict[str, Any] = {}
         self._init_state()
@@ -212,13 +221,18 @@ class RunManager:
             self._staged_stops.clear()
             if isinstance(outcome, RunManager.Complete):
                 self._dispatched_ids = ()
+                self._reload_message_id = None
             if self._staged_rewinds:
                 rewind = self._staged_rewinds.pop(0)
                 self._dispatch(
-                    rewind.type, rewind.messages, rollback_to=rewind.rollback_to
+                    rewind.type,
+                    rewind.messages,
+                    rollback_to=rewind.rollback_to,
+                    message_id=rewind.message_id,
                 )
+                rewind.ack()
                 if not rewind.future.done():
-                    rewind.future.set_result(None)
+                    self._run_futures.append(rewind.future)
             elif outcome is not None:
                 self._settle_outcome(outcome)
             else:
@@ -307,6 +321,7 @@ class RunManager:
         *,
         rollback_to: Any = _ABSENT,
         responses: Any = _ABSENT,
+        message_id: str | None = None,
     ) -> None:
         if type not in _ENTRY_TYPES:
             raise ValueError(f"invalid entry type: {type!r}")
@@ -318,16 +333,20 @@ class RunManager:
         ]
         for message in messages:
             self._callers.pop(message["id"], None)
+        self._adopt_entities(message["id"] for message in messages)
         record: dict[str, Any] = {"type": type, "messages": list(messages)}
         if rollback_to is not _ABSENT:
             record["rollbackTo"] = rollback_to
         if responses is not _ABSENT:
             record["responses"] = responses
+        if message_id is not None:
+            record["messageId"] = message_id
         self._dispatch_record = record
         self._stop_reason = None
         self._state["error"] = None
         if messages:
             self._dispatched_ids = tuple(m["id"] for m in messages)
+        self._reload_message_id = message_id
         self._state["status"] = "running"
         ctx = RunManager.StartContext(
             type=type,
@@ -337,6 +356,7 @@ class RunManager:
             _manager=self,
             _rollback_to=rollback_to,
             _responses=responses,
+            _message_id=message_id,
         )
         self._ctx = ctx
         self._task = self._create_task(self._run(ctx))
@@ -359,10 +379,21 @@ class RunManager:
                 )
         except Exception as exc:
             self._settle(ctx)
-            self._freeze(str(exc) or type(exc).__name__)
+            message = str(exc) or type(exc).__name__
+            if isinstance(exc, StatewireReject):
+                self._freeze(exc.message, exc.payload)
+                self._settle_entities(exc)
+            else:
+                self._freeze(message)
+                self._settle_entities(_reject("run-error", message))
             self._drain()
             return
         self._settle(ctx)
+        self._settle_entities(
+            _reject("run-error", "run ended in error")
+            if isinstance(outcome, RunManager.Error)
+            else None
+        )
         self._outcome = outcome
         self._drain()
 
@@ -372,6 +403,22 @@ class RunManager:
             self._task = None
         self._dispatch_record = None
 
+    def _settle_entities(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 _adopt_entities(self, ids: Iterable[str]) -> None:
+        for id in ids:
+            future = self._entity_futures.pop(id, None)
+            if future is not None:
+                self._run_futures.append(future)
+
     def _pop_dispatchable(self) -> bool:
         steer = self._lane_items("steerQueue")
         if steer:
@@ -385,9 +432,14 @@ class RunManager:
             return True
         return False
 
-    def _freeze(self, message: str) -> None:
+    def _freeze(self, message: str, payload: Any = None) -> None:
         self._state["status"] = "error"
-        self._state["error"] = {"message": message}
+        if isinstance(payload, dict):
+            self._state["error"] = {**payload, "message": message}
+        elif payload is not None:
+            self._state["error"] = {"message": message, "payload": payload}
+        else:
+            self._state["error"] = {"message": message}
 
     # ─── Message and placement validation ───────────────────
 
@@ -468,6 +520,24 @@ class RunManager:
             raise _reject("not-adjacent", "insertAfter and insertBefore are not adjacent")
         return slot
 
+    def _check_anchor(self, e: _Send) -> None:
+        if e.anchor is _ABSENT:
+            return
+        if e.anchor is None:
+            if not e.thread_empty:
+                raise _reject("wrong-anchor", "a null anchor asserts an empty thread")
+            return
+        if self._lane_of(e.anchor) is not None:
+            return
+        if e.anchor in self._dispatched_ids or e.anchor == self._reload_message_id:
+            return
+        if e.anchor_meta is None:
+            raise _reject("unknown-id", f"anchor {e.anchor} names nothing")
+        if not e.anchor_meta["onActiveBranch"]:
+            raise _reject(
+                "wrong-anchor", f"anchor {e.anchor} is off the active branch"
+            )
+
     # ─── Queue mutations ────────────────────────────────────
 
     def _stamped(self, message: dict[str, Any]) -> dict[str, Any]:
@@ -543,6 +613,7 @@ class RunManager:
             return self._apply_move(e, fx)
         current = self._lane_of(e.message_id)
         if current is not None:
+            self._check_anchor(e)
             with self._caller_stamp(e.message_id, e.caller):
                 self._place(e.lane, current, e.message, e.params)
             if e.lane == "steerQueue":
@@ -550,16 +621,21 @@ class RunManager:
             return None
         if e.message_id in self._dispatched_ids:
             return self._park_dispatched_edit(e)
-        if e.meta is not None:
+        if e.meta is not None or e.message_id == self._reload_message_id:
             raise _reject(
                 "duplicate-id", f"message id {e.message_id} is already used"
             )
+        if e.anchor is _ABSENT:
+            raise _reject("invalid-message", "anchorMessageId is required")
+        self._check_anchor(e)
         with self._caller_stamp(e.message_id, e.caller):
             self._insert_new(e.lane, e.message, e.params)
+        self._entity_futures[e.message_id] = e.future
+        e.ack()
         fx.new_added = True
         if e.lane == "steerQueue":
             fx.steer_added = True
-        return None
+        return _PARKED
 
     def _apply_move(self, e: _Send, fx: _Effects) -> Any:
         current = self._lane_of(e.message_id)
@@ -592,6 +668,7 @@ class RunManager:
             raise _reject("unknown-id", f"message {e.message_id} is unknown")
         if self._task is not None and not e.meta["isLeaf"]:
             raise _reject("not-leaf", "only the leaf may be edited during a run")
+        self._check_anchor(e)
         with self._caller_stamp(e.message_id, e.caller):
             self._staged_rewinds.append(
                 _Rewind(
@@ -608,6 +685,11 @@ class RunManager:
         self._state[lane] = [
             item for item in self._lane_items(lane) if item["id"] != e.message_id
         ]
+        entity = self._entity_futures.pop(e.message_id, None)
+        if entity is not None and not entity.done():
+            entity.set_exception(
+                _reject("removed", f"message {e.message_id} was removed from the queue")
+            )
         return None
 
     def _apply_input(self, e: _Input) -> Any:
@@ -653,8 +735,23 @@ class RunManager:
 
     def _apply_reload(self, e: _Reload) -> Any:
         self._check_leaf_lanes(e.source_meta, "run/reload")
+        if (
+            self._lane_of(e.message_id) is not None
+            or e.message_id in self._dispatched_ids
+            or e.message_id == self._reload_message_id
+        ):
+            raise _reject(
+                "duplicate-id", f"message id {e.message_id} is already used"
+            )
         self._staged_rewinds.append(
-            _Rewind("message-reload", [], e.source_meta["parentId"], e.ack, e.future)
+            _Rewind(
+                "message-reload",
+                [],
+                e.source_meta["parentId"],
+                e.ack,
+                e.future,
+                message_id=e.message_id,
+            )
         )
         return _PARKED
 
@@ -684,17 +781,50 @@ class RunManager:
             raise _reject(
                 "invalid-message", "exactly one of message and messageId is required"
             )
+        anchor = params.get("anchorMessageId", _ABSENT)
+        anchor_meta: dict[str, Any] | None = None
+        thread_empty = False
+        if anchor is None:
+            root = await self._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:
+            if not isinstance(anchor, str):
+                raise _reject("invalid-message", "anchorMessageId must be an id or null")
+            anchor_meta = await self._get_message_meta(anchor)
         if not has_message:
             message_id = params["messageId"]
             if not isinstance(message_id, str):
                 raise _reject("invalid-message", "messageId must be a string")
             return await self._stage(
-                _Send(lane, params, None, message_id, None, None, ack)
+                _Send(
+                    lane,
+                    params,
+                    None,
+                    message_id,
+                    None,
+                    None,
+                    ack,
+                    anchor=anchor,
+                    anchor_meta=anchor_meta,
+                    thread_empty=thread_empty,
+                )
             )
         message = self._validated_message(params["message"])
         meta = await self._get_message_meta(message["id"])
         return await self._stage(
-            _Send(lane, params, message, message["id"], meta, caller, ack)
+            _Send(
+                lane,
+                params,
+                message,
+                message["id"],
+                meta,
+                caller,
+                ack,
+                anchor=anchor,
+                anchor_meta=anchor_meta,
+                thread_empty=thread_empty,
+            )
         )
 
     async def enqueue(
@@ -766,6 +896,11 @@ 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")
+        message_id = params.get("messageId")
+        if not isinstance(message_id, str) or message_id == "":
+            raise _reject("invalid-message", "messageId must be a non-empty string")
+        if await self._get_message_meta(message_id) is not None:
+            raise _reject("duplicate-id", f"message id {message_id} is already used")
         meta = await self._get_message_meta(source_id)
         if meta is None:
             raise _reject("unknown-id", f"message {source_id} is unknown")
@@ -783,7 +918,7 @@ class RunManager:
                     "capability-missing",
                     "the assistant-continuation capability is not enabled",
                 )
-        return await self._stage(_Reload(meta, ack))
+        return await self._stage(_Reload(meta, message_id, ack))
 
     async def stop(self, params: Any = None, *, ack: Callable[[], None]) -> Any:
         if params is not None and not isinstance(params, dict):
@@ -917,11 +1052,20 @@ class RunManager:
         _manager: "RunManager"
         _rollback_to: Any
         _responses: Any
+        _message_id: str | None
 
         @property
         def stop_reason(self) -> str | None:
             return self._manager._stop_reason
 
+        @property
+        def message_id(self) -> str:
+            if self._message_id is None:
+                raise AttributeError(
+                    "message_id is only present on message-reload entries"
+                )
+            return self._message_id
+
         @property
         def has_rollback(self) -> bool:
             return self._rollback_to is not _ABSENT
@@ -956,6 +1100,7 @@ class RunManager:
             self._manager._state["steerQueue"] = []
             for item in items:
                 self._manager._callers.pop(item["id"], None)
+            self._manager._adopt_entities(item["id"] for item in items)
             return tuple(
                 {k: v for k, v in item.items() if k != "caller"} for item in items
             )

{harness_sdk_python-0.3.0 → harness_sdk_python-0.4.0}/tests/run_helpers.py

@@ -35,7 +35,9 @@ class Script:
         self.calls.put_nowait(call)
         return await call.outcome
 
-    async def get_message_meta(self, message_id: str) -> dict[str, Any] | None:
+    async def get_message_meta(self, message_id: str | None) -> dict[str, Any] | None:
+        if message_id is None:
+            return {"isLeaf": not self.thread}
         return self.thread.get(message_id)
 
     async def next_call(self, timeout: float = 5) -> Call:
@@ -202,6 +204,11 @@ def msg(id: str, text: str | None = None) -> dict[str, Any]:
     return {"id": id, "role": "user", "parts": [{"type": "text", "text": text or id}]}
 
 
+def add(id: str, text: str | None = None, *, anchor: str | None = None, **fields: Any) -> dict[str, Any]:
+    """Params for an enqueue/steer add: message + the required branch anchor."""
+    return {"message": msg(id, text), "anchorMessageId": anchor, **fields}
+
+
 def assert_rejected(rsp: dict[str, Any], reason: str) -> None:
     assert rsp["type"] == "rejected", rsp
     assert rsp["payload"] == {"reason": reason}, rsp

{harness_sdk_python-0.3.0 → harness_sdk_python-0.4.0}/tests/test_batches.py

@@ -5,7 +5,7 @@ drain takes exactly one action; late-settling commands ride a later envelope.
 import asyncio
 from typing import Any
 
-from run_helpers import Script, msg, queue_ids, run_host
+from run_helpers import Script, add, queue_ids, run_host
 
 from harness_sdk import RunManager
 
@@ -15,29 +15,32 @@ async def test_multi_steer_batch_places_all_and_dispatches_once():
     async with run_host(script) as (drv, host):
         first = await drv.batch(
             [
-                ("run/steer", {"message": msg("s1")}),
-                ("run/steer", {"message": msg("s2")}),
-                ("run/steer", {"message": msg("s3")}),
+                ("run/steer", add("s1")),
+                ("run/steer", add("s2")),
+                ("run/steer", add("s3")),
             ]
         )
         for offset in range(3):
-            assert (await drv.res(first + offset))["type"] == "accepted"
+            assert (await drv.res(first + offset, terminal=False))["type"] == "pending"
         call = await script.next_call()
         assert call.ctx.type == "message-send"
         assert [m["id"] for m in call.ctx.messages] == ["s1", "s2", "s3"]
         script.no_call()
         assert queue_ids(drv.replica, "steerQueue") == []
+        call.finish(RunManager.Complete())
+        for offset in range(3):
+            assert (await drv.res(first + offset))["type"] == "accepted"
 
 
 async def test_steer_and_stop_in_one_batch_nets_to_stop():
     script = Script()
     async with run_host(script) as (drv, host):
-        await drv.command("run/enqueue", {"message": msg("m1")})
+        await drv.command("run/enqueue", add("m1"), terminal=False)
         call = await script.next_call()
         first = await drv.batch(
-            [("run/steer", {"message": msg("s1")}), ("run/stop", None)]
+            [("run/steer", add("s1")), ("run/stop", None)]
         )
-        assert (await drv.res(first))["type"] == "accepted"
+        assert (await drv.res(first, terminal=False))["type"] == "pending"
         assert (await drv.res(first + 1, terminal=False))["type"] == "pending"
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         call.finish(RunManager.Stop(dispatch_queue=False))
@@ -50,7 +53,7 @@ async def test_steer_and_stop_in_one_batch_nets_to_stop():
 async def test_stop_settles_only_after_the_run_task_ends():
     script = Script()
     async with run_host(script) as (drv, host):
-        await drv.command("run/enqueue", {"message": msg("m1")})
+        await drv.command("run/enqueue", add("m1"), terminal=False)
         call = await script.next_call()
         pending = await drv.command("run/stop", terminal=False)
         assert pending["type"] == "pending"
@@ -67,16 +70,16 @@ async def test_stop_settles_only_after_the_run_task_ends():
 class TailScript(Script):
     """get_message_meta suspends, pushing staging past the handler prefix."""
 
-    async def get_message_meta(self, message_id: str) -> dict[str, Any] | None:
+    async def get_message_meta(self, message_id: str | None) -> dict[str, Any] | None:
         await asyncio.sleep(0)
-        return self.thread.get(message_id)
+        return await super().get_message_meta(message_id)
 
 
 async def test_handler_tail_staging_decides_in_its_own_envelope():
     script = TailScript()
     async with run_host(script) as (drv, host):
-        res = await drv.command("run/enqueue", {"message": msg("m1")})
-        assert res["type"] == "accepted"
+        res = await drv.command("run/enqueue", add("m1"), terminal=False)
+        assert res["type"] == "pending"
         call = await script.next_call()
         assert [m["id"] for m in call.ctx.messages] == ["m1"]
         dispatch_env = next(
@@ -88,6 +91,6 @@ async def test_handler_tail_staging_decides_in_its_own_envelope():
             )
         )
         # The decide ran outside the batch segment: its ops flush in an
-        # envelope of their own, before the command's covering ack.
-        assert "res" not in dispatch_env
-        assert dispatch_env.get("ack", 0) < res["seq"]
+        # envelope of their own, alongside the pending verdict and its ack.
+        assert dispatch_env["res"] == [{"seq": res["seq"], "type": "pending"}]
+        assert dispatch_env["ack"] >= res["seq"]

harness_sdk_python-0.4.0/tests/test_branch_anchor.py

@@ -0,0 +1,145 @@
+from run_helpers import Script, add, assert_rejected, msg, queue_ids, run_host
+
+from harness_sdk import RunManager
+
+
+async def test_add_requires_a_branch_anchor():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        assert_rejected(
+            await drv.command("run/enqueue", {"message": msg("m1")}, terminal=False),
+            "invalid-message",
+        )
+        assert_rejected(
+            await drv.command("run/steer", {"message": msg("m1")}, terminal=False),
+            "invalid-message",
+        )
+
+
+async def test_null_anchor_valid_only_on_an_empty_thread():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        res = await drv.command("run/enqueue", add("m1"), terminal=False)
+        assert res["type"] == "pending"
+        await script.next_call()
+        script.thread["m1"] = {
+            "parentId": None, "role": "user", "isLeaf": True, "onActiveBranch": True
+        }
+        assert_rejected(
+            await drv.command("run/enqueue", add("m2"), terminal=False), "wrong-anchor"
+        )
+        res = await drv.command("run/enqueue", add("m2", anchor="m1"), terminal=False)
+        assert res["type"] == "pending"
+
+
+async def test_active_branch_anchor_accepted_off_branch_and_unknown_rejected():
+    script = Script()
+    script.thread.update(
+        {
+            "u1": {"parentId": None, "role": "user", "isLeaf": False, "onActiveBranch": True},
+            "a1": {"parentId": "u1", "role": "assistant", "isLeaf": True, "onActiveBranch": True},
+            "old": {"parentId": "u1", "role": "assistant", "isLeaf": True, "onActiveBranch": False},
+        }
+    )
+    async with run_host(script) as (drv, host):
+        res = await drv.command("run/enqueue", add("m1", anchor="a1"), terminal=False)
+        assert res["type"] == "pending"
+        await script.next_call()
+        assert_rejected(
+            await drv.command("run/enqueue", add("m2", anchor="old"), terminal=False),
+            "wrong-anchor",
+        )
+        assert_rejected(
+            await drv.command("run/enqueue", add("m2", anchor="zz"), terminal=False),
+            "unknown-id",
+        )
+
+
+async def test_queued_item_and_dispatched_ids_are_valid_anchors():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        await drv.command("run/enqueue", add("m1"), terminal=False)
+        await script.next_call()
+        await drv.command("run/enqueue", add("m2", anchor="m1"), terminal=False)
+        await drv.command("run/steer", add("s1", anchor="m2"), terminal=False)
+        assert queue_ids(drv.replica, "queue") == ["m2"]
+        assert queue_ids(drv.replica, "steerQueue") == ["s1"]
+
+
+async def test_replaced_tail_anchor_rejects_after_an_edit_rewrite():
+    script = Script()
+    script.thread.update(
+        {
+            "u1": {"parentId": None, "role": "user", "isLeaf": True, "onActiveBranch": True},
+        }
+    )
+    async with run_host(script, capabilities=("rewind",)) as (drv, host):
+        res = await drv.command(
+            "run/edit", {"sourceId": "u1", "message": msg("m2")}, terminal=False
+        )
+        assert res["type"] == "pending"
+        await script.next_call()
+        script.thread["u1"] = {
+            "parentId": None, "role": "user", "isLeaf": True, "onActiveBranch": False
+        }
+        script.thread["m2"] = {
+            "parentId": None, "role": "user", "isLeaf": True, "onActiveBranch": True
+        }
+        assert_rejected(
+            await drv.command("run/enqueue", add("q1", anchor="u1"), terminal=False),
+            "wrong-anchor",
+        )
+        res = await drv.command("run/enqueue", add("q1", anchor="m2"), terminal=False)
+        assert res["type"] == "pending"
+
+
+async def test_anchor_on_the_queued_edit_form_is_validated_never_ignored():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        await drv.command("run/enqueue", add("m1"), terminal=False)
+        await script.next_call()
+        await drv.command("run/enqueue", add("m2", anchor="m1"), terminal=False)
+        assert_rejected(
+            await drv.command(
+                "run/enqueue",
+                {"message": msg("m2", "edited"), "anchorMessageId": "zz"},
+                terminal=False,
+            ),
+            "unknown-id",
+        )
+        await drv.command(
+            "run/enqueue",
+            {"message": msg("m2", "edited"), "anchorMessageId": "m1"},
+            terminal=False,
+        )
+        assert drv.replica["queue"][0]["parts"][0]["text"] == "edited"
+
+
+async def test_reload_requires_a_message_id_and_delivers_it_on_the_start_context():
+    script = Script()
+    script.thread.update(
+        {
+            "u1": {"parentId": None, "role": "user", "isLeaf": False, "onActiveBranch": True},
+            "a1": {"parentId": "u1", "role": "assistant", "isLeaf": True, "onActiveBranch": True},
+        }
+    )
+    async with run_host(script, capabilities=("rewind",)) as (drv, host):
+        assert_rejected(
+            await drv.command("run/reload", {"sourceId": "a1"}, terminal=False),
+            "invalid-message",
+        )
+        assert_rejected(
+            await drv.command(
+                "run/reload", {"sourceId": "a1", "messageId": "u1"}, terminal=False
+            ),
+            "duplicate-id",
+        )
+        res = await drv.command(
+            "run/reload", {"sourceId": "a1", "messageId": "r9"}, terminal=False
+        )
+        assert res["type"] == "pending"
+        call = await script.next_call()
+        assert call.ctx.type == "message-reload"
+        assert call.ctx.message_id == "r9"
+        call.finish(RunManager.Complete())
+        await drv.wait_status("ready")