@mastra/mcp-docs-server 1.3.7-alpha.5 → 1.3.7-alpha.7

package/.docs/docs/harness/agent-controller.md

@@ -133,6 +133,24 @@ const session = await controller.createSession({
 
 Use [`session.thread.create()`](https://mastra.ai/reference/agent-controller/session) and [`session.thread.switch()`](https://mastra.ai/reference/agent-controller/session) to move one live Session between conversations.
 
+### Transfer thread ownership
+
+Each new thread stores its durable owner in `metadata.ownerId` and its original creator in `metadata.createdBy`. Both default to the Session host's `ownerId`. `createdBy` doesn't change when ownership transfers.
+
+Read the active thread's owner and transfer it through `session.thread`:
+
+```typescript
+const currentOwnerId = await session.thread.getOwner()
+
+await session.thread.transferOwnership({
+  toOwnerId: 'user-456',
+})
+```
+
+Transfers are serialized within one process. Hosts that require a durable cross-process compare-and-set should commit it in their own storage first, then call `transferOwnership()` to mirror the owner onto the active thread.
+
+Every run snapshots the thread owner when it starts. Tools and other dynamic runtime code can read that value from `AgentControllerRequestContext.threadOwnerId`. If ownership changes during a run, the active run keeps the old snapshot and the next run receives the new owner. `context.session.ownerId` remains the identity of the process-local Session host.
+
 ### List stored messages from the client
 
 Use the Agent Controller client to page through a thread's stored messages. Passing an options object returns the messages with pagination metadata:

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

@@ -179,6 +179,94 @@ The API returns `401` for invalid credentials, `403` for organization authorizat
 
 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).
 
+## Metrics API
+
+The Metrics API queries metrics 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.
+
+The endpoints share their query parameters, request bodies, and response types with the Mastra runtime metric routes. See the [metric queries reference](https://mastra.ai/reference/observability/metrics/queries) for the full contract, including [shared filters](https://mastra.ai/reference/observability/metrics/queries), [analytics methods](https://mastra.ai/reference/observability/metrics/queries), and [metric discovery](https://mastra.ai/reference/observability/metrics/queries).
+
+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 metrics in every project available to the token's organization.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/discovery/metric-names?prefix=mastra_model_" \
+  -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    | `/metrics`                       | List raw metric records                 |
+| POST   | `/metrics/aggregate`             | Return one aggregate value              |
+| POST   | `/metrics/breakdown`             | Group metrics by dimensions             |
+| POST   | `/metrics/timeseries`            | Bucket metrics by interval              |
+| POST   | `/metrics/percentiles`           | Return percentile series for one metric |
+| GET    | `/discovery/metric-names`        | List metric names                       |
+| GET    | `/discovery/metric-label-keys`   | List label keys for a metric            |
+| GET    | `/discovery/metric-label-values` | List values for a metric label key      |
+
+The list and discovery endpoints take their arguments as query parameters. See [`listMetrics(args)`](https://mastra.ai/reference/observability/metrics/queries) and [metric discovery](https://mastra.ai/reference/observability/metrics/queries) in the metric queries reference for the parameters each one accepts.
+
+Analytics endpoints accept the same JSON request bodies and return types as the [metric queries reference](https://mastra.ai/reference/observability/metrics/queries), including `name`, `aggregation`, `filters`, `groupBy`, `interval`, `percentiles`, `comparePeriod`, `limit`, `orderDirection`, and `distinctColumn`.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/metrics/aggregate" \
+  -X POST \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
+  -H "Content-Type: application/json" \
+  --data '{"name":["mastra_model_total_input_tokens","mastra_model_total_output_tokens"],"aggregation":"sum","filters":{"timestamp":{"start":"2026-09-13T00:00:00Z","end":"2026-10-13T00:00:00Z"}},"comparePeriod":"previous_period"}' | jq
+```
+
+`filters.timestamp` is optional. If you omit `start` and `end`, the query covers all retained data. `comparePeriod` requires both `start` and `end`. Without them, the previous-period fields are `null`.
+
+The API returns `401` for invalid credentials, `403` for organization authorization failures, and `400` for malformed query arguments or JSON bodies.
+
+#### `MastraClient`
+
+`MastraClient` from `@mastra/client-js` exposes the analytics and discovery methods. Set `baseUrl` to the region's host without the `/api/observability` path:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const mastraClient = new MastraClient({
+  baseUrl: 'https://observability.mastra.ai',
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_PLATFORM_ACCESS_TOKEN}`,
+    'X-Mastra-Project-Id': process.env.MASTRA_PROJECT_ID!,
+  },
+})
+
+const result = await mastraClient.getMetricAggregate({
+  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
+  aggregation: 'sum',
+})
+```
+
+#### CLI
+
+The [`mastra api metric`](https://mastra.ai/reference/cli/mastra) commands target the United States endpoint by default. Pass `--url` to query the European Union region:
+
+```bash
+mastra api --url https://observability.eu.mastra.ai metric aggregate '<json>'
+```
+
 ## Gateway proxy endpoints
 
 Visit the [Gateway documentation](https://gateway.mastra.ai/docs) for more details.

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

@@ -168,6 +168,8 @@ The CLI can infer platform credentials from your project environment. See the [`
 
 You can query exported feedback over HTTP. See the [Feedback API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, project scoping, and supported query parameters such as `traceId` and `environment`.
 
+You can query exported metrics over HTTP, with `MastraClient`, or with `mastra api metric`. See the [Metrics API](https://mastra.ai/docs/mastra-platform/api) for regional endpoints, authentication, project scoping, and supported endpoints.
+
 ## Import existing traces
 
 Use `mastra traces import` to move existing trace history from a supported observability provider into an existing Mastra Platform project. The command reads and validates complete traces at the source, converts them into Mastra spans, then uses a shared workflow for preparation, upload, resume, and verification.

package/.docs/docs/server/request-context.md

@@ -284,11 +284,11 @@ requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
 requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
 ```
 
-| Key                         | Purpose                                                                                                                                                                                                                                 |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MASTRA_RESOURCE_ID_KEY`    | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not.                                                                                        |
-| `MASTRA_THREAD_ID_KEY`      | Forces thread operations to use this thread ID, overriding client-provided values                                                                                                                                                       |
-| `MASTRA_MESSAGE_AUTHOR_KEY` | Names who sent a user message as `{ id, name?, avatarUrl? }`. Agent-controller sessions copy it onto every message the request sends as `providerMetadata.mastra.author`, so a thread shared by several people can show who wrote what. |
+| Key                         | Purpose                                                                                                                                                                                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_RESOURCE_ID_KEY`    | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not.                                                                                                                          |
+| `MASTRA_THREAD_ID_KEY`      | Forces thread operations to use this thread ID, overriding client-provided values                                                                                                                                                                                         |
+| `MASTRA_MESSAGE_AUTHOR_KEY` | Names who sent a user message as `{ id, name?, avatarUrl? }`. Agent-controller sessions persist it at `content.metadata.signal.author` and mirror it to `providerMetadata.mastra.author` for compatibility, so a thread shared by several people can show who wrote what. |
 
 These keys are used to implement user isolation in multi-tenant applications. See [Authorization middleware](https://mastra.ai/docs/server/middleware) for usage examples.
 

package/.docs/reference/agent-controller/agent-controller-class.md

@@ -194,7 +194,7 @@ The same `resourceId` and `scope` return the same `Session` instance. A differen
 
 **id** (`string`): Stable session identifier. Defaults to the controller id.
 
-**ownerId** (`string`): Stable session owner identifier. Defaults to id.
+**ownerId** (`string`): Stable identity of the process-local Session host. Defaults to id. New threads use it as their initial owner, but later transfers do not change this value.
 
 **tags** (`Record<string, string>`): Tags copied to threads created by the session.
 

package/.docs/reference/agent-controller/session.md

@@ -92,20 +92,25 @@ Returns: `() => void`
 
 ### Messages and run control
 
-#### `sendMessage({ content, files?, requestContext? })`
+#### `sendMessage({ content, files?, requestContext?, author? })`
 
-Send a user message. The session creates a thread first when no thread is active.
+Send a user message. The session creates a thread first when no thread is active. Pass `author` when the host has authenticated the sender.
 
 ```typescript
 await session.sendMessage({
   content: 'Summarize this file.',
   files: [{ data: fileContents, mediaType: 'text/plain', filename: 'notes.txt' }],
+  author: { id: 'user-123' },
 })
 ```
 
-When `requestContext` carries `MASTRA_MESSAGE_AUTHOR_KEY`, the stored message names that sender under `content.providerMetadata.mastra.author`. See [Reserved keys](https://mastra.ai/docs/server/request-context).
+The author persists under `content.metadata.signal.author`. Read it with `getMessageAuthor(message)` from `@mastra/core/agent`. When `requestContext` carries `MASTRA_MESSAGE_AUTHOR_KEY`, the session uses that value if `author` is omitted. See [Reserved keys](https://mastra.ai/docs/server/request-context).
 
-#### `steer({ content, requestContext? })`
+#### `queueMessage({ content, files?, requestContext?, author? })`
+
+Queue a message for the next run, or send it immediately while the session is idle. Author metadata persists with the queued message.
+
+#### `steer({ content, requestContext?, author? })`
 
 Queue steering content into an active run.
 
@@ -295,7 +300,9 @@ To change the resource ID, use [`controller.setResourceId()`](https://mastra.ai/
 
 ## Thread
 
-`session.thread` owns the active thread binding and resource-scoped thread operations. Stored threads and messages can survive controller recreation when storage is configured. Conversation settings such as mode, model, thinking level, token usage, and pending runs are restored from the active thread when the session creates or switches threads. The live session and its event bus don't persist.
+`session.thread` owns the active thread binding and resource-scoped thread operations. Stored threads and messages can survive controller recreation when storage is configured. Conversation settings such as mode, model, thinking level, token usage, pending runs, and ownership are restored from the active thread when the session creates or switches threads. The live session and its event bus don't persist.
+
+New threads store the Session host's `ownerId` in the reserved `metadata.ownerId` and `metadata.createdBy` fields. Clones use the cloning Session host for both fields. Existing threads without `metadata.ownerId` read as owned by the current Session host without writing a backfill.
 
 ### `session.thread.create({ title?, id?, requestContext? })`
 
@@ -369,6 +376,43 @@ Return the active thread ID, creating and binding a new thread when none is boun
 const threadId = await session.thread.ensureId()
 ```
 
+### `session.thread.getOwner({ threadId? })`
+
+Return a thread's durable owner. Omit `threadId` to read the active thread. The method returns `undefined` when no thread is selected. An owner-less legacy thread returns the Session host's `ownerId` without writing a backfill.
+
+```typescript
+const ownerId = await session.thread.getOwner()
+```
+
+Returns: `Promise<string | undefined>`
+
+### `session.thread.transferOwnership({ toOwnerId })`
+
+Store `toOwnerId` in the active thread's `metadata.ownerId` and emit `thread_owner_changed`. The original `metadata.createdBy` value doesn't change.
+
+```typescript
+await session.thread.transferOwnership({
+  toOwnerId: 'user-456',
+})
+```
+
+Returns: `Promise<void>`
+
+Transfers are serialized within one process. Storage-backed applications that require a durable cross-process compare-and-set should perform it in their own store first, then call this method to mirror the result.
+
+A successful change emits:
+
+```typescript
+const event = {
+  type: 'thread_owner_changed',
+  threadId: 'thread-7',
+  fromOwnerId: 'user-123',
+  toOwnerId: 'user-456',
+}
+```
+
+Runs snapshot ownership when they start. Within agent tools and dynamic runtime functions, `AgentControllerRequestContext.threadOwnerId` remains unchanged for the run's lifetime. A transfer becomes visible on the next run. `AgentControllerRequestContext.session.ownerId` continues to identify the process-local Session host.
+
 ### `session.thread.list(options?)`
 
 List threads from storage. By default only threads for the current resource are returned, and transient forked subagent threads are hidden.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.3.7-alpha.5",
+  "version": "1.3.7-alpha.7",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.77.0-alpha.2",
+    "@mastra/core": "1.77.0-alpha.3",
     "@mastra/mcp": "^2.4.0-alpha.0"
   },
   "devDependencies": {
@@ -43,9 +43,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
-    "@internal/lint": "0.0.142",
-    "@mastra/core": "1.77.0-alpha.2",
-    "@internal/types-builder": "0.0.117"
+    "@internal/types-builder": "0.0.117",
+    "@mastra/core": "1.77.0-alpha.3",
+    "@internal/lint": "0.0.142"
   },
   "homepage": "https://mastra.ai",
   "repository": {