@agorio/session-redis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agorio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @agorio/session-redis
+
+Redis-backed `SessionStorage` for the [Agorio SDK](https://www.npmjs.com/package/@agorio/sdk). Durable agent session persistence across process restarts.
+
+```bash
+npm install @agorio/sdk @agorio/session-redis ioredis
+```
+
+```ts
+import Redis from 'ioredis';
+import { ShoppingAgent } from '@agorio/sdk';
+import { RedisSessionStorage } from '@agorio/session-redis';
+
+const storage = new RedisSessionStorage({
+  redis: new Redis(process.env.REDIS_URL!),
+  keyPrefix: 'agorio:sessions:',
+  ttlSeconds: 60 * 60 * 24 * 30, // 30-day expiry
+});
+
+const agent = new ShoppingAgent({
+  llm,
+  sessionStorage: storage,
+  sessionId: 'po-1234',          // resumes from this session if it exists
+  sessionCustomerId: 'cust-acme',
+});
+
+await agent.run('Order 100 ergonomic chairs from preferred vendors');
+// If the process crashes mid-run, construct the same agent again — it picks
+// up from the last persisted iteration.
+```
+
+## Why durable sessions?
+
+Procurement agents pause for human approval. A `submit_payment` over $1k might wait hours for a reviewer to click "approve" — the agent must survive a process restart in that window. `RedisSessionStorage` is the production answer; `MemorySessionStorage` and `FileSessionStorage` (shipped in-tree with the SDK) are the dev / single-process answers.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @agorio/session-redis — Redis-backed SessionStorage.
+ *
+ *   import Redis from 'ioredis';
+ *   import { RedisSessionStorage } from '@agorio/session-redis';
+ *
+ *   const storage = new RedisSessionStorage({
+ *     redis: new Redis(process.env.REDIS_URL!),
+ *     keyPrefix: 'agorio:sessions:',
+ *     ttlSeconds: 60 * 60 * 24 * 30, // 30 days
+ *   });
+ *
+ *   const agent = new ShoppingAgent({ llm, sessionStorage: storage, sessionId: 'po-1234' });
+ *
+ * The storage layout is one HSET-style JSON document per session, plus
+ * a secondary index `<prefix>by_customer:<customerId>` (a SET of session IDs)
+ * for filtered list() queries.
+ */
+import type { SessionState, SessionStorage } from '@agorio/sdk';
+/** Minimal Redis client surface — ioredis and node-redis v4 both satisfy this. */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    del(...keys: string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    mget(...keys: string[]): Promise<Array<string | null>>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    expire?(key: string, seconds: number): Promise<number>;
+}
+export interface RedisSessionStorageOptions {
+    redis: RedisClientLike;
+    /** Key prefix for session documents. Default: `agorio:sessions:`. */
+    keyPrefix?: string;
+    /** Optional per-session TTL in seconds. Omit for no expiry. */
+    ttlSeconds?: number;
+}
+export declare class RedisSessionStorage implements SessionStorage {
+    private readonly redis;
+    private readonly keyPrefix;
+    private readonly ttlSeconds?;
+    constructor(options: RedisSessionStorageOptions);
+    save(state: SessionState): Promise<void>;
+    load(sessionId: string): Promise<SessionState | null>;
+    list(filter?: {
+        customerId?: string;
+        before?: Date;
+    }): Promise<SessionState[]>;
+    delete(sessionId: string): Promise<void>;
+    private sessionKey;
+    private customerIndexKey;
+}

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * @agorio/session-redis — Redis-backed SessionStorage.
+ *
+ *   import Redis from 'ioredis';
+ *   import { RedisSessionStorage } from '@agorio/session-redis';
+ *
+ *   const storage = new RedisSessionStorage({
+ *     redis: new Redis(process.env.REDIS_URL!),
+ *     keyPrefix: 'agorio:sessions:',
+ *     ttlSeconds: 60 * 60 * 24 * 30, // 30 days
+ *   });
+ *
+ *   const agent = new ShoppingAgent({ llm, sessionStorage: storage, sessionId: 'po-1234' });
+ *
+ * The storage layout is one HSET-style JSON document per session, plus
+ * a secondary index `<prefix>by_customer:<customerId>` (a SET of session IDs)
+ * for filtered list() queries.
+ */
+export class RedisSessionStorage {
+    redis;
+    keyPrefix;
+    ttlSeconds;
+    constructor(options) {
+        if (!options.redis)
+            throw new Error('RedisSessionStorage: `redis` client is required');
+        this.redis = options.redis;
+        this.keyPrefix = options.keyPrefix ?? 'agorio:sessions:';
+        this.ttlSeconds = options.ttlSeconds;
+    }
+    async save(state) {
+        const key = this.sessionKey(state.sessionId);
+        const json = JSON.stringify(state);
+        if (this.ttlSeconds && this.ttlSeconds > 0) {
+            await this.redis.set(key, json, 'EX', this.ttlSeconds);
+        }
+        else {
+            await this.redis.set(key, json);
+        }
+        if (state.customerId) {
+            await this.redis.sadd(this.customerIndexKey(state.customerId), state.sessionId);
+        }
+    }
+    async load(sessionId) {
+        const raw = await this.redis.get(this.sessionKey(sessionId));
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    async list(filter) {
+        let sessionIds;
+        if (filter?.customerId) {
+            sessionIds = await this.redis.smembers(this.customerIndexKey(filter.customerId));
+        }
+        else {
+            const keys = await this.redis.keys(`${this.keyPrefix}*`);
+            const indexPrefix = `${this.keyPrefix}by_customer:`;
+            sessionIds = keys
+                .filter(k => !k.startsWith(indexPrefix))
+                .map(k => k.slice(this.keyPrefix.length));
+        }
+        if (sessionIds.length === 0)
+            return [];
+        const docs = await this.redis.mget(...sessionIds.map(id => this.sessionKey(id)));
+        const states = [];
+        for (const doc of docs) {
+            if (!doc)
+                continue;
+            const state = JSON.parse(doc);
+            if (filter?.before && new Date(state.savedAt) >= filter.before)
+                continue;
+            states.push(state);
+        }
+        return states;
+    }
+    async delete(sessionId) {
+        const existing = await this.load(sessionId);
+        await this.redis.del(this.sessionKey(sessionId));
+        if (existing?.customerId) {
+            await this.redis.srem(this.customerIndexKey(existing.customerId), sessionId);
+        }
+    }
+    sessionKey(id) {
+        return `${this.keyPrefix}${id}`;
+    }
+    customerIndexKey(customerId) {
+        return `${this.keyPrefix}by_customer:${customerId}`;
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@agorio/session-redis",
+  "version": "0.1.0",
+  "description": "Redis-backed SessionStorage for Agorio SDK — durable agent session persistence across process restarts",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@agorio/sdk": "^0.7.0",
+    "ioredis": "^5.4.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@agorio/sdk": "file:../..",
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.17"
+  },
+  "keywords": [
+    "agorio",
+    "session",
+    "redis",
+    "ioredis",
+    "shopping-agent",
+    "ai-agent",
+    "persistence"
+  ],
+  "author": "Agorio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nolpak14/agorio",
+    "directory": "packages/session-redis"
+  }
+}