Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { createHash, randomUUID } from 'node:crypto'
import { promises as fs } from 'node:fs'
import { dirname, join } from 'node:path'
import { mergeAuthoritativeServerMessages, messageServerTurnNumber } from './chatMessageMerge.js'
import { assertSafeFilesystemSegment } from './pathSafety.js'
import type {
ChatAuthorityScope,
ChatDeleteResult,
ChatDeleteTombstone,
ChatFile,
ChatIndex,
ChatMessage,
ChatMetadata,
ReplaceChatMessagesOptions,
} from './types.js'
// Keep the catalog at v2 while paged transcripts are dual-readable by the
// pre-paging desktop build. The page layout has its own versioned metadata.
const INDEX_VERSION = 2
const MAX_READABLE_INDEX_VERSION = 3
const PAGED_CHAT_VERSION = 1
const DEFAULT_PAGE_SIZE = 100
const MAX_COMPATIBILITY_WINDOWS = 100
const MAX_COMPATIBILITY_WINDOW_BYTES = 8 * 1024 * 1024
const DEFAULT_MAX_LOCAL_SYNCED_MESSAGES = 1000
const LEGACY_COMPATIBILITY_MESSAGE_LIMIT = 100
const PAGE_FILE_PATTERN = /^\d{6}\.json$/
export interface ChatStoreOptions {
pageSize?: number
maxLocalSyncedMessages?: number
}
interface ChatPageEntry {
file: string
count: number
serverSynced: boolean
firstServerTurnNumber?: number
lastServerTurnNumber?: number
}
interface PagedChatMeta {
version: typeof PAGED_CHAT_VERSION
chatId: string
pageSize: number
messageCount: number
localMessageCount: number
prunedBeforeCount?: number
legacyCompatibilitySignature?: string
pages: ChatPageEntry[]
}
interface ChatPageFile {
version: typeof PAGED_CHAT_VERSION
chatId: string
pageNumber: number
messages: ChatMessage[]
}
interface SnapshotCandidate {
dir: string
kind: 'next' | 'previous'
token: string
mtimeMs: number
}
function isNonNegativeSafeInteger(value: unknown): value is number {
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
}
function isPositiveSafeInteger(value: unknown): value is number {
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1
}
function isChatAuthorityScope(value: unknown): value is ChatAuthorityScope {
if (!value || typeof value !== 'object' || Array.isArray(value)) return false
const scope = value as Record<string, unknown>
return (
typeof scope.environmentKey === 'string' &&
scope.environmentKey.length > 0 &&
typeof scope.userId === 'string' &&
scope.userId.length > 0 &&
(scope.teamId === null || typeof scope.teamId === 'string')
)
}
function isChatDeleteTombstone(value: unknown): value is ChatDeleteTombstone {
if (!value || typeof value !== 'object' || Array.isArray(value)) return false
const tombstone = value as Record<string, unknown>
return typeof tombstone.chatId === 'string' && isChatAuthorityScope(tombstone.authorityScope)
}
function sameChatAuthorityScope(left: ChatAuthorityScope, right: ChatAuthorityScope): boolean {
return (
left.environmentKey === right.environmentKey &&
left.userId === right.userId &&
left.teamId === right.teamId
)
}
/**
* The identity a local deletion is bound to: environment + user. The store is
* rooted at `<env>/<user>/<agentRef>`, so together with the per-agent index this
* is the Host/agent identity the chat belongs to. The session team is NOT part
* of it: it is rebound from `me.teamId` on every team switch, and a deletion the
* user confirmed for a Host's chat must keep holding after that switch.
*/
function sameChatDeletionIdentity(left: ChatAuthorityScope, right: ChatAuthorityScope): boolean {
return left.environmentKey === right.environmentKey && left.userId === right.userId
}
function normalizePositiveInteger(value: number | undefined, fallback: number): number {
if (value === undefined) return fallback
if (!Number.isFinite(value)) return fallback
const normalized = Math.floor(value)
return normalized > 0 ? normalized : fallback
}
function normalizeMaxLocalSyncedMessages(value: number | undefined): number {
if (value === undefined) return DEFAULT_MAX_LOCAL_SYNCED_MESSAGES
if (value === Number.POSITIVE_INFINITY) return Number.POSITIVE_INFINITY
if (!Number.isFinite(value)) return DEFAULT_MAX_LOCAL_SYNCED_MESSAGES
return Math.max(0, Math.floor(value))
}
function pageFileName(pageNumber: number): string {
return `${pageNumber.toString().padStart(6, '0')}.json`
}
function pageNumberFromFileName(fileName: string): number {
if (!PAGE_FILE_PATTERN.test(fileName)) return 0
return Number(fileName.slice(0, 6))
}
function isNotFoundError(err: unknown): boolean {
return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT'
}
function isRawFilesystemError(err: unknown): boolean {
return typeof (err as NodeJS.ErrnoException | undefined)?.code === 'string'
}
function isUnsupportedDirectorySyncError(err: unknown): boolean {
if (process.platform !== 'win32') return false
const code = (err as NodeJS.ErrnoException | undefined)?.code
return code === 'EISDIR' || code === 'EPERM' || code === 'EINVAL' || code === 'ENOTSUP'
}
function isUnsafeSegmentError(err: unknown): boolean {
return err instanceof Error && /unsafe path segment/.test(err.message)
}
function aggregateMessages(
messages: ChatMessage[]
): Pick<ChatMetadata, 'errorCount' | 'toolCallCount'> {
return {
errorCount: messages.reduce((total, message) => total + (message.isError ? 1 : 0), 0),
toolCallCount: messages.reduce((total, message) => total + (message.toolSteps?.length ?? 0), 0),
}
}
function visibleMessageCount(messages: ChatMessage[]): number {
return messages.reduce(
(total, message) => total + (message.role === 'user' || message.role === 'assistant' ? 1 : 0),
0
)
}
function pageEntry(file: string, messages: ChatMessage[]): ChatPageEntry {
const serverTurns = messages
.map(messageServerTurnNumber)
.filter((turn): turn is number => turn !== undefined)
return {
file,
count: messages.length,
serverSynced: messages.length > 0 && serverTurns.length === messages.length,
firstServerTurnNumber: serverTurns.length ? Math.min(...serverTurns) : undefined,
lastServerTurnNumber: serverTurns.length ? Math.max(...serverTurns) : undefined,
}
}
function samePageEntry(left: ChatPageEntry, right: ChatPageEntry): boolean {
return (
left.file === right.file &&
left.count === right.count &&
left.serverSynced === right.serverSynced &&
left.firstServerTurnNumber === right.firstServerTurnNumber &&
left.lastServerTurnNumber === right.lastServerTurnNumber
)
}
interface ParsedChatIndex {
index: ChatIndex
/** Tombstone / pending-cleanup entries dropped because they were malformed. */
droppedTombstoneEntries: number
}
function parseChatIndex(raw: string): ParsedChatIndex {
const parsed = JSON.parse(raw) as unknown
if (!parsed || typeof parsed !== 'object') {
throw new Error('Invalid chat index')
}
const candidate = parsed as Record<string, unknown>
if (
typeof candidate.version === 'number' &&
Number.isSafeInteger(candidate.version) &&
candidate.version > MAX_READABLE_INDEX_VERSION
) {
throw new UnsupportedChatIndexVersionError(candidate.version)
}
if (
(candidate.version !== 2 && candidate.version !== 3) ||
(candidate.lastActiveChatId !== null && typeof candidate.lastActiveChatId !== 'string') ||
typeof candidate.onboardingDismissed !== 'boolean' ||
!Array.isArray(candidate.chats) ||
(candidate.deletedChatTombstones !== undefined &&
!Array.isArray(candidate.deletedChatTombstones)) ||
(candidate.pendingChatCleanup !== undefined && !Array.isArray(candidate.pendingChatCleanup))
) {
throw new Error('Invalid chat index')
}
for (const chat of candidate.chats) {
if (!chat || typeof chat !== 'object') throw new Error('Invalid chat index entry')
const metadata = chat as Record<string, unknown>
if (
typeof metadata.id !== 'string' ||
typeof metadata.title !== 'string' ||
typeof metadata.createdAt !== 'string' ||
typeof metadata.updatedAt !== 'string' ||
!isNonNegativeSafeInteger(metadata.messageCount) ||
(metadata.errorCount !== undefined && !isNonNegativeSafeInteger(metadata.errorCount)) ||
(metadata.toolCallCount !== undefined && !isNonNegativeSafeInteger(metadata.toolCallCount)) ||
(metadata.unreadTerminal !== undefined && typeof metadata.unreadTerminal !== 'boolean') ||
(metadata.lastTerminalAt !== undefined && typeof metadata.lastTerminalAt !== 'string')
) {
throw new Error('Invalid chat index entry')
}
}
// One malformed tombstone must not condemn the whole catalog (and with it every
// other tombstone): drop only the malformed entries and report the count.
let droppedTombstoneEntries = 0
const keepValidTombstones = (
entries: unknown[] | undefined
): ChatDeleteTombstone[] | undefined => {
if (entries === undefined) return undefined
const valid = entries.filter(isChatDeleteTombstone)
droppedTombstoneEntries += entries.length - valid.length
return valid
}
const deletedChatTombstones = keepValidTombstones(candidate.deletedChatTombstones as unknown[])
const pendingChatCleanup = keepValidTombstones(candidate.pendingChatCleanup as unknown[])
const index = { ...candidate, version: INDEX_VERSION } as unknown as ChatIndex
if (deletedChatTombstones) index.deletedChatTombstones = deletedChatTombstones
if (pendingChatCleanup) index.pendingChatCleanup = pendingChatCleanup
return { index, droppedTombstoneEntries }
}
/**
* Durable copy of the tombstone and pending-cleanup lists, written next to
* `index.json`. A corrupt catalog is quarantined and replaced by an empty one;
* without this copy every confirmed local deletion of that agent would be
* forgotten and the deleted chats could be recreated from the server.
*/
const TOMBSTONE_SIDECAR_VERSION = 1
interface TombstoneSidecar {
version: typeof TOMBSTONE_SIDECAR_VERSION
deletedChatTombstones: ChatDeleteTombstone[]
pendingChatCleanup: ChatDeleteTombstone[]
}
/**
* `deletedChatTombstones` are intentionally unbounded and never pruned: a
* deleted chat is never reopened, and the tombstone is what keeps a late write
* (a server session sync, a delayed append) from resurrecting it. An entry costs
* ~209 bytes (measured), so the growth is negligible. Do not add a cap or an
* expiry: evicting a tombstone would let exactly that late write bring the
* deleted chat back. Only `pendingChatCleanup` entries are removed, once the
* chat's artifacts are gone.
*/
function mergeTombstones(
primary: ChatDeleteTombstone[] | undefined,
recovered: ChatDeleteTombstone[]
): ChatDeleteTombstone[] {
const merged = [...(primary ?? [])]
for (const candidate of recovered) {
const present = merged.some(
existing =>
existing.chatId === candidate.chatId &&
sameChatAuthorityScope(existing.authorityScope, candidate.authorityScope)
)
if (!present) merged.push(candidate)
}
return merged
}
class UnsupportedChatIndexVersionError extends Error {
constructor(version: number) {
super(`Unsupported chat index version ${version}`)
this.name = 'UnsupportedChatIndexVersionError'
}
}
/**
* Reject any path-component (agentRef / chatId) that could escape the store
* root via `path.join`. agentRefs are slugs and chatIds are UUIDs in practice,
* so this only ever trips on malicious/garbage input — but `replaceMessages`
* (wholesale overwrite) and `deleteChat` (unlink) make traversal high-impact,
* so we guard centrally where the on-disk path is built.
*/
function encodedChatId(chatId: string): string {
return Buffer.from(chatId, 'utf8').toString('base64url')
}
function legacyCorruptFileBelongsToChat(fileName: string, chatId: string): boolean {
const encoded = encodedChatId(chatId)
const match =
/^(.*)-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.json$/i.exec(
fileName
)
return match?.[1] === encoded
}
function sameReconciledMessage(local: ChatMessage, server: ChatMessage): boolean {
if (local.id === server.id) return true
const localTurn = messageServerTurnNumber(local)
const serverTurn = messageServerTurnNumber(server)
if (
localTurn !== undefined &&
serverTurn !== undefined &&
localTurn === serverTurn &&
local.role === server.role
) {
return true
}
if (
localTurn === undefined &&
serverTurn !== undefined &&
local.role === server.role &&
((local.task_id && server.task_id && local.task_id === server.task_id) ||
(local.content.trim() === server.content.trim() &&
Math.abs(local.timestamp - server.timestamp) <= 60_000))
) {
return true
}
return false
}
function reconciledMessageRoleRank(message: ChatMessage): number {
return message.role === 'user' ? 0 : message.role === 'assistant' ? 1 : 2
}
function mergeReconciledMessages(existing: ChatMessage[], incoming: ChatMessage[]): ChatMessage[] {
const merged = [...existing]
for (const serverMessage of incoming) {
const matchIndex = merged.findIndex(message => sameReconciledMessage(message, serverMessage))
if (matchIndex >= 0) {
merged[matchIndex] = {
...serverMessage,
task_id: merged[matchIndex]?.task_id ?? serverMessage.task_id,
}
continue
}
const serverTurn = messageServerTurnNumber(serverMessage)
const insertionIndex =
serverTurn === undefined
? -1
: merged.findIndex(message => {
const messageTurn = messageServerTurnNumber(message)
if (messageTurn === undefined) return false
return (
messageTurn > serverTurn ||
(messageTurn === serverTurn &&
reconciledMessageRoleRank(message) > reconciledMessageRoleRank(serverMessage))
)
})
if (insertionIndex < 0) merged.push(serverMessage)
else merged.splice(insertionIndex, 0, serverMessage)
}
return merged
}
function emptyIndex(): ChatIndex {
return {
version: INDEX_VERSION,
lastActiveChatId: null,
onboardingDismissed: false,
chats: [],
}
}
export class ChatStore {
private readonly pageSize: number
private readonly maxLocalSyncedMessages: number
private authorityScope: ChatAuthorityScope | null = null
/** Set by every bind; the next cleanup retry walks every agent once. */
private pendingCleanupSweep = true
constructor(
private readonly baseDir: string,
options: ChatStoreOptions = {}
) {
this.pageSize = normalizePositiveInteger(options.pageSize, DEFAULT_PAGE_SIZE)
this.maxLocalSyncedMessages = normalizeMaxLocalSyncedMessages(options.maxLocalSyncedMessages)
}
setAuthorityScope(scope: ChatAuthorityScope): void {
this.authorityScope = Object.freeze({ ...scope })
this.pendingCleanupSweep = true
}
getAuthorityScope(): ChatAuthorityScope | null {
return this.authorityScope ? { ...this.authorityScope } : null
}
private requireAuthorityScope(expected?: ChatAuthorityScope): ChatAuthorityScope {
const current = this.authorityScope
if (!current || (expected && !sameChatAuthorityScope(current, expected))) {
throw new Error('Chat deletion authority scope changed')
}
return current
}
/**
* Same check as `requireAuthorityScope` but on the deletion identity
* (environment + user): pending-cleanup retries must keep working after a team
* switch, and must still refuse another user or environment.
*/
private requireDeletionIdentity(expected: ChatAuthorityScope): ChatAuthorityScope {
const current = this.authorityScope
if (!current || !sameChatDeletionIdentity(current, expected)) {
throw new Error('Chat deletion authority scope changed')
}
return current
}
private isDeletedInScope(index: ChatIndex, chatId: string): boolean {
return Boolean(
index.deletedChatTombstones?.some(
tombstone =>
tombstone.chatId === chatId &&
(!this.authorityScope ||
sameChatDeletionIdentity(tombstone.authorityScope, this.authorityScope))
)
)
}
/**
* Index read-modify-write sequences are serialized per agent because every
* chat shares one `index.json`. Paged transcript operations use a separate
* per-chat chain so reads stay atomic with writes for the same chat without
* queuing behind unrelated chat activity.
*/
private indexChains = new Map<string, Promise<unknown>>()
private chatChains = new Map<string, Promise<unknown>>()
private tombstoneSidecarSerialized = new Map<string, string>()
private warnedTombstoneAgents = new Set<string>()
private warnedCleanupFailures = new Set<string>()
private cleanedSnapshotSiblingKeys = new Set<string>()
private compatibilityCheckedKeys = new Set<string>()
private compatibilityWindows = new Map<string, ChatMessage[]>()
private compatibilityWindowBytes = new Map<string, number>()
private compatibilityWindowsTotalBytes = 0
/**
* Server titles of sessions the catalog reported before they were in the
* index, keyed by agent then chat. `createChat` reads (and drops) the entry
* when the user opens such a chat, so hydration stores the title the
* catalog already showed instead of the 'New Chat' placeholder. Written and
* read only inside `serializeIndex` for the agent.
*/
private serverOnlyTitles = new Map<string, Map<string, string>>()
private dropCompatibilityWindow(key: string): void {
this.compatibilityWindows.delete(key)
this.compatibilityWindowsTotalBytes -= this.compatibilityWindowBytes.get(key) ?? 0
this.compatibilityWindowBytes.delete(key)
}
private cacheCompatibilityWindow(key: string, messages: ChatMessage[]): void {
this.dropCompatibilityWindow(key)
const sizeBytes = Buffer.byteLength(JSON.stringify(messages), 'utf8')
this.compatibilityWindows.set(key, [...messages])
this.compatibilityWindowBytes.set(key, sizeBytes)
this.compatibilityWindowsTotalBytes += sizeBytes
while (
this.compatibilityWindows.size > MAX_COMPATIBILITY_WINDOWS ||
this.compatibilityWindowsTotalBytes > MAX_COMPATIBILITY_WINDOW_BYTES
) {
const oldestKey = this.compatibilityWindows.keys().next().value
if (typeof oldestKey !== 'string') break
this.dropCompatibilityWindow(oldestKey)
}
}
private serialize<T>(
chains: Map<string, Promise<unknown>>,
key: string,
fn: () => Promise<T>
): Promise<T> {
const prev = chains.get(key) ?? Promise.resolve()
const run = prev.then(fn, fn)
const settled = run.then(
() => undefined,
() => undefined
)
chains.set(key, settled)
void settled.then(() => {
if (chains.get(key) === settled) chains.delete(key)
})
return run
}
private serializeIndex<T>(agentRef: string, fn: () => Promise<T>): Promise<T> {
return this.serialize(this.indexChains, agentRef, fn)
}
private serializeChat<T>(agentRef: string, chatId: string, fn: () => Promise<T>): Promise<T> {
return this.serialize(this.chatChains, JSON.stringify([agentRef, chatId]), fn)
}
private chatSnapshotCleanupKey(agentRef: string, chatId: string): string {
return JSON.stringify([agentRef, chatId])
}
private agentDir(agentRef: string): string {
assertSafeFilesystemSegment('agentRef', agentRef)
return join(this.baseDir, agentRef)
}
private indexPath(agentRef: string): string {
return join(this.agentDir(agentRef), 'index.json')
}
/**
* Dot-prefixed, so it can never equal `${chatId}.json` (chat ids may not start
* with a dot) nor the `index.json` catalog.
*/
private tombstoneSidecarPath(agentRef: string): string {
return join(this.agentDir(agentRef), '.tombstones.json')
}
private corruptIndexPath(agentRef: string): string {
return join(this.agentDir(agentRef), '.corrupt', `index-${randomUUID()}.json`)
}
private chatFilePath(agentRef: string, chatId: string): string {
assertSafeFilesystemSegment('chatId', chatId, {
reservedNames: ['index', 'chats'],
})
return join(this.agentDir(agentRef), `${chatId}.json`)
}
private chatCompatibilitySignaturePath(agentRef: string, chatId: string): string {
assertSafeFilesystemSegment('chatId', chatId, {
reservedNames: ['index', 'chats'],
})
return join(this.agentDir(agentRef), `${chatId}.compat`)
}
private corruptLegacyChatFilePath(agentRef: string, chatId: string): string {
assertSafeFilesystemSegment('chatId', chatId, {
reservedNames: ['index', 'chats'],
})
return join(this.agentDir(agentRef), '.corrupt', encodedChatId(chatId), `${randomUUID()}.json`)
}
private chatDirPath(agentRef: string, chatId: string): string {
assertSafeFilesystemSegment('chatId', chatId, {
reservedNames: ['index', 'chats'],
})
return join(this.agentDir(agentRef), 'chats', chatId)
}
private chatSnapshotSiblingPath(
agentRef: string,
chatId: string,
kind: 'next' | 'previous' | 'corrupt',
token: string
): string {
assertSafeFilesystemSegment('chatId', chatId, {
reservedNames: ['index', 'chats'],
})
return join(
this.agentDir(agentRef),
'chats',
'.snapshots',
encodedChatId(chatId),
`${kind}-${token}`
)
}
private chatSnapshotRootPath(agentRef: string, chatId: string): string {
assertSafeFilesystemSegment('chatId', chatId, {
reservedNames: ['index', 'chats'],
})
return join(this.agentDir(agentRef), 'chats', '.snapshots', encodedChatId(chatId))
}
private chatPagesDirPath(agentRef: string, chatId: string): string {
return this.chatPagesDirFromChatDir(this.chatDirPath(agentRef, chatId))
}
private chatMetaPath(agentRef: string, chatId: string): string {
return this.chatMetaPathFromChatDir(this.chatDirPath(agentRef, chatId))
}
private chatPagesDirFromChatDir(chatDir: string): string {
return join(chatDir, 'pages')
}
private chatMetaPathFromChatDir(chatDir: string): string {
return join(chatDir, 'meta.json')
}
private chatPagePathFromPagesDir(pagesDir: string, fileName: string): string {
if (!PAGE_FILE_PATTERN.test(fileName)) {
throw new Error(`Invalid chat page: unsafe file name`)
}
return join(pagesDir, fileName)
}
private chatPagePath(agentRef: string, chatId: string, fileName: string): string {
return this.chatPagePathFromPagesDir(this.chatPagesDirPath(agentRef, chatId), fileName)
}
private async syncFile(filePath: string): Promise<void> {
const handle = await fs.open(filePath, 'r')
try {
await handle.sync()
} finally {
await handle.close()
}
}
private async syncDirectory(directoryPath: string): Promise<void> {
let handle: Awaited<ReturnType<typeof fs.open>> | null = null
try {
handle = await fs.open(directoryPath, 'r')
await handle.sync()
} catch (error) {
// Node cannot open/fsync directories on Windows. The file itself is still
// flushed before rename; retain directory fsync on platforms that support it.
if (!isUnsupportedDirectorySyncError(error)) throw error
} finally {
await handle?.close()
}
}
private async syncRenamedEntry(sourcePath: string, targetPath: string): Promise<void> {
const sourceDir = dirname(sourcePath)
const targetDir = dirname(targetPath)
await this.syncDirectory(sourceDir)
if (targetDir !== sourceDir) {
await this.syncDirectory(targetDir)
}
}
private async writeJsonAtomic(
filePath: string,
value: unknown,
indentation?: number
): Promise<void> {
const tmp = `${filePath}.tmp`
try {
const serialized = JSON.stringify(value, null, indentation)
if (serialized === undefined) throw new TypeError('Unable to serialize JSON value')
await fs.writeFile(tmp, serialized, { mode: 0o600 })
await this.syncFile(tmp)
await fs.rename(tmp, filePath)
await this.syncRenamedEntry(tmp, filePath)
} catch (err) {
await fs.rm(tmp, { force: true }).catch(() => undefined)
throw err
}
}
private finalizePagedMeta(meta: PagedChatMeta): PagedChatMeta {
const localMessageCount = meta.pages.reduce((total, page) => total + page.count, 0)
return {
...meta,
pageSize: this.pageSize,
localMessageCount,
}
}
private async readPagedMeta(agentRef: string, chatId: string): Promise<PagedChatMeta | null> {
return this.readPagedMetaAtPath(this.chatMetaPath(agentRef, chatId), chatId)
}
private async readPagedMetaAtPath(
metaPath: string,
chatId: string
): Promise<PagedChatMeta | null> {
let raw: string
try {
raw = await fs.readFile(metaPath, 'utf-8')
} catch (err) {
if (isNotFoundError(err)) return null
throw err
}
try {
const parsed = JSON.parse(raw) as PagedChatMeta
if (
parsed?.version !== PAGED_CHAT_VERSION ||
parsed.chatId !== chatId ||
!Array.isArray(parsed.pages) ||
!isPositiveSafeInteger(parsed.pageSize) ||
!isNonNegativeSafeInteger(parsed.messageCount) ||
!isNonNegativeSafeInteger(parsed.localMessageCount) ||
(parsed.prunedBeforeCount !== undefined &&
!isNonNegativeSafeInteger(parsed.prunedBeforeCount))
) {
throw new Error('Invalid paged chat metadata')
}
let previousPageNumber: number | undefined
for (const page of parsed.pages) {
const pageNumber = pageNumberFromFileName(page.file)
if (
!PAGE_FILE_PATTERN.test(page.file) ||
!isPositiveSafeInteger(page.count) ||
(previousPageNumber !== undefined && pageNumber !== previousPageNumber + 1)
) {
throw new Error('Invalid paged chat metadata page reference')
}
previousPageNumber = pageNumber
}
return this.finalizePagedMeta({
...parsed,
pageSize: normalizePositiveInteger(parsed.pageSize, this.pageSize),
messageCount: parsed.messageCount,
localMessageCount: parsed.localMessageCount,
})
} catch (err) {
throw new Error(`Unable to read paged chat metadata for ${chatId}`, { cause: err })
}
}
private async readLegacyMessages(
agentRef: string,
chatId: string
): Promise<ChatMessage[] | null> {
let raw: string
try {
raw = await fs.readFile(this.chatFilePath(agentRef, chatId), 'utf-8')
} catch (err) {
if (isNotFoundError(err)) return null
throw err
}
try {
const file = JSON.parse(raw) as ChatFile
if (!file || !Array.isArray(file.messages)) {
throw new Error('Invalid legacy chat file')
}
return file.messages
} catch (err) {
// Old flat chat files were written in place, so a crash could leave
// truncated JSON. Quarantine only malformed content; filesystem errors
// above still propagate. Returning "no legacy snapshot" lets the server
// rehydrate the chat and makes subsequent appends writable again.
const corruptPath = this.corruptLegacyChatFilePath(agentRef, chatId)
await fs.mkdir(dirname(corruptPath), { recursive: true, mode: 0o700 })
await fs.rename(this.chatFilePath(agentRef, chatId), corruptPath)
return null
}
}
/**
* Keep a bounded v2 flat-file window for pre-paging desktop builds.
*
* Rewriting this fixed-size window preserves downgrade readability without
* restoring the old unbounded whole-conversation write cost. The server
* remains the source of truth for older synced turns.
*/
private legacyCompatibilitySnapshot(
chatId: string,
messages: ChatMessage[]
): { file: ChatFile; signature: string } {
const compatibilityMessages = messages.slice(-LEGACY_COMPATIBILITY_MESSAGE_LIMIT)
const file: ChatFile = {
version: 2,
chatId,
messages: compatibilityMessages,
}
const signature = createHash('sha256')
.update(JSON.stringify([chatId, compatibilityMessages]))
.digest('hex')
return { file, signature }
}
private async writeLegacyCompatibilitySnapshot(
agentRef: string,
chatId: string,
messages: ChatMessage[]
): Promise<string> {
const { file, signature } = this.legacyCompatibilitySnapshot(chatId, messages)
await this.writeJsonAtomic(this.chatFilePath(agentRef, chatId), file)
await this.writeJsonAtomic(this.chatCompatibilitySignaturePath(agentRef, chatId), {
signature,
})
this.cacheCompatibilityWindow(this.chatSnapshotCleanupKey(agentRef, chatId), file.messages)
return signature
}
private async readLegacyCompatibilitySignature(
agentRef: string,
chatId: string
): Promise<string | null> {
try {
const raw = await fs.readFile(this.chatCompatibilitySignaturePath(agentRef, chatId), 'utf-8')
const parsed = JSON.parse(raw) as { signature?: unknown }
return typeof parsed.signature === 'string' ? parsed.signature : null
} catch {
return null
}
}
private async refreshLegacyCompatibilitySnapshotUnlocked(
agentRef: string,
chatId: string,
meta: PagedChatMeta
): Promise<PagedChatMeta> {
const compatibilityMessages = await this.readMessagesFromPagedMeta(
agentRef,
chatId,
meta,
LEGACY_COMPATIBILITY_MESSAGE_LIMIT
)
const signature = await this.writeLegacyCompatibilitySnapshot(
agentRef,
chatId,
compatibilityMessages
)
const refreshed = { ...meta, legacyCompatibilitySignature: signature }
await this.writePagedMeta(agentRef, chatId, refreshed)
return refreshed
}
/**
* A downgraded build may append local messages to the v2 compatibility file.
* Import only messages missing from the paged snapshot before refreshing the
* bounded window, so upgrading again cannot discard offline work.
*/
private async importDowngradedLocalMessagesUnlocked(
agentRef: string,
chatId: string,
meta: PagedChatMeta
): Promise<PagedChatMeta> {
const compatibilityKey = this.chatSnapshotCleanupKey(agentRef, chatId)
let legacyMessages: ChatMessage[] | null
try {
legacyMessages = await this.readLegacyMessages(agentRef, chatId)
} catch (error) {
if (isRawFilesystemError(error)) {
console.warn(`[chatStore] Downgrade snapshot unavailable for ${chatId}:`, error)
this.compatibilityCheckedKeys.add(compatibilityKey)
return meta
}
const refreshed = await this.refreshLegacyCompatibilitySnapshotUnlocked(
agentRef,
chatId,
meta
)
this.compatibilityCheckedKeys.add(compatibilityKey)
return refreshed
}
if (!legacyMessages) {
const refreshed = await this.refreshLegacyCompatibilitySnapshotUnlocked(
agentRef,
chatId,
meta
)
this.compatibilityCheckedKeys.add(compatibilityKey)
return refreshed
}
this.cacheCompatibilityWindow(compatibilityKey, legacyMessages)
const legacySignature = this.legacyCompatibilitySnapshot(chatId, legacyMessages).signature
if (legacySignature === meta.legacyCompatibilitySignature) {
this.compatibilityCheckedKeys.add(compatibilityKey)
return meta
}
const recordedSignature = await this.readLegacyCompatibilitySignature(agentRef, chatId)
if (legacySignature === recordedSignature) {
const refreshed = await this.refreshLegacyCompatibilitySnapshotUnlocked(
agentRef,
chatId,
meta
)
this.compatibilityCheckedKeys.add(compatibilityKey)
return refreshed
}
const existing = await this.readMessagesFromPagedMeta(agentRef, chatId, meta)
const missing = legacyMessages.filter(
candidate =>
!existing.some(
message =>
sameReconciledMessage(candidate, message) || sameReconciledMessage(message, candidate)
)
)
if (!missing.length) {
const refreshed = await this.refreshLegacyCompatibilitySnapshotUnlocked(
agentRef,
chatId,
meta
)
this.compatibilityCheckedKeys.add(compatibilityKey)
return refreshed
}
const merged = mergeReconciledMessages(existing, missing)
const indexedCount = await this.indexedMessageCount(agentRef, chatId)
const imported = await this.writePagedChatUnlocked(agentRef, chatId, merged, {
messageCount: Math.max(meta.messageCount, merged.length, indexedCount ?? 0),
})
await this.updateChatIndexFromMessages(agentRef, chatId, merged, {
preserveExistingTotals: true,
touchUpdatedAt: false,
})
this.compatibilityCheckedKeys.add(compatibilityKey)
return imported
}
private async readPageMessages(
agentRef: string,
chatId: string,
page: ChatPageEntry
): Promise<ChatMessage[]> {
return this.readPageMessagesAtPath(
chatId,
pageNumberFromFileName(page.file),
this.chatPagePath(agentRef, chatId, page.file)
)
}
private async readPageMessagesAtPath(
chatId: string,
pageNumber: number,
pagePath: string
): Promise<ChatMessage[]> {
const raw = await fs.readFile(pagePath, 'utf-8')
try {
const parsed = JSON.parse(raw) as ChatPageFile
if (
parsed?.version !== PAGED_CHAT_VERSION ||
parsed.chatId !== chatId ||
parsed.pageNumber !== pageNumber ||
!Array.isArray(parsed.messages)
) {
throw new Error('Invalid chat page file')
}
return parsed.messages
} catch (err) {
throw new Error(`Unable to read paged chat page for ${chatId}`, { cause: err })
}
}
private async writePageMessages(
agentRef: string,
chatId: string,
pageNumber: number,
messages: ChatMessage[]
): Promise<ChatPageEntry> {
return this.writePageMessagesToDir(
chatId,
this.chatPagesDirPath(agentRef, chatId),
pageNumber,
messages
)
}
private async writePageMessagesToDir(
chatId: string,
pagesDir: string,
pageNumber: number,
messages: ChatMessage[]
): Promise<ChatPageEntry> {
const file = pageFileName(pageNumber)
const page: ChatPageFile = {
version: PAGED_CHAT_VERSION,
chatId,
pageNumber,
messages,
}
await this.writeJsonAtomic(this.chatPagePathFromPagesDir(pagesDir, file), page)
return pageEntry(file, messages)
}
private async writePagedMeta(
agentRef: string,
chatId: string,
meta: PagedChatMeta
): Promise<void> {
await this.writePagedMetaToDir(chatId, this.chatDirPath(agentRef, chatId), meta)
}
private async writePagedMetaToDir(
chatId: string,
chatDir: string,
meta: PagedChatMeta
): Promise<void> {
await this.writeJsonAtomic(this.chatMetaPathFromChatDir(chatDir), {
...this.finalizePagedMeta(meta),
chatId,
})
}
private async pruneSyncedPages(
meta: PagedChatMeta
): Promise<{ meta: PagedChatMeta; removedFiles: string[] }> {
if (this.maxLocalSyncedMessages === Number.POSITIVE_INFINITY) {
return { meta: this.finalizePagedMeta(meta), removedFiles: [] }
}
let localCount = meta.pages.reduce((total, page) => total + page.count, 0)
let prunedBeforeCount = meta.prunedBeforeCount ?? 0
const retained: ChatPageEntry[] = []
const removedFiles: string[] = []
for (const page of meta.pages) {
const canPrunePage =
page.serverSynced && localCount - page.count >= this.maxLocalSyncedMessages
if (canPrunePage) {
removedFiles.push(page.file)
localCount -= page.count
prunedBeforeCount += page.count
continue
}
retained.push(page)
// Pruning must remove only a contiguous prefix. Once a legacy/local-only
// page is retained, deleting a later synced page would punch a permanent
// hole in the middle of the transcript and make load-older cursors lie.
retained.push(...meta.pages.slice(retained.length + removedFiles.length))
break
}
return {
meta: this.finalizePagedMeta({
...meta,
pages: retained,
prunedBeforeCount: prunedBeforeCount > 0 ? prunedBeforeCount : undefined,
}),
removedFiles,
}
}
/**
* Finish page writes that reached disk before their metadata update.
*
* Existing pages may contain a durable append beyond the count recorded in
* meta.json, and newly-created pages may exist after the last referenced page.
* Both are safe to adopt because page files are themselves written atomically.
*/
private async adoptDurablePageWritesUnlocked(
agentRef: string,
chatId: string,
meta: PagedChatMeta
): Promise<PagedChatMeta | null> {
const pagesDir = this.chatPagesDirPath(agentRef, chatId)
const repairedPages: ChatPageEntry[] = []
let changed = false
for (const [index, page] of meta.pages.entries()) {
let messages: ChatMessage[]
try {
messages = await this.readPageMessages(agentRef, chatId, page)
} catch (error) {
if (isRawFilesystemError(error) && !isNotFoundError(error)) throw error
return null
}
if (messages.length < page.count) return null
if (messages.length > page.count && index !== meta.pages.length - 1) return null
const repaired = pageEntry(page.file, messages)
repairedPages.push(repaired)
changed ||= !samePageEntry(repaired, page)
}
const referenced = new Set(repairedPages.map(page => page.file))
const lastReferencedNumber = pageNumberFromFileName(repairedPages.at(-1)?.file ?? '')
const entries = await fs.readdir(pagesDir).catch(() => [])
const durableOrphans = entries
.filter(
file =>
PAGE_FILE_PATTERN.test(file) &&
!referenced.has(file) &&
pageNumberFromFileName(file) > lastReferencedNumber
)
.sort((a, b) => pageNumberFromFileName(a) - pageNumberFromFileName(b))
let expectedPageNumber = lastReferencedNumber + 1
for (const file of durableOrphans) {
const pageNumber = pageNumberFromFileName(file)
// Reader metadata requires contiguous page numbers. A later orphan cannot
// prove that the missing page was never written, so stop at the first gap.
if (pageNumber !== expectedPageNumber) break
try {
const messages = await this.readPageMessagesAtPath(
chatId,
pageNumber,
this.chatPagePathFromPagesDir(pagesDir, file)
)
if (!messages.length) break
repairedPages.push(pageEntry(file, messages))
referenced.add(file)
changed = true
expectedPageNumber += 1
} catch (error) {
if (isRawFilesystemError(error) && !isNotFoundError(error)) throw error
// Leave an invalid orphan untouched. It is not referenced by metadata,
// so it cannot break reads and may still be useful for manual recovery.
// Later pages are not safe to adopt across this gap.
break
}
}
if (!changed) return meta
const previousLocalCount = meta.pages.reduce((total, page) => total + page.count, 0)
const nextLocalCount = repairedPages.reduce((total, page) => total + page.count, 0)
const repaired = this.finalizePagedMeta({
...meta,
messageCount: Math.max(
meta.messageCount + Math.max(0, nextLocalCount - previousLocalCount),
nextLocalCount + (meta.prunedBeforeCount ?? 0)
),
pages: repairedPages,
})
await this.writePagedMeta(agentRef, chatId, repaired)
await this.updateIndexedMessageCount(agentRef, chatId, repaired.messageCount)
return repaired
}
private async updateIndexedMessageCount(
agentRef: string,
chatId: string,
messageCount: number
): Promise<void> {
await this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const chat = index.chats.find(candidate => candidate.id === chatId)
if (!chat || chat.messageCount >= messageCount) return
chat.messageCount = messageCount
await this.saveIndex(agentRef, index)
})
}
private async rebuildPagedChatFromSurvivingFilesUnlocked(
agentRef: string,
chatId: string
): Promise<boolean> {
const pagesDir = this.chatPagesDirPath(agentRef, chatId)
const entries = await fs.readdir(pagesDir).catch(() => [])
const surviving: ChatMessage[] = []
for (const file of entries
.filter(candidate => PAGE_FILE_PATTERN.test(candidate))
.sort((a, b) => pageNumberFromFileName(a) - pageNumberFromFileName(b))) {
try {
surviving.push(
...(await this.readPageMessagesAtPath(
chatId,
pageNumberFromFileName(file),
this.chatPagePathFromPagesDir(pagesDir, file)
))
)
} catch (error) {
if (isRawFilesystemError(error) && !isNotFoundError(error)) throw error
// Skip only the unreadable page; readable siblings are still valuable.
}
}
const legacy = await this.readLegacyMessages(agentRef, chatId).catch(error => {
if (isRawFilesystemError(error) && !isNotFoundError(error)) throw error
return null
})
const recovered = mergeReconciledMessages(surviving, legacy ?? [])
if (!recovered.length) return false
await this.writePagedChatUnlocked(agentRef, chatId, recovered, {
messageCount: recovered.length,
})
await this.updateIndexedMessageCount(agentRef, chatId, recovered.length)
return true
}
private async recoverPagedChatUnlocked(
agentRef: string,
chatId: string
): Promise<PagedChatMeta | null> {
const activeDir = this.chatDirPath(agentRef, chatId)
const snapshotRoot = this.chatSnapshotRootPath(agentRef, chatId)
const cleanupKey = this.chatSnapshotCleanupKey(agentRef, chatId)
let activeMeta: PagedChatMeta | null = null
let activeReadError: unknown
try {
activeMeta = await this.readPagedMeta(agentRef, chatId)
} catch (err) {
if (isRawFilesystemError(err) && !isNotFoundError(err)) throw err
activeReadError = err
}
if (activeMeta) {
if (this.cleanedSnapshotSiblingKeys.has(cleanupKey)) return activeMeta
const repaired = await this.adoptDurablePageWritesUnlocked(agentRef, chatId, activeMeta)
if (repaired) {
await this.removePagedChatSnapshotSiblings(agentRef, chatId)
this.cleanedSnapshotSiblingKeys.add(cleanupKey)
return repaired
}
activeReadError = new Error(`Paged chat snapshot is incomplete for ${chatId}`)
activeMeta = null
}
if (!activeReadError) {
const activeStat = await fs.stat(activeDir).catch(() => null)
if (activeStat?.isDirectory()) {
activeReadError = new Error(`Paged chat metadata missing for ${chatId}`)
}
}
let entries: Array<{ name: string; isDirectory: () => boolean }>
try {
entries = await fs.readdir(snapshotRoot, { withFileTypes: true })
} catch {
entries = []
}
if (!activeReadError && entries.length === 0) return null
const snapshots = await Promise.all(
entries
.filter(entry => entry.isDirectory())
.map(async entry => {
const nextPrefix = 'next-'
const previousPrefix = 'previous-'
const kind = entry.name.startsWith(nextPrefix)
? 'next'
: entry.name.startsWith(previousPrefix)
? 'previous'
: null
if (!kind) return null
const token =
kind === 'next'
? entry.name.slice(nextPrefix.length)
: entry.name.slice(previousPrefix.length)
if (!token) return null
const dir = join(snapshotRoot, entry.name)
const meta = await this.readPagedMetaAtPath(
this.chatMetaPathFromChatDir(dir),
chatId
).catch(() => null)
if (!meta || !(await this.isCompletePagedSnapshot(dir, chatId, meta))) return null
const stat = await fs.stat(dir).catch(() => null)
return {
dir,
kind,
token,
mtimeMs: stat?.mtimeMs ?? 0,
}
})
)
const validSnapshots = snapshots
.filter((snapshot): snapshot is SnapshotCandidate => snapshot !== null)
.sort((a, b) => b.mtimeMs - a.mtimeMs)
const groups = new Map<
string,
{ next?: SnapshotCandidate; previous?: SnapshotCandidate; mtimeMs: number }
>()
for (const snapshot of validSnapshots) {
const group = groups.get(snapshot.token) ?? { mtimeMs: 0 }
group[snapshot.kind] = snapshot
group.mtimeMs = Math.max(group.mtimeMs, snapshot.mtimeMs)
groups.set(snapshot.token, group)
}
const candidates = [...groups.values()]
.sort((a, b) => b.mtimeMs - a.mtimeMs)
.map(group => group.next ?? group.previous)
.filter((snapshot): snapshot is SnapshotCandidate => Boolean(snapshot))
for (const snapshot of candidates) {
let corruptDir: string | null = null
try {
if (activeReadError) {
corruptDir = this.chatSnapshotSiblingPath(agentRef, chatId, 'corrupt', randomUUID())
try {
await fs.rename(activeDir, corruptDir)
await this.syncRenamedEntry(activeDir, corruptDir)
} catch (err) {
if (!isNotFoundError(err)) throw err
}
} else {
await fs.rm(activeDir, { recursive: true, force: true })
}
await fs.rename(snapshot.dir, activeDir)
await this.syncRenamedEntry(snapshot.dir, activeDir)
await this.removePagedChatSnapshotSiblings(agentRef, chatId)
if (corruptDir) {
await fs.rm(corruptDir, { recursive: true, force: true }).catch(() => undefined)
}
this.cleanedSnapshotSiblingKeys.add(cleanupKey)
return await this.readPagedMeta(agentRef, chatId)
} catch (err) {
if (corruptDir) {
try {
await fs.rename(corruptDir, activeDir)
await this.syncRenamedEntry(corruptDir, activeDir)
} catch {
// Try the next complete snapshot, if one exists.
}
}
// Try the next complete snapshot, if one exists.
}
}
if (await this.rebuildPagedChatFromSurvivingFilesUnlocked(agentRef, chatId)) {
this.cleanedSnapshotSiblingKeys.add(cleanupKey)
return await this.readPagedMeta(agentRef, chatId)
}
if (activeReadError) {
const corruptDir = this.chatSnapshotSiblingPath(agentRef, chatId, 'corrupt', randomUUID())
await fs.mkdir(this.chatSnapshotRootPath(agentRef, chatId), {
recursive: true,
mode: 0o700,
})
try {
await fs.rename(activeDir, corruptDir)
await this.syncRenamedEntry(activeDir, corruptDir)
} catch (err) {
if (!isNotFoundError(err)) throw err
}
console.warn(`[chatStore] Quarantined unreadable paged cache for "${chatId}"`)
return null
}
return null
}
private async removePagedChatSnapshotSiblings(agentRef: string, chatId: string): Promise<void> {
await fs.rm(this.chatSnapshotRootPath(agentRef, chatId), {
recursive: true,
force: true,
})
}
private async isCompletePagedSnapshot(
chatDir: string,
chatId: string,
meta: PagedChatMeta
): Promise<boolean> {
const pagesDir = this.chatPagesDirFromChatDir(chatDir)
for (const page of meta.pages) {
try {
const messages = await this.readPageMessagesAtPath(
chatId,
pageNumberFromFileName(page.file),
this.chatPagePathFromPagesDir(pagesDir, page.file)
)
if (messages.length !== page.count) return false
} catch {
return false
}
}
return true
}
private async writePagedChatUnlocked(
agentRef: string,
chatId: string,
messages: ChatMessage[],
options: { messageCount?: number } = {}
): Promise<PagedChatMeta> {
const chatDir = this.chatDirPath(agentRef, chatId)
const snapshotToken = randomUUID()
const stagingDir = this.chatSnapshotSiblingPath(agentRef, chatId, 'next', snapshotToken)
const backupDir = this.chatSnapshotSiblingPath(agentRef, chatId, 'previous', snapshotToken)
const pagesDir = this.chatPagesDirFromChatDir(stagingDir)
let movedExistingSnapshot = false
let primaryCommitted = false
this.cleanedSnapshotSiblingKeys.delete(this.chatSnapshotCleanupKey(agentRef, chatId))
await fs.mkdir(join(this.agentDir(agentRef), 'chats'), { recursive: true, mode: 0o700 })
await fs.rm(stagingDir, { recursive: true, force: true })
await fs.mkdir(pagesDir, { recursive: true, mode: 0o700 })
try {
const pages: ChatPageEntry[] = []
for (
let start = 0, pageNumber = 1;
start < messages.length;
start += this.pageSize, pageNumber += 1
) {
pages.push(
await this.writePageMessagesToDir(
chatId,
pagesDir,
pageNumber,
messages.slice(start, start + this.pageSize)
)
)
}
const pruned = await this.pruneSyncedPages(
this.finalizePagedMeta({
version: PAGED_CHAT_VERSION,
chatId,
pageSize: this.pageSize,
messageCount: Math.max(messages.length, options.messageCount ?? 0),
localMessageCount: messages.length,
pages,
})
)
const compatibility = this.legacyCompatibilitySnapshot(chatId, messages)
pruned.meta.legacyCompatibilitySignature = compatibility.signature
await this.writePagedMetaToDir(chatId, stagingDir, pruned.meta)
await Promise.all(
pruned.removedFiles.map(file =>
fs.rm(this.chatPagePathFromPagesDir(pagesDir, file), { force: true })
)
)
try {
await fs.rename(chatDir, backupDir)
movedExistingSnapshot = true
await this.syncRenamedEntry(chatDir, backupDir)
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
}
await fs.rename(stagingDir, chatDir)
primaryCommitted = true
await this.syncRenamedEntry(stagingDir, chatDir)
const cacheKey = this.chatSnapshotCleanupKey(agentRef, chatId)
try {
await this.writeLegacyCompatibilitySnapshot(agentRef, chatId, messages)
this.compatibilityCheckedKeys.add(cacheKey)
} catch (error) {
// The paged snapshot is the durable source of truth and has already
// committed. Keep the successful write visible to the caller; a later
// read repairs the auxiliary downgrade window from the paged data.
this.compatibilityCheckedKeys.delete(cacheKey)
console.warn(
`[chatStore] Failed to refresh downgrade snapshot for ${chatId}; retrying on read`,
error
)
}
if (movedExistingSnapshot) {
await fs.rm(backupDir, { recursive: true, force: true }).catch(() => undefined)
}
this.cleanedSnapshotSiblingKeys.add(cacheKey)
return pruned.meta
} catch (err) {
await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined)
if (movedExistingSnapshot && !primaryCommitted) {
await fs
.rename(backupDir, chatDir)
.then(() => this.syncRenamedEntry(backupDir, chatDir))
.catch(() => undefined)
}
throw err
}
}
private async readOrMigratePagedChatUnlocked(
agentRef: string,
chatId: string
): Promise<PagedChatMeta | null> {
const paged = await this.recoverPagedChatUnlocked(agentRef, chatId)
if (paged) {
if (this.compatibilityCheckedKeys.has(this.chatSnapshotCleanupKey(agentRef, chatId))) {
return paged
}
return this.importDowngradedLocalMessagesUnlocked(agentRef, chatId, paged)
}
const legacyMessages = await this.readLegacyMessages(agentRef, chatId)
if (!legacyMessages) return null
const migrated = await this.writePagedChatUnlocked(agentRef, chatId, legacyMessages)
await this.updateChatIndexFromMessages(agentRef, chatId, legacyMessages, {
touchUpdatedAt: false,
})
return migrated
}
private async readMessagesFromPagedMeta(
agentRef: string,
chatId: string,
meta: PagedChatMeta,
limit?: number,
offset?: number
): Promise<ChatMessage[]> {
const localCount = meta.pages.reduce((total, page) => total + page.count, 0)
if (localCount === 0) return []
const effectiveOffset = Math.max(0, Math.floor(offset ?? 0))
const end = Math.max(0, localCount - effectiveOffset)
if (end === 0) return []
const effectiveLimit = limit === undefined ? end : Math.max(0, Math.floor(limit))
if (effectiveLimit === 0) return []
const start = Math.max(0, end - effectiveLimit)
const result: ChatMessage[] = []
let cursor = 0
for (const page of meta.pages) {
const pageStart = cursor
const pageEnd = cursor + page.count
cursor = pageEnd
const overlapStart = Math.max(start, pageStart)
const overlapEnd = Math.min(end, pageEnd)
if (overlapStart >= overlapEnd) continue
const pageMessages = await this.readPageMessages(agentRef, chatId, page)
result.push(...pageMessages.slice(overlapStart - pageStart, overlapEnd - pageStart))
}
return result
}
private async appendPagedMessagesUnlocked(
agentRef: string,
chatId: string,
meta: PagedChatMeta,
newMessages: ChatMessage[]
): Promise<PagedChatMeta> {
if (!newMessages.length) return meta
const cacheKey = this.chatSnapshotCleanupKey(agentRef, chatId)
this.cleanedSnapshotSiblingKeys.delete(cacheKey)
const pages = [...meta.pages]
let remaining = [...newMessages]
const lastPage = pages.at(-1)
if (lastPage && lastPage.count < this.pageSize) {
const currentMessages = await this.readPageMessages(agentRef, chatId, lastPage)
const capacity = Math.max(0, this.pageSize - currentMessages.length)
if (capacity > 0) {
const added = remaining.slice(0, capacity)
remaining = remaining.slice(added.length)
pages[pages.length - 1] = await this.writePageMessages(
agentRef,
chatId,
pageNumberFromFileName(lastPage.file),
[...currentMessages, ...added]
)
}
}
let nextPageNumber = pageNumberFromFileName(pages.at(-1)?.file ?? '') + 1
while (remaining.length) {
const pageMessages = remaining.slice(0, this.pageSize)
remaining = remaining.slice(pageMessages.length)
pages.push(await this.writePageMessages(agentRef, chatId, nextPageNumber, pageMessages))
nextPageNumber += 1
}
const messageCount =
Math.max(meta.messageCount, meta.localMessageCount ?? 0) + newMessages.length
const pruned = await this.pruneSyncedPages({
...meta,
messageCount,
pages,
})
const cachedCompatibilityMessages = this.compatibilityWindows.get(cacheKey)
const compatibilityMessages = cachedCompatibilityMessages
? [...cachedCompatibilityMessages, ...newMessages].slice(-LEGACY_COMPATIBILITY_MESSAGE_LIMIT)
: await this.readMessagesFromPagedMeta(
agentRef,
chatId,
pruned.meta,
LEGACY_COMPATIBILITY_MESSAGE_LIMIT
)
const compatibility = this.legacyCompatibilitySnapshot(chatId, compatibilityMessages)
pruned.meta.legacyCompatibilitySignature = compatibility.signature
await this.writePagedMeta(agentRef, chatId, pruned.meta)
await Promise.all(
pruned.removedFiles.map(file =>
fs.rm(this.chatPagePath(agentRef, chatId, file), { force: true })
)
)
let compatibilityCurrent = compatibility.signature === meta.legacyCompatibilitySignature
if (!compatibilityCurrent) {
try {
await this.writeLegacyCompatibilitySnapshot(agentRef, chatId, compatibilityMessages)
compatibilityCurrent = true
} catch (error) {
// The page and metadata writes above are already durable. Do not turn an
// auxiliary downgrade-window failure into a false append failure.
console.warn(
`[chatStore] Failed to refresh downgrade snapshot for ${chatId}; retrying on read`,
error
)
}
}
this.cleanedSnapshotSiblingKeys.add(cacheKey)
if (compatibilityCurrent) {
this.compatibilityCheckedKeys.add(cacheKey)
} else {
this.compatibilityCheckedKeys.delete(cacheKey)
}
return pruned.meta
}
/**
* The tombstones persisted in the sidecar, or null when there is none.
* An unreadable sidecar is reported (once per agent) and treated as absent:
* the catalog it protects is being rebuilt from an empty one already, and the
* next tombstone write replaces it.
*/
private async readTombstoneSidecar(agentRef: string): Promise<TombstoneSidecar | null> {
let raw: string
try {
raw = await fs.readFile(this.tombstoneSidecarPath(agentRef), 'utf-8')
} catch (error) {
if (isNotFoundError(error)) return null
throw error
}
try {
const parsed = JSON.parse(raw) as Record<string, unknown>
if (
parsed?.version !== TOMBSTONE_SIDECAR_VERSION ||
!Array.isArray(parsed.deletedChatTombstones) ||
!Array.isArray(parsed.pendingChatCleanup)
) {
throw new Error('Invalid tombstone sidecar')
}
return {
version: TOMBSTONE_SIDECAR_VERSION,
deletedChatTombstones: parsed.deletedChatTombstones.filter(isChatDeleteTombstone),
pendingChatCleanup: parsed.pendingChatCleanup.filter(isChatDeleteTombstone),
}
} catch (error) {
if (!this.warnedTombstoneAgents.has(`sidecar:${agentRef}`)) {
this.warnedTombstoneAgents.add(`sidecar:${agentRef}`)
console.warn(
`[chatStore] Unreadable tombstone sidecar for "${agentRef}"; deleted-chat tombstones cannot be recovered`,
error
)
}
return null
}
}
/** Adds the sidecar's tombstones (deduplicated) to an index read from disk. */
private async withRecoveredTombstones(agentRef: string, index: ChatIndex): Promise<ChatIndex> {
const sidecar = await this.readTombstoneSidecar(agentRef)
if (!sidecar) return index
const deletedChatTombstones = mergeTombstones(
index.deletedChatTombstones,
sidecar.deletedChatTombstones
)
const pendingChatCleanup = mergeTombstones(index.pendingChatCleanup, sidecar.pendingChatCleanup)
if (deletedChatTombstones.length > 0) index.deletedChatTombstones = deletedChatTombstones
if (pendingChatCleanup.length > 0) index.pendingChatCleanup = pendingChatCleanup
return index
}
async getIndex(agentRef: string): Promise<ChatIndex> {
let raw: string
try {
raw = await fs.readFile(this.indexPath(agentRef), 'utf-8')
} catch (error) {
// A missing catalog (fresh agent, or one quarantined earlier) still owes
// the tombstones its sidecar holds.
if (isNotFoundError(error)) {
return this.withRecoveredTombstones(agentRef, emptyIndex())
}
throw error
}
try {
const { index, droppedTombstoneEntries } = parseChatIndex(raw)
if (droppedTombstoneEntries === 0) return index
const warnKey = `dropped:${agentRef}`
if (!this.warnedTombstoneAgents.has(warnKey)) {
this.warnedTombstoneAgents.add(warnKey)
console.warn(
`[chatStore] Dropped ${droppedTombstoneEntries} malformed tombstone entr${droppedTombstoneEntries === 1 ? 'y' : 'ies'} from the chat index of "${agentRef}"`
)
}
return this.withRecoveredTombstones(agentRef, index)
} catch (error) {
if (error instanceof UnsupportedChatIndexVersionError) throw error
// Preserve unreadable catalog bytes for bounded recovery/diagnostics, but
// detach them from the writable path so a torn index cannot brick every
// chat mutation. Paged transcripts live under chats/ and remain untouched;
// the catalog can be repopulated by the server as normal writes resume.
// The tombstone sidecar survives the quarantine, so confirmed local
// deletions keep holding on the rebuilt catalog.
const source = this.indexPath(agentRef)
const target = this.corruptIndexPath(agentRef)
await fs.mkdir(dirname(target), { recursive: true, mode: 0o700 })
try {
await fs.rename(source, target)
await this.syncRenamedEntry(source, target)
console.warn(`[chatStore] Quarantined unreadable chat index for "${agentRef}"`)
} catch (renameError) {
if (!isNotFoundError(renameError)) {
throw new Error(`Unable to quarantine chat index for ${agentRef}`, {
cause: renameError,
})
}
}
return this.withRecoveredTombstones(agentRef, emptyIndex())
}
}
private async saveIndex(agentRef: string, index: ChatIndex): Promise<void> {
if (index.version !== INDEX_VERSION) {
throw new Error(`Refusing to overwrite unsupported chat index version ${index.version}`)
}
const dir = this.agentDir(agentRef)
await fs.mkdir(dir, { recursive: true, mode: 0o700 })
// Keep the index readable by the pre-paging desktop while the transcript
// files are maintained in both paged and bounded v2-compatible forms.
const normalized: ChatIndex = { ...index, version: INDEX_VERSION }
// Flush the temp file before rename and the containing directory afterward.
// Visibility atomicity alone does not make the catalog durable across power loss.
const target = this.indexPath(agentRef)
await this.saveTombstoneSidecar(agentRef, normalized)
await this.writeJsonAtomic(target, normalized, 2)
}
/**
* Mirrors the tombstone lists into the sidecar (atomically) whenever they
* change. Skipped for an agent that never had a tombstone. It is written
* before the index, so a rejected save has committed no catalog change. A
* crash between the two writes leaves the sidecar ahead of the index; an
* index read without dropped tombstone entries is authoritative and ignores
* it, and the next save realigns the sidecar with the index.
*/
private async saveTombstoneSidecar(agentRef: string, index: ChatIndex): Promise<void> {
const sidecar: TombstoneSidecar = {
version: TOMBSTONE_SIDECAR_VERSION,
deletedChatTombstones: index.deletedChatTombstones ?? [],
pendingChatCleanup: index.pendingChatCleanup ?? [],
}
const serialized = JSON.stringify(sidecar)
const known = this.tombstoneSidecarSerialized.get(agentRef)
const nothingToProtect =
sidecar.deletedChatTombstones.length === 0 && sidecar.pendingChatCleanup.length === 0
if (known === serialized || (known === undefined && nothingToProtect)) return
await this.writeJsonAtomic(this.tombstoneSidecarPath(agentRef), sidecar)
this.tombstoneSidecarSerialized.set(agentRef, serialized)
}
async listChats(agentRef: string): Promise<ChatMetadata[]> {
const index = await this.getIndex(agentRef)
return index.chats
}
async getLastActiveChatId(agentRef: string): Promise<string | null> {
const index = await this.getIndex(agentRef)
return index.lastActiveChatId
}
async setLastActiveChatId(agentRef: string, chatId: string): Promise<void> {
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
if (this.isDeletedInScope(index, chatId)) return
if (index.lastActiveChatId === chatId) return
index.lastActiveChatId = chatId
await this.saveIndex(agentRef, index)
})
}
async setOnboardingDismissed(agentRef: string, dismissed: boolean): Promise<void> {
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
index.onboardingDismissed = dismissed
await this.saveIndex(agentRef, index)
})
}
async createChat(agentRef: string, chatId: string): Promise<ChatMetadata> {
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
if (this.isDeletedInScope(index, chatId)) {
throw new Error('Chat was deleted locally')
}
const existing = index.chats.find(c => c.id === chatId)
if (existing) return existing
const rememberedTitles = this.serverOnlyTitles.get(agentRef)
const serverTitle = rememberedTitles?.get(chatId)
rememberedTitles?.delete(chatId)
const now = new Date().toISOString()
const meta: ChatMetadata = {
id: chatId,
title: serverTitle ?? 'New Chat',
createdAt: now,
updatedAt: now,
messageCount: 0,
}
index.chats.push(meta)
await this.saveIndex(agentRef, index)
return meta
})
}
async renameChat(agentRef: string, chatId: string, title: string): Promise<void> {
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const chat = index.chats.find(c => c.id === chatId)
if (!chat) return
chat.title = title
chat.updatedAt = new Date().toISOString()
await this.saveIndex(agentRef, index)
})
}
async deleteChat(
agentRef: string,
chatId: string,
authorityScope: ChatAuthorityScope
): Promise<ChatDeleteResult> {
const scope = this.requireAuthorityScope(authorityScope)
const tombstone: ChatDeleteTombstone = { chatId, authorityScope: { ...scope } }
await this.serializeChat(agentRef, chatId, async () => {
this.requireAuthorityScope(scope)
await this.serializeIndex(agentRef, async () => {
this.requireAuthorityScope(scope)
const index = await this.getIndex(agentRef)
index.chats = index.chats.filter(c => c.id !== chatId)
index.deletedChatTombstones = index.deletedChatTombstones ?? []
if (
!index.deletedChatTombstones.some(
existing =>
existing.chatId === chatId && sameChatAuthorityScope(existing.authorityScope, scope)
)
) {
index.deletedChatTombstones.push(tombstone)
}
index.pendingChatCleanup = index.pendingChatCleanup ?? []
if (
!index.pendingChatCleanup.some(
existing =>
existing.chatId === chatId && sameChatAuthorityScope(existing.authorityScope, scope)
)
) {
index.pendingChatCleanup.push(tombstone)
}
if (index.lastActiveChatId === chatId) index.lastActiveChatId = null
await this.saveIndex(agentRef, index)
})
const cacheKey = this.chatSnapshotCleanupKey(agentRef, chatId)
this.cleanedSnapshotSiblingKeys.delete(cacheKey)
this.compatibilityCheckedKeys.delete(cacheKey)
this.dropCompatibilityWindow(cacheKey)
})
const cleaned = await this.finishPendingDeleteCleanup(agentRef, tombstone)
return { cleanupPending: !cleaned }
}
/**
* A deleted chat's cleanup is retried on every catalog read, so a permanent
* failure (EACCES on the chat dir) would repeat forever. Report it once per
* (agent, chat, error code) instead of on every retry, and never hide it.
*/
private warnCleanupFailureOnce(agentRef: string, chatId: string | null, error: unknown): void {
const code = (error as NodeJS.ErrnoException | undefined)?.code ?? 'UNKNOWN'
const key = JSON.stringify([agentRef, chatId, code])
if (this.warnedCleanupFailures.has(key)) return
this.warnedCleanupFailures.add(key)
console.warn(
`[chatStore] Deleted-chat cleanup failed for agent "${agentRef}"${chatId ? ` chat "${chatId}"` : ''} (${code}); it stays queued and is retried`,
error
)
}
private async removeChatArtifacts(
agentRef: string,
chatId: string,
authorityScope: ChatAuthorityScope
): Promise<boolean> {
const corruptLegacyDir = join(this.agentDir(agentRef), '.corrupt')
let corruptLegacyEntries: string[]
try {
corruptLegacyEntries = await fs.readdir(corruptLegacyDir)
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') corruptLegacyEntries = []
else {
this.warnCleanupFailureOnce(agentRef, chatId, error)
return false
}
}
if (!this.authorityScope || !sameChatDeletionIdentity(this.authorityScope, authorityScope)) {
return false
}
const paths = [
{ path: this.chatFilePath(agentRef, chatId), recursive: false },
{ path: join(corruptLegacyDir, encodedChatId(chatId)), recursive: true },
...corruptLegacyEntries
.filter(name => legacyCorruptFileBelongsToChat(name, chatId))
.map(name => ({ path: join(corruptLegacyDir, name), recursive: false })),
{ path: `${this.chatFilePath(agentRef, chatId)}.tmp`, recursive: false },
{ path: this.chatCompatibilitySignaturePath(agentRef, chatId), recursive: false },
{ path: `${this.chatCompatibilitySignaturePath(agentRef, chatId)}.tmp`, recursive: false },
{ path: this.chatDirPath(agentRef, chatId), recursive: true },
]
let allRemoved = true
for (const target of paths) {
if (!this.authorityScope || !sameChatDeletionIdentity(this.authorityScope, authorityScope)) {
return false
}
try {
await fs.rm(target.path, { recursive: target.recursive, force: true })
} catch (error) {
this.warnCleanupFailureOnce(agentRef, chatId, error)
allRemoved = false
}
}
if (!this.authorityScope || !sameChatDeletionIdentity(this.authorityScope, authorityScope)) {
return false
}
try {
await this.removePagedChatSnapshotSiblings(agentRef, chatId)
} catch (error) {
this.warnCleanupFailureOnce(agentRef, chatId, error)
allRemoved = false
}
return (
allRemoved &&
Boolean(this.authorityScope && sameChatDeletionIdentity(this.authorityScope, authorityScope))
)
}
private async finishPendingDeleteCleanup(
agentRef: string,
tombstone: ChatDeleteTombstone
): Promise<boolean> {
if (
!this.authorityScope ||
!sameChatDeletionIdentity(this.authorityScope, tombstone.authorityScope)
) {
return false
}
let artifactsRemoved = false
try {
// Every catalog read starts a retry pass from its own snapshot of the
// queue, so overlapping passes reach the same tombstone. Retry passes
// are serialized per chat (`retryAgentPendingDeleteCleanups`); the later
// one finds it already dequeued and stops. `deleteChat` calls this
// outside `serializeChat`, so a catalog read racing the delete can still
// remove twice; the removal is idempotent (`force`) and can cost one
// more index save.
const index = await this.getIndex(agentRef)
const stillPending = (index.pendingChatCleanup ?? []).some(
existing =>
existing.chatId === tombstone.chatId &&
sameChatDeletionIdentity(existing.authorityScope, tombstone.authorityScope)
)
if (!stillPending) return true
artifactsRemoved = await this.removeChatArtifacts(
agentRef,
tombstone.chatId,
tombstone.authorityScope
)
} catch (error) {
this.warnCleanupFailureOnce(agentRef, tombstone.chatId, error)
return false
}
if (
!artifactsRemoved ||
!this.authorityScope ||
!sameChatDeletionIdentity(this.authorityScope, tombstone.authorityScope)
) {
return false
}
try {
await this.serializeIndex(agentRef, async () => {
this.requireDeletionIdentity(tombstone.authorityScope)
const index = await this.getIndex(agentRef)
index.pendingChatCleanup = (index.pendingChatCleanup ?? []).filter(
existing =>
existing.chatId !== tombstone.chatId ||
!sameChatDeletionIdentity(existing.authorityScope, tombstone.authorityScope)
)
await this.saveIndex(agentRef, index)
})
return true
} catch (error) {
this.warnCleanupFailureOnce(agentRef, tombstone.chatId, error)
return false
}
}
/**
* Retries the calling identity's queued artifact cleanups. With `agentRef`
* only that agent's queue is retried, except on the first retry after a bind
* (`setAuthorityScope`), which walks every agent once so the queues of agents
* that are not read again still finish. Without `agentRef` every agent is
* walked.
*/
async retryPendingDeleteCleanups(
authorityScope: ChatAuthorityScope,
agentRef?: string
): Promise<void> {
const scope = this.requireDeletionIdentity(authorityScope)
if (agentRef !== undefined && !this.pendingCleanupSweep) {
await this.retryAgentPendingDeleteCleanups(agentRef, scope)
return
}
this.pendingCleanupSweep = false
let entries
try {
entries = await fs.readdir(this.baseDir, { withFileTypes: true })
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
// The walk did not happen: the next retry attempts it again.
this.pendingCleanupSweep = true
throw error
}
for (const entry of entries) {
if (!entry.isDirectory()) continue
if (!(await this.retryAgentPendingDeleteCleanups(entry.name, scope))) return
}
}
/** Retries one agent's queue; false once the identity changed and retrying must stop. */
private async retryAgentPendingDeleteCleanups(
agentRef: string,
scope: ChatAuthorityScope
): Promise<boolean> {
try {
const index = await this.getIndex(agentRef)
const pending = (index.pendingChatCleanup ?? []).filter(item =>
sameChatDeletionIdentity(item.authorityScope, scope)
)
for (const tombstone of pending) {
if (!this.authorityScope || !sameChatDeletionIdentity(this.authorityScope, scope)) {
return false
}
await this.serializeChat(agentRef, tombstone.chatId, () =>
this.finishPendingDeleteCleanup(agentRef, tombstone)
)
}
} catch (error) {
// An unrelated or unreadable agent index must not prevent other durable
// cleanup entries from being retried on the next authorized read, but the
// failure is reported (once per agent and code), never swallowed.
this.warnCleanupFailureOnce(agentRef, null, error)
}
return true
}
async loadMessages(
agentRef: string,
chatId: string,
limit?: number,
offset?: number
): Promise<ChatMessage[]> {
try {
return await this.serializeChat(agentRef, chatId, async () => {
const index = await this.getIndex(agentRef)
if (this.isDeletedInScope(index, chatId)) return []
const meta = await this.readOrMigratePagedChatUnlocked(agentRef, chatId)
if (!meta) return []
return this.readMessagesFromPagedMeta(agentRef, chatId, meta, limit, offset)
})
} catch (err) {
if (isUnsafeSegmentError(err)) return []
throw err
}
}
private async updateChatIndexFromMessages(
agentRef: string,
chatId: string,
messages: ChatMessage[],
options: { preserveExistingTotals?: boolean; touchUpdatedAt?: boolean } = {}
): Promise<void> {
await this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const chat = index.chats.find(c => c.id === chatId)
if (!chat) return
const aggregate = aggregateMessages(messages)
const displayMessageCount = visibleMessageCount(messages)
if (options.preserveExistingTotals) {
chat.messageCount = Math.max(chat.messageCount ?? 0, displayMessageCount)
chat.errorCount = Math.max(chat.errorCount ?? 0, aggregate.errorCount ?? 0)
chat.toolCallCount = Math.max(chat.toolCallCount ?? 0, aggregate.toolCallCount ?? 0)
} else {
chat.messageCount = displayMessageCount
Object.assign(chat, aggregate)
}
if (options.touchUpdatedAt !== false) {
chat.updatedAt = new Date().toISOString()
}
await this.saveIndex(agentRef, index)
})
}
private async indexedMessageCount(agentRef: string, chatId: string): Promise<number | undefined> {
try {
const index = await this.getIndex(agentRef)
return index.chats.find(chat => chat.id === chatId)?.messageCount
} catch {
return undefined
}
}
private async saveMessagesInternal(
agentRef: string,
chatId: string,
messages: ChatMessage[],
options: { preserveExistingTotals?: boolean } = {}
): Promise<void> {
return this.serializeChat(agentRef, chatId, async () => {
const index = await this.getIndex(agentRef)
if (this.isDeletedInScope(index, chatId)) return
const indexedCount = options.preserveExistingTotals
? await this.indexedMessageCount(agentRef, chatId)
: undefined
await this.writePagedChatUnlocked(agentRef, chatId, messages, {
messageCount: Math.max(messages.length, indexedCount ?? 0),
})
await this.updateChatIndexFromMessages(agentRef, chatId, messages, {
preserveExistingTotals: options.preserveExistingTotals,
})
})
}
async saveMessages(agentRef: string, chatId: string, messages: ChatMessage[]): Promise<void> {
return this.saveMessagesInternal(agentRef, chatId, messages)
}
/**
* Upsert a server reconciliation window without truncating unseen history.
*
* Reconciliation is intentionally bounded, while the local store may contain
* older pages or optimistic messages that are not present in that window.
* Merge the window into the complete local snapshot before publishing a new
* generation so a background reconcile cannot discard either category.
*/
async replaceMessages(
agentRef: string,
chatId: string,
messages: ChatMessage[],
options: ReplaceChatMessagesOptions = {}
): Promise<void> {
await this.serializeChat(agentRef, chatId, async () => {
const index = await this.getIndex(agentRef)
if (this.isDeletedInScope(index, chatId)) return
const existingMeta = await this.readOrMigratePagedChatUnlocked(agentRef, chatId)
const existingMessages = existingMeta
? await this.readMessagesFromPagedMeta(agentRef, chatId, existingMeta)
: []
const replaceLegacyTurnlessWindow =
existingMessages.length > 0 &&
!options.activeTaskIds?.length &&
existingMessages.every(message => messageServerTurnNumber(message) === undefined) &&
messages.some(message => messageServerTurnNumber(message) !== undefined)
const merged = mergeAuthoritativeServerMessages(existingMessages, messages, {
activeTaskIds: options.activeTaskIds ? new Set(options.activeTaskIds) : undefined,
replaceLegacyTurnlessWindow,
})
const indexedCount = await this.indexedMessageCount(agentRef, chatId)
await this.writePagedChatUnlocked(agentRef, chatId, merged, {
messageCount: Math.max(merged.length, indexedCount ?? 0),
})
await this.updateChatIndexFromMessages(agentRef, chatId, merged, {
preserveExistingTotals: true,
})
})
}
async backfillChatCounters(
agentRef: string,
chatId: string,
messages: ChatMessage[]
): Promise<void> {
await this.updateChatIndexFromMessages(agentRef, chatId, messages, {
preserveExistingTotals: true,
touchUpdatedAt: false,
})
}
async appendMessages(
agentRef: string,
chatId: string,
newMessages: ChatMessage[]
): Promise<void> {
return this.serializeChat(agentRef, chatId, async () => {
const indexBeforeAppend = await this.getIndex(agentRef)
if (this.isDeletedInScope(indexBeforeAppend, chatId)) return
const existing =
(await this.readOrMigratePagedChatUnlocked(agentRef, chatId)) ??
(await this.writePagedChatUnlocked(agentRef, chatId, []))
await this.appendPagedMessagesUnlocked(agentRef, chatId, existing, newMessages)
await this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const chat = index.chats.find(c => c.id === chatId)
if (chat) {
const delta = aggregateMessages(newMessages)
chat.messageCount = (chat.messageCount ?? 0) + visibleMessageCount(newMessages)
chat.errorCount = (chat.errorCount ?? 0) + (delta.errorCount ?? 0)
chat.toolCallCount = (chat.toolCallCount ?? 0) + (delta.toolCallCount ?? 0)
chat.updatedAt = new Date().toISOString()
await this.saveIndex(agentRef, index)
}
})
})
}
/**
* Insert or update messages by reconciled identity before a send's task id is
* known. A send is first persisted optimistically, then updated in place after
* its acknowledgement; append-only writes would duplicate the same user row.
*/
async upsertMessages(agentRef: string, chatId: string, messages: ChatMessage[]): Promise<void> {
if (!messages.length) return
return this.serializeChat(agentRef, chatId, async () => {
const index = await this.getIndex(agentRef)
if (this.isDeletedInScope(index, chatId)) return
const existingMeta =
(await this.readOrMigratePagedChatUnlocked(agentRef, chatId)) ??
(await this.writePagedChatUnlocked(agentRef, chatId, []))
const existingMessages = await this.readMessagesFromPagedMeta(agentRef, chatId, existingMeta)
const merged = mergeReconciledMessages(existingMessages, messages)
const indexedCount = await this.indexedMessageCount(agentRef, chatId)
await this.writePagedChatUnlocked(agentRef, chatId, merged, {
messageCount: Math.max(merged.length, indexedCount ?? 0),
})
await this.updateChatIndexFromMessages(agentRef, chatId, merged, {
preserveExistingTotals: true,
})
})
}
/**
* Flag that a task terminated while the chat was not the active view (D.5).
* Idempotent: a no-op when already flagged, so a noisy task can't spam FS writes.
*/
async markUnreadTerminal(agentRef: string, chatId: string): Promise<void> {
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const chat = index.chats.find(c => c.id === chatId)
if (!chat || chat.unreadTerminal === true) return
chat.unreadTerminal = true
chat.lastTerminalAt = new Date().toISOString()
await this.saveIndex(agentRef, index)
})
}
/**
* Reconcile the local index against the server's session listing (spec §5.3).
* The mcp-host is the source of truth; this refreshes `updatedAt` for chats
* ALREADY tracked locally so the persisted sidebar order/freshness survives a
* cold start without a server round-trip.
*
* Deliberately does NOT create entries for server-only sessions: the sidebar's
* in-memory merge (`useChatListController`) already surfaces those, and a local
* `deleteChat` doesn't remove the server session — eagerly re-persisting it
* would resurrect a chat the user just deleted. Their titles are only kept in
* memory (`serverOnlyTitles`) so `createChat` can use them on first open.
*
* `title`, when present, is the server's own title for the session. It is
* stored so a cold start paints the last title the server reported instead of
* the hydration placeholder; the next catalog page overwrites it, so it never
* diverges from the server for longer than one load. The caller omits it while
* a local rename is pending. A title change does not touch `updatedAt`: the
* sidebar order stays driven by server activity. Returns the count of entries
* changed.
*/
async upsertServerSessions(
agentRef: string,
sessions: Array<{ chatId: string; lastActivityAt?: string; title?: string }>
): Promise<number> {
if (!sessions.length) return 0
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const byId = new Map(index.chats.map(chat => [chat.id, chat]))
let changed = 0
for (const session of sessions) {
const chat = byId.get(session.chatId)
if (!chat) {
// Server-only session: never create an entry (that would resurrect a
// local delete). Remember its title for `createChat`; a session sent
// without one (e.g. a pending local rename) forgets the old title.
this.rememberServerOnlyTitle(agentRef, session.chatId, session.title)
continue
}
let chatChanged = false
const lastActivityAt = session.lastActivityAt
if (
lastActivityAt &&
new Date(lastActivityAt).getTime() > new Date(chat.updatedAt).getTime()
) {
chat.updatedAt = lastActivityAt
chatChanged = true
}
if (session.title && session.title !== chat.title) {
chat.title = session.title
chatChanged = true
}
if (chatChanged) changed += 1
}
if (changed > 0) await this.saveIndex(agentRef, index)
return changed
})
}
private rememberServerOnlyTitle(agentRef: string, chatId: string, title?: string): void {
let titles = this.serverOnlyTitles.get(agentRef)
if (!title) {
titles?.delete(chatId)
return
}
if (!titles) {
titles = new Map()
this.serverOnlyTitles.set(agentRef, titles)
}
titles.set(chatId, title)
}
/** Clear the unread-terminal flag (D.5), e.g. when the user opens the chat. */
async clearUnreadTerminal(agentRef: string, chatId: string): Promise<void> {
return this.serializeIndex(agentRef, async () => {
const index = await this.getIndex(agentRef)
const chat = index.chats.find(c => c.id === chatId)
if (!chat || !chat.unreadTerminal) return
chat.unreadTerminal = false
await this.saveIndex(agentRef, index)
})
}
}