@mastra/memory 1.24.0-alpha.0 → 1.25.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @mastra/memory
 
+## 1.25.0-alpha.0
+
+### Minor Changes
+
+- Added config-level `hooks` to Observational Memory so apps can track what OM's background model calls cost. Previously the `ObserveHooks` lifecycle callbacks only fired when calling `observe()` manually — the automatic pipeline (turn-driven observation and fire-and-forget async buffering) computed token `usage` and `providerMetadata` and dropped them. Hooks set on the OM config (including through `Memory`'s `observationalMemory` options) now fire for every observation and reflection cycle, with `threadId`/`resourceId`/`trigger` call context: ([#19058](https://github.com/mastra-ai/mastra/pull/19058))
+
+  ```ts
+  const memory = new Memory({
+    storage,
+    options: {
+      observationalMemory: {
+        hooks: {
+          onObservationEnd: ({ usage, providerMetadata, error, threadId, trigger }) => {
+            recordOmSpend({ usage, providerMetadata, threadId, trigger });
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  Failed async-buffered cycles never throw (they are fire-and-forget), so they report through the end hook's `error` field instead. Errors thrown by config-level hooks are caught and logged, never failing the cycle. Per-call `observe()` hooks keep their existing payloads and semantics.
+
+### Patch Changes
+
+- Updated dependencies [[`594f7b2`](https://github.com/mastra-ai/mastra/commit/594f7b28f5263fb9982fd50d95c471fb971ea984), [`311f943`](https://github.com/mastra-ai/mastra/commit/311f943bee60e8fdf5c84499ea50e884276c936c), [`0c89896`](https://github.com/mastra-ai/mastra/commit/0c8989673fb7d106837098398131e570c6023b68), [`23b4238`](https://github.com/mastra-ai/mastra/commit/23b423844ad0bcf2a502a68dd62866d6160f9f6d), [`e320a76`](https://github.com/mastra-ai/mastra/commit/e320a763feaf65c6be3cebecf746defcbde161b3), [`03b4918`](https://github.com/mastra-ai/mastra/commit/03b4918c80d188ce375334c393e131c6e94bd7eb), [`14ef73a`](https://github.com/mastra-ai/mastra/commit/14ef73a4bbd73e7808414816eb0628ce1d80b5d7), [`1d677d5`](https://github.com/mastra-ai/mastra/commit/1d677d5f99d7db403f7828585e8c25f299f72628), [`93e28ec`](https://github.com/mastra-ai/mastra/commit/93e28ecce9031c02397e0ae8406593e5c7a95883), [`729dab4`](https://github.com/mastra-ai/mastra/commit/729dab408faccfaef0cbb048e5a4338f9172847e), [`484003d`](https://github.com/mastra-ai/mastra/commit/484003d33ff59330c86b19863e4a38732d7e4155), [`933d291`](https://github.com/mastra-ai/mastra/commit/933d291146b789c19442ad206f94da3e4be90c64)]:
+  - @mastra/core@1.56.0-alpha.3
+
+## 1.24.0
+
+### Minor Changes
+
+- Added exact metadata filtering to message history queries across Memory APIs and supported storage providers. ([#19991](https://github.com/mastra-ai/mastra/pull/19991))
+
+  ```ts
+  const messages = await memory.recall({
+    threadId: 'thread-1',
+    filter: {
+      metadata: {
+        status: 'done',
+        priority: 'high',
+      },
+    },
+  });
+  ```
+
+  Multiple fields use AND semantics. Supported values are strings, finite numbers, booleans, and `null`.
+
+### Patch Changes
+
+- Updated dependencies [[`ce93a3c`](https://github.com/mastra-ai/mastra/commit/ce93a3c114ea1cbfbd576f3db41d7c26c9844f5b), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`a211d09`](https://github.com/mastra-ai/mastra/commit/a211d09185dc65a746534914cf38b67f21ee9bac), [`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa), [`6218217`](https://github.com/mastra-ai/mastra/commit/62182171b6cfca0b099f1c6a77a2e65e7639ab86), [`5807d3a`](https://github.com/mastra-ai/mastra/commit/5807d3ae1d259b8b7d6df7e5bf2b485c694af9c8), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`05db566`](https://github.com/mastra-ai/mastra/commit/05db566fcbdcbf33d0bffca0c72ec30129e2e3ca), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`d1b7e3a`](https://github.com/mastra-ai/mastra/commit/d1b7e3a978a309a5653eeaa490d2d6c7c53bd093), [`29c584a`](https://github.com/mastra-ai/mastra/commit/29c584a13a88831e5ed1fdeb0ff8e82eae180433), [`c093146`](https://github.com/mastra-ai/mastra/commit/c0931466404d3c521308ea119cb165bb7e695155), [`8124754`](https://github.com/mastra-ai/mastra/commit/8124754ae89fbc69f8136d1df4a91904d0f84c4e), [`d12b2e4`](https://github.com/mastra-ai/mastra/commit/d12b2e4023fd9e3d3e93a9169f5088bcee2a849c)]:
+  - @mastra/core@1.54.0
+
 ## 1.24.0-alpha.0
 
 ### Minor Changes

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.24.0-alpha.0"
+  version: "1.25.0-alpha.0"
 ---
 
 ## When to use
@@ -16,11 +16,11 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
+- [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals and suspend tool execution, plus automatically resume suspended tools while keeping humans in control of agent workflows.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Supervisor agents](references/docs-agents-supervisor-agents.md) - Learn how to coordinate multiple agents with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
-- [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents — including observational memory in thread scope — using runEvals and dataset experiments.
-- [Background tasks](references/docs-long-running-agents-background-tasks.md) - Learn how to dispatch long-running tool calls in the background, keep the stream open until they complete, and orchestrate subagents asynchronously.
+- [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents, including observational memory in thread scope, using runEvals and dataset experiments.
+- [Background tasks](references/docs-long-running-agents-background-tasks.md) - Learn how to dispatch long-running tool calls in the background and keep the stream open until they complete, plus orchestrate subagents asynchronously.
 - [Goals](references/docs-long-running-agents-goals.md) - Learn how to set a durable objective on an agent that's judged in the execution loop, so the agent keeps working until the goal is complete or the run budget is exhausted.
 - [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
 - [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
@@ -41,8 +41,8 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: Memory.createThread()](references/reference-memory-createThread.md) - Documentation for the `Memory.createThread()` method in Mastra, which creates a new conversation thread in the memory system.
 - [Reference: Memory.getThreadById()](references/reference-memory-getThreadById.md) - Documentation for the `Memory.getThreadById()` method in Mastra, which retrieves a specific thread by its ID.
 - [Reference: Memory.listThreads()](references/reference-memory-listThreads.md) - Documentation for the `Memory.listThreads()` method in Mastra, which retrieves threads with optional filtering by resourceId and/or metadata.
-- [Reference: Memory class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
-- [Reference: Observational Memory](references/reference-memory-observational-memory.md) - API reference for Observational Memory in Mastra — a three-tier memory system that uses Observer and Reflector agents to maintain long-term memory across conversations.
+- [Reference: Memory class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a reliable system for managing conversation history and thread-based message storage.
+- [Reference: Observational Memory](references/reference-memory-observational-memory.md) - API reference for Observational Memory in Mastra: a three-tier memory system that uses Observer and Reflector agents to maintain long-term memory across conversations.
 - [Reference: summarizeConversation()](references/reference-memory-summarizeConversation.md) - Documentation for the standalone `summarizeConversation()` function in Mastra, which summarizes messages you pass in and extracts structured values from them.
 - [Reference: Memory.summarizeThread()](references/reference-memory-summarizeThread.md) - Documentation for the `Memory.summarizeThread()` method in Mastra, which summarizes a thread's conversation in one shot and extracts structured values from it.
 - [Reference: TokenLimiterProcessor](references/reference-processors-token-limiter-processor.md) - Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,213 +1,11 @@
 {
-  "version": "1.24.0-alpha.0",
+  "version": "1.25.0-alpha.0",
   "package": "@mastra/memory",
-  "exports": {
-    "Extractor": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 316
-    },
-    "ModelByInputTokens": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1354
-    },
-    "OBSERVER_SYSTEM_PROMPT": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js"
-    },
-    "ObservationalMemory": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 28549
-    },
-    "ObservationalMemoryProcessor": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 31183
-    },
-    "TokenCounter": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 22331
-    },
-    "WorkingMemoryExtractor": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 22998
-    },
-    "buildObserverPrompt": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 4504
-    },
-    "buildObserverSystemPrompt": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 3771
-    },
-    "combineObservationGroupRanges": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1446
-    },
-    "deriveObservationGroupProvenance": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1480
-    },
-    "extractCurrentTask": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 4627
-    },
-    "formatMessagesForObserver": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 4226
-    },
-    "getObservationsAsOf": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 31405
-    },
-    "hasCurrentTaskSection": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 4615
-    },
-    "injectAnchorIds": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 3326
-    },
-    "optimizeObservationsForContext": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 4638
-    },
-    "parseAnchorId": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 3299
-    },
-    "parseObservationGroups": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1415
-    },
-    "parseObserverOutput": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 4518
-    },
-    "reconcileObservationGroupsFromReflection": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1504
-    },
-    "renderObservationGroupsForReflection": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1460
-    },
-    "stripEphemeralAnchorIds": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 3356
-    },
-    "stripObservationGroups": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1437
-    },
-    "summarizeConversation": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js"
-    },
-    "wrapInObservationGroup": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 1408
-    },
-    "OBSERVATIONAL_MEMORY_DEFAULTS": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "OBSERVATION_CONTEXT_INSTRUCTIONS": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "OBSERVATION_CONTEXT_PROMPT": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "OBSERVATION_CONTINUATION_HINT": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "Memory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 24423
-    },
-    "MessageHistory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js"
-    },
-    "SUMMARIZE_THREAD_DEFAULTS": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js"
-    },
-    "SemanticRecall": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js"
-    },
-    "WorkingMemory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js"
-    },
-    "deepMergeWorkingMemory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 24062
-    },
-    "extractWorkingMemoryContent": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 24378
-    },
-    "extractWorkingMemoryTags": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 24346
-    },
-    "removeWorkingMemoryTags": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-3UXBG7HA.js",
-      "line": 24359
-    },
-    "WORKING_MEMORY_STATE_ID": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-WCGXQIEN.js"
-    },
-    "WORKING_MEMORY_STATE_PROCESSOR_ID": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-WCGXQIEN.js"
-    },
-    "WorkingMemoryStateProcessor": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-WCGXQIEN.js",
-      "line": 7
-    }
-  },
+  "exports": {},
   "modules": {
     "processors": {
       "index": "dist/processors/index.js",
-      "chunks": [
-        "chunk-3UXBG7HA.js",
-        "chunk-LSJJAJAF.js"
-      ]
+      "chunks": []
     }
   }
 }

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

@@ -6,7 +6,7 @@ Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/wor
 
 ## When to use agent approval
 
-- **Destructive or irreversible actions** such as deleting records, sending emails, or processing payments.
+- **Destructive or irreversible actions** such as deleting records or sending emails, or alternatively processing payments.
 - **Cost-heavy operations** like calling expensive third-party APIs where you want to verify arguments first.
 - **Conditional confirmation** where a tool starts executing and then discovers it needs the user to confirm or supply extra data before finishing.
 
@@ -60,7 +60,7 @@ Mastra offers two distinct mechanisms for pausing tool calls: **pre-execution ap
 
 Pre-execution approval pauses a tool call _before_ its `execute` function runs. The LLM still decides which tool to call and provides arguments, but `execute` doesn't run until you explicitly approve.
 
-Two flags control this, combined with OR logic. If _either_ is `true`, the call pauses:
+The flags control this, combined with OR logic. If _either_ is `true`, the call pauses:
 
 | Flag                        | Where to set it                   | Scope                                       |
 | --------------------------- | --------------------------------- | ------------------------------------------- |
@@ -92,7 +92,7 @@ for await (const chunk of stream.fullStream) {
 
 #### Conditional approval with a function
 
-Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval dynamically — for example, only for tools whose name matches a pattern:
+Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:
 
 ```typescript
 const stream = await agent.stream('Clean up old records', {
@@ -100,10 +100,82 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above doesn't override it. If the function throws, the call requires approval (fail-safe).
+A tool's own `requireApproval` setting takes precedence over the function above. Its rule decides whether that tool needs approval. If the function throws, the call requires approval as a fail-safe.
 
 > **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
 
+#### Bind approval to the exact tool arguments
+
+For sensitive tools, bind the approval to the exact tool name and arguments that were shown to the reviewer. If those arguments drift before execution, the tool shouldn't run under the old approval.
+
+The `tool-call-approval` chunk already includes `toolName`, `toolCallId`, and `args`. You can fingerprint those fields when the approval request is shown. The example below uses a simple JSON string as the fingerprint, but in production you should use a stable hash of the tool name and arguments:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// For your production usecase, build a stable hash of the tool name and args
+function actionFingerprint(toolName: string, args: unknown) {
+  const payload = JSON.stringify({ toolName, args })
+  return `fingerprint-${payload}`
+}
+
+const sensitiveTools = new Set(['issue_refund', 'delete_record'])
+const approvedFingerprints = new Set<string>()
+
+export const approvalBoundAgent = new Agent({
+  id: 'approval-bound-agent',
+  name: 'Approval Bound Agent',
+  model: 'openai/gpt-5.6-sol',
+  tools: { issueRefundTool, deleteRecordTool },
+  hooks: {
+    beforeToolCall: ({ toolName, input }) => {
+      if (!sensitiveTools.has(toolName)) return
+
+      const fingerprint = actionFingerprint(toolName, input)
+      if (!approvedFingerprints.delete(fingerprint)) {
+        return {
+          proceed: false,
+          output: `Tool call blocked: approval did not match ${toolName} arguments.`,
+        }
+      }
+    },
+  },
+})
+```
+
+```typescript
+const stream = await approvalBoundAgent.stream('Refund order ord-1042', {
+  requireToolApproval: ({ toolName }) => sensitiveTools.has(toolName),
+})
+
+async function consumeApprovalStream(currentStream: typeof stream) {
+  for await (const chunk of currentStream.fullStream) {
+    if (chunk.type === 'tool-call-approval') {
+      const { toolName, toolCallId, args } = chunk.payload
+      const fingerprint = actionFingerprint(toolName, args)
+
+      // Present toolName, args, and fingerprint to your approval UI.
+      const approved = await showApprovalDialog({ toolName, args, fingerprint })
+
+      const nextStream = approved
+        ? await approveReviewedToolCall(currentStream.runId, toolCallId, fingerprint)
+        : await approvalBoundAgent.declineToolCall({ runId: currentStream.runId, toolCallId })
+
+      await consumeApprovalStream(nextStream)
+    }
+  }
+}
+
+async function approveReviewedToolCall(runId: string, toolCallId: string, fingerprint: string) {
+  approvedFingerprints.add(fingerprint)
+  return approvalBoundAgent.approveToolCall({ runId, toolCallId })
+}
+
+await consumeApprovalStream(stream)
+```
+
+In production, store the approved fingerprint in durable storage scoped to the user, run, tool call, and policy version. The `Set` above is intentionally small so the boundary is easy to see: the approval is consumed once, and only for the same canonical tool arguments that were reviewed.
+
 ### Runtime suspension with `suspend()`
 
 A tool can also pause _during_ its `execute` function by calling `suspend()`. This is useful when the tool starts running and then discovers it needs additional user input or confirmation before it can finish.
@@ -133,7 +205,7 @@ const weatherTool = createTool({
 })
 ```
 
-> **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
+> **Note:** `suspend()` doesn't throw, return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`
 
@@ -172,11 +244,11 @@ if (output.finishReason === 'suspended') {
 | Decline method     | `declineToolCall({ runId })` | `declineToolCallGenerate({ runId, toolCallId })` |
 | Result             | Stream to iterate            | Full output object                               |
 
-> **Note:** `toolCallId` is optional on all four methods. Pass it when multiple tool calls may be pending at the same time (common in supervisor agents). When omitted, the agent resumes the most recent suspended tool call.
+> **Note:** `toolCallId` is optional on all four methods. Pass it when multiple tool calls may be pending (common in supervisor agents). When omitted, the agent resumes the most recent suspended tool call.
 
 ## Tool-level approval
 
-Instead of pausing every tool call at the agent level, you can mark individual tools as requiring approval. This gives you granular control: only specific tools pause, while others execute immediately.
+Instead of pausing every tool call at the agent level, you can mark individual tools as requiring approval. You get fine-grained control: only specific tools pause, while others execute immediately.
 
 ### Approval using `requireApproval`
 
@@ -303,7 +375,9 @@ const agent = new Agent({
 })
 ```
 
-When enabled, the agent detects suspended tools from message history on the next user message, extracts `resumeData` based on the tool's `resumeSchema`, and automatically resumes the tool. The following example shows a complete conversational flow:
+When enabled, the agent detects suspended tools from message history on the next user message. It extracts `resumeData` based on the tool's `resumeSchema`, then automatically resumes the tool.
+
+The following example shows a complete conversational flow:
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -386,7 +460,7 @@ Both approaches work with the same tool definitions. Automatic resumption trigge
 
 ## 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.
+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:
 
@@ -414,7 +488,7 @@ if (run && toolCall) {
 }
 ```
 
-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.
+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.
 
@@ -477,7 +551,7 @@ const supervisorAgent = new Agent({
   name: 'Supervisor Agent',
   instructions: `You coordinate data retrieval tasks.
     Delegate to data-agent for user lookups.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: { dataAgent },
   memory: new Memory(),
 })

package/dist/docs/references/docs-agents-networks.md

@@ -2,7 +2,7 @@
 
 # Agent networks
 
-> **Deprecated — Use supervisor agents:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
 > See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
@@ -29,7 +29,7 @@ export const routingAgent = new Agent({
   name: 'Routing Agent',
   instructions: `
     You are a network of writers and researchers. The user will ask you to research a topic. Always respond with a complete report—no bullet points. Write in full paragraphs, like a blog post. Do not answer with incomplete or uncertain information.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: {
     researchAgent,
     writingAgent,

package/dist/docs/references/docs-agents-supervisor-agents.md

@@ -8,7 +8,7 @@ A supervisor agent coordinates multiple subagents using [`Agent.stream()`](https
 
 ## When to use supervisor agents
 
-Use supervisor agents when a task requires multiple agents with different specializations to work together. The supervisor handles delegation decisions, context passing, and result synthesis.
+Use supervisor agents when a task requires multiple agents with different specializations to work together. The supervisor handles delegation decisions and context passing, plus result synthesis.
 
 Common use cases:
 
@@ -43,7 +43,7 @@ const supervisor = new Agent({
   id: 'supervisor',
   instructions: `You coordinate research and writing using specialized agents.
     Delegate to research-agent for facts, then writing-agent for content.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: { researchAgent, writingAgent },
   memory: new Memory({
     storage: new LibSQLStore({ id: 'storage', url: 'file:mastra.db' }),
@@ -112,7 +112,7 @@ The `context` object includes:
 
 ### `onDelegationComplete`
 
-Called after a delegation finishes. Use it to inspect results, provide feedback, or stop execution:
+Called after a delegation finishes. Use it to inspect results or provide feedback, or alternatively stop execution:
 
 - `context.bail()`: Stop the supervisor loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the supervisor's memory and is visible to subsequent iterations
@@ -147,7 +147,7 @@ The `context` object includes:
 
 ## Message filtering
 
-By default, subagents receive the full conversation context from the supervisor. Use `messageFilter` to control what messages are shared — for example, to remove sensitive data or limit context size.
+By default, subagents receive the full conversation context from the supervisor. Use `messageFilter` to control what messages are shared, for example, to remove sensitive data or limit context size.
 
 ```typescript
 const stream = await supervisor.stream('Research AI trends', {
@@ -173,7 +173,9 @@ The callback receives `messages` (the full conversation history), `primitiveId`
 
 When a subagent completes, the supervisor model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, aren't added to the supervisor model context.
 
-Application code and UI integrations can still inspect the raw delegation result, including `subAgentToolResults`, from the tool result payload. This keeps debugging and display data available without sending nested tool arguments or outputs back into the supervisor's next model call.
+Application code and UI integrations can still inspect `subAgentToolResults` and the rest of the raw delegation result in the tool result payload.
+
+This keeps debugging and display data available without sending nested tool arguments or outputs back into the supervisor's next model call.
 
 Set `includeSubAgentToolResultsInModelContext` to include the full subagent result, including nested tool results and subagent metadata, in the supervisor model context.
 
@@ -187,7 +189,7 @@ await supervisor.generate('Research AI trends', {
 
 ## Iteration monitoring
 
-`onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress, inject feedback, or stop execution early.
+`onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress or inject feedback, or alternatively stop execution early.
 
 ```typescript
 const stream = await supervisor.stream('Research AI trends', {
@@ -214,7 +216,7 @@ const stream = await supervisor.stream('Research AI trends', {
 })
 ```
 
-Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn to produce a text response incorporating the feedback, but only if the current iteration is still active (e.g., after tool calls) — otherwise no extra turn is granted.
+Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn to produce a text response incorporating the feedback, but only if the current iteration is still active (e.g., after tool calls), otherwise no extra turn is granted.
 
 ## Memory isolation
 
@@ -226,7 +228,7 @@ How it works:
 2. **Scoped memory saves**: Only the delegation prompt and the subagent's response are saved to the subagent's memory
 3. **Fresh thread per invocation**: Each delegation uses a unique thread ID, ensuring clean separation
 
-This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
+As a result, subagents have the context they need without cluttering their memory with the entire supervisor conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
 
 ## Tool approval propagation
 
@@ -309,7 +311,7 @@ const stream = await supervisor.stream('Research AI in education', {
 
 The built-in rubric scorer lets you define what "correct" looks like as a checklist and have the agent self-evaluate and iterate until every criterion is satisfied or `maxSteps` is reached.
 
-It works as an **LLM-as-judge** scorer: a separate grader model reviews the agent's output against the rubric after each iteration. If every required criterion passes, the loop ends. If anything falls short, per-criterion feedback is injected back into the conversation and the agent tries again.
+It works as an **LLM-as-judge** scorer. After each iteration, a separate grader model reviews the agent's output against the rubric. The loop ends when every required criterion passes. A failed criterion adds its feedback to the conversation so the agent can try again.
 
 This is most effective for tasks with clear, verifiable success criteria. You can use it like so:
 
@@ -320,7 +322,7 @@ import { createRubricScorer } from '@mastra/evals/scorers/prebuilt'
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'You coordinate research and writing using specialized agents.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: { researchAgent, writingAgent },
 })
 
@@ -345,9 +347,13 @@ For full API details, see the [rubric scorer reference](https://mastra.ai/refere
 
 ## Writing effective instructions
 
-Clear instructions are essential for effective delegation. Your supervisor's `instructions` should specify available resources, when to use each one, how to coordinate them, and success criteria.
+Clear instructions are essential for effective delegation.
+
+Your supervisor's `instructions` should specify the available resources and when to use each one. They should also define coordination behavior and success criteria.
+
+Each subagent should have a clear `description` that explains its purpose and return format, including when the supervisor should use it.
 
-Each subagent should have a clear `description` that explains what it does, what format it returns, and when to use it. The supervisor uses these descriptions to make delegation decisions.
+The supervisor uses these descriptions to make delegation decisions.
 
 ```typescript
 const supervisor = new Agent({
@@ -380,7 +386,7 @@ Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration)
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'Coordinate research and writing using the available agents.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   agents: { researchAgent, writingAgent },
   backgroundTasks: {
     tools: {