@mastra/mcp-docs-server 0.0.0-studio-deploy-20260404184540 → 0.0.0-studio-cli-20260504022012

package/.docs/reference/storage/redis.md

@@ -0,0 +1,266 @@
+# Redis Storage
+
+The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [node-redis](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.
+
+## Installation
+
+```bash
+npm install @mastra/redis
+```
+
+## Usage
+
+### Using Connection String
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  connectionString: 'redis://localhost:6379',
+})
+
+await storage.init()
+```
+
+### Using Host/Port Configuration
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  host: 'localhost',
+  port: 6379,
+  password: 'your-password',
+  db: 0,
+})
+
+await storage.init()
+```
+
+### Using Pre-configured Client
+
+For advanced configurations like Sentinel or Cluster, you can pass a pre-configured redis client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: 'redis://localhost:6379',
+  socket: {
+    reconnectStrategy: retries => Math.min(retries * 50, 2000),
+  },
+})
+
+// Connect the client before passing to RedisStore
+await client.connect()
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  client,
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for the storage instance
+
+**connectionString** (`string`): Redis connection URL (e.g., \`redis\://localhost:6379\` or \`redis\://:password\@localhost:6379\`)
+
+**host** (`string`): Redis host address
+
+**port** (`number`): Redis port number (Default: `6379`)
+
+**password** (`string`): Redis password for authentication
+
+**db** (`number`): Redis database number (Default: `0`)
+
+**client** (`RedisClient`): Pre-configured redis client (from the \`redis\` package) for advanced setups
+
+> **Note:** You must provide either `connectionString`, `host`, or `client`. These options are mutually exclusive.
+
+## Additional Notes
+
+### Key Structure
+
+The Redis storage implementation uses the following key patterns:
+
+- Threads: `mastra_threads:id:{threadId}`
+- Messages: `mastra_messages:threadId:{threadId}:id:{messageId}`
+- Message index: `msg-idx:{messageId}` (for fast lookups)
+- Thread messages sorted set: `thread:{threadId}:messages`
+- Workflow snapshots: `mastra_workflow_snapshot:namespace:{ns}:workflow_name:{name}:run_id:{id}`
+- Scores: `mastra_scorers:id:{scoreId}`
+- Resources: `mastra_resources:{resourceId}`
+
+### Redis Sentinel
+
+For high-availability deployments using Redis Sentinel, create a custom client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: 'redis://sentinel-host:26379',
+  // Configure sentinel options as needed for your setup
+})
+
+await client.connect()
+
+const storage = new RedisStore({
+  id: 'redis-sentinel-storage',
+  client,
+})
+```
+
+### Redis Cluster
+
+For Redis Cluster deployments, use the cluster client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createCluster } from 'redis'
+
+const cluster = createCluster({
+  rootNodes: [
+    { url: 'redis://node-1:6379' },
+    { url: 'redis://node-2:6379' },
+    { url: 'redis://node-3:6379' },
+  ],
+})
+
+await cluster.connect()
+
+const storage = new RedisStore({
+  id: 'redis-cluster-storage',
+  client: cluster,
+})
+```
+
+### Accessing the Underlying Client
+
+You can access the underlying redis client for custom operations:
+
+```typescript
+const storage = new RedisStore({
+  id: 'redis-storage',
+  connectionString: 'redis://localhost:6379',
+})
+
+await storage.init()
+
+const client = storage.getClient()
+
+// Custom Redis operations
+await client.set('custom-key', 'value')
+const value = await client.get('custom-key')
+```
+
+### Closing Connections
+
+When shutting down your application, close the Redis connection:
+
+```typescript
+await storage.close()
+```
+
+## Usage Example
+
+### Adding memory to an agent
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { RedisStore } from '@mastra/redis'
+
+export const redisAgent = new Agent({
+  id: 'redis-agent',
+  name: 'Redis Agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-4o',
+  memory: new Memory({
+    storage: new RedisStore({
+      id: 'redis-agent-storage',
+      connectionString: process.env.REDIS_URL!,
+    }),
+    options: {
+      lastMessages: 10,
+    },
+  }),
+})
+```
+
+### Using the agent
+
+```typescript
+import 'dotenv/config'
+
+import { mastra } from './mastra'
+
+const threadId = '123'
+const resourceId = 'user-456'
+
+const agent = mastra.getAgent('redisAgent')
+
+const message = await agent.stream('My name is Mastra', {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+})
+
+await message.textStream.pipeTo(new WritableStream())
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+  },
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+### Using with Mastra instance
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'mastra-storage',
+  host: 'localhost',
+  port: 6379,
+})
+
+const mastra = new Mastra({
+  storage, // init() called automatically
+})
+```
+
+If using storage directly without Mastra, call `init()` explicitly:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  host: 'localhost',
+  port: 6379,
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```

package/.docs/reference/streaming/ChunkType.md

@@ -398,6 +398,146 @@ Contains output from workflow step execution, used primarily for usage tracking
 
 **payload.output** (`ChunkType`): Nested chunk data from step execution, typically containing finish events or other step results
 
+## Background task chunks
+
+Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/agents/background-tasks) and `streamUntilIdle()` is used.
+
+### background-task-started
+
+Emitted when a tool call is enqueued as a background task and assigned a `taskId`.
+
+**type** (`"background-task-started"`): Chunk type identifier
+
+**payload** (`BackgroundTaskStartedPayload`): Identifies the newly enqueued task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+### background-task-running
+
+Emitted when a worker picks up the task and execution begins.
+
+**type** (`"background-task-running"`): Chunk type identifier
+
+**payload** (`BackgroundTaskRunningPayload`): Details about the running task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.startedAt** (`Date`): Timestamp at which execution started
+
+**payload.args** (`Record<string, unknown>`): Arguments passed to the tool's execute function
+
+### background-task-progress
+
+Periodic snapshot of how many background tasks are currently running across the agent.
+
+**type** (`"background-task-progress"`): Chunk type identifier
+
+**payload** (`BackgroundTaskProgressPayload`): Aggregate progress for all running tasks
+
+**payload.taskIds** (`string[]`): IDs of all currently running background tasks
+
+**payload.runningCount** (`number`): Number of background tasks currently running
+
+**payload.elapsedMs** (`number`): Milliseconds elapsed since the agent run started
+
+### background-task-output
+
+A streamed output chunk emitted by the task's `execute` function. Wraps an inner [`tool-output`](#tool-output) chunk.
+
+**type** (`"background-task-output"`): Chunk type identifier
+
+**payload** (`BackgroundTaskOutputPayload`): Streamed output from the running task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.payload** (`ToolOutputChunk`): Inner tool-output chunk produced by the task
+
+### background-task-completed
+
+Emitted when the task finishes successfully. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-completed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskResultPayload`): The completed task's result
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.result** (`unknown`): The tool's resolved return value
+
+**payload.completedAt** (`Date`): Timestamp at which the task completed
+
+**payload.isError** (`boolean`): True when the tool returned an error result rather than throwing
+
+### background-task-failed
+
+Emitted when the task throws or times out. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-failed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskFailedPayload`): Failure details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.error** (`{ message: string }`): Error details thrown by the task
+
+**payload.completedAt** (`Date`): Timestamp at which the task failed
+
+### background-task-cancelled
+
+Emitted when the task is cancelled before completing. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-cancelled"`): Chunk type identifier
+
+**payload** (`BackgroundTaskCancelledPayload`): Cancellation details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.completedAt** (`Date`): Timestamp at which the task was cancelled
+
 ## Metadata and special chunks
 
 ### response-metadata
@@ -479,6 +619,6 @@ for await (const chunk of stream.fullStream) {
 
 ## Related types
 
-- [.stream()](https://mastra.ai/reference/streaming/agents/stream) - Method that returns streams emitting these chunks
-- [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput) - The stream object that emits these chunks
-- [workflow.stream()](https://mastra.ai/reference/streaming/workflows/stream) - Method that returns streams emitting these chunks for workflows
+- [.stream()](https://mastra.ai/reference/streaming/agents/stream): Method that returns streams emitting these chunks
+- [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput): The stream object that emits these chunks
+- [workflow.stream()](https://mastra.ai/reference/streaming/workflows/stream): Method that returns streams emitting these chunks for workflows

package/.docs/reference/streaming/agents/MastraModelOutput.md

@@ -248,5 +248,5 @@ if (stream.error) {
 
 ## Related types
 
-- [.stream()](https://mastra.ai/reference/streaming/agents/stream) - Method that returns MastraModelOutput
-- [ChunkType](https://mastra.ai/reference/streaming/ChunkType) - All possible chunk types in the full stream
+- [.stream()](https://mastra.ai/reference/streaming/agents/stream): Method that returns MastraModelOutput
+- [ChunkType](https://mastra.ai/reference/streaming/ChunkType): All possible chunk types in the full stream

package/.docs/reference/streaming/agents/stream.md

@@ -88,7 +88,7 @@ const stream = await agent.stream('message for agent')
 
 **options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Options to fine tune your structured output generation.
 
-**options.structuredOutput.schema** (`z.ZodSchema<S>`): Zod schema defining the expected output structure.
+**options.structuredOutput.schema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the expected output structure.
 
 **options.structuredOutput.model** (`MastraLanguageModel`): Language model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured output
 
@@ -120,7 +120,7 @@ const stream = await agent.stream('message for agent')
 
 **options.memory.resource** (`string`): Identifier for the user or resource associated with the thread.
 
-**options.memory.options** (`MemoryConfig`): Configuration for memory behavior including lastMessages, readOnly, semanticRecall, and workingMemory.
+**options.memory.options** (`MemoryConfig`): Configuration for memory behavior including lastMessages, readOnly, semanticRecall, workingMemory, and filterIncompleteToolCalls.
 
 **options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
 
@@ -206,6 +206,14 @@ const stream = await agent.stream('message for agent')
 
 **options.tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
 
+**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See \[Sub-agent versioning]\(/docs/editor/overview#sub-agent-versioning).
+
+**options.versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors.
+
+**options.versions.agents.versionId** (`string`): Target a specific version by ID.
+
+**options.versions.agents.status** (`'draft' | 'published'`): Target the latest version with this publication status.
+
 ## Returns
 
 **stream** (`MastraModelOutput<Output>`): Returns a MastraModelOutput instance that provides access to the streaming output.

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -0,0 +1,94 @@
+# Agent.streamUntilIdle()
+
+**Added in:** `@mastra/core@1.29.0`
+
+`streamUntilIdle()` streams an agent's response and keeps the stream open until every background task dispatched during the run completes. When a task finishes, its result is written to memory and the agentic loop re-enters automatically so the LLM can react to it. The stream closes once no tasks are running and no completions are queued.
+
+Use it when the agent dispatches background tasks (typically long-running tools or subagents) and you want a single stream that spans the initial response **plus** every continuation triggered by a task completion. For foreground-only runs or if you prefer to manage the continuation manually (manually prompt agent to process the result), use [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream).
+
+## Usage example
+
+```ts
+const stream = await agent.streamUntilIdle('Research solana for me', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+
+for await (const chunk of stream.fullStream) {
+  // chunks from the initial turn AND any continuation turns triggered by
+  // background task completions flow through here
+}
+```
+
+> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it falls through to a plain `agent.stream()` call.
+
+## Parameters
+
+**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects.
+
+**options** (`AgentExecutionOptions<Output> & { maxIdleMs?: number }`): Accepts every option that Agent.stream() accepts, plus maxIdleMs. See the Agent.stream() reference for the full list.
+
+**options.maxIdleMs** (`number`): Closes the outer stream after this many ms of idleness between turns. The timer only runs while the wrapper is between turns, so a slow first token does not close the stream. Default: 5 minutes.
+
+**options.memory** (`{ thread?: string | { id: string }; resource?: string }`): Memory thread and resource for the run. Required for continuations to write background task results back into the conversation.
+
+**options.structuredOutput** (`PublicStructuredOutputOptions<Output>`): Schema-based structured output. Same shape as Agent.stream(). Note that aggregate properties resolve against the first turn only.
+
+For every other option (`maxSteps`, `modelSettings`, `toolChoice`, `outputProcessors`, `onFinish`, `onChunk`, etc.), see the [`Agent.stream()` parameters](https://mastra.ai/reference/streaming/agents/stream). `streamUntilIdle()` forwards them to the initial turn.
+
+## Returns
+
+**stream** (`MastraModelOutput<Output>`): A MastraModelOutput where fullStream spans the initial turn plus every auto-continuation. Aggregate properties (text, toolCalls, toolResults, finishReason, messageList, getFullOutput()) resolve against the first turn only.
+
+### Aggregate properties caveat
+
+`streamUntilIdle()` returns a proxy over the first turn's `MastraModelOutput`. Only `fullStream` is replaced with a combined stream that spans every continuation. Every other property — `text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()` — resolves against the **first turn's** internal buffer.
+
+If you need an aggregate view across all continuations, consume `fullStream` yourself and accumulate.
+
+## Continuation behavior
+
+Internally, `streamUntilIdle()`:
+
+1. Runs the initial turn via `agent.stream(...)` and pipes its `fullStream` into the outer stream.
+2. Subscribes to background-task completion events for the resolved memory scope.
+3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the just-completed `toolCallId`s. The continuation turn flows into the same outer stream.
+4. Closes the outer stream once no tasks are running and no completions are queued.
+
+## Extended usage example
+
+### Cap idle time between turns
+
+```ts
+const stream = await agent.streamUntilIdle('Kick off the long jobs', {
+  memory: { thread: 't1', resource: 'u1' },
+  maxIdleMs: 60_000, // close the stream after 1 minute of idleness between turns
+})
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'background-task-completed') {
+    console.log('Task complete:', chunk.payload.taskId)
+  }
+}
+```
+
+### Aggregate text across continuations
+
+```ts
+const stream = await agent.streamUntilIdle('Research and summarize', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+
+let fullText = ''
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'text-delta') {
+    fullText += chunk.payload.text
+  }
+}
+```
+
+## Related
+
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
+- [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
+- [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -32,6 +32,8 @@ if (result!.status === 'suspended') {
 
 **step** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
 
+**forEachIndex** (`number`): Target a specific iteration of a suspended \`.foreach()\` step. Pass the zero-based index of the iteration to resume; other iterations remain suspended. Omit to resume all suspended iterations of the step with the same \`resumeData\`.
+
 **tracingOptions** (`TracingOptions`): Options for Tracing configuration.
 
 **tracingOptions.metadata** (`Record<string, any>`): Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.