@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/docs-workspace-search.md

@@ -0,0 +1,243 @@
+# Search and Indexing
+
+**Added in:** `@mastra/core@1.1.0`
+
+Search lets agents find relevant content in indexed workspace files. When an agent needs to answer a question or find information, it can search the indexed content instead of reading every file.
+
+## How it works
+
+Workspace search has two phases: indexing and querying.
+
+### Indexing
+
+Content must be indexed before it can be searched. When you index a document:
+
+- The content is tokenized (split into searchable terms)
+- For BM25: term frequencies and document statistics are computed
+- For vector: the content is embedded using your embedder function and stored in the vector store
+
+Each indexed document has:
+
+- **id** - A unique identifier (typically the file path)
+- **content** - The text content
+- **metadata** - Optional key-value data stored with the document
+
+### Querying
+
+When you search:
+
+1. The query is processed using the same tokenization/embedding as indexing
+2. Documents are scored based on relevance to the query
+3. Results are ranked by score and returned with the matching content
+
+Workspaces support three search modes: BM25 keyword search, vector semantic search, and hybrid search that combines both.
+
+## BM25 keyword search
+
+BM25 scores documents based on term frequency and document length. It works well for exact matches and specific terminology.
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  bm25: true,
+})
+```
+
+For custom BM25 parameters (`k1` is term frequency saturation, `b` is document length normalization):
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  bm25: {
+    k1: 1.5,
+    b: 0.75,
+  },
+})
+```
+
+## Vector search
+
+Vector search uses embeddings to find semantically similar content. It requires a vector store and embedder function.
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { PineconeVector } from '@mastra/pinecone'
+import { embed } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  vectorStore: new PineconeVector({
+    apiKey: process.env.PINECONE_API_KEY,
+    index: 'workspace-index',
+  }),
+  embedder: async (text: string) => {
+    const { embedding } = await embed({
+      model: openai.embedding('text-embedding-3-small'),
+      value: text,
+    })
+    return embedding
+  },
+})
+```
+
+## Hybrid search
+
+Configure both BM25 and vector search to enable hybrid mode, which combines keyword matching with semantic understanding.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  bm25: true,
+  vectorStore: pineconeVector,
+  embedder: embedderFn,
+})
+```
+
+## Custom index name
+
+By default, the search index name is derived from the workspace ID. To set a custom name, use `searchIndexName`:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  bm25: true,
+  searchIndexName: 'my_workspace_vectors',
+})
+```
+
+The index name must be a valid SQL identifier: start with a letter or underscore, contain only letters, numbers, or underscores, and be at most 63 characters long.
+
+## Indexing content
+
+### Manual indexing
+
+Use `workspace.index()` to add content to the search index programmatically. The file paths become document IDs. You can also pass metadata for each document.
+
+```typescript
+// Basic indexing
+await workspace.index('/docs/guide.md', 'Content of the guide...')
+
+// Index with metadata for filtering or context
+await workspace.index('/docs/api.md', apiDocContent, {
+  metadata: {
+    category: 'api',
+    version: '2.0',
+  },
+})
+```
+
+Manual indexing is useful when:
+
+- You're indexing content that doesn't come from files (e.g., database records, API responses)
+- You want to pre-process or chunk content before indexing
+- You need to add custom metadata to documents
+
+### Auto-indexing
+
+Configure `autoIndexPaths` to automatically index files when the workspace initializes. Each entry can be a directory path (indexed recursively) or a glob pattern for selective indexing.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  bm25: true,
+  autoIndexPaths: ['/docs', '/support/faq'],
+})
+
+await workspace.init()
+```
+
+When `init()` is called, all matching files are read and indexed for search. The file path becomes the document ID.
+
+Glob patterns let you index specific file types:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  bm25: true,
+  autoIndexPaths: ['/docs/**/*.md', '/support/**/*.txt'],
+})
+```
+
+## Searching
+
+Use `workspace.search()` to find relevant content. Results are ranked by relevance score.
+
+```typescript
+const results = await workspace.search('password reset')
+
+for (const result of results) {
+  console.log(`${result.id}: ${result.score}`)
+  console.log(result.content)
+}
+```
+
+### Search options
+
+You can customize the search behavior with options:
+
+```typescript
+const results = await workspace.search('authentication flow', {
+  topK: 10,
+  mode: 'hybrid',
+  minScore: 0.5,
+  vectorWeight: 0.5,
+})
+```
+
+| Option         | Description                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------- |
+| `topK`         | Maximum number of results to return. Default: 5                                                               |
+| `mode`         | Search mode: `'bm25'`, `'vector'`, or `'hybrid'`. Defaults to the best available mode based on configuration. |
+| `minScore`     | Filter out results below this score threshold (0-1).                                                          |
+| `vectorWeight` | In hybrid mode, how much to weight vector scores vs BM25. 0 = all BM25, 1 = all vector, 0.5 = equal.          |
+
+### Search results
+
+Each result contains:
+
+```typescript
+interface SearchResult {
+  id: string // Document ID (typically file path)
+  content: string // The matching content
+  score: number // Relevance score (0-1)
+  lineRange?: {
+    // Lines where the match was found
+    start: number
+    end: number
+  }
+  metadata?: Record<string, unknown> // Metadata stored with the document
+  scoreDetails?: {
+    // Score breakdown (hybrid mode only)
+    vector?: number
+    bm25?: number
+  }
+}
+```
+
+**Understanding scores:**
+
+- Scores range from 0 to 1, where 1 is a perfect match
+- BM25 scores are normalized based on the best match in the result set
+- Vector scores represent cosine similarity between query and document embeddings
+- In hybrid mode, scores are combined using the `vectorWeight` parameter
+
+### When to use each mode
+
+| Mode     | Best for                             | Example queries                                                          |
+| -------- | ------------------------------------ | ------------------------------------------------------------------------ |
+| `bm25`   | Exact terms, technical queries, code | "useState hook", "404 error", "config.yaml"                              |
+| `vector` | Conceptual queries, natural language | "how to handle user authentication", "best practices for error handling" |
+| `hybrid` | General search, unknown query types  | Most agent use cases                                                     |
+
+## Agent tools
+
+When you configure search on a workspace, agents receive tools for searching and indexing content. See [workspace class reference](https://mastra.ai/reference/workspace/workspace-class) for details.
+
+## Related
+
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)

package/dist/docs/references/docs-workspace-skills.md

@@ -0,0 +1,169 @@
+# Workspace Skills
+
+**Added in:** `@mastra/core@1.1.0`
+
+Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io) - an open standard for packaging agent capabilities.
+
+A skill is a folder containing:
+
+- `SKILL.md`: Instructions and metadata for the agent
+- `references/`: Supporting documentation (optional)
+- `scripts/`: Executable scripts (optional)
+- `assets/`: Images and other files (optional)
+
+```plaintext
+/skills
+  /code-review
+    SKILL.md
+    /references
+      style-guide.md
+      pr-checklist.md
+    /scripts
+      lint.ts
+```
+
+When skills are configured on a workspace, agents can discover and activate them during conversations.
+
+## SKILL.md format
+
+Follow the official [skill specification](https://agentskills.io/specification) when creating your skill. Here is an example `SKILL.md` for a code review skill:
+
+```markdown
+---
+name: code-review
+description: Reviews code for quality, style, and potential issues
+version: 1.0.0
+tags:
+  - development
+  - review
+---
+
+# Code Review
+
+You are a code reviewer. When reviewing code:
+
+1. Check for bugs and edge cases
+2. Verify the code follows the style guide in references/style-guide.md
+3. Suggest improvements for readability
+4. Run the linter using scripts/lint.ts
+
+## What to look out for
+
+- Unused variables and imports
+- Missing error handling
+- Security vulnerabilities
+- Performance issues
+```
+
+## Configuring skills
+
+Enable skill discovery by setting the `skills` option on your workspace:
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['/skills'],
+})
+```
+
+The `skills` directory is relative to your `basePath`. You can specify multiple skill directories or use glob patterns for discovery:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: [
+    '/skills', // Project skills
+    '/team-skills', // Shared team skills
+  ],
+})
+```
+
+You can also pass a direct path to a skill directory or `SKILL.md` file:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['/path/to/my-skill'],
+})
+```
+
+Glob patterns let you discover skills across nested directories:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['./**/skills'],
+})
+```
+
+## Dynamic skills
+
+For dynamic skill paths based on context, pass a function:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: context => {
+    const paths = ['/skills']
+    if (context.user?.role === 'developer') {
+      paths.push('/dev-skills')
+    }
+    return paths
+  },
+})
+```
+
+## How agents use skills
+
+When an agent activates a skill, the skill's instructions are added to the conversation context. The agent can then follow those instructions and access the skill's references and scripts.
+
+Under the hood this involves:
+
+1. Lists available skills in the system message
+2. Allows agents to activate skills during conversation
+3. Provides access to skill references and scripts
+
+## Skill search
+
+If BM25 or vector search is enabled on the workspace, skills are automatically indexed. Agents can search across skill content to find relevant instructions.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['/skills'],
+  bm25: true,
+})
+```
+
+## Custom skill source
+
+By default, skills are read from the workspace filesystem. For advanced use cases, provide a custom `skillSource` to load skills from a different backend.
+
+`VersionedSkillSource` serves published skill versions from a content-addressable blob store, so production agents use a specific published version without touching the live filesystem:
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { VersionedSkillSource } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['/skills'],
+  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
+})
+```
+
+`VersionedSkillSource` accepts three parameters:
+
+- **`versionTree`** (`SkillVersionTree`) — A manifest mapping relative file paths to blob entries (`{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }`).
+- **`blobStore`** (`BlobStore`) — A content-addressable blob store instance that holds the actual file contents referenced by hash.
+- **`versionCreatedAt`** (`Date`) — The timestamp when this skill version was published. Used as the modification time for all files in the version.
+
+When `skillSource` is provided, it is used instead of the workspace filesystem for skill discovery.
+
+## Related
+
+- [Agent skills specification](https://agentskills.io)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Search and indexing](https://mastra.ai/docs/workspace/search)

package/dist/docs/references/guides-agent-frameworks-ai-sdk.md

@@ -0,0 +1,140 @@
+# AI SDK
+
+If you're already using the [Vercel AI SDK](https://sdk.vercel.ai) directly and want to add Mastra capabilities like [processors](https://mastra.ai/docs/agents/processors) or [memory](https://mastra.ai/docs/memory/memory-processors) without switching to the full Mastra agent API, [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra) lets you wrap any AI SDK model with these features. This is useful when you want to keep your existing AI SDK code but add input/output processing, conversation persistence, or content filtering.
+
+> **Tip:** If you want to use Mastra together with AI SDK UI (e.g. `useChat()`), visit the [AI SDK UI guide](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
+
+## Installation
+
+Install `@mastra/ai-sdk` to begin using the `withMastra()` function.
+
+**npm**:
+
+```bash
+npm install @mastra/ai-sdk@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/ai-sdk@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/ai-sdk@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/ai-sdk@latest
+```
+
+## Examples
+
+### With Processors
+
+Processors let you transform messages before they're sent to the model (`processInput`) and after responses are received (`processOutputResult`). This example creates a logging processor that logs message counts at each stage, then wraps an OpenAI model with it.
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+import { withMastra } from '@mastra/ai-sdk'
+import type { Processor } from '@mastra/core/processors'
+
+const loggingProcessor: Processor<'logger'> = {
+  id: 'logger',
+  async processInput({ messages }) {
+    console.log('Input:', messages.length, 'messages')
+    return messages
+  },
+  async processOutputResult({ messages }) {
+    console.log('Output:', messages.length, 'messages')
+    return messages
+  },
+}
+
+const model = withMastra(openai('gpt-4o'), {
+  inputProcessors: [loggingProcessor],
+  outputProcessors: [loggingProcessor],
+})
+
+const { text } = await generateText({
+  model,
+  prompt: 'What is 2 + 2?',
+})
+```
+
+### With Memory
+
+Memory automatically loads previous messages from storage before the LLM call and saves new messages after. This example configures a libSQL storage backend to persist conversation history, loading the last 10 messages for context.
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+import { withMastra } from '@mastra/ai-sdk'
+import { LibSQLStore } from '@mastra/libsql'
+
+const storage = new LibSQLStore({
+  id: 'my-app',
+  url: 'file:./data.db',
+})
+await storage.init()
+
+const memoryStorage = await storage.getStore('memory')
+
+const model = withMastra(openai('gpt-4o'), {
+  memory: {
+    storage: memoryStorage!,
+    threadId: 'user-thread-123',
+    resourceId: 'user-123',
+    lastMessages: 10,
+  },
+})
+
+const { text } = await generateText({
+  model,
+  prompt: 'What did we talk about earlier?',
+})
+```
+
+### With Processors & Memory
+
+You can combine processors and memory together. Input processors run after memory loads historical messages, and output processors run before memory saves the response.
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+import { withMastra } from '@mastra/ai-sdk'
+import { LibSQLStore } from '@mastra/libsql'
+
+const storage = new LibSQLStore({ id: 'my-app', url: 'file:./data.db' })
+await storage.init()
+
+const memoryStorage = await storage.getStore('memory')
+
+const model = withMastra(openai('gpt-4o'), {
+  inputProcessors: [myGuardProcessor],
+  outputProcessors: [myLoggingProcessor],
+  memory: {
+    storage: memoryStorage!,
+    threadId: 'thread-123',
+    resourceId: 'user-123',
+    lastMessages: 10,
+  },
+})
+
+const { text } = await generateText({
+  model,
+  prompt: 'Hello!',
+})
+```
+
+## Related
+
+- [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra) - API reference for `withMastra()`
+- [Processors](https://mastra.ai/docs/agents/processors) - Learn about input and output processors
+- [Memory](https://mastra.ai/docs/memory/overview) - Overview of Mastra's memory system
+- [AI SDK UI](https://mastra.ai/guides/build-your-ui/ai-sdk-ui) - Using AI SDK UI hooks with Mastra agents, workflows, and networks

package/dist/docs/references/reference-agents-agent.md

@@ -0,0 +1,141 @@
+# Agent Class
+
+The `Agent` class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, and handling voice capabilities.
+
+## Usage examples
+
+### Basic string instructions
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// String instructions
+export const agent = new Agent({
+  id: 'test-agent',
+  name: 'Test Agent',
+  instructions: 'You are a helpful assistant that provides concise answers.',
+  model: 'openai/gpt-5.1',
+})
+
+// System message object
+export const agent2 = new Agent({
+  id: 'test-agent-2',
+  name: 'Test Agent 2',
+  instructions: {
+    role: 'system',
+    content: 'You are an expert programmer',
+  },
+  model: 'openai/gpt-5.1',
+})
+
+// Array of system messages
+export const agent3 = new Agent({
+  id: 'test-agent-3',
+  name: 'Test Agent 3',
+  instructions: [
+    { role: 'system', content: 'You are a helpful assistant' },
+    { role: 'system', content: 'You have expertise in TypeScript' },
+  ],
+  model: 'openai/gpt-5.1',
+})
+```
+
+### Single CoreSystemMessage
+
+Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  id: 'core-message-agent',
+  name: 'Core Message Agent',
+  instructions: {
+    role: 'system',
+    content: 'You are a helpful assistant specialized in technical documentation.',
+    providerOptions: {
+      openai: {
+        reasoningEffort: 'low',
+      },
+    },
+  },
+  model: 'openai/gpt-5.1',
+})
+```
+
+### Multiple CoreSystemMessages
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// This could be customizable based on the user
+const preferredTone = {
+  role: 'system',
+  content: 'Always maintain a professional and empathetic tone.',
+}
+
+export const agent = new Agent({
+  id: 'multi-message-agent',
+  name: 'Multi Message Agent',
+  instructions: [
+    { role: 'system', content: 'You are a customer service representative.' },
+    preferredTone,
+    {
+      role: 'system',
+      content: 'Escalate complex issues to human agents when needed.',
+      providerOptions: {
+        anthropic: { cacheControl: { type: 'ephemeral' } },
+      },
+    },
+  ],
+  model: 'anthropic/claude-sonnet-4-20250514',
+})
+```
+
+## Constructor parameters
+
+**id?:** (`string`): Unique identifier for the agent. Defaults to \`name\` if not provided.
+
+**name:** (`string`): Display name for the agent. Used as the identifier if \`id\` is not provided.
+
+**description?:** (`string`): Optional description of the agent's purpose and capabilities.
+
+**instructions:** (`SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>`): Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, array of system messages, or a function that returns any of these types dynamically. SystemMessage types: string | string\[] | CoreSystemMessage | CoreSystemMessage\[] | SystemModelMessage | SystemModelMessage\[]
+
+**model:** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>`): The language model used by the agent. Can be provided statically or resolved at runtime.
+
+**agents?:** (`Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>`): Subagents that the agent can access. Can be provided statically or resolved dynamically.
+
+**tools?:** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
+
+**workflows?:** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
+
+**defaultOptions?:** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>`): Default options used when calling \`stream()\` and \`generate()\`.
+
+**defaultGenerateOptionsLegacy?:** (`AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>`): Default options used when calling \`generateLegacy()\`.
+
+**defaultStreamOptionsLegacy?:** (`AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>`): Default options used when calling \`streamLegacy()\`.
+
+**mastra?:** (`Mastra`): Reference to the Mastra runtime instance (injected automatically).
+
+**scorers?:** (`MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>`): Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.
+
+**memory?:** (`MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>`): Memory module used for storing and retrieving stateful context.
+
+**voice?:** (`CompositeVoice`): Voice settings for speech input and output.
+
+**inputProcessors?:** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with \`createWorkflow()\` using ProcessorStepSchema.
+
+**outputProcessors?:** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.
+
+**maxProcessorRetries?:** (`number`): Maximum number of times a processor can request retrying the LLM step.
+
+**requestContextSchema?:** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.
+
+## Returns
+
+**agent:** (`Agent<TAgentId, TTools>`): A new Agent instance with the specified configuration.
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)