class DatabaseConversationStore implements ClaimsPendingApprovals, ConversationStore, PaginatesConversations, ResolvesPendingApprovals, StoresConversationTurns, VerifiesConversationOwnership

Constants

protected TURN_CONTEXT_KEY

Methods

__construct(string|null $connection = null)

Create a new conversation store instance.

string|null
latestConversationId(string $participantType, string|int $participantId, string $agent)

Get the participant's most recent conversation ID with the given agent.

bool
conversationBelongsTo(string $conversationId, string|null $participantType, string|int|null $participantId)

Determine whether the given conversation was stored for the given participant.

string
storeConversation(string|null $participantType, string|int|null $participantId, string $title, string|null $id = null)

Store a new conversation and return its ID.

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.

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.

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.

currentTurn(string $conversationId)

Get the turn whose transaction owns these writes.

MessageStatus
statusFor(AgentResponse $response, Throwable|null $exception)

Determine the status the turn is stored under, given how it ended.

array
metaFor(AgentResponse $response, Throwable|null $exception)

Build the meta the turn is stored under, carrying the error it died with.

object|null
pausedRowFor(string $conversationId, AgentPrompt $prompt)

Find the row the given resume paused on, matching the turn its decisions name.

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.

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.

stepsFor(AgentPrompt $prompt, AgentResponse $response)

Serialize the turn's steps, one entry per model round-trip.

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.

void
forgetReplayBlocks(string $conversationId)

Drop the raw provider blocks of the paused rows a now-completed turn resumed from.

withoutReplayBlocks(Collection $steps)

Drop the raw provider blocks from the given steps.

pendingReasonsFor(AgentResponse $response)

Get the reasons a response paused on, keyed by tool call ID.

array
decoded(string|null $json)

Decode a stored JSON column.

array
pausedCallIds(object $record)

Get the tool-call IDs a stored row is still awaiting a decision on.

array
gatedCallIds(object $record)

Get the IDs of a stored row's tool calls that were gated behind an approval.

pendingApprovalsIn(object $record)

Rebuild the approvals a stored row is still awaiting a decision on.

void
touchConversation(string $conversationId, mixed $timestamp)

Update the conversation's activity timestamp.

array
messageAttributes(string $messageId, string $conversationId, string|null $participantType, string|int|null $participantId, mixed $now, array $attributes)

Build the message row attributes.

getLatestConversationMessages(string $conversationId, int $limit)

Get the latest messages for the given conversation.

userMessageFrom(object $record)

Rebuild a stored user turn.

array
assistantTurnFrom(object $record)

Rebuild a stored assistant turn step by step, so every tool result answers the message that made its call.

interruptedResultFor(array $toolCall)

Build the result a failed turn's unanswered call replays with.

decodedSteps(object $record)

Decode a stored row's steps.

paginateConversationMessages(string $conversationId, int $perPage = 15, string $cursorName = 'cursor', Cursor|string|null $cursor = null)

Paginate the given conversation's messages, newest first.

array
pendingApprovalsFor(string $conversationId)

Get the tool calls the given conversation's newest turn is still waiting on.

rehydrateAttachments(string $attachments)

Rehydrate attachments from their stored JSON representation.

claimPendingApprovals(string $conversationId, array $toolCallIds)

Claim the paused turn matching the complete pending call set before any tools execute.

void
recordApprovalResult(ApprovalClaim $claim, ToolResult $result)

Record one tool outcome while its claim still owns the paused turn.

void
storeApprovalResults(string $conversationId, array $toolResults)

Durably record resolved approval results on the paused turn before the run continues.

stepsWithApprovalResults(object $row, array $toolResults)

Merge results into their original calls without overwriting recorded outcomes.

assistantRows(string $conversationId)

Query the conversation's assistant rows, newest first.

table(string $table)

Get a query builder for the given table using the configured connection.

array
partitionedAttributes(array $attributes)

Stamp raw store inserts with the current partition.

void
ensureWriteAllowed()

Allow specialized stores to reject writes without restricting reads.

string
conversationsTable()

Resolve the conversations table name from config.

string
messagesTable()

Resolve the messages table name from config.

Details

at line 53
__construct(string|null $connection = null)

Create a new conversation store instance.

Parameters

string|null $connection

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.

Parameters

string $participantType
string|int $participantId
string $agent

Return Value

string|null

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.

Parameters

string $conversationId
string|null $participantType
string|int|null $participantId

Return Value

bool

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.

Parameters

string|null $participantType
string|int|null $participantId
string $title
string|null $id

Return Value

string

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.

Parameters

string $conversationId
string|null $participantType
string|int|null $participantId
string $agent
UserMessage $message

Return Value

string

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.

Parameters

string $conversationId
string|null $participantType
string|int|null $participantId
AgentPrompt $prompt
AgentResponse $response
Throwable|null $exception

the error the run died with, when it did not finish

Return Value

string|null

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.

Parameters

string $conversationId
string|null $newConversationTitle
string|null $participantType
string|int|null $participantId
AgentPrompt $prompt
AgentResponse $response
Throwable|null $exception

Return Value

StoredTurn

at line 260
protected ConversationTurnState|null currentTurn(string $conversationId)

Get the turn whose transaction owns these writes.

Parameters

string $conversationId

Return Value

ConversationTurnState|null

at line 271
protected MessageStatus statusFor(AgentResponse $response, Throwable|null $exception)

Determine the status the turn is stored under, given how it ended.

Parameters

AgentResponse $response
Throwable|null $exception

Return Value

MessageStatus

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.

Parameters

AgentResponse $response
Throwable|null $exception

Return Value

array

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.

Parameters

string $conversationId
AgentPrompt $prompt

Return Value

object|null

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.

Parameters

string $conversationId
object $paused
AgentPrompt $prompt
AgentResponse $response
Throwable|null $exception

Return Value

string

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.

Parameters

object $paused
AgentResponse $response
Throwable|null $exception

Return Value

array

at line 387
protected Collection stepsFor(AgentPrompt $prompt, AgentResponse $response)

Serialize the turn's steps, one entry per model round-trip.

Parameters

AgentPrompt $prompt
AgentResponse $response

Return Value

Collection

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.

Parameters

iterable $toolCalls
iterable $toolResults
Collection $reasons

Return Value

array

at line 448
protected void forgetReplayBlocks(string $conversationId)

Drop the raw provider blocks of the paused rows a now-completed turn resumed from.

Parameters

string $conversationId

Return Value

void

at line 483
protected Collection withoutReplayBlocks(Collection $steps)

Drop the raw provider blocks from the given steps.

Parameters

Collection $steps

Return Value

Collection

at line 493
protected Collection pendingReasonsFor(AgentResponse $response)

Get the reasons a response paused on, keyed by tool call ID.

Parameters

AgentResponse $response

Return Value

Collection

at line 503
protected array decoded(string|null $json)

Decode a stored JSON column.

Parameters

string|null $json

Return Value

array

at line 513
protected array pausedCallIds(object $record)

Get the tool-call IDs a stored row is still awaiting a decision on.

Parameters

object $record

Return Value

array

at line 523
protected array gatedCallIds(object $record)

Get the IDs of a stored row's tool calls that were gated behind an approval.

Parameters

object $record

Return Value

array

at line 536
protected Collection pendingApprovalsIn(object $record)

Rebuild the approvals a stored row is still awaiting a decision on.

Parameters

object $record

Return Value

Collection

at line 551
protected void touchConversation(string $conversationId, mixed $timestamp)

Update the conversation's activity timestamp.

Parameters

string $conversationId
mixed $timestamp

Return Value

void

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.

Parameters

string $messageId
string $conversationId
string|null $participantType
string|int|null $participantId
mixed $now
array $attributes

Return Value

array

at line 591
Collection getLatestConversationMessages(string $conversationId, int $limit)

Get the latest messages for the given conversation.

Parameters

string $conversationId
int $limit

Return Value

Collection

at line 609
protected Message userMessageFrom(object $record)

Rebuild a stored user turn.

Parameters

object $record

Return Value

Message

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.

Parameters

object $record

Return Value

array

at line 669
protected ToolResult interruptedResultFor(array $toolCall)

Build the result a failed turn's unanswered call replays with.

Parameters

array $toolCall

Return Value

ToolResult

at line 685
protected Collection decodedSteps(object $record)

Decode a stored row's steps.

Parameters

object $record

Return Value

Collection

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.

Parameters

string $conversationId
int $perPage
string $cursorName
Cursor|string|null $cursor

Return Value

CursorPaginator

at line 715
array pendingApprovalsFor(string $conversationId)

Get the tool calls the given conversation's newest turn is still waiting on.

Parameters

string $conversationId

Return Value

array

at line 732
protected Collection rehydrateAttachments(string $attachments)

Rehydrate attachments from their stored JSON representation.

Parameters

string $attachments

Return Value

Collection

at line 761
ApprovalClaim|null claimPendingApprovals(string $conversationId, array $toolCallIds)

Claim the paused turn matching the complete pending call set before any tools execute.

Parameters

string $conversationId
array $toolCallIds

Return Value

ApprovalClaim|null

at line 821
void recordApprovalResult(ApprovalClaim $claim, ToolResult $result)

Record one tool outcome while its claim still owns the paused turn.

Parameters

ApprovalClaim $claim
ToolResult $result

Return Value

void

at line 851
void storeApprovalResults(string $conversationId, array $toolResults)

Durably record resolved approval results on the paused turn before the run continues.

Parameters

string $conversationId
array $toolResults

Return Value

void

Exceptions

ApprovalMismatchException

at line 899
protected Collection stepsWithApprovalResults(object $row, array $toolResults)

Merge results into their original calls without overwriting recorded outcomes.

Parameters

object $row
array $toolResults

Return Value

Collection

at line 924
protected Builder assistantRows(string $conversationId)

Query the conversation's assistant rows, newest first.

Parameters

string $conversationId

Return Value

Builder

at line 935
protected Builder table(string $table)

Get a query builder for the given table using the configured connection.

Parameters

string $table

Return Value

Builder

at line 949
protected array partitionedAttributes(array $attributes)

Stamp raw store inserts with the current partition.

Parameters

array $attributes

Return Value

array

at line 959
protected void ensureWriteAllowed()

Allow specialized stores to reject writes without restricting reads.

Return Value

void

at line 966
protected string conversationsTable()

Resolve the conversations table name from config.

Return Value

string

at line 974
protected string messagesTable()

Resolve the messages table name from config.

Return Value

string