@mastra/mcp-docs-server 1.1.42 → 1.1.43-alpha.0

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

@@ -0,0 +1,228 @@
+# AcpAgent class
+
+The `AcpAgent` class wraps an Agent Client Protocol (ACP)-compatible coding agent as a Mastra subagent. Use it when a parent Mastra agent should delegate repository inspection, code edits, or other ACP-backed tasks to a named subagent.
+
+If you want the parent agent to call the ACP agent as a tool instead, use [`createACPTool()`](https://mastra.ai/reference/acp/create-acp-tool).
+
+## Usage example
+
+Register an ACP-compatible coding agent in a parent agent's `agents` map:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  description: 'An ACP-compatible coding agent that can inspect and edit files',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Delegate code editing tasks to the code-agent subagent.',
+  model: 'openai/gpt-5.5',
+  agents: {
+    codeAgent,
+  },
+})
+```
+
+For Claude Code, ACP support is provided by the `@agentclientprotocol/claude-agent-acp` bridge package. Configure the ACP agent command to run the bridge, then select a Claude model after session creation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const claudeCodeAgent = new AcpAgent({
+  id: 'claude-code-agent',
+  name: 'Claude Code Agent',
+  description: 'Use Claude Code through ACP.',
+  command: 'npx',
+  args: ['@agentclientprotocol/claude-agent-acp'],
+  cwd: process.cwd(),
+  model: 'claude-sonnet-4-6',
+})
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the subagent.
+
+**name** (`string`): Display name used during agent delegation. Defaults to \`id\`.
+
+**description** (`string`): Description shown to the model when it can delegate to this subagent.
+
+**command** (`string`): ACP agent executable to spawn.
+
+**args** (`string[]`): Arguments passed to the ACP agent executable. (Default: `[]`)
+
+**env** (`Record<string, string>`): Environment variables to merge with the current process environment when spawning the ACP process.
+
+**cwd** (`string`): Working directory for the ACP process and ACP session. Also used as the default local filesystem base path. (Default: `process.cwd()`)
+
+**session** (`Partial<NewSessionRequest>`): ACP session creation options. Defaults to \`cwd\` or \`process.cwd()\` and an empty MCP server list.
+
+**initialize** (`Partial<InitializeRequest>`): ACP initialization options. Defaults to Mastra client information, the current ACP protocol version, and read/write filesystem capabilities.
+
+**authMethodId** (`string`): ACP authentication method ID to invoke after initialization and before session creation.
+
+**persistSession** (`boolean`): Whether to keep the ACP process and session alive after each prompt. Set to \`false\` to stop the process after each prompt completes. (Default: `true`)
+
+**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
+
+**workspace** (`Workspace`): Workspace used for ACP file read and write requests. Defaults to a \`Workspace\` backed by \`LocalFilesystem\` at \`cwd\` or \`process.cwd()\`.
+
+**model** (`ModelId`): Model ID to select after ACP session creation using the ACP \`session/set\_model\` method.
+
+## Properties
+
+**id** (`TId`): Readonly subagent identifier from the constructor options.
+
+**name** (`string`): Readonly display name for this subagent.
+
+**description** (`string`): Readonly description shown when the parent agent can delegate to this subagent.
+
+**connection** (`ACPConnection`): Readonly ACP connection used to start the agent process, create sessions, send prompts, stream updates, and manage models.
+
+## Methods
+
+### Generation
+
+#### `generate(messages, options?)`
+
+Sends the prompt to the ACP agent, buffers text chunks from the ACP response, and returns a Mastra subagent generate result.
+
+```typescript
+const result = await codeAgent.generate('Inspect the repository and summarize the test setup')
+
+console.log(result.text)
+```
+
+#### `stream(messages, options?)`
+
+Sends the prompt to the ACP agent and returns a Mastra subagent stream result. ACP `agent_message_chunk` updates are emitted as Mastra `text-delta` chunks.
+
+```typescript
+const result = await codeAgent.stream('Refactor the selected module and explain each change')
+
+for await (const chunk of result.fullStream) {
+  if (chunk.type === 'text-delta') {
+    process.stdout.write(chunk.payload.text)
+  }
+}
+```
+
+`resumeGenerate()` and `resumeStream()` are not supported and throw an error when called.
+
+### Model management
+
+#### `getAvailableModels()`
+
+Starts the ACP process if needed and returns the model list advertised by the ACP session.
+
+```typescript
+const models = await codeAgent.getAvailableModels()
+// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]
+```
+
+#### `setModel(modelId)`
+
+Selects a model for the active ACP session. If the ACP agent advertises available models, the model ID must match one of them.
+
+```typescript
+await codeAgent.setModel('claude-sonnet-4-6')
+```
+
+## Session lifecycle
+
+`AcpAgent` starts the configured `command` on first use, initializes the ACP client, and creates an ACP session. By default, `persistSession` is `true`, so the process and session stay alive across `generate()`, `stream()`, `getAvailableModels()`, and `setModel()` calls.
+
+Set `persistSession: false` when each prompt should run in a fresh ACP process:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run one isolated ACP coding task',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+  persistSession: false,
+})
+```
+
+With `persistSession: false`, `@mastra/acp` stops the ACP process after each prompt completes.
+
+## Workspace integration
+
+ACP file operations go through Mastra's `Workspace` abstraction. If you do not pass `workspace`, `@mastra/acp` creates a `Workspace` backed by `LocalFilesystem` and uses `cwd` or `process.cwd()` as the filesystem base path.
+
+Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: process.cwd(),
+  }),
+})
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run coding tasks in a controlled workspace',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  workspace,
+})
+```
+
+Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `AcpAgent` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+Pass `onPermissionRequest` to inspect the request and return your own permission response:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Related
+
+- [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)
+- [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
+- [Agent reference](https://mastra.ai/reference/agents/agent)
+- [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/reference/acp/create-acp-tool.md

@@ -0,0 +1,131 @@
+# createACPTool()
+
+The `createACPTool()` function creates a Mastra tool that sends a `task` string to an Agent Client Protocol (ACP)-compatible coding agent and returns the final ACP response as `output`. Use it when a parent agent should decide when to call the ACP agent as a tool.
+
+If you want to register the ACP agent as a Mastra subagent instead, use the [`AcpAgent` class](https://mastra.ai/reference/acp/acp-agent).
+
+## Usage example
+
+Create a code editing tool and register it on a parent agent:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent to inspect and edit code',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
+  model: 'openai/gpt-5.5',
+  tools: {
+    codeAgentTool,
+  },
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for the Mastra tool.
+
+**description** (`string`): Description shown to the model when it can call this tool.
+
+**command** (`string`): ACP agent executable to spawn.
+
+**args** (`string[]`): Arguments passed to the ACP agent executable. (Default: `[]`)
+
+**env** (`Record<string, string>`): Environment variables to merge with the current process environment when spawning the ACP process.
+
+**cwd** (`string`): Working directory for the ACP process and ACP session. Also used as the default local filesystem base path. (Default: `process.cwd()`)
+
+**session** (`Partial<NewSessionRequest>`): ACP session creation options. Defaults to \`cwd\` or \`process.cwd()\` and an empty MCP server list.
+
+**initialize** (`Partial<InitializeRequest>`): ACP initialization options. Defaults to Mastra client information, the current ACP protocol version, and read/write filesystem capabilities.
+
+**authMethodId** (`string`): ACP authentication method ID to invoke after initialization and before session creation.
+
+**persistSession** (`boolean`): Whether the ACP connection created for a tool execution disconnects after the prompt. Set to \`false\` to stop the process after each prompt completes. (Default: `true`)
+
+**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
+
+**workspace** (`Workspace`): Workspace option from the shared ACP connection options. During tool execution, \`createACPTool()\` passes the current Mastra workspace from the execution context when one is available; otherwise the ACP connection falls back to a local filesystem workspace. Use \`AcpAgent\` when you need to provide an explicit workspace instance.
+
+**model** (`ModelId`): Model ID to select after ACP session creation using the ACP \`session/set\_model\` method.
+
+## Input schema
+
+**task** (`string`): The task to send to the ACP agent.
+
+## Output schema
+
+**output** (`string`): The final text output returned by the ACP agent.
+
+## Suspend and resume schema
+
+`createACPTool()` defines suspend and resume schemas for permission request payloads. Permission decisions are returned through `onPermissionRequest`; by default, `@mastra/acp` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+### Suspend payload
+
+**permissionRequest** (`{ title: string; options: { optionId: string; name: string }[] }`): Permission request title and selectable options returned by the ACP agent.
+
+### Resume payload
+
+**optionId** (`string`): Permission option ID to select when resuming with \`outcome: "selected"\`.
+
+**outcome** (`"selected" | "cancelled"`): Permission decision used to continue or cancel the ACP request.
+
+## Session lifecycle
+
+Each tool execution creates an ACP connection, starts the configured `command`, initializes the ACP client, creates an ACP session, and sends the `task` with ACP `session/prompt`.
+
+By default, `persistSession` is `true` for the ACP connection created during tool execution. Set `persistSession: false` when the ACP process should stop as soon as that prompt completes.
+
+Use [`AcpAgent`](https://mastra.ai/reference/acp/acp-agent) when you need a reusable ACP subagent instance with explicit session lifecycle control across calls.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `@mastra/acp` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+Pass `onPermissionRequest` to inspect the request and return your own permission response:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+
+export const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Related
+
+- [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)
+- [AcpAgent class reference](https://mastra.ai/reference/acp/acp-agent)
+- [Tool reference](https://mastra.ai/reference/tools/create-tool)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

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

@@ -141,7 +141,7 @@ The model receives this as:
 <user name="Devin" from="slack">Can we simplify the API surface?</user>
 ```
 
-The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
+The UI sees the message contents and can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
 
 ### `sendMessage(message, options)`
 
@@ -196,6 +196,54 @@ Sends a signal to an active run or memory thread.
 
 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.
 
+### `sendNotificationSignal(notification, options)`
+
+Creates or coalesces a notification inbox record, resolves the notification delivery policy, and sends a notification signal when the decision is immediate.
+
+```typescript
+const result = await agent.sendNotificationSignal(
+  {
+    source: 'github',
+    kind: 'ci-status',
+    priority: 'high',
+    summary: 'CI failed on main: 3 tests failed.',
+    dedupeKey: 'github:acme/app:main:ci',
+  },
+  {
+    resourceId: 'user-123',
+    threadId: 'thread-abc',
+  },
+)
+```
+
+**notification.source** (`string`): External system that produced the notification, such as \`github\`, \`slack\`, or \`email\`.
+
+**notification.kind** (`string`): Notification kind within the source, such as \`ci-status\`, \`mention\`, or \`direct-message\`.
+
+**notification.summary** (`string`): LLM-facing summary used as the notification signal contents.
+
+**notification.priority** (`'low' | 'medium' | 'high' | 'urgent'`): Priority used by the notification delivery policy. Defaults to \`medium\`.
+
+**notification.payload** (`unknown`): Structured payload stored on the inbox record for tools or application code.
+
+**notification.dedupeKey** (`string`): Key used to coalesce duplicate pending notifications from the same source and thread.
+
+**notification.coalesceKey** (`string`): Key used to combine related pending notifications from the same source and thread.
+
+**notification.attributes** (`Record<string, JSONValue>`): Extra attributes copied onto the emitted notification signal.
+
+**notification.metadata** (`Record<string, unknown>`): Application metadata stored on the inbox record.
+
+**options.resourceId** (`string`): Resource ID for the notification inbox and target memory thread.
+
+**options.threadId** (`string`): Thread ID for the notification inbox and target memory thread.
+
+**options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when an immediate notification wakes an idle thread.
+
+Returns `{ accepted: true, record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void> }`. `record` is the stored inbox record. `decision` is the delivery-policy result. `signal` and `runId` are present when ingress emits a signal immediately, including the immediate summary emitted for active high-priority notifications. `persisted` is present when the emitted signal is persisted without waking an idle thread.
+
+Default delivery is priority-aware. `urgent` notifications deliver immediately. `high` notifications deliver immediately when the thread is idle; when the thread is active, Mastra emits a summary immediately and keeps `deliverAt` for later full delivery when the thread is idle. `medium` notifications deliver immediately when idle and batch into summaries when active. `low` notifications batch into summaries in both active and idle threads; idle low-priority summaries reach subscribers without waking the model loop. For the full flow, visit [Signals](https://mastra.ai/docs/agents/signals).
+
 ### `subscribeToThread(options)`
 
 Subscribes to raw stream chunks for a memory thread. Use this before calling `sendMessage()`, `queueMessage()`, or `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
@@ -234,6 +282,8 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **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.
 
+**notifications** (`{ deliveryPolicy?: NotificationDeliveryPolicyConfig }`): Notification delivery configuration for \`sendNotificationSignal()\`. \`deliveryPolicy\` can define \`decide\`, \`sources\`, \`priorities\`, or \`default\` rules that return \`deliver\`, \`queue\`, \`defer\`, \`summarize\`, \`persist\`, or \`discard\` decisions.
+
 **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/agents/durable-agent.md

@@ -0,0 +1,239 @@
+# DurableAgent
+
+`DurableAgent` wraps an existing [`Agent`](https://mastra.ai/reference/agents/agent) with durable execution and resumable streams. It runs the agentic loop so that a client can disconnect and reconnect without missing events, and it streams those events over [PubSub](https://mastra.ai/docs/server/pubsub). Use it when a run must outlive a single request or survive a dropped connection.
+
+Create one with the [`createDurableAgent`](#createdurableagentoptions) factory, or use [`createEventedAgent`](#createeventedagentoptions) for fire-and-forget execution on the built-in workflow engine. For Inngest-powered execution, use `createInngestAgent` from `@mastra/inngest`.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+import { createDurableAgent } from '@mastra/core/agent/durable'
+
+const agent = new Agent({
+  id: 'my-agent',
+  name: 'My Agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.5',
+})
+
+const durableAgent = createDurableAgent({ agent })
+
+export const mastra = new Mastra({
+  agents: { myAgent: durableAgent },
+})
+```
+
+Stream a response and read the result. The `cleanup` function unsubscribes from PubSub when you are done with the run:
+
+```typescript
+const { output, runId, cleanup } = await durableAgent.stream('Hello!')
+
+const text = await output.text
+
+cleanup()
+```
+
+## `createDurableAgent(options)`
+
+Wraps an `Agent` with durable execution and resumable streams. This is the recommended way to create a `DurableAgent`.
+
+```typescript
+import { createDurableAgent } from '@mastra/core/agent/durable'
+
+const durableAgent = createDurableAgent({ agent })
+```
+
+Returns: `DurableAgent`
+
+### Parameters
+
+**agent** (`Agent`): The Agent to wrap with durable execution capabilities. Agent methods delegate to this agent.
+
+**id** (`string`): ID override. (Default: `agent.id`)
+
+**name** (`string`): Name override. (Default: `agent.name`)
+
+**cache** (`MastraServerCache | false`): Cache for stored stream events, which enables resumable streams. If omitted, the agent inherits the cache from the Mastra instance, or uses an InMemoryServerCache. Set to \`false\` to disable caching, which makes streams non-resumable.
+
+**pubsub** (`PubSub`): PubSub instance for streaming events. (Default: `EventEmitterPubSub`)
+
+**maxSteps** (`number`): Maximum number of steps for the agentic loop.
+
+## `createEventedAgent(options)`
+
+Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It does not accept `id` or `name` overrides.
+
+```typescript
+import { createEventedAgent } from '@mastra/core/agent/durable'
+
+const eventedAgent = createEventedAgent({ agent })
+```
+
+Returns: `EventedAgent` (a subclass of `DurableAgent`)
+
+### Parameters
+
+**agent** (`Agent`): The Agent to wrap with evented durable execution capabilities.
+
+**cache** (`MastraServerCache | false`): Cache for stored stream events, which enables resumable streams. If omitted, the agent inherits the cache from the Mastra instance, or uses an InMemoryServerCache. Set to \`false\` to disable caching.
+
+**pubsub** (`PubSub`): PubSub instance for streaming events. (Default: `EventEmitterPubSub`)
+
+**maxSteps** (`number`): Maximum number of steps for the agentic loop.
+
+## Constructor parameters
+
+The `DurableAgent` class accepts the same options as `createDurableAgent`, plus `cleanupTimeoutMs`. Prefer the factory unless you need to subclass.
+
+**agent** (`Agent`): The Agent to wrap with durable execution capabilities.
+
+**id** (`string`): ID override. (Default: `agent.id`)
+
+**name** (`string`): Name override. (Default: `agent.name`)
+
+**cache** (`MastraServerCache | false`): Cache for stored stream events. If omitted, inherits from the Mastra instance or uses an InMemoryServerCache. Set to \`false\` to disable caching.
+
+**pubsub** (`PubSub`): PubSub instance for streaming events. (Default: `EventEmitterPubSub`)
+
+**maxSteps** (`number`): Maximum number of steps for the agentic loop.
+
+**cleanupTimeoutMs** (`number`): Grace period in milliseconds before registry entries are cleaned up automatically after a stream finishes or errors. Set to 0 to disable auto-cleanup and require a manual \`cleanup()\` call. Auto-cleanup does not fire on suspended events. (Default: `30000`)
+
+## Methods
+
+### Execution
+
+#### `stream(messages, options?)`
+
+Streams a response using durable execution. Returns immediately with a result whose `output` produces events as the run progresses.
+
+```typescript
+const { output, runId, cleanup } = await durableAgent.stream('Hello!', {
+  onChunk: chunk => console.log(chunk),
+  onFinish: result => console.log('done', result),
+})
+
+const text = await output.text
+cleanup()
+```
+
+Returns: [`Promise<DurableAgentStreamResult>`](#durableagentstreamresult)
+
+#### `resume(runId, resumeData, options?)`
+
+Resumes a suspended run, for example after a tool approval. Pass the `runId` from the original stream and the data the run was waiting on. Throws if no registry entry exists for the run.
+
+```typescript
+const { output, cleanup } = await durableAgent.resume(runId, {
+  approved: true,
+})
+
+await output.text
+cleanup()
+```
+
+Returns: [`Promise<DurableAgentStreamResult>`](#durableagentstreamresult)
+
+#### `observe(runId, options?)`
+
+Reconnects to an existing run, replaying cached events before delivering live ones. Use this after a network disconnection. Pass `offset` to start replay from a known position.
+
+```typescript
+const { output, cleanup } = await durableAgent.observe(runId, {
+  offset: 0,
+  onChunk: chunk => console.log(chunk),
+})
+
+await output.text
+```
+
+Returns: `Promise<DurableAgentStreamResult>`
+
+> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, do not call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup does not fire on suspended events.
+
+## Stream options
+
+`stream()` accepts a `DurableAgentStreamOptions` object. It supports the agent execution options below, plus lifecycle callbacks.
+
+**runId** (`string`): Unique identifier for this run. Use it later with \`resume()\` or \`observe()\`.
+
+**instructions** (`AgentExecutionOptions['instructions']`): Overrides the agent's default instructions for this run. Accepts a static string or the same dynamic instructions value the agent supports.
+
+**context** (`ModelMessage[]`): Additional context messages to provide to the agent.
+
+**memory** (`object`): Memory configuration for conversation persistence and retrieval.
+
+**requestContext** (`RequestContext`): Request context carrying dynamic configuration and state for this run.
+
+**maxSteps** (`number`): Maximum number of steps to run for this stream.
+
+**toolsets** (`object`): Additional tool sets available for this run.
+
+**clientTools** (`object`): Client-side tools available during execution.
+
+**toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Tool selection strategy.
+
+**activeTools** (`string[]`): Restricts execution to the named subset of the agent's tools.
+
+**modelSettings** (`object`): Model-specific settings such as temperature.
+
+**requireToolApproval** (`boolean`): Require approval for all tool calls, which suspends the run until resumed.
+
+**autoResumeSuspendedTools** (`boolean`): Automatically resume tools that suspended, instead of waiting for an external \`resume()\` call.
+
+**toolCallConcurrency** (`number`): Maximum number of tool calls to execute concurrently.
+
+**includeRawChunks** (`boolean`): Include raw provider chunks in the stream output.
+
+**maxProcessorRetries** (`number`): Maximum number of processor retries per generation.
+
+**structuredOutput** (`object`): Structured output configuration.
+
+**versions** (`object`): Version overrides for sub-agent delegation.
+
+**onChunk** (`(chunk: ChunkType) => void | Promise<void>`): Called for each streamed chunk.
+
+**onStepFinish** (`(result: AgentStepFinishEventData) => void | Promise<void>`): Called when a step in the agentic loop finishes.
+
+**onFinish** (`(result: AgentFinishEventData) => void | Promise<void>`): Called when the run finishes.
+
+**onError** (`(error: Error) => void | Promise<void>`): Called when the run errors.
+
+**onSuspended** (`(data: AgentSuspendedEventData) => void | Promise<void>`): Called when the run suspends, for example for tool approval.
+
+`resume()` and `observe()` accept the same lifecycle callbacks (`onChunk`, `onStepFinish`, `onFinish`, `onError`, `onSuspended`). `observe()` also accepts an `offset` to control where replay starts.
+
+## DurableAgentStreamResult
+
+The object returned by `stream()`, `resume()`, and `observe()`.
+
+```typescript
+interface DurableAgentStreamResult<OUTPUT = undefined> {
+  output: MastraModelOutput<OUTPUT>
+  readonly fullStream: ReadableStream<any>
+  runId: string
+  threadId?: string
+  resourceId?: string
+  cleanup: () => void
+}
+```
+
+**output** (`MastraModelOutput`): The streaming output. Await \`output.text\` for the full text, or consume \`output.fullStream\`.
+
+**fullStream** (`ReadableStream`): The full event stream, delegating to \`output.fullStream\`.
+
+**runId** (`string`): The unique run ID. Pass it to \`resume()\` or \`observe()\` to reconnect.
+
+**threadId** (`string`): Thread ID when using memory.
+
+**resourceId** (`string`): Resource ID when using memory.
+
+**cleanup** (`() => void`): Unsubscribes from PubSub and clears registry entries for the run. Call it when done with the run.
+
+## Related
+
+- [Agent class](https://mastra.ai/reference/agents/agent)
+- [PubSub](https://mastra.ai/docs/server/pubsub)
+- [`.getMemory()`](https://mastra.ai/reference/agents/getMemory)