@kernl-sdk/pg 0.1.9

package/dist/thread/store.d.ts

@@ -0,0 +1,64 @@
+import type { Pool, PoolClient } from "pg";
+import { type ThreadRecord } from "@kernl-sdk/storage";
+import { Thread, type ThreadEvent } from "kernl/internal";
+import { type AgentRegistry, type ModelRegistry, type ThreadStore, type NewThread, type ThreadUpdate, type ThreadInclude, type ThreadListOptions, type ThreadHistoryOptions } from "kernl";
+/**
+ * PostgreSQL Thread store implementation.
+ */
+export declare class PGThreadStore implements ThreadStore {
+    private db;
+    private registries;
+    constructor(db: Pool | PoolClient);
+    /**
+     * Bind runtime registries for hydrating Thread instances.
+     *
+     * (TODO): move into abstract ThreadStore class
+     */
+    bind(registries: {
+        agents: AgentRegistry;
+        models: ModelRegistry;
+    }): void;
+    /**
+     * Get a thread by id.
+     */
+    get(tid: string, include?: ThreadInclude): Promise<Thread | null>;
+    /**
+     * List threads matching the filter.
+     */
+    list(options?: ThreadListOptions): Promise<Thread[]>;
+    /**
+     * Insert a new thread into the store.
+     */
+    insert(thread: NewThread): Promise<Thread>;
+    /**
+     * Update thread runtime state.
+     */
+    update(tid: string, patch: ThreadUpdate): Promise<Thread>;
+    /**
+     * Delete a thread and cascade to thread_events.
+     */
+    delete(tid: string): Promise<void>;
+    /**
+     * Get the event history for a thread.
+     */
+    history(tid: string, opts?: ThreadHistoryOptions): Promise<ThreadEvent[]>;
+    /**
+     * Append events to the thread history.
+     *
+     * Semantics:
+     * - Guaranteed per-thread ordering via monotonically increasing `seq`
+     * - Idempotent on `(tid, event.id)`: duplicate ids MUST NOT create duplicate rows
+     * - Events maintain insertion order
+     *
+     * NOTE: Thread class manages monotonic seq and timestamp assignment, is the only entrypoint.
+     */
+    append(events: ThreadEvent[]): Promise<void>;
+    /**
+     * Hydrate a Thread instance from a database record.
+     */
+    hydrate(thread: {
+        record: ThreadRecord;
+        events?: ThreadEvent[];
+    }): Thread;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/thread/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/thread/store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE3C,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,OAAO,CAAC;AAEf;;GAEG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,UAAU,CAA0D;gBAEhE,EAAE,EAAE,IAAI,GAAG,UAAU;IAKjC;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqGvE;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiG1D;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BhD;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA6C/D;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;OAEG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,WAAW,EAAE,CAAC;IAsCzB;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkClD;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,MAAM;CAkC1E"}

package/dist/thread/store.js

@@ -0,0 +1,346 @@
+import assert from "assert";
+import { SCHEMA_NAME, NewThreadCodec, ThreadEventRecordCodec, } from "@kernl-sdk/storage";
+import { Thread } from "kernl/internal";
+import { Context, } from "kernl";
+/**
+ * PostgreSQL Thread store implementation.
+ */
+export class PGThreadStore {
+    db;
+    registries;
+    constructor(db) {
+        this.db = db;
+        this.registries = null;
+    }
+    /**
+     * Bind runtime registries for hydrating Thread instances.
+     *
+     * (TODO): move into abstract ThreadStore class
+     */
+    bind(registries) {
+        this.registries = registries;
+    }
+    /**
+     * Get a thread by id.
+     */
+    async get(tid, include) {
+        // JOIN with thread_events if include.history
+        if (include?.history) {
+            const opts = typeof include.history === "object" ? include.history : undefined;
+            const params = [tid];
+            let index = 2;
+            let eventFilter = "";
+            if (opts?.after !== undefined) {
+                eventFilter += ` AND e.seq > $${index++}`;
+                params.push(opts.after);
+            }
+            if (opts?.kinds && opts.kinds.length > 0) {
+                eventFilter += ` AND e.kind = ANY($${index++})`;
+                params.push(opts.kinds);
+            }
+            const order = opts?.order ?? "asc";
+            const limit = opts?.limit ? ` LIMIT ${opts.limit}` : "";
+            const query = `
+        SELECT
+          t.*,
+          e.id as event_id,
+          e.tid as event_tid,
+          e.seq,
+          e.kind as event_kind,
+          e.timestamp,
+          e.data,
+          e.metadata as event_metadata
+        FROM ${SCHEMA_NAME}.threads t
+        LEFT JOIN ${SCHEMA_NAME}.thread_events e ON t.id = e.tid${eventFilter}
+        WHERE t.id = $1
+        ORDER BY e.seq ${order.toUpperCase()}
+        ${limit}
+      `;
+            const result = await this.db.query(query, params);
+            if (result.rows.length === 0) {
+                return null;
+            }
+            // first row has thread data (all rows have same thread data)
+            const first = result.rows[0];
+            const record = {
+                id: first.id,
+                namespace: first.namespace,
+                agent_id: first.agent_id,
+                model: first.model,
+                context: first.context,
+                tick: first.tick,
+                state: first.state,
+                parent_task_id: first.parent_task_id,
+                metadata: first.metadata,
+                created_at: first.created_at,
+                updated_at: first.updated_at,
+            };
+            // collect events from all rows (skip rows where event_id is null)
+            const events = result.rows
+                .filter((row) => row.event_id !== null)
+                .map((row) => ThreadEventRecordCodec.decode({
+                id: row.event_id,
+                tid: row.event_tid,
+                seq: row.seq,
+                kind: row.event_kind,
+                timestamp: Number(row.timestamp), // pg returns BIGINT as string by default, normalize to number
+                data: row.data,
+                metadata: row.event_metadata,
+            }));
+            try {
+                return this.hydrate({ record, events });
+            }
+            catch (error) {
+                return null;
+            }
+        }
+        // simple query without events
+        const result = await this.db.query(`SELECT * FROM ${SCHEMA_NAME}.threads WHERE id = $1`, [tid]);
+        if (result.rows.length === 0) {
+            return null;
+        }
+        try {
+            return this.hydrate({ record: result.rows[0] });
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * List threads matching the filter.
+     */
+    async list(options) {
+        let query = `SELECT * FROM ${SCHEMA_NAME}.threads`;
+        const values = [];
+        let paramIndex = 1;
+        // build WHERE clause
+        const conditions = [];
+        if (options?.filter) {
+            const { state, agentId, parentTaskId, createdAfter, createdBefore, namespace, } = options.filter;
+            if (namespace) {
+                conditions.push(`namespace = $${paramIndex++}`);
+                values.push(namespace);
+            }
+            if (state) {
+                if (Array.isArray(state)) {
+                    conditions.push(`state = ANY($${paramIndex++})`);
+                    values.push(state);
+                }
+                else {
+                    conditions.push(`state = $${paramIndex++}`);
+                    values.push(state);
+                }
+            }
+            if (agentId) {
+                conditions.push(`agent_id = $${paramIndex++}`);
+                values.push(agentId);
+            }
+            if (parentTaskId) {
+                conditions.push(`parent_task_id = $${paramIndex++}`);
+                values.push(parentTaskId);
+            }
+            if (createdAfter) {
+                conditions.push(`created_at > $${paramIndex++}`);
+                values.push(createdAfter.getTime());
+            }
+            if (createdBefore) {
+                conditions.push(`created_at < $${paramIndex++}`);
+                values.push(createdBefore.getTime());
+            }
+        }
+        if (conditions.length > 0) {
+            query += ` WHERE ${conditions.join(" AND ")}`;
+        }
+        // build ORDER BY clause
+        const orderClauses = [];
+        if (options?.order?.createdAt) {
+            orderClauses.push(`created_at ${options.order.createdAt.toUpperCase()}`);
+        }
+        if (options?.order?.updatedAt) {
+            orderClauses.push(`updated_at ${options.order.updatedAt.toUpperCase()}`);
+        }
+        if (orderClauses.length > 0) {
+            query += ` ORDER BY ${orderClauses.join(", ")}`;
+        }
+        else {
+            // default: most recent first
+            query += ` ORDER BY created_at DESC`;
+        }
+        if (options?.limit) {
+            query += ` LIMIT $${paramIndex++}`;
+            values.push(options.limit);
+        }
+        if (options?.offset) {
+            query += ` OFFSET $${paramIndex++}`;
+            values.push(options.offset);
+        }
+        const result = await this.db.query(query, values);
+        return result.rows
+            .map((record) => {
+            try {
+                return this.hydrate({ record });
+            }
+            catch (error) {
+                // Skip threads with non-existent agent/model (graceful degradation)
+                //
+                // (TODO): what do we want to do with this?
+                return null;
+            }
+        })
+            .filter((thread) => thread !== null);
+    }
+    /**
+     * Insert a new thread into the store.
+     */
+    async insert(thread) {
+        const record = NewThreadCodec.encode(thread);
+        const result = await this.db.query(`INSERT INTO ${SCHEMA_NAME}.threads
+       (id, namespace, agent_id, model, context, tick, state, parent_task_id, metadata, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8, $9::jsonb, $10, $11)
+       RETURNING *`, [
+            record.id,
+            record.namespace,
+            record.agent_id,
+            record.model,
+            record.context,
+            record.tick,
+            record.state,
+            record.parent_task_id,
+            record.metadata,
+            record.created_at,
+            record.updated_at,
+        ]);
+        return this.hydrate({ record: result.rows[0] });
+    }
+    /**
+     * Update thread runtime state.
+     */
+    async update(tid, patch) {
+        const updates = [];
+        const values = [];
+        let paramIndex = 1;
+        if (patch.tick !== undefined) {
+            updates.push(`tick = $${paramIndex++}`);
+            values.push(patch.tick);
+        }
+        if (patch.state !== undefined) {
+            updates.push(`state = $${paramIndex++}`);
+            values.push(patch.state);
+        }
+        if (patch.context !== undefined) {
+            updates.push(`context = $${paramIndex++}`);
+            // NOTE: Store the raw context value, not the Context wrapper. 
+            //
+            // THis may change in the future depending on Context implementation.
+            values.push(JSON.stringify(patch.context.context));
+        }
+        if (patch.metadata !== undefined) {
+            updates.push(`metadata = $${paramIndex++}`);
+            values.push(patch.metadata ? JSON.stringify(patch.metadata) : null);
+        }
+        // always update `updated_at`
+        updates.push(`updated_at = $${paramIndex++}`);
+        values.push(Date.now());
+        values.push(tid); // WHERE id = $N
+        const result = await this.db.query(`UPDATE ${SCHEMA_NAME}.threads
+       SET ${updates.join(", ")}
+       WHERE id = $${paramIndex}
+       RETURNING *`, values);
+        return this.hydrate({ record: result.rows[0] });
+    }
+    /**
+     * Delete a thread and cascade to thread_events.
+     */
+    async delete(tid) {
+        await this.db.query(`DELETE FROM ${SCHEMA_NAME}.threads WHERE id = $1`, [
+            tid,
+        ]);
+    }
+    /**
+     * Get the event history for a thread.
+     */
+    async history(tid, opts) {
+        let query = `SELECT * FROM ${SCHEMA_NAME}.thread_events WHERE tid = $1`;
+        const values = [tid];
+        let paramIndex = 2;
+        // - filter:seq -
+        if (opts?.after !== undefined) {
+            query += ` AND seq > $${paramIndex++}`;
+            values.push(opts.after);
+        }
+        // - filter:kind -
+        if (opts?.kinds && opts.kinds.length > 0) {
+            query += ` AND kind = ANY($${paramIndex++})`;
+            values.push(opts.kinds);
+        }
+        // - order -
+        const order = opts?.order ?? "asc";
+        query += ` ORDER BY seq ${order.toUpperCase()}`;
+        // - limit -
+        if (opts?.limit !== undefined) {
+            query += ` LIMIT $${paramIndex++}`;
+            values.push(opts.limit);
+        }
+        const result = await this.db.query(query, values);
+        return result.rows.map((record) => ThreadEventRecordCodec.decode({
+            ...record,
+            // Normalize BIGINT (string) to number for zod schema
+            timestamp: Number(record.timestamp),
+        }));
+    }
+    /**
+     * Append events to the thread history.
+     *
+     * Semantics:
+     * - Guaranteed per-thread ordering via monotonically increasing `seq`
+     * - Idempotent on `(tid, event.id)`: duplicate ids MUST NOT create duplicate rows
+     * - Events maintain insertion order
+     *
+     * NOTE: Thread class manages monotonic seq and timestamp assignment, is the only entrypoint.
+     */
+    async append(events) {
+        if (events.length === 0)
+            return;
+        const records = events.map((e) => ThreadEventRecordCodec.encode(e));
+        const values = [];
+        const placeholders = [];
+        let index = 1;
+        for (const record of records) {
+            placeholders.push(`($${index++}, $${index++}, $${index++}, $${index++}, $${index++}, $${index++}::jsonb, $${index++}::jsonb)`);
+            values.push(record.id, record.tid, record.seq, record.kind, record.timestamp, record.data, record.metadata);
+        }
+        // insert with ON CONFLICT DO NOTHING for idempotency
+        await this.db.query(`INSERT INTO ${SCHEMA_NAME}.thread_events
+       (id, tid, seq, kind, timestamp, data, metadata)
+       VALUES ${placeholders.join(", ")}
+       ON CONFLICT (tid, id) DO NOTHING`, values);
+    }
+    /**
+     * Hydrate a Thread instance from a database record.
+     */
+    hydrate(thread) {
+        assert(this.registries, "registries should be bound to storage in Kernl constructor");
+        const { record, events = [] } = thread;
+        const agent = this.registries.agents.get(record.agent_id);
+        const model = this.registries.models.get(record.model);
+        if (!agent || !model) {
+            throw new Error(`Thread ${record.id} references non-existent agent/model (agent: ${record.agent_id}, model: ${record.model})`);
+        }
+        return new Thread({
+            agent,
+            history: events,
+            context: new Context(record.namespace, record.context),
+            model,
+            task: null, // TODO: load from TaskStore when it exists
+            tid: record.id,
+            namespace: record.namespace,
+            tick: record.tick,
+            state: record.state,
+            metadata: record.metadata,
+            createdAt: new Date(record.created_at),
+            updatedAt: new Date(record.updated_at),
+            storage: this, // pass storage reference so resumed thread can persist
+            persisted: true,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kernl-sdk/pg",
+  "version": "0.1.9",
+  "description": "PostgreSQL storage adapter for kernl",
+  "keywords": [
+    "kernl",
+    "storage",
+    "postgresql",
+    "postgres"
+  ],
+  "author": "dremnik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kernl-sdk/kernl.git",
+    "directory": "packages/storage/pg"
+  },
+  "homepage": "https://github.com/kernl-sdk/kernl#readme",
+  "bugs": {
+    "url": "https://github.com/kernl-sdk/kernl/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@types/pg": "^8.15.6",
+    "tsc-alias": "^1.8.10",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.8",
+    "@kernl-sdk/protocol": "^0.2.4"
+  },
+  "dependencies": {
+    "pg": "^8.16.3",
+    "kernl": "^0.6.0",
+    "@kernl-sdk/shared": "^0.1.5",
+    "@kernl-sdk/storage": "0.1.9"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:run": "vitest run"
+  }
+}