@mastra/mcp-docs-server 1.2.19-alpha.16 → 1.2.19-alpha.18

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

@@ -105,6 +105,60 @@ The root URL for the endpoints below is: `/v1/gateway`
 | GET    | `/projects/:id/memory/threads/:threadId/observations/history` | Observation history (dashboard)             |
 | GET    | `/models`                                                     | List available models                       |
 
+## Observability feedback query API
+
+The hosted feedback query API lists and analyzes feedback exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.
+
+Use the root URL for your environment's data-residency region:
+
+| Region         | Root URL                                               |
+| -------------- | ------------------------------------------------------ |
+| United States  | `https://observability.mastra.ai/api/observability`    |
+| European Union | `https://observability.eu.mastra.ai/api/observability` |
+
+Telemetry stays in its residency region. Querying the other region returns no records for the environment. See [Observability co-location](https://mastra.ai/docs/mastra-platform/regions) for the environment-to-region mapping.
+
+### Authentication and project scope
+
+Every request requires a platform access token. Create one in [Mastra Platform](https://projects.mastra.ai), or use the token written to `.env` during Platform setup.
+
+Include `X-Mastra-Project-Id` to limit results to one project. If you omit it, the query covers feedback in every project available to the token's organization.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/feedback?page=0&perPage=20&feedbackType=rating" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Use an organization-scoped Platform access token. Gateway inference keys such as `mk_*` keys aren't accepted. Queries remain constrained to the token's organization even when you supply a project ID.
+
+### Endpoints
+
+| Method | Endpoint                | Description                  |
+| ------ | ----------------------- | ---------------------------- |
+| GET    | `/feedback`             | List feedback records        |
+| POST   | `/feedback/aggregate`   | Return one aggregate value   |
+| POST   | `/feedback/breakdown`   | Group feedback by dimensions |
+| POST   | `/feedback/timeseries`  | Bucket feedback by interval  |
+| POST   | `/feedback/percentiles` | Return percentile series     |
+
+The list endpoint accepts page-mode parameters such as `page`, `perPage`, `field`, and `direction`, plus feedback filters as query parameters. It also supports delta polling with `mode=delta`, `after`, and `limit`. Responses contain a `feedback` array and page or delta metadata.
+
+Analytics endpoints accept the same JSON request shapes and return types as the [feedback reference](https://mastra.ai/reference/observability/feedback). Analytics operate only on numeric feedback values.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/feedback/aggregate" \
+  -X POST \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
+  -H "Content-Type: application/json" \
+  --data '{"feedbackType":"rating","feedbackSource":"user","aggregation":"avg"}' | jq
+```
+
+The API returns `401` for invalid credentials, `403` for organization authorization failures, and `400` for malformed query arguments or JSON bodies.
+
+Hosted observability doesn't provide a feedback creation route. Export feedback from the application as described in [Export feedback to Mastra Platform](https://mastra.ai/docs/observability/feedback).
+
 ## Gateway proxy endpoints
 
 Visit the [Gateway documentation](https://gateway.mastra.ai/docs) for more details.

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

@@ -130,7 +130,7 @@ See [Mastra storage exporter](https://mastra.ai/docs/observability/integrations/
 
 ## View observability data
 
-Open your project in [Mastra Platform](https://projects.mastra.ai) to inspect exported traces, logs, metrics, scores, and feedback. A Studio or Server deployment isn't required.
+Open your project in [Mastra Platform](https://projects.mastra.ai) to inspect exported traces, logs, metrics, and scores. A Studio or Server deployment isn't required. Query exported feedback through the hosted feedback API described below.
 
 Use a consistent `serviceName` to filter data from a specific application or deployment.
 
@@ -164,6 +164,8 @@ bun x mastra api trace list
 
 The CLI can infer platform credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available commands, filtering, pagination, credential resolution, and `curl` examples.
 
+You can query exported feedback over HTTP. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, and project scoping.
+
 ## Next steps
 
 - 📹 [Mastra observability and Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)

package/.docs/docs/observability/feedback.md

@@ -33,6 +33,10 @@ await mastra.observability.addFeedback({
 })
 ```
 
+When you pass only `traceId` and `spanId`, `addFeedback()` rehydrates the target from configured observability storage before emitting the feedback event. Configure [`MastraStorageExporter`](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) when feedback is added after the traced execution has finished. If the trace isn't available in storage, Mastra logs a warning and drops the feedback event.
+
+During a live traced execution, you can pass its `correlationContext` to emit feedback without rehydrating the trace from storage. This path is useful when the active request collects feedback before its tracing context ends.
+
 ## Find the trace for a message
 
 Feedback is usually collected against a message a user has already read, so you need the `traceId` for that message. Assistant messages carry it in `content.metadata`, both in the stream result and when the message is recalled later from memory:
@@ -143,6 +147,16 @@ const ratingsOverTime = await observability!.getFeedbackTimeSeries({
 
 See the [feedback reference](https://mastra.ai/reference/observability/feedback) for all fields, filters, return types, and percentile query parameters.
 
+The local runtime exposes the list route at `/api/observability/feedback` and analytics under its related paths. See the [HTTP routes table](https://mastra.ai/reference/observability/feedback). Mastra Platform provides a separate, unversioned hosted query API. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for regional endpoints, authentication, and project scoping.
+
+## Export feedback to Mastra Platform
+
+[`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) forwards emitted feedback events to Mastra Platform automatically because the hosted query API doesn't provide a creation route.
+
+If your application adds feedback after an agent or workflow response using only its `traceId`, configure `MastraStorageExporter` alongside `MastraPlatformExporter`. The storage exporter keeps the trace available for `addFeedback()` to rehydrate, and the Platform exporter forwards the resulting feedback event. Exporting a trace to Platform doesn't make it available to the application's local storage.
+
+See [Observability on Mastra Platform](https://mastra.ai/docs/mastra-platform/observability) for the combined exporter configuration.
+
 ## Export feedback to external platforms
 
 Feedback flows through the observability event bus, so exporters that support feedback forward it automatically. The [PostHog exporter](https://mastra.ai/reference/observability/tracing/exporters/posthog) sends feedback as native `$ai_feedback` events that appear on the linked trace in PostHog.

package/.docs/docs/server/middleware.md

@@ -58,6 +58,32 @@ registerApiRoute('/my-custom-route', {
 
 ## Common examples
 
+### Block built-in route groups
+
+Mastra doesn't provide a configuration option to remove or allowlist built-in routes. On Hono-based serving paths, you can make selected route groups unavailable by returning a response without calling `next()`:
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const notFound = async () => new Response('Not Found', { status: 404 })
+
+export const mastra = new Mastra({
+  server: {
+    middleware: [
+      { path: '/api/memory/*', handler: notFound },
+      { path: '/api/logs/*', handler: notFound },
+      { path: '/api/observability/*', handler: notFound },
+    ],
+  },
+})
+```
+
+Each wildcard pattern blocks both the route group itself and its nested routes. For example, `/api/logs/*` blocks `/api/logs` and `/api/logs/transports`. Other route groups remain available.
+
+Generated servers pass `server.apiPrefix` to the Hono adapter's [`prefix` constructor option](https://mastra.ai/reference/server/hono-adapter), which prefixes built-in routes. Middleware paths are registered unchanged, so they must explicitly include the configured prefix. For example, with `apiPrefix: '/api/v2'`, use `/api/v2/memory/*`. Custom API routes must live outside the configured API prefix and aren't blocked by these patterns.
+
+This approach can't block routes declared public with `requiresAuth: false`, because Mastra skips user middleware for those routes. With a non-Hono server adapter, register equivalent middleware through the server framework instead.
+
 ### Using `RequestContext`
 
 You can populate `RequestContext` in a runtime server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.

package/.docs/docs/subagents.md

@@ -159,12 +159,12 @@ const stream = await parentAgent.stream('Research AI trends', {
 
 The `context` object includes:
 
-| Property      | Description                              |
-| ------------- | ---------------------------------------- |
-| `primitiveId` | The ID of the subagent that ran          |
-| `result`      | The subagent's response                  |
-| `error`       | Error if the delegation failed           |
-| `bail()`      | Function to stop the parent agent's loop |
+| Property      | Description                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `primitiveId` | The ID of the subagent that ran                                                               |
+| `result`      | The subagent's response, including `text`, `usage`, `finishReason`, and `subAgentToolResults` |
+| `error`       | Error if the delegation failed                                                                |
+| `bail()`      | Function to stop the parent agent's loop                                                      |
 
 ### Hook errors
 

package/.docs/integrations/channels/github.md

@@ -74,7 +74,7 @@ export const mastra = new Mastra({
 })
 ```
 
-After the agent has created a memory thread, subscribe that thread to a PR. Passing `owner` and `repo` works from any directory:
+After the agent has created a memory thread, subscribe that thread to a PR. Choose `review` mode when the thread only needs code revisions, authorized latest PR comments, and observable review-thread-state updates:
 
 ```typescript
 await githubSignals.subscribeThreadToPR({
@@ -85,19 +85,66 @@ await githubSignals.subscribeThreadToPR({
     repo: 'web-app',
     number: 42,
   },
+  mode: 'review',
 })
 ```
 
 The provider syncs the PR immediately, stores the subscription, and starts polling every five minutes. Set `pollIntervalMs` in the `GithubSignals` constructor to change the interval. If the process restarts, call `startPollingForThread()` for each persisted thread subscription to resume polling.
 
-## Pull request notifications
+A thread has one current GitHub Signals subscription. Subscribing it to another PR replaces the existing subscription.
 
-GitHub Signals notifies the agent when a subscribed PR has:
+## Subscription modes
 
-- A new authorized comment, commit, or other pull request activity.
-- A change in unresolved review threads.
-- Continuous integration (CI) checks that start, fail, or recover.
-- Merge conflicts that appear or are resolved.
-- A state change to closed, reopened, or merged.
+GitHub Signals supports two subscription modes:
 
-The initial sync sends a baseline notification with the current PR state. A merge automatically removes the thread's subscription to that PR.
+- `review`: Follows new head revisions, authorized latest PR comments, and observable review-thread-state changes, including when all review threads become resolved.
+- `working`: Follows all actionable PR activity detected by the provider. Comment-bearing notifications remain subject to existing authorization gates. This is the default when `mode` is omitted and for stored subscriptions without a valid mode.
+
+The following table shows the observable behavior of each mode:
+
+| Pull request activity                                 | `working`                                             | `review`                                                                                                          |
+| ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| First observation                                     | Sends a baseline notification                         | Saves all cursors without notifying unless the PR is closed or merged; then notifies and removes the subscription |
+| New commit or force-push                              | Notifies when the latest comment author is authorized | Notifies without requiring a comment author                                                                       |
+| New authorized latest PR comment                      | Notifies                                              | Notifies                                                                                                          |
+| Observable review-thread-state change                 | Notifies while unresolved threads remain              | Notifies, including when all review threads become resolved                                                       |
+| Continuous integration checks start, fail, or recover | Notifies                                              | Saves the new state without notifying                                                                             |
+| Merge conflicts appear or resolve                     | Notifies                                              | Saves the new state without notifying                                                                             |
+| Other actionable aggregate PR activity                | Notifies when applicable authorization checks pass    | Saves the new state without notifying                                                                             |
+| PR closes without merging                             | Notifies and keeps the subscription                   | Notifies and removes the subscription                                                                             |
+| PR reopens                                            | Notifies                                              | Doesn't notify because the earlier close removed the subscription                                                 |
+| PR merges                                             | Notifies and removes the subscription                 | Notifies and removes the subscription                                                                             |
+
+Review mode uses the latest generic PR comment exposed by `gitcrawl`. The snapshot doesn't distinguish general PR conversation from inline review comments. Comment notifications require an authorized author because they include comment content. Review-state notifications contain only provider-generated state summaries and aren't author-gated.
+
+The review-state cursor includes the unresolved thread count and the latest unresolved thread timestamp. It reports when the count reaches zero, but it can't report replies on threads that are already resolved.
+
+During subscription, a PR already known to be closed or merged isn't stored and doesn't send an activity notification. Otherwise, review mode silently saves its first available non-terminal snapshot, including when the subscribe-time snapshot fails and a later poll supplies the first observation. If the first available poll snapshot or a later snapshot is closed or merged, the provider sends a terminal notification and removes the subscription. It doesn't follow a later reopen unless you subscribe again.
+
+## Subscription tools
+
+The provider adds `github_subscribe_pr` and `github_unsubscribe_pr` tools to the agent. Pass `mode` when subscribing:
+
+```json
+{
+  "owner": "acme",
+  "repo": "web-app",
+  "number": 42,
+  "mode": "review"
+}
+```
+
+Omitting `mode` selects `working`. Don't subscribe for a one-off PR inspection.
+
+## MastraCode commands
+
+In MastraCode, use the spaced `--mode` flag with a PR number, `owner/repo#number`, or full GitHub PR URL:
+
+```text
+/github subscribe 42 --mode review
+/github acme/web-app#42 --mode working
+/github unsubscribe 42
+/github debug
+```
+
+MastraCode rejects `--mode=review`, missing or repeated mode values, unknown modes, and mode flags on unsubscribe. `/github debug` shows the stored mode and displays absent or invalid legacy values as `working`.

package/.docs/integrations/sandboxes/daytona.md

@@ -282,6 +282,22 @@ await sandbox.instance.updateNetworkSettings({
 })
 ```
 
+### Secrets
+
+Inject credentials without exposing raw values to code running inside the sandbox. Create a [Daytona Secret](https://www.daytona.io/docs/en/secrets/) once for your organization (via the Daytona dashboard or SDK), then map environment variable names to Secret names:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DaytonaSandbox({
+    secrets: {
+      GITHUB_TOKEN: 'github-token',
+    },
+  }),
+})
+```
+
+Inside the sandbox, the environment variable holds an opaque placeholder. Daytona's egress proxy substitutes the real value into HTTPS request headers toward the Secret's allowed hosts, so the raw credential never enters the sandbox. Secrets are applied at sandbox creation and are preserved by `clone()`.
+
 ## Constructor parameters
 
 **id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
@@ -328,6 +344,8 @@ await sandbox.instance.updateNetworkSettings({
 
 **domainAllowList** (`string`): Comma-separated list of allowed domains when network access is restricted. Supports wildcards, for example \*.githubusercontent.com. Use this instead of networkAllowList for services whose IP addresses change.
 
+**secrets** (`Record<string, string>`): Daytona Secrets to expose inside the sandbox, mapping environment variable names to Daytona Secret names. The env var holds an opaque placeholder; the real value is substituted into HTTPS request headers at egress toward the Secret's allowed hosts.
+
 ## Properties
 
 **id** (`string`): Sandbox instance identifier.

package/.docs/integrations/sandboxes/e2b.md

@@ -68,6 +68,8 @@ const agent = new Agent({
 
 **id** (`string`): Unique identifier for this sandbox instance (Default: `Auto-generated`)
 
+**sandboxId** (`string`): Persisted E2B provider sandbox ID to reattach to deterministically. When set, start() connects to this exact sandbox (resuming it if paused) instead of discovering by logical id metadata. Only a typed "sandbox gone" error (not found, killed, or not running) falls through to the usual logical-id lookup and create ladder; auth, quota, rate-limit, timeout, and network errors propagate without creating a new sandbox. A sandbox tagged with a different logical id is refused. Read the resolved provider ID from the sandboxId property after start.
+
 **domain** (`string`): Domain for self-hosted E2B. Falls back to E2B\_DOMAIN env var.
 
 **apiUrl** (`string`): API URL for self-hosted E2B. Falls back to E2B\_API\_URL env var.
@@ -88,6 +90,8 @@ const agent = new Agent({
 
 **status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
 
+**sandboxId** (`string | undefined`): The E2B provider sandbox ID resolved after connect or create. Persist it and pass it back via the sandboxId constructor option (or clone({ sandboxId })) to reattach deterministically. Undefined until the sandbox has been started in this process.
+
 **processes** (`E2BProcessManager`): Background process manager. See SandboxProcessManager reference.
 
 ## Background processes

package/.docs/integrations/sandboxes/vercel.md

@@ -158,7 +158,7 @@ Both callbacks are optional and can be used independently.
 
 **instructions** (`string | ((opts) => string)`): Override the default instructions returned by getInstructions(). Pass a string to replace them, or a function to extend the defaults.
 
-**onStart** (`SandboxLifecycleHook`): Lifecycle hook called after the sandbox reaches running status.
+**onStart** (`SandboxStartHook`): Lifecycle hook called after the sandbox reaches running status.
 
 **onStop** (`SandboxLifecycleHook`): Lifecycle hook called before the sandbox stops.
 
@@ -303,7 +303,7 @@ const workspace = new Workspace({
 
 **instructions** (`string | ((opts) => string)`): Custom instructions that override the default instructions returned by getInstructions(). Pass a string to fully replace, or a function to extend the defaults.
 
-**onStart** (`SandboxLifecycleHook`): Lifecycle hook called after the sandbox reaches running status.
+**onStart** (`SandboxStartHook`): Lifecycle hook called after the sandbox reaches running status.
 
 **onStop** (`SandboxLifecycleHook`): Lifecycle hook called before the sandbox stops.
 

package/.docs/models/environment-variables.md

@@ -126,6 +126,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Opper](https://mastra.ai/models/providers/opper)                                              | `opper/*`                  | `OPPER_API_KEY`                                                                                       |
 | [OrcaRouter](https://mastra.ai/models/providers/orcarouter)                                    | `orcarouter/*`             | `ORCAROUTER_API_KEY`                                                                                  |
 | [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)                           | `ovhcloud/*`               | `OVHCLOUD_API_KEY`                                                                                    |
+| [Pendra](https://mastra.ai/models/providers/pendra)                                            | `pendra/*`                 | `PENDRA_API_KEY`                                                                                      |
 | [Perplexity](https://mastra.ai/models/providers/perplexity)                                    | `perplexity/*`             | `PERPLEXITY_API_KEY`                                                                                  |
 | [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)                        | `perplexity-agent/*`       | `PERPLEXITY_API_KEY`                                                                                  |
 | [Pioneer](https://mastra.ai/models/providers/pioneer)                                          | `pioneer/*`                | `PIONEER_API_KEY`                                                                                     |

package/.docs/models/gateways/netlify.md

@@ -2,7 +2,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 234 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 233 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -137,7 +137,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/google/gemma-3-12b-it`                                    |
 | `openrouter/google/gemma-3-27b-it`                                    |
 | `openrouter/google/gemma-3-4b-it`                                     |
-| `openrouter/google/gemma-3n-e4b-it`                                   |
 | `openrouter/google/gemma-4-26b-a4b-it`                                |
 | `openrouter/google/gemma-4-31b-it`                                    |
 | `openrouter/gryphe/mythomax-l2-13b`                                   |

package/.docs/models/gateways/openrouter.md

@@ -2,7 +2,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 357 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 355 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -131,7 +131,6 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemma-3-12b-it`                                    |
 | `google/gemma-3-27b-it`                                    |
 | `google/gemma-3-4b-it`                                     |
-| `google/gemma-3n-e4b-it`                                   |
 | `google/gemma-4-26b-a4b-it`                                |
 | `google/gemma-4-26b-a4b-it:free`                           |
 | `google/gemma-4-31b-it`                                    |
@@ -295,7 +294,6 @@ ANTHROPIC_API_KEY=ant-...
 | `qwen/qwen-2.5-coder-32b-instruct`                         |
 | `qwen/qwen-plus`                                           |
 | `qwen/qwen-plus-2025-07-28`                                |
-| `qwen/qwen-plus-2025-07-28:thinking`                       |
 | `qwen/qwen2.5-vl-72b-instruct`                             |
 | `qwen/qwen3-14b`                                           |
 | `qwen/qwen3-235b-a22b`                                     |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6837 models from 186 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6846 models from 187 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/agnes.md

@@ -2,7 +2,7 @@
 
 # ![Agnes AI logo](https://models.dev/logos/agnes.svg)Agnes AI
 
-Access 2 Agnes AI models through Mastra's model router. Authentication is handled automatically using the `AGNES_API_KEY` environment variable.
+Access 3 Agnes AI models through Mastra's model router. Authentication is handled automatically using the `AGNES_API_KEY` environment variable.
 
 Learn more in the [Agnes AI documentation](https://agnes-ai.com/doc).
 
@@ -34,10 +34,11 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                   | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ----------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `agnes/agnes-2.0-flash` | 512K    |       |           |       |       |       | —          | —           |
-| `agnes/agnes-2.5-flash` | 512K    |       |           |       |       |       | —          | —           |
+| Model                       | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| --------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `agnes/agnes-2.0-flash`     | 512K    |       |           |       |       |       | —          | —           |
+| `agnes/agnes-2.5-flash`     | 512K    |       |           |       |       |       | —          | —           |
+| `agnes/agnes-2.5-pro-alpha` | 1.0M    |       |           |       |       |       | $0.45      | $0.90       |
 
 ## Advanced configuration
 
@@ -67,7 +68,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "agnes/agnes-2.5-flash"
+      ? "agnes/agnes-2.5-pro-alpha"
       : "agnes/agnes-2.0-flash";
   }
 });

package/.docs/models/providers/edenai.md

@@ -2,7 +2,7 @@
 
 # ![Eden AI logo](https://models.dev/logos/edenai.svg)Eden AI
 
-Access 231 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
+Access 233 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
 
 Learn more in the [Eden AI documentation](https://docs.edenai.co).
 
@@ -198,8 +198,8 @@ for await (const chunk of stream) {
 | `edenai/perplexityai/sonar-deep-research`                              | 128K    |       |           |       |       |       | $2         | $8          |
 | `edenai/perplexityai/sonar-pro`                                        | 200K    |       |           |       |       |       | $3         | $15         |
 | `edenai/perplexityai/sonar-reasoning-pro`                              | 128K    |       |           |       |       |       | $2         | $8          |
-| `edenai/qwen/deepseek-v4-flash-0731`                                   | 1.0M    |       |           |       |       |       | $0.35      | $1          |
-| `edenai/qwen/deepseek-v4-pro-0813`                                     | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `edenai/qwen/deepseek-v4-flash-0731`                                   | 1.0M    |       |           |       |       |       | $0.18      | $0.53       |
+| `edenai/qwen/deepseek-v4-pro-0813`                                     | 1.0M    |       |           |       |       |       | $0.58      | $2          |
 | `edenai/qwen/qwen-max`                                                 | 33K     |       |           |       |       |       | $2         | $6          |
 | `edenai/qwen/qwen-vl-max`                                              | 131K    |       |           |       |       |       | $0.80      | $3          |
 | `edenai/qwen/qwen-vl-plus`                                             | 131K    |       |           |       |       |       | $0.21      | $0.63       |
@@ -208,8 +208,10 @@ for await (const chunk of stream) {
 | `edenai/qwen/qwen3-coder-480b-a35b-instruct`                           | 262K    |       |           |       |       |       | $2         | $8          |
 | `edenai/qwen/qwen3-coder-flash`                                        | 1.0M    |       |           |       |       |       | $0.30      | $2          |
 | `edenai/qwen/qwen3-coder-next`                                         | 262K    |       |           |       |       |       | $0.30      | $2          |
+| `edenai/qwen/qwen3-coder-next@eu`                                      | 262K    |       |           |       |       |       | $0.30      | $2          |
 | `edenai/qwen/qwen3-coder-plus`                                         | 1.0M    |       |           |       |       |       | $1         | $5          |
 | `edenai/qwen/qwen3-max`                                                | 262K    |       |           |       |       |       | $1         | $6          |
+| `edenai/qwen/qwen3-max@eu`                                             | 262K    |       |           |       |       |       | $1         | $6          |
 | `edenai/qwen/qwen3-next-80b-a3b-instruct`                              | 131K    |       |           |       |       |       | $0.15      | $1          |
 | `edenai/qwen/qwen3-next-80b-a3b-thinking`                              | 131K    |       |           |       |       |       | $0.15      | $1          |
 | `edenai/qwen/qwen3-vl-235b-a22b-instruct`                              | 131K    |       |           |       |       |       | $0.40      | $2          |

package/.docs/models/providers/evroc.md

@@ -2,7 +2,7 @@
 
 # ![evroc logo](https://models.dev/logos/evroc.svg)evroc
 
-Access 15 evroc models through Mastra's model router. Authentication is handled automatically using the `EVROC_API_KEY` environment variable.
+Access 16 evroc models through Mastra's model router. Authentication is handled automatically using the `EVROC_API_KEY` environment variable.
 
 Learn more in the [evroc documentation](https://docs.evroc.com/products/think/overview.html).
 
@@ -49,7 +49,8 @@ for await (const chunk of stream) {
 | `evroc/openai/whisper-large-v3-turbo`           | 448     |       |           |       |       |       | $0.00      | $0.00       |
 | `evroc/Qwen/Qwen3-Embedding-8B`                 | 41K     |       |           |       |       |       | $0.12      | $0.12       |
 | `evroc/Qwen/Qwen3-Reranker-4B`                  | 32K     |       |           |       |       |       | $0.06      | —           |
-| `evroc/Qwen/Qwen3.6-35B-A3B-FP8`                | 262K    |       |           |       |       |       | $0.34      | $1          |
+| `evroc/Qwen/Qwen3.6-35B-A3B`                    | 262K    |       |           |       |       |       | $0.34      | $1          |
+| `evroc/Qwen/Qwen3.8-27B`                        | 262K    |       |           |       |       |       | $0.87      | $4          |
 | `evroc/zai-org/GLM-5.2`                         | 524K    |       |           |       |       |       | $1         | $6          |
 
 ## Advanced configuration

package/.docs/models/providers/hyper.md

@@ -40,11 +40,11 @@ for await (const chunk of stream) {
 | `hyper/deepseek-v4-flash-0731`                       | 1.0M    |       |           |       |       |       | $0.44      | $1          |
 | `hyper/deepseek-v4-pro`                              | 1.0M    |       |           |       |       |       | $2         | $5          |
 | `hyper/deepseek-v4-pro-0813`                         | 1.0M    |       |           |       |       |       | $1         | $4          |
-| `hyper/gemma-4-26b-a4b-it`                           | 256K    |       |           |       |       |       | $0.11      | $0.41       |
-| `hyper/glm-5`                                        | 203K    |       |           |       |       |       | $0.86      | $3          |
+| `hyper/gemma-4-26b-a4b-it`                           | 256K    |       |           |       |       |       | $0.12      | $0.42       |
+| `hyper/glm-5`                                        | 203K    |       |           |       |       |       | $0.91      | $3          |
 | `hyper/glm-5.1`                                      | 203K    |       |           |       |       |       | $1         | $4          |
 | `hyper/glm-5.2`                                      | 1.0M    |       |           |       |       |       | $2         | $5          |
-| `hyper/gpt-oss-120b`                                 | 128K    |       |           |       |       |       | $0.18      | $0.68       |
+| `hyper/gpt-oss-120b`                                 | 128K    |       |           |       |       |       | $0.19      | $0.70       |
 | `hyper/kimi-k2.5`                                    | 262K    |       |           |       |       |       | $0.54      | $3          |
 | `hyper/kimi-k2.6`                                    | 262K    |       |           |       |       |       | $1         | $4          |
 | `hyper/kimi-k2.7-code`                               | 262K    |       |           |       |       |       | $1         | $4          |

package/.docs/models/providers/inceptron.md

@@ -39,7 +39,7 @@ for await (const chunk of stream) {
 | `inceptron/deepseek-ai/DeepSeek-V4-Flash-0731` | 1.0M    |       |           |       |       |       | $0.13      | $0.28       |
 | `inceptron/moonshotai/Kimi-K2.6`               | 262K    |       |           |       |       |       | $0.57      | $3          |
 | `inceptron/moonshotai/Kimi-K2.7-Code`          | 262K    |       |           |       |       |       | $0.67      | $3          |
-| `inceptron/zai-org/GLM-5.2`                    | 1.0M    |       |           |       |       |       | $0.75      | $3          |
+| `inceptron/zai-org/GLM-5.2`                    | 1.0M    |       |           |       |       |       | $0.75      | $2          |
 
 ## Advanced configuration
 

package/.docs/models/providers/kilo.md

@@ -2,7 +2,7 @@
 
 # ![Kilo Gateway logo](https://models.dev/logos/kilo.svg)Kilo Gateway
 
-Access 367 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
+Access 365 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
 
 Learn more in the [Kilo Gateway documentation](https://kilo.ai).
 
@@ -40,10 +40,10 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 200K    |       |           |       |       |       | $1         | $5          |
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
-| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.04      | $0.10       |
+| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.04      | $0.08       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.38      | $2          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
-| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $3         | $14         |
+| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $3         | $13         |
 | `kilo/~openai/gpt-latest`                                       | 1.1M    |       |           |       |       |       | $2         | $10         |
 | `kilo/~openai/gpt-mini-latest`                                  | 400K    |       |           |       |       |       | $0.75      | $5          |
 | `kilo/~x-ai/grok-latest`                                        | 500K    |       |           |       |       |       | $2         | $6          |
@@ -114,7 +114,7 @@ for await (const chunk of stream) {
 | `kilo/google/gemini-2.5-pro-preview`                            | 1.0M    |       |           |       |       |       | $1         | $10         |
 | `kilo/google/gemini-2.5-pro-preview-05-06`                      | 1.0M    |       |           |       |       |       | $1         | $10         |
 | `kilo/google/gemini-3-flash-preview`                            | 1.0M    |       |           |       |       |       | $0.50      | $3          |
-| `kilo/google/gemini-3-pro-image`                                | 66K     |       |           |       |       |       | $2         | $12         |
+| `kilo/google/gemini-3-pro-image`                                | 131K    |       |           |       |       |       | $2         | $12         |
 | `kilo/google/gemini-3-pro-image-preview`                        | 66K     |       |           |       |       |       | $2         | $12         |
 | `kilo/google/gemini-3.1-flash-image`                            | 131K    |       |           |       |       |       | $0.50      | $3          |
 | `kilo/google/gemini-3.1-flash-image-preview`                    | 66K     |       |           |       |       |       | $0.50      | $3          |
@@ -131,7 +131,6 @@ for await (const chunk of stream) {
 | `kilo/google/gemma-3-12b-it`                                    | 131K    |       |           |       |       |       | $0.05      | $0.15       |
 | `kilo/google/gemma-3-27b-it`                                    | 131K    |       |           |       |       |       | $0.08      | $0.16       |
 | `kilo/google/gemma-3-4b-it`                                     | 131K    |       |           |       |       |       | $0.05      | $0.10       |
-| `kilo/google/gemma-3n-e4b-it`                                   | 33K     |       |           |       |       |       | $0.06      | $0.12       |
 | `kilo/google/gemma-4-26b-a4b-it`                                | 262K    |       |           |       |       |       | $0.04      | $0.22       |
 | `kilo/google/gemma-4-31b-it`                                    | 262K    |       |           |       |       |       | $0.08      | $0.35       |
 | `kilo/google/lyria-3-clip-preview`                              | 1.0M    |       |           |       |       |       | —          | —           |
@@ -157,9 +156,9 @@ for await (const chunk of stream) {
 | `kilo/meta-llama/llama-3.1-8b-instruct`                         | 131K    |       |           |       |       |       | $0.02      | $0.04       |
 | `kilo/meta-llama/llama-3.2-1b-instruct`                         | 60K     |       |           |       |       |       | $0.03      | $0.20       |
 | `kilo/meta-llama/llama-3.2-3b-instruct`                         | 131K    |       |           |       |       |       | $0.05      | $0.33       |
-| `kilo/meta-llama/llama-3.3-70b-instruct`                        | 131K    |       |           |       |       |       | $0.10      | $0.32       |
+| `kilo/meta-llama/llama-3.3-70b-instruct`                        | 128K    |       |           |       |       |       | $0.10      | $0.32       |
 | `kilo/meta-llama/llama-4-maverick`                              | 1.0M    |       |           |       |       |       | $0.20      | $0.70       |
-| `kilo/meta-llama/llama-4-scout`                                 | 328K    |       |           |       |       |       | $0.10      | $0.30       |
+| `kilo/meta-llama/llama-4-scout`                                 | 131K    |       |           |       |       |       | $0.10      | $0.30       |
 | `kilo/meta-llama/llama-guard-4-12b`                             | 164K    |       |           |       |       |       | $0.18      | $0.18       |
 | `kilo/meta/muse-glimmer-30b`                                    | 131K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/meta/muse-spark-1.1`                                      | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -173,7 +172,7 @@ for await (const chunk of stream) {
 | `kilo/minimax/minimax-m2-her`                                   | 66K     |       |           |       |       |       | $0.30      | $1          |
 | `kilo/minimax/minimax-m2.1`                                     | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/minimax/minimax-m2.5`                                     | 200K    |       |           |       |       |       | $0.30      | $1          |
-| `kilo/minimax/minimax-m2.7`                                     | 197K    |       |           |       |       |       | $0.30      | $1          |
+| `kilo/minimax/minimax-m2.7`                                     | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/minimax/minimax-m2.7:free`                                | 197K    |       |           |       |       |       | —          | —           |
 | `kilo/minimax/minimax-m3`                                       | 524K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/minimax/minimax-m3:free`                                  | 1.0M    |       |           |       |       |       | —          | —           |
@@ -299,8 +298,7 @@ for await (const chunk of stream) {
 | `kilo/qwen/qwen-2.5-coder-32b-instruct`                         | 33K     |       |           |       |       |       | $0.66      | $1          |
 | `kilo/qwen/qwen-plus`                                           | 1.0M    |       |           |       |       |       | $0.26      | $0.78       |
 | `kilo/qwen/qwen-plus-2025-07-28`                                | 1.0M    |       |           |       |       |       | $0.26      | $0.78       |
-| `kilo/qwen/qwen-plus-2025-07-28:thinking`                       | 1.0M    |       |           |       |       |       | $0.26      | $0.78       |
-| `kilo/qwen/qwen2.5-vl-72b-instruct`                             | 128K    |       |           |       |       |       | $0.80      | $1          |
+| `kilo/qwen/qwen2.5-vl-72b-instruct`                             | 32K     |       |           |       |       |       | $0.25      | $0.75       |
 | `kilo/qwen/qwen3-14b`                                           | 41K     |       |           |       |       |       | $0.23      | $0.91       |
 | `kilo/qwen/qwen3-235b-a22b`                                     | 131K    |       |           |       |       |       | $0.46      | $2          |
 | `kilo/qwen/qwen3-235b-a22b-2507`                                | 262K    |       |           |       |       |       | $0.15      | $0.60       |

package/.docs/models/providers/llmgateway-providers.md

@@ -2,7 +2,7 @@
 
 # ![LLM Gateway logo](https://models.dev/logos/llmgateway-providers.svg)LLM Gateway
 
-Access 377 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
+Access 378 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
 
 Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
 
@@ -133,11 +133,12 @@ for await (const chunk of stream) {
 | `llmgateway-providers/azure/o3`                                     | 200K    |       |           |       |       |       | $2         | $8          |
 | `llmgateway-providers/azure/o3-mini`                                | 200K    |       |           |       |       |       | $1         | $4          |
 | `llmgateway-providers/azure/o4-mini`                                | 200K    |       |           |       |       |       | $1         | $4          |
-| `llmgateway-providers/baidu/deepseek-v4-flash`                      | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
-| `llmgateway-providers/baidu/deepseek-v4-pro`                        | 1.0M    |       |           |       |       |       | $2         | $3          |
+| `llmgateway-providers/baidu/deepseek-v4-flash`                      | 1.0M    |       |           |       |       |       | $0.44      | $1          |
+| `llmgateway-providers/baidu/deepseek-v4-pro`                        | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `llmgateway-providers/baidu/glm-5`                                  | 203K    |       |           |       |       |       | $1         | $3          |
 | `llmgateway-providers/baidu/glm-5.1`                                | 203K    |       |           |       |       |       | $1         | $4          |
 | `llmgateway-providers/baidu/glm-5.2`                                | 1.0M    |       |           |       |       |       | $1         | $4          |
+| `llmgateway-providers/baidu/glm-5.3`                                | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `llmgateway-providers/baidu/kimi-k2.6`                              | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `llmgateway-providers/bytedance/deepseek-v3.2`                      | 131K    |       |           |       |       |       | $0.28      | $0.42       |
 | `llmgateway-providers/bytedance/deepseek-v4-flash`                  | 1.0M    |       |           |       |       |       | $0.44      | $1          |

package/.docs/models/providers/nano-gpt.md

@@ -2,7 +2,7 @@
 
 # ![NanoGPT logo](https://models.dev/logos/nano-gpt.svg)NanoGPT
 
-Access 606 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
+Access 608 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
 
 Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
 
@@ -472,6 +472,8 @@ for await (const chunk of stream) {
 | `nano-gpt/qwen/Qwen3.6-35B-A3B:thinking`                         | 262K    |       |           |       |       |       | $0.11      | $0.80       |
 | `nano-gpt/qwen/qwen3.8-27b-obliterated`                          | 262K    |       |           |       |       |       | $0.18      | $0.50       |
 | `nano-gpt/qwen/qwen3.8-27b-obliterated:thinking`                 | 262K    |       |           |       |       |       | $0.18      | $0.50       |
+| `nano-gpt/qwen/qwen3.8-27b-uncensored`                           | 262K    |       |           |       |       |       | $0.18      | $0.50       |
+| `nano-gpt/qwen/qwen3.8-27b-uncensored:thinking`                  | 262K    |       |           |       |       |       | $0.18      | $0.50       |
 | `nano-gpt/qwen25-vl-72b-instruct`                                | 32K     |       |           |       |       |       | $0.70      | $0.70       |
 | `nano-gpt/qwen3-30b-a3b-instruct-2507`                           | 256K    |       |           |       |       |       | $0.20      | $0.50       |
 | `nano-gpt/qwen3-coder-30b-a3b-instruct`                          | 128K    |       |           |       |       |       | $0.10      | $0.40       |

package/.docs/models/providers/opencode-go.md

@@ -2,7 +2,7 @@
 
 # ![OpenCode Go logo](https://models.dev/logos/opencode-go.svg)OpenCode Go
 
-Access 29 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 30 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Go documentation](https://opencode.ai/docs/zen).
 
@@ -43,7 +43,7 @@ for await (const chunk of stream) {
 | `opencode-go/glm-5.2`                      | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `opencode-go/glm-5.3`                      | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `opencode-go/gpt-5.6-luna`                 | 1.1M    |       |           |       |       |       | $0.20      | $1          |
-| `opencode-go/grok-4.5`                     | 500K    |       |           |       |       |       | $2         | $6          |
+| `opencode-go/grok-4.6`                     | 500K    |       |           |       |       |       | $2         | $6          |
 | `opencode-go/hy3`                          | 256K    |       |           |       |       |       | $0.02      | $0.07       |
 | `opencode-go/kimi-k2.6`                    | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `opencode-go/kimi-k2.7-code`               | 262K    |       |           |       |       |       | $0.95      | $4          |

package/.docs/models/providers/pendra.md

@@ -0,0 +1,78 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![Pendra logo](https://models.dev/logos/pendra.svg)Pendra
+
+Access 6 Pendra models through Mastra's model router. Authentication is handled automatically using the `PENDRA_API_KEY` environment variable.
+
+Learn more in the [Pendra documentation](https://pendra.ai/docs/integrations/opencode).
+
+```bash
+PENDRA_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "pendra/deepseek-v4-flash"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Note:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Pendra documentation](https://pendra.ai/docs/integrations/opencode) for details.
+
+## Models
+
+| Model                      | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| -------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `pendra/deepseek-v4-flash` | 1.0M    |       |           |       |       |       | —          | —           |
+| `pendra/glm-4.7-flash`     | 200K    |       |           |       |       |       | —          | —           |
+| `pendra/gpt-oss:120b`      | 131K    |       |           |       |       |       | —          | —           |
+| `pendra/llama3.3:70b`      | 128K    |       |           |       |       |       | —          | —           |
+| `pendra/qwen3-coder:30b`   | 262K    |       |           |       |       |       | —          | —           |
+| `pendra/qwen3.6:27b`       | 262K    |       |           |       |       |       | —          | —           |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://api.pendra.ai/api/v1",
+    id: "pendra/deepseek-v4-flash",
+    apiKey: process.env.PENDRA_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "pendra/qwen3.6:27b"
+      : "pendra/deepseek-v4-flash";
+  }
+});
+```

package/.docs/models/providers.md

@@ -125,6 +125,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Opper](https://mastra.ai/models/providers/opper)
 - [OrcaRouter](https://mastra.ai/models/providers/orcarouter)
 - [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)
+- [Pendra](https://mastra.ai/models/providers/pendra)
 - [Perplexity](https://mastra.ai/models/providers/perplexity)
 - [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)
 - [Pioneer](https://mastra.ai/models/providers/pioneer)

package/.docs/reference/cli/mastra.md

@@ -1100,9 +1100,9 @@ For runtime commands, the command resolves the target server in this order:
 2. `http://localhost:4111` for a local `mastra dev` server.
 3. `.mastra-project.json` for a Mastra platform project.
 
-Automatic platform auth is only used when the CLI resolves a Mastra platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
+Automatic Platform authentication is used when the CLI resolves a project from `.mastra-project.json` or recognizes an explicit Mastra-hosted Studio, Factory, or observability URL. Localhost and arbitrary explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
-For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. Both resolve credentials in this order:
+For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets the United States endpoint at `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. When the CLI selects either hosted target automatically, it resolves credentials in this order:
 
 1. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
 2. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your environment.
@@ -1111,7 +1111,13 @@ For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targ
 
 Learning commands also send `X-Mastra-Organization-Id`, resolved from an explicit `--header`, `MASTRA_ORGANIZATION_ID` in your environment, or `.mastra-project.json`, in that order.
 
-Use `--url` and `--header` when you need to override the default hosted observability target or credentials.
+European Union observability data is stored at `https://observability.eu.mastra.ai`. Pass that trusted host with `--url`; it uses the same Platform credential resolution as the default United States endpoint:
+
+```bash
+mastra api --url https://observability.eu.mastra.ai trace list
+```
+
+Use `--url` and `--header` when you need to override another target or its credentials.
 
 ### Flags
 
@@ -1527,7 +1533,7 @@ mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","p
 
 #### Observability with `curl`
 
-You can call the hosted observability API directly with your platform access token and project ID:
+You can call the hosted observability API directly with your platform access token and project ID. The examples below use the United States host. Substitute `https://observability.eu.mastra.ai` for a European Union environment. The [hosted feedback query API](https://mastra.ai/docs/mastra-platform/api) documents feedback endpoints that don't have CLI commands:
 
 ```bash
 curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \

package/.docs/reference/client-js/observability.md

@@ -92,7 +92,7 @@ const scores = await mastraClient.listScoresBySpan({
 
 ## Feedback
 
-Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
+Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform feedback query API. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
 
 ### Creating feedback
 

package/.docs/reference/observability/feedback.md

@@ -54,6 +54,8 @@ await mastra.observability.addFeedback?.({
 
 **feedback** (`FeedbackInput`): Feedback payload to add.
 
+Without `correlationContext`, the method looks up `traceId` in configured observability storage. If the trace or requested span isn't found, Mastra logs a warning and drops the feedback event. Configure `MastraStorageExporter` when adding feedback by ID after execution, including when `MastraPlatformExporter` handles remote export.
+
 ### `createFeedback(args)`
 
 Creates one feedback record through the observability storage domain. Storage-level calls write directly to the store, so include `timestamp`.
@@ -375,6 +377,8 @@ Use `FeedbackFilter` in `listFeedback()` and OLAP query `filters`.
 
 ## HTTP routes
 
+These routes belong to a Mastra runtime and use its configured observability storage. They're separate from the [unversioned Mastra Platform feedback query API](https://mastra.ai/docs/mastra-platform/api), which doesn't provide a feedback creation route.
+
 | Method | Path                                      | Purpose                      | Permission           |
 | ------ | ----------------------------------------- | ---------------------------- | -------------------- |
 | `GET`  | `/api/observability/feedback`             | List feedback records        | None derived         |

package/.docs/reference/workspace/local-sandbox.md

@@ -54,6 +54,8 @@ const response = await agent.generate('Run npm install')
 
 **nativeSandbox** (`NativeSandboxConfig`): Configuration for native sandboxing (see NativeSandboxConfig below).
 
+`start()` reports `{ outcome: 'created' }` when the working directory didn't exist yet and `{ outcome: 'connected' }` when it reattaches to an existing directory. See [`start()`](https://mastra.ai/reference/workspace/sandbox) for the shared contract.
+
 ## `NativeSandboxConfig`
 
 Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'` or `'bwrap'`).

package/.docs/reference/workspace/platform-sandbox.md

@@ -118,6 +118,8 @@ const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
 
 When `sandboxId` is set, `environmentId` isn't required because the sandbox already exists.
 
+`start()` reports `{ outcome: 'connected' }` on reattach and `{ outcome: 'created' }` on a fresh provision (including a checkpoint-recovered boot, which is a new VM even when its filesystem was restored). See [`start()`](https://mastra.ai/reference/workspace/sandbox) for the shared contract.
+
 ### Checkpoint recovery
 
 The constructor `id` (explicit or auto-generated) is sent to the platform on `POST /sandbox` as an advisory recovery key:
@@ -226,7 +228,7 @@ console.log(result.exitCode)
 
 ## Methods
 
-**start** (`() => Promise<void>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
+**start** (`() => Promise<SandboxStartResult>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
 
 **destroy** (`() => Promise<void>`): Tear down the remote sandbox and clear the cached exec lease. A subsequent start() provisions a fresh sandbox (or restores from checkpoint when a stable id is set).
 

package/.docs/reference/workspace/sandbox.md

@@ -17,10 +17,78 @@ The `WorkspaceSandbox` interface defines how workspaces execute commands and man
 Starts the sandbox and is called automatically by `workspace.init()` or the first `executeCommand()` call.
 
 ```typescript
-await sandbox.start()
+const result = await sandbox.start()
+// { outcome: 'created' } — a fresh VM was created
+// { outcome: 'connected' } — reconnected to an existing VM
+// undefined — the provider does not report
 ```
 
-This method prepares the sandbox for command execution.
+**Returns:** `void | Promise<SandboxStartResult | void>`
+
+A sandbox constructed with a known `id` resolves that id on `start()`: reconnect or resume the sandbox if it exists, create it if not (get-or-create). Providers that support this report a `SandboxStartResult`:
+
+**outcome** (`'created' | 'connected'`): 'created' when a brand-new sandbox VM (or working directory) was provisioned; 'connected' when the call reconnected to or resumed an existing one.
+
+Providers that predate the contract return `void`, which the base class treats as unknown.
+
+Provider implementations plug into the start lifecycle at one of three rungs; the best available wins, and the base class always owns coalescing, status management, the `onStart` hook, and mount processing:
+
+1. **Acquisition primitives**: implement protected `find()` (side-effect-free lookup by logical id, returning a provider-native handle or `undefined`), `connect(handle)` (wake/resume/adopt), and `create()` (provision fresh) without overriding `start()`. The base orchestrates find → connect → `{ outcome: 'connected' }`, else create → `{ outcome: 'created' }`. The outcome is derived structurally from which branch ran. Used by `E2BSandbox`, `DaytonaSandbox`, and `LocalSandbox`.
+2. **`start()` override returning `SandboxStartResult`**: for providers whose API is a fused get-or-create where decomposition would add round-trips (`PlatformSandbox`, `RailwaySandbox`).
+3. **`start()` override returning `void`**: legacy providers, where the outcome is unknown.
+
+Concurrent `start()` calls on one instance coalesce onto a single in-flight attempt, and joined callers share that attempt's result (all observe `outcome: 'created'` when the shared attempt created the VM). The in-flight slot is cleared when the attempt settles, so a failed start can be retried. While the sandbox is already `running`, `start()` resolves `{ outcome: 'connected' }` without re-invoking the provider.
+
+The result is also forwarded to the `onStart` lifecycle hook as `{ sandbox, outcome }`.
+
+### `onStart` (constructor option)
+
+`onStart` runs inside the start lifecycle, after the sandbox reaches `running` status and before pending mounts are processed. It fires on every start regardless of trigger, whether an explicit call, a lazy `ensureRunning()` from a command, or a revival after the provider replaced the VM. That makes it the seam for once-per-VM setup: branch on `outcome` and probe or run whatever the environment needs.
+
+```typescript
+new E2BSandbox({
+  id: sessionId,
+  onStart: async ({ sandbox, outcome }) => {
+    if (outcome === 'created') {
+      // Fresh VM: run the full setup.
+      await runSetup(sandbox)
+      return
+    }
+    // Reconnected: probe, and self-heal if setup never completed.
+    const probe = await sandbox.executeCommand('test -d ~/repo/.git')
+    if (probe.exitCode !== 0) await runSetup(sandbox)
+  },
+})
+```
+
+Semantics:
+
+- A thrown error is fatal: `start()` rejects with the hook's error and the sandbox is marked `error`, so a caller never observes a running sandbox whose setup hook failed. Nothing is latched, and the next `start()` (including the one triggered by the next lazy command) retries the hook. `onStop` and `onDestroy` remain non-fatal observers, because teardown proceeds best-effort.
+- `outcome` distinguishes the branches: `'created'` means this start provisioned a fresh VM (run setup), `'connected'` means it reconnected or resumed (setup normally already ran, so probe when the hook must self-heal a crash between create and setup-complete). `undefined` means the provider doesn't report.
+- Keep setup work idempotent. A hook re-runs whenever a probe decides it should, and a checkpoint-recovered fresh VM reports `outcome: 'created'`.
+- The sandbox status flips to `running` before the hook executes (the hook runs commands through the sandbox's own command path), so commands issued concurrently through `ensureRunning()` can interleave with it. Callers awaiting the original `start()` always observe a sandbox whose hook finished.
+- The hook runs before pending filesystem mounts are processed, so it can't rely on mounted paths.
+
+### `setOnStart(update)`
+
+Attaches a start hook after construction, for runtimes that receive a sandbox they didn't build. Without it, every host that constructs a sandbox has to accept a hook and pass it to the provider constructor, and a host that forgets leaves setup unrun with no error.
+
+The updater receives the hook currently installed, either the `onStart` constructor option or one a previous call left behind, and returns the hook to install. Composing this way means a caller never discards a hook it didn't know about:
+
+```typescript
+sandbox.setOnStart?.(previous => async args => {
+  await previous?.(args) // whatever prepared the sandbox runs first
+  await mySetup(args)
+})
+```
+
+Semantics:
+
+- Errors stay fatal, exactly as with the constructor option. Because each hook awaits the next, a throw stops the ones sequenced after it.
+- The caller chooses the order. Await `previous` first when your hook needs the workspace it prepares, or last when yours is the one preparing it.
+- Ignoring `previous` replaces the installed hook. That's supported, and it's how a caller takes over setup a runtime installed.
+- Each call wraps the current hook, so attach once per sandbox instance. Attaching on a path that runs per request stacks duplicate work on every start.
+- Only starts that begin after the call see the new hook.
 
 ### `stop()`
 

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.19-alpha.18
+
+### Patch Changes
+
+- Updated dependencies [[`4ff3ee2`](https://github.com/mastra-ai/mastra/commit/4ff3ee2bff7ed07528b4817f8f49639031c72a4d), [`c24754c`](https://github.com/mastra-ai/mastra/commit/c24754c1fb6fe144e5051e536e98c8a18b0214ac), [`45dd6ee`](https://github.com/mastra-ai/mastra/commit/45dd6ee089bd7df0d0c98a10098e483fd388e04a), [`32d3583`](https://github.com/mastra-ai/mastra/commit/32d358332cb8ac2306b83b73cf3536e74dbd435e), [`aca2869`](https://github.com/mastra-ai/mastra/commit/aca2869b2031982f3c4a2f52525c9be7cf123ef8)]:
+  - @mastra/core@1.62.0-alpha.11
+
 ## 1.2.19-alpha.16
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.19-alpha.16",
+  "version": "1.2.19-alpha.18",
   "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/core": "1.62.0-alpha.10",
-    "@mastra/mcp": "^1.17.2-alpha.2"
+    "@mastra/mcp": "^1.17.2-alpha.2",
+    "@mastra/core": "1.62.0-alpha.11"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/types-builder": "0.0.100",
     "@internal/lint": "0.0.125",
-    "@mastra/core": "1.62.0-alpha.10"
+    "@internal/types-builder": "0.0.100",
+    "@mastra/core": "1.62.0-alpha.11"
   },
   "homepage": "https://mastra.ai",
   "repository": {