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
feat(messages): assign a stable transcript id on append
xf gong4de0abd52215
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b5ceab2..fa2a974 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added++- **Messages carry a stable `id`.** `UserMessage`, `AssistantMessage`, and+ `ToolResultMessage` have `id: str`, empty until the agent appends the+ message. A host may set it first; that value is kept. The id is written+ onto both the object the loop keeps and the object stored in the+ checkpointer. Rows saved before this field existed load as `""` and+ compaction keeps identifying them by content hash. New messages use+ `id:`, so a later rewrite of `run_id`, `timestamp`, or `metadata` does+ not change which transcript entry a summary covers.+### Fixed- **Compaction no longer goes blind when its persisted state is dropped.** Threediff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.pyindex def0ba6..f101569 100644--- a/cubeloop/agent/agent.py+++ b/cubeloop/agent/agent.py@@ -52,6 +52,19 @@ from cubeloop.types import JsonObject, StructuredValueTMessage = TypeVar("TMessage")+def _ensure_message_id(message: Message) -> None:+ """Assign a transcript id in place when the message does not have one.++ Called before the message is appended. In-place, and before any+ ``model_copy`` that stamps ``run_id``, so the object the loop keeps and+ the object written to the checkpointer carry the same id. A non-empty id+ is left alone. Checkpoint load does not come through here, so rows that+ predate the field stay empty and compaction keeps hashing them.+ """+ if not message.id:+ message.id = uuid.uuid4().hex++def _consume_control_exception(future: asyncio.Future[StructuredValue]) -> None:"""Mark a detach control exception retrieved without changing awaiters."""if not future.cancelled():@@ -1167,6 +1180,7 @@ class Agent(Generic[TMessage]):timestamp=time.time(),run_id=owning_run_id,)+ _ensure_message_id(synthetic)self._state._messages.append(synthetic)await self.checkpointer.append(self.thread_id, [synthetic])@@ -1180,6 +1194,7 @@ class Agent(Generic[TMessage]):timestamp=time.time(),run_id=owning_run_id,)+ _ensure_message_id(term)self._state._messages.append(term)await self.checkpointer.append(self.thread_id, [term])@@ -1318,18 +1333,16 @@ class Agent(Generic[TMessage]):for block in last_assistant.content:if not isinstance(block, ToolCall) or block.id in answered:continue- synthetic.append(- ToolResultMessage(- tool_call_id=block.id,- tool_name=block.name,- content=[- TextContent(text="[Tool execution cancelled by user]")- ],- is_error=True,- timestamp=time.time(),- run_id=owning_run_id,- )+ cancelled = ToolResultMessage(+ tool_call_id=block.id,+ tool_name=block.name,+ content=[TextContent(text="[Tool execution cancelled by user]")],+ is_error=True,+ timestamp=time.time(),+ run_id=owning_run_id,)+ _ensure_message_id(cancelled)+ synthetic.append(cancelled)if not synthetic:return@@ -1348,6 +1361,7 @@ class Agent(Generic[TMessage]):self._state.streaming_message = event.messageelif event.type == "message_end":msg = event.message+ _ensure_message_id(msg)active = self._state.active_run_idif active is not None:if msg.run_id is None:diff --git a/cubeloop/middleware/compaction/state.py b/cubeloop/middleware/compaction/state.pyindex 036296d..d3996a6 100644--- a/cubeloop/middleware/compaction/state.py+++ b/cubeloop/middleware/compaction/state.py@@ -57,6 +57,9 @@ def message_ref(message: Message) -> str:payload = message.model_dump(mode="json", exclude_none=True)for field in _VOLATILE_REF_FIELDS:payload.pop(field, None)+ # An unset id serialises as "". Leave it out of the hash so rows written+ # before the field existed keep the ref they were stored under.+ payload.pop("id", None)encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()return "sha256:" + hashlib.sha256(encoded).hexdigest()diff --git a/cubeloop/providers/base.py b/cubeloop/providers/base.pyindex 50d6b44..57dd763 100644--- a/cubeloop/providers/base.py+++ b/cubeloop/providers/base.py@@ -93,9 +93,15 @@ class ToolCall(BaseModel):arguments: JsonObject+# ``id`` is the transcript identity used by compaction. Empty means the+# message has not been appended yet, or it was stored before the field+# existed. It is not a ``default_factory``: loading an old checkpoint row+# must keep ``""`` so those rows stay on the content hash. The agent fills+# it once, in place, at append time, and keeps a host-supplied value.class UserMessage(BaseModel):role: Literal["user"] = "user"content: list[Content]+ id: str = ""timestamp: float | None = Nonemetadata: JsonObject = Field(default_factory=dict)run_id: str | None = None@@ -104,6 +110,7 @@ class UserMessage(BaseModel):class AssistantMessage(BaseModel):role: Literal["assistant"] = "assistant"content: list[Content | ThinkingContent | ToolCall]+ id: str = ""stop_reason: str = "stop"error_message: str | None = Noneerror_type: str | None = None@@ -128,6 +135,7 @@ class ToolResultMessage(BaseModel):content: list[Content]details: StructuredValue = Noneis_error: bool = False+ id: str = ""timestamp: float | None = Nonemetadata: JsonObject = Field(default_factory=dict)run_id: str | None = Nonediff --git a/tests/agent/test_message_id.py b/tests/agent/test_message_id.pynew file mode 100644index 0000000..0be8da7--- /dev/null+++ b/tests/agent/test_message_id.py@@ -0,0 +1,108 @@+"""Stable transcript ids are assigned once, at append time."""++import asyncio++import pytest++from cubeloop.agent.agent import Agent+from cubeloop.agent.types import AgentContext+from cubeloop.checkpointer.memory import MemoryCheckpointer+from cubeloop.middleware.base import Middleware+from cubeloop.middleware.compaction.state import message_ref+from cubeloop.providers.base import AssistantMessage, Message, TextContent, UserMessage+from cubeloop.providers.faux import FauxProvider+++class _CaptureIds(Middleware):+ """Record the ids the loop is about to send to the model."""++ def __init__(self) -> None:+ self.ids: list[str] = []++ async def transform_context(+ self,+ messages: list[Message],+ *,+ ctx: AgentContext,+ signal: asyncio.Event | None = None,+ ) -> list[Message]:+ del ctx, signal+ self.ids = [message.id for message in messages]+ return messages+++def _agent(cp: MemoryCheckpointer, middleware: list[Middleware] | None = None) -> Agent:+ provider = FauxProvider()+ provider.set_responses(+ [AssistantMessage(content=[TextContent(text="ok")], stop_reason="end_turn")]+ )+ return Agent(+ model=provider.model("faux-model"),+ checkpointer=cp,+ thread_id="t",+ middleware=middleware,+ )+++def test_missing_id_loads_as_empty_string() -> None:+ msg = UserMessage.model_validate(+ {"role": "user", "content": [{"type": "text", "text": "hi"}]}+ )+ assert msg.id == ""+++async def test_prompt_shares_one_id_across_the_loop_state_and_checkpoint() -> None:+ """The session copies the caller's message before the run.++ ``run_id`` stamping then copies a user message again. Both copies must+ carry the id assigned at append time. The caller's own object is left+ untouched.+ """+ cp = MemoryCheckpointer()+ capture = _CaptureIds()+ agent = _agent(cp, middleware=[capture])+ message = UserMessage(content=[TextContent(text="hello")])++ await agent.prompt(message, run_id="R1")++ assert message.id == ""+ stored_id = agent.state.messages[0].id+ assert stored_id+ assert capture.ids[0] == stored_id+ loaded = await cp.load("t")+ assert loaded is not None+ assert loaded.messages[0].id == stored_id+ assert message_ref(loaded.messages[0]) == f"id:{stored_id}"+ assert agent.state.messages[1].id+ assert agent.state.messages[1].id != stored_id+++async def test_prompt_keeps_a_host_supplied_id() -> None:+ cp = MemoryCheckpointer()+ agent = _agent(cp)+ message = UserMessage(content=[TextContent(text="hello")], id="host-1")++ await agent.prompt(message, run_id="R1")++ assert message.id == "host-1"+ assert agent.state.messages[0].id == "host-1"+ loaded = await cp.load("t")+ assert loaded is not None+ assert loaded.messages[0].id == "host-1"+++async def test_loaded_message_without_id_is_not_backfilled() -> None:+ cp = MemoryCheckpointer()+ old = UserMessage(content=[TextContent(text="old")])+ await cp.append("t", [old])+ agent = _agent(cp)++ await agent.prompt("next", run_id="R2")++ assert agent.state.messages[0].id == ""+ assert agent.state.messages[1].id+ assert message_ref(agent.state.messages[0]).startswith("sha256:")+ assert message_ref(agent.state.messages[1]) == f"id:{agent.state.messages[1].id}"diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.pyindex c027720..1e91abd 100644--- a/tests/middleware/test_compaction.py+++ b/tests/middleware/test_compaction.py@@ -1,6 +1,8 @@from __future__ import annotationsimport asyncio+import hashlib+import jsonimport loggingfrom typing import Any@@ -131,14 +133,13 @@ def test_load_state_accepts_state_and_ignores_unknown_values() -> None:def test_message_ref_prefers_explicit_message_id() -> None:- class _MessageWithId:- id = "msg-123"-- def model_dump(self, **kwargs: Any) -> dict[str, Any]:- del kwargs- return {"content": "unused"}+ message = UserMessage(content=[TextContent(text="hello")], id="msg-123")+ rewritten = message.model_copy(+ update={"run_id": "other", "metadata": {"captured_at": "later"}}+ )- assert message_ref(_MessageWithId()) == "id:msg-123" # type: ignore[arg-type]+ assert message_ref(message) == "id:msg-123"+ assert message_ref(rewritten) == "id:msg-123"async def test_over_threshold_writes_json_safe_state_to_ctx_extra() -> None:@@ -1477,6 +1478,23 @@ def test_message_ref_ignores_volatile_bookkeeping() -> None:assert message_ref(result[0]) != message_ref(result[1])+def test_unset_message_id_does_not_change_the_content_hash() -> None:+ """Rows stored before ``id`` existed must keep their ref.++ ``model_dump`` now includes ``id: ""``. The hash fallback drops that key,+ so a checkpoint written by the previous release still matches.+ """+ message = UserMessage(content=[TextContent(text="hello")], run_id="run-1")+ payload = message.model_dump(mode="json", exclude_none=True)+ assert payload["id"] == ""+ payload.pop("id")+ for field in ("run_id", "timestamp", "metadata"):+ payload.pop(field, None)+ encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()++ assert message_ref(message) == "sha256:" + hashlib.sha256(encoded).hexdigest()++def _stale_state_for(messages: list[Message]) -> CompactionState:"""A state whose refs describe a *different* history — the shape of #233."""return CompactionState(