HistoryStore
Defined in: packages/engine/src/lib/history/history-store.ts:55
Backing persistence for HistoryManager. The engine ships an in-memory reference implementation; production deployments provide their own (Redis, Postgres, SQLite, etc.).
Implementations MUST guarantee that append is atomic with respect
to concurrent calls sharing the same (sessionId, entry.input.id) pair —
exactly one wins and the duplicate reports { inserted: false }. In
single-process JavaScript this is free; in multi-process deployments use
the backend’s native primitives (INSERT OR IGNORE, ON CONFLICT DO NOTHING,
Redis SETNX, etc.).
Type Parameters
Section titled “Type Parameters”TMeta = unknown
Methods
Section titled “Methods”append()
Section titled “append()”append(
sessionId,entry):Promise<{inserted:boolean; }>
Defined in: packages/engine/src/lib/history/history-store.ts:60
Atomically check-and-insert. Returns { inserted: false } if an entry
with the same MessageId already exists in the given session.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”SessionId
HistoryEntry<TMeta>
Returns
Section titled “Returns”Promise<{ inserted: boolean; }>
clear()
Section titled “clear()”clear(
sessionId):Promise<void>
Defined in: packages/engine/src/lib/history/history-store.ts:75
Wipes all entries for a session. No-op on an unknown session.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”SessionId
Returns
Section titled “Returns”Promise<void>
get(
sessionId):Promise<readonlyHistoryEntry<TMeta>[]>
Defined in: packages/engine/src/lib/history/history-store.ts:66
Returns all entries for a session in insertion order.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”SessionId
Returns
Section titled “Returns”Promise<readonly HistoryEntry<TMeta>[]>
getResponseById()
Section titled “getResponseById()”getResponseById(
sessionId,messageId):Promise<GetResponseByIdResult>
Defined in: packages/engine/src/lib/history/history-store.ts:90
Point-lookup of a previously recorded turn’s response.
Returns one of three semantically distinct outcomes (see
GetResponseByIdResult). The engine’s replay path treats miss
and kind-mismatch identically (both fall through to a fresh LLM
call), but the type-level distinction lets the consumer decide what
to do about a messageId reuse across kinds — surface it as a
warning, page on it, etc. Stores backed by a remote backend should
implement this against backend-native point-lookup primitives (Redis
HGET, Postgres SELECT response WHERE …) to avoid materializing
the full HistoryEntry.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”SessionId
messageId
Section titled “messageId”MessageId
Returns
Section titled “Returns”Promise<GetResponseByIdResult>
replace()
Section titled “replace()”replace(
sessionId,entries):Promise<void>
Defined in: packages/engine/src/lib/history/history-store.ts:69
Overwrites the session’s entry list. Used by truncation.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”SessionId
entries
Section titled “entries”readonly HistoryEntry<TMeta>[]
Returns
Section titled “Returns”Promise<void>