@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

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

@@ -0,0 +1,292 @@
+# ChunkType
+
+The `ChunkType` type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.
+
+## Base Properties
+
+All chunks include these base properties:
+
+**type:** (`string`): The specific chunk type identifier
+
+**runId:** (`string`): Unique identifier for this execution run
+
+**from:** (`ChunkFrom`): enumAGENT:'AGENT'Chunk from agent executionUSER:'USER'Chunk from user inputSYSTEM:'SYSTEM'Chunk from system processesWORKFLOW:'WORKFLOW'Chunk from workflow execution
+
+## Text Chunks
+
+### text-start
+
+Signals the beginning of text generation.
+
+**type:** (`"text-start"`): Chunk type identifier
+
+**payload:** (`TextStartPayload`): TextStartPayloadid:stringUnique identifier for this text generationproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### text-delta
+
+Incremental text content during generation.
+
+**type:** (`"text-delta"`): Chunk type identifier
+
+**payload:** (`TextDeltaPayload`): TextDeltaPayloadid:stringUnique identifier for this text generationtext:stringThe incremental text contentproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### text-end
+
+Signals the end of text generation.
+
+**type:** (`"text-end"`): Chunk type identifier
+
+**payload:** (`TextEndPayload`): TextEndPayloadid:stringUnique identifier for this text generationproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Reasoning Chunks
+
+### reasoning-start
+
+Signals the beginning of reasoning generation (for models that support reasoning).
+
+**type:** (`"reasoning-start"`): Chunk type identifier
+
+**payload:** (`ReasoningStartPayload`): ReasoningStartPayloadid:stringUnique identifier for this reasoning generationsignature?:stringReasoning signature if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### reasoning-delta
+
+Incremental reasoning text during generation.
+
+**type:** (`"reasoning-delta"`): Chunk type identifier
+
+**payload:** (`ReasoningDeltaPayload`): ReasoningDeltaPayloadid:stringUnique identifier for this reasoning generationtext:stringThe incremental reasoning textproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### reasoning-end
+
+Signals the end of reasoning generation.
+
+**type:** (`"reasoning-end"`): Chunk type identifier
+
+**payload:** (`ReasoningEndPayload`): ReasoningEndPayloadid:stringUnique identifier for this reasoning generationsignature?:stringFinal reasoning signature if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### reasoning-signature
+
+Contains the reasoning signature from models that support advanced reasoning (like OpenAI's o1 series). The signature represents metadata about the model's internal reasoning process, such as effort level or reasoning approach, but not the actual reasoning content itself.
+
+**type:** (`"reasoning-signature"`): Chunk type identifier
+
+**payload:** (`ReasoningSignaturePayload`): ReasoningSignaturePayloadid:stringUnique identifier for the reasoning sessionsignature:stringSignature describing the reasoning approach or effort level (e.g., reasoning effort settings)providerMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Tool Chunks
+
+### tool-call
+
+A tool is being called.
+
+**type:** (`"tool-call"`): Chunk type identifier
+
+**payload:** (`ToolCallPayload`): ToolCallPayloadtoolCallId:stringUnique identifier for this tool calltoolName:stringName of the tool being calledargs?:Record\<string, any>Arguments passed to the toolproviderExecuted?:booleanWhether the provider executed the tooloutput?:anyTool output if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-result
+
+Result from a tool execution.
+
+**type:** (`"tool-result"`): Chunk type identifier
+
+**payload:** (`ToolResultPayload`): ToolResultPayloadtoolCallId:stringUnique identifier for the tool calltoolName:stringName of the executed toolresult:anyThe result of the tool executionisError?:booleanWhether the result is an errorproviderExecuted?:booleanWhether the provider executed the toolargs?:Record\<string, any>Arguments that were passed to the toolproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-call-input-streaming-start
+
+Signals the start of streaming tool call arguments.
+
+**type:** (`"tool-call-input-streaming-start"`): Chunk type identifier
+
+**payload:** (`ToolCallInputStreamingStartPayload`): ToolCallInputStreamingStartPayloadtoolCallId:stringUnique identifier for this tool calltoolName:stringName of the tool being calledproviderExecuted?:booleanWhether the provider executed the tooldynamic?:booleanWhether the tool call is dynamicproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-call-delta
+
+Incremental tool call arguments during streaming.
+
+**type:** (`"tool-call-delta"`): Chunk type identifier
+
+**payload:** (`ToolCallDeltaPayload`): ToolCallDeltaPayloadargsTextDelta:stringIncremental text delta for tool argumentstoolCallId:stringUnique identifier for this tool calltoolName?:stringName of the tool being calledproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-call-input-streaming-end
+
+Signals the end of streaming tool call arguments.
+
+**type:** (`"tool-call-input-streaming-end"`): Chunk type identifier
+
+**payload:** (`ToolCallInputStreamingEndPayload`): ToolCallInputStreamingEndPayloadtoolCallId:stringUnique identifier for this tool callproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### tool-error
+
+An error occurred during tool execution.
+
+**type:** (`"tool-error"`): Chunk type identifier
+
+**payload:** (`ToolErrorPayload`): ToolErrorPayloadid?:stringOptional identifiertoolCallId:stringUnique identifier for the tool calltoolName:stringName of the tool that failedargs?:Record\<string, any>Arguments that were passed to the toolerror:unknownThe error that occurredproviderExecuted?:booleanWhether the provider executed the toolproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Source and File Chunks
+
+### source
+
+Contains source information for content.
+
+**type:** (`"source"`): Chunk type identifier
+
+**payload:** (`SourcePayload`): SourcePayloadid:stringUnique identifiersourceType:'url' | 'document'Type of sourcetitle:stringTitle of the sourcemimeType?:stringMIME type of the sourcefilename?:stringFilename if applicableurl?:stringURL if applicableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### file
+
+Contains file data.
+
+**type:** (`"file"`): Chunk type identifier
+
+**payload:** (`FilePayload`): FilePayloaddata:string | Uint8ArrayThe file database64?:stringBase64 encoded data if applicablemimeType:stringMIME type of the fileproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+## Control Chunks
+
+### start
+
+Signals the start of streaming.
+
+**type:** (`"start"`): Chunk type identifier
+
+**payload:** (`StartPayload`): StartPayload\[key: string]:anyAdditional start data
+
+### step-start
+
+Signals the start of a processing step.
+
+**type:** (`"step-start"`): Chunk type identifier
+
+**payload:** (`StepStartPayload`): StepStartPayloadmessageId?:stringOptional message identifierrequest:objectRequest information including body and other datawarnings?:LanguageModelV2CallWarning\[]Any warnings from the language model call
+
+### step-finish
+
+Signals the completion of a processing step.
+
+**type:** (`"step-finish"`): Chunk type identifier
+
+**payload:** (`StepFinishPayload`): StepFinishPayloadid?:stringOptional identifiermessageId?:stringOptional message identifierstepResult:objectStep execution result with reason, warnings, and continuation infooutput:objectOutput information including usage statisticsmetadata:objectExecution metadata including request and provider infototalUsage?:LanguageModelV2UsageTotal usage statisticsresponse?:LanguageModelV2ResponseMetadataResponse metadataproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata
+
+### raw
+
+Contains raw data from the provider.
+
+**type:** (`"raw"`): Chunk type identifier
+
+**payload:** (`RawPayload`): RawPayload\[key: string]:anyRaw data from the provider
+
+### finish
+
+Stream has completed successfully.
+
+**type:** (`"finish"`): Chunk type identifier
+
+**payload:** (`FinishPayload`): FinishPayloadstepResult:objectStep execution resultoutput:objectOutput information including usagemetadata:objectExecution metadatamessages:objectMessage historyresponse:objectResponse metadata and messages from the model provider
+
+### error
+
+An error occurred during streaming.
+
+**type:** (`"error"`): Chunk type identifier
+
+**payload:** (`ErrorPayload`): ErrorPayloaderror:unknownThe error that occurred
+
+### abort
+
+Stream was aborted.
+
+**type:** (`"abort"`): Chunk type identifier
+
+**payload:** (`AbortPayload`): AbortPayload\[key: string]:anyAdditional abort data
+
+## Object and Output Chunks
+
+### object
+
+Emitted when using output generation with defined schemas. Contains partial or complete structured data that conforms to the specified Zod or JSON schema. This chunk is typically skipped in some execution contexts and used for streaming structured object generation.
+
+**type:** (`"object"`): Chunk type identifier
+
+**object:** (`Partial<OUTPUT>`): Partial or complete structured data matching the defined schema. The type is determined by the OUTPUT schema parameter.
+
+### tool-output
+
+Contains output from agent or workflow execution, particularly used for tracking usage statistics and completion events. Often wraps other chunk types (like finish chunks) to provide nested execution context.
+
+**type:** (`"tool-output"`): Chunk type identifier
+
+**payload:** (`ToolOutputPayload`): ToolOutputPayloadoutput:ChunkTypeNested chunk data, often containing finish events with usage statistics
+
+### step-output
+
+Contains output from workflow step execution, used primarily for usage tracking and step completion events. Similar to tool-output but specifically for individual workflow steps.
+
+**type:** (`"step-output"`): Chunk type identifier
+
+**payload:** (`StepOutputPayload`): StepOutputPayloadoutput:ChunkTypeNested chunk data from step execution, typically containing finish events or other step results
+
+## Metadata and Special Chunks
+
+### response-metadata
+
+Contains metadata about the LLM provider's response. Emitted by some providers after text generation to provide additional context like model ID, timestamps, and response headers. This chunk is used internally for state tracking and doesn't affect message assembly.
+
+**type:** (`"response-metadata"`): Chunk type identifier
+
+**payload:** (`ResponseMetadataPayload`): ResponseMetadataPayloadsignature?:stringResponse signature if available\[key: string]:anyAdditional provider-specific metadata fields (e.g., id, modelId, timestamp, headers)
+
+### watch
+
+Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where `stream()` is used.
+
+**type:** (`"watch"`): Chunk type identifier
+
+**payload:** (`WatchPayload`): WatchPayloadworkflowState?:objectCurrent workflow execution state (when used in workflows)eventTimestamp?:numberTimestamp when the event occurred\[key: string]:anyAdditional monitoring and execution data
+
+### tripwire
+
+Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.
+
+**type:** (`"tripwire"`): Chunk type identifier
+
+**payload:** (`TripwirePayload`): TripwirePayloadreason:stringExplanation of why the content was blocked (e.g., 'Output processor blocked content')retry?:booleanWhether the processor requested a retry of the stepmetadata?:unknownAdditional metadata from the processor (e.g., scores, categories)processorId?:stringID of the processor that triggered the tripwire
+
+## Usage Example
+
+```typescript
+const stream = await agent.stream('Hello')
+
+for await (const chunk of stream.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta':
+      console.log('Text:', chunk.payload.text)
+      break
+
+    case 'tool-call':
+      console.log('Calling tool:', chunk.payload.toolName)
+      break
+
+    case 'tool-result':
+      console.log('Tool result:', chunk.payload.result)
+      break
+
+    case 'reasoning-delta':
+      console.log('Reasoning:', chunk.payload.text)
+      break
+
+    case 'finish':
+      console.log('Finished:', chunk.payload.stepResult.reason)
+      console.log('Usage:', chunk.payload.output.usage)
+      break
+
+    case 'error':
+      console.error('Error:', chunk.payload.error)
+      break
+  }
+}
+```
+
+## 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

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

@@ -0,0 +1,182 @@
+# MastraModelOutput
+
+The `MastraModelOutput` class is returned by [.stream()](https://mastra.ai/reference/streaming/agents/stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
+
+```typescript
+// MastraModelOutput is returned by agent.stream()
+const stream = await agent.stream('Hello world')
+```
+
+For setup and basic usage, see the [.stream()](https://mastra.ai/reference/streaming/agents/stream) method documentation.
+
+## Streaming Properties
+
+These properties provide real-time access to model outputs as they're generated:
+
+**fullStream:** (`ReadableStream<ChunkType<OUTPUT>>`): ReadableStreamChunkType:ChunkType\<OUTPUT>All possible chunk types that can be emitted during streaming
+
+**textStream:** (`ReadableStream<string>`): Stream of incremental text content only. Filters out all metadata, tool calls, and control chunks to provide just the text being generated.
+
+**objectStream:** (`ReadableStream<Partial<OUTPUT>>`): ReadableStreamPartialSchemaOutput:Partial\<OUTPUT>Partially completed object matching the defined schema
+
+**elementStream:** (`ReadableStream<OUTPUT extends (infer T)[] ? T : never>`): Stream of individual array elements when the output schema defines an array type. Each element is emitted as it's completed rather than waiting for the entire array.
+
+## Promise-based Properties
+
+These properties resolve to final values after the stream completes:
+
+**text:** (`Promise<string>`): The complete concatenated text response from the model. Resolves when text generation is finished.
+
+**object:** (`Promise<OUTPUT>`): PromiseInferSchemaOutput:OUTPUTFully typed object matching the exact schema definition
+
+**reasoning:** (`Promise<string>`): Complete reasoning text for models that support reasoning (like OpenAI's o1 series). Returns empty string for models without reasoning capability.
+
+**reasoningText:** (`Promise<string | undefined>`): Alternative access to reasoning content. May be undefined for models that don't support reasoning, while 'reasoning' returns empty string.
+
+**toolCalls:** (`Promise<ToolCallChunk[]>`): ToolCallChunktype:'tool-call'Chunk type identifierrunId:stringExecution run identifierfrom:ChunkFromSource of the chunk (AGENT, WORKFLOW, etc.)payload:ToolCallPayloadTool call data including toolCallId, toolName, args, and execution details
+
+**toolResults:** (`Promise<ToolResultChunk[]>`): ToolResultChunktype:'tool-result'Chunk type identifierrunId:stringExecution run identifierfrom:ChunkFromSource of the chunk (AGENT, WORKFLOW, etc.)payload:ToolResultPayloadTool result data including toolCallId, toolName, result, and error status
+
+**usage:** (`Promise<LanguageModelUsage>`): RecordinputTokens:numberTokens consumed by the input promptoutputTokens:numberTokens generated in the responsetotalTokens:numberSum of input and output tokensreasoningTokens?:numberHidden reasoning tokens (for reasoning models)cachedInputTokens?:numberNumber of input tokens that were a cache hit
+
+**finishReason:** (`Promise<string | undefined>`): enumstop:'stop'Model finished naturallylength:'length'Hit maximum token limittool\_calls:'tool\_calls'Model called toolscontent\_filter:'content\_filter'Content was filtered
+
+**response:** (`Promise<Response>`): Responseid?:stringResponse ID from the model providertimestamp?:DateResponse timestampmodelId?:stringModel identifier used for this responseheaders?:Record\<string, string>Response headers from the model providermessages?:ResponseMessage\[]Response messages in model formatuiMessages?:UIMessage\[]Response messages in UI format, includes any metadata added by output processors
+
+## Error Properties
+
+**error:** (`string | Error | { message: string; stack: string; } | undefined`): Error information if the stream encountered an error. Undefined if no errors occurred. Can be a string message, Error object, or serialized error with stack trace.
+
+## Methods
+
+**getFullOutput:** (`() => Promise<FullOutput>`): FullOutputtext:stringComplete text responseobject?:OUTPUTStructured output if schema was providedtoolCalls:ToolCallChunk\[]All tool call chunks madetoolResults:ToolResultChunk\[]All tool result chunksusage:Record\<string, number>Token usage statisticsreasoning?:stringReasoning text if availablefinishReason?:stringWhy generation finishedresponse:ResponseResponse metadata and messages from the model provider
+
+**consumeStream:** (`(options?: ConsumeStreamOptions) => Promise<void>`): ConsumeStreamOptionsonError?:(error: Error) => voidCallback for handling stream errors
+
+## Usage Examples
+
+### Basic Text Streaming
+
+```typescript
+const stream = await agent.stream('Write a haiku')
+
+// Stream text as it's generated
+for await (const text of stream.textStream) {
+  process.stdout.write(text)
+}
+
+// Or get the complete text
+const fullText = await stream.text
+console.log(fullText)
+```
+
+### Structured Output Streaming
+
+```typescript
+const stream = await agent.stream('Generate user data', {
+  structuredOutput: {
+    schema: z.object({
+      name: z.string(),
+      age: z.number(),
+      email: z.string(),
+    }),
+  },
+})
+
+// Stream partial objects
+for await (const partial of stream.objectStream) {
+  console.log('Progress:', partial) // { name: "John" }, { name: "John", age: 30 }, ...
+}
+
+// Get final validated object
+const user = await stream.object
+console.log('Final:', user) // { name: "John", age: 30, email: "john@example.com" }
+```
+
+````text
+### Tool Calls and Results
+
+```typescript
+const stream = await agent.stream("What's the weather in NYC?", {
+  tools: { weather: weatherTool }
+});
+
+// Monitor tool calls
+const toolCalls = await stream.toolCalls;
+const toolResults = await stream.toolResults;
+
+console.log("Tools called:", toolCalls);
+console.log("Results:", toolResults);
+````
+
+### Complete Output Access
+
+```typescript
+const stream = await agent.stream('Analyze this data')
+
+const output = await stream.getFullOutput()
+console.log({
+  text: output.text,
+  usage: output.usage,
+  reasoning: output.reasoning,
+  finishReason: output.finishReason,
+})
+```
+
+### Full Stream Processing
+
+```typescript
+const stream = await agent.stream('Complex task')
+
+for await (const chunk of stream.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta':
+      process.stdout.write(chunk.payload.text)
+      break
+    case 'tool-call':
+      console.log(`Calling ${chunk.payload.toolName}...`)
+      break
+    case 'reasoning-delta':
+      console.log(`Reasoning: ${chunk.payload.text}`)
+      break
+    case 'finish':
+      console.log(`Done! Reason: ${chunk.payload.stepResult.reason}`)
+      // Access response messages with any metadata added by output processors
+      const uiMessages = chunk.payload.response?.uiMessages
+      if (uiMessages) {
+        console.log('Response messages:', uiMessages)
+      }
+      break
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+const stream = await agent.stream('Analyze this data')
+
+try {
+  // Option 1: Handle errors in consumeStream
+  await stream.consumeStream({
+    onError: error => {
+      console.error('Stream error:', error)
+    },
+  })
+
+  const result = await stream.text
+} catch (error) {
+  console.error('Failed to get result:', error)
+}
+
+// Option 2: Check error property
+const result = await stream.getFullOutput()
+if (stream.error) {
+  console.error('Stream had errors:', 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