@mastra/mcp-docs-server 1.2.7-alpha.21 → 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/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.7-alpha.21",
+  "version": "1.2.7-alpha.22",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.51.0-alpha.11",
+    "@mastra/core": "1.51.0-alpha.12",
     "@mastra/mcp": "^1.14.0-alpha.0"
   },
   "devDependencies": {
@@ -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.11"
+    "@internal/lint": "0.0.113",
+    "@mastra/core": "1.51.0-alpha.12"
   },
   "homepage": "https://mastra.ai",
   "repository": {