DatabaseConversationStore
class DatabaseConversationStore implements ClaimsPendingApprovals, ConversationStore, PaginatesConversations, ResolvesPendingApprovals, StoresConversationTurns, VerifiesConversationOwnership
Constants
| protected TURN_CONTEXT_KEY |
|
Methods
Create a new conversation store instance.
Get the participant's most recent conversation ID with the given agent.
Determine whether the given conversation was stored for the given participant.
Store a new conversation and return its ID.
Store a new user message for the given conversation and return its ID.
Store the assistant turn for the given conversation, folding a resumed run into the row it paused on.
Commit the conversation and both sides of a turn with one activity update.
Get the turn whose transaction owns these writes.
Determine the status the turn is stored under, given how it ended.
Build the meta the turn is stored under, carrying the error it died with.
Find the row the given resume paused on, matching the turn its decisions name.
Append the steps a resumed run made to the row its turn paused on.
Keep the citations the paused half of the turn collected, under the resuming provider and model.
Serialize the turn's steps, one entry per model round-trip.
Pair a step's tool calls with the results they were answered by, marking those awaiting approval with their reason.
Drop the raw provider blocks of the paused rows a now-completed turn resumed from.
Get the reasons a response paused on, keyed by tool call ID.
Decode a stored JSON column.
Get the tool-call IDs a stored row is still awaiting a decision on.
Get the IDs of a stored row's tool calls that were gated behind an approval.
Rebuild the approvals a stored row is still awaiting a decision on.
Update the conversation's activity timestamp.
Build the message row attributes.
Get the latest messages for the given conversation.
Rebuild a stored user turn.
Rebuild a stored assistant turn step by step, so every tool result answers the message that made its call.
Build the result a failed turn's unanswered call replays with.
Decode a stored row's steps.
Paginate the given conversation's messages, newest first.
Get the tool calls the given conversation's newest turn is still waiting on.
Rehydrate attachments from their stored JSON representation.
Claim the paused turn matching the complete pending call set before any tools execute.
Record one tool outcome while its claim still owns the paused turn.
Durably record resolved approval results on the paused turn before the run continues.
Merge results into their original calls without overwriting recorded outcomes.
Query the conversation's assistant rows, newest first.
Get a query builder for the given table using the configured connection.
Stamp raw store inserts with the current partition.
Allow specialized stores to reject writes without restricting reads.
Resolve the conversations table name from config.
Resolve the messages table name from config.
Details
at line 53
__construct(string|null $connection = null)
Create a new conversation store instance.
at line 62
string|null
latestConversationId(string $participantType, string|int $participantId, string $agent)
Get the participant's most recent conversation ID with the given agent.
at line 75
bool
conversationBelongsTo(string $conversationId, string|null $participantType, string|int|null $participantId)
Determine whether the given conversation was stored for the given participant.
at line 93
string
storeConversation(string|null $participantType, string|int|null $participantId, string $title, string|null $id = null)
Store a new conversation and return its ID.
at line 117
string
storeUserMessage(string $conversationId, string|null $participantType, string|int|null $participantId, string $agent, UserMessage $message)
Store a new user message for the given conversation and return its ID.
at line 145
string|null
storeAssistantMessage(string $conversationId, string|null $participantType, string|int|null $participantId, AgentPrompt $prompt, AgentResponse $response, Throwable|null $exception = null)
Store the assistant turn for the given conversation, folding a resumed run into the row it paused on.
at line 210
StoredTurn
storeTurn(string $conversationId, string|null $newConversationTitle, string|null $participantType, string|int|null $participantId, AgentPrompt $prompt, AgentResponse $response, Throwable|null $exception = null)
Commit the conversation and both sides of a turn with one activity update.
at line 260
protected ConversationTurnState|null
currentTurn(string $conversationId)
Get the turn whose transaction owns these writes.
at line 271
protected MessageStatus
statusFor(AgentResponse $response, Throwable|null $exception)
Determine the status the turn is stored under, given how it ended.
at line 285
protected array
metaFor(AgentResponse $response, Throwable|null $exception)
Build the meta the turn is stored under, carrying the error it died with.
at line 295
protected object|null
pausedRowFor(string $conversationId, AgentPrompt $prompt)
Find the row the given resume paused on, matching the turn its decisions name.
at line 323
protected string
resumePausedRow(string $conversationId, object $paused, AgentPrompt $prompt, AgentResponse $response, Throwable|null $exception = null)
Append the steps a resumed run made to the row its turn paused on.
at line 374
protected array
mergedMeta(object $paused, AgentResponse $response, Throwable|null $exception = null)
Keep the citations the paused half of the turn collected, under the resuming provider and model.
at line 387
protected Collection
stepsFor(AgentPrompt $prompt, AgentResponse $response)
Serialize the turn's steps, one entry per model round-trip.
at line 423
protected array
toolCallsFor(iterable $toolCalls, iterable $toolResults, Collection $reasons)
Pair a step's tool calls with the results they were answered by, marking those awaiting approval with their reason.
at line 448
protected void
forgetReplayBlocks(string $conversationId)
Drop the raw provider blocks of the paused rows a now-completed turn resumed from.
at line 483
protected Collection
withoutReplayBlocks(Collection $steps)
Drop the raw provider blocks from the given steps.
at line 493
protected Collection
pendingReasonsFor(AgentResponse $response)
Get the reasons a response paused on, keyed by tool call ID.
at line 503
protected array
decoded(string|null $json)
Decode a stored JSON column.
at line 513
protected array
pausedCallIds(object $record)
Get the tool-call IDs a stored row is still awaiting a decision on.
at line 523
protected array
gatedCallIds(object $record)
Get the IDs of a stored row's tool calls that were gated behind an approval.
at line 536
protected Collection
pendingApprovalsIn(object $record)
Rebuild the approvals a stored row is still awaiting a decision on.
at line 551
protected void
touchConversation(string $conversationId, mixed $timestamp)
Update the conversation's activity timestamp.
at line 574
protected array
messageAttributes(string $messageId, string $conversationId, string|null $participantType, string|int|null $participantId, mixed $now, array $attributes)
Build the message row attributes.
at line 591
Collection
getLatestConversationMessages(string $conversationId, int $limit)
Get the latest messages for the given conversation.
at line 609
protected Message
userMessageFrom(object $record)
Rebuild a stored user turn.
at line 623
protected array
assistantTurnFrom(object $record)
Rebuild a stored assistant turn step by step, so every tool result answers the message that made its call.
at line 669
protected ToolResult
interruptedResultFor(array $toolCall)
Build the result a failed turn's unanswered call replays with.
at line 685
protected Collection
decodedSteps(object $record)
Decode a stored row's steps.
at line 701
CursorPaginator
paginateConversationMessages(string $conversationId, int $perPage = 15, string $cursorName = 'cursor', Cursor|string|null $cursor = null)
Paginate the given conversation's messages, newest first.
at line 715
array
pendingApprovalsFor(string $conversationId)
Get the tool calls the given conversation's newest turn is still waiting on.
at line 732
protected Collection
rehydrateAttachments(string $attachments)
Rehydrate attachments from their stored JSON representation.
at line 761
ApprovalClaim|null
claimPendingApprovals(string $conversationId, array $toolCallIds)
Claim the paused turn matching the complete pending call set before any tools execute.
at line 821
void
recordApprovalResult(ApprovalClaim $claim, ToolResult $result)
Record one tool outcome while its claim still owns the paused turn.
at line 851
void
storeApprovalResults(string $conversationId, array $toolResults)
Durably record resolved approval results on the paused turn before the run continues.
at line 899
protected Collection
stepsWithApprovalResults(object $row, array $toolResults)
Merge results into their original calls without overwriting recorded outcomes.
at line 924
protected Builder
assistantRows(string $conversationId)
Query the conversation's assistant rows, newest first.
at line 935
protected Builder
table(string $table)
Get a query builder for the given table using the configured connection.
at line 949
protected array
partitionedAttributes(array $attributes)
Stamp raw store inserts with the current partition.
at line 959
protected void
ensureWriteAllowed()
Allow specialized stores to reject writes without restricting reads.
at line 966
protected string
conversationsTable()
Resolve the conversations table name from config.
at line 974
protected string
messagesTable()
Resolve the messages table name from config.