Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion python/packages/core/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID
- **`ContextProvider`** - Base class for context providers (RAG, memory systems)
- **`HistoryProvider`** - Base class for conversation history storage
- **`InMemoryHistoryProvider`** - Built-in session-state history provider for local runs
- **`FileHistoryProvider`** - Experimental append-only file-backed history provider; msgspec JSON Lines is the default and `serialization_format="msgpack"` uses length-prefixed binary MessagePack records. Custom `dumps`/`loads` remain as deprecated JSON-only compatibility hooks and emit `DeprecationWarning` when supplied.
- **`FileHistoryProvider`** - Experimental append-only file-backed history provider; msgspec JSON Lines is the default and `serialization_format="msgpack"` uses length-prefixed binary MessagePack records. Custom `dumps`/`loads` remain as deprecated JSON-only compatibility hooks and emit `DeprecationWarning` when supplied. A save whose incoming prefix covers the whole stored transcript also persists changed payloads for those stored messages, so in-place compaction annotations reach disk; the rewrite goes through a sibling temporary file and `os.replace`, and a rejected record leaves the previous file untouched. A shorter suffix replay still only appends.
- **Mixed computer/function workflow history** - The default `HistoryProvider.after_run` defers completed local
function results for loadable providers that store inputs until the computer reply arrives, so history records
them once in call order. Custom `after_run` implementations must handle this themselves.
Expand Down
133 changes: 126 additions & 7 deletions python/packages/core/agent_framework/_sessions.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
import logging
import math
import os
import stat
import threading
import time
import uuid
Expand All @@ -35,7 +36,7 @@
from functools import partial
from hashlib import sha256
from pathlib import Path
from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeAlias, TypeVar, cast
from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Literal, TypeAlias, TypeVar, cast

import msgspec
from typing_extensions import TypedDict
Expand Down Expand Up @@ -183,6 +184,31 @@ def _get_message_hash(message: Message) -> MessageIdentity:
return get_message_identity(message)


def _same_stored_payload(left: Any, right: Any) -> bool:
"""Return whether two serialized payloads are identical, including value types.

Plain ``==`` treats ``1`` and ``True`` (and ``1.0``) as equal, but JSON and
MessagePack store them differently, so a type-only change has to be persisted.
"""
if type(left) is not type(right):
return False
if isinstance(left, Mapping):
left_mapping = cast(Mapping[str, Any], left)
right_mapping = cast(Mapping[str, Any], right)
return left_mapping.keys() == right_mapping.keys() and all(
_same_stored_payload(left_mapping[key], right_mapping[key]) for key in left_mapping
)
if isinstance(left, list):
left_items = cast(list[Any], left)
right_items = cast(list[Any], right)
return len(left_items) == len(right_items) and all(
_same_stored_payload(a, b) for a, b in zip(left_items, right_items, strict=True)
)
if isinstance(left, float) and math.isnan(left):
return math.isnan(right)
return bool(left == right)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nan never equals itself, so once any stored message carries a NaN in additional_properties (a score, a usage metric) every replay counts it as changed and rewrites the whole file on each save. checked both json and msgpack, the inode changes on an identical replay

Suggested change
return bool(left == right)
if isinstance(left, float) and math.isnan(left):
return math.isnan(right)
return bool(left == right)

fixed this plus a test in this commit, you can just cherry pick it instead of redoing it: its-amann@829fa56

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Cherry-picked as ce986772184cd97e53b23b5ac416d540233d41f7, preserving the original commit and authorship.

Validation on that head:

  • The new JSON and MessagePack cases both pass: 2 passed, 212 deselected.
  • Removing the two-line NaN guard makes both cases fail with the inode changing on identical replay (pytest exit 1). I restored the production file byte for byte, verified its SHA256, and reran the cases successfully.
  • Full test_sessions.py: 214 passed.
  • Ruff check and format check pass on both changed files.
  • Pyright on _sessions.py: 0 errors.

The tests used Python 3.14.5, pytest 9.2.0, msgspec 0.22.0 and pydantic 2.14.1 in an existing non-iCloud environment, with agent_framework imported from this branch.



def filter_new_messages(existing: Sequence[Message], incoming: Sequence[Message]) -> list[Message]:
"""Return messages after the ordered overlap with persisted history.

Expand Down Expand Up @@ -2583,6 +2609,10 @@ class FileHistoryProvider(HistoryProvider):
The custom ``dumps`` and ``loads`` constructor arguments remain available
for JSON Lines compatibility but are deprecated.

New messages append. When a save replays the whole stored transcript with
changed payloads, for example after compaction annotated stored messages in
place, those records are updated too through an atomic replacement.

Security posture:
Persisted history is stored as plaintext JSONL or binary MessagePack on
the local filesystem.
Expand Down Expand Up @@ -2716,7 +2746,7 @@ async def save_messages(
state: dict[str, Any] | None = None,
**kwargs: Any,
) -> None:
"""Append messages to the session's history file."""
"""Append messages to the session's history file, persisting changed stored payloads."""
mark_feature_used(FeatureIndex.CORE_FILE_HISTORY_PROVIDER)
del state, kwargs
if not messages:
Expand All @@ -2731,14 +2761,23 @@ def _append_messages() -> None:
if self.serialization_format == "json":
existing_messages = self._read_json_messages(file_path) if file_path.exists() else []
new_messages = filter_new_messages(existing_messages, messages)
if new_messages:
with file_path.open("a", encoding="utf-8") as file_handle:
for message in new_messages:
file_handle.write(f"{self._serialize_json_message(message)}\n")
updated = self._updated_stored_messages(existing_messages, messages, new_messages)
if not new_messages and not updated:
return
if updated:
self._rewrite_json_messages(file_path, updated, new_messages)
return
with file_path.open("a", encoding="utf-8") as file_handle:
for message in new_messages:
file_handle.write(f"{self._serialize_json_message(message)}\n")
return
existing_messages = self._read_msgpack_messages(file_path) if file_path.exists() else []
new_messages = filter_new_messages(existing_messages, messages)
if not new_messages:
updated = self._updated_stored_messages(existing_messages, messages, new_messages)
if not new_messages and not updated:
return
if updated:
self._rewrite_msgpack_messages(file_path, updated, new_messages)
return
# Check the whole batch first so a record the reader would reject never reaches
# the file and the existing history stays loadable. Records are encoded into one
Expand All @@ -2764,6 +2803,86 @@ def _append_messages() -> None:
async with async_lock:
await asyncio.to_thread(_append_messages)

@staticmethod
def _updated_stored_messages(
existing: Sequence[Message], incoming: Sequence[Message], new_messages: Sequence[Message]
) -> list[Message] | None:
"""Return the transcript with updated stored payloads, or ``None`` when nothing changed.

Compaction excludes stored messages by annotating them in place, so the same
transcript can arrive again with updated ``additional_properties`` on messages
that are already on disk. ``filter_new_messages`` only reports the unseen tail,
which would leave those annotations unpersisted.

Only an exact overlap with the stored transcript is considered: the incoming
prefix must cover the whole stored history, so a partial replay that matched a
shorter suffix never rewrites records it did not carry. Payloads are compared as
serialized dicts, which is what the reader reconstructs.
"""
if not existing:
return None
stored_count = len(incoming) - len(new_messages)
if stored_count != len(existing):
return None
merged = list(existing)
changed = False
for index, message in enumerate(incoming[:stored_count]):
if not _same_stored_payload(message.to_dict(), existing[index].to_dict()):
merged[index] = message
changed = True
return merged if changed else None

def _rewrite_json_messages(
self, file_path: Path, merged: Sequence[Message], new_messages: Sequence[Message]
) -> None:
"""Replace the transcript atomically so a failed encode leaves the old file intact."""
serialized = "".join(
f"{self._serialize_json_message(message)}\n" for message in [*merged, *new_messages]
).encode("utf-8")
with self._staging_history_file(file_path) as stage:
stage.write(serialized)

def _rewrite_msgpack_messages(
self, file_path: Path, merged: Sequence[Message], new_messages: Sequence[Message]
) -> None:
"""Replace the transcript atomically after every record passes the reader's checks."""
record = bytearray()
# Encode into a sibling staging file so a rejected record never touches the history.
with self._staging_history_file(file_path) as stage:
for message in [*merged, *new_messages]:
self._encode_msgpack_record(message, record)
stage.write(len(record).to_bytes(self._MSGPACK_RECORD_HEADER_BYTES, "big"))
stage.write(record)

@staticmethod
@contextlib.contextmanager
def _staging_history_file(file_path: Path) -> Generator[BinaryIO]:
"""Yield a sibling staging file that replaces ``file_path`` on clean exit.

The name carries only a short prefix and a random token: a session ID may
already use most of the filesystem's component budget, so embedding the
history filename would push the staging name past it.

The staging file is created with the history's own access bits (or ``0600``
when it does not exist yet) so replacing a restricted transcript never
widens who can read it, regardless of the process umask.
"""
stage_path = file_path.with_name(f".history-{uuid.uuid4().hex}.tmp")
try:
mode = stat.S_IMODE(file_path.stat().st_mode)
except FileNotFoundError:
mode = 0o600
descriptor = os.open(stage_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
try:
with os.fdopen(descriptor, "wb") as stage:
yield stage
# os.open applies the umask, so set the intended bits explicitly.
os.chmod(stage_path, mode)
os.replace(stage_path, file_path)
finally:
with contextlib.suppress(FileNotFoundError):
stage_path.unlink()

def _encode_msgpack_record(self, message: Message, record: bytearray) -> None:
"""Encode ``message`` into ``record`` and reject it if the reader would refuse the record."""
_DEFAULT_MSGPACK_ENCODER.encode_into(message.to_dict(), record)
Expand Down
Loading
Loading