@mastra/memory 1.24.0 → 1.25.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @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

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"
+  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,5 +1,5 @@
 {
-  "version": "1.24.0",
+  "version": "1.25.0-alpha.0",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

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: {

package/dist/docs/references/docs-evals-evals-with-memory.md

@@ -2,7 +2,7 @@
 
 # Evals with memory
 
-Agents that use memory in `thread` scope — including observational memory — require a thread ID at run time. When an eval invokes the agent without one, you'll see:
+Agents that use memory in `thread` scope, including observational memory, require a thread ID at run time. When an eval invokes the agent without one, you'll see:
 
 ```text
 ObservationalMemory (scope: 'thread') requires a threadId, but none was found in RequestContext or MessageList.
@@ -18,11 +18,11 @@ This page covers the three working patterns for running Mastra evals against mem
 | One independent thread per item, focused CI loop | [`runEvals` per item](#per-item-threads-with-runevals)                                    |
 | Per-item threads driven by a stored `Dataset`    | [`dataset.startExperiment` with an inline task](#dataset-experiments-with-an-inline-task) |
 
-Pre-seeding `RequestContext` with `MastraMemory` **isn't** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread` — `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
+Pre-seeding `RequestContext` with `MastraMemory` **isn't** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread`, `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
 
 ## Shared thread with `runEvals`
 
-`runEvals` accepts `targetOptions`, which is forwarded to `agent.generate()`. Passing `memory: { thread, resource }` runs every data item against the same thread — useful for testing recall across a multi-turn conversation.
+`runEvals` accepts `targetOptions`, which is forwarded to `agent.generate()`. Passing `memory: { thread, resource }` runs every data item against the same thread, useful for testing recall across a multi-turn conversation.
 
 ```typescript
 import { runEvals } from '@mastra/core/evals'
@@ -88,7 +88,7 @@ const average = scores.reduce((a, b) => a + b, 0) / scores.length
 
 ## Dataset experiments with an inline task
 
-`dataset.startExperiment({ target: agent })` **doesn't** forward a `memory` option to the agent — only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
+`dataset.startExperiment({ target: agent })` **doesn't** forward a `memory` option to the agent, only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
 
 ```typescript
 import { randomUUID } from 'node:crypto'

package/dist/docs/references/docs-long-running-agents-background-tasks.md

@@ -74,7 +74,7 @@ export const researchTool = createTool({
 
 ### Agent-level
 
-Use `backgroundTasks.tools` on the agent to opt in specific tools, override timeouts for individual tools, or run all background-eligible tools in the background. Use `disabled: true` to short-circuit background dispatch for the agent entirely.
+Use `backgroundTasks.tools` on the agent to opt in specific tools or override timeouts for individual tools, or alternatively run all background-eligible tools in the background. Use `disabled: true` to short-circuit background dispatch for the agent entirely.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -82,7 +82,7 @@ import { Agent } from '@mastra/core/agent'
 export const researcher = new Agent({
   id: 'researcher',
   instructions: 'You research topics and answer questions.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   tools: { researchTool, summarizeTool },
   backgroundTasks: {
     tools: {
@@ -106,7 +106,7 @@ When a tool is registered on an agent that has background tasks enabled, the mod
 }
 ```
 
-The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer — it's not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
+The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer, it's not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
 
 ### Resolution order
 
@@ -172,7 +172,7 @@ Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) fo
 
 ### Aggregate properties
 
-`stream()` with `untilIdle` returns a `MastraModelOutput` that looks like the one from a regular `stream()` call, but only `fullStream` spans the initial turn **and** any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
+`stream()` with `untilIdle` returns a `MastraModelOutput` that looks like the one from a regular `stream()` call, but `fullStream` alone spans the initial turn and any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
 
 ## Subagents in the background
 
@@ -184,7 +184,7 @@ import { Agent } from '@mastra/core/agent'
 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: {
@@ -260,7 +260,7 @@ export const reviewTool = createTool({
 })
 ```
 
-The first invocation of `execute` sees `resumeData === undefined` and calls `suspend`. After the task is resumed, the runtime restarts the tool with `resumeData` populated; the `if` branch falls through and the tool returns its real result.
+The first invocation of `execute` sees `resumeData === undefined` and calls `suspend`. After the task is resumed, the runtime restarts the tool with `resumeData` populated. The `if` condition is false, so the tool returns its real result.
 
 To resume the task once an approval arrives:
 
@@ -273,19 +273,19 @@ await mastra.backgroundTaskManager?.resume(taskId, {
 
 ### What happens to the agent loop
 
-When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion, its result lands in the message list, and the agent runs a follow-up turn — all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
+When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion, its result is added to the message list, and the agent runs a follow-up turn, all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
 
 ### Re-registering the executor on resume
 
-The manager keeps tool executors in process memory. If the process restarts while a task is suspended, the executor closure is gone — the caller of `resume()` must re-register it first via `manager.registerTaskContext(taskId, ...)`. Tasks dispatched and resumed inside the same process don't need this.
+The manager keeps tool executors in process memory. If the process restarts while a task is suspended, the executor closure is gone, the caller of `resume()` must re-register it first via `manager.registerTaskContext(taskId, ...)`. Tasks dispatched and resumed inside the same process don't need this.
 
 ### Cancelling a suspended task
 
-`manager.cancel(taskId)` works against suspended tasks the same way it works for running ones: the row flips to `cancelled`, the workflow snapshot is cleaned up, and a `task.cancelled` event fires.
+`manager.cancel(taskId)` works against suspended tasks the same way it works for running ones. The row changes to `cancelled` and the workflow snapshot is cleaned up. A `task.cancelled` event then fires.
 
 ## Lifecycle callbacks
 
-Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their respective outcomes:
+Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their outcomes:
 
 - Tool-level `background.onComplete` / `onFailed`: scoped to one tool.
 - Agent-level `backgroundTasks.onTaskComplete` / `onTaskFailed`: scoped to all tasks dispatched by this agent.

package/dist/docs/references/docs-long-running-agents-goals.md

@@ -6,7 +6,9 @@
 
 > **Beta:** The Goals feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
+A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted.
+
+The objective is persisted in thread state, so it survives reloads and is evaluated in-loop, even when a new message arrives in the middle of an already-running turn.
 
 Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents): an LLM-as-judge scores the agent's output each iteration and gates the loop. The difference is that a goal is **durable** (stored in thread state, not passed per call) and is set and updated through `Agent` methods rather than per-`stream()` options.
 
@@ -22,7 +24,7 @@ For a one-off completion check within a single `stream()` call, use [`isTaskComp
 
 ## Quickstart
 
-Goals require a configured [storage](https://mastra.ai/docs/storage/overview) backend and a memory-backed thread. Add a `goal` config to the agent — a judge model is required for the goal to do anything — then set an objective for a thread:
+Goals require a configured [storage](https://mastra.ai/docs/storage/overview) backend and a memory-backed thread. Add a `goal` config to the agent, a judge model is required for the goal to do anything, then set an objective for a thread:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -31,7 +33,7 @@ const worker = new Agent({
   id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory,
   goal: {
     judge: 'openai/gpt-5-mini',
@@ -51,19 +53,21 @@ const stream = await worker.stream('Start working on the goal', {
 })
 ```
 
-The `goal` config auto-registers the state-signal projection, so the model always sees the current objective as `<current-objective>` in its context — no extra setup needed.
+The `goal` config auto-registers the state-signal projection, so the model always sees the current objective as `<current-objective>` in its context without extra setup.
 
 ## How the goal step works
 
 A goal step runs inside the agentic execution loop, right after `isTaskComplete`. On a real candidate answer it scores the conversation against the objective and gates the loop:
 
-- **Not satisfied, budget remaining** → the loop continues; per-evaluation feedback is injected so the agent iterates.
+- **Not satisfied, budget remaining** → the loop continues. Per-evaluation feedback is injected so the agent iterates.
 - **Satisfied** → the loop stops and the objective is marked `done`.
 - **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops and the objective is marked `paused`. Raise `maxRuns`, then resume the objective to continue.
 
-The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations — the same gating as `isTaskComplete`.
+The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations, the same gating as `isTaskComplete`.
+
+**The judge model is the activation switch.** If no judge resolves (neither the per-objective override nor the agent's `goal.judge`), the goal step performs no scoring or budget consumption and emits no `goal` chunk.
 
-**The judge model is the activation switch.** If no judge resolves (neither the per-objective override nor the agent's `goal.judge`), the goal step does nothing: no scoring, no budget consumed, no `goal` chunk. Effective settings resolve as per-objective record value → agent `goal` config → built-in default (`maxRuns` `50`, a default judge prompt).
+Effective settings resolve as per-objective record value → agent `goal` config → built-in default (`maxRuns` `50`, a default judge prompt).
 
 By default the step uses a built-in LLM-as-judge scorer that returns `1` when the objective is achieved and `0` otherwise. Supply your own scorer with `goal.scorer` to customize judging.
 
@@ -72,7 +76,7 @@ const worker = new Agent({
   id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory,
   goal: {
     // A resolver function lets you inject provider credentials and read the
@@ -109,6 +113,6 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
-- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers) — how the objective is projected into context
-- [Memory storage](https://mastra.ai/docs/storage/overview) — the storage backend goals require
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents): `isTaskComplete` and the rubric scorer
+- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers): how the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/storage/overview): the storage backend goals require