@mastra/mcp-docs-server 1.1.3 → 1.1.4

package/.docs/docs/memory/observational-memory.md

@@ -180,6 +180,8 @@ As the agent converses, message tokens accumulate. At regular intervals (`buffer
 
 When message tokens reach the `messageTokens` threshold, buffered chunks activate: their observations move into the active observation log, and the corresponding raw messages are removed from the context window. The agent never pauses.
 
+Buffered observations also include continuation hints — a suggested next response and the current task — so the main agent maintains conversational continuity after activation shrinks the context window.
+
 If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort.
 
 Reflection works similarly — the Reflector runs in the background when observations reach a fraction of the reflection threshold.

package/.docs/docs/streaming/tool-streaming.md

@@ -147,6 +147,12 @@ export const weatherTool = createTool({
 
 For detailed documentation on all lifecycle hooks, see the [createTool() reference](https://mastra.ai/reference/tools/create-tool).
 
+### Streaming tool input in UIs
+
+When a model generates a tool call, the arguments arrive incrementally as `tool-call-delta` stream chunks before the final `tool-call` chunk. UIs can listen for the corresponding `tool_input_start`, `tool_input_delta`, and `tool_input_end` events to render tool arguments as they stream in — for example, showing a file path or command immediately rather than waiting for the complete tool call.
+
+Using a partial JSON parser on the accumulated `argsTextDelta` fragments lets you extract usable argument values before the JSON is complete. This enables features like live diff previews for edit tools, streaming file content for write tools, and instant display of search patterns or file paths.
+
 ## Tool using an agent
 
 Pipe an agent's `fullStream` to the tool's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the tool run.

package/.docs/docs/workspace/filesystem.md

@@ -53,7 +53,27 @@ By default, `LocalFilesystem` runs in **contained mode** — all file operations
 
 In contained mode, absolute paths that fall within `basePath` are used as-is, while other absolute paths are treated as virtual paths relative to `basePath` (e.g. `/file.txt` resolves to `basePath/file.txt`). Any resolved path that escapes `basePath` throws a `PermissionError`.
 
-If your agent needs to access paths outside `basePath` (for example, global skills directories or user home folders), disable containment:
+If your agent needs to access specific paths outside `basePath`, use `allowedPaths` to grant access without disabling containment entirely:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+    allowedPaths: ['/home/user/.config', '/home/user/documents'],
+  }),
+});
+```
+
+Allowed paths can be updated at runtime using the `setAllowedPaths()` method:
+
+```typescript
+// Add a path dynamically
+workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents']);
+```
+
+This is the recommended approach for least-privilege access — the agent can only reach the specific directories you allow.
+
+If your agent needs unrestricted access to the entire filesystem, disable containment:
 
 ```typescript
 const workspace = new Workspace({

package/.docs/guides/deployment/digital-ocean.md

@@ -1,37 +1,22 @@
-# Digital Ocean
+# Deploy Mastra to Digital Ocean
 
-Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
+This guide covers Digital Ocean's App Platform and Droplets. Each of these offerings has its own set of strengths and is suited for different types of projects and developer expertise. Read [Digital Ocean's comparison](https://www.digitalocean.com/community/conceptual-articles/digitalocean-app-platform-vs-doks-vs-droplets) to understand the differences and choose the best option for your project.
 
-> **Note:** This guide assumes your Mastra application has been created using the default `npx create-mastra@latest` command. For more information on how to create a new Mastra application, refer to our [getting started guide](https://mastra.ai/guides/getting-started/quickstart)
+> **Info:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
 
-## Instructions
+## Before you begin
 
-**App Platform**:
+You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Digital Ocean](https://www.digitalocean.com/) account.
 
-### Prerequisites
-
-- A Git repository containing your Mastra application. This can be a [GitHub](https://github.com/) repository, [GitLab](https://gitlab.com/) repository, or any other compatible source provider.
-- A [Digital Ocean account](https://www.digitalocean.com/)
-
-### Deployment Steps
+The **App Platform** uses an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using [LibSQLStore](https://mastra.ai/reference/storage/libsql) with a file URL, switch to a remotely hosted database.
 
-1. Create a new App
+## App Platform
 
-   - Log in to your [Digital Ocean dashboard](https://cloud.digitalocean.com/).
-   - Navigate to the [App Platform](https://docs.digitalocean.com/products/app-platform/) service.
-   - Select your source provider and create a new app.
+After setting up your project, push it to your remote Git provider of choice (e.g. GitHub).
 
-2. Configure Deployment Source
+1. Follow the official [App Platform quickstart](https://docs.digitalocean.com/products/app-platform/getting-started/quickstart/#create-an-app). It'll guide you through connecting your repository, selecting the branch to deploy from, and configuring the source directory if necessary.
 
-   - Connect and select your repository. You may also choose a container image or a sample app.
-   - Select the branch you want to deploy from.
-   - Configure the source directory if necessary. If your Mastra application uses the default directory structure, no action is required here.
-   - Head to the next step.
-
-3. Configure Resource Settings and Environment Variables
-
-   - A Node.js build should be detected automatically.
-   - **Configure Build Command**: You need to add a custom build command for the app platform to build your Mastra project successfully. Set the build command based on your package manager:
+2. Make sure that a "Node.js" build is detected. You'll need to configure a build command. Set it based on your package manager:
 
    **npm**:
 
@@ -57,62 +42,29 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
    bun run build
    ```
 
-   - Add any required environment variables for your Mastra application. This includes API keys, database URLs, and other configuration values.
-   - You may choose to configure the size of your resource here.
-   - Other things you may optionally configure include, the region of your resource, the unique app name, and what project the resource belongs to.
-   - Once you're done, you may create the app after reviewing your configuration and pricing estimates.
-
-4. Deployment
-
-   - Your app will be built and deployed automatically.
-   - Digital Ocean will provide you with a URL to access your deployed application.
-
-You can now access your deployed application at the URL provided by Digital Ocean.
-
-> **Warning:** The Digital Ocean App Platform uses an ephemeral file system, meaning that any files written to the file system are short-lived and may be lost. Remove any usage of [LibSQLStore](https://mastra.ai/reference/storage/libsql) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
-
-**Droplets**:
-
-```bash
-npm run build
-```
-
-**Tab 3**:
+3. Add any required environment variables for your Mastra application. This includes API keys, database URLs, and other configuration values.
 
-```bash
-pnpm run build
-```
+4. Your app will be built and deployed automatically. Digital Ocean will provide you with a URL to access your deployed application.
 
-**Tab 4**:
+5. You can now call your Mastra endpoints over HTTP.
 
-```bash
-yarn build
-```
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
 
-**Tab 5**:
-
-```bash
-bun run build
-```
-
-**Tab 6**:
-
-Deploy your Mastra application to Digital Ocean's Droplets.
+## Droplets
 
 ### Prerequisites
 
-- A [Digital Ocean account](https://www.digitalocean.com/)
-- A [Droplet](https://docs.digitalocean.com/products/droplets/) running Ubuntu 24+
+- A Droplet running Ubuntu 24.04 LTS or later
 - A domain name with an A record pointing to your droplet
 - A reverse proxy configured (e.g., using [nginx](https://nginx.org/))
 - SSL certificate configured (e.g., using [Let's Encrypt](https://letsencrypt.org/))
 - Node.js 22.13.0 or later installed on your droplet
 
-### Deployment Steps
+### Deploy
 
-1. Clone your Mastra application
+After setting up your project, push it to your remote Git provider of choice (e.g. GitHub). Connect to your Droplet and make sure `git` is installed.
 
-   Connect to your Droplet and clone your repository:
+1. Clone your repository:
 
    **Public Repository**:
 
@@ -132,15 +84,33 @@ Deploy your Mastra application to Digital Ocean's Droplets.
    cd "<your-repository>"
    ```
 
-2. Install dependencies
+2. Install the project dependencies:
+
+   **npm**:
 
    ```bash
    npm install
    ```
 
-3. Set up environment variables
+   **pnpm**:
 
-   Create a `.env` file and add your environment variables:
+   ```bash
+   pnpm install
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn install
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun install
+   ```
+
+3. Set the required environment variables for your Mastra application. Create a `.env` file in the root of your project:
 
    ```bash
    touch .env
@@ -149,52 +119,50 @@ Deploy your Mastra application to Digital Ocean's Droplets.
    Edit the `.env` file and add your environment variables:
 
    ```bash
-   OPENAI_API_KEY=<your-openai-api-key>
-   # Add other required environment variables
+   OPENAI_API_KEY=your-api-key
    ```
 
-4. Build the application
+4. Build the project:
+
+   **npm**:
 
    ```bash
    npm run build
    ```
 
-5. Run the application
+   **pnpm**:
 
    ```bash
-   node --env-file=".env" .mastra/output/index.mjs
+   pnpm run build
    ```
 
-   > **Note:** Your Mastra application will run on port 4111 by default. Ensure your reverse proxy is configured to forward requests to this port.
+   **Yarn**:
 
-**Tab 7**:
+   ```bash
+   yarn build
+   ```
 
-```bash
-git clone https://github.com/<your-username>/<your-repository>.git
-```
+   **Bun**:
 
-**Tab 8**:
+   ```bash
+   bun run build
+   ```
 
-```bash
-git clone https://<your-username>:<your-personal-access-token>@github.com/<your-username>/<your-repository>.git
-```
+   This will create a production build of Mastra's server in the `.mastra/output` directory.
 
-## Connect to your Mastra server
+5. You can run the [Mastra Server](https://mastra.ai/docs/deployment/mastra-server) by running the `mastra start` command:
 
-You can now connect to your Mastra server from your client application using a `MastraClient` from the `@mastra/client-js` package.
+   ```bash
+   mastra start
+   ```
 
-Refer to the [`MastraClient` documentation](https://mastra.ai/docs/server/mastra-client) for more information.
+   > **Info:** Your Mastra application will run on port 4111 by default. Ensure your reverse proxy is configured to forward requests to this port.
 
-```typescript
-import { MastraClient } from "@mastra/client-js";
+6. You can now call your Mastra endpoints over HTTP.
 
-const mastraClient = new MastraClient({
-  baseUrl: "https://<your-domain-name>",
-});
-```
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
 
-## Next steps
+## Related
 
-- [Mastra Client SDK](https://mastra.ai/reference/client-js/mastra-client)
-- [Digital Ocean App Platform documentation](https://docs.digitalocean.com/products/app-platform/)
-- [Digital Ocean Droplets documentation](https://docs.digitalocean.com/products/droplets/)
+- [Digital Ocean App Platform](https://docs.digitalocean.com/products/app-platform/)
+- [Digital Ocean Droplets](https://docs.digitalocean.com/products/droplets/)

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

@@ -0,0 +1,645 @@
+# Harness Class
+
+**Added in:** `@mastra/core@1.1.0`
+
+The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
+
+## Usage example
+
+```typescript
+import { Harness } from '@mastra/core/harness';
+import { LibSQLStore } from '@mastra/libsql';
+import { z } from 'zod';
+
+const harness = new Harness({
+  id: 'my-coding-agent',
+  storage: new LibSQLStore({ url: 'file:./data.db' }),
+  stateSchema: z.object({
+    currentModelId: z.string().optional(),
+  }),
+  modes: [
+    { id: 'plan', name: 'Plan', default: true, agent: planAgent },
+    { id: 'build', name: 'Build', agent: buildAgent },
+  ],
+});
+
+harness.subscribe((event) => {
+  if (event.type === 'message_update') {
+    renderMessage(event.message);
+  }
+});
+
+await harness.init();
+await harness.selectOrCreateThread();
+await harness.sendMessage({ content: 'Hello!' });
+```
+
+## Constructor parameters
+
+**id:** (`string`): Unique identifier for this harness instance.
+
+**resourceId?:** (`string`): Resource ID for grouping threads (e.g., project identifier). Threads are scoped to this resource ID. Defaults to \`id\`.
+
+**storage?:** (`MastraCompositeStore`): Storage backend for persistence (threads, messages, state).
+
+**stateSchema?:** (`z.ZodObject`): Zod schema defining the shape of harness state. Used for validation and extracting defaults.
+
+**initialState?:** (`Partial<z.infer<TState>>`): Initial state values. Must conform to the schema if provided.
+
+**memory?:** (`MastraMemory`): Memory configuration shared across all modes. Propagated to mode agents that don't have their own memory.
+
+**modes:** (`HarnessMode[]`): Available agent modes. At least one mode is required. Each mode defines an agent and optional defaults.
+
+**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.
+
+**subagents?:** (`HarnessSubagent[]`): Subagent definitions. When provided, the harness creates a built-in \`subagent\` tool that parent agents can call to spawn focused subagents.
+
+**resolveModel?:** (`(modelId: string) => MastraLanguageModel`): Converts a model ID string (e.g., \`"anthropic/claude-sonnet-4"\`) to a language model instance. Used by subagents and observational memory model resolution.
+
+**omConfig?:** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
+
+**heartbeatHandlers?:** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
+
+**idGenerator?:** (`() => string`): Custom ID generator for threads, messages, and other entities. (Default: `timestamp + random string`)
+
+**modelAuthChecker?:** (`ModelAuthChecker`): Custom auth checker for model providers. Return \`true\`/\`false\` to override the default environment variable check, or \`undefined\` to fall back to defaults.
+
+**modelUseCountProvider?:** (`ModelUseCountProvider`): Provides per-model use counts for sorting and display in \`listAvailableModels()\`.
+
+**toolCategoryResolver?:** (`(toolName: string) => ToolCategory | null`): Maps tool names to permission categories (\`'read'\`, \`'edit'\`, \`'execute'\`, \`'mcp'\`, \`'other'\`). Used by the permission system to resolve category-level policies.
+
+**threadLock?:** (`{ acquire, release }`): Thread locking callbacks to prevent concurrent access from multiple processes. \`acquire\` should throw if the lock is held.
+
+### HarnessMode
+
+Each entry in the `modes` array configures a single agent mode.
+
+**id:** (`string`): Unique identifier for this mode (e.g., \`"plan"\`, \`"build"\`).
+
+**name?:** (`string`): Human-readable name for display.
+
+**default?:** (`boolean`): Whether this is the default mode when the harness starts. (Default: `false`)
+
+**defaultModelId?:** (`string`): Default model ID for this mode (e.g., \`"anthropic/claude-sonnet-4-20250514"\`). Used when no per-mode model has been explicitly selected.
+
+**color?:** (`string`): Hex color for the mode indicator (e.g., \`"#7c3aed"\`).
+
+**agent:** (`Agent | ((state) => Agent)`): The agent for this mode. It can be a static Agent instance or a function that receives harness state and returns an Agent.
+
+### HarnessSubagent
+
+Each entry in the `subagents` array defines a subagent the harness can spawn.
+
+**id:** (`string`): Unique identifier for this subagent type (e.g., \`"explore"\`, \`"execute"\`).
+
+**name:** (`string`): Human-readable name shown in tool output.
+
+**description:** (`string`): Description of what this subagent does. Used in the auto-generated tool description.
+
+**instructions:** (`string`): System prompt for this subagent.
+
+**tools?:** (`ToolsInput`): Tools this subagent has direct access to.
+
+**allowedHarnessTools?:** (`string[]`): Tool IDs from the harness's shared \`tools\` config. Merged with \`tools\` above to let subagents use a subset of harness tools.
+
+**defaultModelId?:** (`string`): Default model ID for this subagent type.
+
+## Properties
+
+**id:** (`string`): Harness identifier, set at construction.
+
+## Methods
+
+### Lifecycle
+
+#### `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.
+
+```typescript
+await harness.init();
+```
+
+#### `selectOrCreateThread()`
+
+Select the most recent thread for the current resource, or create one if none exist. Loads thread metadata and acquires a thread lock.
+
+```typescript
+const thread = await harness.selectOrCreateThread();
+```
+
+#### `destroy()`
+
+Stop all heartbeat handlers and clean up resources.
+
+```typescript
+await harness.destroy();
+```
+
+### State
+
+#### `getState()`
+
+Return a read-only snapshot of the current harness state.
+
+```typescript
+const state = harness.getState();
+```
+
+#### `setState(updates)`
+
+Update the harness state. Validates against `stateSchema` if provided, and emits a `state_changed` event with the new state and changed keys.
+
+```typescript
+await harness.setState({ currentModelId: 'anthropic/claude-sonnet-4-20250514' });
+```
+
+### Modes
+
+#### `listModes()`
+
+Return all configured `HarnessMode` instances.
+
+```typescript
+const modes = harness.listModes();
+```
+
+#### `getCurrentModeId()`
+
+Return the ID of the currently active mode.
+
+```typescript
+const modeId = harness.getCurrentModeId();
+```
+
+#### `getCurrentMode()`
+
+Return the `HarnessMode` object for the current mode.
+
+```typescript
+const mode = harness.getCurrentMode();
+```
+
+#### `switchMode({ modeId })`
+
+Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events.
+
+```typescript
+await harness.switchMode({ modeId: 'build' });
+```
+
+### Models
+
+#### `getCurrentModelId()`
+
+Return the ID of the currently selected model from state.
+
+```typescript
+const modelId = harness.getCurrentModelId();
+```
+
+#### `getModelName()`
+
+Return a short display name from the current model ID. For example, `"claude-sonnet-4"` from `"anthropic/claude-sonnet-4"`.
+
+```typescript
+const name = harness.getModelName();
+```
+
+#### `getFullModelId()`
+
+Return the complete model ID string.
+
+```typescript
+const fullId = harness.getFullModelId();
+```
+
+#### `hasModelSelected()`
+
+Check if a model ID is currently selected.
+
+```typescript
+if (harness.hasModelSelected()) {
+  // Ready to send messages
+}
+```
+
+#### `switchModel({ modelId, scope?, modeId? })`
+
+Switch the active model. When `scope` is `'thread'`, the model ID is persisted to thread metadata so it's restored when switching back. Emits a `model_changed` event.
+
+```typescript
+// Set for current session only
+await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-20250514' });
+
+// Persist to the current thread
+await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-20250514', scope: 'thread' });
+```
+
+#### `getCurrentModelAuthStatus()`
+
+Check if the current model's provider has authentication configured. Uses `modelAuthChecker` if provided, falling back to environment variable checks from the provider registry.
+
+```typescript
+const status = await harness.getCurrentModelAuthStatus();
+// { hasAuth: true, apiKeyEnvVar: 'ANTHROPIC_API_KEY' }
+```
+
+#### `listAvailableModels()`
+
+Retrieve all available models from the provider registry, including their authentication status and use counts.
+
+```typescript
+const models = await harness.listAvailableModels();
+// [{ id, provider, modelName, hasApiKey, apiKeyEnvVar, useCount }]
+```
+
+### Threads
+
+#### `getCurrentThreadId()`
+
+Return the ID of the currently active thread.
+
+```typescript
+const threadId = harness.getCurrentThreadId();
+```
+
+#### `createThread({ title? })`
+
+Create a new thread. Initializes thread metadata, saves it to storage, acquires a thread lock, and emits a `thread_created` event.
+
+```typescript
+const thread = await harness.createThread({ title: 'New conversation' });
+```
+
+#### `switchThread({ threadId })`
+
+Switch to a different thread. Aborts any in-progress operations, acquires a lock on the new thread, releases the lock on the previous thread, loads the thread's metadata, and emits a `thread_changed` event.
+
+```typescript
+await harness.switchThread({ threadId: 'thread-abc123' });
+```
+
+#### `listThreads(options?)`
+
+List threads from storage. By default, only threads for the current resource are returned.
+
+```typescript
+// List threads for current resource
+const threads = await harness.listThreads();
+
+// List all threads across resources
+const allThreads = await harness.listThreads({ allResources: true });
+```
+
+#### `renameThread({ title })`
+
+Update the title of the current thread.
+
+```typescript
+await harness.renameThread({ title: 'Updated title' });
+```
+
+#### `getResourceId()`
+
+Return the current resource ID.
+
+```typescript
+const resourceId = harness.getResourceId();
+```
+
+#### `setResourceId({ resourceId })`
+
+Set the resource ID and clear the current thread.
+
+```typescript
+harness.setResourceId({ resourceId: 'project-xyz' });
+```
+
+#### `getSession()`
+
+Return current session information including thread ID, mode ID, and the list of threads.
+
+```typescript
+const session = await harness.getSession();
+// { currentThreadId, currentModeId, threads }
+```
+
+### Messages
+
+#### `sendMessage({ content, images? })`
+
+Send a message to the current agent. Creates a thread if none exists, builds a `RequestContext` and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically.
+
+```typescript
+await harness.sendMessage({ content: 'Explain the authentication flow' });
+```
+
+#### `listMessages(options?)`
+
+Retrieve messages for the current thread.
+
+```typescript
+const messages = await harness.listMessages();
+
+// Limit to the last 50 messages
+const recent = await harness.listMessages({ limit: 50 });
+```
+
+#### `listMessagesForThread({ threadId, limit? })`
+
+Retrieve messages for a specific thread.
+
+```typescript
+const messages = await harness.listMessagesForThread({ threadId: 'thread-abc123' });
+```
+
+#### `getFirstUserMessageForThread({ threadId })`
+
+Retrieve the first user message for a given thread.
+
+```typescript
+const firstMsg = await harness.getFirstUserMessageForThread({ threadId: 'thread-abc123' });
+```
+
+### Flow control
+
+#### `abort()`
+
+Abort any in-progress generation.
+
+```typescript
+harness.abort();
+```
+
+#### `steer({ content })`
+
+Steer the agent mid-stream by injecting an instruction into the current generation.
+
+```typescript
+harness.steer({ content: 'Focus on security implications' });
+```
+
+#### `followUp({ content })`
+
+Queue a follow-up message to be sent after the current generation completes. If no operation is running, sends the message immediately.
+
+```typescript
+harness.followUp({ content: 'Now apply those changes' });
+```
+
+### Tool approvals
+
+#### `respondToToolApproval({ decision })`
+
+Respond to a pending tool approval request. Called when a `tool_approval_required` event is received.
+
+```typescript
+harness.respondToToolApproval({ decision: 'approve' });
+harness.respondToToolApproval({ decision: 'decline' });
+```
+
+### Questions and plans
+
+#### `respondToQuestion({ questionId, answer })`
+
+Respond to a pending question from the `ask_user` built-in tool.
+
+```typescript
+harness.respondToQuestion({ questionId: 'q-123', answer: 'Yes, proceed with the refactor' });
+```
+
+#### `respondToPlanApproval({ planId, response })`
+
+Respond to a pending plan approval from the `submit_plan` built-in tool. The `response` object contains `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.
+
+```typescript
+harness.respondToPlanApproval({ planId: 'plan-123', response: { action: 'approved' } });
+harness.respondToPlanApproval({ planId: 'plan-123', response: { action: 'rejected', feedback: 'Needs more detail' } });
+```
+
+### Permissions
+
+#### `grantSessionCategory({ category })`
+
+Grant a tool category for the current session. Tools in this category are auto-approved without prompting.
+
+```typescript
+harness.grantSessionCategory({ category: 'edit' });
+```
+
+#### `grantSessionTool({ toolName })`
+
+Grant a specific tool for the current session.
+
+```typescript
+harness.grantSessionTool({ toolName: 'mastra_workspace_execute_command' });
+```
+
+#### `getSessionGrants()`
+
+Return currently granted session categories and tools.
+
+```typescript
+const grants = harness.getSessionGrants();
+// { categories: Set<string>, tools: Set<string> }
+```
+
+#### `setPermissionForCategory({ category, policy })`
+
+Set the permission policy for a tool category.
+
+```typescript
+harness.setPermissionForCategory({ category: 'execute', policy: 'ask' });
+```
+
+#### `setPermissionForTool({ toolName, policy })`
+
+Set the permission policy for a specific tool. Per-tool policies take precedence over category policies.
+
+```typescript
+harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' });
+```
+
+#### `getPermissionRules()`
+
+Return the current permission rules.
+
+```typescript
+const rules = harness.getPermissionRules();
+// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }
+```
+
+#### `getToolCategory({ toolName })`
+
+Resolve a tool's category using the configured `toolCategoryResolver`.
+
+```typescript
+const category = harness.getToolCategory({ toolName: 'mastra_workspace_write_file' });
+// 'edit'
+```
+
+### Observational memory
+
+#### `loadOMProgress()`
+
+Load observational memory records for the current thread and emit an `om_status` event with reconstructed progress.
+
+```typescript
+await harness.loadOMProgress();
+```
+
+#### `getObserverModelId()`
+
+Return the observer model ID from state or the default from `omConfig`.
+
+```typescript
+const modelId = harness.getObserverModelId();
+```
+
+#### `getReflectorModelId()`
+
+Return the reflector model ID from state or the default from `omConfig`.
+
+```typescript
+const modelId = harness.getReflectorModelId();
+```
+
+#### `switchObserverModel({ modelId })`
+
+Switch the observer model. Persists the setting to thread metadata and emits an `om_model_changed` event.
+
+```typescript
+await harness.switchObserverModel({ modelId: 'anthropic/claude-haiku-3.5' });
+```
+
+#### `switchReflectorModel({ modelId })`
+
+Switch the reflector model. Persists the setting to thread metadata and emits an `om_model_changed` event.
+
+```typescript
+await harness.switchReflectorModel({ modelId: 'anthropic/claude-haiku-3.5' });
+```
+
+#### `getObservationThreshold()`
+
+Return the observation threshold in tokens from state or the default from `omConfig`.
+
+```typescript
+const threshold = harness.getObservationThreshold();
+```
+
+#### `getReflectionThreshold()`
+
+Return the reflection threshold in tokens from state or the default from `omConfig`.
+
+```typescript
+const threshold = harness.getReflectionThreshold();
+```
+
+### Subagents
+
+#### `getSubagentModelId({ agentType? })`
+
+Retrieve the subagent model ID. Prioritizes per-type settings over the global setting.
+
+```typescript
+const modelId = harness.getSubagentModelId({ agentType: 'explore' });
+```
+
+#### `setSubagentModelId({ modelId, agentType? })`
+
+Set the subagent model ID. Pass an `agentType` to set a per-type override, or omit it to set the global default. Persists to thread settings and emits a `subagent_model_changed` event.
+
+```typescript
+// Set global subagent model
+await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-20250514' });
+
+// Set per-type model
+await harness.setSubagentModelId({ modelId: 'anthropic/claude-haiku-3.5', agentType: 'explore' });
+```
+
+### Events
+
+#### `subscribe(listener)`
+
+Register an event listener. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = harness.subscribe((event) => {
+  switch (event.type) {
+    case 'message_update':
+      renderMessage(event.message);
+      break;
+    case 'tool_approval_required':
+      showApprovalPrompt(event.toolName);
+      break;
+    case 'error':
+      console.error(event.error);
+      break;
+  }
+});
+
+// Later:
+unsubscribe();
+```
+
+## Events
+
+The harness emits events through registered listeners. The following table lists the available event types:
+
+| Event type                 | Description                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `mode_changed`             | The active mode changed.                                            |
+| `model_changed`            | The active model changed.                                           |
+| `thread_changed`           | The active thread changed.                                          |
+| `thread_created`           | A new thread was created.                                           |
+| `state_changed`            | Harness state was updated.                                          |
+| `agent_start`              | The agent started processing.                                       |
+| `agent_end`                | The agent finished processing.                                      |
+| `message_start`            | A new message started streaming.                                    |
+| `message_update`           | A message was updated with new content.                             |
+| `message_end`              | A message finished streaming.                                       |
+| `tool_start`               | A tool call started.                                                |
+| `tool_approval_required`   | A tool call requires user approval.                                 |
+| `tool_update`              | A tool call was updated with progress.                              |
+| `tool_end`                 | A tool call finished.                                               |
+| `tool_input_start`         | Tool input started streaming.                                       |
+| `tool_input_delta`         | Tool input received a streaming delta.                              |
+| `tool_input_end`           | Tool input finished streaming.                                      |
+| `usage_update`             | Token usage was updated.                                            |
+| `error`                    | An error occurred.                                                  |
+| `info`                     | An informational message was emitted.                               |
+| `follow_up_queued`         | A follow-up message was queued.                                     |
+| `workspace_status_changed` | The workspace status changed.                                       |
+| `workspace_ready`          | The workspace finished initializing.                                |
+| `workspace_error`          | The workspace encountered an error.                                 |
+| `om_status`                | Observational memory status update.                                 |
+| `om_observation_start`     | An observation started.                                             |
+| `om_observation_end`       | An observation completed.                                           |
+| `om_reflection_start`      | A reflection started.                                               |
+| `om_reflection_end`        | A reflection completed.                                             |
+| `ask_question`             | The agent asked a question via the `ask_user` tool.                 |
+| `plan_approval_required`   | The agent submitted a plan for approval via the `submit_plan` tool. |
+| `plan_approved`            | A plan was approved.                                                |
+| `subagent_start`           | A subagent started processing.                                      |
+| `subagent_text_delta`      | A subagent emitted a text delta.                                    |
+| `subagent_tool_start`      | A subagent started a tool call.                                     |
+| `subagent_tool_end`        | A subagent finished a tool call.                                    |
+| `subagent_end`             | A subagent finished processing.                                     |
+| `subagent_model_changed`   | A subagent's model changed.                                         |
+| `task_updated`             | A task list was updated.                                            |
+
+## Built-in tools
+
+The harness provides built-in tools to agents in every mode:
+
+| Tool          | Description                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `ask_user`    | Ask the user a question and wait for their response.                                             |
+| `submit_plan` | Submit a plan for user review and approval.                                                      |
+| `task_write`  | Create or update a structured task list for tracking progress.                                   |
+| `task_check`  | Check the completion status of the current task list.                                            |
+| `subagent`    | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). |

package/.docs/reference/index.md

@@ -194,6 +194,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [WorkspaceFilesystem](https://mastra.ai/reference/workspace/filesystem)
 - [WorkspaceSandbox](https://mastra.ai/reference/workspace/sandbox)
+- [Harness Class](https://mastra.ai/reference/harness/harness-class)
 - [.stream()](https://mastra.ai/reference/streaming/agents/stream)
 - [.streamLegacy()](https://mastra.ai/reference/streaming/agents/streamLegacy)
 - [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput)

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

@@ -36,7 +36,7 @@ export const agent = new Agent({
 
 ### Options parameters
 
-**lastMessages?:** (`number | false`): Number of most recent messages to retrieve. Set to false to disable. (Default: `10`)
+**lastMessages?:** (`number | false`): Number of most recent messages to include in context. Set to \`false\` to disable loading conversation history into context. Use \`Number.MAX\_SAFE\_INTEGER\` to retrieve all messages with no limit. To prevent saving new messages, use the \`readOnly\` option instead. (Default: `10`)
 
 **readOnly?:** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory. (Default: `false`)
 

package/.docs/reference/memory/observational-memory.md

@@ -221,6 +221,7 @@ Default settings:
 
 - `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
 - `observation.bufferActivation: 0.8` — on activation, remove enough messages to keep only 20% of the threshold remaining
+- Buffered observations include continuation hints (`suggestedResponse`, `currentTask`) that survive activation to maintain conversational continuity
 - `reflection.bufferActivation: 0.5` — start background reflection at 50% of observation threshold
 
 To customize:

package/.docs/reference/workspace/local-filesystem.md

@@ -36,6 +36,10 @@ const response = await agent.generate('List all files in the workspace');
 
 **id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
 
+**contained?:** (`boolean`): When true, all file operations are restricted to stay within basePath. Prevents path traversal attacks and symlink escapes. See \[containment]\(/docs/workspace/filesystem#containment). (Default: `true`)
+
+**allowedPaths?:** (`string[]`): Additional absolute paths that are allowed beyond basePath. Useful with \`contained: true\` to grant access to specific directories without disabling containment entirely. Paths are resolved to absolute paths. (Default: `[]`)
+
 **readOnly?:** (`boolean`): When true, all write operations are blocked. Read operations are still allowed. (Default: `false`)
 
 ## Properties
@@ -50,6 +54,8 @@ const response = await agent.generate('List all files in the workspace');
 
 **readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
 
+**allowedPaths:** (`readonly string[]`): Current set of additional allowed paths (absolute, resolved). These paths are permitted beyond basePath when containment is enabled.
+
 ## Methods
 
 ### `init()`
@@ -76,6 +82,25 @@ await filesystem.destroy();
 
 Called by `workspace.destroy()`.
 
+### `setAllowedPaths(pathsOrUpdater)`
+
+Update the allowed paths at runtime. Accepts a new paths array (replaces current) or an updater callback that receives the current paths and returns the new set.
+
+```typescript
+// Set directly
+filesystem.setAllowedPaths(['/home/user/.config']);
+
+// Update with callback
+filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents']);
+
+// Clear all allowed paths
+filesystem.setAllowedPaths([]);
+```
+
+**Parameters:**
+
+**pathsOrUpdater:** (`string[] | ((current: readonly string[]) => string[])`): New allowed paths array or updater function receiving current paths
+
 ### `readFile(path, options?)`
 
 Read file contents.

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

@@ -176,22 +176,6 @@ const context = workspace.getPathContext();
 // { filesystem?, sandbox?, instructions }
 ```
 
-**Returns:** `PathContext`
-
-```typescript
-interface PathContext {
-  filesystem?: {
-    provider: string;
-    basePath?: string;
-  };
-  sandbox?: {
-    provider: string;
-    workingDirectory?: string;
-  };
-  instructions: string;
-}
-```
-
 The `instructions` field contains provider-generated descriptions combined from the filesystem and sandbox. These instructions are included in tool descriptions to help agents understand the execution context.
 
 #### `getToolsConfig()`
@@ -239,11 +223,4 @@ Added when BM25 or vector search is configured:
 | `mastra_workspace_search` | Search indexed content using keyword (BM25), semantic (vector), or hybrid search. Returns ranked results with scores. |
 | `mastra_workspace_index`  | Index content for search. Associates content with a path for later retrieval.                                         |
 
-The `index` tool is excluded when the filesystem is in read-only mode.
-
-## Related
-
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
-- [Search and indexing](https://mastra.ai/docs/workspace/search)
-- [Filesystem reference](https://mastra.ai/reference/workspace/filesystem)
-- [Sandbox reference](https://mastra.ai/reference/workspace/sandbox)
+The `index` tool is excluded when the filesystem is in read-only mode.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.4
+
+### Patch Changes
+
+- Updated dependencies [[`0d9efb4`](https://github.com/mastra-ai/mastra/commit/0d9efb47992c34aa90581c18b9f51f774f6252a5), [`5caa13d`](https://github.com/mastra-ai/mastra/commit/5caa13d1b2a496e2565ab124a11de9a51ad3e3b9), [`940163f`](https://github.com/mastra-ai/mastra/commit/940163fc492401d7562301e6f106ccef4fefe06f), [`47892c8`](https://github.com/mastra-ai/mastra/commit/47892c85708eac348209f99f10f9a5f5267e11c0), [`45bb78b`](https://github.com/mastra-ai/mastra/commit/45bb78b70bd9db29678fe49476cd9f4ed01bfd0b), [`70eef84`](https://github.com/mastra-ai/mastra/commit/70eef84b8f44493598fdafa2980a0e7283415eda), [`d84e52d`](https://github.com/mastra-ai/mastra/commit/d84e52d0f6511283ddd21ed5fe7f945449d0f799), [`24b80af`](https://github.com/mastra-ai/mastra/commit/24b80af87da93bb84d389340181e17b7477fa9ca), [`608e156`](https://github.com/mastra-ai/mastra/commit/608e156def954c9604c5e3f6d9dfce3bcc7aeab0), [`2b2e157`](https://github.com/mastra-ai/mastra/commit/2b2e157a092cd597d9d3f0000d62b8bb4a7348ed), [`59d30b5`](https://github.com/mastra-ai/mastra/commit/59d30b5d0cb44ea7a1c440e7460dfb57eac9a9b5), [`453693b`](https://github.com/mastra-ai/mastra/commit/453693bf9e265ddccecef901d50da6caaea0fbc6), [`78d1c80`](https://github.com/mastra-ai/mastra/commit/78d1c808ad90201897a300af551bcc1d34458a20), [`c204b63`](https://github.com/mastra-ai/mastra/commit/c204b632d19e66acb6d6e19b11c4540dd6ad5380), [`742a417`](https://github.com/mastra-ai/mastra/commit/742a417896088220a3b5560c354c45c5ca6d88b9)]:
+  - @mastra/core@1.6.0
+
+## 1.1.4-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`0d9efb4`](https://github.com/mastra-ai/mastra/commit/0d9efb47992c34aa90581c18b9f51f774f6252a5), [`5caa13d`](https://github.com/mastra-ai/mastra/commit/5caa13d1b2a496e2565ab124a11de9a51ad3e3b9), [`940163f`](https://github.com/mastra-ai/mastra/commit/940163fc492401d7562301e6f106ccef4fefe06f), [`b260123`](https://github.com/mastra-ai/mastra/commit/b2601234bd093d358c92081a58f9b0befdae52b3), [`47892c8`](https://github.com/mastra-ai/mastra/commit/47892c85708eac348209f99f10f9a5f5267e11c0), [`45bb78b`](https://github.com/mastra-ai/mastra/commit/45bb78b70bd9db29678fe49476cd9f4ed01bfd0b), [`70eef84`](https://github.com/mastra-ai/mastra/commit/70eef84b8f44493598fdafa2980a0e7283415eda), [`d84e52d`](https://github.com/mastra-ai/mastra/commit/d84e52d0f6511283ddd21ed5fe7f945449d0f799), [`24b80af`](https://github.com/mastra-ai/mastra/commit/24b80af87da93bb84d389340181e17b7477fa9ca), [`608e156`](https://github.com/mastra-ai/mastra/commit/608e156def954c9604c5e3f6d9dfce3bcc7aeab0), [`2b2e157`](https://github.com/mastra-ai/mastra/commit/2b2e157a092cd597d9d3f0000d62b8bb4a7348ed), [`59d30b5`](https://github.com/mastra-ai/mastra/commit/59d30b5d0cb44ea7a1c440e7460dfb57eac9a9b5), [`453693b`](https://github.com/mastra-ai/mastra/commit/453693bf9e265ddccecef901d50da6caaea0fbc6), [`78d1c80`](https://github.com/mastra-ai/mastra/commit/78d1c808ad90201897a300af551bcc1d34458a20), [`c204b63`](https://github.com/mastra-ai/mastra/commit/c204b632d19e66acb6d6e19b11c4540dd6ad5380), [`742a417`](https://github.com/mastra-ai/mastra/commit/742a417896088220a3b5560c354c45c5ca6d88b9)]:
+  - @mastra/core@1.6.0-alpha.0
+
 ## 1.1.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,15 +29,15 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^3.25.76",
-    "@mastra/core": "1.5.0",
+    "@mastra/core": "1.6.0",
     "@mastra/mcp": "^1.0.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.9",
     "@types/jsdom": "^21.1.7",
     "@types/node": "22.19.7",
-    "@vitest/coverage-v8": "4.0.12",
-    "@vitest/ui": "4.0.12",
+    "@vitest/coverage-v8": "4.0.18",
+    "@vitest/ui": "4.0.18",
     "@wong2/mcp-cli": "^1.13.0",
     "cross-env": "^10.1.0",
     "eslint": "^9.37.0",
@@ -45,10 +45,10 @@
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "4.0.16",
-    "@internal/lint": "0.0.60",
-    "@internal/types-builder": "0.0.35",
-    "@mastra/core": "1.5.0"
+    "vitest": "4.0.18",
+    "@internal/lint": "0.0.61",
+    "@internal/types-builder": "0.0.36",
+    "@mastra/core": "1.6.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {