@mastra/core 0.20.0 → 0.20.1-alpha.2

package/dist/{chunk-7EUC32F3.cjs → chunk-6K7IMZVR.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var chunkI6TOPBP6_cjs = require('./chunk-I6TOPBP6.cjs');
-var chunkYEEAHLAK_cjs = require('./chunk-YEEAHLAK.cjs');
+var chunkMHHMY2K4_cjs = require('./chunk-MHHMY2K4.cjs');
+var chunkPWPESTZZ_cjs = require('./chunk-PWPESTZZ.cjs');
 var chunkV3VLOOSW_cjs = require('./chunk-V3VLOOSW.cjs');
 var chunk4D4KB75Y_cjs = require('./chunk-4D4KB75Y.cjs');
 var chunk2JUDZXVI_cjs = require('./chunk-2JUDZXVI.cjs');
 var chunkUU5L5GDY_cjs = require('./chunk-UU5L5GDY.cjs');
 var chunkTSNDVBUU_cjs = require('./chunk-TSNDVBUU.cjs');
-var chunkDVHBWEYY_cjs = require('./chunk-DVHBWEYY.cjs');
+var chunkLCJHFYJS_cjs = require('./chunk-LCJHFYJS.cjs');
 var chunk6TEQIYXV_cjs = require('./chunk-6TEQIYXV.cjs');
 var chunkWM4VQWOZ_cjs = require('./chunk-WM4VQWOZ.cjs');
 var chunkWVCEJBDR_cjs = require('./chunk-WVCEJBDR.cjs');
@@ -102,7 +102,7 @@ function createOnScorerHook(mastra) {
   };
 }
 async function validateAndSaveScore(storage, payload) {
-  const payloadToSave = chunkYEEAHLAK_cjs.saveScorePayloadSchema.parse(payload);
+  const payloadToSave = chunkPWPESTZZ_cjs.saveScorePayloadSchema.parse(payload);
   await storage?.saveScore(payloadToSave);
 }
 async function findScorer(mastra, entityId, entityType, scorerName) {
@@ -182,12 +182,35 @@ exports.Mastra = class Mastra {
   get pubsub() {
     return this.#pubsub;
   }
+  /**
+   * Gets the currently configured ID generator function.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   idGenerator: () => `custom-${Date.now()}`
+   * });
+   * const generator = mastra.getIdGenerator();
+   * console.log(generator?.()); // "custom-1234567890"
+   * ```
+   */
   getIdGenerator() {
     return this.#idGenerator;
   }
   /**
-   * Generate a unique identifier using the configured generator or default to crypto.randomUUID()
-   * @returns A unique string ID
+   * Generates a unique identifier using the configured generator or defaults to `crypto.randomUUID()`.
+   *
+   * This method is used internally by Mastra for creating unique IDs for various entities
+   * like workflow runs, agent conversations, and other resources that need unique identification.
+   *
+   * @throws {MastraError} When the custom ID generator returns an empty string
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra();
+   * const id = mastra.generateId();
+   * console.log(id); // "550e8400-e29b-41d4-a716-446655440000"
+   * ```
    */
   generateId() {
     if (this.#idGenerator) {
@@ -206,9 +229,47 @@ exports.Mastra = class Mastra {
     }
     return crypto$1.randomUUID();
   }
+  /**
+   * Sets a custom ID generator function for creating unique identifiers.
+   *
+   * The ID generator function will be used by `generateId()` instead of the default
+   * `crypto.randomUUID()`. This is useful for creating application-specific ID formats
+   * or integrating with existing ID generation systems.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra();
+   * mastra.setIdGenerator(() => `custom-${Date.now()}`);
+   * const id = mastra.generateId();
+   * console.log(id); // "custom-1234567890"
+   * ```
+   */
   setIdGenerator(idGenerator) {
     this.#idGenerator = idGenerator;
   }
+  /**
+   * Creates a new Mastra instance with the provided configuration.
+   *
+   * The constructor initializes all the components specified in the config, sets up
+   * internal systems like logging and telemetry, and registers components with each other.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   agents: {
+   *     assistant: new Agent({
+   *       name: 'assistant',
+   *       instructions: 'You are a helpful assistant',
+   *       model: 'openai/gpt-5'
+   *     })
+   *   },
+   *   storage: new PostgresStore({
+   *     connectionString: process.env.DATABASE_URL
+   *   }),
+   *   logger: new PinoLogger({ name: 'MyApp' })
+   * });
+   * ```
+   */
   constructor(config) {
     if (config?.serverMiddleware) {
       this.#serverMiddleware = config.serverMiddleware.map(m => ({
@@ -230,7 +291,7 @@ exports.Mastra = class Mastra {
         this.#events[topic] = config?.events?.[topic] ?? [];
       }
     }
-    const workflowEventProcessor = new chunkI6TOPBP6_cjs.WorkflowEventProcessor({
+    const workflowEventProcessor = new chunkMHHMY2K4_cjs.WorkflowEventProcessor({
       mastra: this
     });
     const workflowEventCb = async (event, cb) => {
@@ -270,7 +331,7 @@ exports.Mastra = class Mastra {
       this.#logger?.warn(`Mastra telemetry is enabled, but the required instrumentation file was not loaded. If you are using Mastra outside of the mastra server environment, see: https://mastra.ai/en/docs/observability/tracing#tracing-outside-mastra-server-environment`, `If you are using a custom instrumentation file or want to disable this warning, set the globalThis.___MASTRA_TELEMETRY___ variable to true in your instrumentation file.`);
     }
     if (config?.observability) {
-      chunkDVHBWEYY_cjs.setupAITracing(config.observability);
+      chunkLCJHFYJS_cjs.setupAITracing(config.observability);
     }
     if (this.#telemetry && storage) {
       this.#storage = this.#telemetry.traceClass(storage, {
@@ -427,7 +488,7 @@ do:
    * Register this Mastra instance with AI tracing exporters that need it
    */
   registerAITracingExporters() {
-    const allTracingInstances = chunkDVHBWEYY_cjs.getAllAITracing();
+    const allTracingInstances = chunkLCJHFYJS_cjs.getAllAITracing();
     allTracingInstances.forEach(tracing => {
       const exporters = tracing.getExporters();
       exporters.forEach(exporter => {
@@ -441,7 +502,7 @@ do:
    * Initialize all AI tracing exporters after registration is complete
    */
   initAITracingExporters() {
-    const allTracingInstances = chunkDVHBWEYY_cjs.getAllAITracing();
+    const allTracingInstances = chunkLCJHFYJS_cjs.getAllAITracing();
     allTracingInstances.forEach(tracing => {
       const config = tracing.getConfig();
       const exporters = tracing.getExporters();
@@ -459,6 +520,27 @@ do:
       });
     });
   }
+  /**
+   * Retrieves a registered agent by its name.
+   *
+   * @template TAgentName - The specific agent name type from the registered agents
+   * @throws {MastraError} When the agent with the specified name is not found
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   agents: {
+   *     weatherAgent: new Agent({
+   *       name: 'weather-agent',
+   *       instructions: 'You provide weather information',
+   *       model: 'openai/gpt-5'
+   *     })
+   *   }
+   * });
+   * const agent = mastra.getAgent('weatherAgent');
+   * const response = await agent.generate('What is the weather?');
+   * ```
+   */
   getAgent(name) {
     const agent = this.#agents?.[name];
     if (!agent) {
@@ -478,6 +560,31 @@ do:
     }
     return this.#agents[name];
   }
+  /**
+   * Retrieves a registered agent by its unique ID.
+   *
+   * This method searches for an agent using its internal ID property. If no agent
+   * is found with the given ID, it also attempts to find an agent using the ID as
+   * a name (for backward compatibility).
+   *
+   * @throws {MastraError} When no agent is found with the specified ID
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   agents: {
+   *     assistant: new Agent({
+   *       name: 'assistant',
+   *       instructions: 'You are a helpful assistant',
+   *       model: 'openai/gpt-5'
+   *     })
+   *   }
+   * });
+   *
+   * const assistant = mastra.getAgent('assistant');
+   * const sameAgent = mastra.getAgentById(assistant.id);
+   * ```
+   */
   getAgentById(id) {
     let agent = Object.values(this.#agents).find(a => a.id === id);
     if (!agent) {
@@ -502,9 +609,66 @@ do:
     }
     return agent;
   }
+  /**
+   * Returns all registered agents as a record keyed by their names.
+   *
+   * This method provides access to the complete registry of agents, allowing you to
+   * iterate over them, check what agents are available, or perform bulk operations.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   agents: {
+   *     weatherAgent: new Agent({ name: 'weather', model: openai('gpt-4o') }),
+   *     supportAgent: new Agent({ name: 'support', model: openai('gpt-4o') })
+   *   }
+   * });
+   *
+   * const allAgents = mastra.getAgents();
+   * console.log(Object.keys(allAgents)); // ['weatherAgent', 'supportAgent']
+   * ```
+   */
   getAgents() {
     return this.#agents;
   }
+  /**
+   * Retrieves a registered vector store by its name.
+   *
+   * @template TVectorName - The specific vector store name type from the registered vectors
+   * @throws {MastraError} When the vector store with the specified name is not found
+   *
+   * @example Using a vector store for semantic search
+   * ```typescript
+   * import { PineconeVector } from '@mastra/pinecone';
+   * import { OpenAIEmbedder } from '@mastra/embedders';
+   *
+   * const mastra = new Mastra({
+   *   vectors: {
+   *     knowledge: new PineconeVector({
+   *       apiKey: process.env.PINECONE_API_KEY,
+   *       indexName: 'knowledge-base',
+   *       embedder: new OpenAIEmbedder({
+   *         apiKey: process.env.OPENAI_API_KEY,
+   *         model: 'text-embedding-3-small'
+   *       })
+   *     }),
+   *     products: new PineconeVector({
+   *       apiKey: process.env.PINECONE_API_KEY,
+   *       indexName: 'product-catalog'
+   *     })
+   *   }
+   * });
+   *
+   * // Get a vector store and perform semantic search
+   * const knowledgeBase = mastra.getVector('knowledge');
+   * const results = await knowledgeBase.query({
+   *   query: 'How to reset password?',
+   *   topK: 5
+   * });
+   *
+   * console.log('Relevant documents:', results);
+   * ```
+   */
   getVector(name) {
     const vector = this.#vectors?.[name];
     if (!vector) {
@@ -524,12 +688,78 @@ do:
     }
     return vector;
   }
+  /**
+   * Returns all registered vector stores as a record keyed by their names.
+   *
+   * @example Listing all vector stores
+   * ```typescript
+   * const mastra = new Mastra({
+   *   vectors: {
+   *     documents: new PineconeVector({ indexName: 'docs' }),
+   *     images: new PineconeVector({ indexName: 'images' }),
+   *     products: new ChromaVector({ collectionName: 'products' })
+   *   }
+   * });
+   *
+   * const allVectors = mastra.getVectors();
+   * console.log(Object.keys(allVectors)); // ['documents', 'images', 'products']
+   *
+   * // Check vector store types and configurations
+   * for (const [name, vectorStore] of Object.entries(allVectors)) {
+   *   console.log(`Vector store ${name}:`, vectorStore.constructor.name);
+   * }
+   * ```
+   */
   getVectors() {
     return this.#vectors;
   }
+  /**
+   * Gets the currently configured deployment provider.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   deployer: new VercelDeployer({
+   *     token: process.env.VERCEL_TOKEN,
+   *     projectId: process.env.VERCEL_PROJECT_ID
+   *   })
+   * });
+   *
+   * const deployer = mastra.getDeployer();
+   * if (deployer) {
+   *   await deployer.deploy({
+   *     name: 'my-mastra-app',
+   *     environment: 'production'
+   *   });
+   * }
+   * ```
+   */
   getDeployer() {
     return this.#deployer;
   }
+  /**
+   * Retrieves a registered legacy workflow by its ID.
+   *
+   * Legacy workflows are the previous generation of workflow system in Mastra,
+   * maintained for backward compatibility. For new implementations, use the
+   * modern workflow system accessed via `getWorkflow()`.
+   *
+   * @template TWorkflowId - The specific workflow ID type from the registered legacy workflows
+   * @throws {MastraError} When the legacy workflow with the specified ID is not found
+   * @deprecated Use `getWorkflow()` for new implementations
+   *
+   * @example Getting a legacy workflow
+   * ```typescript
+   * const mastra = new Mastra({
+   *   legacy_workflows: {
+   *     oldDataFlow: legacyWorkflowInstance
+   *   }
+   * });
+   *
+   * const workflow = mastra.legacy_getWorkflow('oldDataFlow');
+   * const result = await workflow.execute({ input: 'data' });
+   * ```
+   */
   legacy_getWorkflow(id, {
     serialized
   } = {}) {
@@ -556,6 +786,33 @@ do:
     }
     return workflow;
   }
+  /**
+   * Retrieves a registered workflow by its ID.
+   *
+   * @template TWorkflowId - The specific workflow ID type from the registered workflows
+   * @throws {MastraError} When the workflow with the specified ID is not found
+   *
+   * @example Getting and executing a workflow
+   * ```typescript
+   * import { createWorkflow, createStep } from '@mastra/core/workflows';
+   * import { z } from 'zod';
+   *
+   * const processDataWorkflow = createWorkflow({
+   *   name: 'process-data',
+   *   triggerSchema: z.object({ input: z.string() })
+   * })
+   *   .then(validateStep)
+   *   .then(transformStep)
+   *   .then(saveStep)
+   *   .commit();
+   *
+   * const mastra = new Mastra({
+   *   workflows: {
+   *     dataProcessor: processDataWorkflow
+   *   }
+   * });
+   * ```
+   */
   getWorkflow(id, {
     serialized
   } = {}) {
@@ -609,6 +866,35 @@ do:
     }
     return workflow;
   }
+  /**
+   * Retrieves a registered workflow by its unique ID.
+   *
+   * This method searches for a workflow using its internal ID property. If no workflow
+   * is found with the given ID, it also attempts to find a workflow using the ID as
+   * a name (for backward compatibility).
+   *
+   * @throws {MastraError} When no workflow is found with the specified ID
+   *
+   * @example Finding a workflow by ID
+   * ```typescript
+   * const mastra = new Mastra({
+   *   workflows: {
+   *     dataProcessor: createWorkflow({
+   *       name: 'process-data',
+   *       triggerSchema: z.object({ input: z.string() })
+   *     }).commit()
+   *   }
+   * });
+   *
+   * // Get the workflow's ID
+   * const workflow = mastra.getWorkflow('dataProcessor');
+   * const workflowId = workflow.id;
+   *
+   * // Later, retrieve the workflow by ID
+   * const sameWorkflow = mastra.getWorkflowById(workflowId);
+   * console.log(sameWorkflow.name); // "process-data"
+   * ```
+   */
   getWorkflowById(id) {
     let workflow = Object.values(this.#workflows).find(a => a.id === id);
     if (!workflow) {
@@ -633,6 +919,32 @@ do:
     }
     return workflow;
   }
+  /**
+   * Returns all registered legacy workflows as a record keyed by their IDs.
+   *
+   * Legacy workflows are the previous generation of workflow system in Mastra,
+   * maintained for backward compatibility. For new implementations, use `getWorkflows()`.
+   *
+   * @deprecated Use `getWorkflows()` for new implementations
+   *
+   * @example Listing all legacy workflows
+   * ```typescript
+   * const mastra = new Mastra({
+   *   legacy_workflows: {
+   *     oldFlow1: legacyWorkflow1,
+   *     oldFlow2: legacyWorkflow2
+   *   }
+   * });
+   *
+   * const allLegacyWorkflows = mastra.legacy_getWorkflows();
+   * console.log(Object.keys(allLegacyWorkflows)); // ['oldFlow1', 'oldFlow2']
+   *
+   * // Execute all legacy workflows
+   * for (const [id, workflow] of Object.entries(allLegacyWorkflows)) {
+   *   console.log(`Legacy workflow ${id}:`, workflow.name);
+   * }
+   * ```
+   */
   legacy_getWorkflows(props = {}) {
     if (props.serialized) {
       return Object.entries(this.#legacy_workflows).reduce((acc, [k, v]) => {
@@ -646,9 +958,66 @@ do:
     }
     return this.#legacy_workflows;
   }
+  /**
+   * Returns all registered scorers as a record keyed by their IDs.
+   *
+   * @example Listing all scorers
+   * ```typescript
+   * import { HelpfulnessScorer, AccuracyScorer, RelevanceScorer } from '@mastra/scorers';
+   *
+   * const mastra = new Mastra({
+   *   scorers: {
+   *     helpfulness: new HelpfulnessScorer(),
+   *     accuracy: new AccuracyScorer(),
+   *     relevance: new RelevanceScorer()
+   *   }
+   * });
+   *
+   * const allScorers = mastra.getScorers();
+   * console.log(Object.keys(allScorers)); // ['helpfulness', 'accuracy', 'relevance']
+   *
+   * // Check scorer configurations
+   * for (const [id, scorer] of Object.entries(allScorers)) {
+   *   console.log(`Scorer ${id}:`, scorer.name, scorer.description);
+   * }
+   * ```
+   */
   getScorers() {
     return this.#scorers;
   }
+  /**
+   * Retrieves a registered scorer by its key.
+   *
+   * @template TScorerKey - The specific scorer key type from the registered scorers
+   * @throws {MastraError} When the scorer with the specified key is not found
+   *
+   * @example Getting and using a scorer
+   * ```typescript
+   * import { HelpfulnessScorer, AccuracyScorer } from '@mastra/scorers';
+   *
+   * const mastra = new Mastra({
+   *   scorers: {
+   *     helpfulness: new HelpfulnessScorer({
+   *       model: openai('gpt-4o'),
+   *       criteria: 'Rate how helpful this response is'
+   *     }),
+   *     accuracy: new AccuracyScorer({
+   *       model: 'openai/gpt-5'
+   *     })
+   *   }
+   * });
+   *
+   * // Get a specific scorer
+   * const helpfulnessScorer = mastra.getScorer('helpfulness');
+   * const score = await helpfulnessScorer.score({
+   *   input: 'How do I reset my password?',
+   *   output: 'You can reset your password by clicking the forgot password link.',
+   *   expected: 'Detailed password reset instructions'
+   * });
+   *
+   * console.log('Helpfulness score:', score);
+   * ```
+   */
   getScorer(key) {
     const scorer = this.#scorers?.[key];
     if (!scorer) {
@@ -663,6 +1032,36 @@ do:
     }
     return scorer;
   }
+  /**
+   * Retrieves a registered scorer by its name.
+   *
+   * This method searches through all registered scorers to find one with the specified name.
+   * Unlike `getScorer()` which uses the registration key, this method uses the scorer's
+   * internal name property.
+   *
+   * @throws {MastraError} When no scorer is found with the specified name
+   *
+   * @example Finding a scorer by name
+   * ```typescript
+   * import { HelpfulnessScorer } from '@mastra/scorers';
+   *
+   * const mastra = new Mastra({
+   *   scorers: {
+   *     myHelpfulnessScorer: new HelpfulnessScorer({
+   *       name: 'helpfulness-evaluator',
+   *       model: 'openai/gpt-5'
+   *     })
+   *   }
+   * });
+   *
+   * // Find scorer by its internal name, not the registration key
+   * const scorer = mastra.getScorerByName('helpfulness-evaluator');
+   * const score = await scorer.score({
+   *   input: 'question',
+   *   output: 'answer'
+   * });
+   * ```
+   */
   getScorerByName(name) {
     for (const [_key, value] of Object.entries(this.#scorers ?? {})) {
       if (value.name === name) {
@@ -678,6 +1077,29 @@ do:
     this.#logger?.trackException(error);
     throw error;
   }
+  /**
+   * Returns all registered workflows as a record keyed by their IDs.
+   *
+   * @example Listing all workflows
+   * ```typescript
+   * const mastra = new Mastra({
+   *   workflows: {
+   *     dataProcessor: createWorkflow({...}).commit(),
+   *     emailSender: createWorkflow({...}).commit(),
+   *     reportGenerator: createWorkflow({...}).commit()
+   *   }
+   * });
+   *
+   * const allWorkflows = mastra.getWorkflows();
+   * console.log(Object.keys(allWorkflows)); // ['dataProcessor', 'emailSender', 'reportGenerator']
+   *
+   * // Execute all workflows with sample data
+   * for (const [id, workflow] of Object.entries(allWorkflows)) {
+   *   console.log(`Workflow ${id}:`, workflow.name);
+   *   // const result = await workflow.execute(sampleData);
+   * }
+   * ```
+   */
   getWorkflows(props = {}) {
     if (props.serialized) {
       return Object.entries(this.#workflows).reduce((acc, [k, v]) => {
@@ -691,6 +1113,25 @@ do:
     }
     return this.#workflows;
   }
+  /**
+   * Sets the storage provider for the Mastra instance.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra();
+   *
+   * // Set PostgreSQL storage
+   * mastra.setStorage(new PostgresStore({
+   *   connectionString: process.env.DATABASE_URL
+   * }));
+   *
+   * // Now agents can use memory with the storage
+   * const agent = new Agent({
+   *   name: 'assistant',
+   *   memory: new Memory({ storage: mastra.getStorage() })
+   * });
+   * ```
+   */
   setStorage(storage) {
     this.#storage = chunkV3VLOOSW_cjs.augmentWithInit(storage);
   }
@@ -727,7 +1168,7 @@ do:
         this.#mcpServers?.[key]?.__setLogger(this.#logger);
       });
     }
-    const allTracingInstances = chunkDVHBWEYY_cjs.getAllAITracing();
+    const allTracingInstances = chunkLCJHFYJS_cjs.getAllAITracing();
     allTracingInstances.forEach(instance => {
       instance.__setLogger(this.#logger);
     });
@@ -784,18 +1225,116 @@ do:
       this.#vectors = vectors;
     }
   }
+  /**
+   * Gets all registered text-to-speech (TTS) providers.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   tts: {
+   *     openai: new OpenAITTS({
+   *       apiKey: process.env.OPENAI_API_KEY,
+   *       voice: 'alloy'
+   *     })
+   *   }
+   * });
+   *
+   * const ttsProviders = mastra.getTTS();
+   * const openaiTTS = ttsProviders?.openai;
+   * if (openaiTTS) {
+   *   const audioBuffer = await openaiTTS.synthesize('Hello, world!');
+   * }
+   * ```
+   */
   getTTS() {
     return this.#tts;
   }
+  /**
+   * Gets the currently configured logger instance.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   logger: new PinoLogger({
+   *     name: 'MyApp',
+   *     level: 'info'
+   *   })
+   * });
+   *
+   * const logger = mastra.getLogger();
+   * logger.info('Application started');
+   * logger.error('An error occurred', { error: 'details' });
+   * ```
+   */
   getLogger() {
     return this.#logger;
   }
+  /**
+   * Gets the currently configured telemetry instance.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   telemetry: {
+   *     enabled: true,
+   *     serviceName: 'my-mastra-app'
+   *   }
+   * });
+   *
+   * const telemetry = mastra.getTelemetry();
+   * if (telemetry) {
+   *   const span = telemetry.startSpan('custom-operation');
+   *   span.setAttributes({ operation: 'data-processing' });
+   *   span.end();
+   * }
+   * ```
+   */
   getTelemetry() {
     return this.#telemetry;
   }
+  /**
+   * Gets the currently configured memory instance.
+   *
+   * @deprecated Memory should be configured directly on agents instead of on the Mastra instance.
+   * Use `new Agent({ memory: new Memory() })` instead.
+   *
+   * @example Legacy memory usage (deprecated)
+   * ```typescript
+   * // This approach is deprecated
+   * const mastra = new Mastra({
+   *   // memory: new Memory() // This is no longer supported
+   * });
+   *
+   * // Use this instead:
+   * const agent = new Agent({
+   *   name: 'assistant',
+   *   memory: new Memory({
+   *     storage: new LibSQLStore({ url: ':memory:' })
+   *   })
+   * });
+   * ```
+   */
   getMemory() {
     return this.#memory;
   }
+  /**
+   * Gets the currently configured storage provider.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   storage: new LibSQLStore({ url: 'file:./data.db' })
+   * });
+   *
+   * // Use the storage in agent memory
+   * const agent = new Agent({
+   *   name: 'assistant',
+   *   memory: new Memory({
+   *     storage: mastra.getStorage()
+   *   })
+   * });
+   * ```
+   */
   getStorage() {
     return this.#storage;
   }
@@ -920,20 +1459,52 @@ do:
     return await this.#logger.getLogs(transportId, params);
   }
   /**
-   * Get all registered MCP server instances.
-   * @returns A record of MCP server ID to MCPServerBase instance, or undefined if none are registered.
+   * Gets all registered Model Context Protocol (MCP) server instances.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   mcpServers: {
+   *     filesystem: new FileSystemMCPServer({
+   *       rootPath: '/app/data'
+   *     })
+   *   }
+   * });
+   *
+   * const mcpServers = mastra.getMCPServers();
+   * if (mcpServers) {
+   *   const fsServer = mcpServers.filesystem;
+   *   const tools = await fsServer.getTools();
+   * }
+   * ```
    */
   getMCPServers() {
     return this.#mcpServers;
   }
   /**
-   * Get a specific MCP server instance.
-   * If a version is provided, it attempts to find the server with that exact logical ID and version.
-   * If no version is provided, it returns the server with the specified logical ID that has the most recent releaseDate.
-   * The logical ID should match the `id` property of the MCPServer instance (typically set via MCPServerConfig.id).
-   * @param serverId - The logical ID of the MCP server to retrieve.
-   * @param version - Optional specific version of the MCP server to retrieve.
-   * @returns The MCP server instance, or undefined if not found or if the specific version is not found.
+   * Retrieves a specific Model Context Protocol (MCP) server instance by its logical ID.
+   *
+   * This method searches for an MCP server using its logical ID. If a version is specified,
+   * it returns the exact version match. If no version is provided, it returns the server
+   * with the most recent release date.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   mcpServers: {
+   *     filesystem: new FileSystemMCPServer({
+   *       id: 'fs-server',
+   *       version: '1.0.0',
+   *       rootPath: '/app/data'
+   *     })
+   *   }
+   * });
+   *
+   * const fsServer = mastra.getMCPServer('fs-server');
+   * if (fsServer) {
+   *   const tools = await fsServer.getTools();
+   * }
+   * ```
    */
   getMCPServer(serverId, version) {
     if (!this.#mcpServers) {
@@ -1003,10 +1574,32 @@ do:
     await this.#pubsub.flush();
   }
   /**
-   * Shutdown Mastra and clean up all resources
+   * Gracefully shuts down the Mastra instance and cleans up all resources.
+   *
+   * This method performs a clean shutdown of all Mastra components, including:
+   * - AI tracing registry and all tracing instances
+   * - Event engine and pub/sub system
+   * - All registered components and their resources
+   *
+   * It's important to call this method when your application is shutting down
+   * to ensure proper cleanup and prevent resource leaks.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   agents: { myAgent },
+   *   workflows: { myWorkflow }
+   * });
+   *
+   * // Graceful shutdown on SIGINT
+   * process.on('SIGINT', async () => {
+   *   await mastra.shutdown();
+   *   process.exit(0);
+   * });
+   * ```
    */
   async shutdown() {
-    await chunkDVHBWEYY_cjs.shutdownAITracingRegistry();
+    await chunkLCJHFYJS_cjs.shutdownAITracingRegistry();
     await this.stopEventEngine();
     this.#logger?.info("Mastra shutdown completed");
   }
@@ -1021,5 +1614,5 @@ exports.Mastra = /*@__PURE__*/(_ => {
   chunkEBVYYC2Q_cjs.__runInitializers(_init, 1, exports.Mastra);
   return exports.Mastra;
 })();
-//# sourceMappingURL=chunk-7EUC32F3.cjs.map
-//# sourceMappingURL=chunk-7EUC32F3.cjs.map
+//# sourceMappingURL=chunk-6K7IMZVR.cjs.map
+//# sourceMappingURL=chunk-6K7IMZVR.cjs.map