Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

feat(messages): assign a stable transcript id on append

xf gong4de0abd52215
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.** Three
diff --git a/cubeloop/agent/agent.py b/cubeloop/agent/agent.py
index def0ba6..f101569 100644
--- a/cubeloop/agent/agent.py
+++ b/cubeloop/agent/agent.py
@@ -52,6 +52,19 @@ from cubeloop.types import JsonObject, StructuredValue
TMessage = 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.message
elif event.type == "message_end":
msg = event.message
+ _ensure_message_id(msg)
active = self._state.active_run_id
if active is not None:
if msg.run_id is None:
diff --git a/cubeloop/middleware/compaction/state.py b/cubeloop/middleware/compaction/state.py
index 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.py
index 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 = None
metadata: 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 = None
error_type: str | None = None
@@ -128,6 +135,7 @@ class ToolResultMessage(BaseModel):
content: list[Content]
details: StructuredValue = None
is_error: bool = False
+ id: str = ""
timestamp: float | None = None
metadata: JsonObject = Field(default_factory=dict)
run_id: str | None = None
diff --git a/tests/agent/test_message_id.py b/tests/agent/test_message_id.py
new file mode 100644
index 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.py
index c027720..1e91abd 100644
--- a/tests/middleware/test_compaction.py
+++ b/tests/middleware/test_compaction.py
@@ -1,6 +1,8 @@
from __future__ import annotations
import asyncio
+import hashlib
+import json
import logging
from 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(