Append new items to the conversation history.
Items to add to the session history.
Remove all items that belong to the session and reset its state.
Retrieve items from the conversation history.
Optionallimit: number
The maximum number of items to return. When provided the most recent limit items should be returned in chronological order.
Ensure and return the identifier for this session.
Remove and return the most recent item from the conversation history if it exists.
OptionalprepareOptionally rewrite a stored history item before it is sent back to the model.
Session implementations can use this to strip provider-managed replay metadata while
preserving their public getItems() shape for UI and deletion workflows.
OptionalprepareOptionally normalize stored and expected history before persistence reconciliation compares them.
Session implementations can use this to remove backend-assigned metadata while preserving
their public getItems() shape.
OptionalpreserveOptionally preserve reasoning item IDs when persisting generated output.
Some remote session stores require provider-assigned reasoning identities to accept stored reasoning items, even when model replay should omit those IDs.
OptionalreplaceOptionally replace the logical session history with a compaction marker and its retained suffix without resetting the session identity.
Implementations may append the replacement when their backend treats the leading compaction item as the authoritative replay boundary. If this method is absent, the runner falls back to clearing and rebuilding the session with rollback protection.
Optional session capability for atomic, idempotent history changes.
Implementations must persist the operation identifier and history change atomically. Repeating an operation identifier with the same transaction must succeed without applying the transaction again. Reusing an operation identifier with a different transaction, or attempting to replace a suffix that does not match, must fail without changing history.
Implementations may reject item metadata that cannot be snapshotted and compared deterministically, but must do so before changing history or recording the operation identifier.