@sqlite-sync/ai 0.4.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqlite-sync contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @sqlite-sync/ai
+
+AI agent tools for [@sqlite-sync](https://github.com/krolebord-dev/sqlite-sync) databases. Gives an AI SDK agent safe, read-only access to a synced SQLite database.
+
+## What's included
+
+- `createSchemaDoc` — generates a markdown schema doc by introspecting the synced database (structure from `PRAGMA table_info`, semantics from app-provided context).
+- `createAiDbAccess` — server-side access object living next to the storage; its methods double as an RPC contract for cross-Durable-Object setups.
+- `createDbTools` — AI SDK v6 `ToolSet` (currently a `getDbSchema` tool) backed by an `AiDbAccess` or a stub proxying to one.
+
+## Usage (Cloudflare Durable Object)
+
+```ts
+import { createAiDbAccess } from "@sqlite-sync/ai";
+import { createKyselyExecutor, durableObjectAdapter } from "@sqlite-sync/cloudflare";
+
+// In the DO that owns the synced database:
+async onStart() {
+  await durableObjectAdapter.createCrdtStorage({ syncDbSchema, storage: this.ctx.storage, /* ... */ });
+  this.aiDbAccess = createAiDbAccess({
+    executor: createKyselyExecutor(this.ctx.storage),
+    syncDbSchema,
+    context: {
+      overview: "# My app's database\n\nDeletes are soft-deletes; the views below already hide them.",
+      tables: {
+        todos: {
+          description: "The user's todos.",
+          columns: { completed: "1 when done." },
+        },
+      },
+    },
+  });
+}
+
+// RPC method for agents running elsewhere:
+getDbSchemaDoc() {
+  return this.aiDbAccess.getSchemaDoc();
+}
+```
+
+```ts
+import { createDbTools } from "@sqlite-sync/ai";
+
+// In the agent:
+getTools() {
+  return createDbTools({
+    access: async () => {
+      const stub = await this.getUserDbStub();
+      return { getSchemaDoc: () => stub.getDbSchemaDoc() };
+    },
+  });
+}
+```
+
+`context.tables` keys are CRDT view names (`crdtTableName`). The doc skips the internal `tombstone` column and introspects base tables (views lose `NOT NULL` fidelity), presenting them under their view names.

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { SyncDbSchema } from '@sqlite-sync/core';
+import { ToolSet } from 'ai';
+
+/**
+ * App-provided semantics merged into the generated schema doc.
+ * Keys of `tables` are CRDT view names (`crdtTableName`), not base table names.
+ */
+type SchemaDocContext = {
+    overview?: string;
+    tables?: Record<string, {
+        description?: string;
+        columns?: Record<string, string>;
+    }>;
+};
+/**
+ * Generates a markdown schema doc for an AI agent by introspecting the synced database.
+ * Structure comes from `PRAGMA table_info` on the base tables (introspecting the views would
+ * lose NOT NULL fidelity), presented under the view names the agent queries; semantics come
+ * from the consumer-provided context. The internal `tombstone` column is omitted.
+ */
+declare function createSchemaDoc(opts: {
+    execute: (sql: string) => Record<string, unknown>[];
+    syncDbSchema: SyncDbSchema;
+    context?: SchemaDocContext;
+}): string;
+
+type AiDbExecuteParams = {
+    sql: string;
+    parameters: readonly unknown[];
+};
+/**
+ * Minimal executor contract for AI database access. Runtime-specific — inject the one that
+ * matches where the storage lives; @sqlite-sync/cloudflare's `createKyselyExecutor` satisfies it.
+ *
+ * `transaction` MUST roll back everything the callback executed when the callback throws —
+ * it backs the read-only enforcement of the query tooling.
+ */
+type AiDbExecutor = {
+    execute<TResult = unknown>(query: AiDbExecuteParams): {
+        rows: TResult[];
+    };
+    transaction(callback: (tx: Pick<AiDbExecutor, "execute">) => void): void;
+};
+/**
+ * Read-only AI access to a synced database. Lives where the storage lives; its method names
+ * are the RPC contract, so a DO stub proxying to these methods exposes the same surface
+ * (promise-wrapped) and satisfies the tool layer's `DbToolsAccess`.
+ */
+type AiDbAccess = {
+    getSchemaDoc(): string;
+};
+/**
+ * Create where the CRDT storage was created (e.g. a Durable Object's `onStart`, after
+ * migrations have run) — the schema doc is introspected once and cached.
+ */
+declare function createAiDbAccess(opts: {
+    executor: AiDbExecutor;
+    syncDbSchema: SyncDbSchema;
+    context?: SchemaDocContext;
+}): AiDbAccess;
+
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * What the tools need from the database side. Satisfied directly by `AiDbAccess`, or by a
+ * Durable Object stub whose RPC methods delegate to one (RPC wraps returns in promises).
+ */
+type DbToolsAccess = {
+    getSchemaDoc(): MaybePromise<string>;
+};
+/**
+ * AI SDK tools for a synced database. `access` is a factory because acquiring the database
+ * may itself be async per call (e.g. resolving a Durable Object stub from another DO).
+ */
+declare function createDbTools(opts: {
+    access: () => MaybePromise<DbToolsAccess>;
+}): ToolSet;
+
+export { type AiDbAccess, type AiDbExecuteParams, type AiDbExecutor, type DbToolsAccess, type SchemaDocContext, createAiDbAccess, createDbTools, createSchemaDoc };

package/dist/index.js

@@ -0,0 +1,70 @@
+// src/schema-doc.ts
+function quoteId(name) {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+function createSchemaDoc(opts) {
+  const sections = [];
+  const overview = opts.context?.overview?.trim();
+  if (overview) {
+    sections.push(overview);
+  }
+  for (const table of opts.syncDbSchema.tablesConfig) {
+    const tableContext = opts.context?.tables?.[table.crdtTableName];
+    const columns = opts.execute(`PRAGMA table_info(${quoteId(table.baseTableName)})`);
+    const lines = [`## ${table.crdtTableName}`];
+    if (tableContext?.description) {
+      lines.push("", tableContext.description.trim());
+    }
+    lines.push("", "Columns:");
+    for (const column of columns) {
+      if (column.name === "tombstone") continue;
+      const description = tableContext?.columns?.[column.name];
+      lines.push(
+        `- \`${column.name}\` ${column.type}${column.notnull ? " NOT NULL" : ""}${description ? ` \u2014 ${description}` : ""}`
+      );
+    }
+    sections.push(lines.join("\n"));
+  }
+  return sections.join("\n\n");
+}
+
+// src/db-access.ts
+function createAiDbAccess(opts) {
+  let schemaDoc;
+  return {
+    getSchemaDoc() {
+      schemaDoc ??= createSchemaDoc({
+        execute: (sql) => opts.executor.execute({ sql, parameters: [] }).rows,
+        syncDbSchema: opts.syncDbSchema,
+        context: opts.context
+      });
+      return schemaDoc;
+    }
+  };
+}
+
+// src/tools.ts
+import { jsonSchema, tool } from "ai";
+var emptyInputSchema = jsonSchema({
+  type: "object",
+  properties: {},
+  additionalProperties: false
+});
+function createDbTools(opts) {
+  return {
+    getDbSchema: tool({
+      description: "Get the schema documentation for the synced SQLite database: tables, columns, types, and data conventions. Call this before reasoning about the data.",
+      inputSchema: emptyInputSchema,
+      execute: async () => {
+        const access = await opts.access();
+        return await access.getSchemaDoc();
+      }
+    })
+  };
+}
+export {
+  createAiDbAccess,
+  createDbTools,
+  createSchemaDoc
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema-doc.ts","../src/db-access.ts","../src/tools.ts"],"sourcesContent":["import type { SyncDbSchema } from \"@sqlite-sync/core\";\n\n/**\n * App-provided semantics merged into the generated schema doc.\n * Keys of `tables` are CRDT view names (`crdtTableName`), not base table names.\n */\nexport type SchemaDocContext = {\n  overview?: string;\n  tables?: Record<string, { description?: string; columns?: Record<string, string> }>;\n};\n\ntype TableInfoRow = {\n  cid: number;\n  name: string;\n  type: string;\n  notnull: number;\n};\n\nfunction quoteId(name: string) {\n  return `\"${name.replaceAll('\"', '\"\"')}\"`;\n}\n\n/**\n * Generates a markdown schema doc for an AI agent by introspecting the synced database.\n * Structure comes from `PRAGMA table_info` on the base tables (introspecting the views would\n * lose NOT NULL fidelity), presented under the view names the agent queries; semantics come\n * from the consumer-provided context. The internal `tombstone` column is omitted.\n */\nexport function createSchemaDoc(opts: {\n  execute: (sql: string) => Record<string, unknown>[];\n  syncDbSchema: SyncDbSchema;\n  context?: SchemaDocContext;\n}): string {\n  const sections: string[] = [];\n\n  const overview = opts.context?.overview?.trim();\n  if (overview) {\n    sections.push(overview);\n  }\n\n  for (const table of opts.syncDbSchema.tablesConfig) {\n    const tableContext = opts.context?.tables?.[table.crdtTableName];\n    const columns = opts.execute(`PRAGMA table_info(${quoteId(table.baseTableName)})`) as TableInfoRow[];\n\n    const lines = [`## ${table.crdtTableName}`];\n    if (tableContext?.description) {\n      lines.push(\"\", tableContext.description.trim());\n    }\n    lines.push(\"\", \"Columns:\");\n    for (const column of columns) {\n      if (column.name === \"tombstone\") continue;\n      const description = tableContext?.columns?.[column.name];\n      lines.push(\n        `- \\`${column.name}\\` ${column.type}${column.notnull ? \" NOT NULL\" : \"\"}${description ? ` — ${description}` : \"\"}`,\n      );\n    }\n    sections.push(lines.join(\"\\n\"));\n  }\n\n  return sections.join(\"\\n\\n\");\n}\n","import type { SyncDbSchema } from \"@sqlite-sync/core\";\nimport { createSchemaDoc, type SchemaDocContext } from \"./schema-doc\";\n\nexport type AiDbExecuteParams = {\n  sql: string;\n  parameters: readonly unknown[];\n};\n\n/**\n * Minimal executor contract for AI database access. Runtime-specific — inject the one that\n * matches where the storage lives; @sqlite-sync/cloudflare's `createKyselyExecutor` satisfies it.\n *\n * `transaction` MUST roll back everything the callback executed when the callback throws —\n * it backs the read-only enforcement of the query tooling.\n */\nexport type AiDbExecutor = {\n  execute<TResult = unknown>(query: AiDbExecuteParams): { rows: TResult[] };\n  transaction(callback: (tx: Pick<AiDbExecutor, \"execute\">) => void): void;\n};\n\n/**\n * Read-only AI access to a synced database. Lives where the storage lives; its method names\n * are the RPC contract, so a DO stub proxying to these methods exposes the same surface\n * (promise-wrapped) and satisfies the tool layer's `DbToolsAccess`.\n */\nexport type AiDbAccess = {\n  getSchemaDoc(): string;\n};\n\n/**\n * Create where the CRDT storage was created (e.g. a Durable Object's `onStart`, after\n * migrations have run) — the schema doc is introspected once and cached.\n */\nexport function createAiDbAccess(opts: {\n  executor: AiDbExecutor;\n  syncDbSchema: SyncDbSchema;\n  context?: SchemaDocContext;\n}): AiDbAccess {\n  let schemaDoc: string | undefined;\n\n  return {\n    getSchemaDoc() {\n      schemaDoc ??= createSchemaDoc({\n        execute: (sql) => opts.executor.execute<Record<string, unknown>>({ sql, parameters: [] }).rows,\n        syncDbSchema: opts.syncDbSchema,\n        context: opts.context,\n      });\n      return schemaDoc;\n    },\n  };\n}\n","import { jsonSchema, type ToolSet, tool } from \"ai\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * What the tools need from the database side. Satisfied directly by `AiDbAccess`, or by a\n * Durable Object stub whose RPC methods delegate to one (RPC wraps returns in promises).\n */\nexport type DbToolsAccess = {\n  getSchemaDoc(): MaybePromise<string>;\n};\n\nconst emptyInputSchema = jsonSchema<Record<string, never>>({\n  type: \"object\",\n  properties: {},\n  additionalProperties: false,\n});\n\n/**\n * AI SDK tools for a synced database. `access` is a factory because acquiring the database\n * may itself be async per call (e.g. resolving a Durable Object stub from another DO).\n */\nexport function createDbTools(opts: { access: () => MaybePromise<DbToolsAccess> }): ToolSet {\n  return {\n    getDbSchema: tool({\n      description:\n        \"Get the schema documentation for the synced SQLite database: tables, columns, types, and data conventions. Call this before reasoning about the data.\",\n      inputSchema: emptyInputSchema,\n      execute: async () => {\n        const access = await opts.access();\n        return await access.getSchemaDoc();\n      },\n    }),\n  };\n}\n"],"mappings":";AAkBA,SAAS,QAAQ,MAAc;AAC7B,SAAO,IAAI,KAAK,WAAW,KAAK,IAAI,CAAC;AACvC;AAQO,SAAS,gBAAgB,MAIrB;AACT,QAAM,WAAqB,CAAC;AAE5B,QAAM,WAAW,KAAK,SAAS,UAAU,KAAK;AAC9C,MAAI,UAAU;AACZ,aAAS,KAAK,QAAQ;AAAA,EACxB;AAEA,aAAW,SAAS,KAAK,aAAa,cAAc;AAClD,UAAM,eAAe,KAAK,SAAS,SAAS,MAAM,aAAa;AAC/D,UAAM,UAAU,KAAK,QAAQ,qBAAqB,QAAQ,MAAM,aAAa,CAAC,GAAG;AAEjF,UAAM,QAAQ,CAAC,MAAM,MAAM,aAAa,EAAE;AAC1C,QAAI,cAAc,aAAa;AAC7B,YAAM,KAAK,IAAI,aAAa,YAAY,KAAK,CAAC;AAAA,IAChD;AACA,UAAM,KAAK,IAAI,UAAU;AACzB,eAAW,UAAU,SAAS;AAC5B,UAAI,OAAO,SAAS,YAAa;AACjC,YAAM,cAAc,cAAc,UAAU,OAAO,IAAI;AACvD,YAAM;AAAA,QACJ,OAAO,OAAO,IAAI,MAAM,OAAO,IAAI,GAAG,OAAO,UAAU,cAAc,EAAE,GAAG,cAAc,WAAM,WAAW,KAAK,EAAE;AAAA,MAClH;AAAA,IACF;AACA,aAAS,KAAK,MAAM,KAAK,IAAI,CAAC;AAAA,EAChC;AAEA,SAAO,SAAS,KAAK,MAAM;AAC7B;;;AC3BO,SAAS,iBAAiB,MAIlB;AACb,MAAI;AAEJ,SAAO;AAAA,IACL,eAAe;AACb,oBAAc,gBAAgB;AAAA,QAC5B,SAAS,CAAC,QAAQ,KAAK,SAAS,QAAiC,EAAE,KAAK,YAAY,CAAC,EAAE,CAAC,EAAE;AAAA,QAC1F,cAAc,KAAK;AAAA,QACnB,SAAS,KAAK;AAAA,MAChB,CAAC;AACD,aAAO;AAAA,IACT;AAAA,EACF;AACF;;;AClDA,SAAS,YAA0B,YAAY;AAY/C,IAAM,mBAAmB,WAAkC;AAAA,EACzD,MAAM;AAAA,EACN,YAAY,CAAC;AAAA,EACb,sBAAsB;AACxB,CAAC;AAMM,SAAS,cAAc,MAA8D;AAC1F,SAAO;AAAA,IACL,aAAa,KAAK;AAAA,MAChB,aACE;AAAA,MACF,aAAa;AAAA,MACb,SAAS,YAAY;AACnB,cAAM,SAAS,MAAM,KAAK,OAAO;AACjC,eAAO,MAAM,OAAO,aAAa;AAAA,MACnC;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sqlite-sync/ai",
+  "version": "0.4.6",
+  "description": "AI agent tools for @sqlite-sync databases",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/krolebord-dev/sqlite-sync",
+    "directory": "packages/ai"
+  },
+  "keywords": [
+    "sqlite",
+    "sync",
+    "ai",
+    "agent",
+    "tools",
+    "offline-first",
+    "local-first"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@sqlite-sync/core": "^0.4.6",
+    "ai": "^6.0.0"
+  },
+  "devDependencies": {
+    "ai": "^6.0.201",
+    "tsup": "^8.3.5",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.8",
+    "@sqlite-sync/core": "0.4.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit"
+  }
+}