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

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/sandbox/overview.md

@@ -73,6 +73,48 @@ Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled
 
 See the [sandbox tools reference](https://mastra.ai/reference/workspace/workspace-class) for all generated tools and the [tool configuration reference](https://mastra.ai/reference/workspace/workspace-class) for approvals, output limits, and hooks.
 
+### Computer-use tools
+
+Sandboxes that run a desktop environment can expose screenshot, mouse, and keyboard control. The workspace registers these tools when a statically configured sandbox supports the computer capability:
+
+| Tool                       | Does                                                                             |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `computer_screenshot`      | Captures the desktop as a PNG image and returns it to the model as native media. |
+| `computer_click`           | Presses and releases the left mouse button at pixel coordinates.                 |
+| `computer_double_click`    | Presses the left mouse button twice at pixel coordinates.                        |
+| `computer_right_click`     | Presses and releases the right mouse button at pixel coordinates.                |
+| `computer_move_mouse`      | Moves the cursor to pixel coordinates without pressing a button.                 |
+| `computer_drag`            | Presses, drags, and releases between two points.                                 |
+| `computer_type`            | Types text into the focused element.                                             |
+| `computer_press_key`       | Presses a key or key combination, such as `Enter` or `ctrl+s`.                   |
+| `computer_scroll`          | Scrolls up or down.                                                              |
+| `computer_get_screen_info` | Gets the screen dimensions and cursor position.                                  |
+| `computer_wait`            | Waits for the interface to settle.                                               |
+
+[`DaytonaSandbox`](https://mastra.ai/integrations/sandboxes/daytona) and [`E2BDesktopSandbox`](https://mastra.ai/integrations/sandboxes/e2b-desktop) support this capability. Other sandbox backends don't register the computer tools. Resolver-backed sandboxes don't register them because the workspace can't inspect the resolved sandbox's capabilities when it creates the tool list.
+
+Action tools take a screenshot after each action by default. Configure the screenshot behavior for each tool:
+
+```typescript
+import { Workspace, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+import { E2BDesktopSandbox } from '@mastra/e2b-desktop'
+
+const workspace = new Workspace({
+  sandbox: new E2BDesktopSandbox(),
+  tools: {
+    [WORKSPACE_TOOLS.COMPUTER.CLICK]: {
+      screenshotAfterAction: true,
+      screenshotDelayMs: 1000,
+    },
+    [WORKSPACE_TOOLS.COMPUTER.TYPE]: {
+      requireApproval: true,
+    },
+  },
+})
+```
+
+Computer tools accept the same per-tool `enabled` and `requireApproval` configuration as other workspace tools.
+
 Authored runtime functions, including tools and workflow steps, can get the live sandbox from their execution context. Use it to execute commands, install dependencies, process files, or spawn a long-running process.
 
 ```typescript
@@ -136,6 +178,7 @@ Use a remote or container sandbox when commands need a stronger boundary from th
 - [Daytona](https://mastra.ai/integrations/sandboxes/daytona)
 - [Docker](https://mastra.ai/integrations/sandboxes/docker)
 - [E2B](https://mastra.ai/integrations/sandboxes/e2b)
+- [E2B Desktop](https://mastra.ai/integrations/sandboxes/e2b-desktop)
 - [Mastra](https://mastra.ai/reference/workspace/platform-sandbox)
 - [Modal](https://mastra.ai/integrations/sandboxes/modal)
 - [Railway](https://mastra.ai/integrations/sandboxes/railway)

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,52 @@ 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()`.
+
+### Computer use (desktop)
+
+`DaytonaSandbox` exposes the [computer capability](https://mastra.ai/docs/sandbox/overview): screenshot, mouse, and keyboard control of a desktop environment inside the sandbox. When the sandbox is used in a workspace, agents automatically get the `mastra_workspace_computer_*` tools.
+
+The desktop processes (Xvfb, xfce4, x11vnc, noVNC) are started lazily on the first computer operation:
+
+```typescript
+const sandbox = new DaytonaSandbox()
+await sandbox.start()
+
+await sandbox.computer.leftClick(100, 200)
+await sandbox.computer.type('hello')
+const { data } = await sandbox.computer.screenshot() // PNG bytes
+
+// Live desktop view via the noVNC preview link
+const url = await sandbox.computer.streamUrl()
+```
+
+Disable the capability, or manage the desktop processes yourself, with the `computerUse` option:
+
+```typescript
+// No computer capability, no computer tools
+new DaytonaSandbox({ computerUse: false })
+
+// Capability stays on, but you call sandbox.daytona.computerUse.start() yourself
+new DaytonaSandbox({ computerUse: { autoStart: false } })
+```
+
+For Daytona-specific desktop APIs (regions, compressed screenshots, screen recording, accessibility tree), use the [direct SDK access](#direct-sdk-access) escape hatch: `sandbox.daytona.computerUse`.
+
 ## Constructor parameters
 
 **id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
@@ -328,6 +374,10 @@ 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.
+
+**computerUse** (`boolean | { autoStart?: boolean; noVncPort?: number }`): Computer-use (desktop) capability configuration. Set to false to disable the capability. Set autoStart to false to manage the desktop processes yourself. noVncPort sets the noVNC viewer port used by computer.streamUrl(). (Default: `true`)
+
 ## Properties
 
 **id** (`string`): Sandbox instance identifier.
@@ -342,6 +392,8 @@ await sandbox.instance.updateNetworkSettings({
 
 **processes** (`DaytonaProcessManager`): Background process manager. See SandboxProcessManager reference.
 
+**computer** (`SandboxComputer | undefined`): Computer-use capability: screenshot, mouse, keyboard, and stream URL. Undefined when constructed with computerUse: false. See SandboxComputer reference.
+
 ## Background processes
 
 `DaytonaSandbox` includes a built-in process manager for spawning and managing background processes. Processes run in the Daytona cloud sandbox using session-based command execution.

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

@@ -0,0 +1,128 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# E2B Desktop
+
+Runs a full Linux desktop environment in an isolated [E2B](https://e2b.dev) cloud sandbox with screenshot, mouse, and keyboard control. `E2BDesktopSandbox` extends [`E2BSandbox`](https://mastra.ai/integrations/sandboxes/e2b), so everything the base provider supports (command execution, background processes, file upload, pause/resume reconnection) works against the same desktop machine. For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/e2b-desktop
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/e2b-desktop
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/e2b-desktop
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/e2b-desktop
+```
+
+Set your E2B API key with the `E2B_API_KEY` environment variable or the `apiKey` option.
+
+## Usage
+
+Add an `E2BDesktopSandbox` to a workspace and assign it to an agent. Because the sandbox supports the [computer capability](https://mastra.ai/docs/sandbox/overview), the workspace registers the `mastra_workspace_computer_*` tools alongside the shell and process tools:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { E2BDesktopSandbox } from '@mastra/e2b-desktop'
+
+const workspace = new Workspace({
+  sandbox: new E2BDesktopSandbox({
+    resolution: [1280, 720],
+  }),
+})
+
+const agent = new Agent({
+  id: 'desktop-agent',
+  name: 'Desktop Agent',
+  instructions: 'You can control a Linux desktop and run shell commands.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+
+const response = await agent.generate(
+  'Take a screenshot, then create /tmp/hello.txt with the text "hello" and cat it.',
+)
+```
+
+The agent can mix desktop actions (click, type, screenshot) with shell commands. Both surfaces operate on the same machine.
+
+### Direct desktop control
+
+Use the `computer` capability programmatically without an agent:
+
+```typescript
+const sandbox = new E2BDesktopSandbox()
+await sandbox.start()
+
+await sandbox.computer.leftClick(100, 200)
+await sandbox.computer.type('hello')
+const { data } = await sandbox.computer.screenshot() // PNG bytes
+
+const size = await sandbox.computer.getScreenSize()
+console.log(size) // { width: 1024, height: 768 }
+```
+
+### Live desktop view
+
+`streamUrl()` starts an authenticated noVNC stream inside the sandbox and returns a viewer URL. Open it in a browser to watch the agent work:
+
+```typescript
+const url = await sandbox.computer.streamUrl()
+// https://6080-<sandbox-id>.e2b.app/vnc.html?...&password=<auth-key>
+```
+
+### Desktop SDK escape hatch
+
+Desktop-only APIs such as `launch`, `open`, window helpers, and custom stream control are available on the underlying [`@e2b/desktop`](https://github.com/e2b-dev/desktop) sandbox:
+
+```typescript
+await sandbox.desktop.launch('xfce4-terminal')
+await sandbox.desktop.open('https://mastra.ai')
+```
+
+## Constructor parameters
+
+Accepts all [`E2BSandbox` options](https://mastra.ai/integrations/sandboxes/e2b) plus:
+
+**resolution** (`[number, number]`): Desktop display resolution as \[width, height] in pixels. Applies to newly created sandboxes only.
+
+**dpi** (`number`): Desktop display DPI. Applies to newly created sandboxes only.
+
+When no `template` is provided, the E2B-hosted `desktop` template is used instead of the base provider's mountable template.
+
+## Properties
+
+**computer** (`SandboxComputer`): Computer-use capability: screenshot, mouse, keyboard, and stream URL. See SandboxComputer reference.
+
+**desktop** (`Sandbox`): The underlying @e2b/desktop SDK sandbox for desktop-only APIs. Throws if the sandbox has not started.
+
+**name** (`string`): Provider name ('E2BDesktopSandbox')
+
+**provider** (`string`): Provider identifier ('e2b-desktop')
+
+## Cloud storage mounting
+
+The default `desktop` template has no FUSE tooling, so [cloud storage mounting](https://mastra.ai/integrations/sandboxes/e2b) requires a custom desktop template with `s3fs` or `gcsfuse` installed. Pass it with the `template` option.
+
+## Related
+
+- [Computer-use tools](https://mastra.ai/docs/sandbox/overview)
+- [`E2BSandbox` reference](https://mastra.ai/integrations/sandboxes/e2b)
+- [`WorkspaceSandbox` interface](https://mastra.ai/reference/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

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/integrations.md

@@ -40,6 +40,7 @@
 - [Daytona](https://mastra.ai/integrations/sandboxes/daytona)
 - [Docker](https://mastra.ai/integrations/sandboxes/docker)
 - [E2B](https://mastra.ai/integrations/sandboxes/e2b)
+- [E2B Desktop](https://mastra.ai/integrations/sandboxes/e2b-desktop)
 - [Mastra](https://mastra.ai/reference/workspace/platform-sandbox)
 - [Modal](https://mastra.ai/integrations/sandboxes/modal)
 - [Railway](https://mastra.ai/integrations/sandboxes/railway)

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