The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.
TypeScript agentai-chatai-studioall-in-onecoding-agentdesktop-appfluximage-generationlinuxllmlocal-ailocal-llmopen-sourceprivacyself-hostedstable-diffusionuncensoreduncensored-aivideo-generationwindows
// The part of an answer that has arrived, written so that it survives a hard
// kill of the app.
//
// Finding (acceptance on Android, buttons, H2): a local answer was running,
// about 250 characters stood on screen, the app was killed (`am force-stop`).
// After the restart only the question was there, while the app said "The part
// that arrived is kept".
//
// The chat store does write while an answer streams, every two seconds at the
// latest (lib/coalescedStorage.ts). But an IndexedDB write is "relaxed" by
// default: the browser reports it done before the bytes are on the disk, and
// a process that is killed takes its unwritten buffer with it. The same is
// true for localStorage. A kill by the system after a while in the background
// loses nothing, which is why this went unnoticed: by then the buffer was out.
//
// So a phone keeps a second, tiny record for every running answer: which
// message, and its text so far. It goes into a database of its own with
// durability "strict", which makes the browser wait for the disk. A few
// hundred bytes every second and a half cost nothing; writing the whole chat
// history that way would. On the next start the sweep of interrupted runs
// (lib/interrupted-runs.ts) puts the text back when the history has less.
import { log } from './logger'
export interface AnswerCheckpoint {
conversationId: string
messageId: string
content: string
thinking?: string
modelId?: string
/** When the message was created. */
timestamp: number
}
export interface CheckpointMessage {
id: string
role: string
content: string
thinking?: string
hidden?: boolean
finishReason?: string
modelId?: string
timestamp?: number
}
/** How often a running answer is written. */
export const CHECKPOINT_EVERY_MS = 1500
/**
* How often a run that has no text yet is looked at for its first text. The
* regular beat wrote for the first time 1.5 s after the run began, so a kill
* before that lost the beginning the user had already read: 475 to 971
* characters, 6 of 6 at 1.0 and 1.4 s (check on the iPhone, M2). Looking is a
* read of the chat store, nothing is written until there is text.
*
* 25 ms and not 100 (finding N7 of the Android review: 1 of 14 kills after
* visible text came back with "Nothing of the answer was saved"): the text
* stood on screen up to one look before the record was even started, and the
* strict write comes after that. The look costs one array walk, for the first
* second of a run only.
*/
export const FIRST_TEXT_LOOK_MS = 25
/** One more early record this long after the first: the first holds a few characters only. */
export const SECOND_RECORD_AFTER_MS = 500
const DB_NAME = 'lu-answer-checkpoints'
const STORE = 'answers'
/** Which runs began and which of them ended, written as durably as the answers (see RunMark). */
const RUNS = 'runs'
const STORES = [STORE, RUNS] as const
/**
* When a run began in a conversation and, once it has, when it ended.
*
* The ledger of open runs (lib/interrupted-runs.ts) lives in localStorage,
* and a WebView has a write to localStorage on the disk only 0.3 to 2
* seconds later. An app that was swiped away right after an answer had
* finished came back with the run still in the ledger, and the finished
* answer was labelled "interrupted" (review of round 6, finding 7). This
* record says the same thing through the one door that waits for the disk.
*/
export interface RunMark {
openedAt: number
closedAt?: number
}
/**
* Pure: the answer a run is writing, or null. It is the last visible message
* when that is an assistant message nobody has finished yet.
*/
export function openAnswerOf(conversationId: string, messages: readonly CheckpointMessage[]): AnswerCheckpoint | null {
let last: CheckpointMessage | undefined
for (let i = messages.length - 1; i >= 0; i--) {
if (!messages[i].hidden) {
last = messages[i]
break
}
}
if (!last || last.role !== 'assistant' || last.finishReason) return null
return {
conversationId,
messageId: last.id,
content: last.content,
...(last.thinking ? { thinking: last.thinking } : {}),
...(last.modelId ? { modelId: last.modelId } : {}),
timestamp: typeof last.timestamp === 'number' ? last.timestamp : Date.now(),
}
}
export type CheckpointRepair =
/** The history has as much as the record, or more. Nothing to do. */
| { kind: 'none' }
/** The answer is in the history, but with less text than was written. */
| { kind: 'longer'; messageId: string; content: string; thinking?: string }
/** The history ends with the question: the answer never reached the disk. */
| { kind: 'missing'; checkpoint: AnswerCheckpoint }
/**
* Pure: what a record has to put back into the history that came off the
* disk. A record only ever speaks for the answer at the end of its chat, and
* never for one that was finished: a healthy answer is not touched.
*/
export function repairFromCheckpoint(messages: readonly CheckpointMessage[], checkpoint: AnswerCheckpoint | null | undefined): CheckpointRepair {
if (!checkpoint) return { kind: 'none' }
const hasText = checkpoint.content.trim() !== '' || (checkpoint.thinking ?? '').trim() !== ''
if (!hasText) return { kind: 'none' }
const visible = messages.filter((m) => !m.hidden)
const last = visible[visible.length - 1]
if (!last) return { kind: 'none' }
if (last.role === 'assistant') {
if (last.id !== checkpoint.messageId || last.finishReason) return { kind: 'none' }
const longerText = checkpoint.content.length > last.content.length
const longerThought = (checkpoint.thinking ?? '').length > (last.thinking ?? '').length
if (!longerText && !longerThought) return { kind: 'none' }
return {
kind: 'longer',
messageId: last.id,
content: longerText ? checkpoint.content : last.content,
...(longerThought ? { thinking: checkpoint.thinking } : {}),
}
}
// The answer of this record was never written to the history at all. It belongs right after
// the question, and only when the history does not know its id from somewhere else.
if (last.role !== 'user' || messages.some((m) => m.id === checkpoint.messageId)) return { kind: 'none' }
return { kind: 'missing', checkpoint }
}
function hasIDB(): boolean {
return typeof indexedDB !== 'undefined'
}
let opening: Promise<IDBDatabase> | null = null
function db(): Promise<IDBDatabase> {
if (opening) return opening
opening = new Promise<IDBDatabase>((resolve, reject) => {
// Version 2 added the store of the run marks. The answers stay as they are.
const request = indexedDB.open(DB_NAME, 2)
request.onupgradeneeded = () => {
for (const name of STORES) {
if (!request.result.objectStoreNames.contains(name)) request.result.createObjectStore(name)
}
}
request.onsuccess = () => {
const base = request.result
if (STORES.every((name) => base.objectStoreNames.contains(name))) {
resolve(base)
return
}
// A database of this name without the store (made by something that only looked): start it again.
base.close()
const gone = indexedDB.deleteDatabase(DB_NAME)
gone.onsuccess = gone.onerror = gone.onblocked = () => reject(new Error('the checkpoint database had no store'))
}
request.onerror = () => reject(request.error ?? new Error('could not open the checkpoint database'))
request.onblocked = () => reject(new Error('the checkpoint database is blocked'))
})
// A failed open is tried again by the next write.
opening.catch(() => {
opening = null
})
return opening
}
function strictWrite(base: IDBDatabase, store: string = STORE): IDBTransaction {
try {
// "strict": the browser reports the write done only when it is on the disk.
return base.transaction(store, 'readwrite', { durability: 'strict' })
} catch {
// An older WebView does not know the option. The write is then as durable as any other.
return base.transaction(store, 'readwrite')
}
}
function done(tx: IDBTransaction): Promise<void> {
return new Promise((resolve, reject) => {
tx.oncomplete = () => resolve()
tx.onerror = () => reject(tx.error)
tx.onabort = () => reject(tx.error)
})
}
/** Write the record of one running answer. Never throws: a record that cannot be written costs the repair, not the run. */
export async function writeCheckpoint(checkpoint: AnswerCheckpoint): Promise<boolean> {
if (!hasIDB()) return false
try {
const tx = strictWrite(await db())
tx.objectStore(STORE).put(checkpoint, checkpoint.conversationId)
await done(tx)
return true
} catch (err) {
log.warn('[answer-checkpoint] could not write', { err: String(err) })
return false
}
}
/** The run ended on its own terms: its record is not needed any more. */
export async function clearCheckpoint(conversationId: string): Promise<void> {
if (!hasIDB()) return
try {
const tx = strictWrite(await db())
tx.objectStore(STORE).delete(conversationId)
await done(tx)
} catch {
/* a record that stays is ignored by the repair once its answer is finished */
}
}
/** Every record on the disk, by conversation. Empty when there is none or the database cannot be read. */
export async function readCheckpoints(): Promise<Record<string, AnswerCheckpoint>> {
if (!hasIDB()) return {}
try {
const base = await db()
return await new Promise<Record<string, AnswerCheckpoint>>((resolve, reject) => {
const out: Record<string, AnswerCheckpoint> = {}
const request = base.transaction(STORE, 'readonly').objectStore(STORE).openCursor()
request.onsuccess = () => {
const cursor = request.result
if (!cursor) {
resolve(out)
return
}
const value = cursor.value as Partial<AnswerCheckpoint> | null
if (value && typeof value.messageId === 'string' && typeof value.content === 'string') {
out[String(cursor.key)] = { ...(value as AnswerCheckpoint), conversationId: String(cursor.key) }
}
cursor.continue()
}
request.onerror = () => reject(request.error)
})
} catch {
return {}
}
}
/** Forget every record. Called after the repair of a start. */
export async function clearAllCheckpoints(): Promise<void> {
if (!hasIDB()) return
try {
const tx = strictWrite(await db())
tx.objectStore(STORE).clear()
await done(tx)
} catch {
/* see clearCheckpoint */
}
}
/** Where the run marks are kept. A seam, so the sweep is tested without a database. */
export interface RunMarkStore {
/** Write the mark of one conversation. Resolves once it is on the disk. Never throws. */
write(conversationId: string, mark: RunMark): Promise<void>
/** Every mark on the disk. Empty when there is none or the database cannot be read. */
read(): Promise<Record<string, RunMark>>
/** Forget every mark but the ones of `keep`. */
clear(keep: readonly string[]): Promise<void>
}
/** The run marks in the database of the answers, written with durability "strict". */
export const diskRunMarks: RunMarkStore = {
async write(conversationId, mark) {
if (!hasIDB()) return
try {
const tx = strictWrite(await db(), RUNS)
tx.objectStore(RUNS).put(mark, conversationId)
await done(tx)
} catch (err) {
log.warn('[answer-checkpoint] could not write a run mark', { err: String(err) })
}
},
async read() {
if (!hasIDB()) return {}
try {
const base = await db()
return await new Promise<Record<string, RunMark>>((resolve, reject) => {
const out: Record<string, RunMark> = {}
const request = base.transaction(RUNS, 'readonly').objectStore(RUNS).openCursor()
request.onsuccess = () => {
const cursor = request.result
if (!cursor) {
resolve(out)
return
}
const value = cursor.value as Partial<RunMark> | null
if (value && typeof value.openedAt === 'number') {
out[String(cursor.key)] = {
openedAt: value.openedAt,
...(typeof value.closedAt === 'number' ? { closedAt: value.closedAt } : {}),
}
}
cursor.continue()
}
request.onerror = () => reject(request.error)
})
} catch {
return {}
}
},
async clear(keep) {
if (!hasIDB()) return
try {
const base = await db()
const kept = new Set(keep)
const tx = strictWrite(base, RUNS)
const store = tx.objectStore(RUNS)
if (kept.size === 0) {
store.clear()
} else {
const request = store.openCursor()
request.onsuccess = () => {
const cursor = request.result
if (!cursor) return
if (!kept.has(String(cursor.key))) cursor.delete()
cursor.continue()
}
}
await done(tx)
} catch {
/* a mark that stays is judged again at the next start, against the ledger of then */
}
},
}
/**
* Keeps the records of the running answers. `read` hands in the answer a
* conversation is writing right now (the chat store), `write` puts it on the
* disk. One writer per conversation, and a text that did not change is not
* written again.
*/
export function createCheckpointer(
read: (conversationId: string) => AnswerCheckpoint | null,
write: (checkpoint: AnswerCheckpoint) => Promise<unknown> = writeCheckpoint,
clear: (conversationId: string) => Promise<unknown> = clearCheckpoint,
everyMs: number = CHECKPOINT_EVERY_MS,
) {
const timers = new Map<string, ReturnType<typeof setInterval>>()
const written = new Map<string, string>()
/** The early look of a run: the interval that waits for the first text, then the one shot for the second record. */
const early = new Map<string, { look?: ReturnType<typeof setInterval>; again?: ReturnType<typeof setTimeout> }>()
const stopEarly = (conversationId: string) => {
const e = early.get(conversationId)
if (e?.look !== undefined) clearInterval(e.look)
if (e?.again !== undefined) clearTimeout(e.again)
early.delete(conversationId)
}
const save = async (conversationId: string): Promise<void> => {
const now = read(conversationId)
if (!now) return
const mark = `${now.messageId}:${now.content.length}:${(now.thinking ?? '').length}`
if (written.get(conversationId) === mark) return
written.set(conversationId, mark)
await write(now)
}
return {
/** A run began in this conversation. */
open(conversationId: string): void {
if (timers.has(conversationId)) return
timers.set(conversationId, setInterval(() => void save(conversationId), everyMs))
// The first record is written with the first text, not with the first beat (see FIRST_TEXT_LOOK_MS).
// Off the path of the stream: a timer of its own, and one write.
const look = setInterval(() => {
const now = read(conversationId)
if (!now || (now.content === '' && !now.thinking)) return
clearInterval(look)
void save(conversationId)
early.set(conversationId, { again: setTimeout(() => { early.delete(conversationId); void save(conversationId) }, Math.min(SECOND_RECORD_AFTER_MS, everyMs)) })
}, Math.min(FIRST_TEXT_LOOK_MS, everyMs))
early.set(conversationId, { look })
},
/** The run ended on its own terms. */
close(conversationId: string): void {
const timer = timers.get(conversationId)
if (timer !== undefined) clearInterval(timer)
timers.delete(conversationId)
stopEarly(conversationId)
written.delete(conversationId)
void clear(conversationId)
},
/** Write every running answer now: the app is leaving the screen. */
saveAll(): Promise<void> {
return Promise.all([...timers.keys()].map((id) => save(id))).then(() => undefined)
},
stop(): void {
for (const timer of timers.values()) clearInterval(timer)
for (const id of [...early.keys()]) stopEarly(id)
timers.clear()
written.clear()
},
}
}