@mastra/mcp-docs-server 1.1.49-alpha.0 → 1.1.49-alpha.2

package/.docs/docs/harness/tool-approvals.md

@@ -0,0 +1,145 @@
+# 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.
+
+## When to use tool approvals
+
+Use tool approvals when agents have access to destructive or sensitive tools (file writes, command execution, API calls) and you want a human-in-the-loop checkpoint before those tools run.
+
+## Permission policies
+
+Three policies control tool behavior:
+
+- `allow`: The tool runs without prompting
+- `ask`: The tool pauses and emits a `tool_approval_required` event; the user must approve or decline
+- `deny`: The tool is blocked from execution
+
+### Setting policies
+
+Set policies per-category or per-tool. Per-tool policies take precedence over category policies:
+
+```typescript
+// Category-level: all execute tools require approval
+harness.setPermissionForCategory({ category: 'execute', policy: 'ask' })
+
+// Tool-level: this specific tool is always blocked
+harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+```
+
+### Tool categories
+
+The `toolCategoryResolver` maps tool names to categories. Pass it to the Harness constructor:
+
+```typescript
+const harness = new Harness({
+  id: 'my-agent',
+  toolCategoryResolver: toolName => {
+    if (toolName.includes('write') || toolName.includes('delete')) return 'edit'
+    if (toolName.includes('execute')) return 'execute'
+    return 'read'
+  },
+})
+```
+
+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()`:
+
+```typescript
+harness.subscribe(event => {
+  if (event.type === 'tool_approval_required') {
+    // Show approval UI...
+    harness.session.respondToToolApproval({ decision: 'approve' })
+  }
+})
+```
+
+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' })
+```
+
+## 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:
+
+```typescript
+// Grant all edit tools for this session
+harness.session.grantCategory('edit')
+
+// Grant a specific tool
+harness.session.grantTool('mastra_workspace_execute_command')
+
+// Check current grants
+const grants = harness.session.getGrants()
+// { categories: ['edit'], tools: ['mastra_workspace_execute_command'] }
+```
+
+## Tool suspensions
+
+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 => {
+  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
+    const { question } = event.suspendPayload as { question: string }
+    // Show question to user, then resume:
+    harness.respondToToolSuspension({
+      toolCallId: event.toolCallId,
+      resumeData: 'User response here',
+    })
+  }
+})
+```
+
+### Plan approval
+
+The `submit_plan` tool suspends via the same mechanism. Resume with an `action` field:
+
+```typescript
+// Approve the plan
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'approved' },
+})
+
+// Reject with feedback
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'rejected', feedback: 'Needs more detail' },
+})
+```
+
+## Built-in tools
+
+The Harness provides these built-in tools to agents in every mode:
+
+| Tool            | Description                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `ask_user`      | Ask the user a question (free text, single-select, or multi-select) |
+| `submit_plan`   | Submit a plan for user review and approval                          |
+| `task_write`    | Create or replace a structured task list                            |
+| `task_update`   | Update one tracked task by ID                                       |
+| `task_complete` | Mark one tracked task completed                                     |
+| `task_check`    | Check task list completion status                                   |
+| `subagent`      | Spawn a focused subagent (requires `subagents` config)              |
+
+Disable specific built-in tools with `disableBuiltinTools`:
+
+```typescript
+const harness = new Harness({
+  id: 'no-plans',
+  disableBuiltinTools: ['submit_plan'],
+})
+```
+
+## Related
+
+- [Harness overview](https://mastra.ai/docs/harness/overview)
+- [Session](https://mastra.ai/docs/harness/session)
+- [Subagents](https://mastra.ai/docs/harness/subagents)
+- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [API reference](https://mastra.ai/reference/harness/harness-class)

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

@@ -44,7 +44,7 @@ You get a stable API endpoint, environment variable management, custom domain su
 
    If you're not already authenticated, the CLI prompts you to log in. It stores your credentials locally and any subsequent CLI commands use these credentials.
 
-   The command runs `mastra build`, uploads the artifact, builds a Docker image, and deploys it to Railway. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
+   The command runs `mastra build`, uploads the artifact, builds a Docker image, and deploys it. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
 
    > **Note:** Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically. On the first deploy, these seed the project if no env vars are set yet. After that, manage env vars through the web dashboard. Review and sanitize these files before first deploy to avoid uploading development-only or personal secrets.
 
@@ -56,11 +56,11 @@ You get a stable API endpoint, environment variable management, custom domain su
 
 ## Deploy lifecycle
 
-A deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). Only one build runs per project at a time. If multiple deploys queue up, only the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions Railway infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
+A deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). Only one build runs per project at a time. If multiple deploys queue up, only the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
 
 ## Idle behavior
 
-Server on Mastra platform runs on Railway, which can sleep a service after a period of inactivity to save resources. Railway measures inactivity by outbound network traffic. A service is considered idle only after roughly 10 minutes with no outbound packets. Any recurring outbound traffic resets this timer and keeps the service awake.
+Server on Mastra platform can sleep a service after a period of inactivity to save resources. Inactivity is measured by outbound network traffic. A service is considered idle only after roughly 10 minutes with no outbound packets. Any recurring outbound traffic resets this timer and keeps the service awake.
 
 A server that never sleeps usually has a background task or a long-lived connection sending traffic on a timer. Check for the following common causes.