Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

agent(history): freeze HistoryItem + lock byte-prefix property in tests

Saurav Panda8236cc750606
diff --git a/browser_use/agent/message_manager/views.py b/browser_use/agent/message_manager/views.py
index 1b11fbbc3..b4d7f1982 100644
--- a/browser_use/agent/message_manager/views.py
+++ b/browser_use/agent/message_manager/views.py
@@ -13,7 +13,12 @@ if TYPE_CHECKING:
class HistoryItem(BaseModel):
- """Represents a single agent history item with its data and string representation"""
+ """Represents a single agent history item with its data and string representation.
+
+ Frozen so that once appended to MessageManagerState.agent_history_items, the rendered
+ transcript prefix stays byte-identical across steps. This is what lets Gemini's implicit
+ cache (and similar caches) match the agent-history portion of the prompt step over step.
+ """
step_number: int | None = None
evaluation_previous_goal: str | None = None
@@ -23,7 +28,7 @@ class HistoryItem(BaseModel):
error: str | None = None
system_message: str | None = None
- model_config = ConfigDict(arbitrary_types_allowed=True)
+ model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
def model_post_init(self, __context) -> None:
"""Validate that error and system_message are not both provided"""
diff --git a/tests/ci/test_history_item_byte_stable.py b/tests/ci/test_history_item_byte_stable.py
new file mode 100644
index 000000000..97df5b267
--- /dev/null
+++ b/tests/ci/test_history_item_byte_stable.py
@@ -0,0 +1,91 @@
+"""Lock down the byte-prefix property of agent history serialization.
+
+For Gemini's implicit cache (and similar provider caches) to hit step over step,
+the rendered string for steps 1..N at step N+1 must be byte-identical to the
+rendered string for steps 1..N at step N. This file asserts:
+
+1. HistoryItem is frozen — once appended, no mutation can later shift its bytes.
+2. Rendering items[:N] is a strict byte-prefix of rendering items[:N+1] under
+ the join used by agent_history_description (newline-separated to_string()).
+3. to_string() is itself deterministic — same fields in, same bytes out.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from browser_use.agent.message_manager.views import HistoryItem
+
+
+def _render(items: list[HistoryItem]) -> str:
+ return '\n'.join(item.to_string() for item in items)
+
+
+def test_history_item_is_frozen():
+ item = HistoryItem(step_number=1, memory='m', next_goal='g', action_results='r')
+ with pytest.raises(ValidationError):
+ item.memory = 'mutated' # type: ignore[misc]
+
+
+def test_to_string_is_deterministic():
+ a = HistoryItem(
+ step_number=3,
+ evaluation_previous_goal='Verdict: Success',
+ memory='visited 2 pages',
+ next_goal='click Submit',
+ action_results='Action 1/1: clicked element 5',
+ )
+ b = HistoryItem(
+ step_number=3,
+ evaluation_previous_goal='Verdict: Success',
+ memory='visited 2 pages',
+ next_goal='click Submit',
+ action_results='Action 1/1: clicked element 5',
+ )
+ assert a.to_string() == b.to_string()
+
+
+def test_render_grows_by_strict_byte_prefix():
+ """The cache property: appending a new history item must extend the rendered string,
+ never rewrite earlier bytes."""
+ items: list[HistoryItem] = []
+ prev = ''
+ for n in range(1, 8):
+ items.append(
+ HistoryItem(
+ step_number=n,
+ evaluation_previous_goal=f'eval {n}',
+ memory=f'mem {n}',
+ next_goal=f'goal {n}',
+ action_results=f'Action 1/1: did thing {n}',
+ )
+ )
+ current = _render(items)
+ assert current.startswith(prev), (
+ f'Step {n} broke byte-prefix property.\nPrev tail: {prev[-200:]!r}\nCurrent at prev len: {current[: len(prev)][-200:]!r}'
+ )
+ prev = current
+
+
+def test_prefix_property_holds_with_mixed_entry_shapes():
+ """Errors, system messages, and full step entries should all preserve byte-prefix growth."""
+ items: list[HistoryItem] = [
+ HistoryItem(step_number=0, system_message='Agent initialized'),
+ HistoryItem(step_number=1, memory='m1', next_goal='g1', action_results='r1'),
+ HistoryItem(step_number=2, error='Agent failed to output in the right format.'),
+ HistoryItem(step_number=3, evaluation_previous_goal='eval', memory='m3', next_goal='g3', action_results='r3'),
+ HistoryItem(system_message='<follow_up_user_request> new task </follow_up_user_request>'),
+ HistoryItem(step_number=4, memory='m4', next_goal='g4', action_results='r4'),
+ ]
+ prev = ''
+ for n in range(1, len(items) + 1):
+ current = _render(items[:n])
+ assert current.startswith(prev), f'Mixed-shape prefix broke at n={n}'
+ prev = current
+
+
+def test_optional_fields_dont_silently_collapse():
+ """Conditional field inclusion in to_string() must not produce ambiguous output —
+ a None field today shouldn't render identically to a populated field tomorrow."""
+ with_memory = HistoryItem(step_number=1, memory='something', action_results='r').to_string()
+ without_memory = HistoryItem(step_number=1, action_results='r').to_string()
+ assert with_memory != without_memory, 'memory contribution to output collapsed to identity'