@mastra/mcp-docs-server 1.2.7-alpha.20 → 1.2.7-alpha.22

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

@@ -850,10 +850,16 @@ const agent = new Agent({
 
 The retry mechanism:
 
-- Only works in `processOutputStep()` and `processInputStep()` methods
+- Works in `processOutputStep()` and `processInputStep()` methods
 - Replays the step with the abort reason added as context for the LLM
 - Tracks retry count via the `retryCount` parameter
-- Respects `maxProcessorRetries` limit on the agent
+- Requires an explicit `maxProcessorRetries` limit on the agent or call
+
+### Error processor retry limits
+
+`processAPIError()` has a separate default: when `errorProcessors` are configured and `maxProcessorRetries` is omitted, the runtime allows up to `10` retries. Set the limit explicitly when you need a bounded retry budget.
+
+For `StreamErrorRetryProcessor`, also set its `maxRetries` to the same value. Its own default is `1`, which can otherwise be lower than the agent cap. Keep model retries at `0` when the processor is the only retry mechanism for a request.
 
 ### Violation callbacks
 
@@ -908,7 +914,7 @@ For `agent.generate()`, the result exposes the same information as `result.tripw
 
 `abort` accepts a second options argument:
 
-- `retry: true` asks the agent to retry instead of ending. Retries require `maxProcessorRetries` to be set on the agent or call.
+- `retry: true` asks the agent to retry instead of ending. Input and output processor retries require `maxProcessorRetries` to be set on the agent or call.
 - `metadata` attaches structured data to the `tripwire` chunk so downstream consumers can branch on categories like `pii`, `quality`, or `moderation`.
 
 ## API error handling

package/.docs/reference/agents/generateLegacy.md

@@ -2,9 +2,9 @@
 
 # Agent.generateLegacy() (Legacy)
 
-> **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.generate()`](https://mastra.ai/reference/agents/generate) method instead.
+> **Warning:** **Deprecated**: This method is deprecated and only works with legacy model adapters. For current model adapters, use [`.generate()`](https://mastra.ai/reference/agents/generate) instead.
 
-The `.generateLegacy()` method is the legacy version of the agent generation API, used to interact with V1 model agents to produce text or structured responses. This method accepts messages and optional generation options.
+The `.generateLegacy()` method is the legacy version of the agent generation API, used with legacy model adapters to produce text or structured responses. This method accepts messages and optional generation options.
 
 ## Usage example
 
@@ -12,6 +12,12 @@ The `.generateLegacy()` method is the legacy version of the agent generation API
 await agent.generateLegacy('message for agent')
 ```
 
+## Processor retry support
+
+`generateLegacy()` doesn't run error processors or `maxProcessorRetries`. It uses the legacy AI SDK generation path instead.
+
+Scorer judges with legacy model adapters call `generateLegacy()`. They don't receive the coordinated `StreamErrorRetryProcessor` budget available to scorer judges that use Mastra’s current generation API. Use a current model adapter when you need error-processor retries. The legacy `maxRetries` option remains separate and defaults to `2`.
+
 ## Parameters
 
 **messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects with multimodal content (text, images, etc.).

package/.docs/reference/evals/create-scorer.md

@@ -57,9 +57,9 @@ const scorer = createScorer({
 
 **judge.outputProcessors** (`Processor[]`): Output processors applied to the internal judge agent's output before it is returned (e.g. moderation, transformation).
 
-**judge.errorProcessors** (`Processor[]`): Error processors for the internal judge agent. These implement processAPIError and can inspect LLM API rejections and signal a retry, e.g. StreamErrorRetryProcessor. Requires maxProcessorRetries to be set for retry-based processors to take effect.
+**judge.errorProcessors** (`Processor[]`): Error processors for judge models that use Mastra’s current generation API. These implement processAPIError and can inspect LLM API rejections and signal a retry, e.g. StreamErrorRetryProcessor. Legacy model adapters use generateLegacy() and do not run error processors.
 
-**judge.maxProcessorRetries** (`number`): Maximum number of times processors can trigger a retry per judge generation. Required for retry-based error processors (e.g. StreamErrorRetryProcessor) to take effect.
+**judge.maxProcessorRetries** (`number`): Maximum number of times error processors can retry one judge generation. The runtime defaults to 10 when errorProcessors are configured without this value. Set it explicitly to bound the retry budget.
 
 **type** (`string`): Type specification for input/output. Use 'agent' for automatic agent types. For custom types, use the generic approach instead.
 
@@ -71,6 +71,61 @@ The judge only runs for steps defined as **prompt objects** (`preprocess`, `anal
 
 When a prompt-object step runs, its structured LLM output is stored in the corresponding result field (`preprocessStepResult`, `analyzeStepResult`, or the value consumed by `calculateScore` in `generateScore`).
 
+## Retry judge requests
+
+Use the existing judge `errorProcessors` configuration to retry transient failures inside a failed judge request. This doesn't retry the scorer workflow, trace target, batch item, score write, or a completed scorer step.
+
+`@mastra/core` `1.49.0` doesn't include scorer error-processor configuration. Upgrade to a version with scorer processor support, or backport that focused change, before using this configuration.
+
+The following example uses one bounded retry budget. Set the processor `maxRetries` and `judge.maxProcessorRetries` to the same value. Keep the internal judge agent's model retries at the default of `0` so model retries don't multiply processor attempts.
+
+```typescript
+import { createScorer } from '@mastra/core/evals'
+import { StreamErrorRetryProcessor } from '@mastra/core/processors'
+
+const isTransientNetworkError = (error: unknown) =>
+  error instanceof Error && /ECONNRESET|ETIMEDOUT|socket hang up/i.test(error.message)
+
+const retryProcessor = new StreamErrorRetryProcessor({
+  maxRetries: 2,
+  maxRetryAfterMs: 30_000,
+  delayMs: ({ retryCount }) => Math.min(1_000 * 2 ** retryCount, 30_000),
+  matchers: [isTransientNetworkError],
+  retryUnknownErrors: false,
+})
+
+export const responseQuality = createScorer({
+  id: 'response-quality',
+  description: 'Scores response quality',
+  judge: {
+    model: myModel,
+    instructions: 'Return a score and concise reason.',
+    errorProcessors: [retryProcessor],
+    maxProcessorRetries: 2,
+  },
+})
+  .generateScore({
+    description: 'Score the response quality.',
+    createPrompt: ({ run }) => `Score: ${run.output}`,
+  })
+  .generateReason({
+    description: 'Explain the score.',
+    createPrompt: () => 'Explain the score.',
+  })
+```
+
+With this configuration, a failed request has at most three provider attempts: the initial request plus two processor retries. If `generateScore` completes and `generateReason` receives a retryable failure, only `generateReason` retries.
+
+`StreamErrorRetryProcessor` honors retryable provider metadata and narrow custom matchers. It keeps `retryUnknownErrors` disabled by default, so authentication, invalid-request, and context-length errors fail immediately unless you explicitly match them. It bounds `Retry-After` values to `30_000` milliseconds by default; use `maxRetryAfterMs` to change that cap.
+
+Avoid adding outer scorer or workflow retries. Avoid combining a nonzero model retry setting with this processor unless you intentionally accept additional attempts.
+
+### Override retries for one step
+
+A step's `judge` configuration overrides scorer-level judge fields. Processor arrays replace the scorer-level arrays. Omit `maxProcessorRetries` in the step configuration to inherit the scorer-level numeric cap.
+
+Coordinated processor retries require a judge model that uses Mastra’s current generation API. Legacy model adapters call [`generateLegacy()`](https://mastra.ai/reference/agents/generateLegacy), bypass error processors, and use that API's separate AI SDK `maxRetries` default of `2`.
+
 ## Type safety
 
 You can specify input/output types when creating scorers for better type inference and IntelliSense support:

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -2,9 +2,9 @@
 
 # StreamErrorRetryProcessor
 
-`StreamErrorRetryProcessor` is an **error processor** that retries transient errors emitted after an LLM stream starts. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific stream error shapes.
+`StreamErrorRetryProcessor` is an **error processor** that retries transient LLM API and stream failures. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific error shapes.
 
-The processor isn't enabled by default in core. Add it to `errorProcessors` for agents that need stream-error retry handling.
+The processor isn't enabled by default in core. Add it to `errorProcessors` for agents that need bounded retry handling.
 
 ## Usage example
 
@@ -35,6 +35,18 @@ When the error is retryable, the processor returns `{ retry: true }`. It doesn't
 
 When `delayMs` is set, the processor waits before signaling a retry. This is useful for transient network errors like `ECONNRESET` where immediately retrying is likely to fail again. The delay can be a fixed number of milliseconds or a function evaluated with the error args (for example, to implement exponential backoff).
 
+### Retry limits
+
+`maxRetries` defaults to `1` and limits this processor's retry requests. The agent also limits processor retries with `maxProcessorRetries`. When error processors are configured without an agent limit, the runtime cap is `10`.
+
+Set both values explicitly to the same bounded value when you need a single retry budget. Keep model `maxRetries` at `0` for that call to avoid multiplying provider attempts.
+
+### `Retry-After` handling
+
+For retryable errors with a `Retry-After` response header, the processor reads case-insensitive delta-seconds and HTTP-date values through the error cause chain. It waits for the longer of `delayMs` and the bounded server delay.
+
+`maxRetryAfterMs` defaults to `30_000`. It caps only provider-provided wait time. A longer explicit `delayMs` remains unchanged. Invalid or expired headers are ignored.
+
 ## Retry unknown errors
 
 Set `retryUnknownErrors` to retry errors that don't match provider metadata, the built-in OpenAI matcher, or a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:

package/.docs/reference/pubsub/base.md

@@ -101,6 +101,16 @@ Waits for any in-flight deliveries to settle. Call this before shutdown to avoid
 await pubsub.flush()
 ```
 
+#### `clearTopic(topic)`
+
+Deletes all retained state for a topic — cached history, persistent stream entries, and consumer groups — once no more events will be published to it. Mastra's run lifecycles (durable agents and the evented workflow engine) call this automatically when a run reaches a terminal state, so per-run topics don't accumulate on transports that retain messages.
+
+The default implementation is a no-op: transports that retain nothing per topic (such as `EventEmitterPubSub`) have nothing to clear. Backends that persist messages, like [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), override it. The contract is best-effort — implementations log failures rather than throwing, because callers invoke it fire-and-forget at cleanup boundaries.
+
+```typescript
+await pubsub.clearTopic('workflow.events.v2.run-123')
+```
+
 ### Replay methods
 
 These methods support resuming a stream after a disconnect. The default implementations fall back to a regular `subscribe`, so backends without history support behave as live-only. [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) overrides them to replay cached events.

package/.docs/reference/pubsub/caching-pubsub.md

@@ -92,6 +92,14 @@ const events = await pubsub.getHistory('my-topic', 0)
 
 Returns: `Promise<Event[]>`
 
+### `clearTopic(topic)`
+
+Removes the topic's cached events and offset counter, and forwards the call to the inner pub/sub so persistent transports (such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)) can delete their retained state too. Mastra's run lifecycles call this automatically when a run finishes.
+
+```typescript
+await pubsub.clearTopic('my-topic')
+```
+
 ## Functions
 
 ### `withCaching(pubsub, cache, options?)`

package/.docs/reference/pubsub/redis-streams.md

@@ -101,7 +101,7 @@ await pubsub.flush()
 
 ### `clearTopic(topic)`
 
-Deletes a topic's stream and every consumer group on it, freeing the memory a finished topic would otherwise hold. The durable-agent runtime calls this automatically when a run's cleanup fires; call it yourself only once nothing will read the topic again. It's best-effort and never throws — failures are logged at warn level. A subscriber still attached when the stream is deleted recovers on its own but misses the deleted entries.
+Deletes a topic's stream and every consumer group on it, freeing the memory a finished topic would otherwise hold. Mastra's run lifecycles — durable agents and the evented workflow engine — call this automatically when a run reaches a terminal state; call it yourself only once nothing will read the topic again. It's best-effort and never throws — failures are logged at warn level. A subscriber still attached when the stream is deleted recovers on its own but misses the deleted entries.
 
 Automatic cleanup requires `@mastra/core` and `@mastra/redis-streams` versions that both support `clearTopic`: the runtime routes the call through its caching layer, so upgrade the two packages together to get end-of-run stream deletion.
 

package/.docs/reference/voice/google.md

@@ -12,7 +12,7 @@ import { GoogleVoice } from '@mastra/voice-google'
 // Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
 const voice = new GoogleVoice()
 
-// Text-to-Speech
+// Text-to-Speech (plain text)
 const audioStream = await voice.speak('Hello, world!', {
   languageCode: 'en-US',
   audioConfig: {
@@ -20,6 +20,19 @@ const audioStream = await voice.speak('Hello, world!', {
   },
 })
 
+// Text-to-Speech with SSML
+const ssmlStream = await voice.speak('ignored', {
+  input: {
+    ssml: '<speak>Take <say-as interpret-as="unit">5 mg</say-as> daily.</speak>',
+  },
+})
+
+// Text-to-Speech with Gemini-TTS model
+const geminiStream = await voice.speak('Hello from Gemini TTS!', {
+  voice: { name: 'Kore', modelName: 'gemini-2.5-flash-preview-tts' },
+  input: { prompt: 'Warm, calm tone.' },
+})
+
 // Speech-to-Text
 const transcript = await voice.listen(audioStream, {
   config: {
@@ -68,25 +81,52 @@ Converts text to speech using Google Cloud Text-to-Speech service.
 
 **options** (`object`): Speech synthesis options
 
-**options.speaker** (`string`): Voice ID to use for this request
+**options.speaker** (`string`): Voice ID to use for this request.
+
+**options.languageCode** (`string`): Language code for the voice (e.g., 'en-US'). Defaults to the language code derived from the speaker ID, or 'en-US'.
 
-**options.languageCode** (`string`): Language code for the voice (e.g., 'en-US'). Defaults to the language code from the speaker ID or 'en-US'
+**options.input** (`ISynthesizeSpeechRequest['input']`): Rich input object passed through to the Google Cloud TTS API. Supports ssml, markup, prompt (Gemini-TTS style steering), customPronunciations, and multiSpeakerMarkup. When provided without text, ssml, markup, or multiSpeakerMarkup, the positional input argument is used as the text field automatically.
 
-**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Audio configuration options from Google Cloud Text-to-Speech API
+**options.voice** (`ISynthesizeSpeechRequest['voice']`): Voice configuration merged on top of defaults (name and languageCode). Supports modelName (e.g., 'gemini-2.5-flash-preview-tts') and multiSpeakerVoiceConfig.
+
+**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Audio configuration options from Google Cloud Text-to-Speech API.
 
 Returns: `Promise<NodeJS.ReadableStream>`
 
 ### `listen()`
 
-Converts speech to text using Google Cloud Speech-to-Text service.
+Converts speech to text using Google Cloud Speech-to-Text service. Supports both v1 (default) and v2 APIs. The v2 API adds support for AAC-in-MP4 audio (iOS Safari) via auto-decoding.
+
+#### v1 (default)
 
 **audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
 
-**options** (`object`): Recognition options
+**options** (`GoogleListenOptionsV1`): v1 recognition options
+
+**options.config** (`IRecognitionConfig`): v1 recognition configuration from Google Cloud Speech-to-Text API
+
+#### v2
+
+Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
+
+```typescript
+const transcript = await voice.listen(iosSafariAacStream, {
+  v2: true,
+  config: {
+    autoDecodingConfig: {},
+  },
+})
+```
+
+**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
+
+**options** (`GoogleListenOptionsV2`): v2 recognition options
+
+**options.v2** (`true`): Enables the v2 API path
 
-**options.stream** (`boolean`): Whether to use streaming recognition
+**options.config** (`v2.IRecognitionConfig`): v2 recognition configuration. Defaults to auto-decoding with languageCodes: \['en-US'] and model: 'long'. Set autoDecodingConfig: {} to auto-detect the audio format, or use explicitDecodingConfig to specify an encoding like MP4\_AAC, M4A\_AAC, or MOV\_AAC.
 
-**options.config** (`IRecognitionConfig`): Recognition configuration from Google Cloud Speech-to-Text API
+**options.recognizer** (`string`): v2 recognizer resource path. Defaults to projects/{project}/locations/global/recognizers/\_ where {project} is resolved from the constructor project option, GOOGLE\_CLOUD\_PROJECT, or the client's default project.
 
 Returns: `Promise<string>`
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.7-alpha.22
+
+### Patch Changes
+
+- Updated dependencies [[`aa38805`](https://github.com/mastra-ai/mastra/commit/aa38805b878b827403be785eb90688d7172f5a40), [`2d22570`](https://github.com/mastra-ai/mastra/commit/2d22570c7dfdd02123d0ecc529efb05ccba2d9fc), [`4378341`](https://github.com/mastra-ai/mastra/commit/43783412df5ea3dd35f5b1f6e4851e79c346fc89)]:
+  - @mastra/core@1.51.0-alpha.12
+
+## 1.2.7-alpha.21
+
+### Patch Changes
+
+- Updated dependencies [[`45a8e65`](https://github.com/mastra-ai/mastra/commit/45a8e65e1556d1362cb3f25187023c36de26661d), [`c8ed116`](https://github.com/mastra-ai/mastra/commit/c8ed11699f62bcac70102ab4ec84d80d20541da6), [`33f2b88`](https://github.com/mastra-ai/mastra/commit/33f2b88842c09a567f906fac4cb61cd5277ced59)]:
+  - @mastra/core@1.51.0-alpha.11
+
 ## 1.2.7-alpha.20
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.7-alpha.20",
+  "version": "1.2.7-alpha.22",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.14.0-alpha.0",
-    "@mastra/core": "1.51.0-alpha.10"
+    "@mastra/core": "1.51.0-alpha.12",
+    "@mastra/mcp": "^1.14.0-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.113",
     "@internal/types-builder": "0.0.88",
-    "@mastra/core": "1.51.0-alpha.10"
+    "@internal/lint": "0.0.113",
+    "@mastra/core": "1.51.0-alpha.12"
   },
   "homepage": "https://mastra.ai",
   "repository": {