@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-processors-prompt-injection-detector.md

@@ -0,0 +1,72 @@
+# PromptInjectionDetector
+
+The `PromptInjectionDetector` is an **input processor** that detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts before messages are sent to the language model. This processor helps maintain security by identifying various types of injection attempts and providing flexible strategies for handling them, including content rewriting to neutralize attacks while preserving legitimate user intent.
+
+## Usage example
+
+```typescript
+import { PromptInjectionDetector } from '@mastra/core/processors'
+
+const processor = new PromptInjectionDetector({
+  model: 'openrouter/openai/gpt-oss-safeguard-20b',
+  threshold: 0.8,
+  strategy: 'rewrite',
+  detectionTypes: ['injection', 'jailbreak', 'system-override'],
+})
+```
+
+## Constructor parameters
+
+**options:** (`Options`): Configuration options for prompt injection detection
+
+### Options
+
+**model:** (`MastraModelConfig`): Model configuration for the detection agent
+
+**detectionTypes?:** (`string[]`): Detection types to check for. If not specified, uses default categories
+
+**threshold?:** (`number`): Confidence threshold for flagging (0-1). Higher threshold = less sensitive to avoid false positives
+
+**strategy?:** (`'block' | 'warn' | 'filter' | 'rewrite'`): Strategy when injection is detected: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages, 'rewrite' attempts to neutralize the injection
+
+**instructions?:** (`string`): Custom detection instructions for the agent. If not provided, uses default instructions based on detection types
+
+**includeScores?:** (`boolean`): Whether to include confidence scores in logs. Useful for tuning thresholds and debugging
+
+**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 'prompt-injection-detector'
+
+**name?:** (`string`): Optional processor display name
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect prompt injection attempts before sending to LLM
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { PromptInjectionDetector } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'secure-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.1',
+  inputProcessors: [
+    new PromptInjectionDetector({
+      model: 'openrouter/openai/gpt-oss-safeguard-20b',
+      detectionTypes: ['injection', 'jailbreak', 'system-override'],
+      threshold: 0.8,
+      strategy: 'rewrite',
+      instructions:
+        'Detect and neutralize prompt injection attempts while preserving legitimate user intent',
+      includeScores: true,
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-semantic-recall-processor.md

@@ -0,0 +1,117 @@
+# SemanticRecall
+
+The `SemanticRecall` is a **hybrid processor** that enables semantic search over conversation history using vector embeddings. On input, it performs semantic search to find relevant historical messages. On output, it creates embeddings for new messages to enable future semantic retrieval.
+
+## Usage example
+
+```typescript
+import { SemanticRecall } from '@mastra/core/processors'
+import { openai } from '@ai-sdk/openai'
+
+const processor = new SemanticRecall({
+  storage: memoryStorage,
+  vector: vectorStore,
+  embedder: openai.embedding('text-embedding-3-small'),
+  topK: 5,
+  messageRange: 2,
+  scope: 'resource',
+})
+```
+
+## Constructor parameters
+
+**options:** (`SemanticRecallOptions`): Configuration options for the semantic recall processor
+
+### Options
+
+**storage:** (`MemoryStorage`): Storage instance for retrieving messages
+
+**vector:** (`MastraVector`): Vector store for semantic search
+
+**embedder:** (`MastraEmbeddingModel<string>`): Embedder for generating query embeddings
+
+**topK?:** (`number`): Number of most similar messages to retrieve
+
+**messageRange?:** (`number | { before: number; after: number }`): Number of context messages to include before/after each match. Can be a single number (same for both) or an object with separate values
+
+**scope?:** (`'thread' | 'resource'`): Scope of semantic search. 'thread' searches within the current thread only. 'resource' searches across all threads for the resource
+
+**threshold?:** (`number`): Minimum similarity score threshold (0-1). Messages below this threshold are filtered out
+
+**indexName?:** (`string`): Index name for the vector store. If not provided, auto-generated based on embedder model
+
+**logger?:** (`IMastraLogger`): Optional logger instance for structured logging
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'semantic-recall'
+
+**name:** (`string`): Processor display name set to 'SemanticRecall'
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Performs semantic search on historical messages and adds relevant context to the message list
+
+**processOutputResult:** (`(args: { messages: MastraDBMessage[]; messageList?: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Creates embeddings for new messages to enable future semantic search
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { SemanticRecall, MessageHistory } from '@mastra/core/processors'
+import { PostgresStorage } from '@mastra/pg'
+import { PgVector } from '@mastra/pg'
+import { openai } from '@ai-sdk/openai'
+
+const storage = new PostgresStorage({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+const vector = new PgVector({
+  id: 'pg-vector',
+  connectionString: process.env.DATABASE_URL,
+})
+
+const semanticRecall = new SemanticRecall({
+  storage,
+  vector,
+  embedder: openai.embedding('text-embedding-3-small'),
+  topK: 5,
+  messageRange: { before: 2, after: 1 },
+  scope: 'resource',
+  threshold: 0.7,
+})
+
+export const agent = new Agent({
+  name: 'semantic-memory-agent',
+  instructions: 'You are a helpful assistant with semantic memory recall',
+  model: 'openai:gpt-4o',
+  inputProcessors: [semanticRecall, new MessageHistory({ storage, lastMessages: 50 })],
+  outputProcessors: [semanticRecall, new MessageHistory({ storage })],
+})
+```
+
+## Behavior
+
+### Input processing
+
+1. Extracts the user query from the last user message
+2. Generates embeddings for the query
+3. Performs vector search to find semantically similar messages
+4. Retrieves matched messages along with surrounding context (based on `messageRange`)
+5. For `scope: 'resource'`, formats cross-thread messages as a system message with timestamps
+6. Adds recalled messages with `source: 'memory'` tag
+
+### Output processing
+
+1. Extracts text content from new user and assistant messages
+2. Generates embeddings for each message
+3. Stores embeddings in the vector store with metadata (message ID, thread ID, resource ID, role, content, timestamp)
+4. Uses LRU caching for embeddings to avoid redundant API calls
+
+### Cross-thread recall
+
+When `scope` is set to `'resource'`, the processor can recall messages from other threads. These cross-thread messages are formatted as a system message with timestamps and conversation labels to provide context about when and where the conversation occurred.
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-system-prompt-scrubber.md

@@ -0,0 +1,80 @@
+# SystemPromptScrubber
+
+The `SystemPromptScrubber` is an **output processor** that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying various types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.
+
+## Usage example
+
+```typescript
+import { SystemPromptScrubber } from '@mastra/core/processors'
+
+const processor = new SystemPromptScrubber({
+  model: 'openrouter/openai/gpt-oss-safeguard-20b',
+  strategy: 'redact',
+  redactionMethod: 'mask',
+  includeDetections: true,
+})
+```
+
+## Constructor parameters
+
+**options:** (`Options`): Configuration options for system prompt detection and handling
+
+### Options
+
+**model:** (`MastraModelConfig`): Model configuration for the detection agent
+
+**strategy?:** (`'block' | 'warn' | 'filter' | 'redact'`): Strategy when system prompts are detected: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages, 'redact' replaces with redacted versions
+
+**customPatterns?:** (`string[]`): Custom patterns to detect system prompts (regex strings)
+
+**includeDetections?:** (`boolean`): Whether to include detection details in warnings. Useful for debugging and monitoring
+
+**instructions?:** (`string`): Custom instructions for the detection agent. If not provided, uses default instructions
+
+**redactionMethod?:** (`'mask' | 'placeholder' | 'remove'`): Redaction method for system prompts: 'mask' replaces with asterisks, 'placeholder' replaces with placeholder text, 'remove' removes entirely
+
+**placeholderText?:** (`string`): Custom placeholder text for redaction when redactionMethod is 'placeholder'
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'system-prompt-scrubber'
+
+**name?:** (`string`): Optional processor display name
+
+**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null>`): Processes streaming output parts to detect and handle system prompts during streaming
+
+**processOutputResult:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to detect and handle system prompts in non-streaming scenarios
+
+## Extended usage example
+
+When using `SystemPromptScrubber` 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 scrubber, reducing the number of LLM calls required for detection.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { BatchPartsProcessor, SystemPromptScrubber } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'scrubbed-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 system prompt detection on batched content
+    new SystemPromptScrubber({
+      model: 'openrouter/openai/gpt-oss-safeguard-20b',
+      strategy: 'redact',
+      customPatterns: ['system prompt', 'internal instructions'],
+      includeDetections: true,
+      redactionMethod: 'placeholder',
+      placeholderText: '[REDACTED]',
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-token-limiter-processor.md

@@ -0,0 +1,115 @@
+# TokenLimiterProcessor
+
+The `TokenLimiterProcessor` limits the number of tokens in messages. It can be used as both an input and output processor:
+
+- **Input processor**: Filters historical messages to fit within the context window, prioritizing recent messages
+- **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits
+
+## Usage example
+
+```typescript
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+const processor = new TokenLimiterProcessor({
+  limit: 1000,
+  strategy: 'truncate',
+  countMode: 'cumulative',
+})
+```
+
+## Constructor parameters
+
+**options:** (`number | Options`): Either a simple number for token limit, or configuration options object
+
+### Options
+
+**limit:** (`number`): Maximum number of tokens to allow in the response
+
+**encoding?:** (`TiktokenBPE`): Optional encoding to use. Defaults to o200k\_base which is used by gpt-5.1
+
+**strategy?:** (`'truncate' | 'abort'`): Strategy when token limit is reached: 'truncate' stops emitting chunks, 'abort' calls abort() to stop the stream
+
+**countMode?:** (`'cumulative' | 'part'`): Whether to count tokens from the beginning of the stream or just the current part: 'cumulative' counts all tokens from start, 'part' only counts tokens in current part
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'token-limiter'
+
+**name?:** (`string`): Optional processor display name
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Filters input messages to fit within token limit, prioritizing recent messages while preserving system messages
+
+**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming
+
+**processOutputResult:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to limit token count in non-streaming scenarios
+
+**getMaxTokens:** (`() => number`): Get the maximum token limit
+
+## Error behavior
+
+When used as an input processor, `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
+
+- **Empty messages**: If there are no messages to process, a TripWire is thrown because you cannot send an LLM request with no messages.
+- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you cannot send an LLM request with only system messages and no user/assistant messages.
+
+```typescript
+import { TripWire } from '@mastra/core/agent'
+
+try {
+  await agent.generate('Hello')
+} catch (error) {
+  if (error instanceof TripWire) {
+    console.log('Token limit error:', error.message)
+  }
+}
+```
+
+## Extended usage example
+
+### As an input processor (limit context window)
+
+Use `inputProcessors` to limit historical messages sent to the model, which helps stay within context window limits:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'context-limited-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-4o',
+  memory: new Memory({
+    /* ... */
+  }),
+  inputProcessors: [
+    new TokenLimiterProcessor({ limit: 4000 }), // Limits historical messages to ~4000 tokens
+  ],
+})
+```
+
+### As an output processor (limit response length)
+
+Use `outputProcessors` to limit the length of generated responses:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'response-limited-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-4o',
+  outputProcessors: [
+    new TokenLimiterProcessor({
+      limit: 1000,
+      strategy: 'truncate',
+      countMode: 'cumulative',
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-tool-call-filter.md

@@ -0,0 +1,85 @@
+# ToolCallFilter
+
+The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+
+## Usage example
+
+```typescript
+import { ToolCallFilter } from '@mastra/core/processors'
+
+// Exclude all tool calls
+const filterAll = new ToolCallFilter()
+
+// Exclude specific tools by name
+const filterSpecific = new ToolCallFilter({
+  exclude: ['searchDatabase', 'sendEmail'],
+})
+```
+
+## Constructor parameters
+
+**options?:** (`Options`): Configuration options for the tool call filter
+
+### Options
+
+**exclude?:** (`string[]`): List of specific tool names to exclude. If not provided or undefined, all tool calls are excluded
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'tool-call-filter'
+
+**name:** (`string`): Processor display name set to 'ToolCallFilter'
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Processes input messages to filter out tool calls and their results based on configuration
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolCallFilter } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'filtered-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai:gpt-4o',
+  tools: {
+    searchDatabase,
+    sendEmail,
+    getWeather,
+  },
+  inputProcessors: [
+    // Filter out database search tool calls from context
+    // to reduce token usage while keeping other tool interactions
+    new ToolCallFilter({
+      exclude: ['searchDatabase'],
+    }),
+  ],
+})
+```
+
+## Filtering all tool calls
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolCallFilter } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'no-tools-context-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai:gpt-4o',
+  tools: {
+    searchDatabase,
+    sendEmail,
+  },
+  inputProcessors: [
+    // Remove all tool calls from the message history
+    // The agent can still use tools, but previous tool interactions
+    // won't be included in the context
+    new ToolCallFilter(),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-processors-tool-search-processor.md

@@ -0,0 +1,111 @@
+# ToolSearchProcessor
+
+The `ToolSearchProcessor` is an **input processor** that enables dynamic tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (`search_tools` and `load_tool`) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.
+
+## Usage example
+
+```typescript
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: {
+    createIssue: githubTools.createIssue,
+    sendEmail: emailTools.send,
+    getWeather: weatherTools.forecast,
+    // ... many more tools
+  },
+  search: {
+    topK: 5,
+    minScore: 0.1,
+  },
+})
+```
+
+## Constructor parameters
+
+**options:** (`ToolSearchProcessorOptions`): Configuration options for the tool search processor
+
+### Options
+
+**tools:** (`Record<string, Tool>`): All tools that can be searched and loaded dynamically. These tools are not immediately available to the agent — they must be discovered via search and loaded on demand.
+
+**search?:** (`{ topK?: number; minScore?: number }`): Configuration for the search behavior.
+
+**search.topK?:** (`number`): Maximum number of tools to return in search results.
+
+**search.minScore?:** (`number`): Minimum relevance score (0-1) for including a tool in search results.
+
+**ttl?:** (`number`): Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'tool-search'
+
+**name:** (`string`): Processor display name set to 'Tool Search Processor'
+
+**processInputStep:** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes each step to inject search/load meta-tools and any previously loaded tools into the agent's tool set.
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+// Tools from various integrations
+import { githubTools } from './tools/github'
+import { slackTools } from './tools/slack'
+import { dbTools } from './tools/database'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: {
+    ...githubTools, // createIssue, listPRs, mergePR, ...
+    ...slackTools, // sendMessage, createChannel, ...
+    ...dbTools, // query, insert, update, ...
+  },
+  search: {
+    topK: 5,
+    minScore: 0.1,
+  },
+})
+
+const agent = new Agent({
+  name: 'dynamic-tools-agent',
+  instructions:
+    'You are a helpful assistant with access to many tools. Use search_tools to find relevant tools, then load_tool to make them available.',
+  model: 'openai/gpt-4o',
+  inputProcessors: [toolSearch],
+})
+```
+
+The agent workflow is:
+
+1. Agent receives a user message
+2. Agent calls `search_tools` with keywords (e.g., "github issue")
+3. Agent reviews results and calls `load_tool` with the tool name
+4. The loaded tool becomes available on the next turn
+5. Agent uses the loaded tool normally
+
+## Combining with other processors
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolSearchProcessor, TokenLimiter } from '@mastra/core/processors'
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'openai/gpt-4o',
+  inputProcessors: [
+    new ToolSearchProcessor({
+      tools: allTools,
+      search: { topK: 5 },
+    }),
+    // Place TokenLimiter last to ensure context fits
+    new TokenLimiter(127000),
+  ],
+})
+```
+
+## Related
+
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Using Tools](https://mastra.ai/docs/agents/using-tools)

package/dist/docs/references/reference-processors-unicode-normalizer.md

@@ -0,0 +1,62 @@
+# UnicodeNormalizer
+
+The `UnicodeNormalizer` is an **input processor** that normalizes Unicode text to ensure consistent formatting and remove potentially problematic characters before messages are sent to the language model. This processor helps maintain text quality by handling various Unicode representations, removing control characters, and standardizing whitespace formatting.
+
+## Usage example
+
+```typescript
+import { UnicodeNormalizer } from '@mastra/core/processors'
+
+const processor = new UnicodeNormalizer({
+  stripControlChars: true,
+  collapseWhitespace: true,
+})
+```
+
+## Constructor parameters
+
+**options?:** (`Options`): Configuration options for Unicode text normalization
+
+### Options
+
+**stripControlChars?:** (`boolean`): Whether to strip control characters. When enabled, removes control characters except , ,
+
+**preserveEmojis?:** (`boolean`): Whether to preserve emojis. When disabled, emojis may be removed if they contain control characters
+
+**collapseWhitespace?:** (`boolean`): Whether to collapse consecutive whitespace. When enabled, multiple spaces/tabs/newlines are collapsed to single instances
+
+**trim?:** (`boolean`): Whether to trim leading and trailing whitespace
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'unicode-normalizer'
+
+**name?:** (`string`): Optional processor display name
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => MastraDBMessage[]`): Processes input messages to normalize Unicode text
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { UnicodeNormalizer } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  id: 'normalized-agent',
+  name: 'normalized-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.1',
+  inputProcessors: [
+    new UnicodeNormalizer({
+      stripControlChars: true,
+      preserveEmojis: true,
+      collapseWhitespace: true,
+      trim: true,
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)