@mastra/mcp-docs-server 1.2.19-alpha.4 → 1.2.19

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

@@ -10,6 +10,8 @@ The `WorkspaceSandbox` interface defines how workspaces execute commands and man
 
 **processes** (`SandboxProcessManager`): Background process manager. If not implemented, process management tools won't be available. See SandboxProcessManager reference.
 
+**computer** (`SandboxComputer`): Computer-use (desktop) capability. If not implemented, computer tools won't be available. See Computer capability.
+
 ## Methods
 
 ### `start()`
@@ -17,10 +19,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
+```
+
+**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)
+  },
+})
 ```
 
-This method prepares the sandbox for command execution.
+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()`
 
@@ -69,12 +139,40 @@ const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
 
 **options.cwd** (`string`): Working directory for the command
 
-**options.env** (`Record<string, string>`): Additional environment variables
+**options.env** (`Record<string, string>`): Additional environment variables for this command. These take precedence over the sandbox environment for this command execution only.
 
 **options.onStdout** (`(data: string) => void`): Callback for stdout streaming
 
 **options.onStderr** (`(data: string) => void`): Callback for stderr streaming
 
+### `setEnv(update)`
+
+Update the sandbox's runtime environment. These values are merged into every command the sandbox runs, including `executeCommand()` and `processes.spawn()`, so credentials installed or rotated after the sandbox was created reach every subsequent command. Optional, so check for support or use optional chaining.
+
+```typescript
+sandbox.setEnv?.(env => ({ ...env, GH_TOKEN: token }))
+```
+
+The updater receives a copy of the current environment and returns the replacement, so a single call can set, unset, or batch-update variables. Removing a key removes it from the sandbox's runtime environment only, so values the provider supplies on its own still apply. Seed the initial values with the `env` constructor option.
+
+The runtime environment applies to commands executed through the sandbox rather than to the VM's own environment, so it's never written into the VM and survives provider pause and resume. When a command runs, provider defaults are applied first, the sandbox's runtime environment overrides them, and the per-call `env` option on `executeCommand()` wins over both.
+
+**Parameters:**
+
+**update** (`(env: Record<string, string | undefined>) => Record<string, string | undefined>`): Receives a copy of the sandbox's current runtime environment and returns the replacement.
+
+**Returns:** `void`
+
+### `getEnv()`
+
+Returns a copy of the sandbox's current runtime environment. Mutating the returned object doesn't change the sandbox, so use `setEnv()` for updates.
+
+```typescript
+const token = sandbox.getEnv().GH_TOKEN
+```
+
+**Returns:** `Record<string, string | undefined>`
+
 ### `getInfo()`
 
 Get sandbox status and resource information.
@@ -99,6 +197,48 @@ const instructions = sandbox.getInstructions?.()
 
 **Returns:** `string`
 
+## Computer capability
+
+Sandboxes with a controllable desktop environment implement the optional `SandboxComputer` interface on the `computer` property. When present on a statically configured sandbox, the workspace tools factory registers the `mastra_workspace_computer_*` tools automatically. See [Computer-use tools](https://mastra.ai/docs/sandbox/overview).
+
+Coordinates are pixels from the top-left corner of the display. Providers normalize their SDK semantics (key names, scroll units) onto this surface and expose richer native APIs through their own accessors.
+
+**screenshot()** (`() => Promise<{ data: Uint8Array; mediaType: "image/png" }>`): Capture the current display as a PNG image.
+
+**leftClick(x, y)** (`(x: number, y: number) => Promise<void>`): Left-click at the given coordinates.
+
+**rightClick(x, y)** (`(x: number, y: number) => Promise<void>`): Right-click at the given coordinates.
+
+**doubleClick(x, y)** (`(x: number, y: number) => Promise<void>`): Double-click (left button) at the given coordinates.
+
+**moveMouse(x, y)** (`(x: number, y: number) => Promise<void>`): Move the cursor without clicking.
+
+**drag(from, to)** (`(from: ComputerPosition, to: ComputerPosition) => Promise<void>`): Press the left button at from, drag to to, and release.
+
+**scroll(direction, amount)** (`(direction: 'up' | 'down', amount: number) => Promise<void>`): Scroll the display by the given amount of ticks.
+
+**type(text)** (`(text: string) => Promise<void>`): Type text into the focused element.
+
+**press(key)** (`(key: string | string[]) => Promise<void>`): Press a key or key combination. A string presses one key (for example 'Enter'); an array presses a chord (for example \['ctrl', 's']).
+
+**getScreenSize()** (`() => Promise<{ width: number; height: number }>`): Get the display dimensions.
+
+**getCursorPosition()** (`() => Promise<{ x: number; y: number }>`): Get the current cursor position.
+
+**streamUrl()** (`() => Promise<string | null>`): Get a URL for a live view of the desktop, such as noVNC, or null when unavailable. Optional, not all providers expose a viewer.
+
+Use the `supportsComputer()` type guard to check for the capability:
+
+```typescript
+import { supportsComputer } from '@mastra/core/workspace'
+
+if (supportsComputer(sandbox)) {
+  const { data } = await sandbox.computer.screenshot()
+}
+```
+
+`DaytonaSandbox` and `E2BDesktopSandbox` implement this capability. See the [Daytona](https://mastra.ai/integrations/sandboxes/daytona) and [E2B Desktop](https://mastra.ai/integrations/sandboxes/e2b-desktop) integration pages.
+
 ## Related
 
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @mastra/mcp-docs-server
 
+## 1.2.19
+
+### Patch Changes
+
+- Updated dependencies [[`79f04a7`](https://github.com/mastra-ai/mastra/commit/79f04a7f6c6829da541139f638f2f1d267916e08), [`65edab1`](https://github.com/mastra-ai/mastra/commit/65edab1c233d17b8f163bad12fca410d0e6f16b1), [`1e47b75`](https://github.com/mastra-ai/mastra/commit/1e47b7520cab4cfaa8daed52f17e2e6d14ff7539), [`ab20a38`](https://github.com/mastra-ai/mastra/commit/ab20a38d0275f8d85e0f3833bd87ef487bcc609f), [`fd4d5fe`](https://github.com/mastra-ai/mastra/commit/fd4d5fe4f943699b85db5e74404f190d5a6b8c2a), [`ae8790c`](https://github.com/mastra-ai/mastra/commit/ae8790c4bfaa088d2ab279d1dcc06f326b9fd109), [`2c85f42`](https://github.com/mastra-ai/mastra/commit/2c85f428e04ccd63ea31a7ec80b5b327afdad555), [`11bbeb9`](https://github.com/mastra-ai/mastra/commit/11bbeb9b108ef2264e05acefc6dafb9cbb342921), [`48ef1f1`](https://github.com/mastra-ai/mastra/commit/48ef1f1d24eedafbb07f64e659a81b52b67b8bf6), [`aa3a85d`](https://github.com/mastra-ai/mastra/commit/aa3a85daf094c683bb97efdf4b6a696d2e474af5), [`d29d06f`](https://github.com/mastra-ai/mastra/commit/d29d06fe00bbd35b4571150ea04c59d2ed783c71), [`dfb7efa`](https://github.com/mastra-ai/mastra/commit/dfb7efa19e348b5a788be2d954362cbae12379d6), [`e6516df`](https://github.com/mastra-ai/mastra/commit/e6516dfcdae4f4ac0e7971d84359a81385ee602f), [`1a485f3`](https://github.com/mastra-ai/mastra/commit/1a485f3538f5ec64d58bd8b5e1e99de0c695c87b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`8661d7d`](https://github.com/mastra-ai/mastra/commit/8661d7d7179f0a024456aabdd8679bcecd09ac28), [`dbbfeb8`](https://github.com/mastra-ai/mastra/commit/dbbfeb85ec949dc9ebc0755e1ad262e4f5eba8db), [`575e343`](https://github.com/mastra-ai/mastra/commit/575e343900451021d96110916497d334af7bc252), [`0b2a3d1`](https://github.com/mastra-ai/mastra/commit/0b2a3d1783875c5b97b7b36ab3d03d7360e0dde7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`3cc9d00`](https://github.com/mastra-ai/mastra/commit/3cc9d00b2b4333e0377a5e9df5eff92c17ce7630), [`cacb839`](https://github.com/mastra-ai/mastra/commit/cacb8392d9e74189b56d857290b0615f98a2683d), [`57de7d6`](https://github.com/mastra-ai/mastra/commit/57de7d644ba7146edb4e9e6111ec4fa98c3a59e9), [`c8e4cea`](https://github.com/mastra-ai/mastra/commit/c8e4ceac9a390d78c8327dff3cdb2861dd71957f), [`ed01e9a`](https://github.com/mastra-ai/mastra/commit/ed01e9a807514a904374bf687a7b8f18750f6f78), [`b47b26e`](https://github.com/mastra-ai/mastra/commit/b47b26e6fe95cb8a3482be2c5e52de157fe59d0b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`733a537`](https://github.com/mastra-ai/mastra/commit/733a537489a858b5880b2e98809334fba895a221), [`e8e299c`](https://github.com/mastra-ai/mastra/commit/e8e299cc6abdfc39947e2fec25803493015d3882), [`edfc548`](https://github.com/mastra-ai/mastra/commit/edfc548886bc7bae17b681f8b6b41a47eb32bcd2), [`b05f486`](https://github.com/mastra-ai/mastra/commit/b05f48612984d5fe2447ea2d6cdd5c604d285b97), [`a8a4871`](https://github.com/mastra-ai/mastra/commit/a8a4871215f51da95c47129602157ce5372f634a), [`eb9ecaa`](https://github.com/mastra-ai/mastra/commit/eb9ecaa89c36e889749e3b825cfc507ce7f7980b), [`4ff3ee2`](https://github.com/mastra-ai/mastra/commit/4ff3ee2bff7ed07528b4817f8f49639031c72a4d), [`9207dfa`](https://github.com/mastra-ai/mastra/commit/9207dfab8062e5fc68b751684797ff86fe0b4e70), [`5165cdc`](https://github.com/mastra-ai/mastra/commit/5165cdcdcf50e144bb8113278535196cc9b07065), [`e737014`](https://github.com/mastra-ai/mastra/commit/e737014e0fc7035759762bb5b48baef1d6c0f6a7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`f591643`](https://github.com/mastra-ai/mastra/commit/f591643becdf0be9bddce6ba1748e64bc30d77f1), [`63796ba`](https://github.com/mastra-ai/mastra/commit/63796ba0fda60253be17535e68f6bbbf1e6ffa09), [`b1ad324`](https://github.com/mastra-ai/mastra/commit/b1ad324d657f3544b0701332aef7eb10e9a36258), [`61c566d`](https://github.com/mastra-ai/mastra/commit/61c566dd2f2cde2b23ed8f139924e530d4202214), [`c24754c`](https://github.com/mastra-ai/mastra/commit/c24754c1fb6fe144e5051e536e98c8a18b0214ac), [`12c61d2`](https://github.com/mastra-ai/mastra/commit/12c61d280c8cb208bc3c8dbcbe5dcc60cf9d1cd0), [`c46eb09`](https://github.com/mastra-ai/mastra/commit/c46eb09ce4987509af57a0ac582c61241a6dd2f1), [`9ee8120`](https://github.com/mastra-ai/mastra/commit/9ee8120ce17f76b9f617489e05a283353742690a), [`d975e92`](https://github.com/mastra-ai/mastra/commit/d975e924d4936f46c386bd3dee39c671720289f6), [`45dd6ee`](https://github.com/mastra-ai/mastra/commit/45dd6ee089bd7df0d0c98a10098e483fd388e04a), [`4e9a228`](https://github.com/mastra-ai/mastra/commit/4e9a2283d5fd6ed1b70a2751eb3dc2cbf82ada20), [`d6ce34a`](https://github.com/mastra-ai/mastra/commit/d6ce34aeceb06ddf3d595a1eed5cc74f481a46a1), [`f95f468`](https://github.com/mastra-ai/mastra/commit/f95f468cf1e7c2b924a13826494f98b8f2ccd581), [`30ed33e`](https://github.com/mastra-ai/mastra/commit/30ed33ee14084a26019aba15fceadda6d6ddefaf), [`04a815f`](https://github.com/mastra-ai/mastra/commit/04a815fc8971d29e97fcdcc5008a1eb472fc00ff), [`1cfa878`](https://github.com/mastra-ai/mastra/commit/1cfa8784d8da0dfaa0317e5048bc48b6084a5ea5), [`997cf5b`](https://github.com/mastra-ai/mastra/commit/997cf5bb3fc600b30aa20e048b663e48e0e1305a), [`9a12ef3`](https://github.com/mastra-ai/mastra/commit/9a12ef3fccf3f4186db0f294f4ee1f02cf4d8db2), [`32d3583`](https://github.com/mastra-ai/mastra/commit/32d358332cb8ac2306b83b73cf3536e74dbd435e), [`7960688`](https://github.com/mastra-ai/mastra/commit/7960688828e04eaf3106e34f7758fa580257eef6), [`91ad69d`](https://github.com/mastra-ai/mastra/commit/91ad69d64994c89199b0c55399e64ed91c61df2f), [`c4e2364`](https://github.com/mastra-ai/mastra/commit/c4e2364742bc37beebfa995db2d42efce6cfc7b8), [`8dc408d`](https://github.com/mastra-ai/mastra/commit/8dc408d34438f9e13297f792c11a5cfd6cf952e1), [`c92def1`](https://github.com/mastra-ai/mastra/commit/c92def10a13c822972c96f0a4ca6ffc1f4258aed), [`63041eb`](https://github.com/mastra-ai/mastra/commit/63041eb4c50b520a0a80e03d4cd6ea99f67715a0), [`c118318`](https://github.com/mastra-ai/mastra/commit/c1183181c9804303db4b511c2e2648f8b714712b), [`c5eaec5`](https://github.com/mastra-ai/mastra/commit/c5eaec5a860d80d0e3805e67db0414b87ac8cbed), [`fc07c64`](https://github.com/mastra-ai/mastra/commit/fc07c6465043e08e99193a6751a01c56ffc2e7a1), [`cced745`](https://github.com/mastra-ai/mastra/commit/cced745a056ec2225c5bc702e32d848847aa8b65), [`542dee2`](https://github.com/mastra-ai/mastra/commit/542dee254167f974ff8cbbbfc0ce10f9a2616a7b), [`3c19dce`](https://github.com/mastra-ai/mastra/commit/3c19dcef8e73062a80627a4927eae3ec11145afd), [`aca2869`](https://github.com/mastra-ai/mastra/commit/aca2869b2031982f3c4a2f52525c9be7cf123ef8), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`e6f8450`](https://github.com/mastra-ai/mastra/commit/e6f845074d478527026b18d85031b23353e1d0a4), [`895e9df`](https://github.com/mastra-ai/mastra/commit/895e9dfc17d6f34299eca64e317ded9e5f5e5ef8), [`e66b2ba`](https://github.com/mastra-ai/mastra/commit/e66b2ba100db63eaeab6e21e1ea34b113f2ec781), [`3e8727e`](https://github.com/mastra-ai/mastra/commit/3e8727e11ec1a5d733acedb5c872896394be18c1)]:
+  - @mastra/core@1.62.0
+  - @mastra/mcp@1.17.2
+
+## 1.2.19-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`48ef1f1`](https://github.com/mastra-ai/mastra/commit/48ef1f1d24eedafbb07f64e659a81b52b67b8bf6), [`63796ba`](https://github.com/mastra-ai/mastra/commit/63796ba0fda60253be17535e68f6bbbf1e6ffa09), [`3c19dce`](https://github.com/mastra-ai/mastra/commit/3c19dcef8e73062a80627a4927eae3ec11145afd)]:
+  - @mastra/core@1.62.0-alpha.12
+
+## 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
+
+- Updated dependencies [[`b05f486`](https://github.com/mastra-ai/mastra/commit/b05f48612984d5fe2447ea2d6cdd5c604d285b97), [`7960688`](https://github.com/mastra-ai/mastra/commit/7960688828e04eaf3106e34f7758fa580257eef6)]:
+  - @mastra/core@1.62.0-alpha.10
+
+## 1.2.19-alpha.15
+
+### Patch Changes
+
+- Updated dependencies [[`eb9ecaa`](https://github.com/mastra-ai/mastra/commit/eb9ecaa89c36e889749e3b825cfc507ce7f7980b), [`3e8727e`](https://github.com/mastra-ai/mastra/commit/3e8727e11ec1a5d733acedb5c872896394be18c1)]:
+  - @mastra/core@1.62.0-alpha.9
+
+## 1.2.19-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`aa3a85d`](https://github.com/mastra-ai/mastra/commit/aa3a85daf094c683bb97efdf4b6a696d2e474af5), [`d29d06f`](https://github.com/mastra-ai/mastra/commit/d29d06fe00bbd35b4571150ea04c59d2ed783c71), [`e6516df`](https://github.com/mastra-ai/mastra/commit/e6516dfcdae4f4ac0e7971d84359a81385ee602f), [`0b2a3d1`](https://github.com/mastra-ai/mastra/commit/0b2a3d1783875c5b97b7b36ab3d03d7360e0dde7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`57de7d6`](https://github.com/mastra-ai/mastra/commit/57de7d644ba7146edb4e9e6111ec4fa98c3a59e9), [`e8e299c`](https://github.com/mastra-ai/mastra/commit/e8e299cc6abdfc39947e2fec25803493015d3882), [`edfc548`](https://github.com/mastra-ai/mastra/commit/edfc548886bc7bae17b681f8b6b41a47eb32bcd2), [`a8a4871`](https://github.com/mastra-ai/mastra/commit/a8a4871215f51da95c47129602157ce5372f634a), [`5165cdc`](https://github.com/mastra-ai/mastra/commit/5165cdcdcf50e144bb8113278535196cc9b07065), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`9ee8120`](https://github.com/mastra-ai/mastra/commit/9ee8120ce17f76b9f617489e05a283353742690a), [`d975e92`](https://github.com/mastra-ai/mastra/commit/d975e924d4936f46c386bd3dee39c671720289f6), [`1cfa878`](https://github.com/mastra-ai/mastra/commit/1cfa8784d8da0dfaa0317e5048bc48b6084a5ea5), [`c118318`](https://github.com/mastra-ai/mastra/commit/c1183181c9804303db4b511c2e2648f8b714712b), [`fc07c64`](https://github.com/mastra-ai/mastra/commit/fc07c6465043e08e99193a6751a01c56ffc2e7a1), [`542dee2`](https://github.com/mastra-ai/mastra/commit/542dee254167f974ff8cbbbfc0ce10f9a2616a7b), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`895e9df`](https://github.com/mastra-ai/mastra/commit/895e9dfc17d6f34299eca64e317ded9e5f5e5ef8)]:
+  - @mastra/core@1.62.0-alpha.8
+
+## 1.2.19-alpha.13
+
+### Patch Changes
+
+- Updated dependencies [[`ae8790c`](https://github.com/mastra-ai/mastra/commit/ae8790c4bfaa088d2ab279d1dcc06f326b9fd109), [`dfb7efa`](https://github.com/mastra-ai/mastra/commit/dfb7efa19e348b5a788be2d954362cbae12379d6), [`04a815f`](https://github.com/mastra-ai/mastra/commit/04a815fc8971d29e97fcdcc5008a1eb472fc00ff), [`cced745`](https://github.com/mastra-ai/mastra/commit/cced745a056ec2225c5bc702e32d848847aa8b65)]:
+  - @mastra/core@1.62.0-alpha.7
+  - @mastra/mcp@1.17.2-alpha.2
+
+## 1.2.19-alpha.11
+
+### Patch Changes
+
+- Updated dependencies [[`c8e4cea`](https://github.com/mastra-ai/mastra/commit/c8e4ceac9a390d78c8327dff3cdb2861dd71957f), [`ed01e9a`](https://github.com/mastra-ai/mastra/commit/ed01e9a807514a904374bf687a7b8f18750f6f78), [`4e9a228`](https://github.com/mastra-ai/mastra/commit/4e9a2283d5fd6ed1b70a2751eb3dc2cbf82ada20), [`997cf5b`](https://github.com/mastra-ai/mastra/commit/997cf5bb3fc600b30aa20e048b663e48e0e1305a), [`63041eb`](https://github.com/mastra-ai/mastra/commit/63041eb4c50b520a0a80e03d4cd6ea99f67715a0)]:
+  - @mastra/core@1.62.0-alpha.6
+  - @mastra/mcp@1.17.2-alpha.1
+
+## 1.2.19-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`65edab1`](https://github.com/mastra-ai/mastra/commit/65edab1c233d17b8f163bad12fca410d0e6f16b1), [`ab20a38`](https://github.com/mastra-ai/mastra/commit/ab20a38d0275f8d85e0f3833bd87ef487bcc609f), [`dbbfeb8`](https://github.com/mastra-ai/mastra/commit/dbbfeb85ec949dc9ebc0755e1ad262e4f5eba8db), [`3cc9d00`](https://github.com/mastra-ai/mastra/commit/3cc9d00b2b4333e0377a5e9df5eff92c17ce7630), [`733a537`](https://github.com/mastra-ai/mastra/commit/733a537489a858b5880b2e98809334fba895a221), [`9207dfa`](https://github.com/mastra-ai/mastra/commit/9207dfab8062e5fc68b751684797ff86fe0b4e70), [`12c61d2`](https://github.com/mastra-ai/mastra/commit/12c61d280c8cb208bc3c8dbcbe5dcc60cf9d1cd0), [`9a12ef3`](https://github.com/mastra-ai/mastra/commit/9a12ef3fccf3f4186db0f294f4ee1f02cf4d8db2)]:
+  - @mastra/core@1.62.0-alpha.5
+
+## 1.2.19-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`79f04a7`](https://github.com/mastra-ai/mastra/commit/79f04a7f6c6829da541139f638f2f1d267916e08), [`fd4d5fe`](https://github.com/mastra-ai/mastra/commit/fd4d5fe4f943699b85db5e74404f190d5a6b8c2a), [`f591643`](https://github.com/mastra-ai/mastra/commit/f591643becdf0be9bddce6ba1748e64bc30d77f1), [`b1ad324`](https://github.com/mastra-ai/mastra/commit/b1ad324d657f3544b0701332aef7eb10e9a36258), [`61c566d`](https://github.com/mastra-ai/mastra/commit/61c566dd2f2cde2b23ed8f139924e530d4202214)]:
+  - @mastra/core@1.62.0-alpha.4
+
+## 1.2.19-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`2c85f42`](https://github.com/mastra-ai/mastra/commit/2c85f428e04ccd63ea31a7ec80b5b327afdad555), [`11bbeb9`](https://github.com/mastra-ai/mastra/commit/11bbeb9b108ef2264e05acefc6dafb9cbb342921), [`1a485f3`](https://github.com/mastra-ai/mastra/commit/1a485f3538f5ec64d58bd8b5e1e99de0c695c87b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`8661d7d`](https://github.com/mastra-ai/mastra/commit/8661d7d7179f0a024456aabdd8679bcecd09ac28), [`575e343`](https://github.com/mastra-ai/mastra/commit/575e343900451021d96110916497d334af7bc252), [`cacb839`](https://github.com/mastra-ai/mastra/commit/cacb8392d9e74189b56d857290b0615f98a2683d), [`b47b26e`](https://github.com/mastra-ai/mastra/commit/b47b26e6fe95cb8a3482be2c5e52de157fe59d0b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`c46eb09`](https://github.com/mastra-ai/mastra/commit/c46eb09ce4987509af57a0ac582c61241a6dd2f1), [`30ed33e`](https://github.com/mastra-ai/mastra/commit/30ed33ee14084a26019aba15fceadda6d6ddefaf), [`91ad69d`](https://github.com/mastra-ai/mastra/commit/91ad69d64994c89199b0c55399e64ed91c61df2f), [`c4e2364`](https://github.com/mastra-ai/mastra/commit/c4e2364742bc37beebfa995db2d42efce6cfc7b8), [`8dc408d`](https://github.com/mastra-ai/mastra/commit/8dc408d34438f9e13297f792c11a5cfd6cf952e1), [`c92def1`](https://github.com/mastra-ai/mastra/commit/c92def10a13c822972c96f0a4ca6ffc1f4258aed), [`c5eaec5`](https://github.com/mastra-ai/mastra/commit/c5eaec5a860d80d0e3805e67db0414b87ac8cbed), [`e66b2ba`](https://github.com/mastra-ai/mastra/commit/e66b2ba100db63eaeab6e21e1ea34b113f2ec781)]:
+  - @mastra/core@1.62.0-alpha.3
+  - @mastra/mcp@1.17.2-alpha.0
+
 ## 1.2.19-alpha.4
 
 ### Patch Changes

package/package.json

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

package/.docs/docs/observability/metrics/querying.md

@@ -1,314 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Querying metrics
-
-Mastra exposes the same five OLAP queries (`getMetricAggregate`, `getMetricBreakdown`, `getMetricTimeSeries`, `getMetricPercentiles`, and discovery helpers) through three surfaces: an in-process store accessor and the runtime HTTP API, plus the `mastra api metric` CLI. All three accept the same Zod-validated input shapes, so you can move from a one-off CLI investigation to a programmatic dashboard tool without re-learning the API.
-
-**For AI agents:** Run `npx mastra api metric aggregate '{"name":"mastra_agent_duration_ms","aggregation":"avg"}'` to query average agent latency directly instead of writing a temporary script. Querying local metrics requires a running Mastra server with an OLAP-capable observability store; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api metric aggregate --schema` before constructing a different query. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
-
-## When to use this
-
-- Build a custom dashboard or KPI tile alongside Studio.
-- Power a scheduled alert that fires when token cost or latency crosses a threshold.
-- Give an agent a tool that reads its own performance metrics and explains them in chat.
-- Run one-off investigations from a terminal with `mastra api metric ...`.
-
-For setup of the observability store itself, see the [Metrics overview](https://mastra.ai/docs/observability/metrics/overview). For the list of metric names you can query, see the [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics).
-
-> **Note:** Metric queries are served by the observability domain, which requires an OLAP-capable store (DuckDB locally, ClickHouse in production). See [Metrics overview](https://mastra.ai/docs/observability/metrics/overview) for setup. If the observability store isn't configured, `getStore('observability')` returns `null`.
-
-## Surfaces
-
-### In-process
-
-Inside a tool, server route, or workflow step, get the observability store from the Mastra storage:
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-export const agentLatencyTool = createTool({
-  id: 'agentLatency',
-  description: 'Average agent latency over the last hour.',
-  inputSchema: z.object({}),
-  execute: async (_input, context) => {
-    const observability = await context.mastra!.getStorage()!.getStore('observability')
-    if (!observability) {
-      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
-    }
-
-    const result = await observability.getMetricAggregate({
-      name: ['mastra_agent_duration_ms'],
-      aggregation: 'avg',
-      filters: {
-        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
-      },
-    })
-
-    return { averageMs: result.value }
-  },
-})
-```
-
-`getStore('observability')` returns `null` when the configured backend doesn't support OLAP queries.
-
-### HTTP
-
-The `mastra dev` server (and any deployed Mastra runtime) exposes the same queries under `/api/observability/metrics/*`. Aggregate, breakdown, time series, and percentile endpoints take a JSON body with `POST`. Discovery endpoints use `GET` with query parameters.
-
-```bash
-curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
-  -H "content-type: application/json" \
-  -d '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}'
-```
-
-Available routes:
-
-- `POST /api/observability/metrics/aggregate`
-- `POST /api/observability/metrics/breakdown`
-- `POST /api/observability/metrics/timeseries`
-- `POST /api/observability/metrics/percentiles`
-- `GET /api/observability/metrics` (raw rows, paginated)
-- `GET /api/observability/discovery/metric-names`
-- `GET /api/observability/discovery/metric-label-keys`
-- `GET /api/observability/discovery/metric-label-values`
-
-The `@mastra/client-js` SDK wraps the same routes as `mastraClient.getMetricAggregate(...)`, `getMetricBreakdown(...)`, and so on.
-
-### CLI
-
-`mastra api metric ...` calls the same endpoints with a single JSON argument, so an agent or shell script can fetch metrics without writing any code:
-
-```bash
-mastra api metric aggregate \
-  '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}' \
-  --url http://localhost:4111
-```
-
-By default the CLI targets hosted Mastra observability (`https://observability.mastra.ai`). Pass `--url http://localhost:4111` to query a local `mastra dev` server. See [`mastra api metric aggregate`](https://mastra.ai/reference/cli/mastra) and the surrounding entries for the full command list.
-
-## Queries
-
-### `getMetricAggregate`
-
-Returns a single scalar, the building block for KPI cards.
-
-Inputs:
-
-- `name`: Array of one or more metric names.
-- `aggregation`: One of `'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'`.
-- `filters`: Optional [filter object](#filtering).
-- `comparePeriod`: Optional `'previous_period' | 'previous_day' | 'previous_week'` for period-over-period comparison.
-
-Response:
-
-- `value`, `previousValue`, `changePercent`.
-- `estimatedCost`, `costUnit`, `previousEstimatedCost`, `costChangePercent` for token metrics.
-
-```typescript
-const observability = await mastra.getStorage()!.getStore('observability')
-
-const cost = await observability!.getMetricAggregate({
-  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
-  aggregation: 'sum',
-  comparePeriod: 'previous_day',
-})
-
-console.log(cost.value, cost.estimatedCost, cost.costUnit, cost.changePercent)
-```
-
-### `getMetricBreakdown`
-
-Groups rows by one or more dimensions and aggregates each group, the building block for top-N tables (e.g. "tokens by agent").
-
-Inputs:
-
-- `name`: Array of metric names.
-- `groupBy`: Array of fields to group by (for example `['entityName']`).
-- `aggregation`: Same enum as above.
-- `limit`: Server-side top-K cap. Required for high-cardinality `groupBy`.
-- `orderDirection`: `'ASC' | 'DESC'` (defaults to `DESC`).
-- `filters`: Optional.
-
-Response: `groups[]`, each with `dimensions` (record of group keys to values), `value`, and `estimatedCost`.
-
-```typescript
-const byAgent = await observability!.getMetricBreakdown({
-  name: ['mastra_model_total_input_tokens'],
-  groupBy: ['entityName'],
-  aggregation: 'sum',
-  limit: 10,
-  orderDirection: 'DESC',
-})
-```
-
-### `getMetricTimeSeries`
-
-Buckets values by a fixed interval, the building block for line and bar charts.
-
-Inputs:
-
-- `name`: Array of metric names.
-- `interval`: One of `'1m' | '5m' | '15m' | '1h' | '1d'`.
-- `aggregation`: Same enum.
-- `groupBy`: Optional. When omitted, multiple metric names are summed into one series. Use one call per metric to keep them separate.
-- `filters`: Optional.
-
-Response: `series[]`, each with `name`, `costUnit`, and `points[]` of `{ timestamp, value, estimatedCost }`.
-
-```typescript
-const inputTokens = await observability!.getMetricTimeSeries({
-  name: ['mastra_model_total_input_tokens'],
-  aggregation: 'sum',
-  interval: '1h',
-  filters: {
-    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
-  },
-})
-```
-
-### `getMetricPercentiles`
-
-Returns percentile values bucketed by time, the building block for latency charts.
-
-Inputs:
-
-- `name`: Single metric name (string, not array).
-- `percentiles`: Array of numbers between `0` and `1`, for example `[0.5, 0.95, 0.99]`.
-- `interval`: Same enum as `getMetricTimeSeries`.
-- `filters`: Optional.
-
-Response: `series[]`, each with `percentile` and `points[]` of `{ timestamp, value }`.
-
-```typescript
-const latency = await observability!.getMetricPercentiles({
-  name: 'mastra_agent_duration_ms',
-  percentiles: [0.5, 0.95],
-  interval: '1h',
-})
-```
-
-### Discovery
-
-Use these endpoints to populate dropdowns or to give an agent the menu of values it can filter by. All discovery routes are `GET` and live under `/api/observability/discovery/`.
-
-**Metric-specific** (also exposed as `mastra api metric` subcommands):
-
-| Method                 | Args                                        | Path suffix           | CLI                              |
-| ---------------------- | ------------------------------------------- | --------------------- | -------------------------------- |
-| `getMetricNames`       | `{ prefix?, limit? }`                       | `metric-names`        | `mastra api metric names`        |
-| `getMetricLabelKeys`   | `{ metricName }`                            | `metric-label-keys`   | `mastra api metric label-keys`   |
-| `getMetricLabelValues` | `{ metricName, labelKey, prefix?, limit? }` | `metric-label-values` | `mastra api metric label-values` |
-
-**Shared with traces and logs** (HTTP-only, no dedicated CLI subcommand):
-
-| Method            | Args              | Path suffix     |
-| ----------------- | ----------------- | --------------- |
-| `getEntityTypes`  | `{}`              | `entity-types`  |
-| `getEntityNames`  | `{ entityType? }` | `entity-names`  |
-| `getServiceNames` | `{}`              | `service-names` |
-| `getEnvironments` | `{}`              | `environments`  |
-| `getTags`         | `{ entityType? }` | `tags`          |
-
-## Filtering
-
-Every query accepts the same `filters` object. The most useful fields:
-
-- `name`: Restrict to specific metric names. (Top-level `name` already does this for aggregate/breakdown/timeseries. Use `filters.name` when you want to mix multiple metrics under a single query.)
-- `timestamp`: `{ start, end, startExclusive, endExclusive }`. Both bounds are optional. Omit `end` for "until now".
-- `provider`, `model`, `costUnit`: For token and cost metrics.
-- `labels`: Exact key-value match on metric labels, for example `{ status: 'error' }` for duration metrics.
-- Correlation fields: `entityType`, `entityName`, `parentEntityName`, `rootEntityName`, `userId`, `organizationId`, `resourceId`, `runId`, `sessionId`, `threadId`, `requestId`, `executionSource`, `environment`, `serviceName`, `experimentId`, `tags`.
-
-The same `filters` shape works across all three surfaces:
-
-```typescript
-// In-process
-await observability!.getMetricAggregate({
-  name: ['mastra_tool_duration_ms'],
-  aggregation: 'avg',
-  filters: { entityName: 'weatherTool', labels: { status: 'error' } },
-})
-```
-
-```bash
-# CLI
-mastra api metric aggregate \
-  '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}' \
-  --url http://localhost:4111
-```
-
-```bash
-# HTTP
-curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
-  -H "content-type: application/json" \
-  -d '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}'
-```
-
-### Always provide a time range
-
-`filters.timestamp` is optional, but you should treat it as required for any query that runs against a production store. Observability tables are typically partitioned (or chunked, for TimescaleDB) by event time. When you supply `timestamp.start` (and ideally `end`), the backend can prune to the partitions that overlap the range, usually one or two. Without a time range, the planner has to scan every partition, which can be hundreds of segments over a year of retention and is the most common cause of slow OLAP queries on Postgres-backed stores.
-
-A safe default for ad-hoc queries is the last 24 hours; alerts and dashboards should match their actual evaluation window:
-
-```typescript
-await observability!.getMetricAggregate({
-  name: ['mastra_agent_duration_ms'],
-  aggregation: 'p95',
-  filters: {
-    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
-  },
-})
-```
-
-This guidance applies to all backends (ClickHouse, Postgres v-next, DuckDB), but matters most for Postgres v-next where each missing time bound translates directly into one extra partition scan.
-
-## Example: build a custom KPI tile
-
-The following tool returns input-token volume and estimated cost for the last hour. An agent or a dashboard can call it as `structuredContent` without re-implementing the query.
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-export const tokenKpiTool = createTool({
-  id: 'tokenKpi',
-  description: 'Returns input-token volume and estimated cost for the last hour.',
-  inputSchema: z.object({}),
-  outputSchema: z.object({
-    inputTokens: z.number().nullable(),
-    estimatedCost: z.number().nullable(),
-    costUnit: z.string().nullable(),
-    changePercent: z.number().nullable(),
-  }),
-  execute: async (_input, context) => {
-    const observability = await context.mastra!.getStorage()!.getStore('observability')
-    if (!observability) {
-      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
-    }
-
-    const result = await observability.getMetricAggregate({
-      name: ['mastra_model_total_input_tokens'],
-      aggregation: 'sum',
-      filters: {
-        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
-      },
-      comparePeriod: 'previous_period',
-    })
-
-    return {
-      inputTokens: result.value,
-      estimatedCost: result.estimatedCost ?? null,
-      costUnit: result.costUnit ?? null,
-      changePercent: result.changePercent ?? null,
-    }
-  },
-})
-```
-
-## Related
-
-- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
-- [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
-- [CLI: `mastra api metric ...`](https://mastra.ai/reference/cli/mastra)
-- [Studio observability](https://mastra.ai/docs/studio/observability)