bodhi-realtime-agent / ConversationContext
Class: ConversationContext
Defined in: src/core/conversation-context.ts:22
In-memory conversation timeline that tracks all messages, tool calls, and agent transfers.
Key concepts:
- Items: Append-only list of ConversationItems (user messages, assistant messages, tool events, transfers).
- Checkpoint: A cursor into the items list.
getItemsSinceCheckpoint()returns only new items since the last checkpoint. Used by ConversationHistoryWriter and MemoryDistiller to process incremental batches. - Summary: A compressed representation of older conversation turns. When set via
setSummary(), items before the checkpoint are evicted (they're captured in the summary). - Token estimate: Rough heuristic (
content.length / 4) used to decide when to trigger summarization.
Constructors
Constructor
new ConversationContext():
ConversationContext
Returns
ConversationContext
Accessors
hasPendingUserMessages
Get Signature
get hasPendingUserMessages():
boolean
Defined in: src/core/conversation-context.ts:92
True while any reserved user message is still awaiting its transcript.
Returns
boolean
items
Get Signature
get items(): readonly
ConversationItem[]
Defined in: src/core/conversation-context.ts:30
Returns
readonly ConversationItem[]
summary
Get Signature
get summary():
string|null
Defined in: src/core/conversation-context.ts:34
Returns
string | null
tokenEstimate
Get Signature
get tokenEstimate():
number
Defined in: src/core/conversation-context.ts:39
Rough token count estimate for all items + summary (content.length / 4).
Returns
number
Methods
addAgentTransfer()
addAgentTransfer(
fromAgent,toAgent):void
Defined in: src/core/conversation-context.ts:132
Parameters
fromAgent
string
toAgent
string
Returns
void
addAssistantMessage()
addAssistantMessage(
content):void
Defined in: src/core/conversation-context.ts:112
Parameters
content
string
Returns
void
addToolCall()
addToolCall(
call):void
Defined in: src/core/conversation-context.ts:116
Parameters
call
Returns
void
addToolResult()
addToolResult(
result):void
Defined in: src/core/conversation-context.ts:124
Parameters
result
Returns
void
addUserMessage()
addUserMessage(
content):void
Defined in: src/core/conversation-context.ts:50
Parameters
content
string
Returns
void
clear()
clear():
number
Defined in: src/core/conversation-context.ts:182
Drop every item and start the timeline over: the checkpoint returns to 0 and all pending reservations are forgotten, so the next item added is the first one getItemsSinceCheckpoint() returns. The summary is kept. Persist anything still unflushed before calling this; it discards items whether or not a history store has seen them.
Returns
number
The number of items removed.
getItemsSinceCheckpoint()
getItemsSinceCheckpoint():
ConversationItem[]
Defined in: src/core/conversation-context.ts:145
Return items added since the last checkpoint, stopping before the first still-pending user message (see reserveUserMessage) so provisional text is never handed to a history store.
Returns
getSubagentContext()
getSubagentContext(
task,agentInstructions,memoryFacts,recentTurnCount?,knowledgeBaseContext?):SubagentContextSnapshot
Defined in: src/core/conversation-context.ts:199
Build a snapshot of conversation state for a subagent (summary + recent turns + memory).
Parameters
task
agentInstructions
string
memoryFacts
recentTurnCount?
number = 10
knowledgeBaseContext?
string
Returns
loadItems()
loadItems(
items,opts?):void
Defined in: src/core/conversation-context.ts:164
Load existing items (e.g. when resuming from persisted history). Appends to the timeline. By default (and with alreadyPersisted: true) advances the checkpoint so these items are not re-flushed by ConversationHistoryWriter — appropriate when they already live in the store (e.g. attach-mode resume). Pass { alreadyPersisted: false } to leave the checkpoint in place so the writer re-persists the loaded items into a fresh record (copy-mode resume).
Parameters
items
opts?
alreadyPersisted?
boolean
Returns
void
markCheckpoint()
markCheckpoint():
void
Defined in: src/core/conversation-context.ts:152
Advance the checkpoint cursor past everything getItemsSinceCheckpoint just returned — i.e. up to, but not past, the first pending user message.
Returns
void
pendingUserMessageIds()
pendingUserMessageIds():
string[]
Defined in: src/core/conversation-context.ts:97
Ids of all still-unsealed reservations, oldest first.
Returns
string[]
reserveUserMessage()
reserveUserMessage(
provisionalContent):string
Defined in: src/core/conversation-context.ts:66
Append a user message whose authoritative transcript has not arrived yet.
The slot is inserted in timeline order immediately (so replay and history keep correct interleaving with assistant/tool items) but holds only provisional text. Until sealUserMessage resolves it, the slot acts as a barrier in getItemsSinceCheckpoint() — history stores never observe the provisional text, so a persisted record is written once, already correct. toReplayContent() is unaffected and always reads the current best text.
Parameters
provisionalContent
string
Returns
string
The id to pass to sealUserMessage.
sealUserMessage()
sealUserMessage(
id,finalContent?):boolean
Defined in: src/core/conversation-context.ts:81
Resolve a reserved user message and release the flush barrier.
Parameters
id
string
finalContent?
string
Authoritative transcript. Omit (or pass empty) to seal with the provisional text already in the slot — the fallback used when the authoritative source fails or times out.
Returns
boolean
false if the id is unknown or already sealed.
setSummary()
setSummary(
summary):void
Defined in: src/core/conversation-context.ts:191
Store a compressed summary and evict all items before the current checkpoint.
Parameters
summary
string
Returns
void
toReplayContent()
toReplayContent(
opts?):ReplayItem[]
Defined in: src/core/conversation-context.ts:224
Format the conversation as provider-neutral ReplayItem[] for replay (reconnect recovery or resume). A malformed tool row (unparseable JSON, or missing toolCallId/toolName) is dropped and logged (metadata-only — never the row's content) rather than demoted to assistant text, so the emitted list enforces the same validity the transport replay expects. Errored tool results carry their error string through.
Parameters
opts?
log?
(msg) => void