@mastra/redis 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,229 @@
 # @mastra/redis
 
+## 1.1.0
+
+### Minor Changes
+
+- Update peer dependencies to match core package version bump (1.0.5) ([#12557](https://github.com/mastra-ai/mastra/pull/12557))
+
+### Patch Changes
+
+- Add durable agents with resumable streams ([#12557](https://github.com/mastra-ai/mastra/pull/12557))
+
+  Durable agents make agent execution resilient to disconnections, crashes, and long-running operations.
+
+  ### The Problem
+
+  Standard agent streaming has two fragility points:
+  1. **Connection drops** - If a client disconnects mid-stream (network blip, browser refresh, mobile app backgrounded), all subsequent events are lost. The client has no way to "catch up" on what they missed.
+  2. **Long-running operations** - Agent loops with tool calls can take minutes. Holding an HTTP connection open that long is unreliable. If the server restarts or the connection times out, the work is lost.
+
+  ### The Solution
+
+  **Resumable streams** solve connection drops. Every event is cached with a sequential index. If a client disconnects at event 5, they can reconnect and request events starting from index 6. They receive cached events immediately, then continue with live events as they arrive.
+
+  **Durable execution** solves long-running operations. Instead of executing the agent loop directly in the HTTP request, execution happens in a workflow engine (built-in evented engine or Inngest). The HTTP request just subscribes to events. If the connection drops, execution continues. The client can reconnect anytime to observe progress.
+
+  ### Usage
+
+  Wrap any existing `Agent` with durability using factory functions:
+
+  ```typescript
+  import { Agent } from '@mastra/core/agent';
+  import { createDurableAgent } from '@mastra/core/agent/durable';
+
+  const agent = new Agent({
+    id: 'my-agent',
+    model: openai('gpt-4'),
+    instructions: 'You are helpful',
+  });
+
+  const durableAgent = createDurableAgent({ agent });
+  ```
+
+  **Factory functions for different execution strategies:**
+
+  | Factory                                  | Execution                           | Use Case                        |
+  | ---------------------------------------- | ----------------------------------- | ------------------------------- |
+  | `createDurableAgent({ agent })`          | Local, synchronous                  | Development, simple deployments |
+  | `createEventedAgent({ agent })`          | Fire-and-forget via workflow engine | Long-running operations         |
+  | `createInngestAgent({ agent, inngest })` | Inngest-powered                     | Production, distributed systems |
+
+  ### Resumable Streams
+
+  ```typescript
+  // Start streaming
+  const { runId, output } = await durableAgent.stream('Analyze this data...');
+
+  // Client disconnects at event 5...
+
+  // Reconnect and resume from where we left off
+  const { output: resumed } = await durableAgent.observe(runId, { offset: 6 });
+  // Receives events 6, 7, 8... from cache, then continues with live events
+  ```
+
+  ### PubSub and Cache
+
+  Durable agents use two infrastructure components:
+
+  | Component  | Purpose                                   | Default               |
+  | ---------- | ----------------------------------------- | --------------------- |
+  | **PubSub** | Real-time event delivery during streaming | `EventEmitterPubSub`  |
+  | **Cache**  | Stores events for replay on reconnection  | `InMemoryServerCache` |
+
+  When `stream()` is called, events flow through pubsub in real-time. The cache stores each event with a sequential index. When `observe()` is called, missed events replay from cache before continuing with live events.
+
+  **Configure via Mastra instance (recommended):**
+
+  ```typescript
+  const mastra = new Mastra({
+    cache: new RedisServerCache({ url: 'redis://...' }),
+    pubsub: new RedisPubSub({ url: 'redis://...' }),
+    agents: {
+      // Inherits cache and pubsub from Mastra
+      myAgent: createDurableAgent({ agent }),
+    },
+  });
+  ```
+
+  **Configure per-agent (overrides Mastra):**
+
+  ```typescript
+  const durableAgent = createDurableAgent({
+    agent,
+    cache: new RedisServerCache({ url: 'redis://...' }),
+    pubsub: new RedisPubSub({ url: 'redis://...' }),
+  });
+  ```
+
+  **Disable caching (streams won't be resumable):**
+
+  ```typescript
+  const durableAgent = createDurableAgent({ agent, cache: false });
+  ```
+
+  For single-instance deployments, the defaults work fine. For multi-instance deployments (load balancer, horizontal scaling), use Redis-backed implementations so any instance can serve reconnection requests.
+
+  ### Class Hierarchy
+  - `DurableAgent` extends `Agent` - base class with resumable streams
+  - `EventedAgent` extends `DurableAgent` - fire-and-forget execution
+  - `InngestAgent` extends `DurableAgent` - Inngest-powered execution
+
+- Updated dependencies [[`920c757`](https://github.com/mastra-ai/mastra/commit/920c75799c6bd71787d86deaf654a35af4c839ca), [`d587199`](https://github.com/mastra-ai/mastra/commit/d5871993c0371bde2b0717d6b47194755baa1443), [`1fe2533`](https://github.com/mastra-ai/mastra/commit/1fe2533c4382ca6858aac7c4b63e888c2eac6541), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
+  - @mastra/core@1.30.0
+
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- Update peer dependencies to match core package version bump (1.0.5) ([#12557](https://github.com/mastra-ai/mastra/pull/12557))
+
+### Patch Changes
+
+- Add durable agents with resumable streams ([#12557](https://github.com/mastra-ai/mastra/pull/12557))
+
+  Durable agents make agent execution resilient to disconnections, crashes, and long-running operations.
+
+  ### The Problem
+
+  Standard agent streaming has two fragility points:
+  1. **Connection drops** - If a client disconnects mid-stream (network blip, browser refresh, mobile app backgrounded), all subsequent events are lost. The client has no way to "catch up" on what they missed.
+  2. **Long-running operations** - Agent loops with tool calls can take minutes. Holding an HTTP connection open that long is unreliable. If the server restarts or the connection times out, the work is lost.
+
+  ### The Solution
+
+  **Resumable streams** solve connection drops. Every event is cached with a sequential index. If a client disconnects at event 5, they can reconnect and request events starting from index 6. They receive cached events immediately, then continue with live events as they arrive.
+
+  **Durable execution** solves long-running operations. Instead of executing the agent loop directly in the HTTP request, execution happens in a workflow engine (built-in evented engine or Inngest). The HTTP request just subscribes to events. If the connection drops, execution continues. The client can reconnect anytime to observe progress.
+
+  ### Usage
+
+  Wrap any existing `Agent` with durability using factory functions:
+
+  ```typescript
+  import { Agent } from '@mastra/core/agent';
+  import { createDurableAgent } from '@mastra/core/agent/durable';
+
+  const agent = new Agent({
+    id: 'my-agent',
+    model: openai('gpt-4'),
+    instructions: 'You are helpful',
+  });
+
+  const durableAgent = createDurableAgent({ agent });
+  ```
+
+  **Factory functions for different execution strategies:**
+
+  | Factory                                  | Execution                           | Use Case                        |
+  | ---------------------------------------- | ----------------------------------- | ------------------------------- |
+  | `createDurableAgent({ agent })`          | Local, synchronous                  | Development, simple deployments |
+  | `createEventedAgent({ agent })`          | Fire-and-forget via workflow engine | Long-running operations         |
+  | `createInngestAgent({ agent, inngest })` | Inngest-powered                     | Production, distributed systems |
+
+  ### Resumable Streams
+
+  ```typescript
+  // Start streaming
+  const { runId, output } = await durableAgent.stream('Analyze this data...');
+
+  // Client disconnects at event 5...
+
+  // Reconnect and resume from where we left off
+  const { output: resumed } = await durableAgent.observe(runId, { offset: 6 });
+  // Receives events 6, 7, 8... from cache, then continues with live events
+  ```
+
+  ### PubSub and Cache
+
+  Durable agents use two infrastructure components:
+
+  | Component  | Purpose                                   | Default               |
+  | ---------- | ----------------------------------------- | --------------------- |
+  | **PubSub** | Real-time event delivery during streaming | `EventEmitterPubSub`  |
+  | **Cache**  | Stores events for replay on reconnection  | `InMemoryServerCache` |
+
+  When `stream()` is called, events flow through pubsub in real-time. The cache stores each event with a sequential index. When `observe()` is called, missed events replay from cache before continuing with live events.
+
+  **Configure via Mastra instance (recommended):**
+
+  ```typescript
+  const mastra = new Mastra({
+    cache: new RedisServerCache({ url: 'redis://...' }),
+    pubsub: new RedisPubSub({ url: 'redis://...' }),
+    agents: {
+      // Inherits cache and pubsub from Mastra
+      myAgent: createDurableAgent({ agent }),
+    },
+  });
+  ```
+
+  **Configure per-agent (overrides Mastra):**
+
+  ```typescript
+  const durableAgent = createDurableAgent({
+    agent,
+    cache: new RedisServerCache({ url: 'redis://...' }),
+    pubsub: new RedisPubSub({ url: 'redis://...' }),
+  });
+  ```
+
+  **Disable caching (streams won't be resumable):**
+
+  ```typescript
+  const durableAgent = createDurableAgent({ agent, cache: false });
+  ```
+
+  For single-instance deployments, the defaults work fine. For multi-instance deployments (load balancer, horizontal scaling), use Redis-backed implementations so any instance can serve reconnection requests.
+
+  ### Class Hierarchy
+  - `DurableAgent` extends `Agent` - base class with resumable streams
+  - `EventedAgent` extends `DurableAgent` - fire-and-forget execution
+  - `InngestAgent` extends `DurableAgent` - Inngest-powered execution
+
+- Updated dependencies [[`920c757`](https://github.com/mastra-ai/mastra/commit/920c75799c6bd71787d86deaf654a35af4c839ca), [`1fe2533`](https://github.com/mastra-ai/mastra/commit/1fe2533c4382ca6858aac7c4b63e888c2eac6541), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
+  - @mastra/core@1.30.0-alpha.1
+
 ## 1.0.2
 
 ### Patch Changes

package/dist/cache.d.ts

@@ -0,0 +1,42 @@
+import { MastraServerCache } from '@mastra/core/cache';
+export interface RedisClient {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ...args: unknown[]): Promise<unknown>;
+    llen(key: string): Promise<number>;
+    rpush(key: string, ...values: unknown[]): Promise<number>;
+    lrange(key: string, start: number, stop: number): Promise<unknown[]>;
+    del(...keys: string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<number | boolean>;
+    scan(cursor: string | number, ...args: unknown[]): Promise<[string | number, string[]]>;
+    incr(key: string): Promise<number>;
+}
+export interface RedisServerCacheOptions {
+    keyPrefix?: string;
+    ttlSeconds?: number;
+    setWithExpiry?: (client: RedisClient, key: string, value: unknown, seconds: number) => Promise<unknown>;
+    scanKeys?: (client: RedisClient, cursor: string | number, pattern: string, count: number) => Promise<[string | number, string[]]>;
+}
+export declare class RedisServerCache extends MastraServerCache {
+    private client;
+    private keyPrefix;
+    private ttlSeconds;
+    private setWithExpiry;
+    private scanKeys;
+    constructor(config: {
+        client: RedisClient;
+    }, options?: RedisServerCacheOptions);
+    private getKey;
+    private serialize;
+    private deserialize;
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    listLength(key: string): Promise<number>;
+    listPush(key: string, value: unknown): Promise<void>;
+    listFromTo(key: string, from: number, to?: number): Promise<unknown[]>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    increment(key: string): Promise<number>;
+}
+export declare const upstashPreset: Pick<RedisServerCacheOptions, 'setWithExpiry' | 'scanKeys'>;
+export declare const nodeRedisPreset: Pick<RedisServerCacheOptions, 'setWithExpiry' | 'scanKeys'>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-redis
 description: Documentation for @mastra/redis. Use when working with @mastra/redis APIs, configuration, or implementation.
 metadata:
   package: "@mastra/redis"
-  version: "1.0.2"
+  version: "1.1.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.2",
+  "version": "1.1.0",
   "package": "@mastra/redis",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -6,6 +6,7 @@ var storage = require('@mastra/core/storage');
 var crypto2 = require('crypto');
 var evals = require('@mastra/core/evals');
 var redis = require('redis');
+var cache = require('@mastra/core/cache');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -1795,10 +1796,111 @@ var RedisStore = class extends storage.MastraStorage {
     return `redis://${config.host}:${config.port || 6379}/${config.db || 0}`;
   }
 };
+var defaultSetWithExpiry = (client, key, value, seconds) => {
+  return client.set(key, value, "EX", seconds);
+};
+var defaultScanKeys = (client, cursor, pattern, count) => {
+  return client.scan(cursor, "MATCH", pattern, "COUNT", count);
+};
+var RedisServerCache = class extends cache.MastraServerCache {
+  client;
+  keyPrefix;
+  ttlSeconds;
+  setWithExpiry;
+  scanKeys;
+  constructor(config, options = {}) {
+    super({ name: "RedisServerCache" });
+    this.client = config.client;
+    this.keyPrefix = options.keyPrefix ?? "mastra:cache:";
+    this.ttlSeconds = options.ttlSeconds ?? 300;
+    this.setWithExpiry = options.setWithExpiry ?? defaultSetWithExpiry;
+    this.scanKeys = options.scanKeys ?? defaultScanKeys;
+  }
+  getKey(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  deserialize(value) {
+    if (typeof value === "string") {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    }
+    return value;
+  }
+  async get(key) {
+    const fullKey = this.getKey(key);
+    const value = await this.client.get(fullKey);
+    if (value === null) {
+      return null;
+    }
+    return this.deserialize(value);
+  }
+  async set(key, value) {
+    const fullKey = this.getKey(key);
+    const serialized = this.serialize(value);
+    if (this.ttlSeconds > 0) {
+      await this.setWithExpiry(this.client, fullKey, serialized, this.ttlSeconds);
+    } else {
+      await this.client.set(fullKey, serialized);
+    }
+  }
+  async listLength(key) {
+    const fullKey = this.getKey(key);
+    return this.client.llen(fullKey);
+  }
+  async listPush(key, value) {
+    const fullKey = this.getKey(key);
+    const serialized = this.serialize(value);
+    await this.client.rpush(fullKey, serialized);
+    if (this.ttlSeconds > 0) {
+      await this.client.expire(fullKey, this.ttlSeconds);
+    }
+  }
+  async listFromTo(key, from, to = -1) {
+    const fullKey = this.getKey(key);
+    const values = await this.client.lrange(fullKey, from, to);
+    return values.map((v) => this.deserialize(v));
+  }
+  async delete(key) {
+    const fullKey = this.getKey(key);
+    await this.client.del(fullKey);
+  }
+  async clear() {
+    const pattern = `${this.keyPrefix}*`;
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.scanKeys(this.client, cursor, pattern, 100);
+      if (keys.length > 0) {
+        await this.client.del(...keys);
+      }
+      cursor = nextCursor;
+    } while (cursor !== "0" && cursor !== 0);
+  }
+  async increment(key) {
+    const fullKey = this.getKey(key);
+    return this.client.incr(fullKey);
+  }
+};
+var upstashPreset = {
+  setWithExpiry: (client, key, value, seconds) => client.set(key, value, { ex: seconds }),
+  scanKeys: (client, cursor, pattern, count) => client.scan(cursor, { match: pattern, count })
+};
+var nodeRedisPreset = {
+  setWithExpiry: (client, key, value, seconds) => client.set(key, value, { EX: seconds }),
+  scanKeys: (client, cursor, pattern, count) => client.scan(cursor, { MATCH: pattern, COUNT: count })
+};
 
+exports.RedisServerCache = RedisServerCache;
 exports.RedisStore = RedisStore;
 exports.ScoresRedis = ScoresRedis;
 exports.StoreMemoryRedis = StoreMemoryRedis;
 exports.WorkflowsRedis = WorkflowsRedis;
+exports.nodeRedisPreset = nodeRedisPreset;
+exports.upstashPreset = upstashPreset;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map