@mastra/mcp-docs-server 1.1.33-alpha.4 → 1.1.33-alpha.6

package/.docs/docs/agents/guardrails.md

@@ -184,6 +184,28 @@ export const privateAgent = new Agent({
 
 > **Note:** Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) reference for a full list of configuration options.
 
+### Enforce cost limits
+
+The `CostGuardProcessor()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate — metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
+
+```typescript
+import { CostGuardProcessor } from '@mastra/core/processors'
+
+export const budgetedAgent = new Agent({
+  id: 'budgeted-agent',
+  name: 'Budgeted Agent',
+  inputProcessors: [
+    new CostGuardProcessor({
+      maxCost: 5.0,
+      scope: 'thread',
+      window: '24h',
+    }),
+  ],
+})
+```
+
+> **Note:** Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
+
 ## Processor strategies
 
 Many built-in processors support a `strategy` parameter that controls how they handle flagged content. Supported values include: `block`, `warn`, `detect`, `redact`, `rewrite`, and `translate`.
@@ -201,6 +223,44 @@ inputProcessors: [
 ]
 ```
 
+## Violation callbacks
+
+All processors support an `onViolation` callback that fires when a policy violation is detected, regardless of strategy. Use it for side effects like alerting, logging to external systems, or sending notifications.
+
+The callback receives a `ProcessorViolation` object with `processorId`, `message`, and `detail` (processor-specific metadata).
+
+```typescript
+import { CostGuardProcessor, ModerationProcessor, PIIDetector } from '@mastra/core/processors'
+
+// Alert when cost limits are exceeded
+const costGuard = new CostGuardProcessor({
+  maxCost: 10.0,
+  scope: 'resource',
+  window: '30d',
+})
+
+costGuard.onViolation = ({ processorId, message, detail }) => {
+  alertSystem.notify(`[${processorId}] ${message}`)
+  // detail contains: { usage, limit, totalUsage, scope, scopeKey }
+}
+
+// Log moderation violations
+const moderation = new ModerationProcessor({
+  model: 'openai/gpt-5-nano',
+  strategy: 'block',
+})
+
+moderation.onViolation = ({ processorId, message, detail }) => {
+  auditLog.write({ processor: processorId, violation: message, categories: detail })
+}
+```
+
+The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor — including custom ones — can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `CostGuardProcessor`), the callback also fires on warnings without blocking the request.
+
+Errors thrown by the callback are silently caught to prevent interfering with the processor's main logic.
+
+For more on how violation callbacks integrate with the processor pipeline, see [Violation callbacks](https://mastra.ai/docs/agents/processors) in the Processors documentation.
+
 ## Handle blocked requests
 
 When a processor calls `abort()`, the agent stops processing. How you detect this depends on whether you use `generate()` or `stream()`.

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

@@ -657,6 +657,42 @@ The retry mechanism:
 - Tracks retry count via the `retryCount` parameter
 - Respects `maxProcessorRetries` limit on the agent
 
+### Violation callbacks
+
+All processors expose an `onViolation` property that fires whenever a policy violation is detected — both when `abort()` is called (block strategy) and when a processor issues a warning (warn strategy). Use it for alerting, logging, or side effects without affecting the processor's main logic:
+
+```typescript
+import { ModerationProcessor, CostGuardProcessor } from '@mastra/core/processors'
+
+const moderation = new ModerationProcessor({
+  model: 'openai/gpt-5-nano',
+  strategy: 'block',
+})
+
+moderation.onViolation = ({ processorId, message, detail }) => {
+  // Log to external monitoring, send alerts, update dashboards
+  monitor.track('processor_violation', { processorId, message, detail })
+}
+
+const costGuard = new CostGuardProcessor({
+  maxCost: 10.0,
+  scope: 'resource',
+  window: '30d',
+})
+
+costGuard.onViolation = ({ processorId, message, detail }) => {
+  alertSystem.notify(`[${processorId}] ${message}`)
+}
+```
+
+The callback receives a `ProcessorViolation` object with:
+
+- `processorId`: The ID of the processor that detected the violation
+- `message`: A human-readable description of what was violated
+- `detail`: Processor-specific metadata (e.g. cost usage, detected PII types, moderation categories)
+
+`onViolation` is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any custom processor can use it too. The runner automatically invokes it when any processor calls `abort()`. Errors thrown inside the callback are silently caught to prevent interfering with the processor pipeline.
+
 ### Abort and tripwire chunks
 
 Calling `abort(reason, options)` throws a `TripWire` error that ends processing. On streams, Mastra emits a `tripwire` chunk clients can detect:

package/.docs/docs/deployment/workflow-runners.md

@@ -6,4 +6,10 @@ Mastra [workflows](https://mastra.ai/docs/workflows/overview) can be executed us
 
 Inngest is a developer platform for running background workflows without managing infrastructure. Mastra workflows can be deployed to Inngest, which provides step memoization, automatic retries, real-time monitoring, and suspend/resume capabilities.
 
-Visit the [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest) for setup instructions and the [Inngest workflow example](https://github.com/mastra-ai/mastra/tree/main/examples/inngest) for a complete implementation.
+Visit the [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest) for setup instructions and the [Inngest workflow example](https://github.com/mastra-ai/mastra/tree/main/examples/inngest) for a complete implementation.
+
+## Temporal
+
+Temporal is a durable execution platform for orchestrating long-running workflows. Mastra workflows can run on Temporal workers, with each `createStep` mapped to a Temporal activity for automatic retries and durable state.
+
+The `@mastra/temporal` package is experimental and not ready for production use. Visit the [Temporal deployment guide](https://mastra.ai/guides/deployment/temporal) for setup instructions.

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

@@ -332,6 +332,31 @@ const mcp = new MCPClient({
 })
 ```
 
+**Apify**:
+
+[Apify](https://apify.com) is the largest marketplace of tools for AI, with thousands of ready-made [Actors](https://apify.com/store) to extract real-time data from any website, track competitors, generate leads, analyze sentiment, or orchestrate your apps. Connect your agent through the [Apify MCP Server](https://mcp.apify.com).
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+export const mcp = new MCPClient({
+  servers: {
+    apify: {
+      url: new URL('https://mcp.apify.com'),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer ${process.env.APIFY_TOKEN}`,
+        },
+      },
+    },
+  },
+})
+```
+
+Get your API token from the [Apify Console](https://console.apify.com/settings/integrations) and store it as `APIFY_TOKEN` in your environment.
+
+To pick specific Actors and tools, use the [Apify MCP server configurator](https://mcp.apify.com) and copy the generated URL.
+
 **Ampersand**:
 
 [Ampersand](https://withampersand.com?utm_source=mastra-docs) offers an [MCP Server](https://docs.withampersand.com/mcp) that allows you to connect your agent to 150+ integrations with SaaS products like Salesforce, Hubspot, and Zendesk.

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

@@ -0,0 +1,141 @@
+# Fine-Grained Authorization (FGA)
+
+Fine-Grained Authorization (FGA) adds resource-level permission checks to your Mastra application. While RBAC answers "can this role do this action?", FGA answers **"can this user do this action on this specific resource?"**
+
+## When to use FGA
+
+FGA is designed for multi-tenant B2B products where permissions are contextual:
+
+- A user might be an **admin** of Team A but only a **member** of Team B
+- Thread access should be limited to the user's own organization
+- Workflow execution should be scoped to a specific team or project
+- Tool access depends on the user's relationship to a resource
+
+## Configuration
+
+Configure FGA in your Mastra server config alongside authentication and RBAC:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { MastraFGAPermissions } from '@mastra/core/auth/ee';
+import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos';
+
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      /* ... */
+      fetchMemberships: true,
+    }),
+    fga: new MastraFGAWorkos({
+      resourceMapping: {
+        agent: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
+        workflow: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
+        thread: { fgaResourceType: 'workspace-thread', deriveId: ({ resourceId }) => resourceId },
+      },
+      permissionMapping: {
+        [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows',
+        [MastraFGAPermissions.WORKFLOWS_EXECUTE]: 'manage-workflows',
+        [MastraFGAPermissions.MEMORY_READ]: 'read',
+        [MastraFGAPermissions.MEMORY_WRITE]: 'update',
+      },
+    }),
+  },
+});
+```
+
+When using `MastraFGAWorkos`, set `fetchMemberships: true` on `MastraAuthWorkos`. WorkOS FGA checks need the user's organization memberships to resolve the correct membership ID for authorization.
+
+Use `thread` as the resource-mapping key for memory authorization. `MastraFGAWorkos` still accepts the legacy alias `memory`, but new configs should prefer `thread`.
+
+### Resource mapping
+
+The `resourceMapping` tells Mastra how to resolve FGA resource types and IDs from request context. Keys are Mastra resource types, values define the FGA resource type and how to derive the ID:
+
+```typescript
+resourceMapping: {
+  // When checking "can user execute agent X?", resolve the FGA resource
+  // as the user's team (type: 'team', id: user.teamId)
+  agent: {
+    fgaResourceType: 'team',
+    deriveId: (ctx) => ctx.user.teamId,
+  },
+}
+```
+
+`deriveId()` receives:
+
+- `user` — the authenticated user
+- `resourceId` — the owning Mastra resource ID when available (for example, a thread's `resourceId`)
+- `requestContext` — the current request context for advanced tenant resolution
+
+Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
+
+For thread and memory checks, Mastra still passes the raw `threadId` as the resource being checked, but it also forwards the thread's owning `resourceId` into `deriveId()`. This lets you map thread permissions to composite tenant IDs such as `userId-teamId-orgId`.
+
+### Permission mapping
+
+The `permissionMapping` translates Mastra's internal permission strings to your FGA provider's permission slugs:
+
+```typescript
+import { MastraFGAPermissions } from '@mastra/core/auth/ee';
+
+permissionMapping: {
+  [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows', // Mastra permission -> WorkOS permission slug
+  [MastraFGAPermissions.MEMORY_READ]: 'read',
+}
+```
+
+If no mapping exists for a permission, the original string is passed through.
+
+## Enforcement points
+
+When an FGA provider is configured, Mastra automatically checks authorization at these lifecycle points:
+
+| Lifecycle point                        | Permission checked                             | Resource                               |
+| -------------------------------------- | ---------------------------------------------- | -------------------------------------- |
+| Agent execution (`generate`, `stream`) | `agents:execute`                               | `{ type: 'agent', id: agentId }`       |
+| Workflow execution                     | `workflows:execute`                            | `{ type: 'workflow', id: workflowId }` |
+| Tool execution                         | `tools:execute`                                | `{ type: 'tool', id: toolName }`       |
+| Thread/memory access                   | `memory:read`, `memory:write`, `memory:delete` | `{ type: 'thread', id: threadId }`     |
+| MCP tool execution                     | `tools:execute`                                | `{ type: 'tool', id: toolName }`       |
+| HTTP routes (opt-in)                   | Configured per route                           | Configured per route                   |
+
+All checks are **no-ops when FGA is not configured**, maintaining backward compatibility.
+
+## Custom FGA provider
+
+Implement `IFGAProvider` to use any FGA backend:
+
+```typescript
+import { FGADeniedError } from '@mastra/core/auth/ee'
+import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'
+
+class MyFGAProvider implements IFGAProvider {
+  async check(user: any, params: FGACheckParams): Promise<boolean> {
+    // Your authorization logic
+    return true
+  }
+
+  async require(user: any, params: FGACheckParams): Promise<void> {
+    const allowed = await this.check(user, params)
+    if (!allowed) {
+      throw new FGADeniedError(user, params.resource, params.permission)
+    }
+  }
+
+  async filterAccessible<T extends { id: string }>(
+    user: any,
+    resources: T[],
+    resourceType: string,
+    permission: MastraFGAPermissionInput,
+  ): Promise<T[]> {
+    // Filter resources the user can access
+    return resources
+  }
+}
+```
+
+## Related
+
+- [Authentication overview](https://mastra.ai/docs/server/auth)
+- [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)

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

@@ -81,16 +81,34 @@ export const mastra = new Mastra({
 
 ## Configuration
 
-### User Authorization
+### Default authorization
 
-By default, `MastraAuthWorkos` checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:
+By default, `MastraAuthWorkos` grants access to any authenticated WorkOS user. The authorization check succeeds when the resolved user object contains both a Mastra user ID and a WorkOS user ID.
 
-1. Retrieves the user's organization memberships using their user ID
-2. Extracts all roles from their memberships
-3. Checks if any role has the slug 'admin'
-4. Grants access only if the user has admin role in at least one organization
+### FGA membership loading
 
-To customize user authorization, provide a custom `authorizeUser` function:
+Set `fetchMemberships: true` when you use [`MastraFGAWorkos`](https://mastra.ai/docs/server/auth/fga). This tells the auth provider to load the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.
+
+```typescript
+import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos'
+
+const workosAuth = new MastraAuthWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+  fetchMemberships: true,
+})
+
+const workosFga = new MastraFGAWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+})
+```
+
+When `fetchMemberships` is `false`, Mastra skips the extra WorkOS `listOrganizationMemberships()` call on each authenticated request.
+
+### Service tokens and custom JWT templates
+
+For machine-to-machine or service-account access, you can configure `MastraAuthWorkos` to trust verified bearer-token claims from a WorkOS custom JWT template.
 
 ```typescript
 import { MastraAuthWorkos } from '@mastra/auth-workos'
@@ -98,12 +116,37 @@ import { MastraAuthWorkos } from '@mastra/auth-workos'
 const workosAuth = new MastraAuthWorkos({
   apiKey: process.env.WORKOS_API_KEY,
   clientId: process.env.WORKOS_CLIENT_ID,
-  authorizeUser: async user => {
-    return !!user
+  redirectUri: process.env.WORKOS_REDIRECT_URI,
+  trustJwtClaims: true,
+  jwtClaims: {
+    organizationId: 'org_id',
+    organizationMembershipId: 'urn:mastra:organization_membership_id',
   },
 })
 ```
 
+This is useful when your JWT template already includes the exact FGA context Mastra needs, such as `organizationMembershipId`, tenant IDs, or service-principal identifiers. When `trustJwtClaims` is enabled, Mastra can fall back to those verified claims if a bearer token is not meant to round-trip through `workos.userManagement.getUser()`.
+
+### Custom authorization
+
+If you need stricter authorization, subclass `MastraAuthWorkos` and override `authorizeUser()`:
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+import type { HonoRequest } from 'hono'
+
+class AdminOnlyWorkosAuth extends MastraAuthWorkos {
+  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
+    return user?.metadata?.role === 'admin'
+  }
+}
+
+const workosAuth = new AdminOnlyWorkosAuth({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+})
+```
+
 > **Info:** Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
 
 ## Client-side setup

package/.docs/guides/deployment/temporal.md

@@ -0,0 +1,232 @@
+# Temporal workflow
+
+[Temporal](https://temporal.io/) is a durable execution platform for orchestrating long-running, fault-tolerant workflows. The `@mastra/temporal` package lets you author workflows with the standard Mastra API and run them on a Temporal cluster.
+
+> **Warning:** `@mastra/temporal` is experimental and not ready for production use. The API may change between releases. See the [package README](https://github.com/mastra-ai/mastra/tree/main/workflows/temporal) for the current state.
+
+## How Temporal works with Mastra
+
+Mastra workflows authored with `createWorkflow()` and `createStep()` map onto Temporal's workflow and activity model. The `MastraPlugin` for the Temporal worker compiles your Mastra entry file at bundle time:
+
+- Each `createStep()` handler is extracted into a Temporal activity.
+- Each `createWorkflow()` is rewritten into a Temporal workflow that invokes those activities.
+- The plugin registers the generated activities and workflows with the worker automatically.
+
+When a run starts through `mastra.getWorkflow(...).createRun().start(...)`, the Mastra client hands control to Temporal. Temporal then drives durable execution, retries, and state persistence on the worker.
+
+## Setup
+
+Install the required packages:
+
+**npm**:
+
+```bash
+npm install @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
+```
+
+You also need access to a Temporal cluster. For local development, you can run one with Docker (see [Running locally](#running-locally)).
+
+## Building a Temporal-backed workflow
+
+This guide walks through creating a workflow with Temporal and Mastra, demonstrating a counter application that increments a value.
+
+### Temporal initialization
+
+Initialize the Temporal integration to obtain Mastra-compatible workflow helpers. The `createWorkflow()` and `createStep()` functions are bound to a Temporal client and a task queue.
+
+```ts
+import { init } from '@mastra/temporal'
+import { Client, Connection } from '@temporalio/client'
+import { loadClientConnectConfig } from '@temporalio/envconfig'
+
+const config = loadClientConnectConfig()
+const connection = await Connection.connect(config.connectionOptions)
+const client = new Client({ connection })
+
+export const { createWorkflow, createStep } = init({
+  client,
+  taskQueue: 'mastra',
+})
+```
+
+`loadClientConnectConfig()` reads standard Temporal environment variables such as `TEMPORAL_ADDRESS`, `TEMPORAL_NAMESPACE`, and mTLS settings. See the [Temporal envconfig docs](https://docs.temporal.io/develop/typescript/temporal-clients) for the full list.
+
+### Creating steps
+
+Define the individual steps that will compose your workflow. Each step becomes a Temporal activity.
+
+```ts
+import { z } from 'zod'
+import { createWorkflow, createStep } from '../temporal'
+
+const incrementStep = createStep({
+  id: 'increment',
+  inputSchema: z.object({
+    value: z.number(),
+  }),
+  outputSchema: z.object({
+    value: z.number(),
+  }),
+  execute: async ({ inputData }) => {
+    return { value: inputData.value + 1 }
+  },
+})
+```
+
+### Creating the workflow
+
+Compose the steps into a workflow. The workflow `id` must be a static string literal so the build-time transformer can derive its Temporal export name.
+
+```ts
+const workflow = createWorkflow({
+  id: 'increment-workflow',
+  steps: [incrementStep],
+  inputSchema: z.object({
+    value: z.number(),
+  }),
+  outputSchema: z.object({
+    value: z.number(),
+  }),
+}).then(incrementStep)
+
+workflow.commit()
+
+export { workflow as incrementWorkflow }
+```
+
+### Configuring the Mastra instance
+
+Register the workflow with Mastra. The execution is driven by the Temporal worker.
+
+```ts
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+import { incrementWorkflow } from './workflows'
+
+export const mastra = new Mastra({
+  workflows: { incrementWorkflow },
+  logger: new PinoLogger({ name: 'Mastra', level: 'info' }),
+})
+```
+
+## Running the worker
+
+The worker is a long-lived Node.js process that polls a Temporal task queue. Install `MastraPlugin` and point its `src` option at the Mastra entry file that registers your workflows.
+
+```ts
+import { MastraPlugin } from '@mastra/temporal/worker'
+import { NativeConnection, Worker } from '@temporalio/worker'
+
+const connection = await NativeConnection.connect({
+  address: 'localhost:7233',
+})
+
+const mastraPlugin = new MastraPlugin()
+
+await mastraPlugin.prebuild({
+  entryFile: import.meta.resolve('./index.ts'),
+})
+
+const worker = await Worker.create({
+  connection,
+  namespace: 'default',
+  taskQueue: 'mastra',
+  plugins: [mastraPlugin],
+})
+
+await worker.run()
+```
+
+`MastraPlugin` rewrites the entry file into a workflow-only bundle and wires step handlers in as Temporal activities. You do not need to pass `activities` or `workflowsPath` to `Worker.create()` manually.
+
+## Running workflows
+
+### Running locally
+
+1. Start a local Temporal server. The simplest option is the `temporalio/auto-setup` Docker image:
+
+   ```bash
+   docker run --rm -p 7233:7233 -p 8080:8080 temporalio/auto-setup:latest
+   ```
+
+2. Open the Temporal UI at <http://localhost:8080> to inspect namespaces, workflows, and activities.
+
+3. Start the worker. In a new terminal, run:
+
+   ```bash
+   npx tsx src/mastra/worker.ts
+   ```
+
+4. Trigger a workflow run from a script or any process that imports your Mastra instance:
+
+   ```ts
+   import { mastra } from '../src/mastra'
+
+   const run = await mastra.getWorkflow('incrementWorkflow').createRun()
+   const result = await run.start({ inputData: { value: 5 } })
+
+   console.log(result)
+   ```
+
+5. Monitor execution in the Temporal UI under **Workflows** to see step-by-step activity progress and retry history.
+
+### Running in production
+
+For production, use [Temporal Cloud](https://temporal.io/cloud) or a self-hosted Temporal cluster. Configure the client and worker connections through environment variables read by `@temporalio/envconfig`:
+
+```bash
+TEMPORAL_ADDRESS=your-namespace.tmprl.cloud:7233
+TEMPORAL_NAMESPACE=your-namespace
+TEMPORAL_API_KEY=your-api-key
+```
+
+See the [Temporal Cloud connection docs](https://docs.temporal.io/cloud/get-started) for mTLS and API key options.
+
+> **Warning:** The Temporal worker must run as a long-lived process. Do not deploy it to serverless platforms with short execution limits, such as AWS Lambda or Vercel functions. Use a container, VM, or worker-friendly platform such as Fly.io, Railway, or Kubernetes.
+
+## Configuration options
+
+### `taskQueue`
+
+Required. Identifies the Temporal task queue your worker polls. The same value must be passed to `init()` (used by the client to start runs) and to `Worker.create()` (used by the worker to receive them).
+
+### `startToCloseTimeout`
+
+Optional. Sets the maximum time a single activity (step) is allowed to run before Temporal cancels it and applies the retry policy. Defaults to `1 minute`.
+
+```ts
+export const { createWorkflow, createStep } = init({
+  client,
+  taskQueue: 'mastra',
+  startToCloseTimeout: '5 minutes',
+})
+```
+
+## Constraints and notes
+
+- Workflow ids must be static string literals. The build-time transformer reads the literal value to derive Temporal workflow export names.
+- Activities are generated automatically from `createStep()` handlers. Do not pass them in `Worker.create({ activities })`.
+
+## Related
+
+- [Workflow runners](https://mastra.ai/docs/deployment/workflow-runners)
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Temporal documentation](https://docs.temporal.io/)

package/.docs/reference/auth/workos.md

@@ -28,7 +28,13 @@ export const mastra = new Mastra({
 
 **name** (`string`): Custom name for the auth provider instance. (Default: `"workos"`)
 
-**authorizeUser** (`(user: WorkosUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks if the user has an 'admin' role in any organization membership.
+**redirectUri** (`string`): OAuth redirect URI used by WorkOS AuthKit. Set this when you use the built-in WorkOS sign-in flow. (Default: `process.env.WORKOS_REDIRECT_URI`)
+
+**fetchMemberships** (`boolean`): Loads organization memberships during authentication. Set this to \`true\` when you use \`MastraFGAWorkos\` so FGA checks can resolve the correct organization membership ID. (Default: `false`)
+
+**trustJwtClaims** (`boolean`): Trusts verified bearer-token claims enough to construct a \`WorkOSUser\` even when \`workos.userManagement.getUser()\` does not apply. Use this for service-account or machine-to-machine tokens backed by a WorkOS custom JWT template. (Default: `false`)
+
+**jwtClaims** (`{ userId?: string; workosId?: string; email?: string; name?: string; organizationId?: string; organizationMembershipId?: string }`): Maps verified bearer JWT claims into the authenticated \`WorkOSUser\`. Useful for custom JWT templates that include \`organizationMembershipId\` or other FGA-specific claims.
 
 ## Environment variables
 
@@ -38,24 +44,63 @@ The following environment variables are automatically used when constructor opti
 
 **WORKOS\_CLIENT\_ID** (`string`): Your WorkOS Client ID. Can be found in your WorkOS Dashboard under Applications.
 
+**WORKOS\_REDIRECT\_URI** (`string`): OAuth redirect URI used by WorkOS AuthKit when you use the built-in session-based flow.
+
 ## Default authorization behavior
 
-By default, `MastraAuthWorkos` implements role-based authorization that checks for admin access:
+By default, `MastraAuthWorkos` authorizes any authenticated WorkOS user whose resolved user object includes both `id` and `workosId`.
 
 1. **Token Verification**: The access token is verified with WorkOS to ensure it's valid and not expired
 2. **User Retrieval**: User information is extracted from the verified token
-3. **Organization Membership Check**: The system queries WorkOS for all organization memberships associated with the user's ID
-4. **Role Extraction**: All roles from the user's organization memberships are collected
-5. **Admin Check**: The system checks if any role has the slug 'admin'
-6. **Authorization Decision**: Access is granted only if the user has an admin role in at least one organization
+3. **Authorization Decision**: Access is granted if the resolved user contains the required identifiers
+
+This means that by default, `MastraAuthWorkos` acts as an authentication provider rather than a role gate.
+
+## FGA membership loading
+
+Set `fetchMemberships: true` when you use `MastraFGAWorkos`. This loads the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.
+
+When `fetchMemberships` is `false`, Mastra skips the extra WorkOS `listOrganizationMemberships()` call on each authenticated request.
+
+## Service tokens and JWT claims
+
+If your WorkOS JWT template includes custom claims, you can map them directly into the authenticated `WorkOSUser`.
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+const auth = new MastraAuthWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+  redirectUri: process.env.WORKOS_REDIRECT_URI,
+  trustJwtClaims: true,
+  jwtClaims: {
+    organizationId: 'org_id',
+    organizationMembershipId: 'urn:mastra:organization_membership_id',
+  },
+})
+```
+
+When `trustJwtClaims` is enabled, Mastra can authenticate verified bearer tokens for service principals even if `getUser()` is not the right lookup path. This is the preferred way to pass pre-resolved `organizationMembershipId` values into FGA checks for machine-to-machine flows.
 
-This means that by default, only users with admin privileges in at least one organization will be authorized to access your Mastra endpoints.
+## Custom authorization
 
-To implement custom authorization logic (e.g., allow all authenticated users, check for specific roles, or implement custom business logic), provide a custom `authorizeUser` function.
+If you need stricter authorization, subclass `MastraAuthWorkos` and override `authorizeUser()`:
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+import type { HonoRequest } from 'hono'
+
+class AdminOnlyWorkosAuth extends MastraAuthWorkos {
+  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
+    return user?.metadata?.role === 'admin'
+  }
+}
+```
 
 ## WorkOS user type
 
-The `WorkosUser` type used in the `authorizeUser` function corresponds to the JWT token payload returned by WorkOS. WorkOS allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. Here's an example of what the user object might look like:
+The `WorkOSUser` type available inside `authorizeUser()` and other WorkOS auth hooks includes Mastra's normalized user fields plus WorkOS-specific metadata. WorkOS also allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. The following example shows what a WorkOS-backed user object might look like:
 
 ```javascript
 {

package/.docs/reference/index.md

@@ -160,6 +160,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering)
 - [Spans](https://mastra.ai/reference/observability/tracing/spans)
 - [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor)
+- [CostGuardProcessor](https://mastra.ai/reference/processors/cost-guard-processor)
 - [LanguageDetector](https://mastra.ai/reference/processors/language-detector)
 - [MessageHistory](https://mastra.ai/reference/processors/message-history-processor)
 - [ModerationProcessor](https://mastra.ai/reference/processors/moderation-processor)
@@ -167,6 +168,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PrefillErrorHandler](https://mastra.ai/reference/processors/prefill-error-handler)
 - [Processor Interface](https://mastra.ai/reference/processors/processor-interface)
 - [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
+- [RegexFilterProcessor](https://mastra.ai/reference/processors/regex-filter-processor)
 - [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
 - [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)

package/.docs/reference/processors/cost-guard-processor.md

@@ -0,0 +1,112 @@
+# CostGuardProcessor
+
+The `CostGuardProcessor` enforces monetary cost limits across the agentic loop, blocking or warning when a configurable cost threshold is exceeded.
+
+It uses `processInputStep` to check the cost limit before each LLM call. Cost data is queried from the observability storage APIs (`getMetricAggregate`) for all scopes. For `resource` and `thread` scopes, it aggregates cost across runs within a configurable time window (defaults to 7 days). For `run` scope, it queries cost for the current trace.
+
+For token-based limits, use `TokenLimiterProcessor` instead.
+
+Supports three scoping modes:
+
+- **Run scope**: Tracks cost within a single agent run via trace ID
+- **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
+- **Thread scope**: Tracks cumulative cost per `threadId` across runs
+
+> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as a best-effort threshold, not a hard ceiling.
+
+## Usage example
+
+Track cumulative cost per resource (default scope):
+
+```typescript
+import { CostGuardProcessor } from '@mastra/core/processors'
+
+const costGuard = new CostGuardProcessor({
+  maxCost: 1.0,
+})
+```
+
+Track cumulative cost per thread with a 24-hour window:
+
+```typescript
+import { CostGuardProcessor } from '@mastra/core/processors'
+
+const costGuard = new CostGuardProcessor({
+  maxCost: 5.0,
+  scope: 'thread',
+  window: '24h',
+})
+```
+
+Attach to an agent with an `onViolation` callback:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { CostGuardProcessor } from '@mastra/core/processors'
+
+const costGuard = new CostGuardProcessor({
+  maxCost: 5.0,
+  scope: 'resource',
+  window: '30d',
+})
+
+costGuard.onViolation = ({ detail }) => {
+  console.log(`Cost exceeded for ${detail.scopeKey}: $${detail.usage}/$${detail.limit}`)
+}
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'openai/gpt-5-nano',
+  processors: {
+    input: [costGuard],
+  },
+})
+```
+
+## Constructor parameters
+
+**maxCost** (`number`): Maximum estimated cost allowed (e.g. 0.50 for $0.50 USD). Must be a positive number. Uses cost data from observability metrics. This is an approximate limit due to metric persistence delays.
+
+**scope** (`'run' | 'resource' | 'thread'`): Scope for cost tracking. 'run' tracks cost within the current agent run via trace ID. 'resource' tracks cumulative cost per resourceId across runs (default). 'thread' tracks cumulative cost per threadId across runs. All scopes require observability storage with getMetricAggregate support. (Default: `'resource'`)
+
+**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): Time window for cost aggregation when using 'resource' or 'thread' scope. Only applicable to non-run scopes. (Default: `'7d'`)
+
+**strategy** (`'block' | 'warn'`): Strategy when the cost limit is exceeded. 'block' aborts with a TripWire error. 'warn' logs a warning but allows the step to proceed. (Default: `'block'`)
+
+**message** (`string`): Custom message template for the abort reason. Supports {usage} and {limit} placeholders. (Default: `'Cost guard: cost limit exceeded ({usage}/{limit})'`)
+
+## Instance properties
+
+**id** (`'cost-guard'`): Processor identifier.
+
+**name** (`'Cost Guard'`): Processor display name.
+
+**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Callback invoked when a cost violation is detected, regardless of strategy. Part of the generalized Processor interface. Use for side effects like alerting, logging to external systems, or emailing users. Errors thrown by this callback are silently caught.
+
+**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Checks cumulative estimated cost against maxCost before each LLM call. Queries observability storage for cost data: run scope filters by trace ID, resource/thread scopes filter by their respective IDs with a time window. Calls abort() when the limit is exceeded (block strategy) or logs a warning (warn strategy). Cost checks are approximate due to metric persistence delays.
+
+## Error behavior
+
+When the `block` strategy is active (default), `CostGuardProcessor` calls `abort()` with `retry: false` when the cost limit is exceeded. The TripWire metadata includes:
+
+- `processorId`: `'cost-guard'`
+- `usage`: Current cumulative usage (`estimatedCost`, `costUnit`)
+- `maxCost`: The configured cost limit
+- `scope`: The active scope (`'run'`, `'resource'`, or `'thread'`)
+- `scopeKey`: The scope identifier for resource/thread scopes (if applicable)
+
+## Scoping behavior
+
+| Scope      | Tracks across runs | Filter                      | Requires context                 |
+| ---------- | ------------------ | --------------------------- | -------------------------------- |
+| `run`      | No                 | `traceId` from current span | Tracing context (automatic)      |
+| `resource` | Yes                | `resourceId` + time window  | `resourceId` in `RequestContext` |
+| `thread`   | Yes                | `threadId` + time window    | `threadId` in `RequestContext`   |
+
+All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance does not have observability storage configured, an error is thrown at registration time.
+
+For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
+
+For `resource` and `thread` scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, cost is treated as zero.
+
+> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. There is a short delay between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.

package/.docs/reference/processors/processor-interface.md

@@ -80,6 +80,9 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
   /** When true, processOutputStream also receives `data-*` chunks. Default: false. */
   processDataParts?: boolean
 
+  /** Callback invoked when this processor detects a violation, regardless of strategy. */
+  onViolation?: (violation: ProcessorViolation) => void | Promise<void>
+
   processInput?(
     args: ProcessInputArgs<TTripwireMetadata>,
   ): Promise<ProcessInputResult> | ProcessInputResult
@@ -120,6 +123,8 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
 
 **processDataParts** (`boolean`): When true, the processOutputStream method also receives \`data-\*\` chunks emitted by tools via writer.custom(). Defaults to false.
 
+**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Optional callback invoked when the processor detects a policy violation, regardless of strategy (block or warn). Use for side effects like alerting, logging to external systems, or emailing users. Errors thrown by this callback are silently caught to prevent interfering with processor logic. The violation object contains processorId, message, and a processor-specific detail field.
+
 ## Message arguments
 
 Most processor methods receive both `messages` and `messageList`. They point to the same underlying conversation but expose it differently.

package/.docs/reference/processors/regex-filter-processor.md

@@ -0,0 +1,106 @@
+# RegexFilterProcessor
+
+The `RegexFilterProcessor` applies zero-cost regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made — all detection is regex-based.
+
+Supports built-in presets for common patterns (PII, secrets, URLs) and custom regex rules. Can be applied to input, output, or both phases.
+
+## Usage example
+
+Block PII in input messages:
+
+```typescript
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  presets: ['pii'],
+  strategy: 'block',
+  phase: 'input',
+})
+```
+
+Redact secrets in output:
+
+```typescript
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  presets: ['secrets'],
+  strategy: 'redact',
+  phase: 'output',
+})
+```
+
+Custom rules:
+
+```typescript
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }],
+  strategy: 'redact',
+})
+```
+
+Attach to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'openai/gpt-5-nano',
+  processors: {
+    input: [
+      new RegexFilterProcessor({
+        presets: ['pii', 'secrets'],
+        strategy: 'block',
+      }),
+    ],
+  },
+})
+```
+
+## Constructor parameters
+
+**rules** (`RegexRule[]`): Custom regex rules to apply. Each rule has a name, a regex pattern, and an optional replacement string.
+
+**rules.name** (`string`): Display name for the rule (used in match reports and error messages).
+
+**rules.pattern** (`RegExp`): The regex pattern to match against.
+
+**rules.replacement** (`string`): Replacement string for redact strategy. Defaults to '\[REDACTED]'.
+
+**presets** (`('pii' | 'secrets' | 'urls')[]`): Built-in preset categories. 'pii' matches emails, phone numbers, SSNs, credit cards. 'secrets' matches API keys, bearer tokens, AWS keys. 'urls' matches HTTP/HTTPS URLs.
+
+**strategy** (`'block' | 'redact' | 'warn'`): Strategy when a pattern match is found. 'block' aborts with a TripWire error. 'redact' replaces matched content with replacement text. 'warn' logs a warning but passes content through unchanged. (Default: `'block'`)
+
+**phase** (`'input' | 'output' | 'all'`): Phases to apply the filter. 'input' filters input messages. 'output' filters output stream and result. 'all' filters both. (Default: `'all'`)
+
+## Returns
+
+**id** (`'regex-filter'`): Processor identifier.
+
+**name** (`'Regex Filter'`): Processor display name.
+
+**processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): Checks input messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is output.
+
+**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>`): Checks streaming text-delta chunks against all configured rules. Skipped when phase is input.
+
+**processOutputResult** (`(args: ProcessOutputResultArgs) => ProcessorMessageResult`): Checks output messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is input.
+
+## Error behavior
+
+When the `block` strategy is active (default), `RegexFilterProcessor` throws a `TripWire` error with `retry: false` when any pattern matches. The TripWire metadata includes:
+
+- `processorId`: `'regex-filter'`
+- `matches`: Array of match objects with `rule`, `match` (redacted to `'[REDACTED_MATCH]'`), and `index`
+- `strategy`: `'block'`
+
+## Built-in presets
+
+| Preset    | Patterns                                         | Default replacement                            |
+| --------- | ------------------------------------------------ | ---------------------------------------------- |
+| `pii`     | Emails, phone numbers, SSNs, credit card numbers | `[EMAIL]`, `[PHONE]`, `[SSN]`, `[CREDIT_CARD]` |
+| `secrets` | API keys, bearer tokens, AWS access keys         | `[API_KEY]`, `[BEARER_TOKEN]`, `[AWS_KEY]`     |
+| `urls`    | HTTP/HTTPS URLs                                  | `[URL]`                                        |

package/.docs/reference/tools/perplexity.md

@@ -1,7 +1,5 @@
 # Perplexity tools
 
-Added in: `@mastra/perplexity@0.1.0-alpha.0`
-
 The `@mastra/perplexity` package wraps the [Perplexity Search API](https://docs.perplexity.ai/docs/search/quickstart) as a Mastra-compatible tool. It exposes a factory function that returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) and full Zod input/output schemas.
 
 For chat completions or agentic workflows powered by Perplexity, use Mastra's built-in [Perplexity model provider](https://mastra.ai/models/providers/perplexity) or [Perplexity Agent provider](https://mastra.ai/models/providers/perplexity-agent). Those are separate from this Search tool.

package/.docs/reference/tools/tavily.md

@@ -1,7 +1,5 @@
 # Tavily tools
 
-**Added in:** `@mastra/tavily@0.1.0-alpha.0`
-
 The `@mastra/tavily` package wraps the [Tavily](https://app.tavily.com) API as Mastra-compatible tools. It exposes factory functions for search, extract, crawl, and map — each returning a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
 
 ## Installation

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @mastra/mcp-docs-server
 
+## 1.1.33-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e)]:
+  - @mastra/core@1.32.0-alpha.2
+  - @mastra/mcp@1.6.1-alpha.1
+
 ## 1.1.33-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.33-alpha.4",
+  "version": "1.1.33-alpha.6",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/mcp": "^1.6.1-alpha.0",
-    "@mastra/core": "1.32.0-alpha.1"
+    "@mastra/core": "1.32.0-alpha.2",
+    "@mastra/mcp": "^1.6.1-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.65",
     "@internal/lint": "0.0.90",
-    "@mastra/core": "1.32.0-alpha.1"
+    "@internal/types-builder": "0.0.65",
+    "@mastra/core": "1.32.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {