@mastra/core 1.9.0 → 1.10.0

package/dist/docs/references/reference-streaming-agents-streamLegacy.md

@@ -12,85 +12,125 @@ await agent.streamLegacy('message for agent')
 
 ## 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.
+**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?:** (`AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>`): Optional configuration for the streaming process.
+**options** (`AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>`): Optional configuration for the streaming process.
 
-### Options parameters
+**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
 
-**abortSignal?:** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+**options.context** (`CoreMessage[]`): Additional context messages to provide to the agent.
 
-**context?:** (`CoreMessage[]`): Additional context messages to provide to the agent.
+**options.experimental\_output** (`Zod schema | JsonSchema7`): Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.
 
-**experimental\_output?:** (`Zod schema | JsonSchema7`): Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.
+**options.instructions** (`string`): Custom instructions that override the agent's default instructions for this specific generation. Useful for dynamically modifying agent behavior without creating a new agent instance.
 
-**instructions?:** (`string`): Custom instructions that override the agent's default instructions for this specific generation. Useful for dynamically modifying agent behavior without creating a new agent instance.
+**options.output** (`Zod schema | JsonSchema7`): Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
 
-**output?:** (`Zod schema | JsonSchema7`): Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
+**options.memory** (`object`): Configuration for memory. This is the preferred way to manage memory.
 
-**memory?:** (`object`): thread:string | { id: string; metadata?: Record\<string, any>, title?: string }The conversation thread, as a string ID or an object with an \`id\` and optional \`metadata\`.resource:stringIdentifier for the user or resource associated with the thread.options?:MemoryConfigConfiguration for memory behavior, like message history and semantic recall.
+**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): The conversation thread, as a string ID or an object with an \`id\` and optional \`metadata\`.
 
-**maxSteps?:** (`number`): Maximum number of execution steps allowed. (Default: `5`)
+**options.memory.resource** (`string`): Identifier for the user or resource associated with the thread.
 
-**maxRetries?:** (`number`): Maximum number of retries. Set to 0 to disable retries. (Default: `2`)
+**options.memory.options** (`MemoryConfig`): Configuration for memory behavior, like message history and semantic recall.
 
-**memoryOptions?:** (`MemoryConfig`): lastMessages?:number | falseNumber of recent messages to include in context, or false to disable.semanticRecall?:boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }Enable semantic recall to find relevant past messages. Can be a boolean or detailed configuration.workingMemory?:WorkingMemoryConfiguration for working memory functionality.threads?:{ generateTitle?: boolean | { model: DynamicArgument\<MastraLanguageModel>; instructions?: DynamicArgument\<string> } }Thread-specific configuration, including automatic title generation.
+**options.maxSteps** (`number`): Maximum number of execution steps allowed.
 
-**onFinish?:** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
+**options.maxRetries** (`number`): Maximum number of retries. Set to 0 to disable retries.
 
-**onStepFinish?:** (`StreamTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
+**options.memoryOptions** (`MemoryConfig`): \*\*Deprecated.\*\* Use \`memory.options\` instead. Configuration options for memory management.
 
-**resourceId?:** (`string`): \*\*Deprecated.\*\* Use \`memory.resource\` instead. Identifier for the user or resource interacting with the agent. Must be provided if threadId is provided.
+**options.memoryOptions.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable.
 
-**telemetry?:** (`TelemetrySettings`): isEnabled?:booleanEnable or disable telemetry. Disabled by default while experimental.recordInputs?:booleanEnable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information.recordOutputs?:booleanEnable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information.functionId?:stringIdentifier for this function. Used to group telemetry data by function.
+**options.memoryOptions.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic recall to find relevant past messages. Can be a boolean or detailed configuration.
 
-**temperature?:** (`number`): Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.
+**options.memoryOptions.workingMemory** (`WorkingMemory`): Configuration for working memory functionality.
 
-**threadId?:** (`string`): \*\*Deprecated.\*\* Use \`memory.thread\` instead. Identifier for the conversation thread. Allows for maintaining context across multiple interactions. Must be provided if resourceId is provided.
+**options.memoryOptions.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): Thread-specific configuration, including automatic title generation.
 
-**toolChoice?:** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 'auto':stringLet the model decide whether to use tools (default).'none':stringDo not use any tools.'required':stringRequire the model to use at least one tool.{ type: 'tool'; toolName: string }:objectRequire the model to use a specific tool by name. (Default: `'auto'`)
+**options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
 
-**toolsets?:** (`ToolsetsInput`): Additional toolsets to make available to the agent during streaming.
+**options.onStepFinish** (`StreamTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output
 
-**clientTools?:** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
+**options.resourceId** (`string`): \*\*Deprecated.\*\* Use \`memory.resource\` instead. Identifier for the user or resource interacting with the agent. Must be provided if threadId is provided.
 
-**savePerStep?:** (`boolean`): Save messages incrementally after each stream step completes (default: false).
+**options.telemetry** (`TelemetrySettings`): Settings for telemetry collection during streaming.
 
-**providerOptions?:** (`Record<string, Record<string, JSONValue>>`): openai?:Record\<string, JSONValue>OpenAI-specific options. Example: \`{ reasoningEffort: 'high' }\`anthropic?:Record\<string, JSONValue>Anthropic-specific options. Example: \`{ maxTokens: 1000 }\`google?:Record\<string, JSONValue>Google-specific options. Example: \`{ safetySettings: \[...] }\`\[providerName]?:Record\<string, JSONValue>Other provider-specific options. The key is the provider name and the value is a record of provider-specific options.
+**options.telemetry.isEnabled** (`boolean`): Enable or disable telemetry. Disabled by default while experimental.
 
-**runId?:** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+**options.telemetry.recordInputs** (`boolean`): Enable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information.
 
-**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information.
+**options.telemetry.recordOutputs** (`boolean`): Enable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information.
 
-**maxTokens?:** (`number`): Maximum number of tokens to generate.
+**options.telemetry.functionId** (`string`): Identifier for this function. Used to group telemetry data by function.
 
-**topP?:** (`number`): Nucleus sampling. This is a number between 0 and 1. It is recommended to set either \`temperature\` or \`topP\`, but not both.
+**options.temperature** (`number`): Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.
 
-**topK?:** (`number`): Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.
+**options.threadId** (`string`): \*\*Deprecated.\*\* Use \`memory.thread\` instead. Identifier for the conversation thread. Allows for maintaining context across multiple interactions. Must be provided if resourceId is provided.
 
-**presencePenalty?:** (`number`): Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how the agent uses tools during streaming.
 
-**frequencyPenalty?:** (`number`): Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+**options.toolChoice.'auto'** (`string`): Let the model decide whether to use tools (default).
 
-**stopSequences?:** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+**options.toolChoice.'none'** (`string`): Do not use any tools.
 
-**seed?:** (`number`): The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.
+**options.toolChoice.'required'** (`string`): Require the model to use at least one tool.
 
-**headers?:** (`Record<string, string | undefined>`): Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Require the model to use a specific tool by name.
+
+**options.toolsets** (`ToolsetsInput`): Additional toolsets to make available to the agent during streaming.
+
+**options.clientTools** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
+
+**options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
+
+**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Additional provider-specific options that are passed through to the underlying LLM provider. The structure is \`{ providerName: { optionKey: value } }\`. For example: \`{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }\`.
+
+**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI-specific options. Example: \`{ reasoningEffort: 'high' }\`
+
+**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Anthropic-specific options. Example: \`{ maxTokens: 1000 }\`
+
+**options.providerOptions.google** (`Record<string, JSONValue>`): Google-specific options. Example: \`{ safetySettings: \[...] }\`
+
+**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): Other provider-specific options. The key is the provider name and the value is a record of provider-specific options.
+
+**options.runId** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+
+**options.requestContext** (`RequestContext`): Request Context for dependency injection and contextual information.
+
+**options.maxTokens** (`number`): Maximum number of tokens to generate.
+
+**options.topP** (`number`): Nucleus sampling. This is a number between 0 and 1. It is recommended to set either \`temperature\` or \`topP\`, but not both.
+
+**options.topK** (`number`): Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.
+
+**options.presencePenalty** (`number`): Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+
+**options.frequencyPenalty** (`number`): Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+
+**options.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**options.seed** (`number`): The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.
+
+**options.headers** (`Record<string, string | undefined>`): Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
 
 ## Returns
 
-**textStream?:** (`AsyncGenerator<string>`): Async generator that yields text chunks as they become available.
+**textStream** (`AsyncGenerator<string>`): Async generator that yields text chunks as they become available.
+
+**fullStream** (`Promise<ReadableStream>`): Promise that resolves to a ReadableStream for the complete response.
+
+**text** (`Promise<string>`): Promise that resolves to the complete text response.
 
-**fullStream?:** (`Promise<ReadableStream>`): Promise that resolves to a ReadableStream for the complete response.
+**usage** (`Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>`): Promise that resolves to token usage information.
 
-**text?:** (`Promise<string>`): Promise that resolves to the complete text response.
+**finishReason** (`Promise<string>`): Promise that resolves to the reason why the stream finished.
 
-**usage?:** (`Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>`): Promise that resolves to token usage information.
+**toolCalls** (`Promise<Array<ToolCall>>`): Promise that resolves to the tool calls made during the streaming process.
 
-**finishReason?:** (`Promise<string>`): Promise that resolves to the reason why the stream finished.
+**toolCalls.toolName** (`string`): The name of the tool invoked.
 
-**toolCalls?:** (`Promise<Array<ToolCall>>`): toolName:stringThe name of the tool invoked.args:anyThe arguments passed to the tool.
+**toolCalls.args** (`any`): The arguments passed to the tool.
 
 ## Extended usage example
 

package/dist/docs/references/reference-streaming-workflows-resumeStream.md

@@ -26,23 +26,33 @@ if (result!.status === 'suspended') {
 
 ## Parameters
 
-**resumeData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+**resumeData** (`z.infer<TInput>`): Input data that matches the workflow's input schema
 
-**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+**requestContext** (`RequestContext`): Request Context data to use during workflow execution
 
-**step?:** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
+**step** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
 
-**tracingOptions?:** (`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.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+**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.
+
+**tracingOptions.requestContextKeys** (`string[]`): Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').
+
+**tracingOptions.traceId** (`string`): Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.
+
+**tracingOptions.parentSpanId** (`string`): Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.
+
+**tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
 
 ## Returns
 
-**stream:** (`MastraWorkflowStream<ChunkType>`): A custom stream that extends ReadableStream\<ChunkType> with additional workflow-specific properties
+**stream** (`MastraWorkflowStream<ChunkType>`): A custom stream that extends ReadableStream\<ChunkType> with additional workflow-specific properties
 
-**stream.status:** (`Promise<RunStatus>`): A promise that resolves to the current workflow run status
+**stream.status** (`Promise<RunStatus>`): A promise that resolves to the current workflow run status
 
-**stream.result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+**stream.result** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the final workflow result
 
-**stream.usage:** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>`): A promise that resolves to token usage statistics
+**stream.usage** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>`): A promise that resolves to token usage statistics
 
 ## Stream Events
 

package/dist/docs/references/reference-streaming-workflows-stream.md

@@ -20,27 +20,39 @@ for await (const chunk of stream) {
 
 ## Parameters
 
-**inputData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+**inputData** (`z.infer<TInput>`): Input data that matches the workflow's input schema
 
-**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+**requestContext** (`RequestContext`): Request Context data to use during workflow execution
 
-**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata.
+**tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata.
 
-**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+**tracingContext.currentSpan** (`Span`): Current span for creating child spans and adding metadata.
 
-**closeOnSuspend?:** (`boolean`): Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.
+**tracingOptions** (`TracingOptions`): Options for Tracing configuration.
+
+**tracingOptions.metadata** (`Record<string, any>`): Metadata to add to the root trace span.
+
+**tracingOptions.requestContextKeys** (`string[]`): Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').
+
+**tracingOptions.traceId** (`string`): Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.
+
+**tracingOptions.parentSpanId** (`string`): Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.
+
+**tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**closeOnSuspend** (`boolean`): Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.
 
 ## Returns
 
 Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
 
-**fullStream:** (`ReadableStream<WorkflowStreamEvent>`): A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.
+**fullStream** (`ReadableStream<WorkflowStreamEvent>`): A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.
 
-**result:** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+**result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow result
 
-**status:** (`WorkflowRunStatus`): The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')
+**status** (`WorkflowRunStatus`): The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')
 
-**usage:** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>`): A promise that resolves to token usage statistics
+**usage** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>`): A promise that resolves to token usage statistics
 
 ## Extended usage example
 

package/dist/docs/references/reference-streaming-workflows-timeTravelStream.md

@@ -27,13 +27,13 @@ All parameters are the same as [`Run.timeTravel()`](https://mastra.ai/reference/
 
 ## Returns
 
-**output:** (`WorkflowRunOutput<WorkflowResult<TState, TInput, TOutput, TSteps>>`): An object containing both the stream and result promise
+**output** (`WorkflowRunOutput<WorkflowResult<TState, TInput, TOutput, TSteps>>`): An object containing both the stream and result promise
 
-**output.fullStream:** (`ReadableStream<WorkflowStreamEvent>`): A readable stream that emits workflow events as execution progresses
+**output.fullStream** (`ReadableStream<WorkflowStreamEvent>`): A readable stream that emits workflow events as execution progresses
 
-**output.result:** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow execution result
+**output.result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow execution result
 
-**output.traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled
+**output.traceId** (`string`): The trace ID associated with this execution when Tracing is enabled
 
 ## Stream events
 

package/dist/docs/references/reference-tools-create-tool.md

@@ -112,41 +112,45 @@ export const weatherTool = createTool({
 
 ## Parameters
 
-**id:** (`string`): A unique identifier for the tool.
+**id** (`string`): A unique identifier for the tool.
 
-**description:** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
+**description** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
 
-**inputSchema?:** (`Zod schema`): A Zod schema defining the expected input parameters for the tool's \`execute\` function.
+**inputSchema** (`Zod schema`): A Zod schema defining the expected input parameters for the tool's \`execute\` function.
 
-**outputSchema?:** (`Zod schema`): A Zod schema defining the expected output structure of the tool's \`execute\` function.
+**outputSchema** (`Zod schema`): A Zod schema defining the expected output structure of the tool's \`execute\` function.
 
-**toModelOutput?:** (`(output: TSchemaOut) => unknown`): Optional function that transforms the tool's \`execute\` output before it is sent back to the model. Use this to return \`text\`, \`json\`, or \`content\`-shaped outputs (including multimodal parts like images/files) to the model while still keeping the full raw output in your application code.
+**toModelOutput** (`(output: TSchemaOut) => unknown`): Optional function that transforms the tool's \`execute\` output before it is sent back to the model. Use this to return \`text\`, \`json\`, or \`content\`-shaped outputs (including multimodal parts like images/files) to the model while still keeping the full raw output in your application code.
 
-**suspendSchema?:** (`Zod schema`): A Zod schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
+**suspendSchema** (`Zod schema`): A Zod schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
 
-**resumeSchema?:** (`Zod schema`): A Zod schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.
+**resumeSchema** (`Zod schema`): A Zod schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.
 
-**requireApproval?:** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
+**requireApproval** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
 
-**mcp?:** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
+**mcp** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
 
-**requestContextSchema?:** (`Zod schema`): A Zod schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
+**requestContextSchema** (`Zod schema`): A Zod schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
 
-**execute:** (`function`): input:z.infer\<TInput>The validated input data based on inputSchemacontext?:ToolExecutionContextOptional execution context containing metadataRequestContextTracingContextAbortSignalAgentToolExecutionContextWorkflowToolExecutionContextMCPToolExecutionContext
+**execute** (`function`): The function that contains the tool's logic. It receives two parameters: the validated input data (first parameter) and an optional execution context object (second parameter) containing \`requestContext\`, \`tracingContext\`, \`abortSignal\`, and other execution metadata.
 
-**onInputStart?:** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**execute.input** (`z.infer<TInput>`): The validated input data based on inputSchema
 
-**onInputDelta?:** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**execute.context** (`ToolExecutionContext`): Optional execution context containing metadata
 
-**onInputAvailable?:** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
 
-**onOutput?:** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+
+**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
 
 ## Returns
 
 The `createTool()` function returns a `Tool` object.
 
-**Tool:** (`object`): An object representing the defined tool, ready to be added to an agent.
+**Tool** (`object`): An object representing the defined tool, ready to be added to an agent.
 
 ## Tool Lifecycle Hooks
 
@@ -264,15 +268,15 @@ mcp: {
 
 ### ToolAnnotations Properties
 
-**title?:** (`string`): A human-readable title for the tool. Used for display purposes in UI components.
+**title** (`string`): A human-readable title for the tool. Used for display purposes in UI components.
 
-**readOnlyHint?:** (`boolean`): If true, the tool does not modify its environment. This hint indicates the tool only reads data and has no side effects. Defaults to false.
+**readOnlyHint** (`boolean`): If true, the tool does not modify its environment. This hint indicates the tool only reads data and has no side effects. Defaults to false.
 
-**destructiveHint?:** (`boolean`): If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. This hint helps clients determine if confirmation should be required. Defaults to true.
+**destructiveHint** (`boolean`): If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. This hint helps clients determine if confirmation should be required. Defaults to true.
 
-**idempotentHint?:** (`boolean`): If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment. This hint indicates idempotent behavior. Defaults to false.
+**idempotentHint** (`boolean`): If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment. This hint indicates idempotent behavior. Defaults to false.
 
-**openWorldHint?:** (`boolean`): If true, this tool may interact with an 'open world' of external entities (e.g., web search, external APIs). If false, the tool's domain is closed and fully defined. Defaults to true.
+**openWorldHint** (`boolean`): If true, this tool may interact with an 'open world' of external entities (e.g., web search, external APIs). If false, the tool's domain is closed and fully defined. Defaults to true.
 
 These annotations follow the [MCP specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations) and are passed through when tools are listed via MCP.
 

package/dist/docs/references/reference-tools-graph-rag-tool.md

@@ -25,43 +25,41 @@ const graphTool = createGraphRAGTool({
 
 > **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
 
-**id?:** (`string`): Custom ID for the tool. By default: 'GraphRAG {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+**id** (`string`): Custom ID for the tool. By default: 'GraphRAG {vectorStoreName} {indexName} Tool'. (Set at creation only.)
 
-**description?:** (`string`): Custom description for the tool. By default: 'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns.' (Set at creation only.)
+**description** (`string`): Custom description for the tool. By default: 'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns.' (Set at creation only.)
 
-**vectorStoreName:** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
+**vectorStoreName** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
-**indexName:** (`string`): Name of the index within the vector store. (Can be set at creation or overridden at runtime.)
+**indexName** (`string`): Name of the index within the vector store. (Can be set at creation or overridden at runtime.)
 
-**model:** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+**model** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
 
-**enableFilter?:** (`boolean`): Enable filtering of results based on metadata. (Set at creation only, but will be automatically enabled if a filter is provided in the request context.) (Default: `false`)
+**enableFilter** (`boolean`): Enable filtering of results based on metadata. (Set at creation only, but will be automatically enabled if a filter is provided in the request context.) (Default: `false`)
 
-**includeSources?:** (`boolean`): Include the full retrieval objects in the results. (Can be set at creation or overridden at runtime.) (Default: `true`)
+**includeSources** (`boolean`): Include the full retrieval objects in the results. (Can be set at creation or overridden at runtime.) (Default: `true`)
 
-**graphOptions?:** (`GraphOptions`): Configuration for the graph-based retrieval (Default: `Default graph options`)
+**graphOptions** (`GraphOptions`): Configuration for the graph-based retrieval (Default: `Default graph options`)
 
-**providerOptions?:** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
+**graphOptions.dimension** (`number`): Dimension of the embedding vectors
 
-**vectorStore?:** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
+**graphOptions.threshold** (`number`): Similarity threshold for creating edges between nodes (0-1)
 
-### GraphOptions
+**graphOptions.randomWalkSteps** (`number`): Number of steps in random walk for graph traversal. (Can be set at creation or overridden at runtime.)
 
-**dimension?:** (`number`): Dimension of the embedding vectors (Default: `1536`)
+**graphOptions.restartProb** (`number`): Probability of restarting random walk from query node. (Can be set at creation or overridden at runtime.)
 
-**threshold?:** (`number`): Similarity threshold for creating edges between nodes (0-1) (Default: `0.7`)
+**providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
 
-**randomWalkSteps?:** (`number`): Number of steps in random walk for graph traversal. (Can be set at creation or overridden at runtime.) (Default: `100`)
-
-**restartProb?:** (`number`): Probability of restarting random walk from query node. (Can be set at creation or overridden at runtime.) (Default: `0.15`)
+**vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
 
 ## Returns
 
 The tool returns an object with:
 
-**relevantContext:** (`string`): Combined text from the most relevant document chunks, retrieved using graph-based ranking
+**relevantContext** (`string`): Combined text from the most relevant document chunks, retrieved using graph-based ranking
 
-**sources:** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
+**sources** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
 
 ### QueryResult object structure
 

package/dist/docs/references/reference-tools-mcp-client.md

@@ -16,11 +16,11 @@ constructor({
 
 ### MCPClientOptions
 
-**id?:** (`string`): Optional unique identifier for the configuration instance. Use this to prevent memory leaks when creating multiple instances with identical configurations.
+**id** (`string`): Optional unique identifier for the configuration instance. Use this to prevent memory leaks when creating multiple instances with identical configurations.
 
-**servers:** (`Record<string, MastraMCPServerDefinition>`): A map of server configurations, where each key is a unique server identifier and the value is the server configuration.
+**servers** (`Record<string, MastraMCPServerDefinition>`): A map of server configurations, where each key is a unique server identifier and the value is the server configuration.
 
-**timeout?:** (`number`): Global timeout value in milliseconds for all servers unless overridden in individual server configs. (Default: `60000`)
+**timeout** (`number`): Global timeout value in milliseconds for all servers unless overridden in individual server configs. (Default: `60000`)
 
 ### MastraMCPServerDefinition
 
@@ -29,29 +29,29 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 - If `command` is provided, it uses the Stdio transport.
 - If `url` is provided, it first attempts to use the Streamable HTTP transport and falls back to the legacy SSE transport if the initial connection fails.
 
-**command?:** (`string`): For Stdio servers: The command to execute.
+**command** (`string`): For Stdio servers: The command to execute.
 
-**args?:** (`string[]`): For Stdio servers: Arguments to pass to the command.
+**args** (`string[]`): For Stdio servers: Arguments to pass to the command.
 
-**env?:** (`Record<string, string>`): For Stdio servers: Environment variables to set for the command.
+**env** (`Record<string, string>`): For Stdio servers: Environment variables to set for the command.
 
-**url?:** (`URL`): For HTTP servers (Streamable HTTP or SSE): The URL of the server.
+**url** (`URL`): For HTTP servers (Streamable HTTP or SSE): The URL of the server.
 
-**requestInit?:** (`RequestInit`): For HTTP servers: Request configuration for the fetch API.
+**requestInit** (`RequestInit`): For HTTP servers: Request configuration for the fetch API.
 
-**eventSourceInit?:** (`EventSourceInit`): For SSE fallback: Custom fetch configuration for SSE connections. Required when using custom headers with SSE.
+**eventSourceInit** (`EventSourceInit`): For SSE fallback: Custom fetch configuration for SSE connections. Required when using custom headers with SSE.
 
-**fetch?:** (`FetchLike`): For HTTP servers: Custom fetch implementation used for all network requests. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers (e.g., refreshing bearer tokens), customize request behavior per-request, or intercept and modify requests/responses. When \`fetch\` is provided, \`requestInit\`, \`eventSourceInit\`, and \`authProvider\` become optional, as you can handle these concerns within your custom fetch function.
+**fetch** (`MastraFetchLike`): For HTTP servers: Custom fetch implementation used for all network requests. Receives an optional third \`requestContext\` parameter containing request-scoped data (e.g., authentication cookies, bearer tokens) from the incoming request. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers, forward request-scoped credentials to the MCP server, customize request behavior per-request, or intercept and modify requests/responses. When \`fetch\` is provided, \`requestInit\`, \`eventSourceInit\`, and \`authProvider\` become optional, as you can handle these concerns within your custom fetch function.
 
-**logger?:** (`LogHandler`): Optional additional handler for logging.
+**logger** (`LogHandler`): Optional additional handler for logging.
 
-**timeout?:** (`number`): Server-specific timeout in milliseconds.
+**timeout** (`number`): Server-specific timeout in milliseconds.
 
-**capabilities?:** (`ClientCapabilities`): Server-specific capabilities configuration.
+**capabilities** (`ClientCapabilities`): Server-specific capabilities configuration.
 
-**authProvider?:** (`OAuthClientProvider`): For HTTP servers: OAuth authentication provider for automatic token refresh and OAuth flow management. Use MCPOAuthClientProvider for a ready-to-use implementation.
+**authProvider** (`OAuthClientProvider`): For HTTP servers: OAuth authentication provider for automatic token refresh and OAuth flow management. Use MCPOAuthClientProvider for a ready-to-use implementation.
 
-**enableServerLogs?:** (`boolean`): Whether to enable logging for this server. (Default: `true`)
+**enableServerLogs** (`boolean`): Whether to enable logging for this server. (Default: `true`)
 
 ## Methods
 
@@ -873,7 +873,9 @@ MCPClient handles server connections gracefully:
 
 ## Using Custom Fetch for Dynamic Authentication
 
-For HTTP servers, you can provide a custom `fetch` function to handle dynamic authentication, request interception, or other custom behavior. This is particularly useful when you need to refresh tokens on each request or customize request behavior.
+For HTTP servers, you can provide a custom `fetch` function to handle dynamic authentication, request interception, or other custom behavior. This is particularly useful when you need to refresh tokens on each request or forward user credentials from the incoming request to the MCP server.
+
+The custom `fetch` function receives an optional third `requestContext` parameter, which provides access to request-scoped data (e.g., authentication cookies, bearer tokens) set by middleware or passed during agent/tool execution. The `requestContext` is `null` during the initial connection handshake.
 
 When `fetch` is provided, `requestInit`, `eventSourceInit`, and `authProvider` become optional, as you can handle these concerns within your custom fetch function.
 
@@ -882,21 +884,30 @@ const mcpClient = new MCPClient({
   servers: {
     apiServer: {
       url: new URL('https://api.example.com/mcp'),
-      fetch: async (url, init) => {
-        // Refresh token on each request
-        const token = await getAuthToken() // Your token refresh logic
-
-        return fetch(url, {
-          ...init,
-          headers: {
-            ...init?.headers,
-            Authorization: `Bearer ${token}`,
-          },
-        })
+      fetch: async (url, init, requestContext) => {
+        const headers = new Headers(init?.headers)
+        // Forward auth cookie from the incoming request
+        const cookie = requestContext?.get('cookie')
+        if (cookie) {
+          headers.set('cookie', cookie)
+        }
+        return fetch(url, { ...init, headers })
       },
     },
   },
 })
+
+// Use with an agent — requestContext is automatically forwarded
+const agent = new Agent({
+  name: 'My Agent',
+  instructions: 'You are a helpful assistant.',
+  model: openai('gpt-4o'),
+  tools: await mcpClient.listTools(),
+})
+
+await agent.generate('Hello!', {
+  requestContext: myRequestContext, // forwarded to the custom fetch
+})
 ```
 
 ## Using SSE Request Headers