@mastra/memory 1.21.3-alpha.0 → 1.21.3-alpha.2

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.21.3-alpha.0"
+  version: "1.21.3-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,119 +1,119 @@
 {
-  "version": "1.21.3-alpha.0",
+  "version": "1.21.3-alpha.2",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 795
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js"
+      "implementation": "dist/chunk-X7DOZRJK.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 7194
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 7213
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 9773
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 9798
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 6525
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 6544
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3782
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3787
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3053
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3058
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 887
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 921
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3896
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3901
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3508
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3513
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 9993
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 10018
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3884
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3889
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 2601
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 2606
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3907
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3912
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 2574
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 2579
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 856
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 3792
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 3797
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 945
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 901
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
-      "line": 2631
+      "implementation": "dist/chunk-X7DOZRJK.js",
+      "line": 2636
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 878
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-UHQBCO7I.js",
+      "implementation": "dist/chunk-X7DOZRJK.js",
       "line": 849
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -162,7 +162,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-UHQBCO7I.js",
+        "chunk-X7DOZRJK.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-agents-agent-approval.md

@@ -357,6 +357,44 @@ For automatic tool resumption to work:
 
 Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
 
+## Resuming after a restart
+
+The examples above hold on to `stream.runId` between suspension and approval. That works while the process stays alive, but in production the approval often arrives later — after a page refresh, a server restart, or on a different server instance behind a load balancer.
+
+Use [`listSuspendedRuns()`](https://mastra.ai/reference/agents/listSuspendedRuns) to rediscover the pending run for a conversation from storage:
+
+```typescript
+// In the request handler that receives the user's decision
+const { runs } = await agent.listSuspendedRuns({
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+})
+
+const run = runs[0]
+const toolCall = run?.toolCalls[0]
+
+if (run && toolCall) {
+  let stream
+  if (toolCall.requiresApproval) {
+    // Suspended by requireApproval — approve or decline the tool call
+    stream = await agent.approveToolCall({ runId: run.runId, toolCallId: toolCall.toolCallId })
+  } else {
+    // Suspended by suspend() — resume with the data the tool asked for
+    console.log('Tool asked:', toolCall.suspendPayload)
+    stream = await agent.resumeStream({ name: 'San Francisco' }, { runId: run.runId })
+  }
+  for await (const chunk of stream.textStream) process.stdout.write(chunk)
+}
+```
+
+Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `args`, and `requiresApproval`). Approval suspensions (`requiresApproval: true`) are answered with `approveToolCall()` / `declineToolCall()`, while `suspend()`-based suspensions carry their `suspendPayload` and expect `resumeStream()` with resume data — so you can rebuild the right UI for either flow without keeping any state in memory.
+
+`sendToolApproval()` uses the same storage-backed discovery automatically: when no active run is found in memory for the thread, it looks up the suspended run in storage before failing. If several suspended runs match the thread, pass a `toolCallId` to disambiguate.
+
+The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
+
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/memory/storage). The default in-memory store loses snapshots when the process exits.
+
 ## Tool approval: Supervisor agents
 
 A [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkLEAP5DKB_cjs = require('./chunk-LEAP5DKB.cjs');
+var chunkFQLQMPJY_cjs = require('./chunk-FQLQMPJY.cjs');
 var chunk43FJOLKM_cjs = require('./chunk-43FJOLKM.cjs');
 var chunkQ7SFCCGT_cjs = require('./chunk-Q7SFCCGT.cjs');
 var agent = require('@mastra/core/agent');
@@ -22919,7 +22919,7 @@ var ZodFirstPartyTypeKind3;
   ZodFirstPartyTypeKind4["ZodReadonly"] = "ZodReadonly";
 })(ZodFirstPartyTypeKind3 || (ZodFirstPartyTypeKind3 = {}));
 
-// ../_vendored/ai_v5/dist/chunk-RGIGIB4E.js
+// ../_vendored/ai_v5/dist/chunk-I2JBSJEA.js
 var marker17 = "vercel.ai.error";
 var symbol18 = Symbol.for(marker17);
 var _a19;
@@ -46035,7 +46035,7 @@ function formatTimestamp(date9) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunkLEAP5DKB_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunkFQLQMPJY_cjs.truncateStringByTokens(text4, maxTokens);
   const suffix = hint ? ` [${hint} for more]` : "";
   return { text: truncated + suffix, wasTruncated: true };
 }
@@ -46087,11 +46087,11 @@ ${JSON.stringify(inv.args, null, 2)}`;
             });
           }
           if (inv.state === "result") {
-            const { value: resultValue } = chunkLEAP5DKB_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunkFQLQMPJY_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunkLEAP5DKB_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunkFQLQMPJY_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
             const fullText = `[Tool Result: ${inv.toolName}]
 ${resultStr}`;
             parts.push(makePart(msg, i, "tool-result", fullText, detail, inv.toolName));
@@ -46118,7 +46118,7 @@ ${typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs, null, 2)}`;
         const toolName = part.toolName;
         if (toolName) {
           const rawResult = part.output ?? part.result;
-          const resultStr = chunkLEAP5DKB_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunkFQLQMPJY_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
           const fullText = `[Tool Result: ${toolName}]
 ${resultStr}`;
           parts.push(makePart(msg, i, "tool-result", fullText, detail, toolName));
@@ -46197,7 +46197,7 @@ function renderFormattedParts(parts, timestamps, options) {
   const text4 = buildRenderedText(parts, timestamps);
   let totalTokens = tokenx.estimateTokenCount(text4);
   if (totalTokens > options.maxTokens) {
-    const truncated = chunkLEAP5DKB_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunkFQLQMPJY_cjs.truncateStringByTokens(text4, options.maxTokens);
     return { text: truncated, truncated: true, tokenOffset: totalTokens - options.maxTokens };
   }
   const truncatedIndices = parts.map((p, i) => ({ part: p, index: i })).filter(({ part }) => part.text !== part.fullText).sort((a, b) => expandPriority(a.part) - expandPriority(b.part));
@@ -46230,7 +46230,7 @@ function renderFormattedParts(parts, timestamps, options) {
   if (expandedTokens <= options.maxTokens) {
     return { text: expanded, truncated: false, tokenOffset: 0 };
   }
-  const hardTruncated = chunkLEAP5DKB_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunkFQLQMPJY_cjs.truncateStringByTokens(expanded, options.maxTokens);
   return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
 }
 async function recallPart({
@@ -46281,7 +46281,7 @@ async function recallPart({
 
 `;
           const fallbackText = `${fallbackNote}${firstNextPart.text}`;
-          const truncatedText2 = chunkLEAP5DKB_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunkFQLQMPJY_cjs.truncateStringByTokens(fallbackText, maxTokens);
           const wasTruncated2 = truncatedText2 !== fallbackText;
           return {
             text: truncatedText2,
@@ -46296,7 +46296,7 @@ async function recallPart({
     }
     throw new Error(`Part index ${partIndex} not found in message ${cursor}. Available indices: ${availableIndices}`);
   }
-  const truncatedText = chunkLEAP5DKB_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunkFQLQMPJY_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -48135,7 +48135,7 @@ ${workingMemory}`;
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory: OMClass } = await import('./observational-memory-WZ6JQ4JY.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-2KSGEMXM.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -49087,7 +49087,7 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-WZ6JQ4JY.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-2KSGEMXM.cjs');
     return new ObservationalMemoryProcessor(engine, this, {
       temporalMarkers: effectiveConfig.temporalMarkers
     });
@@ -49114,11 +49114,11 @@ Notes:
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkLEAP5DKB_cjs.ModelByInputTokens; }
+  get: function () { return chunkFQLQMPJY_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkLEAP5DKB_cjs.getObservationsAsOf; }
+  get: function () { return chunkFQLQMPJY_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "WORKING_MEMORY_STATE_ID", {
   enumerable: true,