perf: persist remote runtime events in one transaction per checkpoint

Remote semantic events were written with one or two synchronous SQLite transactions each before being forwarded; recoverable conversations also rewrote the whole assistant message per event. Events now commit together at each remote checkpoint (before the Agent can acknowledge), and before non-remote, question and terminal events, on a size cap or a 50 ms timer. Only newly stored events are forwarded, in order; a failed batch rolls back and blocks later commits. Applies to interactive, background and recovery runs.
This commit is contained in:
mesalogo
2026-10-02 23:11:11 +08:00
parent 855b941aeb
commit d859cbfdeb
6 changed files with 1087 additions and 275 deletions
@@ -4103,6 +4103,204 @@ describe('AssistantDatabase', () => {
raw.close()
})
describe('remote conversation event batches', () => {
const conversationId = '00000000-0000-4000-8000-000000000711'
const taskId = '00000000-0000-4000-8000-000000000712'
const assistantMessageId = '00000000-0000-4000-8000-000000000714'
type BatchEvent = Parameters<
AssistantDatabase['appendRemoteConversationTaskEventsBatch']
>[0]['events'][number]
const openRecoverableTask = (): AssistantDatabase => {
const database = new AssistantDatabase(':memory:')
database.initialize('C:\\Workspace')
const project = database.createSshProject(validatedSshProjectWrite())
database.saveLocalConversations([{
header: { id: conversationId, projectId: project.id, title: '批量', updatedAt: 0 },
messages: []
}])
database.createTask({
id: taskId, projectId: project.id, conversationId,
title: '批量', instructions: '回复', workMode: 'execute',
remoteRecovery: {
recoverable: true,
currentUserMessageId: '00000000-0000-4000-8000-000000000713',
currentAssistantMessageId: assistantMessageId
}
})
return database
}
const entry = (
semanticSequence: string,
eventIndex: number,
event: BatchEvent['event']
): BatchEvent => ({
bindingId: 'batch-binding', operationId: taskId,
semanticSequence, eventIndex, event
})
const taskEvents = (database: AssistantDatabase, id = taskId) =>
((database as unknown as { requireDatabase(): DatabaseSync }).requireDatabase()
.prepare('SELECT kind, payload_json FROM task_events WHERE task_id = ? AND remote_semantic_sequence IS NOT NULL ORDER BY id')
.all(id) as Array<{ kind: string; payload_json: string }>)
.map(({ kind, payload_json }) => ({ kind, payload: JSON.parse(payload_json) as unknown }))
const page: BatchEvent[] = [
entry('1', 0, { requestId: taskId, type: 'reasoning', delta: 'plan ' }),
entry('1', 1, { requestId: taskId, type: 'text', delta: 'Hello' }),
entry('1', 2, { requestId: taskId, type: 'remote-semantic-checkpoint' }),
entry('2', 0, {
requestId: taskId, type: 'tool', callId: 'read', name: 'Read',
state: 'running', summary: 'Read file', input: '{"path":"a"}'
}),
entry('2', 1, { requestId: taskId, type: 'status', message: 'working' }),
entry('2', 2, {
requestId: taskId, type: 'context-metrics', contextTokens: 77,
effectiveTriggerTokens: 1000, compressionEnabled: false, source: 'provider'
}),
entry('2', 3, { requestId: taskId, type: 'remote-semantic-checkpoint' }),
entry('3', 0, {
requestId: taskId, type: 'tool', callId: 'read', name: 'Read',
state: 'completed', summary: 'Read file', output: 'contents'
}),
entry('3', 1, { requestId: taskId, type: 'text', delta: ' world' }),
entry('3', 2, { requestId: taskId, type: 'reasoning', delta: 'done' }),
entry('3', 3, { requestId: taskId, type: 'done', sessionId: 'session' }),
entry('3', 4, { requestId: taskId, type: 'remote-semantic-checkpoint' })
]
const owner = { taskId, conversationId, assistantMessageId }
// Block ids are random per reduction; compare everything else.
const comparable = (database: AssistantDatabase) => {
const conversation = database.getConversation(conversationId)
const message = conversation.messages.find(
(candidate) => candidate.id === assistantMessageId
)!
return {
message: {
...message,
createdAt: undefined,
blocks: message.blocks?.map((block) => ({ ...block, id: undefined }))
},
contextMetrics: conversation.contextMetrics,
status: database.getTask(taskId).status,
error: database.getTask(taskId).error,
events: taskEvents(database),
cursor: database.getHighestCommittedRemoteTaskEventSequenceForTask(taskId)
}
}
it('matches sequential per-event persistence with one message rewrite and terminalizes at its checkpoint', () => {
const sequential = openRecoverableTask()
const batched = openRecoverableTask()
try {
for (const item of page) {
expect(sequential.appendRemoteConversationTaskEventOnce({ ...owner, ...item })).toBe(true)
}
const prepare = vi.spyOn(
(batched as unknown as { requireDatabase(): DatabaseSync }).requireDatabase(),
'prepare'
)
expect(batched.appendRemoteConversationTaskEventsBatch({ ...owner, events: page }))
.toEqual(page.map(() => true))
const statements = prepare.mock.calls.map(([sql]) => sql.replace(/\s+/gu, ' ').trim())
prepare.mockRestore()
expect(statements.filter((sql) => sql.startsWith('UPDATE messages'))).toHaveLength(1)
expect(statements.filter((sql) => sql.startsWith('SELECT id, role, content'))).toHaveLength(1)
expect(statements.filter((sql) => sql.startsWith('UPDATE conversations'))).toHaveLength(1)
expect(comparable(batched)).toEqual(comparable(sequential))
expect(comparable(batched)).toMatchObject({
message: {
content: 'Hello world', reasoning: 'plan done', state: 'complete',
tools: [expect.objectContaining({ callId: 'read', state: 'completed' })]
},
contextMetrics: expect.objectContaining({ contextTokens: 77 }),
status: 'completed',
cursor: '3'
})
} finally {
sequential.close()
batched.close()
}
})
it('deduplicates replayed events within and across batches and keeps their order', () => {
const database = openRecoverableTask()
try {
expect(database.appendRemoteConversationTaskEventsBatch({
...owner, events: page.slice(0, 3)
})).toEqual([true, true, true])
// A reconnect replays page 1 before delivering page 2.
expect(database.appendRemoteConversationTaskEventsBatch({
...owner, events: [...page.slice(0, 3), ...page.slice(3, 7)]
})).toEqual([false, false, false, true, true, true, true])
expect(database.appendRemoteConversationTaskEventsBatch({
...owner, events: page.slice(0, 7)
})).toEqual(page.slice(0, 7).map(() => false))
const message = database.getConversation(conversationId).messages
.find((candidate) => candidate.id === assistantMessageId)!
expect(message).toMatchObject({ content: 'Hello', reasoning: 'plan ', status: 'working' })
expect(message.blocks?.map((block) => block.type)).toEqual(['reasoning', 'text', 'tool'])
expect(taskEvents(database).map(({ kind }) => kind)).toEqual([
'reasoning', 'text', 'remote-semantic-checkpoint',
'tool', 'status', 'context-metrics', 'remote-semantic-checkpoint'
])
expect(database.getTask(taskId).status).toBe('running')
} finally {
database.close()
}
})
it('rolls back the whole batch when one event conflicts', () => {
const database = openRecoverableTask()
try {
database.appendRemoteConversationTaskEventsBatch({ ...owner, events: page.slice(0, 3) })
const before = comparable(database)
expect(() => database.appendRemoteConversationTaskEventsBatch({
...owner,
events: [
page[3]!,
entry('1', 1, { requestId: taskId, type: 'text', delta: 'conflict' })
]
})).toThrow('conflicts')
expect(comparable(database)).toEqual(before)
} finally {
database.close()
}
})
})
it('appends plain remote task event batches in one transaction with replay dedupe', () => {
const database = new AssistantDatabase(':memory:')
database.initialize('C:\\Workspace')
try {
const taskId = '00000000-0000-4000-8000-000000000721'
database.createTask({ id: taskId, title: '批量', instructions: '回复', workMode: 'ask' })
const event = (semanticSequence: string, eventIndex: number, delta: string) => ({
taskId, bindingId: 'plain-batch', operationId: taskId, semanticSequence, eventIndex,
kind: 'text', payload: { requestId: taskId, type: 'text', delta }
})
const exec = vi.spyOn(
(database as unknown as { requireDatabase(): DatabaseSync }).requireDatabase(),
'exec'
)
expect(database.appendRemoteTaskEventsOnce([event('1', 0, 'a'), event('1', 1, 'b')]))
.toEqual([true, true])
expect(exec.mock.calls.map(([sql]) => sql)).toEqual(['BEGIN IMMEDIATE', 'COMMIT'])
exec.mockRestore()
expect(database.appendRemoteTaskEventsOnce([event('1', 1, 'b'), event('2', 0, 'c')]))
.toEqual([false, true])
expect(() => database.appendRemoteTaskEventsOnce([event('3', 0, 'd'), event('2', 0, 'x')]))
.toThrow('conflicts')
expect(((database as unknown as { requireDatabase(): DatabaseSync }).requireDatabase()
.prepare('SELECT payload_json FROM task_events WHERE task_id = ? AND remote_semantic_sequence IS NOT NULL ORDER BY id')
.all(taskId) as Array<{ payload_json: string }>)
.map(({ payload_json }) => (JSON.parse(payload_json) as { delta: string }).delta))
.toEqual(['a', 'b', 'c'])
expect(database.appendRemoteTaskEventsOnce([])).toEqual([])
} finally {
database.close()
}
})
it.each(['failed', 'cancelled'] as const)('creates and recovers a remote-authoritative conversation task, then ends it as %s', async (terminalStatus) => {
const directory = await mkdtemp(
join(tmpdir(), 'goodbuddy-remote-conversation-recovery-')
+300 -157
View File
@@ -161,6 +161,21 @@ export type RemoteConversationTaskEventInput = Omit<
}
}
export type RemoteConversationTaskEventsBatchInput = Pick<
RemoteConversationTaskEventInput,
'taskId' | 'conversationId' | 'assistantMessageId' | 'runtimeSelection'
> & {
events: ReadonlyArray<
Pick<
RemoteConversationTaskEventInput,
'bindingId' | 'operationId' | 'semanticSequence' | 'eventIndex' | 'event'
>
>
}
/** Upper bound for one live remote persistence transaction. */
export const REMOTE_TASK_EVENT_BATCH_MAXIMUM_EVENTS = 512
export type RecoverableRemoteTask = {
taskId: string
projectId: string
@@ -1728,6 +1743,42 @@ function reduceRecoveredAgentEvent(
return conversationMessageSchema.parse(next)
}
/**
* Projects the assistant-message fields that remote event persistence reads
* back from storage before reducing the next remote event.
*/
function storedRemoteAssistantMessage(
id: string,
content: string,
state: ConversationMessage['state'],
createdAt: number,
metadata: MessageMetadata
): ConversationMessage {
return {
id,
role: 'assistant',
content,
state,
createdAt,
status: metadata.status,
terminalStatus: metadata.terminalStatus,
reasoning: metadata.reasoning,
runtimeChecklist: metadata.runtimeChecklist,
blocks: metadata.blocks,
displayCaptureTruncated: metadata.displayCaptureTruncated,
contextCompression: metadata.contextCompression,
contextCompressions: metadata.contextCompressions,
tools: metadata.tools,
subagents: metadata.subagents,
sources: metadata.sources,
sourceReferences: metadata.sourceReferences,
knowledgeRetrieval: metadata.knowledgeRetrieval,
artifactIds: metadata.artifactIds,
task: metadata.task,
attachments: metadata.attachments,
answeredQuestions: metadata.answeredQuestions
}
}
function stripRemoteEventProvenance(
event: RemoteConversationTaskEventInput['event']
): RemoteConversationTaskEventInput['event'] {
@@ -6069,28 +6120,92 @@ export class AssistantDatabase {
)
}
/**
* Appends many remote semantic events in ONE task-event transaction.
* Returns one flag per input event: true when the event was newly stored,
* false when the same provenance was already stored (replay dedupe).
*/
appendRemoteTaskEventsOnce(
events: readonly RemoteTaskEventInput[]
): boolean[] {
if (events.length === 0) {
return []
}
if (events.length > REMOTE_TASK_EVENT_BATCH_MAXIMUM_EVENTS) {
throw new RangeError(
`Remote task event batch must contain at most ${REMOTE_TASK_EVENT_BATCH_MAXIMUM_EVENTS} events`
)
}
const validated = events.map(validateRemoteTaskEvent)
const database = this.requireDatabase()
database.exec('BEGIN IMMEDIATE')
try {
const inserted = validated.map((event) =>
this.insertRemoteTaskEventOnce(database, event)
)
database.exec('COMMIT')
return inserted
} catch (error) {
database.exec('ROLLBACK')
throw error
}
}
appendRemoteConversationTaskEventOnce(
input: RemoteConversationTaskEventInput
): boolean {
return this.appendRemoteConversationTaskEventsBatch({
taskId: input.taskId,
conversationId: input.conversationId,
assistantMessageId: input.assistantMessageId,
runtimeSelection: input.runtimeSelection,
events: [input]
})[0]!
}
/**
* Persists remote semantic events of one recoverable task in ONE
* transaction. The assistant message and conversation row are read at most
* once and written at most once per batch, while events are still reduced
* one by one in their original order. Already stored events (same remote
* provenance) are skipped and reported as false.
*/
appendRemoteConversationTaskEventsBatch(
input: RemoteConversationTaskEventsBatchInput
): boolean[] {
if (input.events.length === 0) {
return []
}
if (input.events.length > REMOTE_TASK_EVENT_BATCH_MAXIMUM_EVENTS) {
throw new RangeError(
`Remote task event batch must contain at most ${REMOTE_TASK_EVENT_BATCH_MAXIMUM_EVENTS} events`
)
}
const conversationId = assistantIdSchema.parse(input.conversationId)
const assistantMessageId = assistantIdSchema.parse(
input.assistantMessageId
)
const requestRuntimeSelection =
optionalAgentRuntimeSelectionSchema.parse(input.runtimeSelection)
const publicEvent = stripRemoteEventProvenance(input.event)
if (publicEvent.requestId !== input.taskId) {
throw new Error('远程事件的请求 ID 与任务不匹配')
}
const event = validateRemoteTaskEvent({
taskId: input.taskId,
bindingId: input.bindingId,
operationId: input.operationId,
semanticSequence: input.semanticSequence,
eventIndex: input.eventIndex,
kind: publicEvent.type,
payload: publicEvent
const prepared = input.events.map((item) => {
const publicEvent = stripRemoteEventProvenance(item.event)
if (publicEvent.requestId !== input.taskId) {
throw new Error('远程事件的请求 ID 与任务不匹配')
}
return {
publicEvent,
event: validateRemoteTaskEvent({
taskId: input.taskId,
bindingId: item.bindingId,
operationId: item.operationId,
semanticSequence: item.semanticSequence,
eventIndex: item.eventIndex,
kind: publicEvent.type,
payload: publicEvent
})
}
})
const taskId = prepared[0]!.event.taskId
const database = this.requireDatabase()
database.exec('BEGIN IMMEDIATE')
try {
@@ -6101,7 +6216,7 @@ export class AssistantDatabase {
FROM tasks
WHERE id = ? AND remote_recoverable = 1`
)
.get(event.taskId) as
.get(taskId) as
| {
project_id: string | null
conversation_id: string | null
@@ -6115,162 +6230,190 @@ export class AssistantDatabase {
) {
throw new Error('远程事件与可恢复任务的消息归属不匹配')
}
const inserted = this.insertRemoteTaskEventOnce(database, event)
if (!inserted) {
database.exec('COMMIT')
return false
}
if (publicEvent.type === 'remote-semantic-checkpoint') {
this.terminalizeRemoteTaskAtCheckpoint(database, event)
database.exec('COMMIT')
return true
}
const row = database
.prepare(
`SELECT id, role, content, state, metadata_json, created_at
FROM messages
WHERE id = ? AND conversation_id = ? AND request_id = ?`
)
.get(
assistantMessageId,
conversationId,
event.taskId
) as
const inserted: boolean[] = []
let message: ConversationMessage | undefined
let lastReduced: ConversationMessage | undefined
let conversationState:
| {
id: string
role: MessageRow['role']
content: string
state: ConversationMessage['state']
metadata_json: string
created_at: string
contextState: ReturnType<typeof parseConversationContextState>
runtimeSelectionKey: ReturnType<typeof remoteEventSelectionKey>
}
| undefined
if (!row || row.role !== 'assistant') {
throw new Error('远程事件的助理消息不存在或不受任务管理')
}
const metadata = JSON.parse(row.metadata_json) as MessageMetadata
const message = conversationMessageSchema.parse({
id: row.id,
role: 'assistant',
content: row.content,
state: row.state,
createdAt:
metadata.createdAt ?? Date.parse(row.created_at),
status: metadata.status,
terminalStatus: metadata.terminalStatus,
reasoning: metadata.reasoning,
runtimeChecklist: metadata.runtimeChecklist,
blocks: metadata.blocks,
displayCaptureTruncated:
metadata.displayCaptureTruncated,
contextCompression: metadata.contextCompression,
contextCompressions: metadata.contextCompressions,
tools: metadata.tools,
subagents: metadata.subagents,
sources: metadata.sources,
sourceReferences: metadata.sourceReferences,
knowledgeRetrieval: metadata.knowledgeRetrieval,
artifactIds: metadata.artifactIds,
task: metadata.task,
attachments: metadata.attachments,
answeredQuestions: metadata.answeredQuestions
})
const reduced = reduceRecoveredAgentEvent(message, publicEvent)
const messageUpdate = database
.prepare(
`UPDATE messages
SET content = ?, state = ?, metadata_json = ?
WHERE id = ? AND conversation_id = ? AND request_id = ?`
const loadMessage = (): ConversationMessage => {
if (message) {
return message
}
const row = database
.prepare(
`SELECT id, role, content, state, metadata_json, created_at
FROM messages
WHERE id = ? AND conversation_id = ? AND request_id = ?`
)
.get(
assistantMessageId,
conversationId,
taskId
) as
| {
id: string
role: MessageRow['role']
content: string
state: ConversationMessage['state']
metadata_json: string
created_at: string
}
| undefined
if (!row || row.role !== 'assistant') {
throw new Error('远程事件的助理消息不存在或不受任务管理')
}
const metadata = JSON.parse(row.metadata_json) as MessageMetadata
message = conversationMessageSchema.parse(
storedRemoteAssistantMessage(
row.id,
row.content,
row.state,
metadata.createdAt ?? Date.parse(row.created_at),
metadata
)
)
.run(
return message
}
const loadConversationState = (): NonNullable<
typeof conversationState
> => {
if (conversationState) {
return conversationState
}
const conversation = database
.prepare(
`SELECT c.runtime_selection_json, c.context_state_json,
p.runtime_selection_json AS project_runtime_selection_json
FROM conversations c
LEFT JOIN projects p ON p.id = c.project_id
WHERE c.id = ?`
)
.get(conversationId) as
| {
runtime_selection_json: string | null
project_runtime_selection_json: string | null
context_state_json: string | null
}
| undefined
if (!conversation) {
throw new Error('远程事件的对话不存在')
}
conversationState = {
contextState: parseConversationContextState(
conversation.context_state_json
),
runtimeSelectionKey: remoteEventSelectionKey(
requestRuntimeSelection,
parseRuntimeSelection(conversation.runtime_selection_json),
parseRuntimeSelection(
conversation.project_runtime_selection_json
)
)
}
return conversationState
}
for (const { event, publicEvent } of prepared) {
if (!this.insertRemoteTaskEventOnce(database, event)) {
inserted.push(false)
continue
}
inserted.push(true)
if (publicEvent.type === 'remote-semantic-checkpoint') {
this.terminalizeRemoteTaskAtCheckpoint(database, event)
continue
}
const reduced = reduceRecoveredAgentEvent(loadMessage(), publicEvent)
lastReduced = reduced
// Match sequential single-event writes exactly: each of them re-read
// only the stored metadata fields before reducing the next event.
message = storedRemoteAssistantMessage(
reduced.id,
reduced.content,
reduced.state,
serializeConversationMessageMetadata(reduced),
assistantMessageId,
conversationId,
event.taskId
reduced.createdAt,
reduced
)
if (messageUpdate.changes !== 1) {
throw new Error('远程事件的助理消息写入失败')
}
const conversation = database
.prepare(
`SELECT c.runtime_selection_json, c.context_state_json,
p.runtime_selection_json AS project_runtime_selection_json
FROM conversations c
LEFT JOIN projects p ON p.id = c.project_id
WHERE c.id = ?`
)
.get(conversationId) as
| {
runtime_selection_json: string | null
project_runtime_selection_json: string | null
context_state_json: string | null
const state = loadConversationState()
if (publicEvent.type === 'context-metrics') {
state.contextState = {
...state.contextState,
contextMetrics: {
runtimeSelectionKey: state.runtimeSelectionKey,
contextTokens: publicEvent.contextTokens,
source: publicEvent.source,
basis: 'model-call'
}
}
| undefined
if (!conversation) {
throw new Error('远程事件的对话不存在')
}
let contextState = parseConversationContextState(
conversation.context_state_json
)
const runtimeSelectionKey = remoteEventSelectionKey(
requestRuntimeSelection,
parseRuntimeSelection(conversation.runtime_selection_json),
parseRuntimeSelection(conversation.project_runtime_selection_json)
)
if (publicEvent.type === 'context-metrics') {
contextState = {
...contextState,
contextMetrics: {
runtimeSelectionKey,
contextTokens: publicEvent.contextTokens,
source: publicEvent.source,
basis: 'model-call'
}
}
} else if (
publicEvent.type === 'context-compression' &&
publicEvent.scope !== 'agent-run'
) {
const estimatedAfterTokens =
publicEvent.estimatedAfterTokens
contextState = {
...contextState,
...(publicEvent.conversationState
? {
contextCompressionState:
publicEvent.conversationState
}
: {}),
...(publicEvent.state === 'completed' &&
estimatedAfterTokens !== undefined
? {
contextMetrics: {
runtimeSelectionKey,
contextTokens: estimatedAfterTokens,
source: 'estimated' as const,
basis: 'conversation' as const
} else if (
publicEvent.type === 'context-compression' &&
publicEvent.scope !== 'agent-run'
) {
const estimatedAfterTokens =
publicEvent.estimatedAfterTokens
state.contextState = {
...state.contextState,
...(publicEvent.conversationState
? {
contextCompressionState:
publicEvent.conversationState
}
}
: {})
: {}),
...(publicEvent.state === 'completed' &&
estimatedAfterTokens !== undefined
? {
contextMetrics: {
runtimeSelectionKey: state.runtimeSelectionKey,
contextTokens: estimatedAfterTokens,
source: 'estimated' as const,
basis: 'conversation' as const
}
}
: {})
}
}
}
database
.prepare(
`UPDATE conversations
SET context_state_json = ?, updated_at = ?
WHERE id = ?`
)
.run(
serializeConversationContextState(
conversationContextStateSchema.parse(contextState)
),
new Date().toISOString(),
conversationId
)
if (lastReduced) {
const messageUpdate = database
.prepare(
`UPDATE messages
SET content = ?, state = ?, metadata_json = ?
WHERE id = ? AND conversation_id = ? AND request_id = ?`
)
.run(
lastReduced.content,
lastReduced.state,
serializeConversationMessageMetadata(lastReduced),
assistantMessageId,
conversationId,
taskId
)
if (messageUpdate.changes !== 1) {
throw new Error('远程事件的助理消息写入失败')
}
}
if (conversationState) {
database
.prepare(
`UPDATE conversations
SET context_state_json = ?, updated_at = ?
WHERE id = ?`
)
.run(
serializeConversationContextState(
conversationContextStateSchema.parse(
conversationState.contextState
)
),
new Date().toISOString(),
conversationId
)
}
database.exec('COMMIT')
return true
return inserted
} catch (error) {
database.exec('ROLLBACK')
throw error