@mastra/mcp-docs-server 1.1.35-alpha.8 → 1.1.36-alpha.1

package/.docs/models/providers/xiaomi-token-plan-sgp.md

@@ -1,6 +1,6 @@
 # ![Xiaomi Token Plan (Singapore) logo](https://models.dev/logos/xiaomi-token-plan-sgp.svg)Xiaomi Token Plan (Singapore)
 
-Access 5 Xiaomi Token Plan (Singapore) models through Mastra's model router. Authentication is handled automatically using the `XIAOMI_API_KEY` environment variable.
+Access 6 Xiaomi Token Plan (Singapore) models through Mastra's model router. Authentication is handled automatically using the `XIAOMI_API_KEY` environment variable.
 
 Learn more in the [Xiaomi Token Plan (Singapore) documentation](https://platform.xiaomimimo.com/#/docs).
 
@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "xiaomi-token-plan-sgp/mimo-v2-omni"
+  model: "xiaomi-token-plan-sgp/mimo-v2-flash"
 });
 
 // Generate a response
@@ -34,7 +34,8 @@ for await (const chunk of stream) {
 
 | Model                                 | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `xiaomi-token-plan-sgp/mimo-v2-omni`  | 256K    |       |           |       |       |       | —          | —           |
+| `xiaomi-token-plan-sgp/mimo-v2-flash` | 262K    |       |           |       |       |       | —          | —           |
+| `xiaomi-token-plan-sgp/mimo-v2-omni`  | 262K    |       |           |       |       |       | —          | —           |
 | `xiaomi-token-plan-sgp/mimo-v2-pro`   | 1.0M    |       |           |       |       |       | —          | —           |
 | `xiaomi-token-plan-sgp/mimo-v2-tts`   | 8K      |       |           |       |       |       | —          | —           |
 | `xiaomi-token-plan-sgp/mimo-v2.5`     | 1.0M    |       |           |       |       |       | —          | —           |
@@ -50,7 +51,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://token-plan-sgp.xiaomimimo.com/v1",
-    id: "xiaomi-token-plan-sgp/mimo-v2-omni",
+    id: "xiaomi-token-plan-sgp/mimo-v2-flash",
     apiKey: process.env.XIAOMI_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -69,7 +70,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "xiaomi-token-plan-sgp/mimo-v2.5-pro"
-      : "xiaomi-token-plan-sgp/mimo-v2-omni";
+      : "xiaomi-token-plan-sgp/mimo-v2-flash";
   }
 });
 ```

package/.docs/models/providers.md

@@ -22,15 +22,18 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Cerebras](https://mastra.ai/models/providers/cerebras)
 - [Chutes](https://mastra.ai/models/providers/chutes)
 - [Clarifai](https://mastra.ai/models/providers/clarifai)
+- [Claudinio](https://mastra.ai/models/providers/claudinio)
 - [CloudFerro Sherlock](https://mastra.ai/models/providers/cloudferro-sherlock)
 - [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)
 - [Cortecs](https://mastra.ai/models/providers/cortecs)
 - [D.Run (China)](https://mastra.ai/models/providers/drun)
+- [Databricks](https://mastra.ai/models/providers/databricks)
 - [Deep Infra](https://mastra.ai/models/providers/deepinfra)
 - [DigitalOcean](https://mastra.ai/models/providers/digitalocean)
 - [DInference](https://mastra.ai/models/providers/dinference)
 - [evroc](https://mastra.ai/models/providers/evroc)
 - [FastRouter](https://mastra.ai/models/providers/fastrouter)
+- [Fireworks (Firepass)](https://mastra.ai/models/providers/firepass)
 - [Fireworks AI](https://mastra.ai/models/providers/fireworks-ai)
 - [Friendli](https://mastra.ai/models/providers/friendli)
 - [FrogBot](https://mastra.ai/models/providers/frogbot)
@@ -45,7 +48,6 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Jiekou.AI](https://mastra.ai/models/providers/jiekou)
 - [Kilo Gateway](https://mastra.ai/models/providers/kilo)
 - [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)
-- [Kiro](https://mastra.ai/models/providers/kiro)
 - [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)
 - [Llama](https://mastra.ai/models/providers/llama)
 - [LLM Gateway](https://mastra.ai/models/providers/llmgateway)
@@ -80,6 +82,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Qiniu](https://mastra.ai/models/providers/qiniu-ai)
 - [Regolo AI](https://mastra.ai/models/providers/regolo-ai)
 - [Requesty](https://mastra.ai/models/providers/requesty)
+- [Sarvam AI](https://mastra.ai/models/providers/sarvam)
 - [Scaleway](https://mastra.ai/models/providers/scaleway)
 - [SiliconFlow](https://mastra.ai/models/providers/siliconflow)
 - [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn)

package/.docs/reference/agents/agent.md

@@ -94,6 +94,89 @@ export const agent = new Agent({
 })
 ```
 
+## Thread signals
+
+Use Agent signals to send real-time context into a memory thread. Signals are useful when a user adds input while an agent is already streaming, or when another process needs to add structured context to the thread.
+
+A `user-message` signal represents user input. When the target thread is running, Mastra delivers the signal into the active agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input by default.
+
+```typescript
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+void (async () => {
+  for await (const chunk of subscription.stream) {
+    console.log(chunk)
+  }
+})()
+
+agent.sendSignal(
+  { type: 'user-message', contents: 'Use the latest customer note too.' },
+  {
+    resourceId: 'user-123',
+    threadId: 'thread-abc',
+    ifIdle: {
+      streamOptions: {
+        maxSteps: 3,
+      },
+    },
+  },
+)
+```
+
+Use a custom signal type for contextual messages that should reach the model as XML-wrapped context instead of normal user input:
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'system-reminder',
+    contents: 'Continue from the previous tool result.',
+    attributes: { reminderType: 'tool-result' },
+  },
+  { resourceId: 'user-123', threadId: 'thread-abc' },
+)
+```
+
+### `sendSignal(signal, options)`
+
+Sends a signal to an active run or memory thread.
+
+**signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to XML context before the next model call.
+
+**options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
+
+**options.resourceId** (`string`): Resource ID for the memory thread. Required with \`threadId\` for thread-targeted signals.
+
+**options.threadId** (`string`): Thread ID to target. Required with \`resourceId\` for thread-targeted signals.
+
+**options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`. Mastra uses the top-level \`resourceId\` and \`threadId\` for memory context.
+
+Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory.
+
+### `subscribeToThread(options)`
+
+Subscribes to raw stream chunks for a memory thread. Use this before calling `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
+
+**options.resourceId** (`string`): Resource ID for the memory thread.
+
+**options.threadId** (`string`): Thread ID to subscribe to.
+
+Returns an `AgentThreadSubscription` object with these members:
+
+**stream** (`AsyncIterable<AgentChunkType>`): Raw agent stream chunks for the subscribed thread.
+
+**activeRunId** (`() => string | null`): Returns the active run ID for the thread, or \`null\` when no run is active.
+
+**abort** (`() => boolean`): Aborts the active run for the thread. Returns \`true\` when a run was aborted.
+
+**unsubscribe** (`() => void`): Stops the subscription without aborting the active run.
+
 ## Constructor parameters
 
 **id** (`string`): Unique identifier for the agent. Defaults to \`name\` if not provided.
@@ -110,6 +193,8 @@ export const agent = new Agent({
 
 **tools** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
 
+**transform** (`ToolPayloadTransformPolicy`): Shared policy for transforming tool payloads before display streams or user-visible transcript messages receive them. Use per-tool \`transform\` on \`createTool()\` for tool-local rules.
+
 **workflows** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
 
 **defaultOptions** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>`): Default options used when calling \`stream()\` and \`generate()\`.

package/.docs/reference/browser/agent-browser.md

@@ -44,22 +44,25 @@ then interact with elements using their refs (e.g., @e5).`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
+**excludeTools** (`BrowserToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
+
 ## Tools
 
-`AgentBrowser` provides 15 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
+`AgentBrowser` provides 16 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
 
 ### Core tools
 
-| Tool               | Description                                       |
-| ------------------ | ------------------------------------------------- |
-| `browser_goto`     | Navigate to a URL                                 |
-| `browser_snapshot` | Get accessibility tree snapshot with element refs |
-| `browser_click`    | Click an element by ref                           |
-| `browser_type`     | Type text into an element                         |
-| `browser_press`    | Press keyboard keys                               |
-| `browser_select`   | Select option from dropdown                       |
-| `browser_scroll`   | Scroll the page or element                        |
-| `browser_close`    | Close the browser                                 |
+| Tool                 | Description                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `browser_goto`       | Navigate to a URL                                                                     |
+| `browser_snapshot`   | Get accessibility tree snapshot with element refs                                     |
+| `browser_click`      | Click an element by ref                                                               |
+| `browser_type`       | Type text into an element                                                             |
+| `browser_press`      | Press keyboard keys                                                                   |
+| `browser_select`     | Select option from dropdown                                                           |
+| `browser_scroll`     | Scroll the page or element                                                            |
+| `browser_screenshot` | Capture a screenshot as PNG (viewport by default; set `fullPage: true` for full page) |
+| `browser_close`      | Close the browser                                                                     |
 
 ### Extended tools
 
@@ -73,6 +76,14 @@ then interact with elements using their refs (e.g., @e5).`,
 | `browser_drag`     | Drag and drop elements                          |
 | `browser_evaluate` | Execute JavaScript in the page (escape hatch)   |
 
+To exclude specific tools, pass `excludeTools` in the constructor:
+
+```typescript
+const browser = new AgentBrowser({
+  excludeTools: ['browser_screenshot'],
+})
+```
+
 ## Tool reference
 
 ### `browser_goto`
@@ -339,6 +350,21 @@ Execute JavaScript in the page context. Use as an escape hatch when other tools
 | `script`      | `string`  | JavaScript to execute (required)        |
 | `returnValue` | `boolean` | Whether to return the result (optional) |
 
+### `browser_screenshot`
+
+Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `browser_snapshot` when you only need text or structured data.
+
+```text
+// Viewport only (default)
+
+// Full scrollable page
+{ "fullPage": true }
+```
+
+| Parameter  | Type      | Description                                                                              |
+| ---------- | --------- | ---------------------------------------------------------------------------------------- |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+
 ### `browser_close`
 
 Close the browser and clean up resources.

package/.docs/reference/browser/stagehand-browser.md

@@ -61,18 +61,29 @@ Use stagehand_extract to get data from pages.`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
+**excludeTools** (`StagehandToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
+
 ## Tools
 
-`StagehandBrowser` provides 6 AI-powered tools for browser automation:
+`StagehandBrowser` provides 7 AI-powered tools for browser automation:
+
+| Tool                   | Description                                                                           |
+| ---------------------- | ------------------------------------------------------------------------------------- |
+| `stagehand_act`        | Perform actions using natural language instructions                                   |
+| `stagehand_extract`    | Extract structured data from pages                                                    |
+| `stagehand_observe`    | Discover actionable elements on a page                                                |
+| `stagehand_navigate`   | Navigate to a URL                                                                     |
+| `stagehand_tabs`       | Manage browser tabs                                                                   |
+| `stagehand_screenshot` | Capture a screenshot as PNG (viewport by default; set `fullPage: true` for full page) |
+| `stagehand_close`      | Close the browser                                                                     |
 
-| Tool                 | Description                                         |
-| -------------------- | --------------------------------------------------- |
-| `stagehand_act`      | Perform actions using natural language instructions |
-| `stagehand_extract`  | Extract structured data from pages                  |
-| `stagehand_observe`  | Discover actionable elements on a page              |
-| `stagehand_navigate` | Navigate to a URL                                   |
-| `stagehand_tabs`     | Manage browser tabs                                 |
-| `stagehand_close`    | Close the browser                                   |
+To exclude specific tools, pass `excludeTools` in the constructor:
+
+```typescript
+const browser = new StagehandBrowser({
+  excludeTools: ['stagehand_screenshot'],
+})
+```
 
 ## Tool reference
 
@@ -224,6 +235,21 @@ Manage browser tabs.
 { "action": "close", "index": 1 }
 ```
 
+### `stagehand_screenshot`
+
+Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `stagehand_observe` or `stagehand_extract` when you only need text or structured data.
+
+```text
+// Viewport only (default)
+
+// Full scrollable page
+{ "fullPage": true }
+```
+
+| Parameter  | Type      | Description                                                                              |
+| ---------- | --------- | ---------------------------------------------------------------------------------------- |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+
 ### `stagehand_close`
 
 Close the browser and clean up resources.

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

@@ -118,6 +118,12 @@ Instead of an interactive prompt you can also define these CLI flags.
 
 **--skills** (`string`): Comma-separated list of agents to install Mastra skills for (e.g., claude-code,cursor,windsurf)
 
+**--observability** (`boolean`): Enable Observability on the Mastra platform during project creation. This opens browser login when needed, prompts for an organization, provisions a platform project, and configures the observability exporters.
+
+**--no-observability** (`boolean`): Skip the Observability prompt during project creation.
+
+**--observability-project** (`string`): Set the platform project name to use when Mastra Observability is enabled.
+
 **--help** (`boolean`): Display help for command
 
 ## Telemetry

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

@@ -201,11 +201,13 @@ mastra studio deploy
 
 The command runs `mastra build`, zips the output, reads an env file from the project directory, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
 
+The deploy command auto-loads the project's `.env` file. If `MASTRA_PROJECT_ID` points to a project that was provisioned for Observability, the deploy links to that project instead of creating a new one. Deploying Studio to an observability-only project converts it into a Studio project on the platform side.
+
 The CLI requires at least one `.env` or `.env.*` file (excluding `.env.example`) in the project directory and fails with `Error: No env file found for deploy.` if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to `.env.production`); pass `--env-file` to choose explicitly. With `--yes` and multiple env files, you must pass `--env-file` or the deploy errors.
 
 Organization and project are resolved in order from: Environment variable flag, `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
 
-If `--project <value>` does not match an existing project (by ID or slug), the CLI treats `<value>` as a new project name and creates it after confirmation. Combined with `--yes`, this creates and deploys a new project in one non-interactive command:
+If `--project <value>` doesn't match an existing project (by ID or slug), the CLI treats `<value>` as a new project name and creates it after confirmation. Combined with `--yes`, this creates and deploys a new project in one non-interactive command:
 
 ```bash
 mastra studio deploy --project "my-new-project" --yes
@@ -295,7 +297,7 @@ Shows diagnosis results and suggested fixes for a failed Studio deploy.
 mastra studio deploy suggestions [deploy-id]
 ```
 
-If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis does not exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
 
 ### `mastra studio projects`
 
@@ -303,12 +305,14 @@ Lists all projects in the current organization.
 
 ### `mastra studio projects create`
 
-Creates a new project through an interactive prompt. This command does not accept a `--name` flag; for non-interactive project creation, use [`mastra studio deploy --project <name> --yes`](#mastra-studio-deploy) instead, which creates the project and deploys to it in one step.
+Creates a new project through an interactive prompt. This command doesn't accept a `--name` flag; for non-interactive project creation, use [`mastra studio deploy --project <name> --yes`](#mastra-studio-deploy) instead, which creates the project and deploys to it in one step.
 
 ## `mastra server deploy`
 
 Builds and deploys your project to Server on Mastra platform. Works the same as [`mastra studio deploy`](#mastra-studio-deploy) with the same flags, arguments, and resolution logic.
 
+The deploy command auto-loads the project's `.env` file. If `MASTRA_PROJECT_ID` points to a project that was provisioned for Observability, the deploy links to that project instead of creating a new one. Deploying Server to an observability-only project converts it into a Server project on the platform side.
+
 ```bash
 mastra server deploy [dir]
 ```
@@ -321,7 +325,7 @@ Shows diagnosis results and suggested fixes for a failed Server deploy.
 mastra server deploy suggestions [deploy-id]
 ```
 
-If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis does not exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
 
 ## `mastra server pause`
 
@@ -339,13 +343,13 @@ Organization ID. Can also be set via the `MASTRA_ORG_ID` environment variable.
 
 #### `--project`
 
-Project ID or slug when `MASTRA_PROJECT_ID` is not set. Slugs are resolved against projects in the current organization.
+Project ID or slug when `MASTRA_PROJECT_ID` isn't set. Slugs are resolved against projects in the current organization.
 
 #### `-c, --config`
 
 Path to the project config file. Defaults to `.mastra-project.json`.
 
-Fails if the instance is not running.
+Fails if the instance isn't running.
 
 ## `mastra server restart`
 
@@ -359,7 +363,7 @@ Same flags as [`mastra server pause`](#mastra-server-pause): **`--org`**, **`--p
 mastra server restart
 ```
 
-Fails if a deployment is still active for this project (running, building, deploying, etc.); that is a platform restriction so you cannot restart while another deploy is in progress.
+Fails if a deployment is still active for this project (running, building, deploying, etc.); that's a platform restriction so you can't restart while another deploy is in progress.
 
 ## `mastra server env`
 
@@ -440,7 +444,7 @@ Lists all organizations with your role in each. The current organization is mark
 
 #### `mastra auth orgs switch`
 
-Switches the active organization through an interactive prompt. Cannot be used when `MASTRA_API_TOKEN` or `MASTRA_ORG_ID` environment variables are set.
+Switches the active organization through an interactive prompt. Can't be used when `MASTRA_API_TOKEN` or `MASTRA_ORG_ID` environment variables are set.
 
 ### `mastra auth tokens`
 
@@ -448,7 +452,7 @@ Lists all API tokens with their last-used date.
 
 #### `mastra auth tokens create`
 
-Creates a new API token. The secret is displayed once and cannot be retrieved again.
+Creates a new API token. The secret is displayed once and can't be retrieved again.
 
 ```bash
 mastra auth tokens create <name>
@@ -464,10 +468,42 @@ mastra auth tokens revoke <token-id>
 
 ## `mastra lint`
 
-The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
+The `mastra lint` command validates the structure and code of your Mastra project.
+
+By default, `mastra lint` runs project checks against your source files and configuration. Use `--preflight` to also run bundle checks against `.mastra/output` before deployment.
+
+```bash
+mastra lint --preflight
+```
 
 It accepts [common flags](#common-flags).
 
+### Flags
+
+#### `--preflight`
+
+Runs deployment preflight checks against the built Mastra output. This builds the project before checking it unless you also pass `--skip-build`.
+
+#### `--skip-build`
+
+Skips the build step and reuses the existing `.mastra/output` directory. This flag only applies when `--preflight` is set.
+
+#### `--env-file <file>`
+
+Uses the specified environment file for preflight validation. This flag only applies when `--preflight` is set.
+
+#### `--strict`
+
+Treats warnings as errors.
+
+#### `--json`
+
+Emits machine-readable JSON output.
+
+#### `--debug`
+
+Enables debug logs.
+
 ## `mastra scorers`
 
 The `mastra scorers` command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.
@@ -534,6 +570,18 @@ Don't include example code. Useful when using the `--default` flag.
 
 Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "cursor-global" | "windsurf" | "vscode"`.
 
+#### `--observability`
+
+Enable Observability on the Mastra platform. The CLI prompts you to select an existing platform project or create a new one, writes the required environment variables, and configures the observability exporters.
+
+#### `--no-observability`
+
+Skip the Mastra Observability prompt.
+
+#### `--observability-project`
+
+Set the platform project name to use when Mastra Observability is enabled.
+
 ## `mastra migrate`
 
 Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.
@@ -552,7 +600,7 @@ It accepts [common flags](#common-flags).
 
 ## `mastra api`
 
-Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra Platform projects, or self-hosted Mastra servers.
+Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, or self-hosted Mastra servers.
 
 ```bash
 mastra api agent list --pretty
@@ -594,9 +642,9 @@ The command resolves the target server in this order:
 
 1. `--url <url>` for an explicit remote or self-hosted server.
 2. `http://localhost:4111` for a local `mastra dev` server.
-3. `.mastra-project.json` for a Mastra Platform project.
+3. `.mastra-project.json` for a Mastra platform project.
 
-Automatic platform auth is only used when the CLI resolves a Mastra Platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets do not receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
+Automatic platform auth is only used when the CLI resolves a Mastra platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
 ### Flags
 
@@ -628,7 +676,7 @@ Pretty-print JSON output. Defaults to `false`.
 
 Print the CLI-oriented request schema for a command that accepts JSON input. The schema comes from the target server's route contracts and includes the command shape, positionals, examples, request schemas, and response shape.
 
-`--schema` is available on leaf commands that accept JSON input. It is not available as a top-level `mastra api` flag.
+`--schema` is available on leaf commands that accept JSON input. It isn't available as a top-level `mastra api` flag.
 
 ```bash
 mastra api agent run --schema
@@ -637,7 +685,7 @@ mastra api tool execute --schema
 
 ### Input model
 
-Commands that accept input take one inline JSON argument. Do not pass file paths or stdin.
+Commands that accept input take one inline JSON argument. Don't pass file paths or stdin.
 
 ```bash
 mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}'

package/.docs/reference/client-js/agents.md

@@ -151,6 +151,95 @@ for await (const part of uiMessageStream) {
 }
 ```
 
+### `sendSignal()`
+
+Send a signal to an active agent run or memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the signal.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const result = await agent.sendSignal({
+  signal: {
+    type: 'user-message',
+    contents: 'Also consider the customer note I just added.',
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+console.log(result.runId)
+```
+
+Use `ifActive.behavior` and `ifIdle.behavior` to control whether Mastra delivers, persists, discards, or wakes from a signal:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Store this for later.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'persist',
+  },
+})
+```
+
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Start from this signal.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
+    },
+  },
+})
+```
+
+Returns `{ accepted: true, runId: string }`.
+
+**signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to contextual XML before the next model call.
+
+**runId** (`string`): Run ID to target directly.
+
+**resourceId** (`string`): Resource ID for the memory thread. Use with \`threadId\` for thread-targeted signals.
+
+**threadId** (`string`): Thread ID to target. Use with \`resourceId\` for thread-targeted signals.
+
+**ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**ifIdle.streamOptions** (`Omit<AgentExecutionOptions, 'messages'>`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`.
+
+### `subscribeToThread()`
+
+Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendSignal()`.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+await subscription.processDataStream({
+  onChunk: async chunk => {
+    console.log(chunk)
+  },
+})
+```
+
+`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted.
+
+**resourceId** (`string`): Resource ID for the memory thread.
+
+**threadId** (`string`): Thread ID to subscribe to.
+
 ### `streamUntilIdle()`
 
 Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
@@ -161,7 +250,7 @@ const response = await agent.streamUntilIdle('Research solana for me', {
     thread: 'thread-1',
     resource: 'resource-1',
   },
-  maxIdleMs: 5 * 60_000,
+  maxIdleMs: 5 * 60_000, //optional
 })
 
 response.processDataStream({
@@ -173,6 +262,31 @@ response.processDataStream({
 })
 ```
 
+### `resumeStreamUntilIdle()`
+
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `resumeStream()`:
+
+```typescript
+const response = await agent.resumeStreamUntilIdle(
+  { approved: true, selectedOption: 'plan-b' },
+  {
+    memory: {
+      thread: 'thread-1',
+      resource: 'resource-1',
+    },
+    runId: 'run-123',
+    toolCallId: 'tool-call-456', // optional
+    maxIdleMs: 5 * 60_000, //optional
+  },
+)
+
+await response.processDataStream({
+  onChunk: chunk => {
+    console.log(chunk)
+  },
+})
+```
+
 The stream emits the same chunk types as `stream()`, plus `background-task-*` chunks for task lifecycle events. Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full server-side API and [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the payload shapes.
 
 ### `getTool()`