@mastra/libsql 1.6.1 → 1.6.2-alpha.0

package/dist/docs/references/docs-workflows-snapshots.md

@@ -0,0 +1,238 @@
+# Snapshots
+
+In Mastra, a snapshot is a serializable representation of a workflow's complete execution state at a specific point in time. Snapshots capture all the information needed to resume a workflow from exactly where it left off, including:
+
+- The current state of each step in the workflow
+- The outputs of completed steps
+- The execution path taken through the workflow
+- Any suspended steps and their metadata
+- The remaining retry attempts for each step
+- Additional contextual data needed to resume execution
+
+Snapshots are automatically created and managed by Mastra whenever a workflow is suspended, and are persisted to the configured storage system.
+
+## The role of snapshots in suspend and resume
+
+Snapshots are the key mechanism enabling Mastra's suspend and resume capabilities. When a workflow step calls `await suspend()`:
+
+1. The workflow execution is paused at that exact point
+2. The current state of the workflow is captured as a snapshot
+3. The snapshot is persisted to storage
+4. The workflow step is marked as "suspended" with a status of `'suspended'`
+5. Later, when `resume()` is called on the suspended step, the snapshot is retrieved
+6. The workflow execution resumes from exactly where it left off
+
+This mechanism provides a powerful way to implement human-in-the-loop workflows, handle rate limiting, wait for external resources, and implement complex branching workflows that may need to pause for extended periods.
+
+## Snapshot anatomy
+
+Each snapshot includes the `runId`, input, step status (`success`, `suspended`, etc.), any suspend and resume payloads, and the final output. This ensures full context is available when resuming execution.
+
+```json
+{
+  "runId": "34904c14-e79e-4a12-9804-9655d4616c50",
+  "status": "success",
+  "value": {},
+  "context": {
+    "input": {
+      "value": 100,
+      "user": "Michael",
+      "requiredApprovers": ["manager", "finance"]
+    },
+    "approval-step": {
+      "payload": {
+        "value": 100,
+        "user": "Michael",
+        "requiredApprovers": ["manager", "finance"]
+      },
+      "startedAt": 1758027577955,
+      "status": "success",
+      "suspendPayload": {
+        "message": "Workflow suspended",
+        "requestedBy": "Michael",
+        "approvers": ["manager", "finance"]
+      },
+      "suspendedAt": 1758027578065,
+      "resumePayload": { "confirm": true, "approver": "manager" },
+      "resumedAt": 1758027578517,
+      "output": { "value": 100, "approved": true },
+      "endedAt": 1758027578634
+    }
+  },
+  "activePaths": [],
+  "serializedStepGraph": [
+    {
+      "type": "step",
+      "step": {
+        "id": "approval-step",
+        "description": "Accepts a value, waits for confirmation"
+      }
+    }
+  ],
+  "suspendedPaths": {},
+  "waitingPaths": {},
+  "result": { "value": 100, "approved": true },
+  "requestContext": {},
+  "timestamp": 1758027578740
+}
+```
+
+## How snapshots are saved and retrieved
+
+Snapshots are saved to the configured storage system. By default, they use libSQL, but you can configure Upstash or PostgreSQL instead. Each snapshot is saved in the `workflow_snapshots` table and identified by the workflow's `runId`.
+
+Read more about:
+
+- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
+- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
+- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
+
+### Saving snapshots
+
+When a workflow is suspended, Mastra automatically persists the workflow snapshot with these steps:
+
+1. The `suspend()` function in a step execution triggers the snapshot process
+2. The `WorkflowInstance.suspend()` method records the suspended machine
+3. `persistWorkflowSnapshot()` is called to save the current state
+4. The snapshot is serialized and stored in the configured database in the `workflow_snapshots` table
+5. The storage record includes the workflow name, run ID, and the serialized snapshot
+
+### Retrieving snapshots
+
+When a workflow is resumed, Mastra retrieves the persisted snapshot with these steps:
+
+1. The `resume()` method is called with a specific step ID
+2. The snapshot is loaded from storage using `loadWorkflowSnapshot()`
+3. The snapshot is parsed and prepared for resumption
+4. The workflow execution is recreated with the snapshot state
+5. The suspended step is resumed, and execution continues
+
+```typescript
+const storage = mastra.getStorage()
+const workflowStore = await storage?.getStore('workflows')
+
+const snapshot = await workflowStore?.loadWorkflowSnapshot({
+  runId: '<run-id>',
+  workflowName: '<workflow-id>',
+})
+
+console.log(snapshot)
+```
+
+## Storage options for snapshots
+
+Snapshots are persisted using a `storage` instance configured on the `Mastra` class. This storage layer is shared across all workflows registered to that instance. Mastra supports multiple storage options for flexibility in different environments.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { approvalWorkflow } from './workflows'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: ':memory:',
+  }),
+  workflows: { approvalWorkflow },
+})
+```
+
+- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
+- [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
+- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
+- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
+- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
+- [More storage providers](https://mastra.ai/docs/memory/storage)
+
+## Best practices
+
+1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
+2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
+3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
+4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
+5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
+
+## Custom snapshot metadata
+
+You can attach custom metadata when suspending a workflow by defining a `suspendSchema`. This metadata is stored in the snapshot and made available when the workflow is resumed.
+
+```typescript
+import { createWorkflow, createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const approvalStep = createStep({
+  id: 'approval-step',
+  description: 'Accepts a value, waits for confirmation',
+  inputSchema: z.object({
+    value: z.number(),
+    user: z.string(),
+    requiredApprovers: z.array(z.string()),
+  }),
+  suspendSchema: z.object({
+    message: z.string(),
+    requestedBy: z.string(),
+    approvers: z.array(z.string()),
+  }),
+  resumeSchema: z.object({
+    confirm: z.boolean(),
+    approver: z.string(),
+  }),
+  outputSchema: z.object({
+    value: z.number(),
+    approved: z.boolean(),
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { value, user, requiredApprovers } = inputData
+    const { confirm } = resumeData ?? {}
+
+    if (!confirm) {
+      return await suspend({
+        message: 'Workflow suspended',
+        requestedBy: user,
+        approvers: [...requiredApprovers],
+      })
+    }
+
+    return {
+      value,
+      approved: confirm,
+    }
+  },
+})
+```
+
+### Providing resume data
+
+Use `resumeData` to pass structured input when resuming a suspended step. It must match the step’s `resumeSchema`.
+
+```typescript
+const workflow = mastra.getWorkflow('approvalWorkflow')
+
+const run = await workflow.createRun()
+
+const result = await run.start({
+  inputData: {
+    value: 100,
+    user: 'Michael',
+    requiredApprovers: ['manager', 'finance'],
+  },
+})
+
+if (result.status === 'suspended') {
+  const resumedResult = await run.resume({
+    step: 'approval-step',
+    resumeData: {
+      confirm: true,
+      approver: 'manager',
+    },
+  })
+}
+```
+
+## Related
+
+- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
+- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)

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-core-getMemory.md

@@ -0,0 +1,50 @@
+# Mastra.getMemory()
+
+The `.getMemory()` method retrieves a memory instance from the Mastra registry by its key. Memory instances are registered in the Mastra constructor and can be referenced by stored agents.
+
+## Usage example
+
+```typescript
+const memory = mastra.getMemory('conversationMemory')
+
+// Use the memory instance
+const thread = await memory.createThread({
+  resourceId: 'user-123',
+  title: 'New Conversation',
+})
+```
+
+## Parameters
+
+**key:** (`TMemoryKey extends keyof TMemory`): The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.
+
+## Returns
+
+**memory:** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
+
+## Example: Registering and Retrieving Memory
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const conversationMemory = new Memory({
+  storage: new LibSQLStore({ id: 'conversation-store', url: ':memory:' }),
+})
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+  },
+})
+
+// Later, retrieve the memory instance
+const memory = mastra.getMemory('conversationMemory')
+```
+
+## Related
+
+- [Mastra.listMemory()](https://mastra.ai/reference/core/listMemory)
+- [Memory overview](https://mastra.ai/docs/memory/overview)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

package/dist/docs/references/reference-core-listMemory.md

@@ -0,0 +1,56 @@
+# Mastra.listMemory()
+
+The `.listMemory()` method returns all memory instances registered with the Mastra instance.
+
+## Usage example
+
+```typescript
+const memoryInstances = mastra.listMemory()
+
+for (const [key, memory] of Object.entries(memoryInstances)) {
+  console.log(`Memory "${key}": ${memory.id}`)
+}
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**memory:** (`Record<string, MastraMemory>`): An object containing all registered memory instances, keyed by their registry keys.
+
+## Example: Checking Registered Memory
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const conversationMemory = new Memory({
+  id: 'conversation-memory',
+  storage: new LibSQLStore({ id: 'conversation-store', url: ':memory:' }),
+})
+
+const analyticsMemory = new Memory({
+  id: 'analytics-memory',
+  storage: new LibSQLStore({ id: 'analytics-store', url: ':memory:' }),
+})
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+    analyticsMemory,
+  },
+})
+
+// List all registered memory instances
+const allMemory = mastra.listMemory()
+console.log(Object.keys(allMemory)) // ["conversationMemory", "analyticsMemory"]
+```
+
+## Related
+
+- [Mastra.getMemory()](https://mastra.ai/reference/core/getMemory)
+- [Memory overview](https://mastra.ai/docs/memory/overview)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

package/dist/docs/references/reference-core-mastra-class.md

@@ -0,0 +1,66 @@
+# Mastra Class
+
+The `Mastra` class is the central orchestrator in any Mastra application, managing agents, workflows, storage, logging, observability, and more. Typically, you create a single instance of `Mastra` to coordinate your application.
+
+Think of `Mastra` as a top-level registry where you register agents, workflows, tools, and other components that need to be accessible throughout your application.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+import { LibSQLStore } from '@mastra/libsql'
+import { weatherWorkflow } from './workflows/weather-workflow'
+import { weatherAgent } from './agents/weather-agent'
+
+export const mastra = new Mastra({
+  workflows: { weatherWorkflow },
+  agents: { weatherAgent },
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: ':memory:',
+  }),
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+})
+```
+
+## Constructor parameters
+
+Visit the [Configuration reference](https://mastra.ai/reference/configuration) for detailed documentation on all available configuration options.
+
+**agents?:** (`Record<string, Agent>`): Agent instances to register, keyed by name (Default: `{}`)
+
+**tools?:** (`Record<string, ToolApi>`): Custom tools to register. Structured as a key-value pair, with keys being the tool name and values being the tool function. (Default: `{}`)
+
+**storage?:** (`MastraCompositeStore`): Storage engine instance for persisting data
+
+**vectors?:** (`Record<string, MastraVector>`): Vector store instance, used for semantic search and vector-based tools (eg Pinecone, PgVector or Qdrant)
+
+**logger?:** (`Logger`): Logger instance created with new PinoLogger() (Default: `Console logger with INFO level`)
+
+**idGenerator?:** (`() => string`): Custom ID generator function. Used by agents, workflows, memory, and other components to generate unique identifiers.
+
+**workflows?:** (`Record<string, Workflow>`): Workflows to register. Structured as a key-value pair, with keys being the workflow name and values being the workflow instance. (Default: `{}`)
+
+**tts?:** (`Record<string, MastraVoice>`): Text-to-speech providers for voice synthesis
+
+**observability?:** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
+
+**deployer?:** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
+
+**server?:** (`ServerConfig`): Server configuration including port, host, timeout, API routes, middleware, CORS settings, and build options for Swagger UI, API request logging, and OpenAPI docs.
+
+**mcpServers?:** (`Record<string, MCPServerBase>`): An object where keys are registry keys (used for getMCPServer()) and values are instances of MCPServer or classes extending MCPServerBase. Each MCPServer must have an id property. Servers can be retrieved by registry key using getMCPServer() or by their intrinsic id using getMCPServerById().
+
+**bundler?:** (`BundlerConfig`): Configuration for the asset bundler with options for externals, sourcemap, and transpilePackages.
+
+**scorers?:** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs (Default: `{}`)
+
+**processors?:** (`Record<string, Processor>`): Input/output processors for transforming agent inputs and outputs (Default: `{}`)
+
+**gateways?:** (`Record<string, MastraModelGateway>`): Custom model gateways to register for accessing AI models through alternative providers or private deployments. Structured as a key-value pair, with keys being the registry key (used for getGateway()) and values being gateway instances. (Default: `{}`)
+
+**memory?:** (`Record<string, MastraMemory>`): Memory instances to register. These can be referenced by stored agents and resolved at runtime. Structured as a key-value pair, with keys being the registry key and values being memory instances. (Default: `{}`)