@mastra/mcp-docs-server 1.2.25-alpha.3 → 1.2.25-alpha.6

package/.docs/reference/observability/tracing/interfaces.md

@@ -53,7 +53,7 @@ For ClickHouse vNext, the method records the complete predicate and waits for li
 
 ### `SpanTypeMap`
 
-Mapping of span types to their corresponding attribute interfaces.
+Mapping of span types to their corresponding attribute interfaces. The list below is abbreviated. The `SpanTypeMap` interface in `@mastra/core/observability` is the complete one.
 
 ```typescript
 interface SpanTypeMap {
@@ -61,6 +61,7 @@ interface SpanTypeMap {
   WORKFLOW_RUN: WorkflowRunAttributes
   MODEL_GENERATION: ModelGenerationAttributes
   MODEL_STEP: ModelStepAttributes
+  MODEL_INFERENCE: ModelInferenceAttributes
   MODEL_CHUNK: ModelChunkAttributes
   TOOL_CALL: ToolCallAttributes
   CLIENT_TOOL_CALL: ClientToolCallAttributes
@@ -85,6 +86,70 @@ interface SpanTypeMap {
 
 This mapping defines which attribute interface is used for each span type when creating or processing spans.
 
+### `SpanInputMap` and `SpanOutputMap`
+
+Mapping of the span types whose `input` and `output` Mastra writes itself with a fixed shape. Every other span type keeps `any`: tool arguments and workflow data are caller-defined, `MODEL_CHUNK` carries several chunk shapes on one span type, and `GENERIC` is the escape hatch for custom spans.
+
+```typescript
+interface SpanInputMap {
+  AGENT_RUN: AgentRunInput
+  MODEL_GENERATION: ModelGenerationInput
+  MODEL_STEP: ModelStepInput
+  MODEL_INFERENCE: ModelStepInput
+}
+
+interface SpanOutputMap {
+  AGENT_RUN: AgentRunOutput
+  MODEL_GENERATION: ModelGenerationOutput
+  MODEL_STEP: ModelStepOutput
+  MODEL_INFERENCE: ModelStepResult
+}
+
+/** The mapped shape when the map lists the type, otherwise `any` */
+type SpanInput<TType extends SpanType> = TType extends keyof SpanInputMap
+  ? SpanInputMap[TType]
+  : any
+type SpanOutput<TType extends SpanType> = TType extends keyof SpanOutputMap
+  ? SpanOutputMap[TType]
+  : any
+```
+
+Narrow a span by its type to read the typed payload. On a stored `SpanRecord`, use `isSpanRecordOfType`:
+
+```typescript
+import { SpanType, isSpanRecordOfType } from '@mastra/core/observability'
+
+if (isSpanRecordOfType(span, SpanType.MODEL_GENERATION)) {
+  span.input?.messages // MessageListInput
+  span.attributes?.usage // UsageStats | undefined
+}
+```
+
+To pick a renderer without checking shapes yourself, describe the payload. The tag is derived at read time from `spanType` and the value's shape. Nothing is stored.
+
+```typescript
+import {
+  describeSpanError,
+  describeSpanInput,
+  describeSpanOutput,
+} from '@mastra/core/observability'
+
+const input = describeSpanInput(span)
+// { type: 'text' | 'messages' | 'agent-run-resume' | 'json'; value } | undefined
+
+const output = describeSpanOutput(span)
+// { type: 'interrupted' | 'agent-run-result' | 'model-generation-result' | 'model-step-result' | 'text' | 'json'; value } | undefined
+
+switch (output?.type) {
+  case 'interrupted':
+    return output.value.status // 'suspended' | 'aborted'
+  case 'model-generation-result':
+    return output.value.text
+}
+
+describeSpanError(span) // SpanErrorInfo | undefined
+```
+
 ### Span
 
 Span interface, used internally for tracing.
@@ -107,8 +172,8 @@ interface Span<TType extends SpanType> {
 
   attributes?: SpanTypeMap[TType]
   metadata?: Record<string, any>
-  input?: any
-  output?: any
+  input?: SpanInput<TType>
+  output?: SpanOutput<TType>
   errorInfo?: any
 
   /** Tags for categorizing traces (only present on root spans) */
@@ -298,7 +363,7 @@ interface SpanOutputProcessor {
 
 ### `SpanType`
 
-AI-specific span types with their associated metadata.
+AI-specific span types with their associated metadata. The list below is abbreviated. The `SpanType` enum in `@mastra/core/observability` is the complete one.
 
 ```typescript
 enum SpanType {
@@ -314,6 +379,9 @@ enum SpanType {
   /** Single model execution step within a generation (one API call) */
   MODEL_STEP = 'model_step',
 
+  /** Model provider call within a step - wraps only the inference, excluding processors and tool executions */
+  MODEL_INFERENCE = 'model_inference',
+
   /** Individual model streaming chunk/event */
   MODEL_CHUNK = 'model_chunk',
 
@@ -627,6 +695,125 @@ interface WorkflowStepAttributes {
 }
 ```
 
+## Span payloads
+
+### `AgentRunInput`
+
+Input recorded on `AGENT_RUN` spans: the messages the caller passed for a fresh run, or the resume data for a resumed run.
+
+```typescript
+type AgentRunInput = MessageListInput | { messages: MessageListInput } | AgentRunResumeInput
+
+interface AgentRunResumeInput {
+  /** Resume data, kept nested when it names a different tool than the suspended one */
+  resumeData?: unknown
+  /** Tool the run resumes into */
+  toolName?: string
+  /** Tool call the run resumes into */
+  toolCallId?: string
+  [key: string]: unknown
+}
+```
+
+### `AgentRunOutput`
+
+Output recorded on `AGENT_RUN` spans.
+
+```typescript
+type AgentRunOutput = AgentRunResult | InterruptedSpanOutput
+
+interface AgentRunResult {
+  /** Final response text */
+  text?: string
+  /** Final structured output */
+  object?: unknown
+  /** Generated files */
+  files?: unknown[]
+  /** Tripwire that aborted the run */
+  tripwire?: StepTripwireData
+}
+```
+
+### `ModelGenerationInput`
+
+Input recorded on `MODEL_GENERATION` spans.
+
+Mastra's own loop records the normalized model messages, system messages first. SDK agents record the raw messages the caller passed, so `messages` keeps the full `MessageListInput` shape.
+
+```typescript
+interface ModelGenerationInput {
+  /** Messages sent to the model */
+  messages: MessageListInput
+  /** Output schema, when structured output was requested */
+  schema?: unknown
+}
+```
+
+### `ModelGenerationOutput`
+
+Output recorded on `MODEL_GENERATION` spans: a `ModelGenerationResult` when the generation finishes, or an `InterruptedSpanOutput` when the run stops first. Every field of `ModelGenerationResult` is optional: a durable run records only `text`.
+
+```typescript
+type ModelGenerationOutput = ModelGenerationResult | InterruptedSpanOutput
+
+interface ModelGenerationResult {
+  text?: string
+  object?: unknown
+  reasoning?: unknown
+  reasoningText?: string
+  files?: unknown[]
+  sources?: unknown[]
+  toolCalls?: unknown[]
+  warnings?: unknown[]
+}
+```
+
+### `ModelStepInput`
+
+Input recorded on `MODEL_STEP` and `MODEL_INFERENCE` spans: a shallow preview of what the step sent to the model.
+
+```typescript
+type ModelStepInput = ModelStepMessage[] | Record<string, unknown> | string
+
+interface ModelStepMessage {
+  /** Message role (e.g., 'system', 'user', 'assistant', 'tool') */
+  role: string
+  /** Message text, with non-text parts summarized */
+  content: string
+}
+```
+
+### `ModelStepOutput`
+
+Output recorded on `MODEL_STEP` spans. A finished step records a `ModelStepResult`, which is the step output without `usage` (that lives on the attributes). A step cut short by a suspension or an abort records an `InterruptedSpanOutput` instead. `MODEL_INFERENCE` spans always record a `ModelStepResult`.
+
+```typescript
+type ModelStepOutput = ModelStepResult | InterruptedSpanOutput
+
+interface ModelStepResult {
+  text?: string
+  toolCalls?: unknown[]
+  steps?: unknown[]
+  object?: unknown
+}
+```
+
+### `InterruptedSpanOutput`
+
+Output recorded on `AGENT_RUN`, `MODEL_GENERATION` and `MODEL_STEP` spans when the run stops before the span's own result exists: a durable run suspended, or the caller aborted. `MODEL_INFERENCE` spans never carry it.
+
+```typescript
+interface InterruptedSpanOutput {
+  status: 'suspended' | 'aborted'
+  /** Why the run stopped */
+  reason?: string
+  /** Tool that suspended the run */
+  toolName?: string
+  /** Tool call that suspended the run */
+  toolCallId?: string
+}
+```
+
 ## Options types
 
 ### `StartSpanOptions`
@@ -648,7 +835,7 @@ interface StartSpanOptions<TType extends SpanType> {
   metadata?: Record<string, any>
 
   /** Input data */
-  input?: any
+  input?: SpanInput<TType>
 
   /** Parent span */
   parent?: AnySpan
@@ -674,10 +861,10 @@ interface UpdateSpanOptions<TType extends SpanType> {
   metadata?: Record<string, any>
 
   /** Input data */
-  input?: any
+  input?: SpanInput<TType>
 
   /** Output data */
-  output?: any
+  output?: SpanOutput<TType>
 }
 ```
 
@@ -688,7 +875,7 @@ Options for ending spans.
 ```typescript
 interface EndSpanOptions<TType extends SpanType> {
   /** Output data */
-  output?: any
+  output?: SpanOutput<TType>
 
   /** Span metadata */
   metadata?: Record<string, any>

package/.docs/reference/observability/tracing/spans.md

@@ -35,10 +35,10 @@ interface BaseSpan<TType extends SpanType> {
   metadata?: Record<string, any>
 
   /** Input passed at the start of the span */
-  input?: any
+  input?: SpanInput<TType>
 
   /** Output generated at the end of the span */
-  output?: any
+  output?: SpanOutput<TType>
 
   /** Error information if span failed */
   errorInfo?: {

package/.docs/reference/voice/voice.connect.md

@@ -13,27 +13,14 @@ import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
 import Speaker from '@mastra/node-speaker'
 
 const speaker = new Speaker({
-  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
-  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
-  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
+  sampleRate: 24000,
+  channels: 1,
+  bitDepth: 16,
 })
 
-// Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
-  realtimeConfig: {
-    model: 'gpt-5.1-realtime',
-    apiKey: process.env.OPENAI_API_KEY,
-    options: {
-      sessionConfig: {
-        turn_detection: {
-          type: 'server_vad',
-          threshold: 0.6,
-          silence_duration_ms: 1200,
-        },
-      },
-    },
-  },
-  speaker: 'alloy', // Default voice
+  apiKey: process.env.OPENAI_API_KEY,
+  speaker: 'alloy',
 })
 // Connect to the real-time service
 await voice.connect()
@@ -41,11 +28,6 @@ await voice.connect()
 voice.on('speaker', stream => {
   stream.pipe(speaker)
 })
-// With connection options
-await voice.connect({
-  timeout: 10000, // 10 seconds timeout
-  reconnect: true,
-})
 ```
 
 ## Parameters
@@ -58,19 +40,46 @@ Returns a `Promise<void>` that resolves when the connection is successfully esta
 
 ## Provider-specific options
 
-Each real-time voice provider may support different options for the `connect()` method:
+Connection configuration depends on the real-time voice provider.
 
 ### OpenAI Realtime
 
-**options** (`Options`): Configuration options.
+`connect()` accepts an optional `requestContext` for tool execution:
+
+**options.requestContext** (`RequestContext`): Runtime context passed to tools called during the session.
+
+See [Request context](https://mastra.ai/docs/server/request-context) for how to populate runtime values.
+
+Set `connectTimeoutMs` in the `OpenAIRealtimeVoice` constructor, not in the `connect()` call:
+
+**connectTimeoutMs** (`number`): Connection handshake deadline in milliseconds. Must be a positive, finite number no greater than 2,147,483,647. Applies only to connection setup, not to an established session. (Default: `15000`)
+
+## Connection failures
+
+For OpenAI Realtime, `connect()` waits for both the WebSocket to open and the server to create a session. It rejects if the connection fails, the server reports an error during the handshake, or the socket closes before the session is ready. A silent handshake times out after 15,000 milliseconds by default.
+
+Catch connection failures directly. An `error` event listener doesn't replace handling the rejected promise:
 
-**options.timeout** (`number`): Connection timeout in milliseconds
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+
+const voice = new OpenAIRealtimeVoice({
+  apiKey: process.env.OPENAI_API_KEY,
+  connectTimeoutMs: 30_000,
+})
+
+try {
+  await voice.connect()
+} catch (error) {
+  console.error('Could not connect to the realtime service:', error)
+}
+```
 
-**options.reconnect** (`boolean`): Whether to automatically reconnect on connection loss
+A failed handshake closes its socket and clears its pending waits. You can retry with `connect()` on the same instance.
 
 ## Using with `CompositeVoice`
 
-When using `CompositeVoice`, the `connect()` method delegates to the configured real-time provider:
+When using `CompositeVoice`, the `connect()` method forwards its options to the configured real-time provider. It throws if no real-time provider is configured:
 
 ```typescript
 import { CompositeVoice } from '@mastra/core/voice'
@@ -86,7 +95,7 @@ await voice.connect()
 ## Notes
 
 - This method is only implemented by real-time voice providers that support speech-to-speech capabilities
-- If called on a voice provider that doesn't support this functionality, it will log a warning and resolve immediately
+- Providers that inherit the base `connect()` implementation log a debug message and resolve without establishing a connection
 - The connection must be established before using other real-time methods like `send()` or `answer()`
 - When you're done with the voice instance, call `close()` to properly clean up resources
 - Some providers may automatically reconnect on connection loss, depending on their implementation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.25-alpha.3",
+  "version": "1.2.25-alpha.6",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.66.0-alpha.1",
+    "@mastra/core": "1.66.0-alpha.3",
     "@mastra/mcp": "^1.17.3"
   },
   "devDependencies": {
@@ -44,9 +44,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.131",
     "@internal/types-builder": "0.0.106",
-    "@mastra/core": "1.66.0-alpha.1"
+    "@internal/lint": "0.0.131",
+    "@mastra/core": "1.66.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {