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

package/.docs/reference/agents/durable-agent.md

@@ -203,9 +203,13 @@ interface PrepareResult {
 
 **activeTools** (`string[]`): Restricts execution to the named subset of the agent's tools.
 
-**modelSettings** (`object`): Model-specific settings such as temperature.
+**modelSettings** (`object`): Model-specific settings such as temperature. Credential-bearing headers (\`Authorization\`, \`X-Api-Key\`, and similar) are stripped from the serialized snapshot before it crosses process boundaries.
 
-**requireToolApproval** (`boolean`): Require approval for all tool calls, which suspends the run until resumed.
+**stopWhen** (`AgentExecutionOptions['stopWhen']`): Predicate or composition that ends the agentic loop early. The closure rides on the in-process run registry; cross-process resumes degrade to \`maxSteps\` only.
+
+**system** (`string | string[]`): Additional system message appended after the agent instructions and before user messages.
+
+**requireToolApproval** (`boolean | ((args: { toolName: string; args: unknown; requestContext: RequestContext; workspace?: string }) => boolean | Promise<boolean>)`): Require approval for tool calls. Pass \`true\` or \`false\` to gate all or none, or a function for per-call policy. Function-form policies live on the in-process run registry; cross-process resumes fall back to a \`true\` shadow.
 
 **autoResumeSuspendedTools** (`boolean`): Automatically resume tools that suspended, instead of waiting for an external \`resume()\` call.
 
@@ -217,10 +221,26 @@ interface PrepareResult {
 
 **structuredOutput** (`object`): Structured output configuration.
 
-**untilIdle** (`boolean | { maxIdleMs?: number }`): When set, keeps the stream open across background-task continuations until the agent is idle. Pass \`true\` for the default 5-minute idle timeout, or \`{ maxIdleMs }\` to customise. Equivalent to the deprecated \`streamUntilIdle()\` method.
+**untilIdle** (`boolean | { maxIdleMs?: number }`): When set, keeps the stream open across background-task continuations until the agent is idle. Pass \`true\` for the default 5-minute idle timeout, or \`{ maxIdleMs }\` to customise. Equivalent to the deprecated \`streamUntilIdle()\` method. Also supported on \`resume()\`.
+
+**disableBackgroundTasks** (`boolean`): Disable background-task dispatch for this run. Background-eligible tools execute inline instead.
+
+**tracingOptions** (`AgentExecutionOptions['tracingOptions']`): Tracing metadata, tags, trace ID, parent span ID, and \`requestContextKeys\` forwarded to the agent and model spans. Fully JSON-serializable.
+
+**actor** (`AgentExecutionOptions['actor']`): Per-call actor signal forwarded to FGA checks and tool execution.
+
+**transform** (`AgentExecutionOptions['transform']`): Per-invocation tool payload transform policy. The \`transformToolPayload\` closure lives on the in-process run registry; only the JSON-safe \`targets\` shadow is serialized.
+
+**prepareStep** (`AgentExecutionOptions['prepareStep']`): Per-step preparation hook invoked as a \`PrepareStepProcessor\` at the start of every iteration. Closure-only — stored on the in-process run registry. Cross-process resumes lose the hook.
+
+**isTaskComplete** (`AgentExecutionOptions['isTaskComplete']`): Per-call completion policy. Scorer instances and \`onComplete\` live on the in-process run registry; the JSON-safe primitives (\`strategy\`, \`timeout\`, \`parallel\`, \`suppressFeedback\`, \`scorerNames\`) are serialized for cross-process observability.
+
+**delegation** (`AgentExecutionOptions['delegation']`): Sub-agent delegation hooks (\`onDelegationStart\`, \`onDelegationComplete\`, \`messageFilter\`). Callbacks are baked into the sub-agent tool wrappers at prepare time. Cross-process resumes lose the callbacks.
 
 **versions** (`object`): Version overrides for sub-agent delegation.
 
+**abortSignal** (`AbortSignal`): External abort signal. Forwarded to the durable run's internal \`AbortController\`, so either source can cancel the run. Cross-process resumes cannot recover the signal — pass a fresh one to \`resume()\` if you need post-resume abortability.
+
 **onChunk** (`(chunk: ChunkType) => void | Promise<void>`): Called for each streamed chunk.
 
 **onStepFinish** (`(result: AgentStepFinishEventData) => void | Promise<void>`): Called when a step in the agentic loop finishes.
@@ -231,6 +251,10 @@ interface PrepareResult {
 
 **onSuspended** (`(data: AgentSuspendedEventData) => void | Promise<void>`): Called when the run suspends, for example for tool approval.
 
+**onAbort** (`AgentExecutionOptions['onAbort']`): Called when the run is aborted via \`abortSignal\` or \`result.abort()\`.
+
+**onIterationComplete** (`AgentExecutionOptions['onIterationComplete']`): Called after every agentic-loop iteration with the latest \`messageList\`, \`finishReason\`, and \`isFinal\` flag. Observation-only on durable agents: returning \`continue: false\` or feedback does not influence the loop.
+
 `resume()` and `observe()` accept the same lifecycle callbacks (`onChunk`, `onStepFinish`, `onFinish`, `onError`, `onSuspended`). `observe()` also accepts an `offset` to control where replay starts.
 
 ## DurableAgentStreamResult
@@ -245,6 +269,7 @@ interface DurableAgentStreamResult<OUTPUT = undefined> {
   threadId?: string
   resourceId?: string
   cleanup: () => void
+  abort: () => void
 }
 ```
 
@@ -260,6 +285,8 @@ interface DurableAgentStreamResult<OUTPUT = undefined> {
 
 **cleanup** (`() => void`): Unsubscribes from PubSub and clears registry entries for the run. Call it when done with the run.
 
+**abort** (`() => void`): Aborts the run by flipping the internal \`AbortController\`. Surfaces as an \`AbortError\` inside the durable LLM-execution step and fires the \`onAbort\` callback. Safe to call after the run has finished — a no-op in that case.
+
 ## Related
 
 - [`createInngestAgent()`](https://mastra.ai/reference/agents/inngest-agent)

package/.docs/reference/auth/google.md

@@ -0,0 +1,355 @@
+# MastraAuthGoogle & MastraRBACGoogle class
+
+## MastraAuthGoogle class
+
+The `MastraAuthGoogle` class provides authentication for Mastra using Google Workspace. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies, verifies Google ID tokens, and integrates with the Mastra server using the `auth` option.
+
+### Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthGoogle } from '@mastra/auth-google'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthGoogle({
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      redirectUri: process.env.GOOGLE_REDIRECT_URI,
+      allowedDomains: ['example.com'],
+    }),
+  },
+})
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables set. In that case, use `new MastraAuthGoogle()` without any arguments.
+
+### Constructor parameters
+
+**clientId** (`string`): Google OAuth client ID. (Default: `process.env.GOOGLE_CLIENT_ID`)
+
+**clientSecret** (`string`): Google OAuth client secret. Required for Studio SSO. (Default: `process.env.GOOGLE_CLIENT_SECRET`)
+
+**redirectUri** (`string`): OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Google Cloud OAuth client. (Default: `process.env.GOOGLE_REDIRECT_URI`)
+
+**scopes** (`string[]`): OAuth scopes requested during the login flow. (Default: `['openid', 'profile', 'email']`)
+
+**allowedDomains** (`string | string[]`): Allowed Google Workspace hosted domains. Mastra validates these against the verified \`hd\` claim. (Default: `process.env.GOOGLE_ALLOWED_DOMAINS`)
+
+**hostedDomain** (`string`): Hosted-domain login hint passed to Google as \`hd\`. This is a hint only and is not used for authorization. (Default: `process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain`)
+
+**session** (`GoogleSessionOptions`): Session cookie configuration.
+
+**session.cookieName** (`string`): Name of the session cookie.
+
+**session.cookieMaxAge** (`number`): Cookie max age in seconds.
+
+**session.cookiePassword** (`string`): Password for encrypting session cookies. Must be at least 32 characters. If not set, an auto-generated value is used in development that does not survive restarts.
+
+**session.secureCookies** (`boolean`): Set the \`Secure\` flag on session cookies.
+
+**name** (`string`): Custom name for the auth provider instance. (Default: `'google'`)
+
+### Environment variables
+
+The following environment variables are automatically used when constructor options aren't provided:
+
+**GOOGLE\_CLIENT\_ID** (`string`): Google OAuth client ID from your Google Cloud OAuth client.
+
+**GOOGLE\_CLIENT\_SECRET** (`string`): Google OAuth client secret. Required for the SSO authorization code flow.
+
+**GOOGLE\_REDIRECT\_URI** (`string`): OAuth redirect URI for the SSO callback.
+
+**GOOGLE\_COOKIE\_PASSWORD** (`string`): Password for encrypting session cookies. Must be at least 32 characters.
+
+**GOOGLE\_ALLOWED\_DOMAINS** (`string`): Comma-separated Google Workspace hosted domains to allow.
+
+**GOOGLE\_HOSTED\_DOMAIN** (`string`): Hosted-domain login hint passed to Google during SSO login.
+
+### Authentication flow
+
+`MastraAuthGoogle` authenticates requests in the following order:
+
+1. **Session cookie**: When SSO is enabled, reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
+2. **Google ID token fallback**: If no valid session cookie is present, verifies the `Authorization` header token against Google's JWKS endpoint.
+
+After authentication, `authorizeUser` checks that the user has a valid Google user ID, the token-derived expiration has not passed, and the user's verified `hd` claim matches `allowedDomains` when domains are configured.
+
+### Authentication methods
+
+#### `authenticateToken(token, request?)`
+
+Authenticates a Google ID token. When SSO is enabled, this method checks the encrypted session cookie before it verifies the Bearer token.
+
+```typescript
+const user = await auth.authenticateToken(idToken, request)
+```
+
+Returns: `Promise<GoogleUser | null>`
+
+#### `getCurrentUser(request)`
+
+Returns the authenticated user from a session cookie or Bearer Google ID token.
+
+```typescript
+const user = await auth.getCurrentUser(request)
+```
+
+Returns: `Promise<GoogleUser | null>`
+
+#### `authorizeUser(user)`
+
+Returns `true` when the user has an ID, has not expired, and matches `allowedDomains` when domains are configured.
+
+```typescript
+const allowed = auth.authorizeUser(user)
+```
+
+Returns: `boolean`
+
+#### `getUser(userId)`
+
+Returns `null`. Google ID tokens are verified directly, so this provider does not perform user lookup by ID.
+
+```typescript
+const user = await auth.getUser(userId)
+```
+
+Returns: `Promise<GoogleUser | null>`
+
+### `GoogleUser` type
+
+The `GoogleUser` type extends the base `EEUser` interface with Google-specific fields:
+
+**id** (`string`): Mastra user ID. Uses the Google \`sub\` claim.
+
+**googleId** (`string`): Google Account subject identifier.
+
+**email** (`string`): User email address.
+
+**name** (`string`): User display name from Google profile claims.
+
+**avatarUrl** (`string`): URL to the user's Google profile picture.
+
+**hostedDomain** (`string`): Google Workspace hosted domain from the verified \`hd\` claim.
+
+**expiresAt** (`Date`): Verified ID token expiration time, when available.
+
+**emailVerified** (`boolean`): Whether Google reports the email address as verified.
+
+**groups** (`string[]`): Optional pre-resolved Google Workspace group role IDs.
+
+## MastraRBACGoogle class
+
+The `MastraRBACGoogle` class maps Google Workspace groups to Mastra permissions. It fetches user groups from the Google Admin SDK Directory API and resolves them against a configurable role mapping. Use it with `MastraAuthGoogle` or any other auth provider.
+
+> **Note:** RBAC requires a valid Enterprise Edition license. It works without a license in development so you can try it locally, but you'll need a license for production. [Contact sales](https://mastra.ai/contact) for more information.
+
+### Usage example
+
+Use `MastraRBACGoogle` alongside an auth provider by passing it to the `rbac` option:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthGoogle, MastraRBACGoogle } from '@mastra/auth-google'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthGoogle(),
+    rbac: new MastraRBACGoogle({
+      serviceAccount: {
+        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
+        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
+        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
+      },
+      roleMapping: {
+        'admins@example.com': ['*'],
+        'engineering@example.com': ['agents:*', 'workflows:*', 'tools:*'],
+        'viewers@example.com': ['agents:read', 'workflows:read'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+To use Google Workspace RBAC with a different auth provider, pass a `getUserKey` function to resolve the Google Directory API user key from the other provider's user object:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+import { MastraRBACGoogle } from '@mastra/auth-google'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0(),
+    rbac: new MastraRBACGoogle({
+      getUserKey: user => user.email,
+      serviceAccount: {
+        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
+        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
+        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
+      },
+      roleMapping: {
+        'engineering@example.com': ['agents:*', 'workflows:*'],
+        'admins@example.com': ['*'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+### Constructor parameters
+
+**roleMapping** (`RoleMapping`): Maps Google Workspace group role IDs to arrays of Mastra permission strings. Use \`'\_default'\` to assign permissions to users who do not match any group. Supports wildcards like \`'\*'\` (full access) and \`'agents:\*'\` (all agent actions).
+
+**accessToken** (`string`): Pre-obtained Workspace Directory API access token.
+
+**getAccessToken** (`() => Promise<string> | string`): Callback that returns a Workspace Directory API access token.
+
+**serviceAccount** (`GoogleWorkspaceServiceAccount`): Service account credentials for domain-wide delegated Directory API access.
+
+**serviceAccount.clientEmail** (`string`): Google service account email.
+
+**serviceAccount.privateKey** (`string`): PEM-encoded private key. Escaped \`\n\` values from .env files are supported.
+
+**serviceAccount.privateKeyId** (`string`): Optional private key ID.
+
+**serviceAccount.subject** (`string`): Workspace administrator user to impersonate with domain-wide delegation.
+
+**serviceAccount.scopes** (`string[]`): OAuth scopes for the service account token.
+
+**getUserKey** (`(user: unknown) => string | undefined`): Extract the Directory API \`userKey\` from an authenticated user. Defaults to \`user.email\`.
+
+**mapGroupToRoles** (`(group: GoogleWorkspaceGroup) => string[]`): Map a Google Workspace group to role IDs. Defaults to \`\[group.email]\`.
+
+**cache** (`PermissionCacheOptions`): Configure the LRU cache for group lookups.
+
+**cache.maxSize** (`number`): Maximum number of users to cache.
+
+**cache.ttlMs** (`number`): Time-to-live in milliseconds.
+
+### RBAC methods
+
+#### `getRoles(user)`
+
+Returns Google Workspace group role IDs for a user.
+
+```typescript
+const roles = await rbac.getRoles(user)
+```
+
+Returns: `Promise<string[]>`
+
+#### `getPermissions(user)`
+
+Returns Mastra permissions resolved from Google Workspace groups and `roleMapping`.
+
+```typescript
+const permissions = await rbac.getPermissions(user)
+```
+
+Returns: `Promise<string[]>`
+
+#### `hasPermission(user, permission)`
+
+Checks whether a user has a permission.
+
+```typescript
+const canReadAgents = await rbac.hasPermission(user, 'agents:read')
+```
+
+Returns: `Promise<boolean>`
+
+#### `hasRole(user, role)`
+
+Checks whether a user resolved to a specific Google Workspace group role.
+
+```typescript
+const isAdmin = await rbac.hasRole(user, 'admins@example.com')
+```
+
+Returns: `Promise<boolean>`
+
+#### `hasAllPermissions(user, permissions)`
+
+Checks whether a user has every requested permission.
+
+```typescript
+const canManageAgents = await rbac.hasAllPermissions(user, ['agents:read', 'agents:update'])
+```
+
+Returns: `Promise<boolean>`
+
+#### `hasAnyPermission(user, permissions)`
+
+Checks whether a user has at least one requested permission.
+
+```typescript
+const canReadSomething = await rbac.hasAnyPermission(user, ['agents:read', 'workflows:read'])
+```
+
+Returns: `Promise<boolean>`
+
+#### `getAvailableRoles()`
+
+Returns the role IDs configured in `roleMapping`, excluding `_default`.
+
+```typescript
+const roles = await rbac.getAvailableRoles()
+```
+
+Returns: `Promise<{ id: string; name: string }[]>`
+
+#### `getPermissionsForRole(roleId)`
+
+Returns the permissions configured for a role ID.
+
+```typescript
+const permissions = await rbac.getPermissionsForRole('engineering@example.com')
+```
+
+Returns: `Promise<string[]>`
+
+#### `clearCache()`
+
+Clears all cached Google Workspace group lookups.
+
+```typescript
+rbac.clearCache()
+```
+
+Returns: `void`
+
+#### `clearUserCache(userKey)`
+
+Clears the cached group lookup for one Directory API user key, such as an email address.
+
+```typescript
+rbac.clearUserCache('user@example.com')
+```
+
+Returns: `void`
+
+#### `getCacheStats()`
+
+Returns the current group lookup cache size and maximum size.
+
+```typescript
+const stats = rbac.getCacheStats()
+```
+
+Returns: `{ size: number; maxSize: number }`
+
+### Additional configuration
+
+`MastraRBACGoogle` uses `GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=...` and handles pagination. Provide a service account with domain-wide delegation for production Google Workspace deployments, or pass `accessToken` / `getAccessToken` if your application already manages Google API tokens.
+
+If `user.groups` is already an array, `MastraRBACGoogle` uses that value and does not call the Directory API. An empty `groups` array means the user has no Google group roles and resolves to `_default` permissions when `_default` is configured.
+
+`MastraRBACGoogle` does not automatically read service-account environment variables. Pass service-account credentials through the `serviceAccount` option, or pass `accessToken` / `getAccessToken`.
+
+## Related
+
+[Google auth docs](https://mastra.ai/docs/server/auth/google)

package/.docs/reference/channels/channel-provider.md

@@ -0,0 +1,65 @@
+# ChannelProvider
+
+`ChannelProvider` is the interface that platform integrations implement to connect agents to a messaging platform. A provider owns the full lifecycle of an integration: app provisioning and OAuth, webhook routing and event handling, adapter creation and agent wiring, and credential management.
+
+Register providers on the `Mastra` constructor under `channels`, keyed by an id you choose. Each provider's routes are merged into the server's API routes automatically, and `initialize()` runs during Mastra startup.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { SlackProvider } from '@mastra/slack'
+
+export const mastra = new Mastra({
+  channels: {
+    slack: new SlackProvider({
+      refreshToken: process.env.SLACK_REFRESH_TOKEN!,
+      baseUrl: process.env.MASTRA_BASE_URL,
+    }),
+  },
+})
+```
+
+The provider's `baseUrl` is the public URL the platform sends webhooks and events to. In production this is your deployed Mastra server URL. For local development, the platform can't reach `http://localhost:4111`, so run a tunnel (such as [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) or [ngrok](https://ngrok.com/)) and point `baseUrl` at the tunnel URL (for example `https://abc123.trycloudflare.com`) so events reach your local dev process.
+
+[`SlackProvider`](https://mastra.ai/reference/channels/slack-provider) is the first built-in implementation. Build a custom provider by implementing this interface.
+
+## Properties
+
+**id** (`string`): Unique identifier for this channel type, for example 'slack' or 'discord'. Used as the key when routing events and looking the provider up from Mastra.
+
+## Methods
+
+**getRoutes** (`() => ApiRoute[]`): Returns the API routes for this channel (OAuth, webhooks, events). These are merged into the server's apiRoutes automatically.
+
+**initialize** (`() => Promise<void>`): Called during Mastra initialization after all agents are registered. Use it for async setup such as restoring active installations. Does not provision new apps.
+
+**configure** (`(credentials: Record<string, unknown> | null) => void | Promise<void>`): Provides or clears platform credentials at runtime. Pass null to clear credentials and delete stored tokens.
+
+**getInfo** (`() => ChannelPlatformInfo`): Returns discovery metadata for the editor UI: platform name, configuration status, and the connect options schema.
+
+**connect** (`(agentId: string, options?: Record<string, unknown>) => Promise<ChannelConnectResult>`): Connects an agent to the platform. Returns a discriminated result describing the authorization flow required to finish the connection.
+
+**disconnect** (`(agentId: string) => Promise<void>`): Disconnects an agent from the platform. Deletes the platform app and cleans up stored state.
+
+**listInstallations** (`() => Promise<ChannelInstallationInfo[]>`): Lists active installations for this platform. Returns public info only, never secrets.
+
+## Accessing a provider
+
+Access a registered provider through the `channels` getter, keyed by the id you registered it under. The getter is typed from the constructor config, so `mastra.channels.slack` is the concrete provider with its full method surface.
+
+```typescript
+await mastra.channels.slack.configure({ refreshToken })
+```
+
+When the key is only known at runtime, look the provider up by string id instead. `getChannelProvider` takes the concrete type as a generic, and `getChannelProviders` returns every registered provider keyed by id.
+
+```typescript
+import type { SlackProvider } from '@mastra/slack'
+
+const slack = mastra.getChannelProvider<SlackProvider>('slack')
+const all = mastra.getChannelProviders()
+```
+
+## Related
+
+- [SlackProvider](https://mastra.ai/reference/channels/slack-provider)
+- [Channels](https://mastra.ai/docs/agents/channels)