@kernl-sdk/libsql 0.1.36 → 0.1.39

package/dist/sql.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SQL utilities for safe query construction.
+ */
+/**
+ * SQL identifier regex - alphanumeric + underscore, must start with letter/underscore.
+ */
+export declare const SQL_IDENTIFIER_REGEX: RegExp;
+/**
+ * SQL clause with placeholder parameters.
+ */
+export interface SQLClause {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Expand an array into individual ? placeholders for IN clause.
+ *
+ * LibSQL/SQLite doesn't support array parameters like PostgreSQL's ANY($1).
+ * This helper expands arrays into individual placeholders.
+ *
+ * @example
+ * expandArray(['a', 'b', 'c']) => { placeholders: '?, ?, ?', params: ['a', 'b', 'c'] }
+ */
+export declare function expandarray(arr: unknown[]): {
+    placeholders: string;
+    params: unknown[];
+};
+//# sourceMappingURL=sql.d.ts.map

package/dist/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB,CAKA"}

package/dist/sql.js

@@ -0,0 +1,22 @@
+/**
+ * SQL utilities for safe query construction.
+ */
+/**
+ * SQL identifier regex - alphanumeric + underscore, must start with letter/underscore.
+ */
+export const SQL_IDENTIFIER_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Expand an array into individual ? placeholders for IN clause.
+ *
+ * LibSQL/SQLite doesn't support array parameters like PostgreSQL's ANY($1).
+ * This helper expands arrays into individual placeholders.
+ *
+ * @example
+ * expandArray(['a', 'b', 'c']) => { placeholders: '?, ?, ?', params: ['a', 'b', 'c'] }
+ */
+export function expandarray(arr) {
+    return {
+        placeholders: arr.map(() => "?").join(", "),
+        params: arr,
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,75 @@
+/**
+ * LibSQL storage adapter.
+ */
+import type { Client } from "@libsql/client";
+import type { IAgentRegistry, IModelRegistry, KernlStorage, Transaction } from "kernl";
+import { LibSQLThreadStore } from "./thread/store.js";
+import { LibSQLMemoryStore } from "./memory/store.js";
+/**
+ * LibSQL storage configuration.
+ */
+export interface LibSQLStorageConfig {
+    /**
+     * LibSQL client instance.
+     */
+    client: Client;
+    /**
+     * Original connection URL (optional).
+     *
+     * Used to detect local file databases for setting SQLite PRAGMAs.
+     * Not needed if using a pre-configured client.
+     */
+    url?: string;
+}
+/**
+ * LibSQL storage adapter.
+ *
+ * Storage is lazily initialized on first use via `ensureInit()`. This means
+ * callers don't need to explicitly call `init()` - it happens automatically.
+ */
+export declare class LibSQLStorage implements KernlStorage {
+    private client;
+    private url?;
+    private initPromise;
+    threads: LibSQLThreadStore;
+    memories: LibSQLMemoryStore;
+    constructor(config: LibSQLStorageConfig);
+    /**
+     * Ensure storage is initialized before any operation.
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    private ensureInit;
+    /**
+     * Bind runtime registries to storage.
+     */
+    bind(registries: {
+        agents: IAgentRegistry;
+        models: IModelRegistry;
+    }): void;
+    /**
+     * Execute a function within a transaction.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Initialize the storage backend.
+     */
+    init(): Promise<void>;
+    /**
+     * Check if this is a local file or in-memory database.
+     */
+    private isLocal;
+    /**
+     * Close the storage backend and cleanup resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Run migrations to ensure all required tables exist.
+     */
+    migrate(): Promise<void>;
+    /**
+     * Create a table from its definition.
+     */
+    private createTable;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,WAAW,EACZ,MAAM,OAAO,CAAC;AAKf,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAC,CAAS;IACrB,OAAO,CAAC,WAAW,CAA8B;IAEjD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC;gBAEhB,MAAM,EAAE,mBAAmB;IAOvC;;;;OAIG;YACW,UAAU;IAUxB;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,MAAM,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAI1E;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B;;OAEG;IACH,OAAO,CAAC,OAAO;IAKf;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAuC9B;;OAEG;YACW,WAAW;CAK1B"}

package/dist/storage.js

@@ -0,0 +1,123 @@
+/**
+ * LibSQL storage adapter.
+ */
+import { KERNL_SCHEMA_NAME, TABLE_MIGRATIONS } from "@kernl-sdk/storage";
+import { UnimplementedError } from "@kernl-sdk/shared/lib";
+import { LibSQLThreadStore } from "./thread/store.js";
+import { LibSQLMemoryStore } from "./memory/store.js";
+import { MIGRATIONS, createTable } from "./migrations.js";
+/**
+ * LibSQL storage adapter.
+ *
+ * Storage is lazily initialized on first use via `ensureInit()`. This means
+ * callers don't need to explicitly call `init()` - it happens automatically.
+ */
+export class LibSQLStorage {
+    client;
+    url;
+    initPromise = null;
+    threads;
+    memories;
+    constructor(config) {
+        this.client = config.client;
+        this.url = config.url;
+        this.threads = new LibSQLThreadStore(this.client, () => this.ensureInit());
+        this.memories = new LibSQLMemoryStore(this.client, () => this.ensureInit());
+    }
+    /**
+     * Ensure storage is initialized before any operation.
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    async ensureInit() {
+        if (!this.initPromise) {
+            this.initPromise = this.init().catch((err) => {
+                this.initPromise = null;
+                throw err;
+            });
+        }
+        return this.initPromise;
+    }
+    /**
+     * Bind runtime registries to storage.
+     */
+    bind(registries) {
+        this.threads.bind(registries);
+    }
+    /**
+     * Execute a function within a transaction.
+     */
+    async transaction(fn) {
+        throw new UnimplementedError();
+    }
+    /**
+     * Initialize the storage backend.
+     */
+    async init() {
+        // Set SQLite PRAGMAs for local file databases
+        // (Turso handles these automatically for remote connections)
+        if (this.isLocal()) {
+            await this.client.execute("PRAGMA journal_mode = WAL");
+            await this.client.execute("PRAGMA busy_timeout = 5000");
+        }
+        // Create migrations table first
+        await this.createTable(TABLE_MIGRATIONS);
+        await this.migrate();
+    }
+    /**
+     * Check if this is a local file or in-memory database.
+     */
+    isLocal() {
+        if (!this.url)
+            return false;
+        return this.url.startsWith("file:") || this.url === ":memory:";
+    }
+    /**
+     * Close the storage backend and cleanup resources.
+     */
+    async close() {
+        this.client.close();
+    }
+    /**
+     * Run migrations to ensure all required tables exist.
+     */
+    async migrate() {
+        const tx = await this.client.transaction("write");
+        try {
+            // read applied migration IDs
+            const migrationsTable = `${KERNL_SCHEMA_NAME}_migrations`;
+            const result = await tx.execute(`SELECT id FROM "${migrationsTable}" ORDER BY applied_at ASC`);
+            const applied = new Set(result.rows.map((row) => row.id));
+            // filter pending migrations
+            const pending = MIGRATIONS.filter((m) => !applied.has(m.id));
+            if (pending.length === 0) {
+                await tx.commit();
+                return;
+            }
+            // run pending migrations + insert into migrations table
+            for (const migration of pending) {
+                await migration.up({
+                    client: tx,
+                    createTable: async (table) => {
+                        await createTable(tx, table);
+                    },
+                });
+                await tx.execute({
+                    sql: `INSERT INTO "${migrationsTable}" (id, applied_at) VALUES (?, ?)`,
+                    args: [migration.id, Date.now()],
+                });
+            }
+            await tx.commit();
+        }
+        catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+    /**
+     * Create a table from its definition.
+     */
+    async createTable(table) {
+        await createTable(this.client, table);
+    }
+}

package/dist/thread/__tests__/append.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=append.test.d.ts.map

package/dist/thread/__tests__/append.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.test.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/append.test.ts"],"names":[],"mappings":""}

package/dist/thread/__tests__/append.test.js

@@ -0,0 +1,141 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { message, IN_PROGRESS, COMPLETED } from "@kernl-sdk/protocol";
+import { create_client, create_storage, create_mock_registries, testid, } from "../../__tests__/helpers.js";
+/** Create a ThreadEvent from a message */
+function evt(id, tid, seq, timestamp, role = "user", text = `msg-${seq}`, metadata = {}) {
+    return {
+        ...message({ role, text }),
+        id,
+        tid,
+        seq,
+        timestamp,
+        metadata,
+    };
+}
+/** Create a tool.call ThreadEvent */
+function toolCallEvt(id, tid, seq, timestamp) {
+    return {
+        kind: "tool.call",
+        id,
+        tid,
+        seq,
+        timestamp,
+        callId: `call-${seq}`,
+        toolId: "test-tool",
+        state: IN_PROGRESS,
+        arguments: "{}",
+        metadata: {},
+    };
+}
+/** Create a tool.result ThreadEvent */
+function toolResultEvt(id, tid, seq, timestamp) {
+    return {
+        kind: "tool.result",
+        id,
+        tid,
+        seq,
+        timestamp,
+        callId: `call-${seq - 1}`,
+        toolId: "test-tool",
+        state: COMPLETED,
+        result: null,
+        error: null,
+        metadata: {},
+    };
+}
+describe("LibSQLThreadStore append", () => {
+    let client;
+    let storage;
+    let tid;
+    beforeEach(async () => {
+        client = create_client();
+        storage = create_storage(client);
+        storage.bind(create_mock_registries());
+        await storage.memories.list(); // init
+        tid = testid("thread");
+        await storage.threads.insert({
+            id: tid,
+            namespace: "default",
+            agentId: "test-agent",
+            model: "test/model",
+        });
+    });
+    afterEach(() => {
+        client.close();
+    });
+    it("appends events in order", async () => {
+        const now = Date.now();
+        await storage.threads.append([
+            evt("e1", tid, 1, new Date(now), "user"),
+            evt("e2", tid, 2, new Date(now + 1), "assistant"),
+        ]);
+        const history = await storage.threads.history(tid);
+        expect(history.length).toBe(2);
+        expect(history[0].id).toBe("e1");
+        expect(history[0].seq).toBe(1);
+        expect(history[1].id).toBe("e2");
+        expect(history[1].seq).toBe(2);
+    });
+    it("preserves event data and metadata", async () => {
+        const now = Date.now();
+        const metadata = { source: "api", version: 2 };
+        await storage.threads.append([
+            evt("e1", tid, 1, new Date(now), "user", "Hello, world!", metadata),
+        ]);
+        const history = await storage.threads.history(tid);
+        const event = history[0];
+        expect(event.kind).toBe("message");
+        if (event.kind === "message") {
+            expect(event.role).toBe("user");
+            expect(event.content).toEqual([{ kind: "text", text: "Hello, world!" }]);
+        }
+        expect(event.metadata).toEqual(metadata);
+        expect(event.timestamp.getTime()).toBe(now);
+    });
+    it("is idempotent on duplicate ids", async () => {
+        const now = Date.now();
+        // First append
+        await storage.threads.append([evt("e1", tid, 1, new Date(now))]);
+        // Duplicate append (same id)
+        await storage.threads.append([evt("e1", tid, 1, new Date(now + 100))]);
+        const history = await storage.threads.history(tid);
+        // Should only have one event
+        expect(history.length).toBe(1);
+        // Original timestamp should be preserved
+        expect(history[0].timestamp.getTime()).toBe(now);
+    });
+    it("handles empty event list", async () => {
+        await storage.threads.append([]);
+        const history = await storage.threads.history(tid);
+        expect(history.length).toBe(0);
+    });
+    it("handles multiple appends", async () => {
+        const now = Date.now();
+        await storage.threads.append([evt("e1", tid, 1, new Date(now))]);
+        await storage.threads.append([
+            toolCallEvt("e2", tid, 2, new Date(now + 1)),
+            toolResultEvt("e3", tid, 3, new Date(now + 2)),
+        ]);
+        await storage.threads.append([evt("e4", tid, 4, new Date(now + 3))]);
+        const history = await storage.threads.history(tid);
+        expect(history.length).toBe(4);
+        expect(history.map((e) => e.id)).toEqual(["e1", "e2", "e3", "e4"]);
+    });
+    it("handles mixed duplicate and new events", async () => {
+        const now = Date.now();
+        await storage.threads.append([
+            evt("e1", tid, 1, new Date(now)),
+            evt("e2", tid, 2, new Date(now + 1)),
+        ]);
+        // Append with one duplicate and one new
+        await storage.threads.append([
+            evt("e2", tid, 2, new Date(now + 100)), // duplicate
+            evt("e3", tid, 3, new Date(now + 2)), // new
+        ]);
+        const history = await storage.threads.history(tid);
+        expect(history.length).toBe(3);
+        expect(history.map((e) => e.id)).toEqual(["e1", "e2", "e3"]);
+        // e2 should have original timestamp
+        expect(history[1].timestamp.getTime()).toBe(now + 1);
+    });
+});

package/dist/thread/__tests__/history.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=history.test.d.ts.map

package/dist/thread/__tests__/history.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.test.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/history.test.ts"],"names":[],"mappings":""}

package/dist/thread/__tests__/history.test.js

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { message, IN_PROGRESS, COMPLETED } from "@kernl-sdk/protocol";
+import { create_client, create_storage, create_mock_registries, testid, } from "../../__tests__/helpers.js";
+/** Create a message ThreadEvent */
+function evt(id, tid, seq, timestamp, role = "user") {
+    return {
+        ...message({ role, text: `msg-${seq}` }),
+        id,
+        tid,
+        seq,
+        timestamp,
+        metadata: {},
+    };
+}
+/** Create a tool.call ThreadEvent */
+function toolCallEvt(id, tid, seq, timestamp) {
+    return {
+        kind: "tool.call",
+        id,
+        tid,
+        seq,
+        timestamp,
+        callId: `call-${seq}`,
+        toolId: "test-tool",
+        state: IN_PROGRESS,
+        arguments: "{}",
+        metadata: {},
+    };
+}
+/** Create a tool.result ThreadEvent */
+function toolResultEvt(id, tid, seq, timestamp) {
+    return {
+        kind: "tool.result",
+        id,
+        tid,
+        seq,
+        timestamp,
+        callId: `call-${seq - 1}`,
+        toolId: "test-tool",
+        state: COMPLETED,
+        result: null,
+        error: null,
+        metadata: {},
+    };
+}
+describe("LibSQLThreadStore history", () => {
+    let client;
+    let storage;
+    let tid;
+    beforeEach(async () => {
+        client = create_client();
+        storage = create_storage(client);
+        storage.bind(create_mock_registries());
+        await storage.memories.list(); // init
+        tid = testid("thread");
+        await storage.threads.insert({
+            id: tid,
+            namespace: "default",
+            agentId: "test-agent",
+            model: "test/model",
+        });
+        // Add test events
+        const now = Date.now();
+        await storage.threads.append([
+            evt("e1", tid, 1, new Date(now)),
+            toolCallEvt("e2", tid, 2, new Date(now + 1)),
+            toolResultEvt("e3", tid, 3, new Date(now + 2)),
+            evt("e4", tid, 4, new Date(now + 3)),
+            evt("e5", tid, 5, new Date(now + 4)),
+        ]);
+    });
+    afterEach(() => {
+        client.close();
+    });
+    it("returns events in asc order by default", async () => {
+        const history = await storage.threads.history(tid);
+        expect(history.length).toBe(5);
+        expect(history[0].seq).toBe(1);
+        expect(history[4].seq).toBe(5);
+    });
+    it("filters by after seq", async () => {
+        const history = await storage.threads.history(tid, { after: 2 });
+        expect(history.length).toBe(3);
+        expect(history[0].seq).toBe(3);
+        expect(history[2].seq).toBe(5);
+    });
+    it("filters by kinds", async () => {
+        const history = await storage.threads.history(tid, {
+            kinds: ["message"],
+        });
+        expect(history.length).toBe(3);
+        expect(history.every((e) => e.kind === "message")).toBe(true);
+    });
+    it("filters by multiple kinds", async () => {
+        const history = await storage.threads.history(tid, {
+            kinds: ["tool.call", "tool.result"],
+        });
+        expect(history.length).toBe(2);
+        expect(history.map((e) => e.kind)).toEqual(["tool.call", "tool.result"]);
+    });
+    it("supports desc order and limit", async () => {
+        const history = await storage.threads.history(tid, {
+            order: "desc",
+            limit: 2,
+        });
+        expect(history.length).toBe(2);
+        expect(history[0].seq).toBe(5);
+        expect(history[1].seq).toBe(4);
+    });
+    it("combines after, kinds, and limit", async () => {
+        const history = await storage.threads.history(tid, {
+            after: 1,
+            kinds: ["message"],
+            limit: 1,
+            order: "asc",
+        });
+        expect(history.length).toBe(1);
+        expect(history[0].seq).toBe(4); // First message after seq 1
+    });
+    it("returns empty array for non-existent thread", async () => {
+        const history = await storage.threads.history("nonexistent");
+        expect(history).toEqual([]);
+    });
+    it("includes history when getting thread with include option", async () => {
+        const thread = await storage.threads.get(tid, { history: true });
+        // Thread is returned with history loaded (history is private,
+        // so we verify via get returning non-null and separate history() call)
+        expect(thread).not.toBeNull();
+        expect(thread?.tid).toBe(tid);
+        // Verify events exist via direct history query
+        const history = await storage.threads.history(tid);
+        expect(history.length).toBe(5);
+    });
+    it("respects history options when getting thread", async () => {
+        const thread = await storage.threads.get(tid, {
+            history: { after: 3, limit: 2 },
+        });
+        // Thread is returned with filtered history loaded
+        expect(thread).not.toBeNull();
+        expect(thread?.tid).toBe(tid);
+        // Verify filtered history via direct query with same options
+        const history = await storage.threads.history(tid, { after: 3, limit: 2 });
+        expect(history.length).toBe(2);
+        expect(history[0].seq).toBe(4);
+    });
+});

package/dist/thread/__tests__/sql.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sql.test.d.ts.map

package/dist/thread/__tests__/sql.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.test.d.ts","sourceRoot":"","sources":["../../../src/thread/__tests__/sql.test.ts"],"names":[],"mappings":""}