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

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.
 
@@ -225,9 +230,13 @@ session.respondToToolApproval({ decision: 'decline', toolCallId: event.toolCallI
 session.respondToToolApproval({ decision: 'always_allow_category', toolCallId: event.toolCallId })
 ```
 
-#### `respondToToolSuspension({ resumeData, toolCallId?, requestContext? })`
+#### `respondToToolSuspension({ resumeData, address?, toolCallId?, requestContext? })`
+
+Resume a suspended tool with application-provided data. Supply `toolCallId` for a prompt on the active thread. To resume after switching threads, retain the full `address` returned by `session.claimToolSuspension(toolCallId, runId)` and pass it instead of `toolCallId`.
 
-Resume a suspended tool with application-provided data. Supply `toolCallId` when several tool calls are suspended.
+An addressed resume uses the source thread's mode, model, and thread-owned preferences, without selecting that thread or replacing the active thread's subscription. Tool state callbacks remain bound to the source even if you switch threads during execution. Host-owned custom state and permission rules remain shared.
+
+After a process restart, a full address can recover a persisted suspension through the controller's configured agents. Recovery requires a uniquely identified originating agent and the existing resume authorization checks. A setup failure leaves the prompt retryable; it doesn't finish another thread's active run.
 
 ```typescript
 await session.respondToToolSuspension({
@@ -244,6 +253,8 @@ For `submit_plan`, pass `{ action: 'approved' }` or `{ action: 'rejected', feedb
 
 Return a copy of the running token-usage tally for the active thread.
 
+The executing run saves token usage to its own thread as each step finishes, including runs resumed while another thread is selected. If a storage operation fails, the execution owner retains the measured usage and retries it with the next step. Sessions that only subscribe to a thread display its saved total without counting replayed steps again or saving usage.
+
 ```typescript
 const usage = session.getTokenUsage()
 // { promptTokens, completionTokens, totalTokens, ... }
@@ -251,7 +262,7 @@ const usage = session.getTokenUsage()
 
 ## Identity
 
-`session.identity` owns the stable identifiers for the conversation: the resource ID and session `id`, plus an `ownerId`. The `id` and `ownerId` are stable for the life of the session and don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage.
+`session.identity` identifies the process-local session host: the resource ID and session `id`, plus an `ownerId`. The `id` and `ownerId` are stable for the life of the host and don't change when the resource ID is switched. AgentController doesn't persist the live session or mirror these values to a `SessionRecord`.
 
 ### `session.identity.getId()`
 
@@ -263,7 +274,7 @@ const sessionId = session.identity.getId()
 
 ### `session.identity.getOwnerId()`
 
-Return the stable owner identifier for the session.
+Return the stable owner identifier for the process-local session host. This value isn't a durable thread owner.
 
 ```typescript
 const ownerId = session.identity.getOwnerId()
@@ -289,12 +300,18 @@ 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. The live session and its event bus don't.
+`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? })`
 
 Create a thread, bind the session to it, and open its event stream. Pass `requestContext` when memory is a function that reads the signed-in user.
 
+For a session created with `createInitialThread: false`, explicit mode, model, and thread-preference selections made before its first binding seed the first new thread. This also applies to `ensureId()` and the first message. Failed creation leaves those selections available for retry.
+
+After the session has bound a conversation, creating another thread uses controller defaults, not the previous conversation's choices. Clearing or deleting the binding doesn't restore the first-thread behavior. Opening an existing thread restores that thread's settings instead of applying unbound startup selections.
+
 ```typescript
 const thread = await session.thread.create({
   id: 'thread-7',
@@ -329,6 +346,8 @@ Returns: `Promise<AgentControllerThread>`
 
 Switch to an owned stored thread and hydrate its mode, model, and observational memory settings. Pass `requestContext` when memory is a function that reads the signed-in user.
 
+Switching away cancels a running local execution only when this session initiated it. A session listening to another session's run detaches without cancelling that run. This follows the current action's initiator, not ownership of the thread. Parked tool prompts remain available for later resume.
+
 ```typescript
 await session.thread.switch({ threadId: 'thread-8' })
 ```
@@ -357,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.
@@ -759,7 +815,13 @@ After every event, the session emits `display_state_changed` with the latest sna
 
 ## State
 
-`session.state` owns the schema-validated AgentController state for the conversation. It holds the current snapshot and validates updates against the `stateSchema` passed to the AgentController. Updates are serialized, and every change emits a `state_changed` event.
+`session.state` exposes the active conversation's thread-owned preferences together with host-owned state. Updates are serialized and validated against the `stateSchema` passed to the AgentController. Visible state changes emit `state_changed`.
+
+Thread-owned preferences include thinking level, observational memory settings, and subagent model selections. Switching threads leaves host-owned custom fields and permission rules unchanged and doesn't persist them.
+
+A queued write keeps its source thread through asynchronous updates and validation. Switching from A to B while a write is pending doesn't apply A's preferences to B. Host-field updates still affect the host. A retained run and the active view of the same thread share update ordering. A resumed run sees edits made while it was parked. Events without a source address that affect the conversation display are emitted only while that source is active.
+
+Inside a tool's controller request context, `state` is a snapshot taken when the context was built. Use `getState()` or `session.state.get()` to read the latest source-thread state after a write.
 
 ### `session.state.get()`
 
@@ -790,9 +852,13 @@ const added = await session.state.update(current => ({
 
 ## Persistence boundaries
 
-A `Session` is a live runtime object. Its event bus, arbitrary `session.state`, permission rules, permission grants, pending approvals, suspensions, follow-ups, run state, and stream state don't automatically survive controller or process recreation. The host must restore any of this state when recreating a session.
+A `Session` is a live runtime object. Its event bus, arbitrary custom state, permission rules, permission grants, follow-ups, and active stream don't automatically survive controller or process recreation. The host must restore the host-owned state it needs.
+
+Configured storage persists threads and messages along with token usage, while thread settings restore mode, model, and supported preferences. Restored settings can include thinking level, observational memory, and subagent model selections with per-agent-type overrides. Persisted suspended runs can be recovered using their full suspension address and originating agent; this doesn't make arbitrary custom state durable.
+
+While a run retains a source-thread view, successful in-memory preference writes remain available when returning to that thread even if best-effort metadata persistence fails. A cold restart can recover only persisted settings and controller defaults.
 
-Configured storage persists threads and messages along with token usage, while thread settings restore mode and model choices. Restored settings can include observational memory and subagent model selections with per-agent-type overrides. A chat channel can map back to stored threads. However, `AgentControllerChannels` keeps channel-to-session and auto-approval state in memory.
+A chat channel can map back to stored threads. However, `AgentControllerChannels` keeps channel-to-session and auto-approval state in memory.
 
 ## Related
 

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

@@ -1153,19 +1153,19 @@ See [Import existing traces](https://mastra.ai/docs/mastra-platform/observabilit
 
 ### Options
 
-#### `--project <name|slug|id>`
+#### `--target-project <name|slug|id>`
 
-Selects the destination Mastra Platform project. Takes precedence over `MASTRA_PROJECT_ID`. Without either value, the command uses the project linked in `.mastra-project.json`.
+Selects the destination Mastra Platform project that receives the traces. Takes precedence over `MASTRA_PROJECT_ID`. Without either value, the command uses the project linked in `.mastra-project.json`. The source project comes from the provider credentials, such as `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY`.
 
-#### `--from <date>`
+#### `--since <date>`
 
-Sets the inclusive start of the import window as an ISO 8601 date or timestamp. It defaults to 30 days before `--to`, clamped to the current 30-day Platform retention boundary.
+Sets the inclusive start of the import window as an ISO 8601 date or timestamp. It defaults to 30 days before `--until`, clamped to the current 30-day Platform retention boundary. `--from` is accepted as an alias.
 
-#### `--to <date>`
+#### `--until <date>`
 
-Sets the exclusive end of the import window as an ISO 8601 date or timestamp. It defaults to the time when the import starts and can't be in the future.
+Sets the exclusive end of the import window as an ISO 8601 date or timestamp. It defaults to the time when the import starts and can't be in the future. `--to` is accepted as an alias.
 
-The complete window must fall within the current 30-day Platform retention period, `--from` must be earlier than `--to`, and the window can't exceed 30 days.
+The complete window must fall within the current 30-day Platform retention period, `--since` must be earlier than `--until`, and the window can't exceed 30 days.
 
 #### `--dry-run`
 
@@ -1173,7 +1173,7 @@ Reads the source and prepares valid traces locally without uploading them. The c
 
 #### `--resume <import-id>`
 
-Resumes a prepared import using its saved provider, destination project, date window, and acknowledged progress. Use the same destination project shown in the generated resume command. This option can't be combined with `--from`, `--to`, or `--dry-run`.
+Resumes a prepared import using its saved provider, destination project, date window, and acknowledged progress. Use the same destination project shown in the generated resume command. This option can't be combined with `--since`, `--until`, or `--dry-run`.
 
 #### `-y, --yes`
 
@@ -1185,29 +1185,29 @@ The command loads `.env` and `.env.local` from the current directory.
 
 | Variable                       | Required                                        | Description                                                                                                       |
 | ------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `LANGFUSE_PUBLIC_KEY`          | For new Langfuse imports                        | Public project API key.                                                                                           |
+| `LANGFUSE_PUBLIC_KEY`          | For new Langfuse imports                        | Public project API key. Together with the secret key, it selects the source Langfuse project.                     |
 | `LANGFUSE_SECRET_KEY`          | For new Langfuse imports                        | Secret project API key.                                                                                           |
 | `LANGFUSE_BASE_URL`            | No                                              | Langfuse host. Defaults to `https://cloud.langfuse.com`.                                                          |
 | `MASTRA_API_TOKEN`             | For headless authentication                     | Mastra Platform API token. Without it, the command uses credentials from `mastra auth login`.                     |
 | `MASTRA_ORG_ID`                | With `MASTRA_API_TOKEN`                         | Organization that owns the destination project.                                                                   |
 | `MASTRA_PLATFORM_ACCESS_TOKEN` | For upload and read-back with interactive login | Mastra Platform access token for the destination. Not required for `--dry-run` or when `MASTRA_API_TOKEN` is set. |
-| `MASTRA_PROJECT_ID`            | When no project is otherwise linked             | Destination project ID. The `--project` flag takes precedence over it.                                            |
+| `MASTRA_PROJECT_ID`            | When no project is otherwise linked             | Destination project ID. The `--target-project` flag takes precedence over it.                                     |
 
 ### Examples
 
 Preview the default 30-day window without uploading:
 
 ```bash
-mastra traces import langfuse --project my-project --dry-run
+mastra traces import langfuse --target-project my-mastra-project --dry-run
 ```
 
 Import a smaller date window without a confirmation prompt:
 
 ```bash
 mastra traces import langfuse \
-  --project my-project \
-  --from "$FROM" \
-  --to "$TO" \
+  --target-project my-mastra-project \
+  --since "$SINCE" \
+  --until "$UNTIL" \
   --yes
 ```
 
@@ -1216,7 +1216,7 @@ Resume an existing import:
 ```bash
 mastra traces import langfuse \
   --resume 00000000-0000-0000-0000-000000000000 \
-  --project my-project
+  --target-project my-mastra-project
 ```
 
 ## `mastra api`

package/package.json

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