@mastra/mcp-docs-server 1.2.14 → 1.2.15-alpha.10

package/.docs/docs/agents/a2a.md

@@ -2,7 +2,7 @@
 
 # A2A (Agent-to-Agent)
 
-Mastra supports the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
+Mastra supports version 0.3.0 of the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
 
 A2A is an open protocol for delegating work to agents across network, framework, vendor, and language boundaries. A remote agent keeps its own tools, prompts, memory, workflows, and infrastructure private while exposing a protocol endpoint that other systems can discover and call.
 
@@ -57,6 +57,18 @@ A2A represents work as messages and tasks. Messages carry text, file, or structu
 
 Tasks are stateful units of work with IDs and lifecycle states. Clients can follow long-running work and send follow-up turns. They can also cancel work or resubscribe after a disconnect.
 
+## Protocol versions
+
+Mastra supports A2A Protocol v0.3 and v1.0 on the same agent card and execution URLs. The `A2A-Version` request header selects the wire protocol:
+
+- Missing, empty, or `0.3`: Uses the existing v0.3 API.
+- `1.0`: Uses the v1.0 API.
+- Any other value: Returns a `VersionNotSupported` protocol error.
+
+Existing `A2AAgent` and `MastraClient.getA2A()` integrations continue to use v0.3. Use `MastraClient.getA2AV1()` for v1.0 requests. The v1 client sends `A2A-Version: 1.0` automatically and adds the `tasks/list` operation.
+
+Import v1.0 protocol types and codecs from `@mastra/core/a2a/v1`. The existing `@mastra/core/a2a/client` export remains on v0.3.
+
 ## Get started
 
 A2A has two common paths in Mastra:
@@ -155,6 +167,33 @@ for await (const event of updates) {
 }
 ```
 
+### Use the v1.0 client
+
+Use `getA2AV1()` to opt into the A2A v1.0 wire protocol. The protocol package provides codecs for creating v1 request values from JSON-shaped input:
+
+```typescript
+import { ListTasksRequest } from '@mastra/core/a2a/v1'
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'https://agent.example.com',
+})
+
+const a2a = client.getA2AV1('weather-agent')
+const response = await a2a.listTasks(
+  ListTasksRequest.fromJSON({
+    contextId: 'customer-support',
+    pageSize: 20,
+  }),
+)
+
+for (const task of response.tasks) {
+  console.log(task.id, task.status)
+}
+```
+
+The v1.0 client supports `getAgentCard()`, `sendMessage()`, `sendMessageStream()`, `getTask()`, `listTasks()`, `cancelTask()`, and `resubscribeTask()`.
+
 ## Configure subagent calls
 
 `A2AAgent` accepts request options for authenticated or constrained environments:
@@ -176,6 +215,38 @@ const remoteWeatherAgent = new A2AAgent({
 
 You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
 
+## Human-in-the-loop
+
+A2A models human-in-the-loop (HITL) work with the `input-required` task state. When a task pauses for input, the client provides the missing input by sending a follow-up message with the same `taskId`, and the server continues the task.
+
+Mastra maps its agent suspension model to this state in both directions:
+
+- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/agent-approval) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
+- **As a client**: when a remote task reaches `input-required` or `auth-required`, `A2AAgent` returns a suspended result with `finishReason: 'suspended'` and a `suspendPayload`. Calling `resumeGenerate()` or `resumeStream()` sends the input or credentials back to the remote task with the original `taskId`.
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const agent = new A2AAgent({
+  url: 'https://agent.example.com/api/.well-known/booking-agent/agent-card.json',
+})
+
+const result = await agent.generate('Book a flight to Paris', { runId: 'run-1' })
+
+if (result.finishReason === 'suspended') {
+  // Inspect result.suspendPayload, collect input from a human,
+  // then resume the remote task.
+  const resumed = await agent.resumeGenerate({ approved: true }, { runId: 'run-1' })
+  console.log(resumed.text)
+}
+```
+
+Follow-up messages for an `input-required` task can carry the resume data as a structured data part, or as JSON or plain text in a text part.
+
+When a resumed run requires additional input, the task returns to `input-required` and the flow repeats. Resuming a suspended run requires storage configured on the Mastra server so the suspended run state can be restored across requests.
+
+> **Note:** A2A task records live in an in-memory store, so a paused task can only be resumed by the same server process that suspended it. A server restart or a horizontally scaled deployment without sticky routing loses the task record, and a follow-up message fails with a task-not-found error.
+
 ## Push notifications
 
 Mastra supports A2A push notifications for remote agents that advertise `capabilities.pushNotifications`. Use push notifications when a client can't keep a stream open, or when a long-running task should update a callback URL after the original request ends.
@@ -192,7 +263,9 @@ await a2a.setTaskPushNotificationConfig({
 })
 ```
 
-Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, or `input-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, `rejected`, `input-required`, or `auth-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+
+Push notification configurations are stored in memory and must be registered again after a server restart.
 
 ## Sign and verify agent cards
 

package/.docs/docs/agents/processors.md

@@ -544,6 +544,8 @@ This means the cache key is derived from the resolved `LanguageModelV2Prompt` Ma
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
+Multimodal prompts are included too. Image and file parts reach the key by value: a URL contributes its full href, and inline binary data (`Uint8Array`, `ArrayBuffer`) contributes a digest of its bytes. Two requests that differ only in which image they reference therefore get different cache entries.
+
 #### Customize the cache key
 
 Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):

package/.docs/docs/agents/skills.md

@@ -123,7 +123,21 @@ export const agent = new Agent({
 })
 ```
 
-The resolver function receives `{ requestContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.
+The resolver function receives `{ requestContext, tracingContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.
+
+The resolver runs once per `RequestContext`. During an agent execution it runs inside a `resolve-skills` span, and `tracingContext.currentSpan` lets you create child spans for your own work, the same way tools do. The resolver also runs on metadata reads such as `agent.listSkills()` and the server's agent endpoints, where no span exists and `tracingContext.currentSpan` is `undefined`, so keep it fast and guard any span usage:
+
+```typescript
+skills: async ({ requestContext, tracingContext }) => {
+  const span = tracingContext?.currentSpan?.createChildSpan({
+    type: 'generic',
+    name: 'entitlements-lookup',
+  })
+  const skills = await fetchSkillsFor(requestContext.get('userId'))
+  span?.end()
+  return skills
+}
+```
 
 See [Request Context](https://mastra.ai/docs/server/request-context) for more on using request context with agents and workflows.
 

package/.docs/docs/capabilities/channels/overview.md

@@ -153,6 +153,25 @@ When the agent calls this tool, users see a card with the tool name, arguments,
 
 Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode, `autoResumeSuspendedTools` can resume suspended tools when a later user message arrives on the same thread. This requires memory. Hidden mode only suppresses the approval buttons.
 
+## Reply formatting
+
+Agent replies post as markdown by default. Platforms with native markdown rendering, such as Slack, render bold text, links, and tables directly. Other platforms convert the markdown to their own format. Agents write standard markdown and it renders correctly everywhere, matching how the same reply renders in Studio.
+
+Set `textFormat: 'plain'` on an adapter to post replies as literal plain text instead:
+
+```typescript
+channels: {
+  adapters: {
+    slack: {
+      adapter: createSlackAdapter(),
+      textFormat: 'plain',
+    },
+  },
+},
+```
+
+Use this escape hatch if your agent is prompted to emit a platform-specific dialect, such as Slack mrkdwn, instead of standard markdown. If you added such prompt instructions to work around markdown rendering literally, remove them instead. The default now renders standard markdown natively. `textFormat` affects final reply text only. Tool cards, error messages, and natively streamed text are unaffected.
+
 ## Multi-user awareness
 
 In group conversations, Mastra prefixes each message with the sender's name and platform ID so the agent can distinguish between speakers:

package/.docs/docs/capabilities/subagents.md

@@ -104,11 +104,29 @@ const stream = await parentAgent.stream('Research AI trends', {
 
 The `context` object includes:
 
-| Property      | Description                               |
-| ------------- | ----------------------------------------- |
-| `primitiveId` | The ID of the subagent being delegated to |
-| `prompt`      | The prompt the parent agent is sending    |
-| `iteration`   | Current iteration number                  |
+| Property         | Description                                       |
+| ---------------- | ------------------------------------------------- |
+| `primitiveId`    | The ID of the subagent being delegated to         |
+| `prompt`         | The prompt the parent agent is sending            |
+| `iteration`      | Current iteration number                          |
+| `requestContext` | The request context the subagent run will receive |
+
+### Request context at the delegation boundary
+
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+
+```typescript
+const stream = await parentAgent.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    onDelegationStart: async context => {
+      context.requestContext.set('audience', 'technical')
+    },
+  },
+})
+```
+
+The subagent reads these entries in its tools and dynamic configuration, such as `instructions: ({ requestContext }) => ...`. See [Request Context](https://mastra.ai/docs/server/request-context) for details. Values must be JSON-serializable to work with durable agents.
 
 ### `onDelegationComplete`
 

package/.docs/docs/connections/overview.md

@@ -0,0 +1,94 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Connections overview
+
+Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
+
+- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/agents/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/agents/acp): Run compatible coding-agent processes as Mastra tools or subagents.
+- [**SDK agents**](https://mastra.ai/docs/agents/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
+- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/mcp/overview): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+
+## When to use connections
+
+Use connections when you need to:
+
+- Delegate work to an agent running in another service or runtime.
+- Run a coding agent against a project workspace.
+- Add a provider-native agent without replacing its SDK runtime or agent loop.
+- Connect agents to external tools and resources or publish Mastra capabilities to other systems.
+
+## Get started
+
+Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/agents/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/agents/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/agents/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/mcp/overview) for tools and resources.
+
+**A2A**:
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const agent = new A2AAgent({
+  url: 'https://agent.example.com/.well-known/agent-card.json',
+})
+
+const result = await agent.generate('Summarize the latest report')
+console.log(result.text)
+```
+
+**ACP**:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+const agent = new AcpAgent({
+  id: 'coding-agent',
+  description: 'Inspects and edits code',
+  command: 'claude',
+  args: ['--acp'],
+  persistSession: false,
+})
+
+const result = await agent.generate('Review this project')
+console.log(result.text)
+```
+
+**SDK agents**:
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai'
+
+const agent = new OpenAISDKAgent({
+  id: 'openai-agent',
+  description: 'Answers project questions',
+  sdkOptions: {
+    name: 'Project assistant',
+    model: 'gpt-5',
+  },
+})
+
+const result = await agent.generate('Explain agent loops in one sentence')
+console.log(result.text)
+```
+
+**MCP**:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const client = new MCPClient({
+  id: 'wikipedia-client',
+  servers: {
+    wikipedia: {
+      command: 'npx',
+      args: ['-y', 'wikipedia-mcp'],
+    },
+  },
+})
+
+try {
+  const tools = await client.listTools()
+  console.log(Object.keys(tools))
+} finally {
+  await client.disconnect()
+}
+```

package/.docs/docs/datasets/running-experiments.md

@@ -58,6 +58,24 @@ const summary = await dataset.startExperiment({
 
 Each item's `input` is passed directly to `agent.generate()`, so it must be a `string`, `string[]`, or `CoreMessage[]`.
 
+#### Memory-enabled agents
+
+When the target agent has its own memory and the request context carries a resource id (`MASTRA_RESOURCE_ID_KEY`, set by auth middleware, the experiment or item `requestContext`, or the Studio **Run Experiment** form), the experiment runner injects a fresh memory thread for each item. A resource id in the request context means "run as this resource": each item's conversation persists as a thread under that resource, and retried items get a new thread per attempt so earlier failed attempts can't leak into the retry's context.
+
+Injected threads are tagged so you can map them back to the run: thread metadata carries the `experimentId` and the dataset item's id as `experimentItemId`. No thread title is generated for them.
+
+Because the threads belong to the caller's resource, resource-scoped memory features both read and write that resource's state during the run:
+
+- Resource-scoped working memory updates persist to the resource, and later items in the run see updates made by earlier items.
+- Resource-scoped semantic recall can surface the resource's prior conversations to the experiment, and experiment transcripts become recallable in that resource's later conversations.
+
+This is useful when you want to evaluate an agent against a real user's accumulated context. If you don't want experiment runs touching real user state, run the experiment with a dedicated evaluation resource id instead.
+
+Thread injection is skipped in the following cases:
+
+- If the request context also sets `MASTRA_THREAD_ID_KEY`, the runner uses that thread as-is, so every item (and retry) shares the same conversation.
+- If the agent has no memory, or the request context has no resource id, the run is memoryless and nothing is persisted.
+
 ### Registered workflow
 
 Point to a workflow registered on your Mastra instance:

package/.docs/docs/evals/overview.md

@@ -75,7 +75,7 @@ export const evaluatedAgent = new Agent({
 
 ### Adding scorers to workflow steps
 
-You can also add scorers to individual workflow steps to evaluate outputs at specific points in your process:
+You can also add scorers to individual workflow steps to evaluate outputs at specific points in your process. Each scorer receives that step's own input and output, so you can measure quality at each step instead of only scoring the final answer:
 
 ```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -83,22 +83,34 @@ import { z } from "zod";
 import { customStepScorer } from "../scorers/custom-step-scorer";
 
 const contentStep = createStep({
+  id: "content-step",
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ content: z.string() }),
   scorers: {
     customStepScorer: {
       scorer: customStepScorer(),
       sampling: {
         type: "ratio",
         rate: 1, // Score every step execution
-      }
-    }
+      },
+    },
+  },
+  execute: async ({ inputData }) => {
+    return { content: await generateContent(inputData.topic) };
   },
 });
 
-export const contentWorkflow = createWorkflow({ ... })
+export const contentWorkflow = createWorkflow({
+  id: "content-workflow",
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ content: z.string() }),
+})
   .then(contentStep)
   .commit();
 ```
 
+For the step-level `scorers` API, see the [Step class reference](https://mastra.ai/reference/workflows/step).
+
 ### How live evaluations work
 
 **Asynchronous execution**: Live evaluations run in the background without blocking your agent responses or workflow execution. This ensures your AI systems maintain their performance while still being monitored.

package/.docs/docs/harness/agent-controller.md

@@ -322,6 +322,10 @@ const controller = new AgentController({
       if (thread.isDM) return message.author.userId
       return defaultResourceId
     },
+    onSessionStart: async ({ session, thread }) => {
+      const plan = await billing.planFor(thread.resourceId)
+      await session.model.switch({ modelId: plan.modelId })
+    },
   },
 })
 
@@ -339,6 +343,8 @@ Point each platform webhook at the controller-specific route:
 
 Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads; an existing thread keeps its stored resource ID.
 
+Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. Use it to apply a model, memory settings, or session state that a channel session would otherwise miss. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+
 Controller channel sessions and auto-approval state are held in memory, so use a long-lived server. Pending approvals and live Session state don't survive process restarts. Adapters that can't render approval controls automatically run tools without an approval prompt so the run doesn't remain suspended.
 
 See [Channels](https://mastra.ai/docs/capabilities/channels/overview) for adapter setup and platform-specific webhook configuration.

package/.docs/docs/harness/overview.md

@@ -0,0 +1,26 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Harness overview
+
+A harness lets an agent pursue long-running, complex goals while keeping its work durable, visible, and steerable. It preserves progress across retries and interruptions, while giving people and other systems a way to inspect progress, add context, approve actions, redirect the agent, or stop it.
+
+In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
+
+[`AgentController`](https://mastra.ai/docs/harness/agent-controller) is a harness designed for interactive agent applications. It extends the base [`Agent`](https://mastra.ai/docs/agents/overview) loop with isolated sessions for each user or task, persistent threads and state, switchable modes and models, tool permissions and approvals, subagent orchestration, and streams for events and display state.
+
+Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
+
+## When to use a harness
+
+Choose a starting point based on what the agent needs. You may use one capability or several.
+
+| If you want to                                                                        | Start here                                                                      | Why                                                                               |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Keep a run available through client disconnects or server restarts                    | [Durable Agents](https://mastra.ai/docs/long-running-agents/durable-agents)     | Persist run state and let clients reconnect to its stream.                        |
+| Run slow tools, workflows, or subagents without blocking                              | [Background Tasks](https://mastra.ai/docs/long-running-agents/background-tasks) | Finish work asynchronously and return its result to the agent.                    |
+| Keep an agent working until it reaches an objective                                   | [Goals](https://mastra.ai/docs/long-running-agents/goals)                       | Evaluate a thread-scoped objective until it's complete or reaches its run budget. |
+| Start work automatically at recurring times                                           | [Schedules](https://mastra.ai/docs/long-running-agents/schedules)               | Start isolated runs or send prompts into an existing thread on a cron schedule.   |
+| Add context, redirect active work, or wake an idle thread                             | [Signals](https://mastra.ai/docs/long-running-agents/signals)                   | Deliver input now or hold it for the next turn.                                   |
+| React to changes in GitHub, Slack, continuous integration, or another external system | [Signal Providers](https://mastra.ai/docs/long-running-agents/signal-providers) | Track subscriptions and forward matching events to agent threads.                 |
+| Build an interactive product with sessions, modes, state, approvals, and events       | [AgentController](https://mastra.ai/docs/harness/agent-controller)              | Host isolated sessions around a shared agent runtime.                             |
+| Let users steer, queue follow-up work, or stop an interactive run                     | [AgentController](https://mastra.ai/docs/harness/agent-controller)              | Expose run controls through each session.                                         |

package/.docs/docs/index.md

@@ -132,7 +132,7 @@ npm create mastra@latest
 **pnpm**:
 
 ```bash
-pnpm create mastra
+pnpm create mastra@latest
 ```
 
 **Yarn**:

package/.docs/docs/mcp/overview.md

@@ -142,6 +142,16 @@ requireToolApproval: ({ toolName }) => toolName.startsWith('delete_')
 
 Treat tool annotations from servers you don't control as untrusted hints. Visit [tool approval](https://mastra.ai/reference/tools/mcp-client) for the callback context and security guidance.
 
+### Security
+
+MCP servers run code and return content on your agent's behalf, so configure them with the same care as any other external dependency:
+
+- **Stdio subprocess environment**: subprocesses inherit only the MCP SDK's curated environment whitelist (for example `PATH` and `HOME` on POSIX), not the full parent environment. Set `inheritDefaultEnv: false` on a server to pass only the variables you list in `env`.
+- **Outbound host restriction**: when HTTP server URLs come from untrusted configuration, set `allowedHosts` to restrict which hosts the client will contact. On the default fetch path this also blocks redirect hops before they're sent; a custom `fetch` gets its final response URL validated after the request runs, so it must enforce redirect policy itself when preventing outbound contact is required.
+- **Tool response trust**: tool results are untrusted model input. Use [input and output processors](https://mastra.ai/docs/agents/processors) to inspect or sanitize content before it reaches the model, and `requireToolApproval` to gate sensitive tools.
+
+Visit the [MCPClient security reference](https://mastra.ai/reference/tools/mcp-client) for enforcement details of each option.
+
 ### MCP registries
 
 Registries provide hosted or packaged MCP servers. The client configuration above works with registry endpoints and commands.

package/.docs/docs/memory/multi-user-threads.md

@@ -156,7 +156,7 @@ const memory = new Memory({
 })
 ```
 
-OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, or `@mastra/mongodb`.
+OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, or `@mastra/oracledb`.
 
 > **Note:** If you switch the Observer to a weaker model and see facts collapse to a generic `User`, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to teach the Observer how to read the `<turn>` tag.
 

package/.docs/docs/memory/observational-memory.md

@@ -94,7 +94,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mysql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mysql`, `@mastra/mongodb`, `@mastra/convex`, and `@mastra/oracledb` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
 
 ## Temporal gap markers
 

package/.docs/docs/memory/semantic-recall.md

@@ -148,6 +148,7 @@ Each vector store page below includes installation instructions, configuration p
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
 - [OpenSearch](https://mastra.ai/reference/vectors/opensearch)
+- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [PostgreSQL](https://mastra.ai/reference/vectors/pg)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
@@ -180,7 +181,7 @@ const agent = new Agent({
 })
 ```
 
-> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, MongoDB, and Upstash storage adapters.
+> **Note:** `scope: 'resource'` is supported by the LibSQL, OracleDB, PostgreSQL, MongoDB, and Upstash storage adapters.
 
 ### Metadata filtering
 

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

@@ -129,6 +129,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 
 - **libSQL** (`@mastra/libsql`)
 - **PostgreSQL** (`@mastra/pg`)
+- **OracleDB** (`@mastra/oracledb`)
 - **Upstash** (`@mastra/upstash`)
 - **MongoDB** (`@mastra/mongodb`)
 

package/.docs/docs/observability/feedback.md

@@ -33,6 +33,22 @@ await mastra.observability.addFeedback({
 })
 ```
 
+## Find the trace for a message
+
+Feedback is usually collected against a message a user has already read, so you need the `traceId` for that message. Assistant messages carry it in `content.metadata`, both in the stream result and when the message is recalled later from memory:
+
+```typescript
+const agent = mastra.getAgent('weatherAgent')
+const memory = await agent.getMemory()
+
+const { messages } = await memory!.recall({ threadId, perPage: false })
+
+const message = messages.find(m => m.id === messageId)
+const traceId = message?.content.metadata?.traceId
+```
+
+The value is the same trace the run reports as `traceId` on its result, so feedback collected at generation time and feedback collected later against a stored message anchor to the same trace. Messages produced while tracing is disabled have no `traceId`.
+
 ## Create feedback
 
 Every `createFeedback()` requires `feedbackType` and `value`. Add `traceId` or `spanId` when the feedback should be anchored to a trace or a specific span. Use `feedbackSource` as optional string metadata, such as `user`, `qa`, `studio`, or `system`.

package/.docs/docs/observability/integrations/exporters/mastra-storage.md

@@ -122,6 +122,7 @@ If you set the strategy to `'auto'`, the `MastraStorageExporter` automatically s
 | **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
 | **[MSSQL](https://mastra.ai/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
 | **[MongoDB](https://mastra.ai/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[OracleDB](https://mastra.ai/reference/storage/oracledb)**     | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
 | **[libSQL](https://mastra.ai/reference/storage/libsql)**         | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
 
 ### Providers without Observability Support

package/.docs/docs/server/auth.md

@@ -17,6 +17,8 @@ Authentication is optional. If no auth is configured, all routes and Studio are
 
 See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for controlling authentication on custom endpoints. Visit the [Studio Auth docs](https://mastra.ai/docs/studio/auth) for more on securing your Studio deployment.
 
+> **Warning:** The default auth configuration protects `/api/*` and treats `/api`, `/api/auth/*` as public. When you set a custom `server.apiPrefix`, those defaults no longer match and built-in routes fall outside the protected pattern. Update `server.auth.protected` and `server.auth.public` to reference your new prefix.
+
 > **Note:** Authentication for Studio is currently supported by the following providers: Simple Auth, JWT, WorkOS, Better Auth, and Google.
 
 ## Available providers

package/.docs/docs/server/mastra-client.md

@@ -69,15 +69,15 @@ The Mastra Client SDK exposes all resources served by the Mastra Server.
 - **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
 - **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: View app performance and trace activity.
 
-## Create and run stored workflows
+## Create and run dynamic workflows
 
-Use `upsertStoredWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.
+Use `upsertDynamicWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.
 
 The following example shows the full lifecycle of a mapping workflow, from creation and inspection through execution and deletion:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
-import type { UpsertStoredWorkflowParams } from '@mastra/client-js'
+import type { UpsertDynamicWorkflowParams } from '@mastra/client-js'
 
 const client = new MastraClient({
   baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
@@ -105,25 +105,25 @@ const definition = {
       }),
     },
   ],
-} satisfies UpsertStoredWorkflowParams
+} satisfies UpsertDynamicWorkflowParams
 
-await client.upsertStoredWorkflow(definition)
+await client.upsertDynamicWorkflow(definition)
 
-const storedWorkflow = client.getStoredWorkflow(definition.id)
-const storedDefinition = await storedWorkflow.details()
+const dynamicWorkflow = client.getDynamicWorkflow(definition.id)
+const dynamicDefinition = await dynamicWorkflow.details()
 
-const workflow = client.getWorkflow(storedDefinition.id)
+const workflow = client.getWorkflow(dynamicDefinition.id)
 const run = await workflow.createRun()
 const result = await run.startAsync({ inputData: { name: 'Ada' } })
 
 console.log(result)
 
-await storedWorkflow.delete()
+await dynamicWorkflow.delete()
 ```
 
-Use `listStoredWorkflows()` to list persisted definitions. Calling `upsertStoredWorkflow()` again with the same `id` replaces the stored definition and live workflow registration.
+Use `listDynamicWorkflows()` to list persisted definitions. Calling `upsertDynamicWorkflow()` again with the same `id` replaces the stored definition and live workflow registration.
 
-> **Warning:** Durable storage requires a configured storage adapter that supports the `workflowDefinitions` domain. Without that domain, Core can register a workflow in memory, but the server's stored-workflow API can't preserve it across restarts.
+> **Warning:** Durable storage requires a configured storage adapter that supports the `workflowDefinitions` domain. Without that domain, Core can register a workflow in memory, but the server's dynamic-workflow API can't preserve it across restarts.
 >
 > Stored definitions support declarative agent, tool, mapping, nested workflow, parallel, foreach, sleep, sleep-until, conditional, and loop entries. They can't contain JavaScript closures. Conditional and loop logic must use the declarative predicate format, and referenced agents, tools, and nested workflows must already be registered.
 >

package/.docs/docs/storage/overview.md

@@ -193,6 +193,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [libSQL](https://mastra.ai/reference/storage/libsql)
 - [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
 - [MongoDB](https://mastra.ai/reference/storage/mongodb)
+- [OracleDB](https://mastra.ai/reference/storage/oracledb)
 - [Upstash](https://mastra.ai/reference/storage/upstash)
 - [Redis](https://mastra.ai/reference/storage/redis)
 - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)

package/.docs/docs/workflows/agents-and-tools.md

@@ -123,7 +123,7 @@ export const testWorkflow = createWorkflow({})
   .commit()
 ```
 
-`.agent()` records a declarative entry in the workflow graph rather than an opaque step, so workflows built this way can be persisted as [stored workflows](https://mastra.ai/docs/workflows/stored-workflows). Visit [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent) for all parameters.
+`.agent()` records a declarative entry in the workflow graph rather than an opaque step, so workflows built this way can be persisted as [dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows). Visit [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent) for all parameters.
 
 ## Using tools in workflows
 
@@ -184,7 +184,7 @@ import { testTool } from '../tools/test-tool'
 export const testWorkflow = createWorkflow({}).then(step1).tool(testTool).commit()
 ```
 
-Like `.agent()`, `.tool()` records a declarative entry, so the workflow can be persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows). Visit [Workflow.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool) for all parameters.
+Like `.agent()`, `.tool()` records a declarative entry, so the workflow can be persisted as a [dynamic workflow](https://mastra.ai/docs/workflows/dynamic-workflows). Visit [Workflow.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool) for all parameters.
 
 ## Related