or3-provider-sqlite 0.0.8 → 0.0.10

package/README.md

@@ -5,7 +5,7 @@ SQLite sync and workspace store provider for OR3 Chat. Provides a lightweight, s
 ## What it provides
 
 - **AuthWorkspaceStore** (`sqlite`) — user identity mapping, workspace CRUD, role resolution
-- **SyncGatewayAdapter** (`sqlite`) — push/pull sync, consistent materialized snapshot pages, LWW conflict resolution, and cursor tracking
+- **SyncGatewayAdapter** (`sqlite`) — push/pull sync, consistent materialized snapshot pages, LWW conflict resolution, cursor tracking, and canonical background-generation history on synchronous SQLite runtimes
 - **ConnectStore** (`sqlite`) — durable, atomic device enrollment and connected-computer records for OR3 Connect
 - **WebhookStore** (`sqlite`) — durable webhook registrations and delivery logs (local, Bun, and Turso runtimes)
 - **Admin stores** (`sqlite`) — workspace access/lifecycle, workspace settings, user search, and deployment-admin grants (local, Bun, and Turso runtimes)
@@ -125,9 +125,11 @@ On server startup, the Nitro plugin:
 6. Registers `WebhookStore` and the admin stores (workspace access, workspace
    settings, user search) — all runtimes except D1
 7. Registers `RateLimitProvider` with ID `sqlite` and the sync admin adapter
+8. Registers a durable `BackgroundJobProvider` with ID `sqlite`, so active chat
+   and workflow jobs remain addressable across Nitro HMR/module reloads
 
 Registration is skipped when `auth.enabled` is `false`, or when neither SQLite
-sync nor SQLite Connect is selected (local-only mode).
+sync, SQLite Connect, nor SQLite background jobs are selected (local-only mode).
 
 ### Schema
 
@@ -138,6 +140,15 @@ Ordered migrations create and evolve all tables:
 - **003–005**: workspace-scoped sync keys, invitations, and admin stores
 - **006_sync_snapshots**: winning operation IDs plus immutable snapshot headers/items
 - **009_or3_connect**: single-use device authorizations and connected computers
+- **017_background_jobs**: durable job status, workflow snapshots, cancellation,
+  inactivity timestamps, and worker leases
+- **018–020**: durable pre-admission cancellation, reasoning/generation history
+  phases, and idempotent canonical generation-write receipts
+
+Background-job claims reset text and iteration progress back to the durable
+checkpoint when reclaiming an expired lease, matching the memory/Convex recovery
+contract. The provider implements `findJobByIdempotencyKey`, which lets the
+server cancel an admission before the client has received its job ID.
 
 Additional migrations (007–008, 010–016) evolve device-cursor ownership,
 upload intents, and Connect credential/lifecycle hardening and rate limits.
@@ -147,16 +158,24 @@ All tables use snake_case aligned with the sync wire format.
 ### Sync semantics
 
 - **Push**: validates ops (including a 256 KB serialized payload ceiling per operation) → checks `op_id` idempotency → allocates contiguous `server_version` block → writes change_log → applies LWW to materialized tables → upserts tombstones for deletes
-- **Pull**: returns ordered changes for `server_version > cursor` with limit/pagination and optional table filtering
-- **Snapshot**: captures canonical live rows and current tombstones at one `highWatermark`, then serves immutable, keyset-paginated pages ordered by `(tableName, pk, kind)`
+- **Pull**: returns ordered changes for `server_version > cursor` with limit/pagination, optional table filtering, `oldestRetainedVersion`, and `requiresSnapshot` when the cursor is behind retained history
+- **Snapshot**: captures canonical live rows and current tombstones at one `highWatermark`, then serves immutable, keyset-paginated pages ordered by `(tableName, pk, kind)`. Notification live rows are filtered to the session user.
 - **Cursor**: forward-only per-device cursor tracking
 - **Retention safety**: tombstone and `change_log` GC is enabled only under the explicit `snapshot-v1` capability and deletes old revisions acknowledged by every registered device
+- **Notifications**: push forces `payload.user_id` to the session user; foreign notification writes are rejected; pull/snapshot omit other users' rows
 
-LWW conflict resolution: incoming wins when `clock` is higher, or when clocks are equal and `hlc` is lexicographically greater.
+LWW conflict resolution: incoming wins when `clock` is higher, then when clocks are equal and `hlc` is lexicographically greater, then when `op_id` is greater. Tombstones use the same `(clock, hlc, op_id)` tuple. LWW losers return `applied: false` with the winning payload.
 
 Local, Bun, and Turso runtimes use `BEGIN IMMEDIATE` transactions. D1 uses its
 native atomic batch API for grouped writes.
 
+Canonical background generation history is advertised by the local, Bun, and
+Turso adapters. It writes admission rows, contiguous change-log versions,
+materialized state, and the receipt in one transaction, then commits a terminal
+snapshot only if its generation still owns the assistant row. D1 does not
+advertise this versioned capability, so background chat admission fails before
+model execution there; ordinary sync and other D1 features are unchanged.
+
 ### Workspace store
 
 - `getOrCreateUser` — maps `(provider, provider_user_id)` to internal user (idempotent)

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "or3-provider-sqlite",
   "configKey": "or3-provider-sqlite",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/server/background-jobs/sqlite-provider.d.ts

@@ -0,0 +1,27 @@
+import type { BackgroundJob, BackgroundJobExecution, BackgroundJobProvider, CreateJobParams, JobUpdate, AdmissionCancellationResult, GenerationHistoryPhase, TerminalGenerationSnapshot } from '~~/server/utils/background-jobs/types';
+export declare class SqliteBackgroundJobProvider implements BackgroundJobProvider {
+    readonly name = "sqlite";
+    createJob(params: CreateJobParams): Promise<string>;
+    getJob(jobId: string, userId: string): Promise<BackgroundJob | null>;
+    findJobByIdempotencyKey(idempotencyKey: string, userId: string): Promise<BackgroundJob | null>;
+    cancelAdmission(userId: string, admissionId: string): Promise<AdmissionCancellationResult>;
+    updateJob(jobId: string, update: JobUpdate): Promise<void>;
+    completeJob(jobId: string, finalContent: string, leaseOwner?: string): Promise<void>;
+    failJob(jobId: string, error: string, leaseOwner?: string): Promise<void>;
+    private finish;
+    abortJob(jobId: string, userId: string): Promise<boolean>;
+    getAbortController(): undefined;
+    checkJobAborted(jobId: string): Promise<boolean>;
+    claimJob(jobId: string, leaseOwner: string, now: number, leaseExpiresAt: number): Promise<BackgroundJob | null>;
+    claimNextJob(leaseOwner: string, now: number, leaseExpiresAt: number): Promise<BackgroundJob | null>;
+    renewJobLease(jobId: string, leaseOwner: string, _now: number, leaseExpiresAt: number): Promise<boolean>;
+    updateJobExecution(jobId: string, execution: BackgroundJobExecution, leaseOwner: string): Promise<boolean>;
+    saveTerminalSnapshot(jobId: string, snapshot: TerminalGenerationSnapshot, leaseOwner?: string): Promise<boolean>;
+    setHistoryPhase(jobId: string, phase: GenerationHistoryPhase, options?: {
+        from?: GenerationHistoryPhase[];
+    }): Promise<boolean>;
+    getPendingHistoryJobs(limit: number): Promise<BackgroundJob[]>;
+    cleanupExpired(): Promise<number>;
+    getActiveJobCount(): Promise<number>;
+}
+export declare const sqliteBackgroundJobProvider: SqliteBackgroundJobProvider;

package/dist/runtime/server/background-jobs/sqlite-provider.js

@@ -0,0 +1,536 @@
+import { getJobConfig } from "~~/server/utils/background-jobs/store";
+import { randomUUID } from "node:crypto";
+import { d1All, d1Run } from "../db/d1.js";
+import { getRawDb, isD1Driver } from "../db/kysely.js";
+function parseJson(value) {
+  if (!value) return void 0;
+  return JSON.parse(value);
+}
+function json(value) {
+  return value === void 0 ? null : JSON.stringify(value);
+}
+function toJob(row) {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    threadId: row.thread_id,
+    messageId: row.message_id,
+    model: row.model,
+    kind: row.kind ?? void 0,
+    status: row.status,
+    content: row.content,
+    reasoning: row.reasoning ?? "",
+    generationId: row.generation_id ?? void 0,
+    historyPhase: row.history_phase ?? void 0,
+    syncProviderId: row.sync_provider_id ?? void 0,
+    chunksReceived: row.chunks_received,
+    startedAt: row.started_at,
+    lastActivityAt: row.last_activity_at,
+    completedAt: row.completed_at ?? void 0,
+    error: row.error ?? void 0,
+    tool_calls: parseJson(row.tool_calls_json),
+    workflow_state: parseJson(
+      row.workflow_state_json
+    ),
+    execution: parseJson(row.execution_json),
+    leaseOwner: row.lease_owner ?? void 0,
+    leaseExpiresAt: row.lease_expires_at ?? void 0,
+    attempts: row.attempts
+  };
+}
+async function all(statement, ...parameters) {
+  if (isD1Driver()) return d1All(statement, ...parameters);
+  return getRawDb().prepare(statement).all(...parameters);
+}
+async function one(statement, ...parameters) {
+  if (isD1Driver()) return (await d1All(statement, ...parameters))[0];
+  return getRawDb().prepare(statement).get(...parameters);
+}
+async function run(statement, ...parameters) {
+  if (isD1Driver()) {
+    const result = await d1Run(statement, ...parameters);
+    return result.meta?.changes ?? 0;
+  }
+  return getRawDb().prepare(statement).run(...parameters).changes;
+}
+function leaseLost() {
+  const error = new Error("Background job lease was superseded");
+  error.name = "BackgroundJobLeaseLostError";
+  return error;
+}
+const ADMISSION_CANCEL_TTL_MS = 10 * 60 * 1e3;
+function admissionCancelled(admissionId) {
+  const error = new Error(
+    `Background admission ${admissionId} was cancelled`
+  );
+  error.name = "AdmissionCancelledError";
+  return error;
+}
+async function isAdmissionCancelled(userId, admissionId, now) {
+  const row = await one(
+    `SELECT 1 AS hit FROM background_admission_cancels
+         WHERE user_id = ? AND admission_id = ? AND expires_at > ?`,
+    userId,
+    admissionId,
+    now
+  );
+  return row !== void 0;
+}
+function insertParameters(id, params, now) {
+  return [
+    id,
+    params.userId,
+    params.threadId,
+    params.messageId,
+    params.model,
+    params.kind ?? null,
+    params.initialContent ?? "",
+    params.initialReasoning ?? "",
+    params.generationId ?? null,
+    params.historyPhase ?? "ready",
+    params.syncProviderId ?? null,
+    now,
+    now,
+    json(params.tool_calls),
+    json(params.workflow_state),
+    json(params.execution),
+    params.idempotencyKey ?? null
+  ];
+}
+const INSERT_JOB = `INSERT INTO background_jobs (
+    id, user_id, thread_id, message_id, model, kind, status, content,
+    reasoning, generation_id, history_phase, sync_provider_id,
+    chunks_received, started_at, last_activity_at, tool_calls_json,
+    workflow_state_json, execution_json, idempotency_key, attempts
+) VALUES (?, ?, ?, ?, ?, ?, 'streaming', ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, 0)`;
+const INSERT_JOB_IF_CAPACITY = `INSERT INTO background_jobs (
+    id, user_id, thread_id, message_id, model, kind, status, content,
+    reasoning, generation_id, history_phase, sync_provider_id,
+    chunks_received, started_at, last_activity_at, tool_calls_json,
+    workflow_state_json, execution_json, idempotency_key, attempts
+) SELECT ?, ?, ?, ?, ?, ?, 'streaming', ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, 0
+  WHERE (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming') < ?
+    AND (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming' AND user_id = ?) < ?
+    AND NOT EXISTS (
+        SELECT 1 FROM background_admission_cancels
+        WHERE user_id = ? AND admission_id = ? AND expires_at > ?
+    )
+  ON CONFLICT(idempotency_key) DO NOTHING
+  RETURNING id`;
+export class SqliteBackgroundJobProvider {
+  name = "sqlite";
+  async createJob(params) {
+    const now = Date.now();
+    const id = randomUUID();
+    const config = getJobConfig();
+    if (isD1Driver()) {
+      if (params.idempotencyKey) {
+        const existing = await one(
+          "SELECT id FROM background_jobs WHERE idempotency_key = ?",
+          params.idempotencyKey
+        );
+        if (existing) return existing.id;
+        if (await isAdmissionCancelled(
+          params.userId,
+          params.idempotencyKey,
+          now
+        )) {
+          throw admissionCancelled(params.idempotencyKey);
+        }
+      }
+      const inserted = await all(
+        INSERT_JOB_IF_CAPACITY,
+        ...insertParameters(id, params, now),
+        config.maxConcurrentJobs,
+        params.userId,
+        config.maxConcurrentJobsPerUser,
+        params.userId,
+        params.idempotencyKey ?? "",
+        now
+      );
+      if (inserted[0]) return inserted[0].id;
+      if (params.idempotencyKey) {
+        const existing = await one(
+          "SELECT id FROM background_jobs WHERE idempotency_key = ?",
+          params.idempotencyKey
+        );
+        if (existing) return existing.id;
+        if (await isAdmissionCancelled(
+          params.userId,
+          params.idempotencyKey,
+          now
+        )) {
+          throw admissionCancelled(params.idempotencyKey);
+        }
+      }
+      throw new Error("Maximum concurrent background jobs reached");
+    }
+    const raw = getRawDb();
+    return raw.transaction(() => {
+      if (params.idempotencyKey) {
+        const existing = raw.prepare(
+          "SELECT id FROM background_jobs WHERE idempotency_key = ?"
+        ).get(params.idempotencyKey);
+        if (existing) return existing.id;
+        const cancelled = raw.prepare(
+          `SELECT 1 AS hit FROM background_admission_cancels
+                             WHERE user_id = ? AND admission_id = ?
+                               AND expires_at > ?`
+        ).get(
+          params.userId,
+          params.idempotencyKey,
+          now
+        );
+        if (cancelled) {
+          throw admissionCancelled(params.idempotencyKey);
+        }
+      }
+      const active = raw.prepare(
+        `SELECT COUNT(*) AS total,
+                    SUM(CASE WHEN user_id = ? THEN 1 ELSE 0 END) AS user_total
+                 FROM background_jobs WHERE status = 'streaming'`
+      ).get(params.userId);
+      if (active.total >= config.maxConcurrentJobs || (active.user_total ?? 0) >= config.maxConcurrentJobsPerUser) {
+        throw new Error(
+          "Maximum concurrent background jobs reached"
+        );
+      }
+      raw.prepare(INSERT_JOB).run(
+        ...insertParameters(id, params, now)
+      );
+      return id;
+    }).immediate();
+  }
+  async getJob(jobId, userId) {
+    const row = await one(
+      `SELECT * FROM background_jobs WHERE id = ?${userId === "*" ? "" : " AND user_id = ?"}`,
+      ...[jobId, ...userId === "*" ? [] : [userId]]
+    );
+    return row ? toJob(row) : null;
+  }
+  async findJobByIdempotencyKey(idempotencyKey, userId) {
+    const row = await one(
+      "SELECT * FROM background_jobs WHERE idempotency_key = ? AND user_id = ?",
+      idempotencyKey,
+      userId
+    );
+    return row ? toJob(row) : null;
+  }
+  async cancelAdmission(userId, admissionId) {
+    const now = Date.now();
+    const expiresAt = now + ADMISSION_CANCEL_TTL_MS;
+    const upsertMarker = `INSERT INTO background_admission_cancels
+                (user_id, admission_id, expires_at)
+             VALUES (?, ?, ?)
+             ON CONFLICT(user_id, admission_id)
+             DO UPDATE SET expires_at = excluded.expires_at`;
+    const abortJob = `UPDATE background_jobs SET status = 'aborted',
+                completed_at = ?, last_activity_at = ?, error = ?,
+                lease_owner = NULL, lease_expires_at = NULL,
+                history_phase = CASE
+                    WHEN generation_id IS NOT NULL
+                      AND COALESCE(history_phase, 'ready') = 'ready'
+                    THEN 'finalization_pending'
+                    ELSE history_phase END
+             WHERE id = ? AND status = 'streaming'`;
+    if (!isD1Driver()) {
+      const raw = getRawDb();
+      return raw.transaction(() => {
+        raw.prepare(
+          "DELETE FROM background_admission_cancels WHERE expires_at <= ?"
+        ).run(now);
+        raw.prepare(upsertMarker).run(userId, admissionId, expiresAt);
+        const job2 = raw.prepare(
+          "SELECT id, status FROM background_jobs WHERE user_id = ? AND idempotency_key = ?"
+        ).get(userId, admissionId);
+        if (!job2) {
+          return { aborted: false, pending: true };
+        }
+        if (job2.status === "streaming") {
+          const changes = raw.prepare(abortJob).run(
+            now,
+            now,
+            "Cancelled by user",
+            job2.id
+          ).changes;
+          return {
+            aborted: changes > 0,
+            jobId: job2.id,
+            pending: false
+          };
+        }
+        return { aborted: false, jobId: job2.id, pending: false };
+      }).immediate();
+    }
+    await run(
+      "DELETE FROM background_admission_cancels WHERE expires_at <= ?",
+      now
+    );
+    await run(upsertMarker, userId, admissionId, expiresAt);
+    const job = await one(
+      "SELECT id, status FROM background_jobs WHERE user_id = ? AND idempotency_key = ?",
+      userId,
+      admissionId
+    );
+    if (!job) {
+      return { aborted: false, pending: true };
+    }
+    if (job.status === "streaming") {
+      const changes = await run(
+        abortJob,
+        now,
+        now,
+        "Cancelled by user",
+        job.id
+      );
+      return {
+        aborted: changes > 0,
+        jobId: job.id,
+        pending: false
+      };
+    }
+    return { aborted: false, jobId: job.id, pending: false };
+  }
+  async updateJob(jobId, update) {
+    const sets = ["last_activity_at = ?"];
+    const values = [Date.now()];
+    if (update.contentChunk !== void 0) {
+      sets.push("content = content || ?");
+      values.push(update.contentChunk);
+    }
+    if (update.reasoningChunk !== void 0) {
+      sets.push("reasoning = reasoning || ?");
+      values.push(update.reasoningChunk);
+    }
+    if (update.chunksReceived !== void 0) {
+      sets.push("chunks_received = ?");
+      values.push(update.chunksReceived);
+    }
+    if (update.tool_calls !== void 0) {
+      sets.push("tool_calls_json = ?");
+      values.push(json(update.tool_calls));
+    }
+    if (update.workflow_state !== void 0) {
+      sets.push("workflow_state_json = ?");
+      values.push(json(update.workflow_state));
+    }
+    values.push(jobId);
+    let where = "id = ? AND status = 'streaming'";
+    if (update.leaseOwner) {
+      where += " AND lease_owner = ? AND lease_expires_at > ?";
+      values.push(update.leaseOwner);
+      values.push(Date.now());
+    }
+    const changes = await run(
+      `UPDATE background_jobs SET ${sets.join(", ")} WHERE ${where}`,
+      ...values
+    );
+    if (update.leaseOwner && changes === 0) throw leaseLost();
+  }
+  async completeJob(jobId, finalContent, leaseOwner) {
+    await this.finish(jobId, "complete", finalContent, null, leaseOwner);
+  }
+  async failJob(jobId, error, leaseOwner) {
+    await this.finish(jobId, "error", null, error, leaseOwner);
+  }
+  async finish(jobId, status, content, error, leaseOwner) {
+    const now = Date.now();
+    const values = [status, now, now, error];
+    const contentSet = content === null ? "" : ", content = ?";
+    if (content !== null) values.push(content);
+    values.push(jobId);
+    let where = "id = ? AND status = 'streaming'";
+    if (leaseOwner) {
+      where += " AND lease_owner = ?";
+      values.push(leaseOwner);
+    }
+    const changes = await run(
+      `UPDATE background_jobs SET status = ?, completed_at = ?, last_activity_at = ?,
+                error = ?, lease_owner = NULL, lease_expires_at = NULL${contentSet}
+             WHERE ${where}`,
+      ...values
+    );
+    if (leaseOwner && changes === 0) throw leaseLost();
+  }
+  async abortJob(jobId, userId) {
+    const now = Date.now();
+    return await run(
+      `UPDATE background_jobs SET status = 'aborted', completed_at = ?,
+                last_activity_at = ?, lease_owner = NULL, lease_expires_at = NULL,
+                history_phase = CASE
+                    WHEN generation_id IS NOT NULL
+                      AND COALESCE(history_phase, 'ready') = 'ready'
+                    THEN 'finalization_pending'
+                    ELSE history_phase END
+             WHERE id = ? AND user_id = ? AND status = 'streaming'`,
+      now,
+      now,
+      jobId,
+      userId
+    ) > 0;
+  }
+  getAbortController() {
+    return void 0;
+  }
+  async checkJobAborted(jobId) {
+    const row = await one(
+      "SELECT status FROM background_jobs WHERE id = ?",
+      jobId
+    );
+    return row?.status === "aborted";
+  }
+  async claimJob(jobId, leaseOwner, now, leaseExpiresAt) {
+    const row = await one(
+      `UPDATE background_jobs SET
+                lease_owner = ?,
+                lease_expires_at = ?,
+                last_activity_at = ?,
+                content = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.contentBase'), '')
+                    ELSE content END,
+                reasoning = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.reasoningBase'), '')
+                    ELSE reasoning END,
+                chunks_received = CASE WHEN attempts > 0 THEN 0 ELSE chunks_received END,
+                attempts = attempts + 1
+             WHERE id = ? AND status = 'streaming' AND execution_json IS NOT NULL
+               AND COALESCE(history_phase, 'ready') = 'ready'
+               AND (lease_owner IS NULL OR lease_expires_at <= ?)
+             RETURNING *`,
+      leaseOwner,
+      leaseExpiresAt,
+      now,
+      jobId,
+      now
+    );
+    return row ? toJob(row) : null;
+  }
+  async claimNextJob(leaseOwner, now, leaseExpiresAt) {
+    const row = await one(
+      `UPDATE background_jobs SET
+                lease_owner = ?,
+                lease_expires_at = ?,
+                last_activity_at = ?,
+                content = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.contentBase'), '')
+                    ELSE content END,
+                reasoning = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.reasoningBase'), '')
+                    ELSE reasoning END,
+                chunks_received = CASE WHEN attempts > 0 THEN 0 ELSE chunks_received END,
+                attempts = attempts + 1
+             WHERE id = (
+                SELECT id FROM background_jobs
+                WHERE status = 'streaming' AND execution_json IS NOT NULL
+                  AND COALESCE(history_phase, 'ready') = 'ready'
+                  AND (lease_owner IS NULL OR lease_expires_at <= ?)
+                ORDER BY started_at ASC LIMIT 1
+             ) RETURNING *`,
+      leaseOwner,
+      leaseExpiresAt,
+      now,
+      now
+    );
+    return row ? toJob(row) : null;
+  }
+  async renewJobLease(jobId, leaseOwner, _now, leaseExpiresAt) {
+    return await run(
+      `UPDATE background_jobs SET lease_expires_at = ?, last_activity_at = ?
+             WHERE id = ? AND status = 'streaming' AND lease_owner = ?
+               AND lease_expires_at > ?`,
+      leaseExpiresAt,
+      Date.now(),
+      jobId,
+      leaseOwner,
+      Date.now()
+    ) > 0;
+  }
+  async updateJobExecution(jobId, execution, leaseOwner) {
+    return await run(
+      `UPDATE background_jobs SET execution_json = ?, last_activity_at = ?
+             WHERE id = ? AND status = 'streaming' AND lease_owner = ?`,
+      json(execution),
+      Date.now(),
+      jobId,
+      leaseOwner
+    ) > 0;
+  }
+  async saveTerminalSnapshot(jobId, snapshot, leaseOwner) {
+    const values = [
+      snapshot.status,
+      snapshot.content,
+      snapshot.reasoning,
+      json(snapshot.toolCalls),
+      snapshot.error ?? null,
+      snapshot.completedAt,
+      snapshot.completedAt
+    ];
+    let where = "id = ? AND status = 'streaming'";
+    values.push(jobId);
+    if (leaseOwner) {
+      where += " AND lease_owner = ? AND lease_expires_at > ?";
+      values.push(leaseOwner, Date.now());
+    }
+    return await run(
+      `UPDATE background_jobs SET status = ?, content = ?, reasoning = ?,
+                    tool_calls_json = ?, error = ?, completed_at = ?,
+                    history_phase = 'finalization_pending',
+                    last_activity_at = ?, lease_owner = NULL, lease_expires_at = NULL
+                 WHERE ${where}`,
+      ...values
+    ) > 0;
+  }
+  async setHistoryPhase(jobId, phase, options) {
+    const values = [phase, jobId];
+    let where = "id = ?";
+    if (options?.from && options.from.length > 0) {
+      const placeholders = options.from.map(() => "?").join(", ");
+      where += ` AND COALESCE(history_phase, 'ready') IN (${placeholders})`;
+      values.push(...options.from);
+    }
+    return await run(`UPDATE background_jobs SET history_phase = ? WHERE ${where}`, ...values) > 0;
+  }
+  async getPendingHistoryJobs(limit) {
+    const rows = await all(
+      `SELECT * FROM background_jobs
+             WHERE history_phase IN ('admission_pending', 'finalization_pending')
+             ORDER BY started_at ASC
+             LIMIT ?`,
+      Math.max(1, Math.min(100, Math.floor(limit)))
+    );
+    return rows.map(toJob);
+  }
+  async cleanupExpired() {
+    const config = getJobConfig();
+    const now = Date.now();
+    const timedOut = await run(
+      `UPDATE background_jobs SET status = 'error', error = 'Job timed out',
+                completed_at = ?, lease_owner = NULL, lease_expires_at = NULL,
+                history_phase = CASE
+                    WHEN generation_id IS NOT NULL
+                      AND COALESCE(history_phase, 'ready') = 'ready'
+                    THEN 'finalization_pending'
+                    ELSE history_phase END
+             WHERE status = 'streaming' AND last_activity_at <= ?`,
+      now,
+      now - config.jobTimeoutMs
+    );
+    const removed = await run(
+      `DELETE FROM background_jobs
+             WHERE status != 'streaming' AND completed_at IS NOT NULL AND completed_at <= ?
+               AND (
+                 history_phase IS NULL
+                 OR history_phase IN ('ready', 'committed', 'superseded')
+               )`,
+      now - config.completedJobRetentionMs
+    );
+    return timedOut + removed;
+  }
+  async getActiveJobCount() {
+    const row = await one(
+      "SELECT COUNT(*) AS total FROM background_jobs WHERE status = 'streaming'"
+    );
+    return row?.total ?? 0;
+  }
+}
+export const sqliteBackgroundJobProvider = new SqliteBackgroundJobProvider();

package/dist/runtime/server/db/migrate.js

@@ -15,6 +15,10 @@ import * as m013 from "./migrations/013_connect_environment_lifecycle.js";
 import * as m014 from "./migrations/014_connect_retention_activation.js";
 import * as m015 from "./migrations/015_rate_limits.js";
 import * as m016 from "./migrations/016_connect_runtime_binding.js";
+import * as m017 from "./migrations/017_background_jobs.js";
+import * as m018 from "./migrations/018_background_admission_cancels.js";
+import * as m019 from "./migrations/019_background_generation_history.js";
+import * as m020 from "./migrations/020_background_generation_receipts.js";
 const REQUIRED_SCHEMA_TABLES = [
   "users",
   "auth_accounts",
@@ -39,7 +43,10 @@ const REQUIRED_SCHEMA_TABLES = [
   "upload_intents",
   "connect_device_authorizations",
   "connect_environments",
-  "rate_limits"
+  "rate_limits",
+  "background_jobs",
+  "background_admission_cancels",
+  "background_generation_receipts"
 ];
 const migrations = {
   "001_init": m001,
@@ -57,7 +64,11 @@ const migrations = {
   "013_connect_environment_lifecycle": m013,
   "014_connect_retention_activation": m014,
   "015_rate_limits": m015,
-  "016_connect_runtime_binding": m016
+  "016_connect_runtime_binding": m016,
+  "017_background_jobs": m017,
+  "018_background_admission_cancels": m018,
+  "019_background_generation_history": m019,
+  "020_background_generation_receipts": m020
 };
 class StaticMigrationProvider {
   async getMigrations() {

package/dist/runtime/server/db/migrations/017_background_jobs.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+/** Durable background chat and workflow execution state. */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;