Skip to content

Agent Zero AI framework

Preserve commentary in native Responses history replay

Alessandro9ef8db9a3c7c
diff --git a/helpers/responses_history.py b/helpers/responses_history.py
index 6851ff87d..8b31cf33c 100644
--- a/helpers/responses_history.py
+++ b/helpers/responses_history.py
@@ -95,6 +95,21 @@ def _contains_secret(value: Any, mask: Callable[[str], str]) -> bool:
return False
+def _replayable_output(item: dict) -> bool:
+ if item.get("type") == "function_call":
+ return _json_object(item.get("arguments")) is not None
+ if item.get("type") == "reasoning":
+ return isinstance(item.get("encrypted_content"), str) and bool(item["encrypted_content"])
+ content = item.get("content")
+ return (
+ item.get("type") == "message" and item.get("role") == "assistant"
+ and item.get("phase") == "commentary" and item.get("status") in (None, "completed")
+ and isinstance(content, list) and bool(content)
+ and all(isinstance(block, dict) and block.get("type") == "output_text"
+ and isinstance(block.get("text"), str) for block in content)
+ )
+
+
def prepare_groups(
records: list[dict], render: Callable[[dict], Any], mask: Callable[[str], str]
) -> list[dict]:
@@ -110,18 +125,7 @@ def prepare_groups(
if not prefix_hash or not calls:
continue
output = [item.to_dict() for item in result.output_items]
- if any(item.get("type") not in {"function_call", "reasoning"} for item in output):
- continue
- if any(
- item.get("type") == "reasoning"
- and (not isinstance(item.get("encrypted_content"), str) or not item["encrypted_content"])
- for item in output
- ):
- continue
- if any(
- _json_object(item.get("arguments")) is None
- for item in output if item.get("type") == "function_call"
- ):
+ if not all(_replayable_output(item) for item in output):
continue
try:
if _contains_secret(output, mask) or _contains_secret([call.arguments for call in calls], mask):
diff --git a/helpers/responses_history.py.dox.md b/helpers/responses_history.py.dox.md
index 586ddd703..f7a7f0991 100644
--- a/helpers/responses_history.py.dox.md
+++ b/helpers/responses_history.py.dox.md
@@ -11,7 +11,8 @@
- Persist only `history_prefix_hash` in existing result capability metadata, never copies of old prompt inputs or a diagnostic replay counter. Hash system, protocol and prepared history; retain freshly prepared extras in each request.
- Require canonical visible arguments, original unique call IDs, immediately paired result records, compatible local Responses state and unchanged prefix/scope. Legacy records without digests stay as text.
-- Replay only function calls and encrypted reasoning, with original provider items. Reject known unmasked secrets, textual follow-ups, unsupported items, incomplete pairs and non-text result layouts.
+- Replay function calls, encrypted reasoning and explicitly tagged assistant commentary with text-only content, preserving original provider items and phase. Reject final/unmarked messages, refusals, incomplete commentary, known unmasked secrets, unsupported items, incomplete pairs and non-text result layouts.
+- This helper is a transport adapter over generic rendered records and metadata. Shared history storage/rendering remains API-agnostic; replay only changes copied provider input.
- Build tool outputs from visible rendered result content, preserving additional fields. Never restore raw tool output metadata or invent a final response-tool result.
- Preserve summaries, unmatched/custom layouts, attachments and all remaining prepared input. No execution or policy authorization occurs here.
- Internal history context is removed before every provider request; Chat and fallback messages remain untouched.
diff --git a/tests/test_responses_history.py b/tests/test_responses_history.py
index 3e64f8d72..da48032ec 100644
--- a/tests/test_responses_history.py
+++ b/tests/test_responses_history.py
@@ -4,12 +4,15 @@ import json
import pytest
from helpers import responses_history as history
-from helpers.llm_result import LLMResult
+from helpers.llm_result import LLMResult, ResponseItem
from helpers.litellm_transport import LiteLLMTransport, clear_transport_capability_cache
TOOLS = [{"type": "function", "name": "lookup", "parameters": {"type": "object", "properties": {}}}]
BASE = [{"role": "system", "content": "Rules"}, {"role": "user", "content": "Question"}]
+COMMENTARY = {"type": "message", "id": "msg_progress", "role": "assistant",
+ "phase": "commentary", "status": "completed",
+ "content": [{"type": "output_text", "text": "The result points to a parsing issue."}]}
@pytest.fixture(autouse=True)
@@ -74,6 +77,46 @@ def test_native_replay_uses_visible_results_and_retains_current_extras():
assert prompt == prompt_for(records)
+def test_commentary_replay_preserves_phase_native_items_and_generic_history():
+ result = completed_call(transport(BASE, BASE))
+ result.output_items.insert(1, ResponseItem.from_any(deepcopy(COMMENTARY)))
+ records = records_for(result)
+ original = deepcopy(records)
+ prompt = prompt_for(records)
+ replay = transport(prompt, prompt, records)
+ request = replay._responses_request(stream=False)
+ assert request["input"][2:5] == [item.to_dict() for item in result.output_items]
+ assert request["input"][5]["call_id"] == "call_1"
+ assert request["input"][5]["output"] == render(records[1])
+ assert request["input"][6] == {"role": "user", "content": "Current extras"}
+ assert records == original and prompt == prompt_for(records)
+ assert replay._chat_request(stream=False)["messages"] == prompt
+
+
[email protected]("change", ["unmarked", "final", "role", "incomplete", "empty", "refusal", "secret"])
+def test_ineligible_commentary_keeps_prepared_history(change):
+ result = completed_call(transport(BASE, BASE))
+ item = deepcopy(COMMENTARY)
+ mask = lambda text: text
+ if change == "unmarked":
+ item.pop("phase")
+ elif change == "final":
+ item["phase"] = "final_answer"
+ elif change == "role":
+ item["role"] = "user"
+ elif change == "incomplete":
+ item["status"] = "incomplete"
+ elif change == "empty":
+ item["content"] = []
+ elif change == "refusal":
+ item["content"].append({"type": "refusal", "refusal": "Not a progress update"})
+ elif change == "secret":
+ mask = lambda text: text.replace("parsing", "MASKED")
+ result.output_items.insert(1, ResponseItem.from_any(item))
+ records = records_for(result)
+ assert history.prepare_groups(records, render, mask) == []
+
+
def test_prepared_context_lifecycle_and_post_hook_changes(monkeypatch):
from types import SimpleNamespace
from langchain_core.messages import SystemMessage, HumanMessage