@mastra/mcp-docs-server 1.2.17-alpha.9 → 1.2.18-alpha.1

package/.docs/docs/guides/context-engineering.md

@@ -0,0 +1,297 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Context engineering
+
+A model can only work with the information available in its context window. That might include the current conversation, remembered details, application data, tool results, or relevant passages from a knowledge base.
+
+Context engineering is the practice of deciding what information the model should see and when. The goal isn't to provide as much as possible, but to keep the context relevant and current. Too little context leaves the model without information it needs; too much can make important details harder to find, increase cost, and reduce the quality of the response long before the model reaches its context limit.
+
+Mastra provides different ways to bring information into context, keep it available over time, retrieve it when needed, and reduce or isolate it as a task grows. This guide explains when to use each mechanism and how they fit together.
+
+| Need                                      | Start with                                    | What the model sees                                      |
+| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------- |
+| Stable identity, rules, or constraints    | [Instructions](#instructions)                 | System context on each model call                        |
+| Data from a database or API               | [Tools](#tools)                               | Tool definitions followed by selected results            |
+| Current customer or application data      | [Inline context](#inline-context)             | Data interpolated into the user message                  |
+| A large, stable knowledge base            | [RAG](#rag)                                   | Semantically relevant chunks from an index               |
+| User- or organization-managed documents   | [Filesystems](#filesystems)                   | Files selected through read or search tools              |
+| Recent conversation or durable facts      | [Memory](#memory)                             | History, observations, or retrieved memories             |
+| A long-running conversation               | [Observational Memory](#observational-memory) | Dense observations plus recent unobserved messages       |
+| New events or changing state during a run | [Signals](#signals)                           | User, reactive, notification, or state messages          |
+| Instructions needed only for some tasks   | [Dynamic skills](#dynamic-skills)             | Skill metadata followed by instructions loaded on demand |
+
+## Instructions
+
+An agent's [`instructions`](https://mastra.ai/reference/agents/agent) define its stable identity, behavior, and constraints. They're system messages and appear before conversation messages in the model request.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: `You help customers understand their account.
+    Today is ${new Date().toDateString()}.
+    Use plain language and don't invent account details.`,
+  model: 'openai/gpt-5.6-sol',
+})
+```
+
+Keep instructions focused on behavior that applies to most calls. Adding current account data, retrieved documents, or task-specific details makes the base prompt larger and harder to reuse.
+
+Instructions can also be resolved at runtime from [`RequestContext`](https://mastra.ai/docs/server/request-context):
+
+```typescript
+instructions: ({ requestContext }) => {
+  const name = requestContext.get('name')
+
+  return `You help ${name} understand their account.`
+}
+```
+
+Use `RequestContext` when instructions depend on data that changes with each request, such as the current user, tenant, locale, role, or feature flags. Values that don't come from the request, such as the current date, can be interpolated directly as shown in the first example.
+
+> **Tip:** If the resolved instructions change often, the model provider may not be able to reuse the same prompt cache prefix. Keep the stable part first, and pass frequently changing background through messages or signals instead.
+>
+> Watch [this short video on prompt caching](https://youtu.be/eBB0dBqfvuQ) to learn how cacheable prompt prefixes reduce latency and cost.
+
+## Inline context
+
+Most applications pass runtime context by interpolating relevant values into the current message. This works well when your code has already loaded customer or application data:
+
+```typescript
+const customer = await db.customer.findById(customerId)
+
+await supportAgent.generate(`
+  Customer: ${customer.name}
+  Plan: ${customer.plan}
+  Question: ${question}
+`)
+```
+
+Select and label the fields the model needs instead of serializing an entire database record. This keeps the prompt smaller and makes the meaning of each value clear.
+
+When memory is enabled, Mastra saves the current user message. Don't interpolate sensitive or temporary data that shouldn't appear in conversation history.
+
+For the less common case where background should affect one response without being saved as conversation history, pass a [`context`](https://mastra.ai/reference/agents/generate) message:
+
+```typescript
+await supportAgent.generate('Recommend the next action.', {
+  context: [{ role: 'user', content: 'The customer has an unresolved billing dispute.' }],
+})
+```
+
+The model sees this background for the current execution, but Mastra doesn't save it to memory. Use `context` when persisting the background would pollute the conversation or expose temporary application state on later turns.
+
+## Tools
+
+[Tools](https://mastra.ai/docs/agents/tools) are the recommended way to fetch current data from a database, API, or service. The model decides when it needs the data and supplies the tool arguments, while your application controls the query and returned fields.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const getCustomer = createTool({
+  id: 'get-customer',
+  description: 'Gets the current profile and plan for a customer',
+  inputSchema: z.object({ customerId: z.string() }),
+  execute: async ({ customerId }) => {
+    const customer = await db.customer.findById(customerId)
+    return { name: customer.name, plan: customer.plan, status: customer.status }
+  },
+})
+```
+
+Use [`toModelOutput`](https://mastra.ai/docs/agents/tools) when application code needs the full result but the model needs a smaller representation.
+
+## RAG
+
+[Retrieval-Augmented Generation (RAG)](https://mastra.ai/reference/rag/overview) retrieves semantically relevant chunks from an indexed corpus. It still fits large, stable knowledge bases where users ask open-ended questions that don't map cleanly to structured database queries.
+
+```typescript
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { createVectorQueryTool } from '@mastra/rag'
+
+const knowledgeBase = createVectorQueryTool({
+  vectorStoreName: 'knowledgeBase',
+  indexName: 'support-docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+})
+```
+
+Register the vector store referenced by `vectorStoreName` on the same Mastra instance as the agent. Mastra supports [multiple vector databases](https://mastra.ai/reference/rag/vector-databases). RAG is often exposed through a tool, as in this example. The design choice is whether the agent needs semantic retrieval or can query the source directly.
+
+Many applications now start with direct, source-specific tools. Models have become better at selecting them, and a direct query is often simpler and cheaper because it doesn't require a chunking, embedding, and vector-index pipeline. Choose RAG when semantic search over unstructured content is the actual requirement, then constrain the returned context with metadata filters, reranking, and a conservative `topK`.
+
+## Filesystems
+
+A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives an agent persistent access to documents and other files. Files can live in a local directory or in providers such as Amazon S3, AgentFS, or Google Drive. The agent receives built-in tools to list, read, and search them.
+
+```typescript
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+export const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './knowledge-base' }),
+  bm25: true,
+  autoIndexPaths: ['**/*.md'],
+})
+
+// Agents receive tools including read_file, list_files, grep,
+// mastra_workspace_search, and mastra_workspace_index.
+await workspace.init()
+```
+
+[Workspace search](https://mastra.ai/docs/sandbox/search) supports BM25 keyword search, vector semantic search, or a hybrid of both. Use a filesystem for a personal assistant that works with a user's files or an organization knowledge base that teammates update in a service such as Google Drive. Search runs against the workspace index, so changed files must be indexed before the agent can retrieve their latest contents.
+
+> **Tip:** Filesystem search can also use vectors, so it overlaps with RAG. Choose a filesystem when the source of truth is a set of files that the agent may need to list, read, or update. Choose a standalone RAG pipeline when retrieval is the main requirement and the source content doesn't need to behave like files.
+
+## Memory
+
+[Memory](https://mastra.ai/docs/memory/overview) gives an agent conversational coherence across turns. It brings recent messages and remembered details into context without requiring the application to resend the full transcript on every turn.
+
+Memory requires a storage provider. Each call also identifies a `resource` that owns the memory and a `thread` that identifies the conversation. Reuse both values to continue the same conversation:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const assistant = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      lastMessages: 20,
+    },
+  }),
+})
+
+await assistant.generate('Help me plan the next project milestone.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'project-456',
+  },
+})
+```
+
+The example assumes storage is configured on the registered Mastra instance or directly on `Memory`. `lastMessages` controls how many recent messages Mastra loads from the thread. The default is 10.
+
+Message history works well for shorter conversations where recent turns contain the context the agent needs. For long-running conversations, Mastra recommends [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps recent conversation available and turns older history into a dense observation log.
+
+## Observational Memory
+
+Conversation history grows with every user message, response, and tool call. Even before it reaches the model's hard context limit, a long transcript can increase cost and make relevant details harder for the model to find. Compression replaces old, verbose history with a smaller representation.
+
+[Observational Memory](https://mastra.ai/docs/memory/observational-memory) handles this continuously. An Observer turns older messages and tool interactions into dense observations, while periodic reflection reorganizes and compresses those observations.
+
+You don't need to configure `lastMessages` when Observational Memory is enabled. Observational Memory manages history itself, keeping recent unobserved messages in context and replacing older messages with observations.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const assistant = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+})
+```
+
+After messages are observed, the model receives the observation log, recent messages that haven't been observed, and a continuation reminder. The raw messages remain stored but no longer occupy the active model context.
+
+Observations are added in stable chunks, which helps providers reuse the existing prompt prefix. Observational Memory can also activate buffered observations after a prompt cache is likely to expire or before the agent changes providers.
+
+## Signals
+
+> **Beta:** Signals may change without a major version bump until the API is stable.
+
+[Signals](https://mastra.ai/docs/harness/signals) add messages or system-generated context to a memory-backed thread. Delivery depends on the thread's state: a signal can wake an idle agent or enter an active loop. It can also wait for the next turn or persist without waking the agent.
+
+State signals require memory and an existing thread. Notification inbox signals require a storage adapter with notification support.
+
+| API                 | Use                                                                | Context behavior                                                        |
+| ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `sendMessage()`     | User input that the active agent should see now                    | Enters the active loop or wakes an idle thread                          |
+| `queueMessage()`    | User input that should wait for the next turn                      | Starts after the current run finishes                                   |
+| `sendSignal()`      | Background results, policy reminders, or external events           | Adds reactive or notification context according to its delivery options |
+| `sendStateSignal()` | Browser state, editor state, task state, or another changing value | Maintains a thread-scoped state lane with snapshots and deltas          |
+
+Use `sendSignal()` for context produced by the system rather than the user:
+
+```typescript
+const result = agent.sendSignal(
+  {
+    type: 'notification',
+    contents: 'CI failed on pull request 123: three tests failed.',
+    attributes: { source: 'github', pullRequest: 123 },
+  },
+  {
+    resourceId: 'user-123',
+    threadId: 'project-456',
+  },
+)
+
+await result.accepted
+```
+
+A processor can send a reactive signal during `processInputStep()`. This is useful for guidance that depends on the current step or a recent tool result. Set `transient: true` when the signal should reach only the current model call. Re-send it when needed instead of storing repeated reminders in conversation history.
+
+State signals represent context that changes over time. Mastra tracks snapshots and deltas for each state lane and can reinsert a fresh snapshot after the previous one leaves the active context window. Use `computeStateSignal()` when a processor owns the state. Working memory, browser context, and task lists can use this lane to stay available even after history or Observational Memory removes older messages.
+
+Signals append changing context near the current turn instead of rewriting the agent's base instructions. Transient and state signals can therefore preserve a more stable prompt prefix while keeping current guidance and state visible to the model.
+
+## Dynamic skills
+
+[Agent skills](https://mastra.ai/docs/skills) let an agent load task-specific instructions only when needed instead of carrying every procedure in its base instructions. Use them for specialized guidance that applies to some requests and keep the default context smaller.
+
+## Context control
+
+Context control limits what the model sees as a task grows. Compaction and processors reduce context within one agent, while subagent boundaries control what moves between agents.
+
+### Compaction
+
+If you've used Claude Code, you may have seen compaction happen during a long session. The Mastra team likes to joke, "Friends don't let friends do compaction."
+
+Compaction waits until a conversation reaches a token threshold. It then summarizes the transcript and replaces earlier messages. It's a blunt fallback. The compaction turn adds latency, and a single summary has to represent everything that came before. Repeated summaries can flatten chronology or lose details that later become important.
+
+Prefer [Observational Memory](#observational-memory) for long-running conversations. It can process history asynchronously in the background while preserving temporal context. Reflection revisits accumulated memories and naturally prunes details that no longer matter. Mastra doesn't provide compaction out of the box, though you could implement it with a custom [processor](https://mastra.ai/docs/agents/processors).
+
+### Processors
+
+[Processors](https://mastra.ai/docs/agents/processors) control what enters model context and can rewrite content before a model call. Use them when information should remain in stored history or application output but doesn't need to be sent back to the model on every step.
+
+For example, `ToolCallFilter` removes old tool arguments and results from the next model request without deleting those messages from storage. The model gets a smaller prompt, while your application can still display or inspect the complete interaction.
+
+Use `processInput()` or `processInputStep()` to change the active message list. Those changes may later be saved to memory. Use `processLLMRequest()` when a rewrite should apply only to the current provider call and leave memory untouched.
+
+Mastra includes several controls for common sources of context bloat:
+
+- [`toModelOutput`](https://mastra.ai/docs/agents/tools): Replace a verbose tool result with a smaller model-facing representation.
+- [`ToolCallFilter`](https://mastra.ai/reference/processors/tool-call-filter): Remove old tool calls and results from model input while retaining them in memory and the UI.
+- [`ToolSearchProcessor`](https://mastra.ai/reference/processors/tool-search-processor): Replace a large tool catalog with search and load tools.
+- [`TokenLimiter`](https://mastra.ai/reference/processors/token-limiter-processor): Prune non-system messages until the prompt fits a token budget.
+
+Start with [`toModelOutput`](https://mastra.ai/docs/agents/tools) for verbose tool results and `ToolCallFilter` for old tool interactions. Add `TokenLimiter` as a final budget guard rather than relying on the model's maximum context window.
+
+### Subagents
+
+A common source of context bloat is passing too much information to and from [subagents](https://mastra.ai/docs/subagents). A subagent gets a separate model context for its delegated task, but the boundary still needs deliberate controls.
+
+By default, Mastra forwards the parent's conversation to the subagent. Use `messageFilter` to pass only the messages that specialist needs:
+
+```typescript
+await supervisor.generate('Investigate the failed deployment.', {
+  delegation: {
+    messageFilter: ({ messages }) => messages.slice(-10),
+  },
+})
+```
+
+In the other direction, Mastra returns the subagent's text to the parent model by default while keeping nested tool calls and metadata available to application code. Leave `includeSubAgentToolResultsInModelContext` disabled unless the parent must reason over those details. Use `onDelegationStart` to refine the child prompt and `onDelegationComplete` to reduce or replace the text returned to the parent.
+
+See [Subagents](https://mastra.ai/docs/subagents) for delegation hooks, memory isolation, iteration monitoring, and result controls.

package/.docs/docs/guides/multi-agent-systems.md

@@ -44,7 +44,7 @@ A supervisor pattern keeps one lead agent in control for the full task. The supe
 
 Use this pattern when the task is open-ended and the full sequence isn't known in advance. For example, a research task may require different lines of inquiry based on what earlier steps uncover. A supervisor can adapt as the task unfolds. The tradeoff is that the supervisor becomes the main coordination point. That makes the pattern flexible, but it also means the result depends heavily on good delegation behavior and clear subagent boundaries.
 
-In Mastra, this pattern maps directly to [supervisor agents](https://mastra.ai/docs/capabilities/subagents). A supervisor agent defines subagents on the `agents` property and uses `stream()` or `generate()` to coordinate them. Mastra also provides delegation hooks, message filtering, and memory isolation to help control this pattern.
+In Mastra, this pattern maps directly to [supervisor agents](https://mastra.ai/docs/subagents). A supervisor agent defines subagents on the `agents` property and uses `stream()` or `generate()` to coordinate them. Mastra also provides delegation hooks, message filtering, and memory isolation to help control this pattern.
 
 > **Tip:** Follow the [supervisor agents tutorial](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents) for a step-by-step guide.
 
@@ -60,12 +60,12 @@ Mastra doesn't provide a dedicated council primitive. In Mastra, implement this
 
 These patterns differ mainly in how they distribute control:
 
-| Pattern           | Who stays in control | Use when                                         | Tradeoff                                                 | Mastra implementation                                              |
-| ----------------- | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------ |
-| Handoffs          | Current specialist   | Ownership should move between specialists        | Context transfer becomes more important                  | Agents with workflows and memory                                   |
-| Workflows         | Execution graph      | The path is known in advance                     | Less adaptive when the task changes                      | [Workflows](https://mastra.ai/docs/workflows/overview)             |
-| Supervisor agents | One lead agent       | Delegation must adapt during execution           | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) |
-| Council           | Final synthesis step | The task needs multiple independent perspectives | Higher cost and latency                                  | Agents with workflow parallelism                                   |
+| Pattern           | Who stays in control | Use when                                         | Tradeoff                                                 | Mastra implementation                                  |
+| ----------------- | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------ |
+| Handoffs          | Current specialist   | Ownership should move between specialists        | Context transfer becomes more important                  | Agents with workflows and memory                       |
+| Workflows         | Execution graph      | The path is known in advance                     | Less adaptive when the task changes                      | [Workflows](https://mastra.ai/docs/workflows/overview) |
+| Supervisor agents | One lead agent       | Delegation must adapt during execution           | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/subagents)  |
+| Council           | Final synthesis step | The task needs multiple independent perspectives | Higher cost and latency                                  | Agents with workflow parallelism                       |
 
 In practice, these patterns are often combined:
 

package/.docs/docs/guides/streaming.md

@@ -31,7 +31,7 @@ for await (const chunk of stream.textStream) {
 
 Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
-> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
+> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/harness/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
 
 ### Output from `Agent.stream()`
 

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

@@ -8,6 +8,8 @@
 
 [Mastra Code](https://code.mastra.ai) and [Mastra Factory](https://factory.mastra.ai) are the flagship AgentController implementations. They're coding agents with multi-model support, persistent conversations, and plan-then-execute workflows. Read [Building a coding agent](https://mastra.ai/blog/building-a-coding-agent) for a step-by-step TUI guide.
 
+When the agent you host works in a codebase, build it with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) instead of `new Agent()`. It returns a standard `Agent` that already has a workspace, task tracking, and retries for transient model errors, which are the defaults Mastra Code runs on.
+
 ## When to use the Agent Controller
 
 Use the Agent Controller when your application needs:
@@ -388,7 +390,7 @@ channels: {
 
 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) for adapter setup and platform-specific webhook configuration.
+See [Channels](https://mastra.ai/docs/channels) for adapter setup and platform-specific webhook configuration.
 
 ## Connect a UI
 
@@ -412,6 +414,6 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 ## Related
 
 - [Agents](https://mastra.ai/docs/agents/overview)
-- [Workspace](https://mastra.ai/docs/workspace/sandbox)
+- [Workspace](https://mastra.ai/docs/sandbox/overview)
 - [Observational memory](https://mastra.ai/docs/memory/observational-memory)
-- [Channels](https://mastra.ai/docs/capabilities/channels)
+- [Channels](https://mastra.ai/docs/channels)

package/.docs/docs/{long-running-agents → harness}/background-tasks.md

@@ -16,7 +16,7 @@ Use background tasks when a tool call may take long enough that the user shouldn
 
 For tool calls that return quickly, foreground execution using `agent.stream()` and `agent.generate()` is simpler.
 
-> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/storage/overview) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
+> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/storage) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
 
 ## Quickstart
 
@@ -121,7 +121,7 @@ If the agent has `backgroundTasks.disabled: true`, every tool call runs synchron
 
 ## Background tasks related stream chunks
 
-When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/long-running-agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
+When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/harness/background-tasks) SSE stream. Each stream covers a different set of chunk types:
 
 | Chunk type                  | When it fires                                                                          | Emitted by     |
 | --------------------------- | -------------------------------------------------------------------------------------- | -------------- |
@@ -376,7 +376,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
-- [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
-- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
+- [Durable agents](https://mastra.ai/docs/harness/durable-agents)
+- [Supervisor agents](https://mastra.ai/docs/subagents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
-- [Storage](https://mastra.ai/docs/storage/overview)
+- [Storage](https://mastra.ai/docs/storage)

package/.docs/docs/{long-running-agents → harness}/durable-agents.md

@@ -118,6 +118,22 @@ const agent = new Agent({
 export const eventedWriter = createEventedAgent({ agent })
 ```
 
+### Stored agents created through the API
+
+Agents created with [`createStoredAgent()`](https://mastra.ai/reference/client-js/agents) opt in with a `durable` field on the agent config. The server wraps the agent with `createDurableAgent()` when it hydrates it, so no code deployment is needed:
+
+```typescript
+await mastraClient.createStoredAgent({
+  id: 'helper',
+  name: 'Helper',
+  instructions: 'You are a helpful assistant.',
+  model: { provider: 'openai', name: 'gpt-5' },
+  durable: true,
+})
+```
+
+`durable` also accepts `{ maxSteps, cleanupTimeoutMs }`. Cache and pubsub are inherited from the server's `Mastra` instance, so configure distributed backends there if you need durability across replicas. Automatic recovery is still configured in code through `recovery.durableAgents`.
+
 ### Inngest-powered with `createInngestAgent()`
 
 Run the workflow on the [Inngest](https://www.inngest.com/docs) platform. Each tool call becomes a memoized step that Inngest can retry independently, and you get a dashboard for monitoring runs:
@@ -198,7 +214,7 @@ await durableAgent.stream('Research topic', {
 })
 ```
 
-Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
+Visit [Background tasks](https://mastra.ai/docs/harness/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
 
 ## Cleanup
 
@@ -267,7 +283,7 @@ Mastra doesn't provide a distributed lease or lock yet. In multi-replica deploym
 
 - [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent)
 - [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent)
-- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/harness/background-tasks)
 - [Inngest deployment guide](https://mastra.ai/integrations/deploy/inngest)
 - [Agent overview](https://mastra.ai/docs/agents/overview)
 - [Worker overview](https://mastra.ai/docs/deployment/workers)

package/.docs/docs/{long-running-agents → harness}/goals.md

@@ -10,7 +10,7 @@ A goal is a durable, thread-scoped objective: a standing instruction the agent k
 
 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/capabilities/subagents): 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.
+Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/subagents): 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.
 
 ## When to use goals
 
@@ -20,11 +20,11 @@ Use a goal when you want an agent to keep working toward a single objective acro
 - Work that should continue across mid-run messages (a message delivered into a live run is still judged against the goal).
 - An objective that must persist across thread reloads or process restarts.
 
-For a one-off completion check within a single `stream()` call, use [`isTaskComplete`](https://mastra.ai/docs/capabilities/subagents) instead.
+For a one-off completion check within a single `stream()` call, use [`isTaskComplete`](https://mastra.ai/docs/subagents) instead.
 
 ## 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) 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'
@@ -113,7 +113,7 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents): `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/subagents): `isTaskComplete` and the rubric scorer
+- [Signal providers](https://mastra.ai/docs/harness/signal-providers): How the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/storage): The storage backend goals require
 - [Mastra Factory](https://factory.mastra.ai) and [Mastra Code](https://code.mastra.ai): Examples of goal-driven coding agents

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

@@ -12,13 +12,14 @@ In Mastra, harness refers to a set of capabilities for managing an agent beyond
 
 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.                                         |
+| If you want to                                                                        | Start here                                                                            | Why                                                                                     |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Keep a run available through client disconnects or server restarts                    | [Durable Agents](https://mastra.ai/docs/harness/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/harness/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/harness/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/harness/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/harness/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/harness/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.                                               |
+| Give an agent files, a shell, and the defaults a coding agent needs                   | [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) | Build a standard agent with a workspace, task tracking, and retries already configured. |

package/.docs/docs/{long-running-agents → harness}/schedules.md

@@ -6,11 +6,11 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/harness/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 
 Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 
-> **Note:** Schedules require a [storage](https://mastra.ai/docs/storage/overview) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
+> **Note:** Schedules require a [storage](https://mastra.ai/docs/storage) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
 
 ## Quickstart
 
@@ -71,7 +71,7 @@ Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing i
 
 ### Threaded
 
-With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/long-running-agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded schedules require a `resourceId` alongside the `threadId`.
+With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/harness/signals) into that thread, so the prompt joins the agent's conversation. Threaded schedules require a `resourceId` alongside the `threadId`.
 
 ```typescript
 await mastra.schedules.create({
@@ -83,7 +83,7 @@ await mastra.schedules.create({
 })
 ```
 
-Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
+Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/harness/signals) accepts and stay JSON-serializable so they persist with the schedule.
 
 These fields require a `threadId`. For the full threaded input shape, see the [agent schedule input reference](https://mastra.ai/reference/schedules/overview).
 
@@ -197,5 +197,5 @@ Hook exceptions are caught and logged. They never re-route the worker or trigger
 ## Related
 
 - [`mastra.schedules`](https://mastra.ai/reference/schedules/overview): API reference for creating and managing schedules.
-- [Signals](https://mastra.ai/docs/long-running-agents/signals): the delivery mechanism behind threaded schedules.
+- [Signals](https://mastra.ai/docs/harness/signals): the delivery mechanism behind threaded schedules.
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): declare a cron schedule on a workflow definition.

package/.docs/docs/{long-running-agents → harness}/signal-providers.md

@@ -6,7 +6,7 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/long-running-agents/signals) into subscribed agent threads.
+A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/harness/signals) into subscribed agent threads.
 
 ## When to use a signal provider
 
@@ -20,7 +20,7 @@ If you only need to push a one-off event into a thread, call [`agent.sendNotific
 
 ## How signal providers work
 
-A signal provider is the producing side of the [signals](https://mastra.ai/docs/long-running-agents/signals) system. It brings external events into a thread, while the signal APIs control how the thread consumes them.
+A signal provider is the producing side of the [signals](https://mastra.ai/docs/harness/signals) system. It brings external events into a thread, while the signal APIs control how the thread consumes them.
 
 A signal provider combines three capabilities:
 
@@ -205,7 +205,7 @@ For a production provider that watches GitHub pull requests, see the [GitHub Cha
 ## Related
 
 - [Guide: Building a signal provider](https://mastra.ai/blog/building-a-signal-provider)
-- [Signals](https://mastra.ai/docs/long-running-agents/signals)
-- [Notification signals](https://mastra.ai/docs/long-running-agents/signals)
+- [Signals](https://mastra.ai/docs/harness/signals)
+- [Notification signals](https://mastra.ai/docs/harness/signals)
 - [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider)
 - [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)

package/.docs/docs/mastra-platform/deploy.md

@@ -63,7 +63,7 @@ A local `.env` file is optional. Environment variables stored on the platform ar
 
 4. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
 
-   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.
 
 The first deploy writes a `.mastra-project.json` file linking your directory to the platform project. Commit it so later deploys, CI runs, and [`mastra env`](https://mastra.ai/docs/mastra-platform/environments) commands target the same project without extra flags.
 

package/.docs/docs/mastra-platform/overview.md

@@ -29,7 +29,7 @@ Choose the path that matches what you want to do:
 Your Mastra application is built from three building blocks:
 
 - [Agents](https://mastra.ai/docs/agents/overview): AI agents that can use tools and follow instructions while maintaining context
-- [Tools](https://mastra.ai/docs/agents/using-tools): Callable functions and integrations available to your agents
+- [Tools](https://mastra.ai/docs/agents/tools): Callable functions and integrations available to your agents
 - [Workflows](https://mastra.ai/docs/workflows/overview): Multi-step orchestration pipelines that coordinate agents and tools
 
 ## Going to production

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

@@ -56,7 +56,7 @@ You get a stable API endpoint with environment variable management and custom do
 
 4. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
 
-   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.
 
 ## Deploy lifecycle
 

package/.docs/docs/memory/message-history.md

@@ -25,7 +25,7 @@ Studio automatically generates a thread and resource ID for you. When calling `s
 
 ## Getting started
 
-Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/storage/overview) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
 
 **npm**: