CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(agent): preserve live tool result run ids
Cue2d7b4751d0cf
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.pyindex b8ac744..99a803b 100644--- a/cubepi/agent/agent.py+++ b/cubepi/agent/agent.py@@ -1196,8 +1196,14 @@ class Agent(Generic[TMessage]):active = self._state.active_run_idif active is not None:if msg.run_id is None:- msg = msg.model_copy(update={"run_id": active})- event = event.model_copy(update={"message": msg})+ if isinstance(msg, AssistantMessage):+ # The loop retains this provider-owned object for tool+ # execution and the next model call. Stamp it in place+ # so tool results can inherit the owning turn's run ID.+ msg.run_id = active+ else:+ msg = msg.model_copy(update={"run_id": active})+ event = event.model_copy(update={"message": msg})elif msg.run_id != active:raise ValueError(f"message.run_id={msg.run_id!r} does not match "diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.pyindex 9d7ff1b..cf53662 100644--- a/cubepi/agent/tools.py+++ b/cubepi/agent/tools.py@@ -128,7 +128,9 @@ def _merge_hitl_details(return {"_non_dict_details": base, "hitl": hitl}-def _make_tool_result_message(finalized: _FinalizedOutcome) -> ToolResultMessage:+def _make_tool_result_message(+ finalized: _FinalizedOutcome, *, run_id: str | None+) -> ToolResultMessage:details = _merge_hitl_details(finalized.result.details, finalized.hitl_trace)return ToolResultMessage(tool_call_id=finalized.tool_call.id,@@ -137,6 +139,7 @@ def _make_tool_result_message(finalized: _FinalizedOutcome) -> ToolResultMessagedetails=details,is_error=finalized.is_error,timestamp=time.time(),+ run_id=run_id,)@@ -534,7 +537,9 @@ async def _execute_sequential(block_reason=finalized.block_reason,),)- tool_msg = _make_tool_result_message(finalized)+ tool_msg = _make_tool_result_message(+ finalized, run_id=assistant_message.run_id+ )await emit_event(emit_fn, MessageStartEvent(message=tool_msg))await emit_event(emit_fn, MessageEndEvent(message=tool_msg))finalized_list.append(finalized)@@ -684,7 +689,9 @@ async def _execute_parallel(if isinstance(s, _FinalizedOutcome)or (s.done() and not s.cancelled() and s.exception() is None)]- await _emit_tool_result_messages(salvaged, emit_fn)+ await _emit_tool_result_messages(+ salvaged, emit_fn, run_id=assistant_message.run_id+ )except asyncio.CancelledError:raiseexcept Exception:@@ -769,7 +776,9 @@ async def _execute_parallel(# resume would re-run tools whose side effects already happened.# A persistence failure propagates instead (consistent with every# other MessageEndEvent site): the run fails rather than suspends.- emitted = await _emit_tool_result_messages(finalized_list, emit_fn)+ emitted = await _emit_tool_result_messages(+ finalized_list, emit_fn, run_id=assistant_message.run_id+ )if isinstance(control_exc, HitlControlException):# Stateless loop entry points append these to the message# lists they return, so callers persisting the return value@@ -777,16 +786,21 @@ async def _execute_parallel(control_exc.partial_tool_results = tuple(emitted)raise control_exc- messages = await _emit_tool_result_messages(finalized_list, emit_fn)+ messages = await _emit_tool_result_messages(+ finalized_list, emit_fn, run_id=assistant_message.run_id+ )return ToolCallBatch(messages=messages, terminate=_should_terminate(finalized_list))async def _emit_tool_result_messages(- finalized_list: list[_FinalizedOutcome], emit_fn: Callable+ finalized_list: list[_FinalizedOutcome],+ emit_fn: Callable,+ *,+ run_id: str | None,) -> list[ToolResultMessage]:messages: list[ToolResultMessage] = []for finalized in finalized_list:- tool_msg = _make_tool_result_message(finalized)+ tool_msg = _make_tool_result_message(finalized, run_id=run_id)await emit_event(emit_fn, MessageStartEvent(message=tool_msg))await emit_event(emit_fn, MessageEndEvent(message=tool_msg))messages.append(tool_msg)diff --git a/dev/plans/2026-07-31-live-tool-result-run-id.md b/dev/plans/2026-07-31-live-tool-result-run-id.mdnew file mode 100644index 0000000..911452e--- /dev/null+++ b/dev/plans/2026-07-31-live-tool-result-run-id.md@@ -0,0 +1,133 @@+# Live ToolResult `run_id` Hotfix Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Ensure every live `ToolResultMessage` created for a run-aware Agent tool turn carries the owning assistant turn's `run_id` before emission, hooks, live-context append, checkpointing, and the next provider call.++**Architecture:** Keep `execute_tool_calls` public behavior and signatures compatible. Make the current assistant message's `run_id` visible on the live assistant object at the existing Agent message-end stamping seam, then pass that value explicitly through the private tool-result construction/emission boundary. Direct calls with an unstamped assistant continue to produce `run_id=None`; no run ID is inferred from call IDs or other global state during tool-result construction.++**Tech Stack:** Python 3.13, asyncio, Pydantic models, `FauxProvider`, `MemoryCheckpointer`, pytest, Ruff, mypy, uv.++---++### Task 1: Pin the Regression at the Real Agent Boundary++**Files:**+- Modify: `tests/agent/test_agent_run_id.py`++- [ ] **Step 1: Add a production-shaped Agent/FauxProvider tool-cycle test**++Create an `Agent` with a real `AgentTool`, `MemoryCheckpointer`, and `run_id="R1"`. Queue a tool-call assistant response followed by a Faux response factory. In the second response factory, assert the just-appended `ToolResultMessage.run_id == "R1"`. Capture `should_stop_after_turn` inputs and tool-result message events so the test also verifies the live context, `new_messages`, hook input, emitted message, `Agent.state.messages`, and checkpointed message all carry exactly `"R1"`.++- [ ] **Step 2: Run the production-shaped test and record RED**++Run:++```bash+uv run pytest tests/agent/test_agent_run_id.py::test_live_tool_results_carry_owning_run_id -vv+```++Expected on base `94d0ca7380502506042390ce73a02de1060387b0`: FAIL in the second Faux response factory because the live `ToolResultMessage.run_id` is `None`, while the `MemoryCheckpointer` copy is stamped `"R1"`.++### Task 2: Pin Executor Outcome and Compatibility Contracts++**Files:**+- Modify: `tests/agent/test_tools.py`++- [ ] **Step 1: Add stamped-assistant executor coverage**++Add focused tests that pass an `AssistantMessage(run_id="R-tools")` into `execute_tool_calls` and assert both emitted `MessageStartEvent`/`MessageEndEvent` messages and returned `ToolCallBatch.messages` retain `"R-tools"` for:++- a mixed parallel batch containing success, validation failure, tool-not-found, tool-body error, and `before_tool_call` blocked outcomes;+- a sequential batch with multiple results.++Also assert message ordering, content/error classification, and tool-call IDs remain unchanged.++- [ ] **Step 2: Add the unstamped legacy control**++Call `execute_tool_calls` directly with an assistant whose `run_id` is `None` and assert every returned and emitted `ToolResultMessage.run_id` remains `None`.++- [ ] **Step 3: Run the focused executor tests and record RED**++Run the new test node IDs with `uv run pytest ... -vv`.++Expected on the pinned base: stamped-assistant assertions FAIL because `_make_tool_result_message` omits `run_id`; the unstamped control PASSes.++### Task 3: Implement the Smallest Construction-Boundary Fix++**Files:**+- Modify: `cubepi/agent/agent.py`+- Modify: `cubepi/agent/tools.py`++- [ ] **Step 1: Preserve the owning ID on the live assistant turn**++At `Agent._process_event`'s existing `MessageEndEvent` stamping seam, ensure an unstamped `AssistantMessage` that belongs to the active run is stamped on the same live object before the loop proceeds to `execute_tool_calls`. Preserve the existing mismatch rejection and persistence behavior. Avoid mutating caller-supplied user messages or adding a run ID to stateless/legacy flows.++- [ ] **Step 2: Pass the assistant ID into tool-result construction**++Change the private `_make_tool_result_message` helper to accept `run_id: str | None` and set `ToolResultMessage.run_id`. Pass `assistant_message.run_id` from sequential construction and through `_emit_tool_result_messages` for every parallel, salvage, cancellation, HITL-sibling, immediate, success, and error outcome.++- [ ] **Step 3: Run the new tests GREEN**++Run:++```bash+uv run pytest tests/agent/test_agent_run_id.py tests/agent/test_tools.py -vv+```++Expected: all tests PASS, including live provider context, emitted event, hook, multiple-result, outcome-matrix, and unstamped-assistant controls.++### Task 4: Verify Regressions and Quality Gates++**Files:**+- Verify only; no new production scope.++- [ ] **Step 1: Run focused Agent/tool/run-ID/checkpointer suites**++```bash+uv run pytest tests/agent/test_agent_run_id.py tests/agent/test_tools.py tests/agent/test_loop.py tests/agent/test_checkpointer_integration.py -q+```++Expected: PASS.++- [ ] **Step 2: Run the full test suite**++```bash+uv run pytest tests/+```++Expected: PASS; record exact passed/skipped counts.++- [ ] **Step 3: Run static and formatting checks**++```bash+uv run ruff check cubepi/ tests/+uv run ruff format --check cubepi/ tests/+uv run mypy cubepi+```++Expected: all PASS; record exact output/counts.++### Task 5: Produce One Local Hotfix Commit and Applicability Report++**Files:**+- Commit only the plan, focused tests, and minimal source fix.++- [ ] **Step 1: Inspect the final diff**++Verify there are no unrelated refactors, public API changes, Cubemanus changes, release/tag changes, or external publishing actions.++- [ ] **Step 2: Commit once locally**++```bash+git add dev/plans/2026-07-31-live-tool-result-run-id.md cubepi/agent/agent.py cubepi/agent/tools.py tests/agent/test_agent_run_id.py tests/agent/test_tools.py+git commit -m "fix(agent): preserve tool result run ids++Co-Authored-By: Claude <[email protected]>"+```++- [ ] **Step 3: Verify clean worktree and main applicability**++Record the exact commit SHA and changed files. Fetch no remote state unless already available; compare against current `origin/main` and use a temporary, non-publishing applicability check (`git apply --check` against the patch or an isolated temporary worktree) without mutating `main`.++Expected: clean worktree and an explicit clean/conflicting applicability result.diff --git a/tests/agent/test_agent_run_id.py b/tests/agent/test_agent_run_id.pyindex 06ab0e4..e70a2f9 100644--- a/tests/agent/test_agent_run_id.py+++ b/tests/agent/test_agent_run_id.py@@ -70,6 +70,110 @@ async def test_appended_messages_carry_run_id():assert m.run_id == "R1"+async def test_live_tool_results_carry_owning_run_id():+ from pydantic import BaseModel++ from cubepi.agent.types import AgentTool, AgentToolResult+ from cubepi.checkpointer.memory import MemoryCheckpointer+ from cubepi.providers.base import ToolResultMessage+ from cubepi.providers.faux import faux_assistant_message, faux_tool_call++ class EchoParams(BaseModel):+ value: str++ async def execute(tool_call_id, params, *, signal=None, on_update=None):+ return AgentToolResult(content=[TextContent(text=params.value)])++ live_provider_run_ids = []+ hook_snapshots = []++ def finish(messages, model):+ assistant = next(+ m+ for m in reversed(messages)+ if isinstance(m, AssistantMessage) and m.stop_reason == "tool_use"+ )+ tool_result = next(+ m for m in reversed(messages) if isinstance(m, ToolResultMessage)+ )+ live_provider_run_ids.append((assistant.run_id, tool_result.run_id))+ return faux_assistant_message("done")++ async def should_stop_after_turn(ctx):+ if ctx.tool_results:+ hook_snapshots.append(+ (+ [m.run_id for m in ctx.tool_results],+ [+ m.run_id+ for m in ctx.context.messages+ if isinstance(m, ToolResultMessage)+ ],+ [+ m.run_id+ for m in ctx.new_messages+ if isinstance(m, ToolResultMessage)+ ],+ )+ )+ return False++ provider = FauxProvider()+ provider.set_responses(+ [+ faux_assistant_message(+ faux_tool_call("echo", {"value": "ok"}, id="call-1"),+ stop_reason="tool_use",+ ),+ finish,+ ]+ )+ checkpointer = MemoryCheckpointer()+ agent = Agent(+ model=provider.model("faux-model"),+ tools=[+ AgentTool(+ name="echo",+ description="Echo a value",+ parameters=EchoParams,+ execute=execute,+ )+ ],+ checkpointer=checkpointer,+ thread_id="run-id-tool-cycle",+ should_stop_after_turn=should_stop_after_turn,+ )+ events = []+ agent.subscribe(lambda event, signal=None: events.append(event))++ await agent.prompt("use the tool", run_id="R1")++ state_tool_result = next(+ message+ for message in agent.state.messages+ if isinstance(message, ToolResultMessage)+ )+ checkpoint = await checkpointer.load("run-id-tool-cycle")+ checkpoint_tool_result = next(+ message+ for message in checkpoint.messages+ if isinstance(message, ToolResultMessage)+ )+ assert state_tool_result.run_id == checkpoint_tool_result.run_id == "R1"++ assert live_provider_run_ids == [("R1", "R1")]+ assert hook_snapshots == [(["R1"], ["R1"], ["R1"])]++ tool_message_events = [+ event.message+ for event in events+ if event.type in ("message_start", "message_end")+ and isinstance(event.message, ToolResultMessage)+ ]+ assert [message.run_id for message in tool_message_events] == ["R1", "R1"]++@pytest.mark.asyncioasync def test_prompt_rejects_mismatched_run_id_before_claim():"""Caller pre-stamps a Message with a different run_id than thediff --git a/tests/agent/test_tools.py b/tests/agent/test_tools.pyindex 1bf18f2..052d6f5 100644--- a/tests/agent/test_tools.py+++ b/tests/agent/test_tools.py@@ -36,8 +36,14 @@ def make_echo_tool()-def make_assistant_msg(tool_calls: list[ToolCall]) -> AssistantMessage:- return AssistantMessage(content=tool_calls, stop_reason="tool_use")+def make_assistant_msg(+ tool_calls: list[ToolCall], *, run_id: str | None = None+) -> AssistantMessage:+ return AssistantMessage(+ content=tool_calls,+ stop_reason="tool_use",+ run_id=run_id,+ )def make_context(tools: list[AgentTool]) -> AgentContext:@@ -623,6 +629,141 @@ class TestToolEvents:assert start_idx < end_idx+class TestToolResultRunId:+ async def test_parallel_outcomes_inherit_assistant_run_id_before_emission(self):+ async def fail_execute(tool_call_id, params, *, signal=None, on_update=None):+ raise RuntimeError("tool failed")++ async def before(before_ctx, *, signal=None):+ if before_ctx.tool_call.id == "t5":+ return BeforeToolCallResult(+ block=True,+ reason="blocked by policy",+ hitl_trace={"request_id": "approval-1"},+ )+ if before_ctx.tool_call.id == "t6":+ raise RuntimeError("hook failed")+ return None++ ctx = make_context(+ [+ make_echo_tool(),+ make_echo_tool(name="fail", execute_fn=fail_execute),+ ]+ )+ msg = make_assistant_msg(+ [+ ToolCall(id="t1", name="echo", arguments={"value": "ok"}),+ ToolCall(id="t2", name="echo", arguments={}),+ ToolCall(id="t3", name="missing", arguments={}),+ ToolCall(id="t4", name="fail", arguments={"value": "boom"}),+ ToolCall(id="t5", name="echo", arguments={"value": "blocked"}),+ ToolCall(id="t6", name="echo", arguments={"value": "hook"}),+ ],+ run_id="R-tools",+ )+ events = []++ batch = await execute_tool_calls(+ ctx,+ msg,+ tool_execution="parallel",+ before_tool_call=before,+ emit=lambda event: events.append(event),+ )++ assert [message.tool_call_id for message in batch.messages] == [+ "t1",+ "t2",+ "t3",+ "t4",+ "t5",+ "t6",+ ]+ assert [message.run_id for message in batch.messages] == ["R-tools"] * 6+ assert [message.is_error for message in batch.messages] == [+ False,+ True,+ True,+ True,+ True,+ True,+ ]+ by_id = {message.tool_call_id: message for message in batch.messages}+ assert by_id["t1"].content[0].text == "echoed: ok"+ assert "field required" in by_id["t2"].content[0].text+ assert "not found" in by_id["t3"].content[0].text+ assert "tool failed" in by_id["t4"].content[0].text+ assert by_id["t5"].content[0].text == "blocked by policy"+ assert by_id["t5"].details == {"hitl": {"request_id": "approval-1"}}+ assert by_id["t6"].content[0].text == "hook failed"++ message_events = [+ event for event in events if event.type in ("message_start", "message_end")+ ]+ assert [+ (event.type, event.message.tool_call_id, event.message.run_id)+ for event in message_events+ ] == [+ (event_type, tool_call_id, "R-tools")+ for tool_call_id in ("t1", "t2", "t3", "t4", "t5", "t6")+ for event_type in ("message_start", "message_end")+ ]++ async def test_sequential_multiple_results_inherit_assistant_run_id(self):+ ctx = make_context([make_echo_tool()])+ msg = make_assistant_msg(+ [+ ToolCall(id="t1", name="echo", arguments={"value": "first"}),+ ToolCall(id="t2", name="echo", arguments={"value": "second"}),+ ],+ run_id="R-sequential",+ )+ events = []++ batch = await execute_tool_calls(+ ctx,+ msg,+ tool_execution="sequential",+ emit=lambda event: events.append(event),+ )++ assert [message.run_id for message in batch.messages] == [+ "R-sequential",+ "R-sequential",+ ]+ message_events = [+ event for event in events if event.type in ("message_start", "message_end")+ ]+ assert [event.message.run_id for event in message_events] == [+ "R-sequential"+ ] * 4++ @pytest.mark.parametrize("tool_execution", ["parallel", "sequential"])+ async def test_unstamped_assistant_does_not_fabricate_run_id(self, tool_execution):+ ctx = make_context([make_echo_tool()])+ msg = make_assistant_msg(+ [+ ToolCall(id="t1", name="echo", arguments={"value": "first"}),+ ToolCall(id="t2", name="echo", arguments={"value": "second"}),+ ]+ )+ events = []++ batch = await execute_tool_calls(+ ctx,+ msg,+ tool_execution=tool_execution,+ emit=lambda event: events.append(event),+ )++ assert [message.run_id for message in batch.messages] == [None, None]+ message_events = [+ event for event in events if event.type in ("message_start", "message_end")+ ]+ assert all(event.message.run_id is None for event in message_events)++class TestToolResultDetails:async def test_details_propagated_to_tool_result_message(self):async def execute_with_details(