Skip to content

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

feat: unified synthetic marker for framework-injected user messages

xf gong87a302840e39
diff --git a/cubepi/__init__.py b/cubepi/__init__.py
index 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__.py
index 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_tokens
from 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.py
index 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_state
return [
- 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.py
index 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, TurnAction
from 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"] = True
return 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"] = None
return 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 = 0
diff --git a/cubepi/providers/__init__.py b/cubepi/providers/__init__.py
index 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.py
index 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: str
description: 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"
+ ),
]
break
else:
diff --git a/tests/test_synthetic_messages.py b/tests/test_synthetic_messages.py
new file mode 100644
index 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.md
index 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`:
```python
from cubepi.middleware.base import TurnAction
-from cubepi.providers.base import UserMessage, TextContent
+from cubepi.providers.base import synthetic_user_message
TurnAction(
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 and
tool calls complete before the loop would normally exit. Return a
non-empty `list[Message]` to inject those messages into context and
continue 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 time
the middleware returns messages, the worker gets another run. Return