Merge commit '2b75d66a6e1' into brennanb2025/native-chat-sqlite-host

This commit is contained in:
Brennan Benson
2026-11-08 11:51:32 -08:00
2 changed files with 511 additions and 0 deletions
@@ -0,0 +1,205 @@
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it } from 'vitest'
import Database from '../../sqlite/sync-database'
import type { AgentJournalItemBody } from '../../../shared/agent-session/journal/agent-session-journal-types'
import { codexProviderHandle } from '../../../shared/agent-session/lifecycle/agent-session-provider-handle-encoding'
import { agentSessionSendBodyFingerprint } from '../../../shared/agent-session/requests/structured-agent-session-send-mutation'
import { ensureAgentSessionAttachmentClaimTables } from '../agent-session-attachments/agent-session-attachment-claims'
import { migrateJournalDomainSchema } from './journal-domain-schema'
import { applyJournalDomainSubmission } from './journal-domain-submission-admission'
import { readJournalDomainSubmissionAttempt } from './journal-domain-submission-records'
import { writeJournalDomainCurrentItem } from './journal-domain-current-item'
import { insertJournalDomainQueueRow } from './journal-domain-queue-rows'
import { readJournalDomainUserStopInForce } from './journal-domain-queue-reads'
import {
applyJournalDomainControlCommand,
type JournalDomainControlOperation
} from './journal-domain-control-command'
const target = { sessionId: 'chat', epoch: 'epoch' }
const now = 1_800_000_000_000
const cleanups: (() => void)[] = []
function fixture() {
const directory = mkdtempSync(join(tmpdir(), 'orca-domain-control-'))
const db = new Database(join(directory, 'journal.sqlite'))
migrateJournalDomainSchema(db)
ensureAgentSessionAttachmentClaimTables(db)
db.prepare(`INSERT INTO journal_chat_state(session_id,workspace_id,epoch,last_sequence,highest_fence)
VALUES('chat','workspace','epoch',10,1)`).run()
cleanups.push(() => {
db.close()
rmSync(directory, { recursive: true, force: true })
})
const transaction = <T>(run: () => T): T => {
db.exec('BEGIN IMMEDIATE')
try {
const value = run()
db.exec('COMMIT')
return value
} catch (error) {
db.exec('ROLLBACK')
throw error
}
}
return {
db,
control: (operation: JournalDomainControlOperation, savedAt = now) =>
transaction(() => applyJournalDomainControlCommand(db, target, operation, {}, savedAt)),
admitQueued: (id: string) => {
const body = { kind: 'message' as const, role: 'user' as const, blocks: [] }
transaction(() =>
applyJournalDomainSubmission(
db,
directory,
target,
{
kind: 'submission',
input: {
clientMessageId: id,
body,
payloadFingerprint: agentSessionSendBodyFingerprint('chat', body),
fence: 1,
origin: 'client',
source: { kind: 'user' },
handoverRecorded: true
}
},
{
identity: {
sessionId: 'chat',
workspaceId: 'workspace',
hostId: 'host',
agent: 'codex',
providerHandle: codexProviderHandle('thread')
}
},
now
)
)
},
write: (itemId: string, body: AgentJournalItemBody) =>
transaction(() =>
writeJournalDomainCurrentItem(db, target, {
item: { itemId, revision: 1, sequence: 1, observedAt: now, body },
hidden: false,
ownerFence: 1
})
),
attempt: (id: string) => readJournalDomainSubmissionAttempt(db, target, id)?.submission,
head: () =>
db
.prepare(`SELECT last_sequence, queue_latest_stop_json, queue_manual_stop_json
FROM journal_chat_state`)
.get()!,
events: () => Number(db.prepare('SELECT COUNT(*) AS n FROM journal_events').get()!.n)
}
}
afterEach(() => {
for (const cleanup of cleanups.splice(0)) {
cleanup()
}
})
it('withdraws host-held sends and records the live turn Stop in one write', () => {
const f = fixture()
f.admitQueued('first')
f.admitQueued('second')
const accepted = f.control(
{ kind: 'stop-accept', event: { reason: 'user-stop' }, fence: 1, liveTurnId: 'turn-1' },
now + 5
)
expect(accepted.value).toEqual({
mark: { epoch: 'epoch', sequence: 15 },
withdrawn: ['first', 'second'],
turnId: 'turn-1'
})
expect(accepted.coordinates.at(-1)).toEqual({ kind: 'tombstone', epoch: 'epoch', seq: 15 })
for (const id of ['first', 'second']) {
expect(f.attempt(id)).toMatchObject({
dispatchState: 'rejected',
rejection: { kind: 'cancelled', neverReachedAgent: true }
})
}
const stop = { sequence: 15, event: { reason: 'user-stop', turnId: 'turn-1', at: now + 5 } }
expect(JSON.parse(String(f.head().queue_latest_stop_json))).toEqual(stop)
expect(JSON.parse(String(f.head().queue_manual_stop_json))).toEqual(stop)
expect(readJournalDomainUserStopInForce(f.db, target)).toEqual(stop)
f.control({ kind: 'stop', event: { reason: 'host-stop' }, fence: 1 }, now + 6)
expect(JSON.parse(String(f.head().queue_manual_stop_json))).toEqual(stop)
f.control({ kind: 'queue-resume', fence: 1 })
expect(readJournalDomainUserStopInForce(f.db, target)).toBeNull()
})
it('rolls back every withdrawal and the Stop when one withdrawal fails', () => {
const f = fixture()
f.admitQueued('first')
f.admitQueued('broken')
f.db
.exec(`CREATE TRIGGER reject_broken BEFORE UPDATE OF payload_json ON journal_submission_attempts
WHEN NEW.message_id='broken' BEGIN SELECT RAISE(ABORT, 'dispatch unavailable'); END`)
const before = { head: f.head(), events: f.events() }
expect(() =>
f.control({ kind: 'stop-accept', event: { reason: 'user-stop' }, fence: 1, liveTurnId: null })
).toThrow('dispatch unavailable')
expect(f.attempt('first')?.dispatchState).toBe('pending')
expect({ head: f.head(), events: f.events() }).toEqual(before)
})
it('marks reopen only while a card waits', () => {
const f = fixture()
const before = { head: f.head(), events: f.events() }
const skipped = f.control({ kind: 'queue-reopen-mark', fence: 1, since: 4 })
expect(skipped).toMatchObject({ value: null, coordinates: [] })
expect({ head: f.head(), events: f.events() }).toEqual(before)
const body = { kind: 'message' as const, role: 'user' as const, blocks: [] }
insertJournalDomainQueueRow(f.db, target, {
messageId: 'card',
body,
position: 1,
fingerprint: agentSessionSendBodyFingerprint('chat', body),
state: 'waiting',
holdReason: null,
returnedReason: null,
returnedRejection: null,
consumedAs: null,
queuedAt: { epoch: 'epoch', sequence: 1 }
})
expect(f.control({ kind: 'queue-reopen-mark', fence: 1, since: 4 }).value).toBe(4)
expect(
Number(f.db.prepare('SELECT queue_reopened_sequence AS n FROM journal_chat_state').get()!.n)
).toBe(4)
})
it('explains a quit only for an interrupted turn whose cut is absent', () => {
const f = fixture()
const cut = {
kind: 'shutdown-cut' as const,
input: {
identity: { provider: 'orca' as const, clientMessageId: 'quit' },
body: { kind: 'status' as const, text: 'Orca quit' },
turnItemId: 'turn-item',
fence: 1
}
}
f.write('turn-item', { kind: 'turn', turnId: 'turn-1', state: 'completed', outcome: 'success' })
const sequence = Number(f.head().last_sequence)
expect(f.control(cut)).toMatchObject({ value: null, coordinates: [] })
f.write('turn-item', { kind: 'turn', turnId: 'turn-1', state: 'interrupted' })
const written = f.control(cut)
expect(written.value).toEqual({
cursor: { epoch: 'epoch', sequence: sequence + 1 },
itemId: 'orca:quit',
revision: 1
})
expect(written.items[0]).toMatchObject({
itemId: 'orca:quit',
turnScope: { kind: 'turn', turnItemId: 'turn-item' }
})
expect(f.control(cut)).toMatchObject({ value: null, coordinates: [] })
expect(Number(f.head().last_sequence)).toBe(sequence + 1)
})
@@ -0,0 +1,306 @@
import type Database from '../../sqlite/sync-database'
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { AgentJournalCursor } from '../../../shared/agent-session/journal/agent-session-journal-identity'
import type { AgentJournalRenderItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
import { agentSessionFailureFact } from '../../../shared/agent-session/failures/agent-session-failure'
import { agentSessionFailureWords } from '../../../shared/agent-session/failures/agent-session-failure-words'
import {
readAgentJournalTurn,
readAgentJournalTurnOutcome
} from '../../../shared/agent-session/lifecycle/agent-session-turn-record'
import { agentTurnVerdict } from '../../../shared/agent-status/lifecycle/agent-turn-outcome'
import type { JournalWriterOperation } from './journal-writer-command'
import type { JournalWriterCoordinate } from './journal-writer-effects'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import type { JournalAppendResult } from './journal-store-contracts'
import type { JournalStopEvent } from './durable-rows/journal-row-schema'
import type { JournalStopAcceptance } from './context-epochs/journal-stop-acceptance'
import {
foldJournalQueuePauseMark,
journalManualStop,
type JournalQueuePauseMarks
} from './queued-messages/queued-message-pause-marks'
import { journalRowBase } from './writing/journal-row-builders'
import { assertJournalFence } from './writing/journal-write-guards'
import type { JournalDomainSubmissionCommit } from './journal-domain-submission-records'
import type { JournalDomainInputCoordinate } from './journal-domain-input-commit'
import { applyJournalDomainInputRecovery } from './journal-domain-input-recovery'
import { applyJournalDomainItem } from './journal-domain-item'
import { observeJournalDomainInputStop } from './journal-domain-input-ends'
import { writeJournalDomainQueueReopenMark } from './journal-domain-queue-pauses'
import { journalDomainQueueAwaitsReopen } from './journal-domain-queue-reads'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
import { restoreJournalSqlFailure } from './journal-sql-failure'
type Target = { sessionId: string; epoch: string }
export type JournalDomainControlOperation = Extract<
JournalWriterOperation,
{
kind:
| 'stop'
| 'stop-accept'
| 'queue-resume'
| 'queue-reopen'
| 'queue-reopen-mark'
| 'shutdown-cut'
}
>
export type JournalDomainControlValue =
| AgentJournalCursor
| JournalStopAcceptance
| JournalAppendResult
| number
| null
/** Coordinates are physical; an empty list means the legacy no-op bound no receipt. */
export type JournalDomainControlCommit = Omit<
JournalDomainSubmissionCommit<JournalDomainControlValue>,
'coordinates'
> & { coordinates: JournalWriterCoordinate[] }
// Same reserved source item key as the legacy Stop row, so ended observations stay keyed alike.
const JOURNAL_STOP_EVENT_ITEM_ID = agentJournalItemKey({
provider: 'orca',
clientMessageId: 'stop-event'
})
// Host-held sends prove non-delivery.
const STOP_WITHDRAWAL = agentSessionFailureWords(
agentSessionFailureFact('cancelled', { neverReachedAgent: true }),
{ surface: 'rejection' }
)
/** Decides each control mark against current head rows at its writer position. */
export function applyJournalDomainControlCommand(
db: Database.Database,
target: Target,
operation: JournalDomainControlOperation,
facts: { stopSettle?: JournalStopSettleFact },
savedAt: number
): JournalDomainControlCommit {
if (!db.isTransaction) {
throw new Error('journal control command requires its writer transaction')
}
const head = db
.prepare(`SELECT last_sequence, highest_fence FROM journal_chat_state
WHERE session_id=? AND epoch=?`)
.get(target.sessionId, target.epoch)
if (!head) {
throw new Error('journal control command targets a retired chat epoch')
}
const result: JournalDomainControlCommit = {
cursor: { epoch: target.epoch, sequence: Number(head.last_sequence) },
value: null,
coordinates: [],
items: [],
removedItemIds: [],
receipts: [],
cards: [],
inputChanged: false
}
switch (operation.kind) {
case 'shutdown-cut':
return appendShutdownCut(db, target, operation.input, facts, savedAt, result)
case 'queue-reopen-mark':
// Nothing awaits reopening: no mark, event or receipt row.
if (!journalDomainQueueAwaitsReopen(db, target)) {
return result
}
break
}
assertJournalFence(operation.fence, Number(head.highest_fence))
switch (operation.kind) {
case 'stop':
result.value = writeMark(db, target, operation.fence, savedAt, result, (sequence) =>
writeStop(db, target, sequence, operation.fence, { ...operation.event, at: savedAt })
)
return result
case 'stop-accept':
return acceptStop(db, target, operation, savedAt, result)
case 'queue-resume':
result.value = writeMark(db, target, operation.fence, savedAt, result, (sequence) => {
db.prepare(`UPDATE journal_chat_state SET queue_resumed_sequence=?
WHERE session_id=? AND epoch=?`).run(sequence, target.sessionId, target.epoch)
})
return result
case 'queue-reopen':
case 'queue-reopen-mark': {
const cursor = writeMark(db, target, operation.fence, savedAt, result, (sequence) =>
writeJournalDomainQueueReopenMark(db, target, sequence, operation.since ?? sequence)
)
result.value =
operation.kind === 'queue-reopen' ? cursor : (operation.since ?? cursor.sequence)
return result
}
}
}
/** Withdrawals and the Stop share one rollback: a failed acceptance interrupts nothing. */
function acceptStop(
db: Database.Database,
target: Target,
operation: Extract<JournalDomainControlOperation, { kind: 'stop-accept' }>,
savedAt: number,
result: JournalDomainControlCommit
): JournalDomainControlCommit {
const turnId = operation.event.turnId ?? operation.liveTurnId
const withdrawals = applyJournalDomainInputRecovery(
db,
target,
{ kind: 'queued-reject', fence: operation.fence, rejection: STOP_WITHDRAWAL },
{},
savedAt
)
const { value: settled, coordinates, ...publication } = withdrawals
if ('failure' in settled) {
throw restoreJournalSqlFailure(settled.failure)
}
Object.assign(result, publication)
result.coordinates.push(...coordinates.map((position) => physicalCoordinate(position)))
const event: JournalStopEvent = {
...operation.event,
...(turnId !== null ? { turnId } : {}),
at: savedAt
}
const mark = writeMark(db, target, operation.fence, savedAt, result, (sequence) =>
writeStop(db, target, sequence, operation.fence, event)
)
result.value = { mark, withdrawn: Array.isArray(settled.value) ? settled.value : [], turnId }
return result
}
/** One event-only head mark; the receipt binds this command's last coordinate. */
function writeMark(
db: Database.Database,
target: Target,
fence: number,
savedAt: number,
result: JournalDomainControlCommit,
write: (sequence: number) => void
): AgentJournalCursor {
const sequence = result.cursor.sequence + 1
write(sequence)
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{ items: [], submissions: [], cards: [] },
{ fence, observedAt: savedAt }
)
result.cursor = { epoch: target.epoch, sequence }
result.coordinates.push({ kind: 'tombstone', epoch: target.epoch, seq: sequence })
result.inputChanged = true
return result.cursor
}
/** Saved marks only; the host's unsaved settle overlay never reaches the head. */
function writeStop(
db: Database.Database,
target: Target,
sequence: number,
fence: number,
event: JournalStopEvent
): void {
const head = db
.prepare(`SELECT queue_latest_stop_json, queue_manual_stop_json FROM journal_chat_state
WHERE session_id=? AND epoch=?`)
.get(target.sessionId, target.epoch)!
const marks: JournalQueuePauseMarks = {
latestStop:
head.queue_latest_stop_json === null ? null : JSON.parse(String(head.queue_latest_stop_json)),
resumedSequence: 0,
reopenedSequence: 0
}
// An older layout's manual Stop is materialized before this write, as the format-3 writer does.
const stop: JournalQueuePauseMarks['latestStop'] =
head.queue_manual_stop_json === null
? journalManualStop(marks)
: JSON.parse(String(head.queue_manual_stop_json))
marks.manualStop = stop && {
sequence: stop.sequence,
event: { ...stop.event, reason: 'user-stop' }
}
foldJournalQueuePauseMark(marks, {
kind: 'tombstone',
itemId: JOURNAL_STOP_EVENT_ITEM_ID,
revision: 1,
stopEvent: event,
...journalRowBase(target.epoch, sequence, fence, event.at)
})
db.prepare(`UPDATE journal_chat_state SET queue_latest_stop_json=?, queue_manual_stop_json=?
WHERE session_id=? AND epoch=?`).run(
JSON.stringify(marks.latestStop),
JSON.stringify(marks.manualStop),
target.sessionId,
target.epoch
)
observeJournalDomainInputStop(db, target, JOURNAL_STOP_EVENT_ITEM_ID, sequence, fence, event)
}
/** Quit explains only a presented interrupted turn; an existing cut writes nothing. */
function appendShutdownCut(
db: Database.Database,
target: Target,
input: Extract<JournalDomainControlOperation, { kind: 'shutdown-cut' }>['input'],
facts: { stopSettle?: JournalStopSettleFact },
savedAt: number,
result: JournalDomainControlCommit
): JournalDomainControlCommit {
const itemId = agentJournalItemKey(input.identity)
const turn = readAgentJournalTurn(visibleItem(db, target, input.turnItemId)?.body)
if (
visibleItem(db, target, itemId) ||
!turn ||
agentTurnVerdict({ state: turn.state, outcome: readAgentJournalTurnOutcome(turn) }) !==
'interruption'
) {
return result
}
const written = applyJournalDomainItem(
db,
target,
{
kind: 'item',
identity: input.identity,
body: input.body,
options: { fence: input.fence, turnScope: { kind: 'turn', turnItemId: input.turnItemId } }
},
savedAt,
facts.stopSettle
)
const { outcome: _outcome, publicCursor: _public, ...publication } = written
Object.assign(result, publication)
const item = written.items.find((entry) => entry.itemId === itemId) ?? written.items[0]!
result.coordinates.push({ kind: 'item', epoch: target.epoch, seq: written.cursor.sequence })
result.value = { cursor: written.cursor, itemId, revision: item.revision }
return result
}
function visibleItem(
db: Database.Database,
target: Target,
key: string
): AgentJournalRenderItem | null {
const row = db
.prepare(`SELECT payload_json FROM journal_items
WHERE session_id=? AND epoch=? AND hidden=0 AND item_id=COALESCE((SELECT item_id FROM journal_item_aliases
WHERE session_id=? AND epoch=? AND provider_item_id=?),?)`)
.get(target.sessionId, target.epoch, target.sessionId, target.epoch, key, key)
return row ? JSON.parse(String(row.payload_json)) : null
}
function physicalCoordinate(position: JournalDomainInputCoordinate): JournalWriterCoordinate {
return {
kind:
position.kind === 'queue-reopen'
? 'tombstone'
: position.kind === 'command-settle'
? 'lifecycle-batch'
: position.kind,
epoch: position.cursor.epoch,
seq: position.cursor.sequence
}
}