@mastra/core 0.24.0 → 1.0.0-beta.0

package/dist/{chunk-BWGXM3D4.js → chunk-7SKXKUYT.js}

@@ -1,15 +1,13 @@
-import { WorkflowEventProcessor } from './chunk-3VXXCPKX.js';
-import { saveScorePayloadSchema } from './chunk-KAEQISOW.js';
+import { WorkflowEventProcessor } from './chunk-P6APHXPZ.js';
 import { augmentWithInit } from './chunk-436FFEF6.js';
+import { saveScorePayloadSchema } from './chunk-76K3IYWM.js';
 import { PubSub } from './chunk-BVUMKER5.js';
-import { InstrumentClass, Telemetry } from './chunk-BLUDYAPI.js';
-import { InMemoryServerCache } from './chunk-3NTOFNIU.js';
-import { registerHook } from './chunk-TTELJD4F.js';
-import { setupAITracing, getAllAITracing, shutdownAITracingRegistry } from './chunk-DTTOVV72.js';
-import { noopLogger } from './chunk-PFXXH2RP.js';
-import { MastraError } from './chunk-PZUZNPFM.js';
-import { ConsoleLogger, LogLevel } from './chunk-UXG7PYML.js';
-import { __decoratorStart, __decorateElement, __runInitializers } from './chunk-3HXBPDKN.js';
+import { noopLogger } from './chunk-X7JMA3IY.js';
+import { registerHook } from './chunk-L54GIUCB.js';
+import { NoOpObservability } from './chunk-KIZIOFZC.js';
+import { MastraError } from './chunk-JJ5O45LH.js';
+import { InMemoryServerCache } from './chunk-OJNJA5ZI.js';
+import { ConsoleLogger, LogLevel } from './chunk-KJ2SW6VA.js';
 import { randomUUID } from 'crypto';
 import EventEmitter from 'events';
 import pMap from 'p-map';
@@ -22,7 +20,7 @@ var EventEmitterPubSub = class extends PubSub {
   }
   async publish(topic, event) {
     const id = crypto.randomUUID();
-    const createdAt = /* @__PURE__ */new Date();
+    const createdAt = /* @__PURE__ */ new Date();
     this.emitter.emit(topic, {
       ...event,
       id,
@@ -35,10 +33,11 @@ var EventEmitterPubSub = class extends PubSub {
   async unsubscribe(topic, cb) {
     this.emitter.off(topic, cb);
   }
-  async flush() {}
+  async flush() {
+  }
 };
 function createOnScorerHook(mastra) {
-  return async hookData => {
+  return async (hookData) => {
     const storage = mastra.getStorage();
     if (!storage) {
       mastra.getLogger()?.warn("Storage not found, skipping score validation and saving");
@@ -47,22 +46,24 @@ function createOnScorerHook(mastra) {
     const entityId = hookData.entity.id;
     const entityType = hookData.entityType;
     const scorer = hookData.scorer;
+    const scorerId = scorer.id;
+    if (!scorerId) {
+      mastra.getLogger()?.warn("Scorer ID not found, skipping score validation and saving");
+      return;
+    }
     try {
-      const scorerToUse = await findScorer(mastra, entityId, entityType, scorer.name);
+      const scorerToUse = await findScorer(mastra, entityId, entityType, scorerId);
       if (!scorerToUse) {
         throw new MastraError({
           id: "MASTRA_SCORER_NOT_FOUND",
           domain: "MASTRA" /* MASTRA */,
           category: "USER" /* USER */,
-          text: `Scorer with ID ${hookData.scorer.id} not found`
+          text: `Scorer with ID ${scorerId} not found`
         });
       }
       let input = hookData.input;
       let output = hookData.output;
-      const {
-        structuredOutput,
-        ...rest
-      } = hookData;
+      const { structuredOutput, ...rest } = hookData;
       const runResult = await scorerToUse.scorer.run({
         ...rest,
         input,
@@ -79,7 +80,7 @@ function createOnScorerHook(mastra) {
         ...rest,
         ...runResult,
         entityId,
-        scorerId: hookData.scorer.name,
+        scorerId,
         spanId,
         traceId,
         metadata: {
@@ -88,34 +89,43 @@ function createOnScorerHook(mastra) {
       };
       await validateAndSaveScore(storage, payload);
       if (currentSpan && spanId && traceId) {
-        await pMap(currentSpan.aiTracing.getExporters(), async exporter => {
-          if (exporter.addScoreToTrace) {
-            await exporter.addScoreToTrace({
-              traceId,
-              spanId,
-              score: runResult.score,
-              reason: runResult.reason,
-              scorerName: scorerToUse.scorer.name,
-              metadata: {
-                ...(currentSpan.metadata ?? {})
+        await pMap(
+          currentSpan.observabilityInstance.getExporters(),
+          async (exporter) => {
+            if (exporter.addScoreToTrace) {
+              try {
+                await exporter.addScoreToTrace({
+                  traceId,
+                  spanId,
+                  score: runResult.score,
+                  reason: runResult.reason,
+                  scorerName: scorerToUse.scorer.id,
+                  metadata: {
+                    ...currentSpan.metadata ?? {}
+                  }
+                });
+              } catch (error) {
+                mastra.getLogger()?.error(`Failed to add score to trace via exporter: ${error}`);
               }
-            });
-          }
-        }, {
-          concurrency: 3
-        });
+            }
+          },
+          { concurrency: 3 }
+        );
       }
     } catch (error) {
-      const mastraError = new MastraError({
-        id: "MASTRA_SCORER_FAILED_TO_RUN_HOOK",
-        domain: "SCORER" /* SCORER */,
-        category: "USER" /* USER */,
-        details: {
-          scorerId: scorer.id,
-          entityId,
-          entityType
-        }
-      }, error);
+      const mastraError = new MastraError(
+        {
+          id: "MASTRA_SCORER_FAILED_TO_RUN_HOOK",
+          domain: "SCORER" /* SCORER */,
+          category: "USER" /* USER */,
+          details: {
+            scorerId: scorer.id,
+            entityId,
+            entityType
+          }
+        },
+        error
+      );
       mastra.getLogger()?.trackException(mastraError);
       mastra.getLogger()?.error(mastraError.toString());
     }
@@ -125,56 +135,46 @@ async function validateAndSaveScore(storage, payload) {
   const payloadToSave = saveScorePayloadSchema.parse(payload);
   await storage?.saveScore(payloadToSave);
 }
-async function findScorer(mastra, entityId, entityType, scorerName) {
+async function findScorer(mastra, entityId, entityType, scorerId) {
   let scorerToUse;
   if (entityType === "AGENT") {
-    const scorers = await mastra.getAgentById(entityId).getScorers();
+    const scorers = await mastra.getAgentById(entityId).listScorers();
     for (const [_, scorer] of Object.entries(scorers)) {
-      if (scorer.scorer.name === scorerName) {
+      if (scorer.scorer.id === scorerId) {
         scorerToUse = scorer;
         break;
       }
     }
   } else if (entityType === "WORKFLOW") {
-    const scorers = await mastra.getWorkflowById(entityId).getScorers();
+    const scorers = await mastra.getWorkflowById(entityId).listScorers();
     for (const [_, scorer] of Object.entries(scorers)) {
-      if (scorer.scorer.name === scorerName) {
+      if (scorer.scorer.id === scorerId) {
         scorerToUse = scorer;
         break;
       }
     }
   }
   if (!scorerToUse) {
-    const mastraRegisteredScorer = mastra.getScorerByName(scorerName);
-    scorerToUse = mastraRegisteredScorer ? {
-      scorer: mastraRegisteredScorer
-    } : void 0;
+    const mastraRegisteredScorer = mastra.getScorerById(scorerId);
+    scorerToUse = mastraRegisteredScorer ? { scorer: mastraRegisteredScorer } : void 0;
   }
   return scorerToUse;
 }
 
 // src/mastra/index.ts
-var _Mastra_decorators, _init;
-_Mastra_decorators = [InstrumentClass({
-  prefix: "mastra",
-  excludeMethods: ["getLogger", "getTelemetry"]
-})];
 var Mastra = class {
   #vectors;
   #agents;
   #logger;
-  #legacy_workflows;
   #workflows;
+  #observability;
   #tts;
   #deployer;
   #serverMiddleware = [];
-  /**
-   * @deprecated Use {@link getAITracing()} instead.
-   */
-  #telemetry;
   #storage;
-  #memory;
   #scorers;
+  #tools;
+  #processors;
   #server;
   #mcpServers;
   #bundler;
@@ -184,24 +184,6 @@ var Mastra = class {
   #internalMastraWorkflows = {};
   // This is only used internally for server handlers that require temporary persistence
   #serverCache;
-  /**
-   * @deprecated use {@link getAITracing()} instead
-   */
-  get telemetry() {
-    return this.#telemetry;
-  }
-  /**
-   * @deprecated use getStorage() instead
-   */
-  get storage() {
-    return this.#storage;
-  }
-  /**
-   * @deprecated use getMemory() instead
-   */
-  get memory() {
-    return this.#memory;
-  }
   get pubsub() {
     return this.#pubsub;
   }
@@ -274,14 +256,15 @@ var Mastra = class {
    * 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'
    *     })
@@ -289,17 +272,12 @@ var Mastra = class {
    *   storage: new PostgresStore({
    *     connectionString: process.env.DATABASE_URL
    *   }),
-   *   logger: new PinoLogger({ name: 'MyApp' })
+   *   logger: new PinoLogger({ name: 'MyApp' }),
+   *   observability: { default: { enabled: true }},
    * });
    * ```
    */
   constructor(config) {
-    if (config?.serverMiddleware) {
-      this.#serverMiddleware = config.serverMiddleware.map(m => ({
-        handler: m.handler,
-        path: m.path || "/api/*"
-      }));
-    }
     this.#serverCache = new InMemoryServerCache();
     if (config?.pubsub) {
       this.#pubsub = config.pubsub;
@@ -314,9 +292,7 @@ var Mastra = class {
         this.#events[topic] = config?.events?.[topic] ?? [];
       }
     }
-    const workflowEventProcessor = new WorkflowEventProcessor({
-      mastra: this
-    });
+    const workflowEventProcessor = new WorkflowEventProcessor({ mastra: this });
     const workflowEventCb = async (event, cb) => {
       try {
         await workflowEventProcessor.process(event, cb);
@@ -337,10 +313,7 @@ var Mastra = class {
         logger = config.logger;
       } else {
         const levelOnEnv = process.env.NODE_ENV === "production" && process.env.MASTRA_DEV !== "true" ? LogLevel.WARN : LogLevel.INFO;
-        logger = new ConsoleLogger({
-          name: "Mastra",
-          level: levelOnEnv
-        });
+        logger = new ConsoleLogger({ name: "Mastra", level: levelOnEnv });
       }
     }
     this.#logger = logger;
@@ -349,202 +322,74 @@ var Mastra = class {
     if (storage) {
       storage = augmentWithInit(storage);
     }
-    this.#telemetry = Telemetry.init(config?.telemetry);
-    if (config?.telemetry?.enabled !== false && typeof globalThis !== "undefined" && globalThis.___MASTRA_TELEMETRY___ !== true) {
-      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?.telemetry?.enabled !== false) {
-      this.#logger?.warn(`Mastra telemetry is deprecated and will be removed on the Nov 4th release. Instead use AI Tracing. More info can be found here: https://github.com/mastra-ai/mastra/issues/8577 and here: https://mastra.ai/en/docs/observability/ai-tracing/overview`);
-    }
     if (config?.observability) {
-      setupAITracing(config.observability);
+      if (typeof config.observability.getDefaultInstance === "function") {
+        this.#observability = config.observability;
+        this.#observability.setLogger({ logger: this.#logger });
+      } else {
+        this.#logger?.warn(
+          'Observability configuration error: Expected an Observability instance, but received a config object. Import and instantiate: import { Observability } from "@mastra/observability"; then pass: observability: new Observability({ default: { enabled: true } }). Observability has been disabled.'
+        );
+        this.#observability = new NoOpObservability();
+      }
+    } else {
+      this.#observability = new NoOpObservability();
+    }
+    this.#storage = storage;
+    this.#vectors = {};
+    this.#mcpServers = {};
+    this.#tts = {};
+    this.#agents = {};
+    this.#scorers = {};
+    this.#tools = {};
+    this.#processors = {};
+    this.#workflows = {};
+    if (config?.tools) {
+      Object.entries(config.tools).forEach(([key, tool]) => {
+        this.addTool(tool, key);
+      });
     }
-    if (this.#telemetry && storage) {
-      this.#storage = this.#telemetry.traceClass(storage, {
-        excludeMethods: ["__setTelemetry", "__getTelemetry", "batchTraceInsert", "getTraces", "getEvalsByAgentName"]
+    if (config?.processors) {
+      Object.entries(config.processors).forEach(([key, processor]) => {
+        this.addProcessor(processor, key);
       });
-      this.#storage.__setTelemetry(this.#telemetry);
-    } else {
-      this.#storage = storage;
     }
     if (config?.vectors) {
-      let vectors = {};
       Object.entries(config.vectors).forEach(([key, vector]) => {
-        if (this.#telemetry) {
-          vectors[key] = this.#telemetry.traceClass(vector, {
-            excludeMethods: ["__setTelemetry", "__getTelemetry"]
-          });
-          vectors[key].__setTelemetry(this.#telemetry);
-        } else {
-          vectors[key] = vector;
-        }
+        this.addVector(vector, key);
       });
-      this.#vectors = vectors;
     }
-    if (config?.mcpServers) {
-      this.#mcpServers = config.mcpServers;
-      Object.entries(this.#mcpServers).forEach(([key, server]) => {
-        server.setId(key);
-        if (this.#telemetry) {
-          server.__setTelemetry(this.#telemetry);
-        }
-        server.__registerMastra(this);
-        server.__setLogger(this.getLogger());
+    if (config?.scorers) {
+      Object.entries(config.scorers).forEach(([key, scorer]) => {
+        this.addScorer(scorer, key);
       });
     }
-    if (config && `memory` in config) {
-      const error = new MastraError({
-        id: "MASTRA_CONSTRUCTOR_INVALID_MEMORY_CONFIG",
-        domain: "MASTRA" /* MASTRA */,
-        category: "USER" /* USER */,
-        text: `
-  Memory should be added to Agents, not to Mastra.
-
-Instead of:
-  new Mastra({ memory: new Memory() })
-
-do:
-  new Agent({ memory: new Memory() })
-`
+    if (config?.workflows) {
+      Object.entries(config.workflows).forEach(([key, workflow]) => {
+        this.addWorkflow(workflow, key);
       });
-      this.#logger?.trackException(error);
-      throw error;
     }
-    if (config?.tts) {
-      this.#tts = config.tts;
-      Object.entries(this.#tts).forEach(([key, ttsCl]) => {
-        if (this.#tts?.[key]) {
-          if (this.#telemetry) {
-            this.#tts[key] = this.#telemetry.traceClass(ttsCl, {
-              excludeMethods: ["__setTelemetry", "__getTelemetry"]
-            });
-            this.#tts[key].__setTelemetry(this.#telemetry);
-          }
-        }
+    if (config?.mcpServers) {
+      Object.entries(config.mcpServers).forEach(([key, server]) => {
+        this.addMCPServer(server, key);
       });
     }
-    const agents = {};
     if (config?.agents) {
       Object.entries(config.agents).forEach(([key, agent]) => {
-        if (agents[key]) {
-          const error = new MastraError({
-            id: "MASTRA_AGENT_REGISTRATION_DUPLICATE_ID",
-            domain: "MASTRA" /* MASTRA */,
-            category: "USER" /* USER */,
-            text: `Agent with name ID:${key} already exists`,
-            details: {
-              agentId: key
-            }
-          });
-          this.#logger?.trackException(error);
-          throw error;
-        }
-        agent.__registerMastra(this);
-        agent.__registerPrimitives({
-          logger: this.getLogger(),
-          telemetry: this.#telemetry,
-          storage: this.storage,
-          memory: this.memory,
-          agents,
-          tts: this.#tts,
-          vectors: this.#vectors
-        });
-        agents[key] = agent;
+        this.addAgent(agent, key);
       });
     }
-    this.#agents = agents;
-    const scorers = {};
-    if (config?.scorers) {
-      Object.entries(config.scorers).forEach(([key, scorer]) => {
-        scorers[key] = scorer;
-      });
-    }
-    this.#scorers = scorers;
-    this.#legacy_workflows = {};
-    if (config?.legacy_workflows) {
-      Object.entries(config.legacy_workflows).forEach(([key, workflow]) => {
-        workflow.__registerMastra(this);
-        workflow.__registerPrimitives({
-          logger: this.getLogger(),
-          telemetry: this.#telemetry,
-          storage: this.storage,
-          memory: this.memory,
-          agents,
-          tts: this.#tts,
-          vectors: this.#vectors
-        });
-        this.#legacy_workflows[key] = workflow;
-        const workflowSteps = Object.values(workflow.steps).filter(step => !!step.workflowId && !!step.workflow);
-        if (workflowSteps.length > 0) {
-          workflowSteps.forEach(step => {
-            this.#legacy_workflows[step.workflowId] = step.workflow;
-          });
-        }
-      });
-    }
-    this.#workflows = {};
-    if (config?.workflows) {
-      Object.entries(config.workflows).forEach(([key, workflow]) => {
-        workflow.__registerMastra(this);
-        workflow.__registerPrimitives({
-          logger: this.getLogger(),
-          telemetry: this.#telemetry,
-          storage: this.storage,
-          memory: this.memory,
-          agents,
-          tts: this.#tts,
-          vectors: this.#vectors
-        });
-        this.#workflows[key] = workflow;
+    if (config?.tts) {
+      Object.entries(config.tts).forEach(([key, tts]) => {
+        this.#tts[key] = tts;
       });
     }
     if (config?.server) {
       this.#server = config.server;
     }
     registerHook("onScorerRun" /* ON_SCORER_RUN */, createOnScorerHook(this));
-    if (config?.observability) {
-      this.registerAITracingExporters();
-      this.initAITracingExporters();
-    }
-    this.setLogger({
-      logger
-    });
-  }
-  /**
-   * Register this Mastra instance with AI tracing exporters that need it
-   */
-  registerAITracingExporters() {
-    const allTracingInstances = getAllAITracing();
-    allTracingInstances.forEach(tracing => {
-      const exporters = tracing.getExporters();
-      exporters.forEach(exporter => {
-        if ("__registerMastra" in exporter && typeof exporter.__registerMastra === "function") {
-          exporter.__registerMastra(this);
-        }
-      });
-    });
-  }
-  /**
-   * Initialize all AI tracing exporters after registration is complete
-   */
-  initAITracingExporters() {
-    const allTracingInstances = getAllAITracing();
-    allTracingInstances.forEach(tracing => {
-      const config = tracing.getConfig();
-      const exporters = tracing.getExporters();
-      exporters.forEach(exporter => {
-        if ("init" in exporter && typeof exporter.init === "function") {
-          try {
-            exporter.init(config);
-          } catch (error) {
-            this.#logger?.warn("Failed to initialize AI tracing exporter", {
-              exporterName: exporter.name,
-              error: error instanceof Error ? error.message : String(error)
-            });
-          }
-        }
-      });
-    });
+    this.#observability.setMastraContext({ mastra: this });
+    this.setLogger({ logger });
   }
   /**
    * Retrieves a registered agent by its name.
@@ -557,6 +402,7 @@ do:
    * const mastra = new Mastra({
    *   agents: {
    *     weatherAgent: new Agent({
+   *       id: 'weather-agent',
    *       name: 'weather-agent',
    *       instructions: 'You provide weather information',
    *       model: 'openai/gpt-5'
@@ -591,7 +437,7 @@ do:
    *
    * 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
    *
@@ -600,6 +446,7 @@ do:
    * const mastra = new Mastra({
    *   agents: {
    *     assistant: new Agent({
+   *       id: 'assistant',
    *       name: 'assistant',
    *       instructions: 'You are a helpful assistant',
    *       model: 'openai/gpt-5'
@@ -612,11 +459,12 @@ do:
    * ```
    */
   getAgentById(id) {
-    let agent = Object.values(this.#agents).find(a => a.id === id);
+    let agent = Object.values(this.#agents).find((a) => a.id === id);
     if (!agent) {
       try {
         agent = this.getAgent(id);
-      } catch {}
+      } catch {
+      }
     }
     if (!agent) {
       const error = new MastraError({
@@ -645,18 +493,58 @@ do:
    * ```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() {
+  listAgents() {
     return this.#agents;
   }
+  /**
+   * 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(agent, key) {
+    const agentKey = key || agent.id;
+    const agents = this.#agents;
+    if (agents[agentKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Agent with key ${agentKey} already exists. Skipping addition.`);
+      return;
+    }
+    agent.__setLogger(this.#logger);
+    agent.__registerMastra(this);
+    agent.__registerPrimitives({
+      logger: this.getLogger(),
+      storage: this.getStorage(),
+      agents,
+      tts: this.#tts,
+      vectors: this.#vectors
+    });
+    agents[agentKey] = agent;
+  }
   /**
    * Retrieves a registered vector store by its name.
    *
@@ -714,6 +602,50 @@ do:
     }
     return vector;
   }
+  /**
+   * 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) {
+    const allVectors = this.#vectors ?? {};
+    for (const vector of Object.values(allVectors)) {
+      if (vector.id === id) {
+        return vector;
+      }
+    }
+    const vectorByKey = allVectors[id];
+    if (vectorByKey) {
+      return vectorByKey;
+    }
+    const error = new MastraError({
+      id: "MASTRA_GET_VECTOR_BY_ID_NOT_FOUND",
+      domain: "MASTRA" /* MASTRA */,
+      category: "USER" /* USER */,
+      text: `Vector store with id ${id} not found`,
+      details: {
+        status: 404,
+        vectorId: String(id),
+        vectors: Object.keys(allVectors).join(", ")
+      }
+    });
+    this.#logger?.trackException(error);
+    throw error;
+  }
   /**
    * Returns all registered vector stores as a record keyed by their names.
    *
@@ -736,9 +668,44 @@ do:
    * }
    * ```
    */
-  getVectors() {
+  listVectors() {
     return this.#vectors;
   }
+  /**
+   * 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(vector, key) {
+    const vectorKey = key || vector.id;
+    const vectors = this.#vectors;
+    if (vectors[vectorKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Vector with key ${vectorKey} already exists. Skipping addition.`);
+      return;
+    }
+    vector.__setLogger(this.#logger || this.getLogger());
+    vectors[vectorKey] = vector;
+  }
+  /**
+   * @deprecated Use listVectors() instead
+   */
+  getVectors() {
+    console.warn("getVectors() is deprecated. Use listVectors() instead.");
+    return this.listVectors();
+  }
   /**
    * Gets the currently configured deployment provider.
    *
@@ -763,55 +730,6 @@ do:
   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
-  } = {}) {
-    const workflow = this.#legacy_workflows?.[id];
-    if (!workflow) {
-      const error = new MastraError({
-        id: "MASTRA_GET_LEGACY_WORKFLOW_BY_ID_NOT_FOUND",
-        domain: "MASTRA" /* MASTRA */,
-        category: "USER" /* USER */,
-        text: `Workflow with ID ${String(id)} not found`,
-        details: {
-          status: 404,
-          workflowId: String(id),
-          workflows: Object.keys(this.#legacy_workflows ?? {}).join(", ")
-        }
-      });
-      this.#logger?.trackException(error);
-      throw error;
-    }
-    if (serialized) {
-      return {
-        name: workflow.name
-      };
-    }
-    return workflow;
-  }
   /**
    * Retrieves a registered workflow by its ID.
    *
@@ -839,9 +757,7 @@ do:
    * });
    * ```
    */
-  getWorkflow(id, {
-    serialized
-  } = {}) {
+  getWorkflow(id, { serialized } = {}) {
     const workflow = this.#workflows?.[id];
     if (!workflow) {
       const error = new MastraError({
@@ -859,25 +775,22 @@ do:
       throw error;
     }
     if (serialized) {
-      return {
-        name: workflow.name
-      };
+      return { name: workflow.name };
     }
     return workflow;
   }
   __registerInternalWorkflow(workflow) {
     workflow.__registerMastra(this);
     workflow.__registerPrimitives({
-      logger: this.getLogger(),
-      storage: this.storage
+      logger: this.getLogger()
     });
     this.#internalMastraWorkflows[workflow.id] = workflow;
   }
   __hasInternalWorkflow(id) {
-    return Object.values(this.#internalMastraWorkflows).some(workflow => workflow.id === id);
+    return Object.values(this.#internalMastraWorkflows).some((workflow) => workflow.id === id);
   }
   __getInternalWorkflow(id) {
-    const workflow = Object.values(this.#internalMastraWorkflows).find(a => a.id === id);
+    const workflow = Object.values(this.#internalMastraWorkflows).find((a) => a.id === id);
     if (!workflow) {
       throw new MastraError({
         id: "MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND",
@@ -897,7 +810,7 @@ do:
    *
    * 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
    *
@@ -922,11 +835,12 @@ do:
    * ```
    */
   getWorkflowById(id) {
-    let workflow = Object.values(this.#workflows).find(a => a.id === id);
+    let workflow = Object.values(this.#workflows).find((a) => a.id === id);
     if (!workflow) {
       try {
         workflow = this.getWorkflow(id);
-      } catch {}
+      } catch {
+      }
     }
     if (!workflow) {
       const error = new MastraError({
@@ -945,45 +859,6 @@ 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]) => {
-        return {
-          ...acc,
-          [k]: {
-            name: v.name
-          }
-        };
-      }, {});
-    }
-    return this.#legacy_workflows;
-  }
   /**
    * Returns all registered scorers as a record keyed by their IDs.
    *
@@ -999,18 +874,48 @@ do:
    *   }
    * });
    *
-   * 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() {
+  listScorers() {
     return this.#scorers;
   }
+  /**
+   * 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(scorer, key) {
+    const scorerKey = key || scorer.id;
+    const scorers = this.#scorers;
+    if (scorers[scorerKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Scorer with key ${scorerKey} already exists. Skipping addition.`);
+      return;
+    }
+    scorers[scorerKey] = scorer;
+  }
   /**
    * Retrieves a registered scorer by its key.
    *
@@ -1024,7 +929,7 @@ do:
    * 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({
@@ -1081,28 +986,298 @@ do:
    * });
    *
    * // 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) {
+  getScorerById(id) {
     for (const [_key, value] of Object.entries(this.#scorers ?? {})) {
-      if (value.name === name) {
+      if (value.id === id || value?.name === id) {
         return value;
       }
     }
     const error = new MastraError({
-      id: "MASTRA_GET_SCORER_BY_NAME_NOT_FOUND",
+      id: "MASTRA_GET_SCORER_BY_ID_NOT_FOUND",
       domain: "MASTRA" /* MASTRA */,
       category: "USER" /* USER */,
-      text: `Scorer with name ${String(name)} not found`
+      text: `Scorer with id ${String(id)} not found`
     });
     this.#logger?.trackException(error);
     throw error;
   }
+  /**
+   * 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(name) {
+    if (!this.#tools || !this.#tools[name]) {
+      const error = new MastraError({
+        id: "MASTRA_GET_TOOL_BY_NAME_NOT_FOUND",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Tool with name ${String(name)} not found`,
+        details: {
+          status: 404,
+          toolName: String(name),
+          tools: Object.keys(this.#tools ?? {}).join(", ")
+        }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    return this.#tools[name];
+  }
+  /**
+   * 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) {
+    const allTools = this.#tools;
+    if (!allTools) {
+      throw new MastraError({
+        id: "MASTRA_GET_TOOL_BY_ID_NOT_FOUND",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Tool with id ${id} not found`
+      });
+    }
+    for (const tool of Object.values(allTools)) {
+      if (tool.id === id) {
+        return tool;
+      }
+    }
+    const toolByKey = allTools[id];
+    if (toolByKey) {
+      return toolByKey;
+    }
+    const error = new MastraError({
+      id: "MASTRA_GET_TOOL_BY_ID_NOT_FOUND",
+      domain: "MASTRA" /* MASTRA */,
+      category: "USER" /* USER */,
+      text: `Tool with id ${id} not found`,
+      details: {
+        status: 404,
+        toolId: String(id),
+        tools: Object.keys(allTools).join(", ")
+      }
+    });
+    this.#logger?.trackException(error);
+    throw error;
+  }
+  /**
+   * 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() {
+    return this.#tools;
+  }
+  /**
+   * 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(tool, key) {
+    const toolKey = key || tool.id;
+    const tools = this.#tools;
+    if (tools[toolKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Tool with key ${toolKey} already exists. Skipping addition.`);
+      return;
+    }
+    tools[toolKey] = tool;
+  }
+  /**
+   * 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(name) {
+    if (!this.#processors || !this.#processors[name]) {
+      const error = new MastraError({
+        id: "MASTRA_GET_PROCESSOR_BY_NAME_NOT_FOUND",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Processor with name ${String(name)} not found`,
+        details: {
+          status: 404,
+          processorName: String(name),
+          processors: Object.keys(this.#processors ?? {}).join(", ")
+        }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    return this.#processors[name];
+  }
+  /**
+   * 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) {
+    const allProcessors = this.#processors;
+    if (!allProcessors) {
+      throw new MastraError({
+        id: "MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Processor with id ${id} not found`
+      });
+    }
+    for (const processor of Object.values(allProcessors)) {
+      if (processor.id === id) {
+        return processor;
+      }
+    }
+    const processorByKey = allProcessors[id];
+    if (processorByKey) {
+      return processorByKey;
+    }
+    const error = new MastraError({
+      id: "MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND",
+      domain: "MASTRA" /* MASTRA */,
+      category: "USER" /* USER */,
+      text: `Processor with id ${id} not found`,
+      details: {
+        status: 404,
+        processorId: String(id),
+        processors: Object.keys(allProcessors).join(", ")
+      }
+    });
+    this.#logger?.trackException(error);
+    throw error;
+  }
+  /**
+   * 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() {
+    return this.#processors;
+  }
+  /**
+   * 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(processor, key) {
+    const processorKey = key || processor.id;
+    const processors = this.#processors;
+    if (processors[processorKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Processor with key ${processorKey} already exists. Skipping addition.`);
+      return;
+    }
+    processors[processorKey] = processor;
+  }
   /**
    * Returns all registered workflows as a record keyed by their IDs.
    *
@@ -1116,7 +1291,7 @@ do:
    *   }
    * });
    *
-   * const allWorkflows = mastra.getWorkflows();
+   * const allWorkflows = mastra.listWorkflows();
    * console.log(Object.keys(allWorkflows)); // ['dataProcessor', 'emailSender', 'reportGenerator']
    *
    * // Execute all workflows with sample data
@@ -1126,19 +1301,52 @@ do:
    * }
    * ```
    */
-  getWorkflows(props = {}) {
+  listWorkflows(props = {}) {
     if (props.serialized) {
       return Object.entries(this.#workflows).reduce((acc, [k, v]) => {
         return {
           ...acc,
-          [k]: {
-            name: v.name
-          }
+          [k]: { name: v.name }
         };
       }, {});
     }
     return this.#workflows;
   }
+  /**
+   * 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(workflow, key) {
+    const workflowKey = key || workflow.id;
+    const workflows = this.#workflows;
+    if (workflows[workflowKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Workflow with key ${workflowKey} already exists. Skipping addition.`);
+      return;
+    }
+    workflow.__registerMastra(this);
+    workflow.__registerPrimitives({
+      logger: this.getLogger(),
+      storage: this.getStorage()
+    });
+    workflows[workflowKey] = workflow;
+  }
   /**
    * Sets the storage provider for the Mastra instance.
    *
@@ -1153,6 +1361,7 @@ do:
    *
    * // Now agents can use memory with the storage
    * const agent = new Agent({
+   *   id: 'assistant',
    *   name: 'assistant',
    *   memory: new Memory({ storage: mastra.getStorage() })
    * });
@@ -1161,23 +1370,18 @@ do:
   setStorage(storage) {
     this.#storage = augmentWithInit(storage);
   }
-  setLogger({
-    logger
-  }) {
+  setLogger({ logger }) {
     this.#logger = logger;
     if (this.#agents) {
-      Object.keys(this.#agents).forEach(key => {
+      Object.keys(this.#agents).forEach((key) => {
         this.#agents?.[key]?.__setLogger(this.#logger);
       });
     }
-    if (this.#memory) {
-      this.#memory.__setLogger(this.#logger);
-    }
     if (this.#deployer) {
       this.#deployer.__setLogger(this.#logger);
     }
     if (this.#tts) {
-      Object.keys(this.#tts).forEach(key => {
+      Object.keys(this.#tts).forEach((key) => {
         this.#tts?.[key]?.__setLogger(this.#logger);
       });
     }
@@ -1185,71 +1389,16 @@ do:
       this.#storage.__setLogger(this.#logger);
     }
     if (this.#vectors) {
-      Object.keys(this.#vectors).forEach(key => {
+      Object.keys(this.#vectors).forEach((key) => {
         this.#vectors?.[key]?.__setLogger(this.#logger);
       });
     }
     if (this.#mcpServers) {
-      Object.keys(this.#mcpServers).forEach(key => {
+      Object.keys(this.#mcpServers).forEach((key) => {
         this.#mcpServers?.[key]?.__setLogger(this.#logger);
       });
     }
-    const allTracingInstances = getAllAITracing();
-    allTracingInstances.forEach(instance => {
-      instance.__setLogger(this.#logger);
-    });
-  }
-  setTelemetry(telemetry) {
-    this.#telemetry = Telemetry.init(telemetry);
-    if (this.#agents) {
-      Object.keys(this.#agents).forEach(key => {
-        if (this.#telemetry) {
-          this.#agents?.[key]?.__setTelemetry(this.#telemetry);
-        }
-      });
-    }
-    if (this.#memory) {
-      this.#memory = this.#telemetry.traceClass(this.#memory, {
-        excludeMethods: ["__setTelemetry", "__getTelemetry"]
-      });
-      this.#memory.__setTelemetry(this.#telemetry);
-    }
-    if (this.#deployer) {
-      this.#deployer = this.#telemetry.traceClass(this.#deployer, {
-        excludeMethods: ["__setTelemetry", "__getTelemetry"]
-      });
-      this.#deployer.__setTelemetry(this.#telemetry);
-    }
-    if (this.#tts) {
-      let tts = {};
-      Object.entries(this.#tts).forEach(([key, ttsCl]) => {
-        if (this.#telemetry) {
-          tts[key] = this.#telemetry.traceClass(ttsCl, {
-            excludeMethods: ["__setTelemetry", "__getTelemetry"]
-          });
-          tts[key].__setTelemetry(this.#telemetry);
-        }
-      });
-      this.#tts = tts;
-    }
-    if (this.#storage) {
-      this.#storage = this.#telemetry.traceClass(this.#storage, {
-        excludeMethods: ["__setTelemetry", "__getTelemetry"]
-      });
-      this.#storage.__setTelemetry(this.#telemetry);
-    }
-    if (this.#vectors) {
-      let vectors = {};
-      Object.entries(this.#vectors).forEach(([key, vector]) => {
-        if (this.#telemetry) {
-          vectors[key] = this.#telemetry.traceClass(vector, {
-            excludeMethods: ["__setTelemetry", "__getTelemetry"]
-          });
-          vectors[key].__setTelemetry(this.#telemetry);
-        }
-      });
-      this.#vectors = vectors;
-    }
+    this.#observability.setLogger({ logger: this.#logger });
   }
   /**
    * Gets all registered text-to-speech (TTS) providers.
@@ -1295,67 +1444,18 @@ do:
   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();
-   * }
-   * ```
-   *
-   * @deprecated use {@link getAITracing()} instead
-   */
-  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' })
+   *   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()
@@ -1366,6 +1466,9 @@ do:
   getStorage() {
     return this.#storage;
   }
+  get observability() {
+    return this.#observability;
+  }
   getServerMiddleware() {
     return this.#serverMiddleware;
   }
@@ -1374,10 +1477,12 @@ do:
   }
   setServerMiddleware(serverMiddleware) {
     if (typeof serverMiddleware === "function") {
-      this.#serverMiddleware = [{
-        handler: serverMiddleware,
-        path: "/api/*"
-      }];
+      this.#serverMiddleware = [
+        {
+          handler: serverMiddleware,
+          path: "/api/*"
+        }
+      ];
       return;
     }
     if (!Array.isArray(serverMiddleware)) {
@@ -1390,7 +1495,7 @@ do:
       this.#logger?.trackException(error);
       throw error;
     }
-    this.#serverMiddleware = serverMiddleware.map(m => {
+    this.#serverMiddleware = serverMiddleware.map((m) => {
       if (typeof m === "function") {
         return {
           handler: m,
@@ -1409,7 +1514,7 @@ do:
   getBundlerConfig() {
     return this.#bundler;
   }
-  async getLogsByRunId({
+  async listLogsByRunId({
     runId,
     transportId,
     fromDate,
@@ -1421,7 +1526,7 @@ do:
   }) {
     if (!transportId) {
       const error = new MastraError({
-        id: "MASTRA_GET_LOGS_BY_RUN_ID_MISSING_TRANSPORT",
+        id: "MASTRA_LIST_LOGS_BY_RUN_ID_MISSING_TRANSPORT",
         domain: "MASTRA" /* MASTRA */,
         category: "USER" /* USER */,
         text: "Transport ID is required",
@@ -1433,12 +1538,12 @@ do:
       this.#logger?.trackException(error);
       throw error;
     }
-    if (!this.#logger?.getLogsByRunId) {
+    if (!this.#logger?.listLogsByRunId) {
       const error = new MastraError({
         id: "MASTRA_GET_LOGS_BY_RUN_ID_LOGGER_NOT_CONFIGURED",
         domain: "MASTRA" /* MASTRA */,
         category: "SYSTEM" /* SYSTEM */,
-        text: "Logger is not configured or does not support getLogsByRunId operation",
+        text: "Logger is not configured or does not support listLogsByRunId operation",
         details: {
           runId,
           transportId
@@ -1447,7 +1552,7 @@ do:
       this.#logger?.trackException(error);
       throw error;
     }
-    return await this.#logger.getLogsByRunId({
+    return await this.#logger.listLogsByRunId({
       runId,
       transportId,
       fromDate,
@@ -1458,7 +1563,7 @@ do:
       perPage
     });
   }
-  async getLogs(transportId, params) {
+  async listLogs(transportId, params) {
     if (!transportId) {
       const error = new MastraError({
         id: "MASTRA_GET_LOGS_MISSING_TRANSPORT",
@@ -1484,7 +1589,7 @@ do:
       });
       throw error;
     }
-    return await this.#logger.getLogs(transportId, params);
+    return await this.#logger.listLogs(transportId, params);
   }
   /**
    * Gets all registered Model Context Protocol (MCP) server instances.
@@ -1502,13 +1607,83 @@ do:
    * const mcpServers = mastra.getMCPServers();
    * if (mcpServers) {
    *   const fsServer = mcpServers.filesystem;
-   *   const tools = await fsServer.getTools();
+   *   const tools = await fsServer.listTools();
    * }
    * ```
    */
-  getMCPServers() {
+  listMCPServers() {
     return this.#mcpServers;
   }
+  /**
+   * 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(server, key) {
+    if (key) {
+      server.setId(key);
+    }
+    const resolvedId = server.id;
+    if (!resolvedId) {
+      const error = new MastraError({
+        id: "MASTRA_ADD_MCP_SERVER_MISSING_ID",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: "MCP server must expose an id or be registered under one",
+        details: { status: 400 }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    const serverKey = key ?? resolvedId;
+    const servers = this.#mcpServers;
+    if (servers[serverKey]) {
+      const logger = this.getLogger();
+      logger.debug(`MCP server with key ${serverKey} already exists. Skipping addition.`);
+      return;
+    }
+    server.__registerMastra(this);
+    server.__setLogger(this.getLogger());
+    servers[serverKey] = server;
+  }
+  /**
+   * 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(name) {
+    if (!this.#mcpServers || !this.#mcpServers[name]) {
+      this.#logger?.debug(`MCP server with name ${String(name)} not found`);
+      return void 0;
+    }
+    return this.#mcpServers[name];
+  }
   /**
    * Retrieves a specific Model Context Protocol (MCP) server instance by its logical ID.
    *
@@ -1528,24 +1703,24 @@ do:
    *   }
    * });
    *
-   * 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, version) {
+  getMCPServerById(serverId, version) {
     if (!this.#mcpServers) {
       return void 0;
     }
     const allRegisteredServers = Object.values(this.#mcpServers || {});
-    const matchingLogicalIdServers = allRegisteredServers.filter(server => server.id === serverId);
+    const matchingLogicalIdServers = allRegisteredServers.filter((server) => server.id === serverId);
     if (matchingLogicalIdServers.length === 0) {
       this.#logger?.debug(`No MCP servers found with logical ID: ${serverId}`);
       return void 0;
     }
     if (version) {
-      const specificVersionServer = matchingLogicalIdServers.find(server => server.version === version);
+      const specificVersionServer = matchingLogicalIdServers.find((server) => server.version === version);
       if (!specificVersionServer) {
         this.#logger?.debug(`MCP server with logical ID '${serverId}' found, but not version '${version}'.`);
       }
@@ -1568,7 +1743,9 @@ do:
           return latestServer;
         }
       }
-      this.#logger?.warn(`Could not determine the latest server for logical ID '${serverId}' due to invalid or missing release dates, or no servers left after filtering.`);
+      this.#logger?.warn(
+        `Could not determine the latest server for logical ID '${serverId}' due to invalid or missing release dates, or no servers left after filtering.`
+      );
       return void 0;
     }
   }
@@ -1605,7 +1782,7 @@ do:
    * 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
    *
@@ -1627,8 +1804,8 @@ do:
    * ```
    */
   async shutdown() {
-    await shutdownAITracingRegistry();
     await this.stopEventEngine();
+    await this.#observability.shutdown();
     this.#logger?.info("Mastra shutdown completed");
   }
   // This method is only used internally for server hnadlers that require temporary persistence
@@ -1636,13 +1813,7 @@ do:
     return this.#serverCache;
   }
 };
-Mastra = /*@__PURE__*/(_ => {
-  _init = __decoratorStart(null);
-  Mastra = __decorateElement(_init, 0, "Mastra", _Mastra_decorators, Mastra);
-  __runInitializers(_init, 1, Mastra);
-  return Mastra;
-})();
 
 export { Mastra };
-//# sourceMappingURL=chunk-BWGXM3D4.js.map
-//# sourceMappingURL=chunk-BWGXM3D4.js.map
+//# sourceMappingURL=chunk-7SKXKUYT.js.map
+//# sourceMappingURL=chunk-7SKXKUYT.js.map