@kuralle-agents/redis-store 0.14.0 → 0.15.0

package/dist/RedisSessionStore.d.ts

@@ -2,6 +2,15 @@ import { type AuditListOptions, type ConversationAuditEntry, type Session, type
 type RedisResult<T = unknown> = T | null;
 type RedisCommand = (...args: any[]) => Promise<RedisResult>;
 export type RedisClientLike = {
+    /**
+     * Atomic script execution, normalised.
+     *
+     * Every real client exposes `eval`, but with a different argument shape (ioredis takes
+     * positional `numKeys`, node-redis takes an options object, Upstash takes two arrays).
+     * The adapters in `adapters.ts` map their client's native form onto this one, so the
+     * store can express an atomic compare-and-swap without knowing which client it holds.
+     */
+    evalScript?: (script: string, keys: string[], args: string[]) => Promise<unknown>;
     get?: RedisCommand;
     set?: RedisCommand;
     del?: RedisCommand;

package/dist/RedisSessionStore.js

@@ -32,6 +32,32 @@ const reviveSession = (raw) => {
     ]));
     return session;
 };
+/**
+ * Atomic compare-and-swap for one session, run server-side so nothing can interleave.
+ *
+ * The previous implementation did GET -> compare in JS -> SET: three round-trips, so two
+ * clients could both read version 5, both pass the check, and both write. The check read
+ * as protection and provided none. (Our test double hid this by performing the version
+ * check inside its own `set`, which a real Redis does not do.)
+ *
+ * Returns -1 on success, otherwise the version actually stored, so the caller can raise a
+ * truthful StaleWriteError. Versions only ever increase from 0, so -1 is a safe sentinel.
+ *
+ * The stored version is read out of the session payload rather than a companion key, so
+ * this works against data written by earlier versions with no migration.
+ */
+const CAS_SCRIPT = `
+local cur = redis.call('GET', KEYS[1])
+local stored = 0
+if cur then
+  local ok, obj = pcall(cjson.decode, cur)
+  if ok and obj and obj.version then stored = tonumber(obj.version) or 0 end
+end
+if stored ~= tonumber(ARGV[2]) then return stored end
+redis.call('SET', KEYS[1], ARGV[1])
+if tonumber(ARGV[3]) > 0 then redis.call('EXPIRE', KEYS[1], ARGV[3]) end
+return -1
+`;
 export class RedisSessionStore {
     client;
     prefix;
@@ -75,25 +101,32 @@ export class RedisSessionStore {
         }
     }
     async save(session) {
+        const evalScript = this.client.evalScript;
+        if (typeof evalScript !== 'function') {
+            throw new Error('RedisSessionStore requires a client that can run Lua scripts. Wrap yours with ' +
+                'fromIORedis / fromNodeRedis / fromUpstash from @kuralle-agents/redis-store, or ' +
+                'supply `evalScript`. Without atomic compare-and-swap a concurrent write is ' +
+                'silently lost, which corrupts the durable journal.');
+        }
+        // Read only to reconcile the conversation index below — never to gate the write.
+        // The version check that actually guards the write happens inside the Lua script.
         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);
-        await setExpiration(this.client, key, this.sessionTtlSeconds);
+        const outcome = Number(await evalScript.call(this.client, CAS_SCRIPT, [key], [
+            payload,
+            String(expectedVersion),
+            String(this.sessionTtlSeconds ?? 0),
+        ]));
+        if (outcome !== -1) {
+            session.version = expectedVersion; // leave the caller's object as it found it
+            throw new StaleWriteError(session.id, expectedVersion, outcome);
+        }
         await addMembers(this.client, this.sessionIndexKey(), session.id);
         if (session.userId) {
             await addMembers(this.client, this.userIndexKey(session.userId), session.id);

package/dist/adapters.d.ts

@@ -1,6 +1,9 @@
 import { RedisSessionStore } from './RedisSessionStore.js';
 import type { RedisClientLike, RedisStoreOptions } from './RedisSessionStore.js';
 export type RedisAdapterOptions = Omit<RedisStoreOptions, 'client'>;
+/** Upstash REST: `eval(script, keys, args)`. */
 export declare const fromUpstash: (client: RedisClientLike, options?: RedisAdapterOptions) => RedisSessionStore;
+/** node-redis v4+: `eval(script, { keys, arguments })`. */
 export declare const fromNodeRedis: (client: RedisClientLike, options?: RedisAdapterOptions) => RedisSessionStore;
+/** ioredis: `eval(script, numKeys, ...keys, ...args)`. */
 export declare const fromIORedis: (client: RedisClientLike, options?: RedisAdapterOptions) => RedisSessionStore;

package/dist/adapters.js

@@ -1,5 +1,12 @@
 import { RedisSessionStore } from './RedisSessionStore.js';
+const withEvalScript = (client, shape) => ({
+    ...client,
+    evalScript: (script, keys, args) => shape(client, script, keys, args),
+});
 const createStore = (client, options) => new RedisSessionStore({ client, ...(options ?? {}) });
-export const fromUpstash = (client, options) => createStore(client, options);
-export const fromNodeRedis = (client, options) => createStore(client, options);
-export const fromIORedis = (client, options) => createStore(client, options);
+/** Upstash REST: `eval(script, keys, args)`. */
+export const fromUpstash = (client, options) => createStore(withEvalScript(client, (c, script, keys, args) => c.eval(script, keys, args)), options);
+/** node-redis v4+: `eval(script, { keys, arguments })`. */
+export const fromNodeRedis = (client, options) => createStore(withEvalScript(client, (c, script, keys, args) => c.eval(script, { keys, arguments: args })), options);
+/** ioredis: `eval(script, numKeys, ...keys, ...args)`. */
+export const fromIORedis = (client, options) => createStore(withEvalScript(client, (c, script, keys, args) => c.eval(script, keys.length, ...keys, ...args)), options);

package/dist/redisHelpers.d.ts

@@ -1,5 +1,5 @@
 import type { RedisClientLike } from './RedisSessionStore.js';
-export declare const callCommand: <T>(client: RedisClientLike, names: Array<keyof RedisClientLike>, ...args: unknown[]) => Promise<T>;
+export declare const callCommand: <T>(client: RedisClientLike, names: Array<Exclude<keyof RedisClientLike, "evalScript">>, ...args: unknown[]) => Promise<T>;
 export declare const getMembers: (client: RedisClientLike, key: string) => Promise<string[]>;
 export declare const addMembers: (client: RedisClientLike, key: string, ...members: string[]) => Promise<void>;
 export declare const removeMembers: (client: RedisClientLike, key: string, ...members: string[]) => Promise<void>;

package/dist/redisHelpers.js

@@ -1,4 +1,7 @@
-export const callCommand = async (client, names, ...args) => {
+export const callCommand = async (client, 
+// `evalScript` is our normalised script hook, not a Redis command — it has its own
+// signature and is called directly, never through this generic dispatcher.
+names, ...args) => {
     for (const name of names) {
         const fn = client[name];
         if (typeof fn === 'function') {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/redis-store"
   },
-  "version": "0.14.0",
+  "version": "0.15.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.14.0"
+    "@kuralle-agents/core": "0.15.0"
   },
   "peerDependencies": {
-    "@kuralle-agents/core": "0.14.0",
-    "@kuralle-agents/rag": "0.14.0"
+    "@kuralle-agents/core": "0.x",
+    "@kuralle-agents/rag": "0.x"
   },
   "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.14.0"
+    "@kuralle-agents/rag": "0.15.0"
   },
   "publishConfig": {
     "access": "public"