@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-observability-tracing-processors-sensitive-data-filter.md

@@ -0,0 +1,144 @@
+# SensitiveDataFilter
+
+A SpanOutputProcessor that redacts sensitive information from span fields.
+
+## Constructor
+
+```typescript
+new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
+```
+
+## SensitiveDataFilterOptions
+
+```typescript
+interface SensitiveDataFilterOptions {
+  /**
+   * List of sensitive field names to redact.
+   * Matching is case-insensitive and normalizes separators
+   * (api-key, api_key, Api Key → apikey).
+   * Defaults include: password, token, secret, key, apikey, auth,
+   * authorization, bearer, bearertoken, jwt, credential,
+   * clientsecret, privatekey, refresh, ssn.
+   */
+  sensitiveFields?: string[]
+
+  /**
+   * The token used for full redaction.
+   * Default: "[REDACTED]"
+   */
+  redactionToken?: string
+
+  /**
+   * Style of redaction to use:
+   * - "full": always replace with redactionToken
+   * - "partial": show 3 characters from the start and end, redact the middle
+   * Default: "full"
+   */
+  redactionStyle?: RedactionStyle
+}
+```
+
+## RedactionStyle
+
+```typescript
+type RedactionStyle = 'full' | 'partial'
+```
+
+## Methods
+
+### process
+
+```typescript
+process(span: AnySpan): AnySpan
+```
+
+Process a span by filtering sensitive data across its key fields: attributes, metadata, input, output, and errorInfo.
+
+**Returns:** A new span with sensitive values redacted.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+No cleanup needed for this processor.
+
+## Properties
+
+```typescript
+readonly name = 'sensitive-data-filter';
+```
+
+## Default Sensitive Fields
+
+When no custom fields are provided:
+
+```typescript
+[
+  'password',
+  'token',
+  'secret',
+  'key',
+  'apikey',
+  'auth',
+  'authorization',
+  'bearer',
+  'bearertoken',
+  'jwt',
+  'credential',
+  'clientsecret',
+  'privatekey',
+  'refresh',
+  'ssn',
+]
+```
+
+## Processing Behavior
+
+### Field Matching
+
+- **Case-insensitive**: `APIKey`, `apikey`, `ApiKey` all match
+
+- **Separator-agnostic**: `api-key`, `api_key`, `apiKey` are treated identically
+
+- **Exact matching**: After normalization, fields must match exactly
+
+  - `token` matches `token`, `Token`, `TOKEN`
+  - `token` does NOT match `promptTokens` or `tokenCount`
+
+### Redaction Styles
+
+#### Full Redaction (default)
+
+All matched values replaced with redactionToken.
+
+#### Partial Redaction
+
+- Shows first 3 and last 3 characters
+- Values ≤ 6 characters are fully redacted
+- Non-string values are converted to strings before partial redaction
+
+### Error Handling
+
+If filtering a field fails, the field is replaced with:
+
+```typescript
+{
+  error: {
+    processor: 'sensitive-data-filter'
+  }
+}
+```
+
+### Processed Fields
+
+The filter recursively processes:
+
+- `span.attributes` - Span metadata and properties
+- `span.metadata` - Custom metadata
+- `span.input` - Input data
+- `span.output` - Output data
+- `span.errorInfo` - Error information
+
+Handles nested objects, arrays, and circular references safely.

package/dist/docs/references/reference-observability-tracing-spans.md

@@ -0,0 +1,224 @@
+# Spans
+
+## BaseSpan
+
+Base interface for all span types.
+
+```typescript
+interface BaseSpan<TType extends SpanType> {
+  /** Unique span identifier */
+  id: string
+
+  /** OpenTelemetry-compatible trace ID (32 hex chars) */
+  traceId: string
+
+  /** Name of the span */
+  name: string
+
+  /** Type of the span */
+  type: TType
+
+  /** When span started */
+  startTime: Date
+
+  /** When span ended */
+  endTime?: Date
+
+  /** Type-specific attributes */
+  attributes?: SpanTypeMap[TType]
+
+  /** User-defined metadata */
+  metadata?: Record<string, any>
+
+  /** Input passed at the start of the span */
+  input?: any
+
+  /** Output generated at the end of the span */
+  output?: any
+
+  /** Error information if span failed */
+  errorInfo?: {
+    message: string
+    id?: string
+    domain?: string
+    category?: string
+    details?: Record<string, any>
+  }
+
+  /** Is an event span? (occurs at startTime, has no endTime) */
+  isEvent: boolean
+}
+```
+
+## Span
+
+Span interface, used internally for tracing. Extends BaseSpan with lifecycle methods and properties.
+
+```typescript
+interface Span<TType extends SpanType> extends BaseSpan<TType> {
+  /** Is an internal span? (spans internal to the operation of mastra) */
+  isInternal: boolean
+
+  /** Parent span reference (undefined for root spans) */
+  parent?: AnySpan
+
+  /** Pointer to the ObservabilityInstance instance */
+  observabilityInstance: ObservabilityInstance
+}
+```
+
+### Properties
+
+```typescript
+/** Returns TRUE if the span is the root span of a trace */
+get isRootSpan(): boolean
+
+/** Returns TRUE if the span is a valid span (not a NO-OP Span) */
+get isValid(): boolean
+
+/** Get the closest parent spanId that isn't an internal span */
+getParentSpanId(includeInternalSpans?: boolean): string | undefined
+
+/** Returns a lightweight span ready for export */
+exportSpan(includeInternalSpans?: boolean): ExportedSpan<TType> | undefined
+```
+
+### Methods
+
+#### end
+
+```typescript
+end(options?: EndSpanOptions<TType>): void
+```
+
+Ends the span and triggers export to configured exporters. Sets the `endTime` and optionally updates `output`, `metadata`, and `attributes`.
+
+#### error
+
+```typescript
+error(options: ErrorSpanOptions<TType>): void
+```
+
+Records an error on the span. Sets the `errorInfo` field and can optionally end the span.
+
+#### update
+
+```typescript
+update(options: UpdateSpanOptions<TType>): void
+```
+
+Updates span data while it's still active. Can modify `input`, `output`, `metadata`, and `attributes`.
+
+#### createChildSpan
+
+```typescript
+createChildSpan<TChildType extends SpanType>(
+  options: ChildSpanOptions<TChildType>
+): Span<TChildType>
+```
+
+Creates a child span under this span. Child spans track sub-operations and inherit the trace context.
+
+#### createEventSpan
+
+```typescript
+createEventSpan<TChildType extends SpanType>(
+  options: ChildEventOptions<TChildType>
+): Span<TChildType>
+```
+
+Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.
+
+## ExportedSpan
+
+Exported Span interface, used for tracing exporters. A lightweight version of Span without methods or circular references.
+
+```typescript
+interface ExportedSpan<TType extends SpanType> extends BaseSpan<TType> {
+  /** Parent span id reference (undefined for root spans) */
+  parentSpanId?: string
+
+  /** TRUE if the span is the root span of a trace */
+  isRootSpan: boolean
+}
+```
+
+## Span Lifecycle Events
+
+Events emitted during the span lifecycle.
+
+### TracingEventType
+
+```typescript
+enum TracingEventType {
+  /** Emitted when a span is created and started */
+  SPAN_STARTED = 'span_started',
+
+  /** Emitted when a span is updated via update() */
+  SPAN_UPDATED = 'span_updated',
+
+  /** Emitted when a span is ended via end() or error() */
+  SPAN_ENDED = 'span_ended',
+}
+```
+
+### TracingEvent
+
+```typescript
+type TracingEvent =
+  | { type: 'span_started'; exportedSpan: AnyExportedSpan }
+  | { type: 'span_updated'; exportedSpan: AnyExportedSpan }
+  | { type: 'span_ended'; exportedSpan: AnyExportedSpan }
+```
+
+Exporters receive these events to process and send trace data to observability platforms.
+
+## Union Types
+
+### AnySpan
+
+```typescript
+type AnySpan = Span<keyof SpanTypeMap>
+```
+
+Union type for cases that need to handle any span type.
+
+### AnyExportedSpan
+
+```typescript
+type AnyExportedSpan = ExportedSpan<keyof SpanTypeMap>
+```
+
+Union type for cases that need to handle any exported span type.
+
+## NO-OP Spans
+
+When tracing is disabled (sampling returns false), NO-OP spans are returned:
+
+### NoOpSpan
+
+```typescript
+class NoOpSpan<TType extends SpanType> extends BaseSpan<TType>
+```
+
+A span that performs no operations. All methods are no-ops:
+
+- `id` returns `'no-op'`
+- `traceId` returns `'no-op-trace'`
+- `isValid` returns `false`
+- `end()`, `error()`, `update()` do nothing
+- `createChildSpan()` returns another NO-OP span
+
+## See Also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Concepts and usage
+- [Creating Child Spans](https://mastra.ai/docs/observability/tracing/overview) - Practical examples
+- [Retrieving Trace IDs](https://mastra.ai/docs/observability/tracing/overview) - Using trace IDs
+
+### Reference
+
+- [Tracing Classes](https://mastra.ai/reference/observability/tracing/instances) - Core tracing classes
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) - Complete type reference
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration) - Configuration options

package/dist/docs/references/reference-processors-batch-parts-processor.md

@@ -0,0 +1,61 @@
+# BatchPartsProcessor
+
+The `BatchPartsProcessor` is an **output processor** that batches multiple stream parts together to reduce the frequency of emissions during streaming. This processor is useful for reducing network overhead, improving user experience by consolidating small text chunks, and optimizing streaming performance by controlling when parts are emitted to the client.
+
+## Usage example
+
+```typescript
+import { BatchPartsProcessor } from '@mastra/core/processors'
+
+const processor = new BatchPartsProcessor({
+  batchSize: 5,
+  maxWaitTime: 100,
+  emitOnNonText: true,
+})
+```
+
+## Constructor parameters
+
+**options?:** (`Options`): Configuration options for batching stream parts
+
+### Options
+
+**batchSize?:** (`number`): Number of parts to batch together before emitting
+
+**maxWaitTime?:** (`number`): Maximum time to wait before emitting a batch (in milliseconds). If set, will emit the current batch even if it hasn't reached batchSize
+
+**emitOnNonText?:** (`boolean`): Whether to emit immediately when a non-text part is encountered
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'batch-parts'
+
+**name?:** (`string`): Optional processor display name
+
+**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to batch them together
+
+**flush:** (`(state?: BatchPartsState) => ChunkType | null`): Force flush any remaining batched parts when the stream ends
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { BatchPartsProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'batched-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.1',
+  outputProcessors: [
+    new BatchPartsProcessor({
+      batchSize: 5,
+      maxWaitTime: 100,
+      emitOnNonText: true,
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-language-detector.md

@@ -0,0 +1,82 @@
+# LanguageDetector
+
+The `LanguageDetector` is an **input processor** that identifies the language of input text and optionally translates it to a target language for consistent processing. This processor helps maintain language consistency by detecting the language of incoming messages and providing flexible strategies for handling multilingual content, including automatic translation to ensure all content is processed in the target language.
+
+## Usage example
+
+```typescript
+import { LanguageDetector } from '@mastra/core/processors'
+
+const processor = new LanguageDetector({
+  model: 'openrouter/openai/gpt-oss-safeguard-20b',
+  targetLanguages: ['English', 'en'],
+  threshold: 0.8,
+  strategy: 'translate',
+})
+```
+
+## Constructor parameters
+
+**options:** (`Options`): Configuration options for language detection and translation
+
+### Options
+
+**model:** (`MastraModelConfig`): Model configuration for the detection/translation agent
+
+**targetLanguages?:** (`string[]`): Target language(s) for the project. If content is detected in a different language, it may be translated. Can be language name ('English') or ISO code ('en')
+
+**threshold?:** (`number`): Confidence threshold for language detection (0-1). Only process when detection confidence exceeds this threshold
+
+**strategy?:** (`'detect' | 'translate' | 'block' | 'warn'`): Strategy when non-target language is detected: 'detect' only detects language, 'translate' automatically translates to target language, 'block' rejects content not in target language, 'warn' logs warning but allows through
+
+**preserveOriginal?:** (`boolean`): Whether to preserve original content in message metadata. Useful for audit trails and debugging
+
+**instructions?:** (`string`): Custom detection instructions for the agent. If not provided, uses default instructions
+
+**minTextLength?:** (`number`): Minimum text length to perform detection. Short text is often unreliable for language detection
+
+**includeDetectionDetails?:** (`boolean`): Whether to include detailed detection info in logs
+
+**translationQuality?:** (`'speed' | 'quality' | 'balanced'`): Translation quality preference: 'speed' prioritizes fast translation, 'quality' prioritizes accuracy, 'balanced' balances between speed and quality
+
+**providerOptions?:** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'language-detector'
+
+**name?:** (`string`): Optional processor display name
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect language and optionally translate content before sending to LLM
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { LanguageDetector } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  id: 'multilingual-agent',
+  name: 'multilingual-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.1',
+  inputProcessors: [
+    new LanguageDetector({
+      model: 'openrouter/openai/gpt-oss-safeguard-20b',
+      targetLanguages: ['English', 'en'],
+      threshold: 0.8,
+      strategy: 'translate',
+      preserveOriginal: true,
+      instructions:
+        'Detect language and translate non-English content to English while preserving original intent',
+      minTextLength: 10,
+      includeDetectionDetails: true,
+      translationQuality: 'quality',
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-message-history-processor.md

@@ -0,0 +1,85 @@
+# MessageHistory
+
+The `MessageHistory` is a **hybrid processor** that handles both retrieval and persistence of message history. On input, it fetches historical messages from storage and prepends them to the conversation. On output, it persists new messages to storage.
+
+## Usage example
+
+```typescript
+import { MessageHistory } from '@mastra/core/processors'
+
+const processor = new MessageHistory({
+  storage: memoryStorage,
+  lastMessages: 50,
+})
+```
+
+## Constructor parameters
+
+**options:** (`MessageHistoryOptions`): Configuration options for the message history processor
+
+### Options
+
+**storage:** (`MemoryStorage`): Storage instance for retrieving and persisting messages
+
+**lastMessages?:** (`number`): Maximum number of historical messages to retrieve. If not specified, retrieves all messages
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'message-history'
+
+**name:** (`string`): Processor display name set to 'MessageHistory'
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Fetches historical messages from storage and adds them to the message list
+
+**processOutputResult:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList>`): Persists new messages (user input and assistant response) to storage, excluding system messages
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { MessageHistory } from '@mastra/core/processors'
+import { PostgresStorage } from '@mastra/pg'
+
+const storage = new PostgresStorage({
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const agent = new Agent({
+  name: 'memory-agent',
+  instructions: 'You are a helpful assistant with conversation memory',
+  model: 'openai:gpt-4o',
+  inputProcessors: [
+    new MessageHistory({
+      storage,
+      lastMessages: 100,
+    }),
+  ],
+  outputProcessors: [
+    new MessageHistory({
+      storage,
+    }),
+  ],
+})
+```
+
+## Behavior
+
+### Input processing
+
+1. Retrieves `threadId` from the request context
+2. Fetches historical messages from storage (ordered by creation date, descending)
+3. Filters out system messages (they should not be stored in the database)
+4. Merges historical messages with incoming messages, avoiding duplicates by ID
+5. Adds historical messages with `source: 'memory'` tag
+
+### Output processing
+
+1. Retrieves `threadId` from the request context
+2. Skips persistence if `readOnly` is set in memory config
+3. Filters out incomplete tool calls from messages
+4. Persists new user input and assistant response messages to storage
+5. Updates the thread's `updatedAt` timestamp
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-moderation-processor.md

@@ -0,0 +1,104 @@
+# ModerationProcessor
+
+The `ModerationProcessor` is a **hybrid processor** that can be used for both input and output processing to provide content moderation using an LLM to detect inappropriate content across multiple categories. This processor helps maintain content safety by evaluating messages against configurable moderation categories with flexible strategies for handling flagged content.
+
+## Usage example
+
+```typescript
+import { ModerationProcessor } from '@mastra/core/processors'
+
+const processor = new ModerationProcessor({
+  model: 'openrouter/openai/gpt-oss-safeguard-20b',
+  threshold: 0.7,
+  strategy: 'block',
+  categories: ['hate', 'harassment', 'violence'],
+})
+```
+
+## Constructor parameters
+
+**options:** (`Options`): Configuration options for content moderation
+
+### Options
+
+**model:** (`MastraModelConfig`): Model configuration for the moderation agent
+
+**categories?:** (`string[]`): Categories to check for moderation. If not specified, uses default OpenAI categories
+
+**threshold?:** (`number`): Confidence threshold for flagging (0-1). Content is flagged if any category score exceeds this threshold
+
+**strategy?:** (`'block' | 'warn' | 'filter'`): Strategy when content is flagged: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages
+
+**instructions?:** (`string`): Custom moderation instructions for the agent. If not provided, uses default instructions based on categories
+
+**includeScores?:** (`boolean`): Whether to include confidence scores in logs. Useful for tuning thresholds and debugging
+
+**chunkWindow?:** (`number`): Number of previous chunks to include for context when moderating stream chunks. If set to 1, includes the previous part, etc.
+
+**providerOptions?:** (`ProviderOptions`): Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'moderation'
+
+**name?:** (`string`): Optional processor display name
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to moderate content before sending to LLM
+
+**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>`): Processes streaming output parts to moderate content during streaming
+
+## Extended usage example
+
+### Input processing
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ModerationProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'moderated-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.1',
+  inputProcessors: [
+    new ModerationProcessor({
+      model: 'openrouter/openai/gpt-oss-safeguard-20b',
+      categories: ['hate', 'harassment', 'violence'],
+      threshold: 0.7,
+      strategy: 'block',
+      instructions: 'Detect and flag inappropriate content in user messages',
+      includeScores: true,
+    }),
+  ],
+})
+```
+
+### Output processing with batching
+
+When using `ModerationProcessor` as an output processor, it's recommended to combine it with `BatchPartsProcessor` to optimize performance. The `BatchPartsProcessor` batches stream chunks together before passing them to the moderator, reducing the number of LLM calls required for moderation.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { BatchPartsProcessor, ModerationProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'output-moderated-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.1',
+  outputProcessors: [
+    // Batch stream parts first to reduce LLM calls
+    new BatchPartsProcessor({
+      batchSize: 10,
+    }),
+    // Then apply moderation on batched content
+    new ModerationProcessor({
+      model: 'openrouter/openai/gpt-oss-safeguard-20b',
+      strategy: 'filter',
+      chunkWindow: 1,
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)