@mastra/mcp-docs-server 1.2.2-alpha.4 → 1.2.2-alpha.7

package/.docs/docs/agents/background-tasks.md

@@ -49,7 +49,7 @@ Once a tool has opted in, the LLM can optionally include a `_background` field i
 
 ### Tool-level
 
-Set `backgroundTasks.enabled: true` on the tool definition. Tools opted in at this layer run in the background whenever called by an agent that has the manager enabled.
+Set `background.enabled: true` on the tool definition. Tools opted in at this layer run in the background whenever called by an agent that has the manager enabled.
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -59,7 +59,7 @@ export const researchTool = createTool({
   id: 'research',
   description: 'Run a long research job',
   inputSchema: z.object({ topic: z.string() }),
-  backgroundTasks: {
+  background: {
     enabled: true,
     timeoutMs: 600_000,
     maxRetries: 1,
@@ -111,7 +111,7 @@ The `_background` override is a _modifier_ on tools the developer has already op
 When a tool call is dispatched, the resolved background config is computed in this priority order:
 
 1. Agent-level `backgroundTasks.tools` entry for the tool.
-2. Tool-level `backgroundTasks` config.
+2. Tool-level `background` config.
 3. LLM `_background.enabled` override (only used to enable background dispatch when the tool was opted in at one of the layers above).
 4. Manager defaults (`defaultTimeoutMs`, `defaultRetries`).
 
@@ -200,7 +200,7 @@ const stream = await supervisor.stream('Research AI in education and write an ar
 
 ### Inheriting from the subagent
 
-If a subagent isn't listed under the supervisor's `backgroundTasks.tools` but has background-eligible tools of its own (either via tool-level `backgroundTasks.enabled: true` or its own `backgroundTasks.tools` entry) the framework still dispatches the entire subagent invocation as a background task. The supervisor inherits the subagent's intent: the subagent itself becomes the background task, and its inner tools run in the foreground inside the subagent's loop.
+If a subagent isn't listed under the supervisor's `backgroundTasks.tools` but has background-eligible tools of its own (either via tool-level `background.enabled: true` or its own `backgroundTasks.tools` entry) the framework still dispatches the entire subagent invocation as a background task. The supervisor inherits the subagent's intent: the subagent itself becomes the background task, and its inner tools run in the foreground inside the subagent's loop.
 
 The background config used for the inherited dispatch (for example `waitTimeoutMs`) is derived from the subagent's own `backgroundTasks` config.
 
@@ -285,7 +285,7 @@ The manager keeps tool executors in process memory. If the process restarts whil
 
 Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their respective outcomes:
 
-- Tool-level `backgroundTasks.onComplete` / `onFailed`: scoped to one tool.
+- Tool-level `background.onComplete` / `onFailed`: scoped to one tool.
 - Agent-level `backgroundTasks.onTaskComplete` / `onTaskFailed`: scoped to all tasks dispatched by this agent.
 - Manager-level `onTaskComplete` / `onTaskFailed`: scoped globally.
 

package/.docs/docs/harness/modes.md

@@ -79,6 +79,27 @@ const buildMode = { id: 'build', additionalTools: { deployTool } }
 
 You can't set both `tools` and `additionalTools` on the same mode.
 
+### Restricting tool visibility
+
+`tools` and `additionalTools` control which tools are **added** to a mode's run — they don't hide the backing agent's own tools. To restrict which of those tools the model can actually see and call, set `availableTools`:
+
+```typescript
+const reviewMode = {
+  id: 'review',
+  name: 'Review',
+  // Only these tools are visible to the model in this mode.
+  availableTools: ['view', 'find_files', 'search_content'],
+}
+```
+
+`availableTools` is a per-mode visibility allowlist that matches each tool by its final exposed name:
+
+- **`undefined`** (default): no mode-level restriction — every tool is visible.
+- **`[]`**: no tools are available for this mode.
+- A denied tool stays hidden even if it appears in the list. Per-tool and per-category `deny` rules in your permission config always take precedence.
+
+Workspace tools use the same list as every other tool — reference them by their exposed names (`view`, `write_file`, `find_files`, etc.). Visibility is enforced at LLM-call time, so the model never sees — and can't attempt to call — a tool outside the allowlist.
+
 ### Mode transitions
 
 A mode can declare a `transitionsTo` target. When the `submit_plan` built-in tool runs in that mode, the Harness transitions to the target mode on approval:

package/.docs/reference/ai-sdk/workflow-snapshot-to-stream.md

@@ -0,0 +1,51 @@
+# workflowSnapshotToStream()
+
+Converts a `WorkflowState` object (as returned by `workflow.getWorkflowRunById()`) into a `ReadableStream` of AI SDK UIMessage data parts. The stream contains the same `WorkflowDataPart` and `WorkflowStepDataPart` chunks that the live [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route) produces.
+
+Use this when you want to display a completed or suspended workflow run using the same UI components that render live workflow streams.
+
+## Usage example
+
+Next.js App Router endpoint that replays a past workflow run as a stream:
+
+```typescript
+import { workflowSnapshotToStream } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '@/src/mastra'
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const runId = searchParams.get('runId')!
+
+  const workflowRun = await mastra.getWorkflow('myWorkflow').getWorkflowRunById(runId)
+
+  if (!workflowRun) {
+    return new Response('Not found', { status: 404 })
+  }
+
+  const stream = workflowSnapshotToStream(workflowRun)
+  return createUIMessageStreamResponse({ stream })
+}
+```
+
+## Parameters
+
+**workflowRun** (`WorkflowState`): The workflow run state object, as returned by \`getWorkflowRunById()\` or the workflow runs API. Contains \`runId\`, \`workflowName\`, \`status\`, and \`steps\`.
+
+## Returns
+
+`ReadableStream` — A stream of AI SDK UIMessage data parts containing:
+
+- A `start` marker
+- A `WorkflowDataPart` with the overall workflow status and all step summaries
+- A `WorkflowStepDataPart` for each step with its full output
+- A `finish` marker
+
+Pass this stream to [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response) or `createUIMessageStream()` from the AI SDK.
+
+## Related
+
+- [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route): Stream live workflow runs
+- [`handleWorkflowStream()`](https://mastra.ai/reference/ai-sdk/handle-workflow-stream): Framework-agnostic handler for live workflow streaming
+- [`toAISdkStream()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-stream): Convert live Mastra streams to AI SDK format
+- [`toAISdkMessages()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-messages): Convert stored agent messages to AI SDK format

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

@@ -666,6 +666,14 @@ Target a specific Mastra server URL.
 mastra api --url https://example.com agent list
 ```
 
+#### `--server-api-prefix <prefix>`
+
+Set the API route prefix of the target server. Defaults to `/api`. Use this when the server is mounted under a custom prefix (for example a `@mastra/fastify` `MastraServer` with `prefix: "/api/mastra-studio"`), the same way `mastra studio` accepts `--server-api-prefix`. You can also set the `MASTRA_API_PREFIX` environment variable instead of passing the flag.
+
+```bash
+mastra api --url https://example.com --server-api-prefix /api/mastra-studio agent list
+```
+
 #### `--header <"Key: Value">`
 
 Send a custom HTTP header. Repeat the flag to send multiple headers.

package/.docs/reference/harness/harness-class.md

@@ -82,6 +82,8 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **modes.additionalTools** (`ToolsInput`): Tools layered on top of the backing agent's tools. Mutually exclusive with \`tools\`.
 
+**modes.availableTools** (`string[]`): Per-mode tool visibility allowlist. When set, only tools whose final exposed names appear in this list are visible to the model and executable during this mode's runs. \`undefined\` = all tools visible; \`\[]\` = no tools. Per-tool and per-category \`deny\` rules take precedence over this list. Workspace tools use the same list — reference them by exposed names (\`view\`, \`write\_file\`, etc.).
+
 **modes.agent** (`Agent`): The agent for this mode. Deprecated in favor of the top-level \`agent\` config with mode-level overrides.
 
 **agent** (`Agent`): Shared backing agent that each mode forks and decorates. When provided, modes layer instructions and tool overrides on top of this agent instead of providing their own.
@@ -92,9 +94,9 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **tools** (`ToolsInput | ((ctx) => ToolsInput)`): Tools available to all agents across all modes. It can be a static tools object or a dynamic function that receives the request context.
 
-**workspace** (`Workspace | WorkspaceConfig | ((ctx) => Workspace)`): Workspace configuration. Accepts a pre-constructed Workspace, a WorkspaceConfig for the harness to construct internally, or a dynamic factory function.
+**workspace** (`Workspace | ((ctx) => Workspace)`): Workspace instance or a dynamic factory function. When omitted, each session created via createSession must provide its own workspace. The factory receives the request context and Mastra instance.
 
-**browser** (`MastraBrowser | ((ctx) => MastraBrowser)`): Browser automation configuration. Propagated to mode agents that don't have their own browser configured.
+**browser** (`MastraBrowser | ((ctx) => MastraBrowser)`): Browser automation instance or a dynamic factory function. When omitted, each session created via createSession can provide its own browser.
 
 **subagents** (`HarnessSubagent[]`): Subagent definitions. When provided, the harness creates a built-in \`subagent\` tool that parent agents can call to spawn focused subagents.
 
@@ -160,20 +162,22 @@ await harness.sendMessage({ content: 'Hello!' })
 
 #### `init()`
 
-Initialize the harness. Loads storage, initializes the workspace, propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the harness.
+Initialize the harness. Loads storage, initializes a static workspace (dynamic factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the harness.
 
 ```typescript
 await harness.init()
 ```
 
-#### `createSession({ id, ownerId, resourceId? })`
+#### `createSession({ id, ownerId, resourceId?, tags?, workspace?, browser?, requestContext? })`
 
-Create a new, fully-wired `Session` and bring it online. The session starts in the default mode with the seeded model, connects to the Harness's shared machinery (agent, storage/lock, config catalog), and has a current thread (the most recent thread for the resource, or a freshly created one). Call `init()` once before creating sessions so shared storage and workspace are ready.
+Create a new, fully-wired `Session` and bring it online. The session starts in the default mode with the seeded model, connects to the Harness's shared machinery (agent, storage/lock, config catalog), and has a current thread (the most recent thread for the resource, or a freshly created one). Call `init()` once before creating sessions so shared storage is ready.
 
 The Harness owns no session of its own — every consumer creates its own session and drives all work through it. In a server or multiplayer setting, each request, thread, or user gets its own session, isolated from every other: independent event bus, mode, model, state, and current thread.
 
 `id` and `ownerId` are required — they mirror `SessionRecord.id` and `SessionRecord.ownerId` and are stable for the life of the session. `resourceId` is optional and defaults to `config.resourceId` then `config.id`.
 
+Each session owns its own `Workspace` and `Browser` instance. When `workspace` is omitted, the Harness resolves its configured workspace (a static instance or a dynamic factory) and passes it to the session. Pass a `workspace` override to give a specific session a different workspace than the Harness default. The workspace is initialized during session creation; `workspace_ready` and `workspace_status_changed` events are emitted on the session bus after `init()` completes, and late subscribers receive a replay of the last workspace status.
+
 ```typescript
 const session = await harness.createSession({
   id: 'session-xyz',
@@ -191,6 +195,19 @@ const session = await harness.createSession({
 })
 ```
 
+Override the workspace and browser for a specific session:
+
+```typescript
+const session = await harness.createSession({
+  id: 'session-xyz',
+  ownerId: 'user-123',
+  workspace: myWorkspace,
+  browser: myBrowser,
+})
+```
+
+`tags` scopes initial thread selection: a thread is a resume candidate only when its metadata matches every provided tag. This lets worktrees sharing a resourceId each resume their own thread (via a `projectPath` tag).
+
 Switching the resource ID via `harness.setResourceId()` changes only the resource ID, not `id` or `ownerId`. Read them through `session.identity.getId()` and `session.identity.getOwnerId()`.
 
 #### `selectOrCreateThread()`
@@ -249,6 +266,48 @@ Return the internal `Mastra` instance, or `undefined` before `init()`. Useful fo
 const mastra = harness.getMastra()
 ```
 
+#### `getWorkspace()`
+
+Return the Harness-level workspace if it is a static `Workspace` instance. Dynamic factory workspaces are not resolved here — use [`resolveWorkspace()`](#resolveworkspace-session-requestcontext-) to resolve a factory against a session's request context.
+
+```typescript
+const workspace = harness.getWorkspace()
+```
+
+#### `resolveWorkspace({ session, requestContext? })`
+
+Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory against the given session's request context and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.
+
+```typescript
+const workspace = await harness.resolveWorkspace({ session })
+```
+
+```typescript
+// With an explicit request context
+const requestContext = new RequestContext()
+const workspace = await harness.resolveWorkspace({ session, requestContext })
+```
+
+#### `hasWorkspace()`
+
+Whether a workspace is configured on this Harness (static instance or dynamic factory). Sessions without an explicit workspace override fall back to this.
+
+```typescript
+if (harness.hasWorkspace()) {
+  // ...
+}
+```
+
+#### `isWorkspaceReady()`
+
+Whether the Harness-level static workspace has been initialized. Dynamic factory workspaces are resolved and initialized per-session during `createSession`, so this returns `false` for factory configs until a session is created.
+
+```typescript
+if (harness.isWorkspaceReady()) {
+  // ...
+}
+```
+
 ### Modes
 
 #### `listModes()`
@@ -469,52 +528,6 @@ const category = harness.getToolCategory({ toolName: 'mastra_workspace_write_fil
 // 'edit'
 ```
 
-### Workspace
-
-#### `getWorkspace()`
-
-Return the current workspace instance, or `undefined` if no workspace is configured or it hasn't been resolved yet.
-
-```typescript
-const workspace = harness.getWorkspace()
-```
-
-#### `resolveWorkspace({ requestContext? })`
-
-Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.
-
-```typescript
-const workspace = await harness.resolveWorkspace()
-```
-
-#### `hasWorkspace()`
-
-Return whether a workspace is configured (static, config-based, or dynamic).
-
-```typescript
-if (harness.hasWorkspace()) {
-  const workspace = await harness.resolveWorkspace()
-}
-```
-
-#### `isWorkspaceReady()`
-
-Return whether the workspace is ready to use. For dynamic workspaces (factory function), always returns `true`. For static workspaces, returns `true` after `init()` succeeds.
-
-```typescript
-if (harness.isWorkspaceReady()) {
-  const workspace = harness.getWorkspace()
-}
-```
-
-#### `destroyWorkspace()`
-
-Destroy the workspace and release resources. Only applies to static workspaces — dynamic workspaces aren't destroyed.
-
-```typescript
-await harness.destroyWorkspace()
-```
-
 ### Observational Memory
 
 #### `loadOMProgress()`

package/.docs/reference/harness/session.md

@@ -51,6 +51,8 @@ The session is organized into sub-objects, each owning one domain of per-convers
 
 **state** (`SessionState<TState>`): The schema-validated, session-owned Harness state. See state methods below.
 
+**browser** (`MastraBrowser | undefined`): The browser automation instance for this session. Set at creation via createSession, or from the Harness config default. Undefined when no browser is configured.
+
 ## Methods
 
 ### Permissions
@@ -563,6 +565,19 @@ const added = await harness.session.state.update(current => ({
 }))
 ```
 
+## Scoping tags
+
+Sessions carry scoping tags (e.g. `{ projectPath }`) seeded at creation and stamped onto every thread the session creates. Thread listings can be filtered back to the session's scope using these tags.
+
+### `getTags()`
+
+Return a copy of the session's scoping tags. Empty object when the session is unscoped.
+
+```typescript
+const tags = harness.session.getTags()
+// { projectPath: '/my/project' }
+```
+
 ## Related
 
 - [Harness class](https://mastra.ai/reference/harness/harness-class)

package/.docs/reference/index.md

@@ -40,6 +40,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [toAISdkV5Messages()](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v5-messages)
 - [withMastra()](https://mastra.ai/reference/ai-sdk/with-mastra)
 - [workflowRoute()](https://mastra.ai/reference/ai-sdk/workflow-route)
+- [workflowSnapshotToStream()](https://mastra.ai/reference/ai-sdk/workflow-snapshot-to-stream)
 - [Auth0](https://mastra.ai/reference/auth/auth0)
 - [Better Auth](https://mastra.ai/reference/auth/better-auth)
 - [Clerk](https://mastra.ai/reference/auth/clerk)

package/.docs/reference/processors/processor-interface.md

@@ -638,6 +638,8 @@ processOutputStep?(args: ProcessOutputStepArgs): ProcessorMessageResult;
 
 **finishReason** (`string`): The finish reason from the LLM (stop, tool-use, length, etc.).
 
+**providerMetadata** (`ProviderMetadata`): Provider-specific metadata for the finishing step (e.g. AWS Bedrock guardrail trace). Present when the model step produced provider metadata, including on content-filter blocks where \`steps\` is empty.
+
 **toolCalls** (`ToolCallInfo[]`): Tool calls made in this step (if any).
 
 **text** (`string`): Generated text from this step.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.2-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [[`462a769`](https://github.com/mastra-ai/mastra/commit/462a769da61850862ca1be3d74134d33078ee6a7), [`f328049`](https://github.com/mastra-ai/mastra/commit/f3280498c324afd2a8d36cd828f5b9f94a2dddc1), [`e545228`](https://github.com/mastra-ai/mastra/commit/e54522856934a5dc030b7b6385771e3548020d59)]:
+  - @mastra/core@1.47.0-alpha.4
+
+## 1.2.2-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`bf3fe49`](https://github.com/mastra-ai/mastra/commit/bf3fe49f9467dbbdb8f9eaf74e0f7971ffb19559), [`24ceaea`](https://github.com/mastra-ai/mastra/commit/24ceaea0bdd8609cabbab764380608ca6621a194), [`6ccf67b`](https://github.com/mastra-ai/mastra/commit/6ccf67bf075753754927a57bc2e1734ba2c820c5), [`825d8de`](https://github.com/mastra-ai/mastra/commit/825d8def9fa64c2bcc3d8dd6b49e09342c3ac5c7), [`ffa09e7`](https://github.com/mastra-ai/mastra/commit/ffa09e772a5c92270eabe2090fc42d45bd8ec4b7), [`461a7c5`](https://github.com/mastra-ai/mastra/commit/461a7c501449295287f4f0ee4b0b42344f39fcf8), [`4211472`](https://github.com/mastra-ai/mastra/commit/4211472a5a2bd319c60cd2e42d9109c3eef7ac1c), [`9e45902`](https://github.com/mastra-ai/mastra/commit/9e4590208e745055cecca202e2db0e5c65e17d3c), [`5c0df77`](https://github.com/mastra-ai/mastra/commit/5c0df776c40efa420f8c07a2f3ee66010296618e)]:
+  - @mastra/core@1.47.0-alpha.3
+
 ## 1.2.2-alpha.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.2-alpha.4",
+  "version": "1.2.2-alpha.7",
   "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.47.0-alpha.2",
-    "@mastra/mcp": "^1.12.0"
+    "@mastra/mcp": "^1.12.0",
+    "@mastra/core": "1.47.0-alpha.4"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@mastra/core": "1.47.0-alpha.2",
+    "@internal/lint": "0.0.108",
     "@internal/types-builder": "0.0.83",
-    "@internal/lint": "0.0.108"
+    "@mastra/core": "1.47.0-alpha.4"
   },
   "homepage": "https://mastra.ai",
   "repository": {