@mastra/mcp-docs-server 1.2.2 → 1.2.3-alpha.1

package/.docs/docs/{harness → agent-controller}/tool-approvals.md

@@ -1,6 +1,6 @@
 # Tool approvals and permissions
 
-The Harness provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.
+The AgentController provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.
 
 ## Permission policies
 
@@ -16,18 +16,18 @@ Set policies per-category or per-tool. Per-tool policies take precedence over ca
 
 ```typescript
 // Category-level: all execute tools require approval
-await harness.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
+await agentController.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
 
 // Tool-level: this specific tool is always blocked
-await harness.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+await agentController.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
 ```
 
 ### Tool categories
 
-The `toolCategoryResolver` maps tool names to categories. Pass it to the Harness constructor:
+The `toolCategoryResolver` maps tool names to categories. Pass it to the AgentController constructor:
 
 ```typescript
-const harness = new Harness({
+const agentController = new AgentController({
   id: 'my-agent',
   toolCategoryResolver: toolName => {
     if (toolName.includes('write') || toolName.includes('delete')) return 'edit'
@@ -41,13 +41,13 @@ Built-in categories are `read`, `edit`, `execute`, `mcp`, and `other`.
 
 ## Responding to approval requests
 
-When a tool's policy is `ask`, the Harness emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
+When a tool's policy is `ask`, the AgentController emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
 
 ```typescript
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'tool_approval_required') {
     // Show approval UI...
-    harness.session.respondToToolApproval({ decision: 'approve' })
+    agentController.session.respondToToolApproval({ decision: 'approve' })
   }
 })
 ```
@@ -55,22 +55,22 @@ harness.subscribe(event => {
 The `decision` field accepts `'approve'`, `'decline'`, or `'always_allow_category'`. When `always_allow_category` is used, the tool's category is granted for the rest of the session. Future tools in the same category are auto-approved.
 
 ```typescript
-harness.session.respondToToolApproval({ decision: 'always_allow_category' })
+agentController.session.respondToToolApproval({ decision: 'always_allow_category' })
 ```
 
 ## Session grants
 
-The Harness owns permission _policy_ (which categories require approval); the [`Session`](https://mastra.ai/docs/harness/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
+The AgentController owns permission _policy_ (which categories require approval); the [`Session`](https://mastra.ai/docs/agent-controller/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
 
 ```typescript
 // Grant all edit tools for this session
-harness.session.grantCategory('edit')
+agentController.session.grantCategory('edit')
 
 // Grant a specific tool
-harness.session.grantTool('mastra_workspace_execute_command')
+agentController.session.grantTool('mastra_workspace_execute_command')
 
 // Check current grants
-const grants = harness.session.getGrants()
+const grants = agentController.session.getGrants()
 // { categories: ['edit'], tools: ['mastra_workspace_execute_command'] }
 ```
 
@@ -79,11 +79,11 @@ const grants = harness.session.getGrants()
 Interactive built-in tools (`ask_user`, `submit_plan`) use the native tool-suspension primitive instead of the approval flow. They emit a `tool_suspended` event with `toolCallId`, `toolName`, and `suspendPayload`. Resume with `respondToToolSuspension()`:
 
 ```typescript
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
     const { question } = event.suspendPayload as { question: string }
     // Show question to user, then resume:
-    harness.respondToToolSuspension({
+    agentController.respondToToolSuspension({
       toolCallId: event.toolCallId,
       resumeData: 'User response here',
     })
@@ -97,13 +97,13 @@ The `submit_plan` tool suspends via the same mechanism. Resume with an `action`
 
 ```typescript
 // Approve the plan
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: { action: 'approved' },
 })
 
 // Reject with feedback
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: { action: 'rejected', feedback: 'Needs more detail' },
 })
@@ -111,7 +111,7 @@ harness.respondToToolSuspension({
 
 ## Built-in tools
 
-The Harness provides these built-in tools to agents in every mode:
+The AgentController provides these built-in tools to agents in every mode:
 
 | Tool            | Description                                                         |
 | --------------- | ------------------------------------------------------------------- |
@@ -126,7 +126,7 @@ The Harness provides these built-in tools to agents in every mode:
 Disable specific built-in tools with `disableBuiltinTools`:
 
 ```typescript
-const harness = new Harness({
+const agentController = new AgentController({
   id: 'no-plans',
   disableBuiltinTools: ['submit_plan'],
 })
@@ -134,8 +134,8 @@ const harness = new Harness({
 
 ## Related
 
-- [Harness overview](https://mastra.ai/docs/harness/overview)
-- [Session](https://mastra.ai/docs/harness/session)
-- [Subagents](https://mastra.ai/docs/harness/subagents)
+- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
+- [Session](https://mastra.ai/docs/agent-controller/session)
+- [Subagents](https://mastra.ai/docs/agent-controller/subagents)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
-- [API reference](https://mastra.ai/reference/harness/harness-class)
+- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/docs/agents/channels.md

@@ -164,6 +164,53 @@ By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupporte
 
 > **Note:** See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced mime types.
 
+## Serverless deployment
+
+On serverless platforms like Vercel, each request runs in a separate, short-lived instance. Channels need two things to work reliably in that environment: a way to keep the function alive while the agent responds, and a shared pub/sub so instances can coordinate.
+
+### Keep the function alive with `waitUntil`
+
+A channel webhook returns a `200` response right away, then the agent runs in the background to post its reply. On most serverless platforms the function is frozen as soon as it responds, which kills the run before the agent answers. Pass a `waitUntil` function so the platform keeps the instance alive until the run finishes.
+
+On Vercel, pass `waitUntil` from `@vercel/functions`:
+
+```typescript
+import { waitUntil } from '@vercel/functions'
+
+export const agent = new Agent({
+  // ...
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+    waitUntil,
+  },
+})
+```
+
+Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soon as the response is sent. Cloudflare Workers and Netlify Functions are detected automatically from the request context, so they don't need it. For runtimes where `waitUntil` lives on the request context but isn't detected automatically, use `resolveWaitUntil`. See the [Channels reference](https://mastra.ai/reference/agents/channels) for details.
+
+### Coordinate instances with a shared pub/sub
+
+Channels route messages through the agent's signal pipeline, and each run acquires a lease on its thread so a single run owns the conversation at a time. The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can land on a different instance than the one running the agent. Without a shared pub/sub, that instance can't reach the active run and starts its own, leaving the original run untouched and the thread processed twice.
+
+Configure a shared pub/sub backed by Redis Streams on the `Mastra` instance so leases and signals coordinate across instances:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  agents: { agent },
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL,
+    keyPrefix: 'mastra:my-app',
+  }),
+})
+```
+
+Vercel's one-click Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
+
 ## Related
 
 - [Guide: Building a Slack assistant](https://mastra.ai/guides/guide/slack-assistant)

package/.docs/models/gateways/vercel.md

@@ -1,6 +1,6 @@
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 292 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 293 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -267,6 +267,7 @@ ANTHROPIC_API_KEY=ant-...
 | `perplexity/sonar-pro`                   |
 | `perplexity/sonar-reasoning-pro`         |
 | `prodia/flux-fast-schnell`               |
+| `quiverai/arrow-1.1`                     |
 | `recraft/recraft-v2`                     |
 | `recraft/recraft-v3`                     |
 | `recraft/recraft-v4`                     |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4540 models from 133 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4548 models from 134 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/tinfoil.md

@@ -0,0 +1,77 @@
+# ![Tinfoil logo](https://models.dev/logos/tinfoil.svg)Tinfoil
+
+Access 7 Tinfoil models through Mastra's model router. Authentication is handled automatically using the `TINFOIL_API_KEY` environment variable.
+
+Learn more in the [Tinfoil documentation](https://docs.tinfoil.sh).
+
+```bash
+TINFOIL_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "tinfoil/gemma4-31b"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Tinfoil documentation](https://docs.tinfoil.sh) for details.
+
+## Models
+
+| Model                            | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| -------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `tinfoil/gemma4-31b`             | 256K    |       |           |       |       |       | $0.40      | $1          |
+| `tinfoil/glm-5-2`                | 384K    |       |           |       |       |       | $2         | $5          |
+| `tinfoil/gpt-oss-120b`           | 131K    |       |           |       |       |       | $0.15      | $0.60       |
+| `tinfoil/gpt-oss-safeguard-120b` | 131K    |       |           |       |       |       | $0.15      | $0.60       |
+| `tinfoil/kimi-k2-6`              | 256K    |       |           |       |       |       | $2         | $5          |
+| `tinfoil/llama3-3-70b`           | 128K    |       |           |       |       |       | $2         | $3          |
+| `tinfoil/nomic-embed-text`       | 8K      |       |           |       |       |       | $0.05      | —           |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://inference.tinfoil.sh/v1",
+    id: "tinfoil/gemma4-31b",
+    apiKey: process.env.TINFOIL_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "tinfoil/nomic-embed-text"
+      : "tinfoil/gemma4-31b";
+  }
+});
+```

package/.docs/models/providers.md

@@ -111,6 +111,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Tencent Coding Plan (China)](https://mastra.ai/models/providers/tencent-coding-plan)
 - [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)
 - [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)
+- [Tinfoil](https://mastra.ai/models/providers/tinfoil)
 - [Together AI](https://mastra.ai/models/providers/togetherai)
 - [Umans AI](https://mastra.ai/models/providers/umans-ai)
 - [Umans AI Coding Plan](https://mastra.ai/models/providers/umans-ai-coding-plan)