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: unified synthetic marker for framework-injected user messages
xf gong87a302840e39
diff --git a/cubepi/__init__.py b/cubepi/__init__.pyindex 86ade09..33de20f 100644--- a/cubepi/__init__.py+++ b/cubepi/__init__.py@@ -37,6 +37,8 @@ from cubepi.providers import (ToolDefinition,ToolResultMessage,UserMessage,+ is_synthetic_message,+ synthetic_user_message,adjust_max_tokens_for_thinking,)from cubepi.errors import (@@ -114,6 +116,8 @@ __all__ = ["ToolDefinition","ToolResultMessage","UserMessage",+ "is_synthetic_message",+ "synthetic_user_message","adjust_max_tokens_for_thinking","compose_middleware","run_agent_loop",diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.pyindex 403da04..c10cadd 100644--- a/cubepi/middleware/compaction/__init__.py+++ b/cubepi/middleware/compaction/__init__.py@@ -22,8 +22,7 @@ from cubepi.middleware.compaction.tokens import approx_tokensfrom cubepi.providers.base import (BoundModel,Message,- TextContent,- UserMessage,+ synthetic_user_message,)SUMMARY_PREFIX = (@@ -47,8 +46,9 @@ def _compressed_view(boundary: int | None,) -> list[Message]:if state and boundary and boundary > 0:- summary = UserMessage(- content=[TextContent(text=SUMMARY_PREFIX + state.summary)],+ summary = synthetic_user_message(+ SUMMARY_PREFIX + state.summary,+ source="compaction_summary",)return [summary, *messages[boundary:]]return list(messages)diff --git a/cubepi/middleware/goal.py b/cubepi/middleware/goal.pyindex 3ce9822..f6211c1 100644--- a/cubepi/middleware/goal.py+++ b/cubepi/middleware/goal.py@@ -22,6 +22,7 @@ from cubepi.providers.base import (ToolCall,ToolResultMessage,UserMessage,+ synthetic_user_message,)_GOAL_PREFIX = "/goal "@@ -169,11 +170,8 @@ class GoalMiddleware(Middleware):goal_state["status"] = "active"ctx.extra["goal"] = goal_statereturn [- UserMessage(- content=[- TextContent(- text=f"Goal not yet met: {result.reason}. Continue working."- )- ]+ synthetic_user_message(+ f"Goal not yet met: {result.reason}. Continue working.",+ source="goal_continuation",)]diff --git a/cubepi/middleware/todo.py b/cubepi/middleware/todo.pyindex 9559b32..68ff597 100644--- a/cubepi/middleware/todo.py+++ b/cubepi/middleware/todo.py@@ -39,6 +39,7 @@ from cubepi.agent.types import ()from cubepi.middleware.base import Middleware, TurnActionfrom cubepi.providers.base import (+ synthetic_user_message,AssistantMessage,Message,TextContent,@@ -357,9 +358,9 @@ def _todo_validation_errors_local(# ----------------------------------------------------------------------------def _make_user_message(text: str) -> UserMessage:- """Wrap plain text in a cubepi UserMessage for injection."""- return UserMessage(content=[TextContent(text=text)])+def _make_user_message(text: str, *, source: str) -> UserMessage:+ """Wrap plain text in a synthetic UserMessage for injection."""+ return synthetic_user_message(text, source=source)# ---------------------------------------------------------------------------@@ -546,7 +547,7 @@ class TodoListMiddleware(Middleware):"All todo items are complete. Do a quick final check before responding.")todo_text = "[Current todo list]\n" + json.dumps(payload, ensure_ascii=False)- todo_msg = UserMessage(content=[TextContent(text=todo_text)])+ todo_msg = synthetic_user_message(todo_text, source="todo_list_view")return list(messages) + [todo_msg]# ------------------------------------------------------------------@@ -609,7 +610,10 @@ class TodoListMiddleware(Middleware):"in parallel. Please call it only once per model invocation to update ""the todo list.")- return [_make_user_message(error_text) for _ in write_todos_calls]+ return [+ _make_user_message(error_text, source="todo_parallel_error")+ for _ in write_todos_calls+ ]def _guard_response(self,@@ -634,13 +638,15 @@ class TodoListMiddleware(Middleware):f"could not continue safely because: {message}")return TurnAction(- inject_messages=[_make_user_message(inject_text)],+ inject_messages=[+ _make_user_message(inject_text, source="todo_blocked")+ ],decision="loop_to_model",)extra["todo_finalization_correction"] = Truereturn TurnAction(- inject_messages=[_make_user_message(message)],+ inject_messages=[_make_user_message(message, source="todo_guard")],decision="loop_to_model",)@@ -685,7 +691,10 @@ class TodoListMiddleware(Middleware):extra["todo_finalization_correction"] = Nonereturn TurnAction(inject_messages=[- _make_user_message(_blocked_todo_guard_message(blocked_guard))+ _make_user_message(+ _blocked_todo_guard_message(blocked_guard),+ source="todo_blocked",+ )],decision="loop_to_model",)@@ -715,7 +724,8 @@ class TodoListMiddleware(Middleware):)if validation_errors:inject: list[Any] = [- _make_user_message(e["error"]) for e in validation_errors+ _make_user_message(e["error"], source="todo_validation_error")+ for e in validation_errors]return TurnAction(inject_messages=inject)@@ -733,7 +743,11 @@ class TodoListMiddleware(Middleware):(stale_count_new - STALE_REMINDER_THRESHOLD) % STALE_REMINDER_INTERVAL== 0):- stale_injections.append(_make_user_message(_STALE_REMINDER_TEXT))+ stale_injections.append(+ _make_user_message(+ _STALE_REMINDER_TEXT, source="todo_stale_reminder"+ )+ )elif has_write_todos or not has_non_todo_tools:# Any write_todos call or non-tool turn resets the counter.stale_count_new = 0diff --git a/cubepi/providers/__init__.py b/cubepi/providers/__init__.pyindex 7ebf909..eac4a81 100644--- a/cubepi/providers/__init__.py+++ b/cubepi/providers/__init__.py@@ -26,6 +26,8 @@ from cubepi.providers.base import (ToolResultMessage,Usage,UserMessage,+ is_synthetic_message,+ synthetic_user_message,adjust_max_tokens_for_thinking,chain_providers,collect_agent_providers,@@ -99,6 +101,8 @@ __all__ = ["ToolResultMessage","Usage","UserMessage",+ "is_synthetic_message",+ "synthetic_user_message","adjust_max_tokens_for_thinking","chain_providers","clamp_thinking_level",diff --git a/cubepi/providers/base.py b/cubepi/providers/base.pyindex 8af9a17..7daa800 100644--- a/cubepi/providers/base.py+++ b/cubepi/providers/base.py@@ -162,6 +162,43 @@ class ToolResultMessage(BaseModel):Message = UserMessage | AssistantMessage | ToolResultMessage+# --- Synthetic message marker (issue #171) ---+#+# Middleware and the framework itself sometimes inject user-role messages+# into the conversation (todo guard nudges, goal continuations, …). Without+# a marker these are indistinguishable from messages a human typed, so+# downstream UIs render internal scaffolding as user chat bubbles. The+# marker lives in ``metadata`` (not a subclass) because class identity does+# not survive the checkpointer/API round-trip — persisted messages are+# revalidated into the plain union types.++SYNTHETIC_METADATA_KEY = "synthetic"+SYNTHETIC_SOURCE_METADATA_KEY = "synthetic_source"+++def synthetic_user_message(text: str, *, source: str) -> UserMessage:+ """Build a user-role message injected by the framework, not typed by a human.++ All injected user-role messages MUST be created through this factory so+ downstream consumers can branch on a single marker+ (``metadata["synthetic"] is True``). ``source`` (e.g. ``"todo_guard"``,+ ``"goal_continuation"``) is for tracing/debugging only — UI behavior+ should never depend on it.+ """+ return UserMessage(+ content=[TextContent(text=text)],+ metadata={+ SYNTHETIC_METADATA_KEY: True,+ SYNTHETIC_SOURCE_METADATA_KEY: source,+ },+ )+++def is_synthetic_message(message: Message) -> bool:+ """True if ``message`` was injected by the framework rather than a human."""+ return message.metadata.get(SYNTHETIC_METADATA_KEY) is True++class ToolDefinition(BaseModel):name: strdescription: str@@ -890,7 +927,9 @@ class BoundModel:content=[TextContent(text=error_text)],is_error=True,),- UserMessage(content=[TextContent(text=error_text)]),+ synthetic_user_message(+ error_text, source="structured_output_retry"+ ),]breakelse:diff --git a/tests/test_synthetic_messages.py b/tests/test_synthetic_messages.pynew file mode 100644index 0000000..53d4844--- /dev/null+++ b/tests/test_synthetic_messages.py@@ -0,0 +1,198 @@+"""Tests for the unified synthetic-message marker (issue #171).++Framework-injected user-role messages (todo guard, goal continuation,+compaction summary, …) must carry ``metadata.synthetic == True`` so+downstream consumers can distinguish them from messages a human typed.+"""++from __future__ import annotations++from typing import Any++from cubepi import Agent+from cubepi.agent.types import AgentContext+from cubepi.middleware.goal import GoalMiddleware+from cubepi.middleware.todo import TodoListMiddleware+from cubepi.providers.base import (+ SYNTHETIC_METADATA_KEY,+ SYNTHETIC_SOURCE_METADATA_KEY,+ AssistantMessage,+ Message,+ TextContent,+ UserMessage,+ is_synthetic_message,+ synthetic_user_message,+)+from cubepi.providers.faux import FauxProvider, faux_assistant_message, faux_tool_call++# ---------------------------------------------------------------------------+# Factory + predicate unit tests+# ---------------------------------------------------------------------------+++def test_factory_sets_marker_and_source() -> None:+ msg = synthetic_user_message("nudge text", source="todo_guard")+ assert isinstance(msg, UserMessage)+ assert msg.content == [TextContent(text="nudge text")]+ assert msg.metadata[SYNTHETIC_METADATA_KEY] is True+ assert msg.metadata[SYNTHETIC_SOURCE_METADATA_KEY] == "todo_guard"+++def test_predicate_true_for_synthetic() -> None:+ assert is_synthetic_message(synthetic_user_message("x", source="test"))+++def test_predicate_false_for_plain_user_message() -> None:+ assert not is_synthetic_message(UserMessage(content=[TextContent(text="hi")]))+++def test_predicate_false_for_assistant_message() -> None:+ assert not is_synthetic_message(AssistantMessage(content=[TextContent(text="hi")]))+++def test_predicate_false_for_non_boolean_marker() -> None:+ msg = UserMessage(+ content=[TextContent(text="hi")],+ metadata={SYNTHETIC_METADATA_KEY: "yes"},+ )+ assert not is_synthetic_message(msg)+++def test_marker_survives_serialization_round_trip() -> None:+ """The marker must be data, not class identity: persistence (checkpointer,+ downstream APIs) round-trips through plain dicts."""+ original = synthetic_user_message("nudge", source="goal_continuation")+ restored = UserMessage.model_validate(original.model_dump())+ assert is_synthetic_message(restored)+ assert restored.metadata[SYNTHETIC_SOURCE_METADATA_KEY] == "goal_continuation"+++# ---------------------------------------------------------------------------+# Real user input must NOT be marked+# ---------------------------------------------------------------------------+++async def test_real_user_prompt_is_not_synthetic() -> None:+ provider = FauxProvider(provider_id="worker")+ provider.set_responses([faux_assistant_message("hello")])+ agent = Agent(model=provider.model("test"))++ await agent.prompt("real human input")++ user_messages = [m for m in agent.state.messages if isinstance(m, UserMessage)]+ assert user_messages+ assert not any(is_synthetic_message(m) for m in user_messages)+++# ---------------------------------------------------------------------------+# Goal middleware: continuation nudge is synthetic+# ---------------------------------------------------------------------------+++async def test_goal_continuation_message_is_synthetic() -> None:+ worker = FauxProvider(provider_id="worker")+ worker.set_responses(+ [+ faux_assistant_message("first attempt"),+ faux_assistant_message("second attempt"),+ ]+ )+ evaluator_provider = FauxProvider(provider_id="evaluator")+ evaluator_provider.set_responses(+ [+ faux_assistant_message(+ faux_tool_call(+ "structured_output",+ {"achieved": False, "reason": "not yet"},+ )+ ),+ faux_assistant_message(+ faux_tool_call(+ "structured_output",+ {"achieved": True, "reason": "done"},+ )+ ),+ ]+ )++ goal = GoalMiddleware(evaluator=evaluator_provider.model("eval"))+ agent = Agent(model=worker.model("test"), middleware=[goal])+ await agent.prompt("/goal all tests pass")++ continuations = [+ m+ for m in agent.state.messages+ if isinstance(m, UserMessage)+ and m.content+ and isinstance(m.content[0], TextContent)+ and m.content[0].text.startswith("Goal not yet met")+ ]+ assert continuations, "expected an injected goal continuation message"+ for msg in continuations:+ assert is_synthetic_message(msg)+ assert msg.metadata[SYNTHETIC_SOURCE_METADATA_KEY] == "goal_continuation"+++# ---------------------------------------------------------------------------+# Todo middleware: injected error/guard messages are synthetic+# ---------------------------------------------------------------------------+++def _todo_middleware(extra: dict[str, Any]) -> TodoListMiddleware:+ return TodoListMiddleware(extra_ref=lambda: extra)+++async def test_todo_parallel_write_todos_errors_are_synthetic() -> None:+ extra: dict[str, Any] = {}+ middleware = _todo_middleware(extra)++ response = faux_assistant_message(+ [+ faux_tool_call("write_todos", {"todos": []}),+ faux_tool_call("write_todos", {"todos": []}),+ ]+ )+ ctx = AgentContext(system_prompt="", messages=[], extra=extra)++ action = await middleware.after_model_response(response, ctx)++ assert action is not None and action.inject_messages+ for msg in action.inject_messages:+ assert is_synthetic_message(msg)+++async def test_todo_validation_errors_are_synthetic() -> None:+ extra: dict[str, Any] = {}+ middleware = _todo_middleware(extra)++ # Invalid payload: unfinished todo without any in_progress item.+ response = faux_assistant_message(+ faux_tool_call(+ "write_todos",+ {"todos": [{"content": "task", "status": "pending"}]},+ )+ )+ ctx = AgentContext(system_prompt="", messages=[], extra=extra)++ action = await middleware.after_model_response(response, ctx)++ assert action is not None and action.inject_messages+ for msg in action.inject_messages:+ assert is_synthetic_message(msg)+++async def test_todo_context_reminder_is_synthetic() -> None:+ extra: dict[str, Any] = {+ "todos": [{"content": "task", "status": "in_progress"}],+ }+ middleware = _todo_middleware(extra)+ history: list[Message] = [UserMessage(content=[TextContent(text="hi")])]+ ctx = AgentContext(system_prompt="", messages=history, extra=extra)++ transformed = await middleware.transform_context(list(history), ctx=ctx)++ appended = transformed[len(history) :]+ assert appended, "expected the todo reminder to be appended"+ for msg in appended:+ assert isinstance(msg, UserMessage)+ assert is_synthetic_message(msg)diff --git a/website/docs/guides/middleware/hooks.md b/website/docs/guides/middleware/hooks.mdindex cf49486..bde1e27 100644--- a/website/docs/guides/middleware/hooks.md+++ b/website/docs/guides/middleware/hooks.md@@ -170,15 +170,24 @@ hook returns a `TurnAction`:```pythonfrom cubepi.middleware.base import TurnAction-from cubepi.providers.base import UserMessage, TextContent+from cubepi.providers.base import synthetic_user_messageTurnAction(response=modified_message, # replace the message; None to keep- inject_messages=[UserMessage(...)], # extra messages to append before next turn+ inject_messages=[ # extra messages to append before next turn+ synthetic_user_message("…", source="my_middleware"),+ ],decision="natural", # "natural" | "stop" | "loop_to_model")```+Injected user-role messages **must** be built with+`synthetic_user_message(text, source=...)`, never with a bare+`UserMessage`. The factory stamps `metadata["synthetic"] = True` so+downstream consumers (UIs replaying history) can tell framework nudges+apart from messages the human actually typed; `source` is a free-form+tag for traces only. Check with `is_synthetic_message(msg)`.+Three control-flow knobs:- `decision="natural"` (default) — proceed to tool execution / next@@ -211,7 +220,9 @@ Fires **after each outer-loop iteration** — i.e. after all turns andtool calls complete before the loop would normally exit. Return anon-empty `list[Message]` to inject those messages into context andcontinue the loop (the agent runs again). Return `None` or `[]` to do-nothing (the loop exits).+nothing (the loop exits). As with `inject_messages`, build returned+user-role messages with `synthetic_user_message(...)` so they carry+the synthetic marker.This hook can fire **multiple times** per `prompt()` call. Each timethe middleware returns messages, the worker gets another run. Return