or3-provider-sqlite 0.0.9 → 0.0.11

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)
@@ -32,7 +32,7 @@ runtime.
 | Runtime | `OR3_SQLITE_DRIVER` | Required configuration | Extra install |
 |---|---|---|---|
 | Local Node (default) | `better-sqlite3` | `OR3_SQLITE_DB_PATH` | `better-sqlite3` |
-| Bun | `bun` | `OR3_SQLITE_DB_PATH` | None; uses built-in `bun:sqlite` |
+| Bun | `bun` | `OR3_SQLITE_DB_PATH` | None for sync; uses built-in `bun:sqlite` |
 | Turso/libSQL | `turso` | `OR3_SQLITE_TURSO_URL`, `OR3_SQLITE_TURSO_AUTH_TOKEN` | `libsql` |
 | Cloudflare D1 | `d1` | `OR3_SQLITE_D1_BINDING` (defaults to `DB`) | None; uses the Worker binding |
 
@@ -51,6 +51,16 @@ OR3_SQLITE_DRIVER=bun
 OR3_SQLITE_DB_PATH=/data/or3-sync.db
 ```
 
+OR3 Chat's source launcher (`bun run dev:ssr`) selects Bun when this provider
+uses the Bun driver, including when only the auth workspace store is active.
+Use the Bun version pinned in the host's `package.json`. The launcher checks
+the built-in driver and required native bindings before Nuxt starts. Run a
+built Bun-configured server with `bun .output/server/index.mjs`.
+
+Basic Auth still uses a separate `better-sqlite3` database; its native binding
+must also be compatible with Bun. The managed Cloud image uses Node and the
+default `better-sqlite3` sync driver.
+
 ### Turso/libSQL
 
 ```bash
@@ -131,6 +141,12 @@ On server startup, the Nitro plugin:
 Registration is skipped when `auth.enabled` is `false`, or when neither SQLite
 sync, SQLite Connect, nor SQLite background jobs are selected (local-only mode).
 
+SQLite background jobs also persist mixed-runtime tool handoffs. Browser-only
+calls are atomically claimed and settled in `execution_json`; parked calls are
+excluded from worker claims until their browser result makes the job runnable.
+Parked handoffs have a separate global and per-user admission cap, so they do
+not consume active worker slots or grow without bound.
+
 ### Schema
 
 Ordered migrations create and evolve all tables:
@@ -142,6 +158,13 @@ Ordered migrations create and evolve all tables:
 - **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.
@@ -151,16 +174,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 current winner as either `{ kind: 'put', payload, revision }` or `{ kind: 'delete', revision, serverDeletedAt? }`. Idempotent `op_id` retries return `replayed: true` and, if superseded, the current winner. A replay does not allocate another server version.
 
 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)
@@ -220,3 +251,17 @@ bun run build       # build for distribution
   `OR3_CONNECT_ENABLED=false` or switch to better-sqlite3, Bun, or Turso.
 - **`OR3_SQLITE_DRIVER=bun requires Bun`** — the Bun driver only runs under
   the Bun runtime with its built-in `bun:sqlite`.
+
+### Atomic workspace settings
+
+The workspace settings store implements `compareAndSet(workspaceId, key, expectedValue, nextValue)` atomically. A `null` expected value means the key must be absent; a conflict returns `false` without overwriting it. The host uses this for concurrent plugin setup saves and persistent AI spend reservations.
+
+
+### Testing local changes in OR3 Chat
+
+With this repository beside `or3-chat`, run `bun install` here once, then
+`bun run dev:ssr` from Chat. Chat's dev wrapper rebuilds the local provider and
+prints its selected path; restart it after provider edits. Missing repositories
+or failed builds fall back to installed packages with a warning.
+`OR3_LOCAL_PROVIDERS=false` disables local selection. Production builds use the
+installed package, so local development does not publish these changes.

package/dist/module.json

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

package/dist/runtime/server/admin/stores/sqlite-store.js

@@ -323,6 +323,22 @@ class SqliteWorkspaceSettingsStore {
       })
     ).execute();
   }
+  /** Atomically write only when the stored value still equals the expected value. */
+  async compareAndSet(workspaceId, key, expectedValue, nextValue) {
+    const now = nowEpoch();
+    if (expectedValue === null) {
+      const result2 = await this.db.insertInto("admin_workspace_settings").values({
+        id: globalThis.crypto.randomUUID(),
+        workspace_id: workspaceId,
+        key,
+        value: nextValue,
+        updated_at: now
+      }).onConflict((oc) => oc.columns(["workspace_id", "key"]).doNothing()).executeTakeFirst();
+      return Number(result2.numInsertedOrUpdatedRows ?? 0) === 1;
+    }
+    const result = await this.db.updateTable("admin_workspace_settings").set({ value: nextValue, updated_at: now }).where("workspace_id", "=", workspaceId).where("key", "=", key).where("value", "=", expectedValue).executeTakeFirst();
+    return Number(result.numUpdatedRows ?? 0) === 1;
+  }
 }
 class SqliteAdminUserStore {
   get db() {

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

@@ -1,8 +1,10 @@
-import type { BackgroundJob, BackgroundJobExecution, BackgroundJobProvider, CreateJobParams, JobUpdate } from '~~/server/utils/background-jobs/types';
+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>;
@@ -14,6 +16,13 @@ export declare class SqliteBackgroundJobProvider implements BackgroundJobProvide
     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>;
+    claimClientToolCall(jobId: string, userId: string, callId: string, claimToken: string, claimExpiresAt: number): Promise<BackgroundJob | null>;
+    settleClientToolCall(jobId: string, userId: string, callId: string, claimToken: string, execution: BackgroundJobExecution, toolCalls: BackgroundJob['tool_calls']): 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>;
 }

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

@@ -19,6 +19,10 @@ function toJob(row) {
     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,
@@ -54,6 +58,24 @@ function leaseLost() {
   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,
@@ -62,6 +84,11 @@ function insertParameters(id, params, now) {
     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),
@@ -72,16 +99,28 @@ function insertParameters(id, params, now) {
 }
 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)`;
+) 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 = ?) < ?
+) SELECT ?, ?, ?, ?, ?, ?, 'streaming', ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, 0
+  WHERE (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming'
+           AND json_extract(execution_json, '$.clientToolCall') IS NULL) < ?
+    AND (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming' AND user_id = ?
+           AND json_extract(execution_json, '$.clientToolCall') IS NULL) < ?
+    AND (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming'
+           AND json_extract(execution_json, '$.clientToolCall') IS NOT NULL) < ?
+    AND (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming' AND user_id = ?
+           AND json_extract(execution_json, '$.clientToolCall') IS NOT NULL) < ?
+    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 {
@@ -97,13 +136,26 @@ export class SqliteBackgroundJobProvider {
           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
+        config.maxConcurrentJobsPerUser,
+        config.maxConcurrentJobs,
+        params.userId,
+        config.maxConcurrentJobsPerUser,
+        params.userId,
+        params.idempotencyKey ?? "",
+        now
       );
       if (inserted[0]) return inserted[0].id;
       if (params.idempotencyKey) {
@@ -112,6 +164,13 @@ export class SqliteBackgroundJobProvider {
           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");
     }
@@ -122,13 +181,28 @@ export class SqliteBackgroundJobProvider {
           "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
+        `SELECT
+                    SUM(CASE WHEN json_extract(execution_json, '$.clientToolCall') IS NULL THEN 1 ELSE 0 END) AS total,
+                    SUM(CASE WHEN user_id = ? AND json_extract(execution_json, '$.clientToolCall') IS NULL THEN 1 ELSE 0 END) AS user_total,
+                    SUM(CASE WHEN json_extract(execution_json, '$.clientToolCall') IS NOT NULL THEN 1 ELSE 0 END) AS waiting_total,
+                    SUM(CASE WHEN user_id = ? AND json_extract(execution_json, '$.clientToolCall') IS NOT NULL THEN 1 ELSE 0 END) AS waiting_user_total
                  FROM background_jobs WHERE status = 'streaming'`
-      ).get(params.userId);
-      if (active.total >= config.maxConcurrentJobs || (active.user_total ?? 0) >= config.maxConcurrentJobsPerUser) {
+      ).get(params.userId, params.userId);
+      if ((active.total ?? 0) >= config.maxConcurrentJobs || (active.user_total ?? 0) >= config.maxConcurrentJobsPerUser || (active.waiting_total ?? 0) >= config.maxConcurrentJobs || (active.waiting_user_total ?? 0) >= config.maxConcurrentJobsPerUser) {
         throw new Error(
           "Maximum concurrent background jobs reached"
         );
@@ -146,6 +220,89 @@ export class SqliteBackgroundJobProvider {
     );
     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()];
@@ -153,6 +310,10 @@ export class SqliteBackgroundJobProvider {
       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);
@@ -168,8 +329,9 @@ export class SqliteBackgroundJobProvider {
     values.push(jobId);
     let where = "id = ? AND status = 'streaming'";
     if (update.leaseOwner) {
-      where += " AND lease_owner = ?";
+      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}`,
@@ -206,7 +368,12 @@ export class SqliteBackgroundJobProvider {
     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
+                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,
@@ -226,12 +393,26 @@ export class SqliteBackgroundJobProvider {
   }
   async claimJob(jobId, leaseOwner, now, leaseExpiresAt) {
     const row = await one(
-      `UPDATE background_jobs SET lease_owner = ?, lease_expires_at = ?, attempts = attempts + 1
+      `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 json_extract(execution_json, '$.clientToolCall') IS NULL
+               AND COALESCE(history_phase, 'ready') = 'ready'
                AND (lease_owner IS NULL OR lease_expires_at <= ?)
              RETURNING *`,
       leaseOwner,
       leaseExpiresAt,
+      now,
       jobId,
       now
     );
@@ -239,15 +420,29 @@ export class SqliteBackgroundJobProvider {
   }
   async claimNextJob(leaseOwner, now, leaseExpiresAt) {
     const row = await one(
-      `UPDATE background_jobs SET lease_owner = ?, lease_expires_at = ?, attempts = attempts + 1
+      `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 json_extract(execution_json, '$.clientToolCall') IS 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;
@@ -255,11 +450,13 @@ export class SqliteBackgroundJobProvider {
   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 = ?`,
+             WHERE id = ? AND status = 'streaming' AND lease_owner = ?
+               AND lease_expires_at > ?`,
       leaseExpiresAt,
       Date.now(),
       jobId,
-      leaseOwner
+      leaseOwner,
+      Date.now()
     ) > 0;
   }
   async updateJobExecution(jobId, execution, leaseOwner) {
@@ -272,26 +469,127 @@ export class SqliteBackgroundJobProvider {
       leaseOwner
     ) > 0;
   }
+  async claimClientToolCall(jobId, userId, callId, claimToken, claimExpiresAt) {
+    const now = Date.now();
+    const row = await one(
+      `UPDATE background_jobs SET
+                execution_json = json_set(
+                    execution_json,
+                    '$.clientToolCall.claimToken', ?,
+                    '$.clientToolCall.claimExpiresAt', ?
+                ),
+                last_activity_at = ?
+             WHERE id = ? AND user_id = ? AND status = 'streaming'
+               AND json_extract(execution_json, '$.clientToolCall.callId') = ?
+               AND (
+                    json_extract(execution_json, '$.clientToolCall.claimToken') IS NULL
+                    OR COALESCE(json_extract(execution_json, '$.clientToolCall.claimExpiresAt'), 0) <= ?
+               )
+             RETURNING *`,
+      claimToken,
+      claimExpiresAt,
+      now,
+      jobId,
+      userId,
+      callId,
+      now
+    );
+    return row ? toJob(row) : null;
+  }
+  async settleClientToolCall(jobId, userId, callId, claimToken, execution, toolCalls) {
+    const now = Date.now();
+    return await run(
+      `UPDATE background_jobs SET execution_json = ?, tool_calls_json = ?,
+                    lease_owner = NULL, lease_expires_at = NULL, last_activity_at = ?
+                 WHERE id = ? AND user_id = ? AND status = 'streaming'
+                   AND json_extract(execution_json, '$.clientToolCall.callId') = ?
+                   AND json_extract(execution_json, '$.clientToolCall.claimToken') = ?
+                   AND COALESCE(json_extract(execution_json, '$.clientToolCall.claimExpiresAt'), 0) > ?`,
+      json(execution),
+      json(toolCalls),
+      now,
+      jobId,
+      userId,
+      callId,
+      claimToken,
+      now
+    ) > 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
+                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 <= ?`,
+             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'"
+      `SELECT COUNT(*) AS total FROM background_jobs WHERE status = 'streaming'
+             AND json_extract(execution_json, '$.clientToolCall') IS NULL`
     );
     return row?.total ?? 0;
   }