@kuralle-agents/redis-store 0.12.0 → 0.14.0

package/README.md

@@ -17,6 +17,7 @@ Three backend implementations — sessions, long-term memory, and vector search
 **Key exports:**
 
 - **`RedisSessionStore`** — `SessionStore` implementation for durable session persistence.
+- **`RedisTraceStore`** — independent native trace persistence and read API.
 - **`RedisMemoryService`** — `MemoryService` implementation for cross-session long-term memory.
 - **`RedisPersistentMemoryStore`** — `PersistentMemoryStore` for durable USER/MEMORY markdown blocks.
 - **`RedisVectorStore`** — `VectorStoreCore` implementation for vector similarity search.
@@ -38,6 +39,21 @@ const runtime = createRuntime({
 });
 ```
 
+## Trace store
+
+```ts
+import { RedisTraceStore } from '@kuralle-agents/redis-store';
+
+const traceStore = new RedisTraceStore({ client, traceTtlSeconds: 604800 });
+const runtime = createRuntime({
+  agents: [agent],
+  defaultAgentId: 'support',
+  tracing: { store: traceStore },
+});
+```
+
+Trace keys use a separate `trace`/`traces` namespace from sessions.
+
 ## Client adapters
 
 **node-redis:**

package/dist/RedisSessionStore.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';
 type RedisResult<T = unknown> = T | null;
 type RedisCommand = (...args: any[]) => Promise<RedisResult>;
 export type RedisClientLike = {

package/dist/RedisSessionStore.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { StaleWriteError, } from '@kuralle-agents/core';
 import { callCommand, getMembers, addMembers, removeMembers, setExpiration, setScore, removeScore, rangeByScore, removeByScore, } from './redisHelpers.js';
 const defaultPrefix = 'kuralle';
 const reviveSession = (raw) => {
@@ -75,9 +76,20 @@ export class RedisSessionStore {
     }
     async save(session) {
         const previous = await this.get(session.id);
+        const expectedVersion = session.version ?? 0;
+        if (previous !== null) {
+            const storedVersion = previous.version ?? 0;
+            if (storedVersion !== expectedVersion) {
+                throw new StaleWriteError(session.id, expectedVersion, storedVersion);
+            }
+        }
+        else if (expectedVersion !== 0) {
+            throw new StaleWriteError(session.id, expectedVersion, 0);
+        }
         session.updatedAt = new Date();
         session.conversationId = session.conversationId ?? session.id;
         session.channelId = session.channelId ?? 'web';
+        session.version = expectedVersion + 1;
         const key = this.sessionKey(session.id);
         const payload = JSON.stringify(session);
         await callCommand(this.client, ['set'], key, payload);

package/dist/RedisTraceStore.d.ts

@@ -0,0 +1,21 @@
+import type { AgentSpan, AgentTrace, TraceListWindow, TraceStore } from '@kuralle-agents/core';
+import type { RedisClientLike } from './RedisSessionStore.js';
+export interface RedisTraceStoreOptions {
+    client: RedisClientLike;
+    prefix?: string;
+    traceTtlSeconds?: number;
+}
+export declare class RedisTraceStore implements TraceStore {
+    private readonly options;
+    private readonly prefix;
+    private queue;
+    constructor(options: RedisTraceStoreOptions);
+    write(span: AgentSpan): Promise<void>;
+    putSpan(span: AgentSpan): Promise<void>;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string, window?: TraceListWindow): Promise<AgentTrace[]>;
+    flush(): Promise<void>;
+    private putSpanDirect;
+    private traceKey;
+    private sessionIndexKey;
+}

package/dist/RedisTraceStore.js

@@ -0,0 +1,53 @@
+import { traceFromSpans } from '@kuralle-agents/core/tracing';
+import { callCommand, rangeByScore, setExpiration, setScore } from './redisHelpers.js';
+export class RedisTraceStore {
+    options;
+    prefix;
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.prefix = options.prefix ?? 'kuralle';
+    }
+    write(span) { return this.putSpan(span); }
+    putSpan(span) {
+        const operation = this.queue.then(() => this.putSpanDirect(span));
+        this.queue = operation.catch(() => { });
+        return operation;
+    }
+    async getTrace(traceId) {
+        await this.queue;
+        const raw = await callCommand(this.options.client, ['get'], this.traceKey(traceId));
+        if (!raw)
+            return null;
+        const spans = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        return traceFromSpans(spans);
+    }
+    async listTraces(sessionId, window) {
+        await this.queue;
+        const min = window?.from?.getTime() ?? '-inf';
+        const max = window?.to?.getTime() ?? '+inf';
+        const ids = (await rangeByScore(this.options.client, this.sessionIndexKey(sessionId), min, max)).reverse();
+        const selected = window?.limit === undefined ? ids : ids.slice(0, window.limit);
+        const traces = await Promise.all(selected.map((id) => this.getTrace(id)));
+        return traces.filter((trace) => trace !== null);
+    }
+    flush() { return this.queue; }
+    async putSpanDirect(span) {
+        const key = this.traceKey(span.traceId);
+        const raw = await callCommand(this.options.client, ['get'], key);
+        const spans = raw
+            ? (typeof raw === 'string' ? JSON.parse(raw) : raw)
+            : [];
+        const index = spans.findIndex((entry) => entry.spanId === span.spanId);
+        if (index >= 0)
+            spans[index] = span;
+        else
+            spans.push(span);
+        await callCommand(this.options.client, ['set'], key, JSON.stringify(spans));
+        await setExpiration(this.options.client, key, this.options.traceTtlSeconds);
+        await setScore(this.options.client, this.sessionIndexKey(span.attributes.sessionId), Math.min(...spans.map((entry) => entry.startTime)), span.traceId);
+        await setExpiration(this.options.client, this.sessionIndexKey(span.attributes.sessionId), this.options.traceTtlSeconds);
+    }
+    traceKey(traceId) { return `${this.prefix}:trace:${traceId}`; }
+    sessionIndexKey(sessionId) { return `${this.prefix}:traces:${sessionId}`; }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { RedisSessionStore } from './RedisSessionStore.js';
 export type { RedisClientLike, RedisStoreOptions } from './RedisSessionStore.js';
+export { RedisTraceStore } from './RedisTraceStore.js';
+export type { RedisTraceStoreOptions } from './RedisTraceStore.js';
 export { RedisMemoryService } from './RedisMemoryService.js';
 export type { RedisMemoryStoreOptions } from './RedisMemoryService.js';
 export { RedisPersistentMemoryStore } from './RedisPersistentMemoryStore.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { RedisSessionStore } from './RedisSessionStore.js';
+export { RedisTraceStore } from './RedisTraceStore.js';
 export { RedisMemoryService } from './RedisMemoryService.js';
 export { RedisPersistentMemoryStore } from './RedisPersistentMemoryStore.js';
 export { fromUpstash, fromNodeRedis, fromIORedis } from './adapters.js';

package/package.json

@@ -4,9 +4,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
-    "directory": "packages/kuralle-redis-store"
+    "directory": "packages/redis-store"
   },
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Redis-backed SessionStore for Kuralle (supports Upstash and common Redis clients)",
   "type": "module",
   "main": "dist/index.js",
@@ -18,11 +18,11 @@
     }
   },
   "dependencies": {
-    "@kuralle-agents/core": "0.12.0"
+    "@kuralle-agents/core": "0.14.0"
   },
   "peerDependencies": {
-    "@kuralle-agents/rag": "0.12.0",
-    "@kuralle-agents/core": "0.12.0"
+    "@kuralle-agents/core": "0.14.0",
+    "@kuralle-agents/rag": "0.14.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.0",
@@ -33,7 +33,7 @@
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
     "zod": "^4.0.0",
-    "@kuralle-agents/rag": "0.12.0"
+    "@kuralle-agents/rag": "0.14.0"
   },
   "publishConfig": {
     "access": "public"