# zidane/durable/sqlite

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

Import: `import { … } from 'zidane/durable/sqlite'`. Source: [src/durable/sqlite.ts](https://github.com/Tahul/zidane/blob/main/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](https://zidane.si/docs/durability.md).

`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.

```ts
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

### `createSqliteRuntime`

Function.

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

```ts
function createSqliteRuntime(options: SqliteRuntimeOptions): SqliteRuntime
```

**Parameters**

- `options` (`SqliteRuntimeOptions`): Runtime options.

**Returns** `SqliteRuntime`

Source: [src/durable/sqlite.ts:54](https://github.com/Tahul/zidane/blob/main/src/durable/sqlite.ts#L54)

## Interfaces

### `SqliteDurableRuntime`

Interface.

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

```ts
interface SqliteDurableRuntime extends DurableRuntime
```

**Properties**

- `dispose` (`() => void`): Stop the awakeable waits of this runtime (they never settle). Idempotent.
- `findAwakeable?` (``(sessionId: string, key: `${string}:${number}:${string}:${number}`) => Promise<AwakeableRecord | undefined>``, from `DurableRuntime`): 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.
- `isControlError` (`(error: unknown) => boolean`, from `DurableRuntime`): Errors the runtime uses to stop or suspend a run: the loop rethrows them untouched instead of reporting a failed call.
- `lease?` (`DurableLease`, readonly, from `DurableRuntime`): Who runs each session's run. Absent where the platform guarantees one writer.
- `mode` (`DurableMode`, readonly, from `DurableRuntime`): How the runtime recovers a run, see [`DurableMode`](https://zidane.si/docs/reference/durable.md#DurableMode).
- `openRun` (`(options: OpenRunOptions) => Promise<RunScope>`, from `DurableRuntime`): Open a run's scope. Handlers are per scope, never shared with another run.
- `resolveAwakeable` (`(id: string, value: JsonValue) => Promise<boolean>`, from `DurableRuntime`): 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`.
- `stores` (`DurableStores`, readonly, from `DurableRuntime`): Where a run persists its session, tool state, queue and submissions.

Source: [src/durable/sqlite-runtime.ts:113](https://github.com/Tahul/zidane/blob/main/src/durable/sqlite-runtime.ts#L113)

### `SqliteRuntime`

Interface.

A SQLite durable runtime that owns its connection.

```ts
interface SqliteRuntime extends SqliteDurableRuntime
```

**Properties**

- `close` (`() => void`): Stop its waits and close the connection. Idempotent.
- `dispose` (`() => void`, from `SqliteDurableRuntime`): Stop the awakeable waits of this runtime (they never settle). Idempotent.
- `findAwakeable?` (``(sessionId: string, key: `${string}:${number}:${string}:${number}`) => Promise<AwakeableRecord | undefined>``, from `SqliteDurableRuntime`): 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.
- `isControlError` (`(error: unknown) => boolean`, from `SqliteDurableRuntime`): Errors the runtime uses to stop or suspend a run: the loop rethrows them untouched instead of reporting a failed call.
- `lease?` (`DurableLease`, readonly, from `SqliteDurableRuntime`): Who runs each session's run. Absent where the platform guarantees one writer.
- `mode` (`DurableMode`, readonly, from `SqliteDurableRuntime`): How the runtime recovers a run, see [`DurableMode`](https://zidane.si/docs/reference/durable.md#DurableMode).
- `openRun` (`(options: OpenRunOptions) => Promise<RunScope>`, from `SqliteDurableRuntime`): Open a run's scope. Handlers are per scope, never shared with another run.
- `resolveAwakeable` (`(id: string, value: JsonValue) => Promise<boolean>`, from `SqliteDurableRuntime`): 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`.
- `stores` (`DurableStores`, readonly, from `SqliteDurableRuntime`): Where a run persists its session, tool state, queue and submissions.

Source: [src/durable/sqlite.ts:43](https://github.com/Tahul/zidane/blob/main/src/durable/sqlite.ts#L43)

### `SqliteRuntimeOptions`

Interface.

Options of [`createSqliteRuntime`](https://zidane.si/docs/reference/durable-sqlite.md#createSqliteRuntime).

```ts
interface SqliteRuntimeOptions
```

**Properties**

- `path` (`string`): Path of the SQLite sessions file. Created when missing (its directory must exist).

Source: [src/durable/sqlite.ts:37](https://github.com/Tahul/zidane/blob/main/src/durable/sqlite.ts#L37)