or3-provider-sqlite 0.0.7 → 0.0.9

package/README.md

@@ -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,8 @@ 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
 
 Additional migrations (007–008, 010–016) evolve device-cursor ownership,
 upload intents, and Connect credential/lifecycle hardening and rate limits.
@@ -146,7 +150,7 @@ All tables use snake_case aligned with the sync wire format.
 
 ### Sync semantics
 
-- **Push**: validates ops → checks `op_id` idempotency → allocates contiguous `server_version` block → writes change_log → applies LWW to materialized tables → upserts tombstones for deletes
+- **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)`
 - **Cursor**: forward-only per-device cursor tracking

package/dist/module.json

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

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

@@ -0,0 +1,20 @@
+import type { BackgroundJob, BackgroundJobExecution, BackgroundJobProvider, CreateJobParams, JobUpdate } 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>;
+    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>;
+    cleanupExpired(): Promise<number>;
+    getActiveJobCount(): Promise<number>;
+}
+export declare const sqliteBackgroundJobProvider: SqliteBackgroundJobProvider;

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

@@ -0,0 +1,299 @@
+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,
+    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;
+}
+function insertParameters(id, params, now) {
+  return [
+    id,
+    params.userId,
+    params.threadId,
+    params.messageId,
+    params.model,
+    params.kind ?? 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,
+    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,
+    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 = ?) < ?
+  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;
+      }
+      const inserted = await all(
+        INSERT_JOB_IF_CAPACITY,
+        ...insertParameters(id, params, now),
+        config.maxConcurrentJobs,
+        params.userId,
+        config.maxConcurrentJobsPerUser
+      );
+      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;
+      }
+      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 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 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.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 = ?";
+      values.push(update.leaseOwner);
+    }
+    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
+             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 = ?, attempts = attempts + 1
+             WHERE id = ? AND status = 'streaming' AND execution_json IS NOT NULL
+               AND (lease_owner IS NULL OR lease_expires_at <= ?)
+             RETURNING *`,
+      leaseOwner,
+      leaseExpiresAt,
+      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 = ?, attempts = attempts + 1
+             WHERE id = (
+                SELECT id FROM background_jobs
+                WHERE status = 'streaming' AND execution_json IS NOT NULL
+                  AND (lease_owner IS NULL OR lease_expires_at <= ?)
+                ORDER BY started_at ASC LIMIT 1
+             ) RETURNING *`,
+      leaseOwner,
+      leaseExpiresAt,
+      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 = ?`,
+      leaseExpiresAt,
+      Date.now(),
+      jobId,
+      leaseOwner
+    ) > 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 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
+             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 <= ?`,
+      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,7 @@ 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";
 const REQUIRED_SCHEMA_TABLES = [
   "users",
   "auth_accounts",
@@ -39,7 +40,8 @@ const REQUIRED_SCHEMA_TABLES = [
   "upload_intents",
   "connect_device_authorizations",
   "connect_environments",
-  "rate_limits"
+  "rate_limits",
+  "background_jobs"
 ];
 const migrations = {
   "001_init": m001,
@@ -57,7 +59,8 @@ 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
 };
 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>;

package/dist/runtime/server/db/migrations/017_background_jobs.js

@@ -0,0 +1,42 @@
+import { sql } from "kysely";
+export async function up(db) {
+  await sql`
+        CREATE TABLE IF NOT EXISTS background_jobs (
+            id TEXT PRIMARY KEY,
+            user_id TEXT NOT NULL,
+            thread_id TEXT NOT NULL,
+            message_id TEXT NOT NULL,
+            model TEXT NOT NULL,
+            kind TEXT,
+            status TEXT NOT NULL,
+            content TEXT NOT NULL DEFAULT '',
+            chunks_received INTEGER NOT NULL DEFAULT 0,
+            started_at INTEGER NOT NULL,
+            last_activity_at INTEGER NOT NULL,
+            completed_at INTEGER,
+            error TEXT,
+            tool_calls_json TEXT,
+            workflow_state_json TEXT,
+            execution_json TEXT,
+            idempotency_key TEXT UNIQUE,
+            lease_owner TEXT,
+            lease_expires_at INTEGER,
+            attempts INTEGER NOT NULL DEFAULT 0
+        )
+    `.execute(db);
+  await sql`
+        CREATE INDEX IF NOT EXISTS background_jobs_active
+        ON background_jobs(status, last_activity_at)
+    `.execute(db);
+  await sql`
+        CREATE INDEX IF NOT EXISTS background_jobs_user_active
+        ON background_jobs(user_id, status)
+    `.execute(db);
+  await sql`
+        CREATE INDEX IF NOT EXISTS background_jobs_claim
+        ON background_jobs(status, lease_expires_at, started_at)
+    `.execute(db);
+}
+export async function down(db) {
+  await sql`DROP TABLE IF EXISTS background_jobs`.execute(db);
+}

package/dist/runtime/server/db/schema.d.ts

@@ -188,6 +188,28 @@ export interface RateLimitsTable {
     window_started_at: number;
     expires_at: number;
 }
+export interface BackgroundJobsTable {
+    id: string;
+    user_id: string;
+    thread_id: string;
+    message_id: string;
+    model: string;
+    kind: string | null;
+    status: 'streaming' | 'complete' | 'error' | 'aborted';
+    content: string;
+    chunks_received: number;
+    started_at: number;
+    last_activity_at: number;
+    completed_at: number | null;
+    error: string | null;
+    tool_calls_json: string | null;
+    workflow_state_json: string | null;
+    execution_json: string | null;
+    idempotency_key: string | null;
+    lease_owner: string | null;
+    lease_expires_at: number | null;
+    attempts: number;
+}
 export interface AdminUsersTable {
     user_id: string;
     created_at: number;
@@ -216,6 +238,7 @@ export interface Or3SqliteDb {
     connect_device_authorizations: ConnectDeviceAuthorizationsTable;
     connect_environments: ConnectEnvironmentsTable;
     rate_limits: RateLimitsTable;
+    background_jobs: BackgroundJobsTable;
     s_threads: SyncedEntityTable;
     s_messages: SyncedEntityTable;
     s_projects: SyncedEntityTable;

package/dist/runtime/server/plugins/register.js

@@ -6,6 +6,7 @@ import { registerSyncGatewayAdapter } from "~~/server/sync/gateway/registry";
 import { registerWebhookStore } from "~~/server/utils/webhooks/store/registry";
 import { registerConnectStore } from "~~/server/connect/store/registry";
 import { registerRateLimitProvider } from "~~/server/utils/rate-limit/registry";
+import { registerBackgroundJobProvider } from "~~/server/utils/background-jobs/registry";
 import { createSqliteAuthWorkspaceStore } from "../auth/sqlite-auth-workspace-store.js";
 import { createSqliteSyncGatewayAdapter } from "../sync/sqlite-sync-gateway-adapter.js";
 import { createSqliteWebhookStore } from "../webhooks/sqlite-webhook-store.js";
@@ -19,6 +20,7 @@ import { createSqliteConnectStore } from "../connect/sqlite-connect-store.js";
 import { getSqliteDriver, initializeSqliteDb } from "../db/kysely.js";
 import { runMigrations } from "../db/migrate.js";
 import { sqliteRateLimitProvider } from "../rate-limit/sqlite-provider.js";
+import { sqliteBackgroundJobProvider } from "../background-jobs/sqlite-provider.js";
 import { useRuntimeConfig } from "#imports";
 const SQLITE_PROVIDER_ID = "sqlite";
 let d1RuntimeInitialization;
@@ -27,7 +29,8 @@ export default defineNitroPlugin(async (nitroApp) => {
   if (!config.auth?.enabled) return;
   const syncSelected = config.sync?.enabled === true && config.sync?.provider === SQLITE_PROVIDER_ID;
   const connectSelected = config.connect?.enabled === true && config.connect?.provider === SQLITE_PROVIDER_ID;
-  if (!syncSelected && !connectSelected) return;
+  const backgroundJobsSelected = config.backgroundJobs?.enabled === true && config.backgroundJobs?.storageProvider === SQLITE_PROVIDER_ID;
+  if (!syncSelected && !connectSelected && !backgroundJobsSelected) return;
   const driver = getSqliteDriver();
   if (driver === "d1" && connectSelected) {
     throw new Error(
@@ -40,6 +43,10 @@ export default defineNitroPlugin(async (nitroApp) => {
     create: createSqliteAuthWorkspaceStore
   });
   registerRateLimitProvider(SQLITE_PROVIDER_ID, sqliteRateLimitProvider);
+  registerBackgroundJobProvider(
+    SQLITE_PROVIDER_ID,
+    sqliteBackgroundJobProvider
+  );
   if (syncSelected) {
     registerSyncGatewayAdapter({
       id: SQLITE_PROVIDER_ID,

package/dist/runtime/server/sync/sqlite-sync-gateway-adapter.js

@@ -21,6 +21,7 @@ const SNAPSHOT_TTL_SECONDS = 60 * 60;
 const SESSION_CONTEXT_KEY_PREFIX = "__or3_session_context_";
 const MIN_SYNC_RETENTION_SECONDS = 60 * 60;
 const MAX_SYNC_RETENTION_SECONDS = 365 * 24 * 60 * 60;
+const MAX_SYNC_PAYLOAD_BYTES = 256 * 1024;
 function uid() {
   return globalThis.crypto.randomUUID();
 }
@@ -56,11 +57,15 @@ function validatePushOperation(workspaceId, op) {
   }
   const payload = op.payload;
   if (!payload) return void 0;
+  let serializedPayload;
   try {
-    JSON.stringify(payload);
+    serializedPayload = JSON.stringify(payload);
   } catch {
     return `Invalid payload for ${op.tableName}: payload is not serializable`;
   }
+  if (new TextEncoder().encode(serializedPayload).byteLength > MAX_SYNC_PAYLOAD_BYTES) {
+    return `Payload too large for ${op.tableName}: exceeds ${MAX_SYNC_PAYLOAD_BYTES} bytes`;
+  }
   if ("_id" in payload) return `Invalid payload for ${op.tableName}: '_id' is immutable`;
   if ("workspace_id" in payload && payload.workspace_id !== workspaceId) {
     return `Invalid payload for ${op.tableName}: 'workspace_id' is immutable`;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "or3-provider-sqlite",
-    "version": "0.0.7",
+    "version": "0.0.9",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/Saluana/or3-provider-sqlite.git"