@mastra/core 0.24.0 → 1.0.0-beta.1

package/dist/mastra/index.d.ts

@@ -1,24 +1,22 @@
 import type { Agent } from '../agent/index.js';
-import type { ObservabilityRegistryConfig } from '../ai-tracing/index.js';
 import type { BundlerConfig } from '../bundler/types.js';
 import type { MastraServerCache } from '../cache/index.js';
 import type { MastraDeployer } from '../deployer/index.js';
+import type { MastraScorer } from '../evals/index.js';
 import type { PubSub } from '../events/pubsub.js';
 import type { Event } from '../events/types.js';
 import { LogLevel } from '../logger/index.js';
 import type { IMastraLogger } from '../logger/index.js';
 import type { MCPServerBase } from '../mcp/index.js';
-import type { MastraMemory } from '../memory/memory.js';
-import type { MastraScorer } from '../scores/index.js';
+import type { ObservabilityEntrypoint } from '../observability/index.js';
+import type { Processor } from '../processors/index.js';
 import type { Middleware, ServerConfig } from '../server/types.js';
 import type { MastraStorage } from '../storage/index.js';
-import { Telemetry } from '../telemetry/index.js';
-import type { OtelConfig } from '../telemetry/index.js';
+import type { ToolAction } from '../tools/index.js';
 import type { MastraTTS } from '../tts/index.js';
 import type { MastraIdGenerator } from '../types/index.js';
 import type { MastraVector } from '../vector/index.js';
 import type { Workflow } from '../workflows/index.js';
-import type { LegacyWorkflow } from '../workflows/legacy/index.js';
 /**
  * Configuration interface for initializing a Mastra instance.
  *
@@ -26,7 +24,6 @@ import type { LegacyWorkflow } from '../workflows/legacy/index.js';
  * with a Mastra instance, including agents, workflows, storage, logging, and more.
  *
  * @template TAgents - Record of agent instances keyed by their names
- * @template TLegacyWorkflows - Record of legacy workflow instances
  * @template TWorkflows - Record of workflow instances
  * @template TVectors - Record of vector store instances
  * @template TTTS - Record of text-to-speech instances
@@ -40,17 +37,18 @@ import type { LegacyWorkflow } from '../workflows/legacy/index.js';
  * const mastra = new Mastra({
  *   agents: {
  *     weatherAgent: new Agent({
- *       name: 'weather-agent',
+ *       id: 'weather-agent',
+ *       name: 'Weather Agent',
  *       instructions: 'You help with weather information',
  *       model: 'openai/gpt-5'
  *     })
  *   },
- *   storage: new LibSQLStore({ url: ':memory:' }),
+ *   storage: new LibSQLStore({ id: 'mastra-storage', url: ':memory:' }),
  *   logger: new PinoLogger({ name: 'MyApp' })
  * });
  * ```
  */
-export interface Config<TAgents extends Record<string, Agent<any>> = Record<string, Agent<any>>, TLegacyWorkflows extends Record<string, LegacyWorkflow> = Record<string, LegacyWorkflow>, TWorkflows extends Record<string, Workflow<any, any, any, any, any, any>> = Record<string, Workflow<any, any, any, any, any, any>>, TVectors extends Record<string, MastraVector> = Record<string, MastraVector>, TTTS extends Record<string, MastraTTS> = Record<string, MastraTTS>, TLogger extends IMastraLogger = IMastraLogger, TMCPServers extends Record<string, MCPServerBase> = Record<string, MCPServerBase>, TScorers extends Record<string, MastraScorer<any, any, any, any>> = Record<string, MastraScorer<any, any, any, any>>> {
+export interface Config<TAgents extends Record<string, Agent<any>> = Record<string, Agent<any>>, TWorkflows extends Record<string, Workflow<any, any, any, any, any, any>> = Record<string, Workflow<any, any, any, any, any, any>>, TVectors extends Record<string, MastraVector> = Record<string, MastraVector>, TTTS extends Record<string, MastraTTS> = Record<string, MastraTTS>, TLogger extends IMastraLogger = IMastraLogger, TMCPServers extends Record<string, MCPServerBase> = Record<string, MCPServerBase>, TScorers extends Record<string, MastraScorer<any, any, any, any>> = Record<string, MastraScorer<any, any, any, any>>, TTools extends Record<string, ToolAction<any, any, any, any>> = Record<string, ToolAction<any, any, any, any>>, TProcessors extends Record<string, Processor> = Record<string, Processor>> {
     /**
      * Agents are autonomous systems that can make decisions and take actions.
      */
@@ -71,11 +69,6 @@ export interface Config<TAgents extends Record<string, Agent<any>> = Record<stri
      * @default `INFO` level in development, `WARN` in production.
      */
     logger?: TLogger | false;
-    /**
-     * Legacy workflow definitions for backward compatibility.
-     * @deprecated Use `workflows` instead.
-     */
-    legacy_workflows?: TLegacyWorkflows;
     /**
      * Workflows provide type-safe, composable task execution with built-in error handling.
      */
@@ -85,15 +78,21 @@ export interface Config<TAgents extends Record<string, Agent<any>> = Record<stri
      */
     tts?: TTTS;
     /**
-     * OpenTelemetry configuration for distributed tracing and observability.
+     * Observability entrypoint for tracking model interactions and tracing.
+     * Pass an instance of the Observability class from @mastra/observability.
      *
-     * @deprecated Use {@link observability} instead.
-     */
-    telemetry?: OtelConfig;
-    /**
-     * AI-specific observability configuration for tracking model interactions.
+     * @example
+     * ```typescript
+     * import { Observability } from '@mastra/observability';
+     *
+     * new Mastra({
+     *   observability: new Observability({
+     *     default: { enabled: true }
+     *   })
+     * })
+     * ```
      */
-    observability?: ObservabilityRegistryConfig;
+    observability?: ObservabilityEntrypoint;
     /**
      * Custom ID generator function for creating unique identifiers.
      * @default `crypto.randomUUID()`
@@ -125,15 +124,13 @@ export interface Config<TAgents extends Record<string, Agent<any>> = Record<stri
      */
     scorers?: TScorers;
     /**
-     * Server middleware functions to be applied to API routes
-     * Each middleware can specify a path pattern (defaults to '/api/*')
-     * @deprecated use server.middleware instead
+     * Tools are reusable functions that agents can use to interact with external systems.
      */
-    serverMiddleware?: Array<{
-        handler: (c: any, next: () => Promise<void>) => Promise<Response | void>;
-        path?: string;
-    }>;
-    memory?: never;
+    tools?: TTools;
+    /**
+     * Processors transform inputs and outputs for agents and workflows.
+     */
+    processors?: TProcessors;
     /**
      * Event handlers for custom application events.
      * Maps event topics to handler functions for event-driven architectures.
@@ -142,20 +139,41 @@ export interface Config<TAgents extends Record<string, Agent<any>> = Record<stri
         [topic: string]: (event: Event, cb?: () => Promise<void>) => Promise<void> | ((event: Event, cb?: () => Promise<void>) => Promise<void>)[];
     };
 }
-export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<string, Agent<any>>, TLegacyWorkflows extends Record<string, LegacyWorkflow> = Record<string, LegacyWorkflow>, TWorkflows extends Record<string, Workflow<any, any, any, any, any, any>> = Record<string, Workflow<any, any, any, any, any, any>>, TVectors extends Record<string, MastraVector> = Record<string, MastraVector>, TTTS extends Record<string, MastraTTS> = Record<string, MastraTTS>, TLogger extends IMastraLogger = IMastraLogger, TMCPServers extends Record<string, MCPServerBase> = Record<string, MCPServerBase>, TScorers extends Record<string, MastraScorer<any, any, any, any>> = Record<string, MastraScorer<any, any, any, any>>> {
+/**
+ * The central orchestrator for Mastra applications, managing agents, workflows, storage, logging, observability, and more.
+ *
+ * The `Mastra` class serves as the main entry point and registry for all components in a Mastra application.
+ * It coordinates the interaction between agents, workflows, storage systems, and other services.
+
+ * @template TAgents - Record of agent instances keyed by their names
+ * @template TWorkflows - Record of modern workflow instances
+ * @template TVectors - Record of vector store instances for semantic search and RAG
+ * @template TTTS - Record of text-to-speech provider instances
+ * @template TLogger - Logger implementation type for application logging
+ * @template TVNextNetworks - Record of next-generation agent network instances
+ * @template TMCPServers - Record of Model Context Protocol server instances
+ * @template TScorers - Record of evaluation scorer instances for measuring AI performance
+ *
+ * @example
+ * ```typescript
+ * const mastra = new Mastra({
+ *   agents: {
+ *     weatherAgent: new Agent({
+ *       id: 'weather-agent',
+ *       name: 'Weather Agent',
+ *       instructions: 'You provide weather information',
+ *       model: 'openai/gpt-5',
+ *       tools: [getWeatherTool]
+ *     })
+ *   },
+ *   workflows: { dataWorkflow },
+ *   storage: new LibSQLStore({ id: 'mastra-storage', url: ':memory:' }),
+ *   logger: new PinoLogger({ name: 'MyApp' })
+ * });
+ * ```
+ */
+export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<string, Agent<any>>, TWorkflows extends Record<string, Workflow<any, any, any, any, any, any>> = Record<string, Workflow<any, any, any, any, any, any>>, TVectors extends Record<string, MastraVector> = Record<string, MastraVector>, TTTS extends Record<string, MastraTTS> = Record<string, MastraTTS>, TLogger extends IMastraLogger = IMastraLogger, TMCPServers extends Record<string, MCPServerBase> = Record<string, MCPServerBase>, TScorers extends Record<string, MastraScorer<any, any, any, any>> = Record<string, MastraScorer<any, any, any, any>>, TTools extends Record<string, ToolAction<any, any, any, any>> = Record<string, ToolAction<any, any, any, any>>, TProcessors extends Record<string, Processor> = Record<string, Processor>> {
     #private;
-    /**
-     * @deprecated use {@link getAITracing()} instead
-     */
-    get telemetry(): Telemetry | undefined;
-    /**
-     * @deprecated use getStorage() instead
-     */
-    get storage(): MastraStorage | undefined;
-    /**
-     * @deprecated use getMemory() instead
-     */
-    get memory(): MastraMemory | undefined;
     get pubsub(): PubSub;
     /**
      * Gets the currently configured ID generator function.
@@ -206,14 +224,15 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * 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.
+     * internal systems like logging and observability, and registers components with each other.
      *
      * @example
      * ```typescript
      * const mastra = new Mastra({
      *   agents: {
      *     assistant: new Agent({
-     *       name: 'assistant',
+     *       id: 'assistant',
+     *       name: 'Assistant',
      *       instructions: 'You are a helpful assistant',
      *       model: 'openai/gpt-5'
      *     })
@@ -221,19 +240,12 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *   storage: new PostgresStore({
      *     connectionString: process.env.DATABASE_URL
      *   }),
-     *   logger: new PinoLogger({ name: 'MyApp' })
+     *   logger: new PinoLogger({ name: 'MyApp' }),
+     *   observability: { default: { enabled: true }},
      * });
      * ```
      */
-    constructor(config?: Config<TAgents, TLegacyWorkflows, TWorkflows, TVectors, TTTS, TLogger, TMCPServers, TScorers>);
-    /**
-     * Register this Mastra instance with AI tracing exporters that need it
-     */
-    private registerAITracingExporters;
-    /**
-     * Initialize all AI tracing exporters after registration is complete
-     */
-    private initAITracingExporters;
+    constructor(config?: Config<TAgents, TWorkflows, TVectors, TTTS, TLogger, TMCPServers, TScorers, TTools, TProcessors>);
     /**
      * Retrieves a registered agent by its name.
      *
@@ -245,6 +257,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * const mastra = new Mastra({
      *   agents: {
      *     weatherAgent: new Agent({
+     *       id: 'weather-agent',
      *       name: 'weather-agent',
      *       instructions: 'You provide weather information',
      *       model: 'openai/gpt-5'
@@ -261,7 +274,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *
      * 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).
+     * a name.
      *
      * @throws {MastraError} When no agent is found with the specified ID
      *
@@ -270,6 +283,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * const mastra = new Mastra({
      *   agents: {
      *     assistant: new Agent({
+     *       id: 'assistant',
      *       name: 'assistant',
      *       instructions: 'You are a helpful assistant',
      *       model: 'openai/gpt-5'
@@ -292,16 +306,38 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * ```typescript
      * const mastra = new Mastra({
      *   agents: {
-     *     weatherAgent: new Agent({ name: 'weather', model: openai('gpt-4o') }),
-     *     supportAgent: new Agent({ name: 'support', model: openai('gpt-4o') })
+     *     weatherAgent: new Agent({ id: 'weather-agent', name: 'weather', model: 'openai/gpt-4o' }),
+     *     supportAgent: new Agent({ id: 'support-agent', name: 'support', model: 'openai/gpt-4o' })
      *   }
      * });
      *
-     * const allAgents = mastra.getAgents();
+     * const allAgents = mastra.listAgents();
      * console.log(Object.keys(allAgents)); // ['weatherAgent', 'supportAgent']
      * ```
      */
-    getAgents(): TAgents;
+    listAgents(): TAgents;
+    /**
+     * Adds a new agent to the Mastra instance.
+     *
+     * This method allows dynamic registration of agents after the Mastra instance
+     * has been created. The agent will be initialized with the current logger.
+     *
+     * @throws {MastraError} When an agent with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newAgent = new Agent({
+     *   id: 'chat-agent',
+     *   name: 'Chat Assistant',
+     *   model: 'openai/gpt-4o'
+     * });
+     * mastra.addAgent(newAgent); // Uses agent.id as key
+     * // or
+     * mastra.addAgent(newAgent, 'customKey'); // Uses custom key
+     * ```
+     */
+    addAgent<A extends Agent<any>>(agent: A, key?: string): void;
     /**
      * Retrieves a registered vector store by its name.
      *
@@ -341,6 +377,26 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * ```
      */
     getVector<TVectorName extends keyof TVectors>(name: TVectorName): TVectors[TVectorName];
+    /**
+     * Retrieves a specific vector store instance by its ID.
+     *
+     * This method searches for a vector store by its internal ID property.
+     * If not found by ID, it falls back to searching by registration key.
+     *
+     * @throws {MastraError} When the specified vector store is not found
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   vectors: {
+     *     embeddings: chromaVector
+     *   }
+     * });
+     *
+     * const vectorStore = mastra.getVectorById('chroma-123');
+     * ```
+     */
+    getVectorById(id: string): MastraVector;
     /**
      * Returns all registered vector stores as a record keyed by their names.
      *
@@ -363,6 +419,28 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * }
      * ```
      */
+    listVectors(): TVectors | undefined;
+    /**
+     * Adds a new vector store to the Mastra instance.
+     *
+     * This method allows dynamic registration of vector stores after the Mastra instance
+     * has been created. The vector store will be initialized with the current logger.
+     *
+     * @throws {MastraError} When a vector store with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newVector = new ChromaVector({ id: 'chroma-embeddings' });
+     * mastra.addVector(newVector); // Uses vector.id as key
+     * // or
+     * mastra.addVector(newVector, 'customKey'); // Uses custom key
+     * ```
+     */
+    addVector<V extends MastraVector>(vector: V, key?: string): void;
+    /**
+     * @deprecated Use listVectors() instead
+     */
     getVectors(): TVectors | undefined;
     /**
      * Gets the currently configured deployment provider.
@@ -386,32 +464,6 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * ```
      */
     getDeployer(): MastraDeployer | undefined;
-    /**
-     * 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<TWorkflowId extends keyof TLegacyWorkflows>(id: TWorkflowId, { serialized }?: {
-        serialized?: boolean;
-    }): TLegacyWorkflows[TWorkflowId];
     /**
      * Retrieves a registered workflow by its ID.
      *
@@ -450,7 +502,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *
      * 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).
+     * a name.
      *
      * @throws {MastraError} When no workflow is found with the specified ID
      *
@@ -475,35 +527,6 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * ```
      */
     getWorkflowById(id: string): 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?: {
-        serialized?: boolean;
-    }): Record<string, LegacyWorkflow>;
     /**
      * Returns all registered scorers as a record keyed by their IDs.
      *
@@ -519,16 +542,37 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *   }
      * });
      *
-     * const allScorers = mastra.getScorers();
+     * const allScorers = mastra.listScorers();
      * 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);
+     *   console.log(`Scorer ${id}:`, scorer.id, scorer.name, scorer.description);
      * }
      * ```
      */
-    getScorers(): TScorers | undefined;
+    listScorers(): TScorers | undefined;
+    /**
+     * Adds a new scorer to the Mastra instance.
+     *
+     * This method allows dynamic registration of scorers after the Mastra instance
+     * has been created.
+     *
+     * @throws {MastraError} When a scorer with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newScorer = new MastraScorer({
+     *   id: 'quality-scorer',
+     *   name: 'Quality Scorer'
+     * });
+     * mastra.addScorer(newScorer); // Uses scorer.id as key
+     * // or
+     * mastra.addScorer(newScorer, 'customKey'); // Uses custom key
+     * ```
+     */
+    addScorer<S extends MastraScorer<any, any, any, any>>(scorer: S, key?: string): void;
     /**
      * Retrieves a registered scorer by its key.
      *
@@ -542,7 +586,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * const mastra = new Mastra({
      *   scorers: {
      *     helpfulness: new HelpfulnessScorer({
-     *       model: openai('gpt-4o'),
+     *       model: 'openai/gpt-4o',
      *       criteria: 'Rate how helpful this response is'
      *     }),
      *     accuracy: new AccuracyScorer({
@@ -586,14 +630,164 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * });
      *
      * // Find scorer by its internal name, not the registration key
-     * const scorer = mastra.getScorerByName('helpfulness-evaluator');
+     * const scorer = mastra.getScorerById('helpfulness-evaluator');
      * const score = await scorer.score({
      *   input: 'question',
      *   output: 'answer'
      * });
      * ```
      */
-    getScorerByName(name: string): MastraScorer<any, any, any, any>;
+    getScorerById(id: string): MastraScorer<any, any, any, any>;
+    /**
+     * Retrieves a specific tool by registration key.
+     *
+     * @throws {MastraError} When the specified tool is not found
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   tools: {
+     *     calculator: calculatorTool,
+     *     weather: weatherTool
+     *   }
+     * });
+     *
+     * const tool = mastra.getTool('calculator');
+     * ```
+     */
+    getTool<TToolName extends keyof TTools>(name: TToolName): TTools[TToolName];
+    /**
+     * Retrieves a specific tool by its ID.
+     *
+     * @throws {MastraError} When the specified tool is not found
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   tools: {
+     *     calculator: calculatorTool
+     *   }
+     * });
+     *
+     * const tool = mastra.getToolById('calculator-tool-id');
+     * ```
+     */
+    getToolById(id: string): ToolAction<any, any, any, any>;
+    /**
+     * Lists all configured tools.
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   tools: {
+     *     calculator: calculatorTool,
+     *     weather: weatherTool
+     *   }
+     * });
+     *
+     * const tools = mastra.listTools();
+     * Object.entries(tools || {}).forEach(([name, tool]) => {
+     *   console.log(`Tool "${name}":`, tool.id);
+     * });
+     * ```
+     */
+    listTools(): TTools | undefined;
+    /**
+     * Adds a new tool to the Mastra instance.
+     *
+     * This method allows dynamic registration of tools after the Mastra instance
+     * has been created.
+     *
+     * @throws {MastraError} When a tool with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newTool = createTool({
+     *   id: 'calculator-tool',
+     *   description: 'Performs calculations'
+     * });
+     * mastra.addTool(newTool); // Uses tool.id as key
+     * // or
+     * mastra.addTool(newTool, 'customKey'); // Uses custom key
+     * ```
+     */
+    addTool<T extends ToolAction<any, any, any, any>>(tool: T, key?: string): void;
+    /**
+     * Retrieves a specific processor by registration key.
+     *
+     * @throws {MastraError} When the specified processor is not found
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   processors: {
+     *     validator: validatorProcessor,
+     *     transformer: transformerProcessor
+     *   }
+     * });
+     *
+     * const processor = mastra.getProcessor('validator');
+     * ```
+     */
+    getProcessor<TProcessorName extends keyof TProcessors>(name: TProcessorName): TProcessors[TProcessorName];
+    /**
+     * Retrieves a specific processor by its ID.
+     *
+     * @throws {MastraError} When the specified processor is not found
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   processors: {
+     *     validator: validatorProcessor
+     *   }
+     * });
+     *
+     * const processor = mastra.getProcessorById('validator-processor-id');
+     * ```
+     */
+    getProcessorById(id: string): Processor;
+    /**
+     * Lists all configured processors.
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   processors: {
+     *     validator: validatorProcessor,
+     *     transformer: transformerProcessor
+     *   }
+     * });
+     *
+     * const processors = mastra.listProcessors();
+     * Object.entries(processors || {}).forEach(([name, processor]) => {
+     *   console.log(`Processor "${name}":`, processor.id);
+     * });
+     * ```
+     */
+    listProcessors(): TProcessors | undefined;
+    /**
+     * Adds a new processor to the Mastra instance.
+     *
+     * This method allows dynamic registration of processors after the Mastra instance
+     * has been created.
+     *
+     * @throws {MastraError} When a processor with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newProcessor = {
+     *   id: 'text-processor',
+     *   processInput: async (messages) => messages
+     * };
+     * mastra.addProcessor(newProcessor); // Uses processor.id as key
+     * // or
+     * mastra.addProcessor(newProcessor, 'customKey'); // Uses custom key
+     * ```
+     */
+    addProcessor<P extends Processor>(processor: P, key?: string): void;
     /**
      * Returns all registered workflows as a record keyed by their IDs.
      *
@@ -607,7 +801,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *   }
      * });
      *
-     * const allWorkflows = mastra.getWorkflows();
+     * const allWorkflows = mastra.listWorkflows();
      * console.log(Object.keys(allWorkflows)); // ['dataProcessor', 'emailSender', 'reportGenerator']
      *
      * // Execute all workflows with sample data
@@ -617,9 +811,30 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * }
      * ```
      */
-    getWorkflows(props?: {
+    listWorkflows(props?: {
         serialized?: boolean;
     }): Record<string, Workflow>;
+    /**
+     * Adds a new workflow to the Mastra instance.
+     *
+     * This method allows dynamic registration of workflows after the Mastra instance
+     * has been created. The workflow will be initialized with Mastra and primitives.
+     *
+     * @throws {MastraError} When a workflow with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newWorkflow = createWorkflow({
+     *   id: 'data-pipeline',
+     *   name: 'Data Pipeline'
+     * }).commit();
+     * mastra.addWorkflow(newWorkflow); // Uses workflow.id as key
+     * // or
+     * mastra.addWorkflow(newWorkflow, 'customKey'); // Uses custom key
+     * ```
+     */
+    addWorkflow<W extends Workflow<any, any, any, any, any, any>>(workflow: W, key?: string): void;
     /**
      * Sets the storage provider for the Mastra instance.
      *
@@ -634,6 +849,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *
      * // Now agents can use memory with the storage
      * const agent = new Agent({
+     *   id: 'assistant',
      *   name: 'assistant',
      *   memory: new Memory({ storage: mastra.getStorage() })
      * });
@@ -643,7 +859,6 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
     setLogger({ logger }: {
         logger: TLogger;
     }): void;
-    setTelemetry(telemetry: OtelConfig): void;
     /**
      * Gets all registered text-to-speech (TTS) providers.
      *
@@ -684,63 +899,18 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * ```
      */
     getLogger(): TLogger;
-    /**
-     * 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();
-     * }
-     * ```
-     *
-     * @deprecated use {@link getAITracing()} instead
-     */
-    getTelemetry(): Telemetry | undefined;
-    /**
-     * 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(): MastraMemory | undefined;
     /**
      * Gets the currently configured storage provider.
      *
      * @example
      * ```typescript
      * const mastra = new Mastra({
-     *   storage: new LibSQLStore({ url: 'file:./data.db' })
+     *   storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./data.db' })
      * });
      *
      * // Use the storage in agent memory
      * const agent = new Agent({
+     *   id: 'assistant',
      *   name: 'assistant',
      *   memory: new Memory({
      *     storage: mastra.getStorage()
@@ -749,6 +919,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * ```
      */
     getStorage(): MastraStorage | undefined;
+    get observability(): ObservabilityEntrypoint;
     getServerMiddleware(): {
         handler: (c: any, next: () => Promise<void>) => Promise<Response | void>;
         path: string;
@@ -757,7 +928,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
     setServerMiddleware(serverMiddleware: Middleware | Middleware[]): void;
     getServer(): ServerConfig | undefined;
     getBundlerConfig(): BundlerConfig | undefined;
-    getLogsByRunId({ runId, transportId, fromDate, toDate, logLevel, filters, page, perPage, }: {
+    listLogsByRunId({ runId, transportId, fromDate, toDate, logLevel, filters, page, perPage, }: {
         runId: string;
         transportId: string;
         fromDate?: Date;
@@ -773,7 +944,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
         perPage: number;
         hasMore: boolean;
     }>;
-    getLogs(transportId: string, params?: {
+    listLogs(transportId: string, params?: {
         fromDate?: Date;
         toDate?: Date;
         logLevel?: LogLevel;
@@ -803,11 +974,49 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * const mcpServers = mastra.getMCPServers();
      * if (mcpServers) {
      *   const fsServer = mcpServers.filesystem;
-     *   const tools = await fsServer.getTools();
+     *   const tools = await fsServer.listTools();
      * }
      * ```
      */
-    getMCPServers(): Record<string, MCPServerBase> | undefined;
+    listMCPServers(): Record<string, MCPServerBase> | undefined;
+    /**
+     * Adds a new MCP server to the Mastra instance.
+     *
+     * This method allows dynamic registration of MCP servers after the Mastra instance
+     * has been created. The server will be initialized with ID, Mastra instance, and logger.
+     *
+     * @throws {MastraError} When an MCP server with the same key already exists
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra();
+     * const newServer = new FileSystemMCPServer({
+     *   rootPath: '/data'
+     * });
+     * mastra.addMCPServer(newServer); // Uses server.id as key
+     * // or
+     * mastra.addMCPServer(newServer, 'customKey'); // Uses custom key
+     * ```
+     */
+    addMCPServer<M extends MCPServerBase>(server: M, key?: string): void;
+    /**
+     * Retrieves a specific MCP server instance by registration key.
+     *
+     * @throws {MastraError} When the specified MCP server is not found
+     *
+     * @example
+     * ```typescript
+     * const mastra = new Mastra({
+     *   mcpServers: {
+     *     filesystem: new FileSystemMCPServer({...})
+     *   }
+     * });
+     *
+     * const fsServer = mastra.getMCPServer('filesystem');
+     * const tools = await fsServer.listTools();
+     * ```
+     */
+    getMCPServer<TMCPServerName extends keyof TMCPServers>(name: TMCPServerName): TMCPServers[TMCPServerName] | undefined;
     /**
      * Retrieves a specific Model Context Protocol (MCP) server instance by its logical ID.
      *
@@ -827,13 +1036,13 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      *   }
      * });
      *
-     * const fsServer = mastra.getMCPServer('fs-server');
+     * const fsServer = mastra.getMCPServerById('fs-server');
      * if (fsServer) {
-     *   const tools = await fsServer.getTools();
+     *   const tools = await fsServer.listTools();
      * }
      * ```
      */
-    getMCPServer(serverId: string, version?: string): MCPServerBase | undefined;
+    getMCPServerById(serverId: string, version?: string): MCPServerBase | undefined;
     addTopicListener(topic: string, listener: (event: any) => Promise<void>): Promise<void>;
     removeTopicListener(topic: string, listener: (event: any) => Promise<void>): Promise<void>;
     startEventEngine(): Promise<void>;
@@ -842,7 +1051,7 @@ export declare class Mastra<TAgents extends Record<string, Agent<any>> = Record<
      * 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
+     * - tracing registry and all tracing instances
      * - Event engine and pub/sub system
      * - All registered components and their resources
      *