OpenAIResponsesCompactionAwareSession

Interface representing a persistent session store for conversation history.

Extends

Session

Methods

addItems()

addItems(items): Promise<void>;

Append new items to the conversation history.

Parameters

Parameter	Type	Description
`items`	`AgentInputItem`[]	Items to add to the session history.

Returns

Promise<void>

Inherited from

Session.addItems

clearSession()

clearSession(): Promise<void>;

Remove all items that belong to the session and reset its state.

Returns

Promise<void>

Inherited from

Session.clearSession

getItems()

getItems(limit?): Promise<AgentInputItem[]>;

Retrieve items from the conversation history.

Parameters

Parameter	Type	Description
`limit?`	`number`	The maximum number of items to return. When provided the most recent limit items should be returned in chronological order.

Returns

Promise<AgentInputItem[]>

Inherited from

Session.getItems

getSessionId()

getSessionId(): Promise<string>;

Ensure and return the identifier for this session.

Returns

Promise<string>

Inherited from

Session.getSessionId

popItem()

popItem(): Promise<
  | AgentInputItem
| undefined>;

Remove and return the most recent item from the conversation history if it exists.

Returns

Promise< | AgentInputItem | undefined>

Inherited from

Session.popItem

prepareHistoryItemForModelInput()?

optional prepareHistoryItemForModelInput(item): AgentInputItem;

Optionally 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.

Parameters

Parameter	Type
`item`	`AgentInputItem`

Returns

AgentInputItem

Inherited from

Session.prepareHistoryItemForModelInput

prepareHistoryItemsForPersistenceComparison()?

optional prepareHistoryItemsForPersistenceComparison(items): AgentInputItem[];

Optionally 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.

Parameters

Parameter	Type
`items`	`AgentInputItem`[]

Returns

AgentInputItem[]

Inherited from

Session.prepareHistoryItemsForPersistenceComparison

preserveReasoningItemIdsForPersistence()?

optional preserveReasoningItemIdsForPersistence(): boolean;

Optionally 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.

Returns

boolean

Inherited from

Session.preserveReasoningItemIdsForPersistence

replaceHistoryWithCompaction()?

optional replaceHistoryWithCompaction(items): Promise<void>;

Optionally 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.

Parameters

Parameter	Type
`items`	`AgentInputItem`[]

Returns

Promise<void>

Inherited from

Session.replaceHistoryWithCompaction

runCompaction()

runCompaction(args?, runContext?):
  | OpenAIResponsesCompactionResult
  | Promise<
  | OpenAIResponsesCompactionResult
  | null>
  | null;

Invoked by the runner after it persists a completed turn into the session.

Implementations may decide to call responses.compact (or an equivalent API) and replace the stored history.

This hook is best-effort. Implementations should consider handling transient failures and deciding whether to retry or skip compaction for the current turn.

Parameters

Parameter	Type
`args?`	`OpenAIResponsesCompactionArgs`
`runContext?`	`RunContext`<`any`>

Returns