@kuralle-agents/postgres-store 0.12.0 → 0.13.0

package/README.md

@@ -17,6 +17,7 @@ Three backend implementations — sessions, long-term memory, and pgvector simil
 **Key exports:**
 
 - **`PostgresSessionStore`** — `SessionStore` implementation for durable session persistence.
+- **`PostgresTraceStore`** — independent native trace persistence and read API.
 - **`PostgresMemoryService`** — `MemoryService` implementation for cross-session long-term memory.
 - **`PostgresPersistentMemoryStore`** — `PersistentMemoryStore` for durable USER/MEMORY markdown blocks.
 - **`PgVectorStore`** — `VectorStoreCore` implementation using pgvector for similarity search.
@@ -38,6 +39,21 @@ const runtime = createRuntime({
 });
 ```
 
+## Trace store
+
+```ts
+import { PostgresTraceStore } from '@kuralle-agents/postgres-store';
+
+const traceStore = new PostgresTraceStore({ client: pool, retentionMs: 604_800_000 });
+const runtime = createRuntime({
+  agents: [agent],
+  defaultAgentId: 'support',
+  tracing: { store: traceStore },
+});
+```
+
+Spans live in the separate `kuralle_trace_spans` table. Set `tableName` to override it.
+
 ## Store options
 
 - `tableName` (default: `'kuralle_sessions'`) — table to store sessions.

package/dist/PostgresSessionStore.d.ts

@@ -1,4 +1,4 @@
-import type { AuditListOptions, ConversationAuditEntry, Session, SessionStore } from '@kuralle-agents/core';
+import { type AuditListOptions, type ConversationAuditEntry, type Session, type SessionStore } from '@kuralle-agents/core';
 import type { QueryResult } from 'pg';
 type PostgresClient = {
     query: (text: string, params?: unknown[]) => Promise<QueryResult>;

package/dist/PostgresSessionStore.js

@@ -1,3 +1,4 @@
+import { StaleWriteError, } from '@kuralle-agents/core';
 const defaultTable = 'kuralle_sessions';
 const defaultAuditTable = 'audit_entries';
 const reviveSession = (raw) => {
@@ -56,8 +57,10 @@ export class PostgresSessionStore {
         conversation_id TEXT NOT NULL DEFAULT '',
         channel_id TEXT NOT NULL DEFAULT 'web',
         data JSONB NOT NULL,
+        version INTEGER NOT NULL DEFAULT 0,
         updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
       )`);
+        await this.client.query(`ALTER TABLE ${this.table} ADD COLUMN IF NOT EXISTS version INTEGER NOT NULL DEFAULT 0`);
         await this.client.query(`ALTER TABLE ${this.table} ADD COLUMN IF NOT EXISTS conversation_id TEXT NOT NULL DEFAULT ''`);
         await this.client.query(`ALTER TABLE ${this.table} ADD COLUMN IF NOT EXISTS channel_id TEXT NOT NULL DEFAULT 'web'`);
         await this.client.query(`UPDATE ${this.table} SET conversation_id = id WHERE conversation_id = ''`);
@@ -74,14 +77,17 @@ export class PostgresSessionStore {
     }
     async get(id) {
         await this.ready;
-        const result = await this.client.query(`SELECT data FROM ${this.table} WHERE id = $1`, [id]);
+        const result = await this.client.query(`SELECT data, version FROM ${this.table} WHERE id = $1`, [id]);
         if (!result.rows.length) {
             return null;
         }
         const raw = result.rows[0]?.data;
+        const version = result.rows[0]?.version;
         try {
             const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
-            return reviveSession(parsed);
+            const session = reviveSession(parsed);
+            session.version = version ?? session.version ?? 0;
+            return session;
         }
         catch (error) {
             console.error('Failed to parse session data from Postgres', error);
@@ -93,11 +99,37 @@ export class PostgresSessionStore {
         session.updatedAt = new Date();
         session.conversationId = session.conversationId ?? session.id;
         session.channelId = session.channelId ?? 'web';
+        const expectedVersion = session.version ?? 0;
         const data = JSON.stringify(session);
-        await this.client.query(`INSERT INTO ${this.table} (id, user_id, conversation_id, channel_id, data, updated_at)
-       VALUES ($1, $2, $3, $4, $5::jsonb, NOW())
-       ON CONFLICT (id)
-       DO UPDATE SET data = EXCLUDED.data, user_id = EXCLUDED.user_id, conversation_id = EXCLUDED.conversation_id, channel_id = EXCLUDED.channel_id, updated_at = NOW()`, [session.id, session.userId ?? null, session.conversationId, session.channelId, data]);
+        const update = await this.client.query(`UPDATE ${this.table}
+       SET data = $5::jsonb,
+           user_id = $2,
+           conversation_id = $3,
+           channel_id = $4,
+           version = version + 1,
+           updated_at = NOW()
+       WHERE id = $1 AND version = $6`, [
+            session.id,
+            session.userId ?? null,
+            session.conversationId,
+            session.channelId,
+            data,
+            expectedVersion,
+        ]);
+        if ((update.rowCount ?? 0) > 0) {
+            return;
+        }
+        if (expectedVersion === 0) {
+            const insert = await this.client.query(`INSERT INTO ${this.table} (id, user_id, conversation_id, channel_id, data, version, updated_at)
+         VALUES ($1, $2, $3, $4, $5::jsonb, 1, NOW())
+         ON CONFLICT (id) DO NOTHING`, [session.id, session.userId ?? null, session.conversationId, session.channelId, data]);
+            if ((insert.rowCount ?? 0) > 0) {
+                return;
+            }
+        }
+        const current = await this.client.query(`SELECT version FROM ${this.table} WHERE id = $1`, [session.id]);
+        const actual = current.rows[0]?.version ?? 0;
+        throw new StaleWriteError(session.id, expectedVersion, actual);
     }
     async delete(id) {
         await this.ready;

package/dist/PostgresTraceStore.d.ts

@@ -0,0 +1,24 @@
+import type { AgentSpan, AgentTrace, TraceListWindow, TraceStore } from '@kuralle-agents/core';
+import type { QueryResult } from 'pg';
+type PostgresClient = {
+    query: (text: string, params?: unknown[]) => Promise<QueryResult>;
+};
+export interface PostgresTraceStoreOptions {
+    client: PostgresClient;
+    tableName?: string;
+    autoMigrate?: boolean;
+    retentionMs?: number;
+}
+export declare class PostgresTraceStore implements TraceStore {
+    private readonly options;
+    private readonly table;
+    private readonly ready;
+    constructor(options: PostgresTraceStoreOptions);
+    write(span: AgentSpan): Promise<void>;
+    putSpan(span: AgentSpan): Promise<void>;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string, window?: TraceListWindow): Promise<AgentTrace[]>;
+    cleanup(maxAgeMs: number): Promise<number>;
+    private init;
+}
+export {};

package/dist/PostgresTraceStore.js

@@ -0,0 +1,68 @@
+import { traceFromSpans } from '@kuralle-agents/core/tracing';
+export class PostgresTraceStore {
+    options;
+    table;
+    ready;
+    constructor(options) {
+        this.options = options;
+        this.table = normalizeTableName(options.tableName ?? 'kuralle_trace_spans');
+        this.ready = options.autoMigrate === false ? Promise.resolve() : this.init();
+    }
+    write(span) { return this.putSpan(span); }
+    async putSpan(span) {
+        await this.ready;
+        await this.options.client.query(`INSERT INTO ${this.table} (trace_id, span_id, session_id, started_at, payload)
+       VALUES ($1, $2, $3, $4, $5::jsonb)
+       ON CONFLICT (trace_id, span_id) DO UPDATE SET payload = EXCLUDED.payload, started_at = EXCLUDED.started_at`, [span.traceId, span.spanId, span.attributes.sessionId, new Date(span.startTime), JSON.stringify(span)]);
+        if (this.options.retentionMs !== undefined)
+            await this.cleanup(this.options.retentionMs);
+    }
+    async getTrace(traceId) {
+        await this.ready;
+        const result = await this.options.client.query(`SELECT payload FROM ${this.table} WHERE trace_id = $1 ORDER BY started_at ASC`, [traceId]);
+        return traceFromSpans(result.rows.map(parseSpan));
+    }
+    async listTraces(sessionId, window) {
+        await this.ready;
+        const params = [sessionId];
+        const having = [];
+        if (window?.from) {
+            params.push(window.from);
+            having.push(`MIN(started_at) >= $${params.length}`);
+        }
+        if (window?.to) {
+            params.push(window.to);
+            having.push(`MIN(started_at) <= $${params.length}`);
+        }
+        params.push(window?.limit ?? 100);
+        const ids = await this.options.client.query(`SELECT trace_id, MIN(started_at) AS trace_started_at FROM ${this.table}
+       WHERE session_id = $1 GROUP BY trace_id ${having.length > 0 ? `HAVING ${having.join(' AND ')}` : ''}
+       ORDER BY trace_started_at DESC LIMIT $${params.length}`, params);
+        const traces = await Promise.all(ids.rows.map((row) => this.getTrace(String(row.trace_id))));
+        return traces.filter((trace) => trace !== null);
+    }
+    async cleanup(maxAgeMs) {
+        await this.ready;
+        const result = await this.options.client.query(`DELETE FROM ${this.table} WHERE trace_id IN (
+        SELECT trace_id FROM ${this.table} GROUP BY trace_id HAVING MIN(started_at) < $1
+      )`, [new Date(Date.now() - maxAgeMs)]);
+        return result.rowCount ?? 0;
+    }
+    async init() {
+        await this.options.client.query(`CREATE TABLE IF NOT EXISTS ${this.table} (
+        trace_id TEXT NOT NULL, span_id TEXT NOT NULL, session_id TEXT NOT NULL,
+        started_at TIMESTAMPTZ NOT NULL, payload JSONB NOT NULL,
+        PRIMARY KEY (trace_id, span_id)
+      )`);
+        await this.options.client.query(`CREATE INDEX IF NOT EXISTS ${this.table.replace(/\./g, '_')}_session_started_idx
+       ON ${this.table} (session_id, started_at DESC)`);
+    }
+}
+function normalizeTableName(table) {
+    if (!/^[a-zA-Z0-9_.]+$/.test(table))
+        throw new Error(`Invalid table name: ${table}`);
+    return table;
+}
+function parseSpan(row) {
+    return (typeof row.payload === 'string' ? JSON.parse(row.payload) : row.payload);
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { PostgresSessionStore } from './PostgresSessionStore.js';
 export type { PostgresStoreOptions } from './PostgresSessionStore.js';
+export { PostgresTraceStore } from './PostgresTraceStore.js';
+export type { PostgresTraceStoreOptions } from './PostgresTraceStore.js';
 export { PostgresMemoryService } from './PostgresMemoryService.js';
 export type { PostgresMemoryStoreOptions } from './PostgresMemoryService.js';
 export { PostgresPersistentMemoryStore } from './PostgresPersistentMemoryStore.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { PostgresSessionStore } from './PostgresSessionStore.js';
+export { PostgresTraceStore } from './PostgresTraceStore.js';
 export { PostgresMemoryService } from './PostgresMemoryService.js';
 export { PostgresPersistentMemoryStore } from './PostgresPersistentMemoryStore.js';
 export { PgVectorStore } from './PgVectorStore.js';

package/package.json

@@ -4,9 +4,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
-    "directory": "packages/kuralle-postgres-store"
+    "directory": "packages/postgres-store"
   },
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "PostgreSQL-backed SessionStore for Kuralle",
   "type": "module",
   "main": "dist/index.js",
@@ -18,19 +18,19 @@
     }
   },
   "dependencies": {
-    "@kuralle-agents/core": "0.12.0"
+    "@kuralle-agents/core": "0.13.0"
   },
   "peerDependencies": {
     "pg": "^8.0.0",
-    "@kuralle-agents/core": "0.12.0",
-    "@kuralle-agents/rag": "0.12.0"
+    "@kuralle-agents/core": "0.13.0",
+    "@kuralle-agents/rag": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
     "@types/pg": "^8.11.0",
     "pg": "^8.11.0",
     "typescript": "^5.3.0",
-    "@kuralle-agents/rag": "0.12.0"
+    "@kuralle-agents/rag": "0.13.0"
   },
   "publishConfig": {
     "access": "public"