Skip to content
zidane
SDK reference

zidane/durable/sqlite

A durable runtime that checkpoints agent runs in a SQLite file, for Bun.

import { … } from 'zidane/durable/sqlite'src/durable/sqlite.ts

Use createSqliteRuntime when a run must continue after its process crashes. It records each model call and tool call in the SQLite sessions file, commits with synchronous = FULL, and its stores.session is the session store to create sessions on. After a crash, agent.resume() in the next process continues the run. It needs Bun (bun:sqlite). See crash recovery.

createSqliteRuntime takes a SqliteRuntimeOptions with one field, path. It creates the file when it is missing, but the directory must exist. It returns a SqliteRuntime, a SqliteDurableRuntime that owns its connection. Call close() to stop its waits and close the connection. A second call does nothing.

TypeScript
import { createAgent } from 'zidane'
import { createSqliteRuntime } from 'zidane/durable/sqlite'
import { anthropic } from 'zidane/providers/anthropic'

const runtime = createSqliteRuntime({ path: './sessions.db' })
const agent = createAgent({ provider: anthropic(), durable: runtime, sessionId: 'job-42' })
// Continue the run a crash cut off, if any; null when there is none.
if (!await agent.resume())
  await agent.run({ prompt: 'Migrate the config files.' })
runtime.close()

Functions#

createSqliteRuntimeFunction#

Open the checkpoint durable runtime over the SQLite file at path, with its own connection. Close it with close().

TypeScript
function createSqliteRuntime(options: SqliteRuntimeOptions): SqliteRuntime

Parameters

Parameters
NameTypeDescription
optionsSqliteRuntimeOptions

Runtime options.

src/durable/sqlite.ts:54

Interfaces#

SqliteDurableRuntimeInterface#

A runtime whose timers can be stopped; the caller closes the connection.

TypeScript
interface SqliteDurableRuntime extends DurableRuntime

Properties

SqliteDurableRuntime properties
NameTypeDescription
dispose() => void

Stop the awakeable waits of this runtime (they never settle). Idempotent.

findAwakeable?from DurableRuntime(sessionId: string, key: `${string}:${number}:${string}:${number}`) => Promise<AwakeableRecord | undefined>

The stored awakeable of (sessionId, key), for a resumer that knows what a run waits on but not the id (a prompt rehydrated from the session's turns). undefined: none. Absent on runtimes without an awakeable table.

isControlErrorfrom DurableRuntime(error: unknown) => boolean

Errors the runtime uses to stop or suspend a run: the loop rethrows them untouched instead of reporting a failed call.

lease?readonlyfrom DurableRuntimeDurableLease

Who runs each session's run. Absent where the platform guarantees one writer.

modereadonlyfrom DurableRuntimeDurableMode

How the runtime recovers a run, see DurableMode.

openRunfrom DurableRuntime(options: OpenRunOptions) => Promise<RunScope>

Open a run's scope. Handlers are per scope, never shared with another run.

resolveAwakeablefrom DurableRuntime(id: string, value: JsonValue) => Promise<boolean>

Resolve an awakeable, also while no process runs its run (the run gets the value when it resumes). Call it from the resumer's side: another process or an ingress client, never the run that waits. In replay mode, resolving from the waiter's own journal shifts every later entry.

false: no awakeable has that id, e.g. a prompt left open by a build without awakeables, and the caller falls back to its own handling. Only runtimes that keep an awakeable table can tell; the others answer true.

storesreadonlyfrom DurableRuntimeDurableStores

Where a run persists its session, tool state, queue and submissions.

src/durable/sqlite-runtime.ts:113

SqliteRuntimeInterface#

A SQLite durable runtime that owns its connection.

TypeScript
interface SqliteRuntime extends SqliteDurableRuntime

Properties

SqliteRuntime properties
NameTypeDescription
close() => void

Stop its waits and close the connection. Idempotent.

disposefrom SqliteDurableRuntime() => void

Stop the awakeable waits of this runtime (they never settle). Idempotent.

findAwakeable?from SqliteDurableRuntime(sessionId: string, key: `${string}:${number}:${string}:${number}`) => Promise<AwakeableRecord | undefined>

The stored awakeable of (sessionId, key), for a resumer that knows what a run waits on but not the id (a prompt rehydrated from the session's turns). undefined: none. Absent on runtimes without an awakeable table.

isControlErrorfrom SqliteDurableRuntime(error: unknown) => boolean

Errors the runtime uses to stop or suspend a run: the loop rethrows them untouched instead of reporting a failed call.

lease?readonlyfrom SqliteDurableRuntimeDurableLease

Who runs each session's run. Absent where the platform guarantees one writer.

modereadonlyfrom SqliteDurableRuntimeDurableMode

How the runtime recovers a run, see DurableMode.

openRunfrom SqliteDurableRuntime(options: OpenRunOptions) => Promise<RunScope>

Open a run's scope. Handlers are per scope, never shared with another run.

resolveAwakeablefrom SqliteDurableRuntime(id: string, value: JsonValue) => Promise<boolean>

Resolve an awakeable, also while no process runs its run (the run gets the value when it resumes). Call it from the resumer's side: another process or an ingress client, never the run that waits. In replay mode, resolving from the waiter's own journal shifts every later entry.

false: no awakeable has that id, e.g. a prompt left open by a build without awakeables, and the caller falls back to its own handling. Only runtimes that keep an awakeable table can tell; the others answer true.

storesreadonlyfrom SqliteDurableRuntimeDurableStores

Where a run persists its session, tool state, queue and submissions.

src/durable/sqlite.ts:43

SqliteRuntimeOptionsInterface#

Options of createSqliteRuntime.

TypeScript
interface SqliteRuntimeOptions

Properties

SqliteRuntimeOptions properties
NameTypeDescription
pathstring

Path of the SQLite sessions file. Created when missing (its directory must exist).

src/durable/sqlite.ts:37