@kernl-sdk/libsql 0.1.38 → 0.1.39

package/src/thread/__tests__/history.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import type { Client } from "@libsql/client";
+import { message, IN_PROGRESS, COMPLETED } from "@kernl-sdk/protocol";
+import type { ThreadEvent } from "kernl/internal";
+
+import {
+  create_client,
+  create_storage,
+  create_mock_registries,
+  testid,
+} from "../../__tests__/helpers";
+import { LibSQLStorage } from "../../storage";
+
+/** Create a message ThreadEvent */
+function evt(
+  id: string,
+  tid: string,
+  seq: number,
+  timestamp: Date,
+  role: "user" | "assistant" = "user",
+): ThreadEvent {
+  return {
+    ...message({ role, text: `msg-${seq}` }),
+    id,
+    tid,
+    seq,
+    timestamp,
+    metadata: {},
+  } as ThreadEvent;
+}
+
+/** Create a tool.call ThreadEvent */
+function toolCallEvt(
+  id: string,
+  tid: string,
+  seq: number,
+  timestamp: Date,
+): ThreadEvent {
+  return {
+    kind: "tool.call",
+    id,
+    tid,
+    seq,
+    timestamp,
+    callId: `call-${seq}`,
+    toolId: "test-tool",
+    state: IN_PROGRESS,
+    arguments: "{}",
+    metadata: {},
+  } as ThreadEvent;
+}
+
+/** Create a tool.result ThreadEvent */
+function toolResultEvt(
+  id: string,
+  tid: string,
+  seq: number,
+  timestamp: Date,
+): ThreadEvent {
+  return {
+    kind: "tool.result",
+    id,
+    tid,
+    seq,
+    timestamp,
+    callId: `call-${seq - 1}`,
+    toolId: "test-tool",
+    state: COMPLETED,
+    result: null,
+    error: null,
+    metadata: {},
+  } as ThreadEvent;
+}
+
+describe("LibSQLThreadStore history", () => {
+  let client: Client;
+  let storage: LibSQLStorage;
+  let tid: string;
+
+  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/src/thread/__tests__/sql.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+
+import { SQL_WHERE, SQL_ORDER, SQL_UPDATE } from "../sql";
+
+describe("LibSQL thread SQL codecs", () => {
+  describe("SQL_WHERE", () => {
+    it("returns empty clause when no filters", () => {
+      const result = SQL_WHERE.encode({ filter: undefined });
+      expect(result.sql).toBe("");
+      expect(result.params).toEqual([]);
+    });
+
+    it("encodes namespace filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { namespace: "default" },
+      });
+      expect(result.sql).toBe("namespace = ?");
+      expect(result.params).toEqual(["default"]);
+    });
+
+    it("encodes agentId filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { agentId: "agent-1" },
+      });
+      expect(result.sql).toBe("agent_id = ?");
+      expect(result.params).toEqual(["agent-1"]);
+    });
+
+    it("encodes single state filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { state: "stopped" },
+      });
+      expect(result.sql).toBe("state = ?");
+      expect(result.params).toEqual(["stopped"]);
+    });
+
+    it("encodes state array filter with IN clause", () => {
+      const result = SQL_WHERE.encode({
+        filter: { state: ["stopped", "running", "interruptible"] },
+      });
+      expect(result.sql).toBe("state IN (?, ?, ?)");
+      expect(result.params).toEqual(["stopped", "running", "interruptible"]);
+    });
+
+    it("encodes parentTaskId filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { parentTaskId: "task-1" },
+      });
+      expect(result.sql).toBe("parent_task_id = ?");
+      expect(result.params).toEqual(["task-1"]);
+    });
+
+    it("encodes date range filters", () => {
+      const after = new Date("2024-01-01");
+      const before = new Date("2024-12-31");
+
+      const result = SQL_WHERE.encode({
+        filter: { createdAfter: after, createdBefore: before },
+      });
+
+      // Uses > and < not >= and <=
+      expect(result.sql).toBe("created_at > ? AND created_at < ?");
+      expect(result.params).toEqual([after.getTime(), before.getTime()]);
+    });
+
+    it("combines multiple filters with AND", () => {
+      const result = SQL_WHERE.encode({
+        filter: {
+          namespace: "default",
+          agentId: "agent-1",
+          state: "stopped",
+        },
+      });
+
+      // Order depends on filter processing order, check contains
+      expect(result.sql).toContain("namespace = ?");
+      expect(result.sql).toContain("agent_id = ?");
+      expect(result.sql).toContain("state = ?");
+      expect(result.sql).toContain(" AND ");
+      expect(result.params).toContain("default");
+      expect(result.params).toContain("agent-1");
+      expect(result.params).toContain("stopped");
+    });
+  });
+
+  describe("SQL_ORDER", () => {
+    it("returns default ordering", () => {
+      const result = SQL_ORDER.encode({ order: undefined });
+      expect(result).toBe("created_at DESC");
+    });
+
+    it("encodes createdAt asc", () => {
+      const result = SQL_ORDER.encode({ order: { createdAt: "asc" } });
+      expect(result).toBe("created_at ASC");
+    });
+
+    it("encodes createdAt desc", () => {
+      const result = SQL_ORDER.encode({ order: { createdAt: "desc" } });
+      expect(result).toBe("created_at DESC");
+    });
+
+    it("encodes updatedAt asc", () => {
+      const result = SQL_ORDER.encode({ order: { updatedAt: "asc" } });
+      expect(result).toBe("updated_at ASC");
+    });
+
+    it("encodes updatedAt desc", () => {
+      const result = SQL_ORDER.encode({ order: { updatedAt: "desc" } });
+      expect(result).toBe("updated_at DESC");
+    });
+  });
+
+  describe("SQL_UPDATE", () => {
+    it("encodes tick update", () => {
+      const result = SQL_UPDATE.encode({ patch: { tick: 5 } });
+      expect(result.sql).toContain("tick = ?");
+      expect(result.params).toContain(5);
+    });
+
+    it("encodes state update", () => {
+      const result = SQL_UPDATE.encode({ patch: { state: "running" } });
+      expect(result.sql).toContain("state = ?");
+      expect(result.params).toContain("running");
+    });
+
+    it("encodes metadata update with JSON stringify", () => {
+      const metadata = { title: "Test" };
+      const result = SQL_UPDATE.encode({ patch: { metadata } });
+      expect(result.sql).toContain("metadata = ?");
+      expect(result.params).toContain(JSON.stringify(metadata));
+    });
+
+    it("always includes updated_at", () => {
+      const before = Date.now();
+      const result = SQL_UPDATE.encode({ patch: { tick: 1 } });
+      const after = Date.now();
+
+      expect(result.sql).toContain("updated_at = ?");
+      const updatedAt = result.params.find(
+        (p) => typeof p === "number" && p >= before && p <= after,
+      );
+      expect(updatedAt).toBeDefined();
+    });
+
+    it("combines multiple updates", () => {
+      const result = SQL_UPDATE.encode({
+        patch: { tick: 3, state: "interruptible" },
+      });
+      expect(result.sql).toContain("tick = ?");
+      expect(result.sql).toContain("state = ?");
+      expect(result.sql).toContain("updated_at = ?");
+    });
+  });
+});

package/src/thread/__tests__/store.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import type { Client } from "@libsql/client";
+import { message } from "@kernl-sdk/protocol";
+import type { ThreadEvent } from "kernl/internal";
+
+import {
+  create_client,
+  create_storage,
+  create_mock_registries,
+  testid,
+} from "../../__tests__/helpers";
+import { LibSQLStorage } from "../../storage";
+
+/** Create a message ThreadEvent */
+function evt(
+  id: string,
+  tid: string,
+  seq: number,
+  timestamp: Date,
+): ThreadEvent {
+  return {
+    ...message({ role: "user", text: `msg-${seq}` }),
+    id,
+    tid,
+    seq,
+    timestamp,
+    metadata: {},
+  } as ThreadEvent;
+}
+
+describe("LibSQLThreadStore", () => {
+  let client: Client;
+  let storage: LibSQLStorage;
+
+  beforeEach(async () => {
+    client = create_client();
+    storage = create_storage(client);
+    storage.bind(create_mock_registries());
+    await storage.memories.list(); // init
+  });
+
+  afterEach(() => {
+    client.close();
+  });
+
+  it("inserts and gets a thread", async () => {
+    const tid = testid("thread");
+
+    const inserted = await storage.threads.insert({
+      id: tid,
+      namespace: "default",
+      agentId: "test-agent",
+      model: "test/model",
+      context: { userId: "user-1" },
+      metadata: { title: "Test" },
+    });
+
+    expect(inserted.tid).toBe(tid);
+    expect(inserted.namespace).toBe("default");
+
+    const found = await storage.threads.get(tid);
+    expect(found).not.toBeNull();
+    expect(found?.tid).toBe(tid);
+    expect(found?.metadata).toEqual({ title: "Test" });
+  });
+
+  it("returns null for non-existent thread", async () => {
+    const found = await storage.threads.get("nonexistent");
+    expect(found).toBeNull();
+  });
+
+  it("updates thread fields and metadata", async () => {
+    const tid = testid("thread");
+
+    await storage.threads.insert({
+      id: tid,
+      namespace: "default",
+      agentId: "test-agent",
+      model: "test/model",
+    });
+
+    const updated = await storage.threads.update(tid, {
+      tick: 5,
+      state: "running",
+      metadata: { title: "Updated", score: 100 },
+    });
+
+    expect(updated._tick).toBe(5);
+    expect(updated.state).toBe("running");
+    expect(updated.metadata).toEqual({ title: "Updated", score: 100 });
+
+    // Verify persisted
+    const found = await storage.threads.get(tid);
+    expect(found?._tick).toBe(5);
+    expect(found?.state).toBe("running");
+  });
+
+  it("lists threads with filters and pagination", async () => {
+    // Create multiple threads
+    await storage.threads.insert({
+      id: testid("t1"),
+      namespace: "ns1",
+      agentId: "test-agent",
+      model: "test/model",
+      state: "stopped",
+    });
+    await storage.threads.insert({
+      id: testid("t2"),
+      namespace: "ns1",
+      agentId: "test-agent",
+      model: "test/model",
+      state: "running",
+    });
+    await storage.threads.insert({
+      id: testid("t3"),
+      namespace: "ns2",
+      agentId: "test-agent",
+      model: "test/model",
+      state: "stopped",
+    });
+
+    // Filter by namespace
+    const ns1Threads = await storage.threads.list({
+      filter: { namespace: "ns1" },
+    });
+    expect(ns1Threads.length).toBe(2);
+
+    // Filter by state
+    const stoppedThreads = await storage.threads.list({
+      filter: { state: "stopped" },
+    });
+    expect(stoppedThreads.length).toBe(2);
+
+    // Filter by state array
+    const activeThreads = await storage.threads.list({
+      filter: { state: ["stopped", "running"] },
+    });
+    expect(activeThreads.length).toBe(3);
+
+    // Pagination
+    const page1 = await storage.threads.list({ limit: 2 });
+    expect(page1.length).toBe(2);
+
+    const page2 = await storage.threads.list({ limit: 2, offset: 2 });
+    expect(page2.length).toBe(1);
+  });
+
+  it("orders threads by createdAt", async () => {
+    const t1 = testid("t1");
+    const t2 = testid("t2");
+
+    await storage.threads.insert({
+      id: t1,
+      namespace: "default",
+      agentId: "test-agent",
+      model: "test/model",
+    });
+
+    // Small delay to ensure different timestamps
+    await new Promise((r) => setTimeout(r, 10));
+
+    await storage.threads.insert({
+      id: t2,
+      namespace: "default",
+      agentId: "test-agent",
+      model: "test/model",
+    });
+
+    const asc = await storage.threads.list({
+      order: { createdAt: "asc" },
+    });
+    expect(asc[0].tid).toBe(t1);
+    expect(asc[1].tid).toBe(t2);
+
+    const desc = await storage.threads.list({
+      order: { createdAt: "desc" },
+    });
+    expect(desc[0].tid).toBe(t2);
+    expect(desc[1].tid).toBe(t1);
+  });
+
+  it("deletes thread", async () => {
+    const tid = testid("thread");
+
+    await storage.threads.insert({
+      id: tid,
+      namespace: "default",
+      agentId: "test-agent",
+      model: "test/model",
+    });
+
+    // Add some events
+    await storage.threads.append([evt("evt-1", tid, 1, new Date())]);
+
+    await storage.threads.delete(tid);
+
+    const found = await storage.threads.get(tid);
+    expect(found).toBeNull();
+
+    // Events should also be deleted (cascade)
+    const history = await storage.threads.history(tid);
+    expect(history.length).toBe(0);
+  });
+
+  it("returns null when agent/model not in registry", async () => {
+    const tid = testid("thread");
+
+    // Insert with non-existent agent
+    await client.execute({
+      sql: `INSERT INTO kernl_threads (id, namespace, agent_id, model, context, tick, state, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      args: [tid, "default", "unknown-agent", "unknown/model", "{}", 0, "idle", Date.now(), Date.now()],
+    });
+
+    // Get should return null (graceful degradation)
+    const found = await storage.threads.get(tid);
+    expect(found).toBeNull();
+  });
+});

package/src/thread/row.ts

@@ -0,0 +1,77 @@
+/**
+ * LibSQL row codecs for thread data.
+ */
+
+import type { Row } from "@libsql/client";
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { ThreadState } from "kernl";
+import type { ThreadRecord, ThreadEventRecord } from "@kernl-sdk/storage";
+
+import { parsejson } from "../utils";
+
+/**
+ * Codec for converting LibSQL rows to ThreadRecord.
+ */
+export const RowToThreadRecord: Codec<Row, ThreadRecord> = {
+  encode(row: Row): ThreadRecord {
+    return {
+      id: row.id as string,
+      namespace: row.namespace as string,
+      agent_id: row.agent_id as string,
+      model: row.model as string,
+      context: parsejson<Record<string, unknown>>(row.context) ?? {},
+      tick: row.tick as number,
+      state: row.state as ThreadState,
+      parent_task_id: row.parent_task_id as string | null,
+      metadata: parsejson<Record<string, unknown>>(row.metadata),
+      created_at: row.created_at as number,
+      updated_at: row.updated_at as number,
+    };
+  },
+
+  decode(): Row {
+    throw new Error("RowToThreadRecord.decode not implemented");
+  },
+};
+
+/**
+ * Codec for converting LibSQL rows (from JOIN query) to ThreadEventRecord.
+ */
+export const RowToEventRecord: Codec<Row, ThreadEventRecord> = {
+  encode(row: Row): ThreadEventRecord {
+    return {
+      id: row.event_id as string,
+      tid: row.event_tid as string,
+      seq: row.seq as number,
+      kind: row.event_kind as string,
+      timestamp: Number(row.timestamp),
+      data: parsejson<Record<string, unknown>>(row.data),
+      metadata: parsejson<Record<string, unknown>>(row.event_metadata),
+    } as ThreadEventRecord;
+  },
+
+  decode(): Row {
+    throw new Error("RowToEventRecord.decode not implemented");
+  },
+};
+
+/**
+ * Codec for converting LibSQL rows to ThreadEventRecord (direct query).
+ */
+export const RowToEventRecordDirect: Codec<Row, ThreadEventRecord> = {
+  encode(row: Row): ThreadEventRecord {
+    return {
+      id: row.id as string,
+      tid: row.tid as string,
+      seq: row.seq as number,
+      kind: row.kind as string,
+      timestamp: Number(row.timestamp),
+      data: parsejson<Record<string, unknown>>(row.data),
+      metadata: parsejson<Record<string, unknown>>(row.metadata),
+    } as ThreadEventRecord;
+  },
+
+  decode(): Row {
+    throw new Error("RowToEventRecordDirect.decode not implemented");
+  },
+};