@mastra/upstash 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,231 @@
 # @mastra/upstash
 
+## 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), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
+  - @mastra/core@1.30.0
+  - @mastra/redis@1.1.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), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
+  - @mastra/core@1.30.0-alpha.1
+  - @mastra/redis@1.1.0-alpha.0
+
 ## 1.0.5
 
 ### Patch Changes

package/dist/cache/index.d.ts

@@ -0,0 +1,60 @@
+import { RedisServerCache } from '@mastra/redis';
+import { Redis } from '@upstash/redis';
+/**
+ * Configuration for UpstashServerCache.
+ * Accepts either:
+ * 1. An existing Redis client from @upstash/redis
+ * 2. URL and token to create a client (requires @upstash/redis to be installed)
+ */
+export type UpstashCacheConfig = {
+    client: Redis;
+} | {
+    url: string;
+    token: string;
+};
+/**
+ * Options for UpstashServerCache
+ */
+export interface UpstashServerCacheOptions {
+    /**
+     * Optional key prefix to namespace all cache keys.
+     * Defaults to 'mastra:cache:'.
+     */
+    keyPrefix?: string;
+    /**
+     * Default TTL in seconds for cached items.
+     * Defaults to 300 (5 minutes).
+     * Set to 0 to disable TTL (items persist until explicitly deleted).
+     */
+    ttlSeconds?: number;
+}
+/**
+ * Upstash Redis implementation of MastraServerCache.
+ *
+ * This is a convenience wrapper around RedisServerCache from @mastra/redis
+ * with the upstash preset pre-configured.
+ *
+ * @example With existing client
+ * ```typescript
+ * import { Redis } from '@upstash/redis';
+ * import { UpstashServerCache } from '@mastra/upstash';
+ *
+ * const redis = new Redis({ url: '...', token: '...' });
+ * const cache = new UpstashServerCache({ client: redis });
+ * ```
+ *
+ * @example With URL and token
+ * ```typescript
+ * import { UpstashServerCache } from '@mastra/upstash';
+ *
+ * const cache = new UpstashServerCache({
+ *   url: process.env.UPSTASH_REDIS_REST_URL!,
+ *   token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+ * });
+ * ```
+ */
+export declare class UpstashServerCache extends RedisServerCache {
+    constructor(config: UpstashCacheConfig, options?: UpstashServerCacheOptions);
+}
+export { RedisServerCache, upstashPreset, type RedisClient, type RedisServerCacheOptions } from '@mastra/redis';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAiB,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,MAAM,EAAE,kBAAkB,EAAE,OAAO,GAAE,yBAA8B;CAiBhF;AAGD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC"}

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,6 +1,15 @@
 {
-  "version": "1.0.5",
+  "version": "1.1.0",
   "package": "@mastra/upstash",
-  "exports": {},
+  "exports": {
+    "RedisServerCache": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/redis"
+    },
+    "upstashPreset": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/redis"
+    }
+  },
   "modules": {}
 }

package/dist/docs/references/docs-memory-working-memory.md

@@ -208,7 +208,7 @@ const paragraphMemory = new Memory({
 
 ## Structured working memory
 
-Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
+Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 
 **Important:** You must specify either `template` or `schema`, but not both.
 

package/dist/index.cjs

@@ -1,7 +1,8 @@
 'use strict';
 
+var redis = require('@mastra/redis');
+var redis$1 = require('@upstash/redis');
 var storage = require('@mastra/core/storage');
-var redis = require('@upstash/redis');
 var error = require('@mastra/core/error');
 var agent = require('@mastra/core/agent');
 var evals = require('@mastra/core/evals');
@@ -10,7 +11,23 @@ var vector = require('@mastra/core/vector');
 var vector$1 = require('@upstash/vector');
 var filter = require('@mastra/core/vector/filter');
 
-// src/storage/index.ts
+// src/cache/index.ts
+var UpstashServerCache = class extends redis.RedisServerCache {
+  constructor(config, options = {}) {
+    let client;
+    if ("client" in config) {
+      client = config.client;
+    } else {
+      client = new redis$1.Redis({ url: config.url, token: config.token });
+    }
+    const redisOptions = {
+      ...redis.upstashPreset,
+      keyPrefix: options.keyPrefix,
+      ttlSeconds: options.ttlSeconds
+    };
+    super({ client }, redisOptions);
+  }
+};
 function getKey(tableName, keys) {
   const keyParts = Object.entries(keys).filter(([_, value]) => value !== void 0).map(([key, value]) => `${key}:${value}`);
   return `${tableName}:${keyParts.join(":")}`;
@@ -44,7 +61,7 @@ function resolveUpstashConfig(config) {
   if ("client" in config) {
     return config.client;
   }
-  return new redis.Redis({
+  return new redis$1.Redis({
     url: config.url,
     token: config.token
   });
@@ -2153,7 +2170,7 @@ var UpstashStore = class extends storage.MastraCompositeStore {
       if (!config.token || typeof config.token !== "string" || config.token.trim() === "") {
         throw new Error("UpstashStore: token is required and cannot be empty.");
       }
-      this.redis = new redis.Redis({
+      this.redis = new redis$1.Redis({
         url: config.url,
         token: config.token
       });
@@ -2872,10 +2889,19 @@ Example Complex Query:
   ]
 }`;
 
+Object.defineProperty(exports, "RedisServerCache", {
+  enumerable: true,
+  get: function () { return redis.RedisServerCache; }
+});
+Object.defineProperty(exports, "upstashPreset", {
+  enumerable: true,
+  get: function () { return redis.upstashPreset; }
+});
 exports.BackgroundTasksUpstash = BackgroundTasksUpstash;
 exports.ScoresUpstash = ScoresUpstash;
 exports.StoreMemoryUpstash = StoreMemoryUpstash;
 exports.UPSTASH_PROMPT = UPSTASH_PROMPT;
+exports.UpstashServerCache = UpstashServerCache;
 exports.UpstashStore = UpstashStore;
 exports.UpstashVector = UpstashVector;
 exports.WorkflowsUpstash = WorkflowsUpstash;