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

package/.docs/reference/server/elysia-adapter.md

@@ -0,0 +1,184 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Elysia adapter
+
+The `@mastra/elysia` package provides a server adapter for running Mastra with [Elysia](https://elysiajs.com).
+
+> **Note:** For general adapter concepts, constructor options, and initialization flow, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the Elysia adapter and Elysia framework:
+
+**npm**:
+
+```bash
+npm install @mastra/elysia@latest elysia
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/elysia@latest elysia
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/elysia@latest elysia
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/elysia@latest elysia
+```
+
+## Usage example
+
+```typescript
+import { Elysia } from 'elysia'
+import { MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.listen(3000)
+
+console.log('Server running on http://localhost:3000')
+```
+
+## Constructor parameters
+
+**app** (`Elysia`): Elysia app instance
+
+**mastra** (`Mastra`): Mastra instance
+
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+
+**openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
+
+**bodyLimitOptions** (`BodyLimitOptions`): Request body size limits
+
+**streamOptions** (`StreamOptions`): Stream redaction config. When true (default), redacts sensitive data from stream chunks before sending to clients. (Default: `{ redact: true }`)
+
+**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH (e.g., GET:/api/health). Value false makes route public, true requires auth.
+
+**tools** (`ToolsInput`): Available tools for the server
+
+**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions** (`MCPOptions`): MCP transport options. Set serverless: true for stateless environments like Vercel Edge.
+
+## Adding custom routes
+
+Add routes directly to the Elysia app:
+
+```typescript
+import { Elysia } from 'elysia'
+import { MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+// Before init - runs before Mastra middleware
+app.get('/early-health', () => ({ status: 'ok' }))
+
+await server.init()
+
+// After init - has access to Mastra context
+app.get('/custom', ({ mastra }) => {
+  return { agents: Object.keys(mastra.listAgents()) }
+})
+```
+
+> **Tip:** Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
+
+When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route). For raw Elysia routes mounted directly on `app`, use `createAuthMiddleware()`:
+
+```typescript
+import { Elysia } from 'elysia'
+import { createAuthMiddleware, MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.get('/custom/protected', async ctx => {
+  const authResponse = await createAuthMiddleware({ mastra })(ctx)
+  if (authResponse) return authResponse
+
+  const user = ctx.requestContext.get('user')
+  return { user }
+})
+
+app.get('/custom/public', async ctx => {
+  const authResponse = await createAuthMiddleware({ mastra, requiresAuth: false })(ctx)
+  if (authResponse) return authResponse
+
+  return { ok: true }
+})
+```
+
+## Accessing context
+
+In Elysia handlers registered after `init()`, access Mastra context from the handler context:
+
+```typescript
+app.get('/custom', ({ mastra, requestContext, abortSignal }) => {
+  const agent = mastra.getAgent('myAgent')
+  const user = requestContext.get('user')
+
+  return { agent: agent.name, user, aborted: abortSignal.aborted }
+})
+```
+
+Available context keys:
+
+| Key                     | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `mastra`                | Mastra instance                                                |
+| `requestContext`        | Request context map                                            |
+| `abortSignal`           | Request cancellation signal                                    |
+| `registeredTools`       | Available tools                                                |
+| `taskStore`             | Task store for A2A operations                                  |
+| `customRouteAuthConfig` | Per-route auth overrides                                       |
+| `user`                  | Authenticated user in `requestContext` when auth is configured |
+
+## OpenAPI helpers
+
+Use `getMastraOpenAPIDoc()` when you need to pass Mastra's generated OpenAPI document to Elysia tooling such as `@elysiajs/openapi`:
+
+```typescript
+import { openapi } from '@elysiajs/openapi'
+import { Elysia } from 'elysia'
+import { getMastraOpenAPIDoc, MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.use(
+  openapi({
+    documentation: getMastraOpenAPIDoc(server),
+  }),
+)
+```
+
+Call `clearMastraOpenAPICache(server)` if you need to regenerate the cached document for the same server instance.
+
+## MCP support
+
+The Elysia adapter supports both MCP HTTP and MCP SSE transports.
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.

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,19 @@
 # @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
+
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.19-alpha.15",
+  "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.9",
-    "@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",
@@ -46,8 +46,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
     "@internal/lint": "0.0.125",
-    "@mastra/core": "1.62.0-alpha.9",
-    "@internal/types-builder": "0.0.100"
+    "@internal/types-builder": "0.0.100",
+    "@mastra/core": "1.62.0-alpha.11"
   },
   "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)