@mastra/core 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/{chunk-VOQ3ULMT.js → chunk-U3XOLEPX.js}

@@ -1,13 +1,13 @@
-import { WorkflowEventProcessor } from './chunk-H6CZGPZD.js';
-import { augmentWithInit } from './chunk-436FFEF6.js';
-import { saveScorePayloadSchema } from './chunk-76K3IYWM.js';
+import { WorkflowEventProcessor } from './chunk-US2U7ECW.js';
+import { saveScorePayloadSchema } from './chunk-ADADLFDR.js';
 import { PubSub } from './chunk-BVUMKER5.js';
-import { noopLogger } from './chunk-X7JMA3IY.js';
+import { augmentWithInit, Agent } from './chunk-2ULLRN4Y.js';
+import { noopLogger } from './chunk-PSCMWPLC.js';
 import { registerHook } from './chunk-L54GIUCB.js';
-import { NoOpObservability } from './chunk-KIZIOFZC.js';
+import { NoOpObservability } from './chunk-Y36Y5MTD.js';
 import { MastraError } from './chunk-JJ5O45LH.js';
-import { InMemoryServerCache } from './chunk-OJNJA5ZI.js';
-import { ConsoleLogger, LogLevel } from './chunk-KJ2SW6VA.js';
+import { InMemoryServerCache } from './chunk-3CKZSDTQ.js';
+import { ConsoleLogger, LogLevel } from './chunk-NRUZYMHE.js';
 import { randomUUID } from 'crypto';
 import EventEmitter from 'events';
 import pMap from 'p-map';
@@ -162,6 +162,17 @@ async function findScorer(mastra, entityId, entityType, scorerId) {
 }
 
 // src/mastra/index.ts
+function createUndefinedPrimitiveError(type, value, key) {
+  const typeLabel = type === "mcp-server" ? "MCP server" : type;
+  const errorId = `MASTRA_ADD_${type.toUpperCase().replace("-", "_")}_UNDEFINED`;
+  return new MastraError({
+    id: errorId,
+    domain: "MASTRA" /* MASTRA */,
+    category: "USER" /* USER */,
+    text: `Cannot add ${typeLabel}: ${typeLabel} is ${value === null ? "null" : "undefined"}. This may occur if config was spread ({ ...config }) and the original object had getters or non-enumerable properties.`,
+    details: { status: 400, ...key && { key } }
+  });
+}
 var Mastra = class {
   #vectors;
   #agents;
@@ -175,11 +186,14 @@ var Mastra = class {
   #scorers;
   #tools;
   #processors;
+  #memory;
   #server;
+  #serverAdapter;
   #mcpServers;
   #bundler;
   #idGenerator;
   #pubsub;
+  #gateways;
   #events = {};
   #internalMastraWorkflows = {};
   // This is only used internally for server handlers that require temporary persistence
@@ -343,45 +357,77 @@ var Mastra = class {
     this.#scorers = {};
     this.#tools = {};
     this.#processors = {};
+    this.#memory = {};
     this.#workflows = {};
+    this.#gateways = {};
     if (config?.tools) {
       Object.entries(config.tools).forEach(([key, tool]) => {
-        this.addTool(tool, key);
+        if (tool != null) {
+          this.addTool(tool, key);
+        }
       });
     }
     if (config?.processors) {
       Object.entries(config.processors).forEach(([key, processor]) => {
-        this.addProcessor(processor, key);
+        if (processor != null) {
+          this.addProcessor(processor, key);
+        }
+      });
+    }
+    if (config?.memory) {
+      Object.entries(config.memory).forEach(([key, memory]) => {
+        if (memory != null) {
+          this.addMemory(memory, key);
+        }
       });
     }
     if (config?.vectors) {
       Object.entries(config.vectors).forEach(([key, vector]) => {
-        this.addVector(vector, key);
+        if (vector != null) {
+          this.addVector(vector, key);
+        }
       });
     }
     if (config?.scorers) {
       Object.entries(config.scorers).forEach(([key, scorer]) => {
-        this.addScorer(scorer, key);
+        if (scorer != null) {
+          this.addScorer(scorer, key);
+        }
       });
     }
     if (config?.workflows) {
       Object.entries(config.workflows).forEach(([key, workflow]) => {
-        this.addWorkflow(workflow, key);
+        if (workflow != null) {
+          this.addWorkflow(workflow, key);
+        }
+      });
+    }
+    if (config?.gateways) {
+      Object.entries(config.gateways).forEach(([key, gateway]) => {
+        if (gateway != null) {
+          this.addGateway(gateway, key);
+        }
       });
     }
     if (config?.mcpServers) {
       Object.entries(config.mcpServers).forEach(([key, server]) => {
-        this.addMCPServer(server, key);
+        if (server != null) {
+          this.addMCPServer(server, key);
+        }
       });
     }
     if (config?.agents) {
       Object.entries(config.agents).forEach(([key, agent]) => {
-        this.addAgent(agent, key);
+        if (agent != null) {
+          this.addAgent(agent, key);
+        }
       });
     }
     if (config?.tts) {
       Object.entries(config.tts).forEach(([key, tts]) => {
-        this.#tts[key] = tts;
+        if (tts != null) {
+          this.#tts[key] = tts;
+        }
       });
     }
     if (config?.server) {
@@ -505,6 +551,241 @@ var Mastra = class {
   listAgents() {
     return this.#agents;
   }
+  async getStoredAgentById(id, options) {
+    const storage = this.#storage;
+    if (!storage) {
+      const error = new MastraError({
+        id: "MASTRA_GET_STORED_AGENT_STORAGE_NOT_CONFIGURED",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: "Storage is not configured",
+        details: { status: 400 }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    if (!storage.supports.agents) {
+      const error = new MastraError({
+        id: "MASTRA_GET_STORED_AGENT_NOT_SUPPORTED",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: "Storage does not support agents",
+        details: { status: 400 }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    const storedAgent = await storage.getAgentById({ id });
+    if (!storedAgent) {
+      return null;
+    }
+    if (options?.raw) {
+      return storedAgent;
+    }
+    return this.#createAgentFromStoredConfig(storedAgent);
+  }
+  async listStoredAgents(args) {
+    const storage = this.#storage;
+    if (!storage) {
+      const error = new MastraError({
+        id: "MASTRA_LIST_STORED_AGENTS_STORAGE_NOT_CONFIGURED",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: "Storage is not configured",
+        details: { status: 400 }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    if (!storage.supports.agents) {
+      const error = new MastraError({
+        id: "MASTRA_LIST_STORED_AGENTS_NOT_SUPPORTED",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: "Storage does not support agents",
+        details: { status: 400 }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    const result = await storage.listAgents({
+      page: args?.page,
+      perPage: args?.perPage,
+      orderBy: args?.orderBy
+    });
+    if (args?.raw) {
+      return result;
+    }
+    const agents = result.agents.map((storedAgent) => this.#createAgentFromStoredConfig(storedAgent));
+    return {
+      agents,
+      total: result.total,
+      page: result.page,
+      perPage: result.perPage,
+      hasMore: result.hasMore
+    };
+  }
+  /**
+   * Creates an Agent instance from a stored agent configuration.
+   * @private
+   */
+  #createAgentFromStoredConfig(storedAgent) {
+    const modelConfig = storedAgent.model;
+    if (!modelConfig.provider || !modelConfig.name) {
+      throw new MastraError({
+        id: "MASTRA_STORED_AGENT_INVALID_MODEL",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Stored agent "${storedAgent.id}" has invalid model configuration. Both provider and name are required.`,
+        details: { agentId: storedAgent.id, model: JSON.stringify(storedAgent.model) }
+      });
+    }
+    const model = `${modelConfig.provider}/${modelConfig.name}`;
+    const tools = this.#resolveStoredTools(storedAgent.tools);
+    const workflows = this.#resolveStoredWorkflows(storedAgent.workflows);
+    const agents = this.#resolveStoredAgents(storedAgent.agents);
+    const memory = this.#resolveStoredMemory(storedAgent.memory);
+    const scorers = this.#resolveStoredScorers(storedAgent.scorers);
+    const agent = new Agent({
+      id: storedAgent.id,
+      name: storedAgent.name,
+      description: storedAgent.description,
+      instructions: storedAgent.instructions,
+      model,
+      tools,
+      workflows,
+      agents,
+      memory,
+      scorers,
+      defaultOptions: storedAgent.defaultOptions
+    });
+    agent.__setLogger(this.#logger);
+    agent.__registerMastra(this);
+    agent.__registerPrimitives({
+      logger: this.getLogger(),
+      storage: this.getStorage(),
+      agents: this.#agents,
+      tts: this.#tts,
+      vectors: this.#vectors
+    });
+    return agent;
+  }
+  /**
+   * Resolves tool references from stored configuration to actual tool instances.
+   * @private
+   */
+  #resolveStoredTools(storedTools) {
+    if (!storedTools || storedTools.length === 0) {
+      return {};
+    }
+    const resolvedTools = {};
+    const registeredTools = this.#tools;
+    for (const toolKey of storedTools) {
+      if (registeredTools && registeredTools[toolKey]) {
+        resolvedTools[toolKey] = registeredTools[toolKey];
+      } else {
+        this.#logger?.warn(`Tool "${toolKey}" referenced in stored agent but not registered in Mastra`);
+      }
+    }
+    return resolvedTools;
+  }
+  /**
+   * Resolves workflow references from stored configuration to actual workflow instances.
+   * @private
+   */
+  #resolveStoredWorkflows(storedWorkflows) {
+    if (!storedWorkflows || storedWorkflows.length === 0) {
+      return {};
+    }
+    const resolvedWorkflows = {};
+    for (const workflowKey of storedWorkflows) {
+      try {
+        const workflow = this.getWorkflow(workflowKey);
+        resolvedWorkflows[workflowKey] = workflow;
+      } catch {
+        try {
+          const workflow = this.getWorkflowById(workflowKey);
+          resolvedWorkflows[workflowKey] = workflow;
+        } catch {
+          this.#logger?.warn(`Workflow "${workflowKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return resolvedWorkflows;
+  }
+  /**
+   * Resolves agent references from stored configuration to actual agent instances.
+   * @private
+   */
+  #resolveStoredAgents(storedAgents) {
+    if (!storedAgents || storedAgents.length === 0) {
+      return {};
+    }
+    const resolvedAgents = {};
+    for (const agentKey of storedAgents) {
+      try {
+        const agent = this.getAgent(agentKey);
+        resolvedAgents[agentKey] = agent;
+      } catch {
+        try {
+          const agent = this.getAgentById(agentKey);
+          resolvedAgents[agentKey] = agent;
+        } catch {
+          this.#logger?.warn(`Agent "${agentKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return resolvedAgents;
+  }
+  /**
+   * Resolves memory reference from stored configuration to actual memory instance.
+   * @private
+   */
+  #resolveStoredMemory(storedMemory) {
+    if (!storedMemory) {
+      return void 0;
+    }
+    try {
+      return this.getMemory(storedMemory);
+    } catch {
+      try {
+        return this.getMemoryById(storedMemory);
+      } catch {
+        this.#logger?.warn(`Memory "${storedMemory}" referenced in stored agent but not registered in Mastra`);
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Resolves scorer references from stored configuration to actual scorer instances.
+   * @private
+   */
+  #resolveStoredScorers(storedScorers) {
+    if (!storedScorers) {
+      return void 0;
+    }
+    const resolvedScorers = {};
+    for (const [scorerKey, scorerConfig] of Object.entries(storedScorers)) {
+      try {
+        const scorer = this.getScorer(scorerKey);
+        resolvedScorers[scorerKey] = {
+          scorer,
+          sampling: scorerConfig.sampling
+        };
+      } catch {
+        try {
+          const scorer = this.getScorerById(scorerKey);
+          resolvedScorers[scorerKey] = {
+            scorer,
+            sampling: scorerConfig.sampling
+          };
+        } catch {
+          this.#logger?.warn(`Scorer "${scorerKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return Object.keys(resolvedScorers).length > 0 ? resolvedScorers : void 0;
+  }
   /**
    * Adds a new agent to the Mastra instance.
    *
@@ -527,6 +808,9 @@ var Mastra = class {
    * ```
    */
   addAgent(agent, key) {
+    if (!agent) {
+      throw createUndefinedPrimitiveError("agent", agent, key);
+    }
     const agentKey = key || agent.id;
     const agents = this.#agents;
     if (agents[agentKey]) {
@@ -544,6 +828,13 @@ var Mastra = class {
       vectors: this.#vectors
     });
     agents[agentKey] = agent;
+    agent.getConfiguredProcessorWorkflows().then((processorWorkflows) => {
+      for (const workflow of processorWorkflows) {
+        this.addWorkflow(workflow, workflow.id);
+      }
+    }).catch((err) => {
+      this.#logger?.debug(`Failed to register processor workflows for agent ${agentKey}:`, err);
+    });
   }
   /**
    * Retrieves a registered vector store by its name.
@@ -689,6 +980,9 @@ var Mastra = class {
    * ```
    */
   addVector(vector, key) {
+    if (!vector) {
+      throw createUndefinedPrimitiveError("vector", vector, key);
+    }
     const vectorKey = key || vector.id;
     const vectors = this.#vectors;
     if (vectors[vectorKey]) {
@@ -859,6 +1153,44 @@ var Mastra = class {
     }
     return workflow;
   }
+  async listActiveWorkflowRuns() {
+    const storage = this.#storage;
+    if (!storage) {
+      this.#logger.debug("Cannot get active workflow runs. Mastra storage is not initialized");
+      return { runs: [], total: 0 };
+    }
+    const defaultEngineWorkflows = Object.values(this.#workflows).filter((workflow) => workflow.engineType === "default");
+    const allRuns = [];
+    let allTotal = 0;
+    for (const workflow of defaultEngineWorkflows) {
+      const runningRuns = await workflow.listWorkflowRuns({ status: "running" });
+      const waitingRuns = await workflow.listWorkflowRuns({ status: "waiting" });
+      allRuns.push(...runningRuns.runs, ...waitingRuns.runs);
+      allTotal += runningRuns.total + waitingRuns.total;
+    }
+    return {
+      runs: allRuns,
+      total: allTotal
+    };
+  }
+  async restartAllActiveWorkflowRuns() {
+    const activeRuns = await this.listActiveWorkflowRuns();
+    if (activeRuns.runs.length > 0) {
+      this.#logger.debug(
+        `Restarting ${activeRuns.runs.length} active workflow run${activeRuns.runs.length > 1 ? "s" : ""}`
+      );
+    }
+    for (const runSnapshot of activeRuns.runs) {
+      const workflow = this.getWorkflowById(runSnapshot.workflowName);
+      try {
+        const run = await workflow.createRun({ runId: runSnapshot.runId });
+        await run.restart();
+        this.#logger.debug(`Restarted ${runSnapshot.workflowName} workflow run ${runSnapshot.runId}`);
+      } catch (error) {
+        this.#logger.error(`Failed to restart ${runSnapshot.workflowName} workflow run ${runSnapshot.runId}: ${error}`);
+      }
+    }
+  }
   /**
    * Returns all registered scorers as a record keyed by their IDs.
    *
@@ -907,6 +1239,9 @@ var Mastra = class {
    * ```
    */
   addScorer(scorer, key) {
+    if (!scorer) {
+      throw createUndefinedPrimitiveError("scorer", scorer, key);
+    }
     const scorerKey = key || scorer.id;
     const scorers = this.#scorers;
     if (scorers[scorerKey]) {
@@ -914,6 +1249,7 @@ var Mastra = class {
       logger.debug(`Scorer with key ${scorerKey} already exists. Skipping addition.`);
       return;
     }
+    scorer.__registerMastra(this);
     scorers[scorerKey] = scorer;
   }
   /**
@@ -1134,6 +1470,9 @@ var Mastra = class {
    * ```
    */
   addTool(tool, key) {
+    if (!tool) {
+      throw createUndefinedPrimitiveError("tool", tool, key);
+    }
     const toolKey = key || tool.id;
     const tools = this.#tools;
     if (tools[toolKey]) {
@@ -1269,6 +1608,9 @@ var Mastra = class {
    * ```
    */
   addProcessor(processor, key) {
+    if (!processor) {
+      throw createUndefinedPrimitiveError("processor", processor, key);
+    }
     const processorKey = key || processor.id;
     const processors = this.#processors;
     if (processors[processorKey]) {
@@ -1278,6 +1620,131 @@ var Mastra = class {
     }
     processors[processorKey] = processor;
   }
+  /**
+   * Retrieves a registered memory instance by its registration key.
+   *
+   * @throws {MastraError} When the memory instance with the specified key is not found
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   memory: {
+   *     chat: new Memory({ storage })
+   *   }
+   * });
+   *
+   * const chatMemory = mastra.getMemory('chat');
+   * ```
+   */
+  getMemory(name) {
+    if (!this.#memory || !this.#memory[name]) {
+      const error = new MastraError({
+        id: "MASTRA_GET_MEMORY_BY_KEY_NOT_FOUND",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Memory with key ${String(name)} not found`,
+        details: {
+          status: 404,
+          memoryKey: String(name),
+          memory: Object.keys(this.#memory ?? {}).join(", ")
+        }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    return this.#memory[name];
+  }
+  /**
+   * Retrieves a registered memory instance by its ID.
+   *
+   * Searches through all registered memory instances and returns the one whose ID matches.
+   *
+   * @throws {MastraError} When no memory instance with the specified ID is found
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   memory: {
+   *     chat: new Memory({ id: 'chat-memory', storage })
+   *   }
+   * });
+   *
+   * const memory = mastra.getMemoryById('chat-memory');
+   * ```
+   */
+  getMemoryById(id) {
+    const allMemory = this.#memory;
+    if (allMemory) {
+      for (const [, memory] of Object.entries(allMemory)) {
+        if (memory.id === id) {
+          return memory;
+        }
+      }
+    }
+    const error = new MastraError({
+      id: "MASTRA_GET_MEMORY_BY_ID_NOT_FOUND",
+      domain: "MASTRA" /* MASTRA */,
+      category: "USER" /* USER */,
+      text: `Memory with id ${id} not found`,
+      details: {
+        status: 404,
+        memoryId: id,
+        availableIds: Object.values(allMemory ?? {}).map((m) => m.id).join(", ")
+      }
+    });
+    this.#logger?.trackException(error);
+    throw error;
+  }
+  /**
+   * Returns all registered memory instances as a record keyed by their names.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   memory: {
+   *     chat: new Memory({ storage }),
+   *     longTerm: new Memory({ storage })
+   *   }
+   * });
+   *
+   * const allMemory = mastra.listMemory();
+   * console.log(Object.keys(allMemory)); // ['chat', 'longTerm']
+   * ```
+   */
+  listMemory() {
+    return this.#memory;
+  }
+  /**
+   * Adds a new memory instance to the Mastra instance.
+   *
+   * This method allows dynamic registration of memory instances after the Mastra instance
+   * has been created.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra();
+   * const chatMemory = new Memory({
+   *   id: 'chat-memory',
+   *   storage: mastra.getStorage()
+   * });
+   * mastra.addMemory(chatMemory); // Uses memory.id as key
+   * // or
+   * mastra.addMemory(chatMemory, 'customKey'); // Uses custom key
+   * ```
+   */
+  addMemory(memory, key) {
+    if (!memory) {
+      throw createUndefinedPrimitiveError("memory", memory, key);
+    }
+    const memoryKey = key || memory.id;
+    const memoryRegistry = this.#memory;
+    if (memoryRegistry[memoryKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Memory with key ${memoryKey} already exists. Skipping addition.`);
+      return;
+    }
+    memoryRegistry[memoryKey] = memory;
+  }
   /**
    * Returns all registered workflows as a record keyed by their IDs.
    *
@@ -1333,6 +1800,9 @@ var Mastra = class {
    * ```
    */
   addWorkflow(workflow, key) {
+    if (!workflow) {
+      throw createUndefinedPrimitiveError("workflow", workflow, key);
+    }
     const workflowKey = key || workflow.id;
     const workflows = this.#workflows;
     if (workflows[workflowKey]) {
@@ -1345,6 +1815,9 @@ var Mastra = class {
       logger: this.getLogger(),
       storage: this.getStorage()
     });
+    if (!workflow.committed) {
+      workflow.commit();
+    }
     workflows[workflowKey] = workflow;
   }
   /**
@@ -1398,6 +1871,9 @@ var Mastra = class {
         this.#mcpServers?.[key]?.__setLogger(this.#logger);
       });
     }
+    if (this.#serverAdapter) {
+      this.#serverAdapter.__setLogger(this.#logger);
+    }
     this.#observability.setLogger({ logger: this.#logger });
   }
   /**
@@ -1511,6 +1987,74 @@ var Mastra = class {
   getServer() {
     return this.#server;
   }
+  /**
+   * Sets the server adapter for this Mastra instance.
+   *
+   * The server adapter provides access to the underlying server app (e.g., Hono, Express)
+   * and allows users to call routes directly via `app.fetch()` instead of making HTTP requests.
+   *
+   * This is typically called by `createHonoServer` or similar factory functions during
+   * server initialization.
+   *
+   * @param adapter - The server adapter instance (e.g., MastraServer from @mastra/hono or @mastra/express)
+   *
+   * @example
+   * ```typescript
+   * const app = new Hono();
+   * const adapter = new MastraServer({ app, mastra });
+   * mastra.setMastraServer(adapter);
+   * ```
+   */
+  setMastraServer(adapter) {
+    if (this.#serverAdapter) {
+      this.#logger?.debug(
+        "Replacing existing server adapter. Only one adapter should be registered per Mastra instance."
+      );
+    }
+    this.#serverAdapter = adapter;
+    if (this.#logger) {
+      adapter.__setLogger(this.#logger);
+    }
+  }
+  /**
+   * Gets the server adapter for this Mastra instance.
+   *
+   * @returns The server adapter, or undefined if not set
+   *
+   * @example
+   * ```typescript
+   * const adapter = mastra.getMastraServer();
+   * if (adapter) {
+   *   const app = adapter.getApp<Hono>();
+   * }
+   * ```
+   */
+  getMastraServer() {
+    return this.#serverAdapter;
+  }
+  /**
+   * Gets the server app from the server adapter.
+   *
+   * This is a convenience method that calls `getMastraServer()?.getApp<T>()`.
+   * Use this to access the underlying server framework's app instance (e.g., Hono, Express)
+   * for direct operations like calling routes via `app.fetch()`.
+   *
+   * @template T - The expected type of the app (e.g., Hono, Express Application)
+   * @returns The server app, or undefined if no adapter is set
+   *
+   * @example
+   * ```typescript
+   * // After createHonoServer() is called:
+   * const app = mastra.getServerApp<Hono>();
+   *
+   * // Call routes directly without HTTP overhead
+   * const response = await app?.fetch(new Request('http://localhost/health'));
+   * const data = await response?.json();
+   * ```
+   */
+  getServerApp() {
+    return this.#serverAdapter?.getApp();
+  }
   getBundlerConfig() {
     return this.#bundler;
   }
@@ -1634,6 +2178,9 @@ var Mastra = class {
    * ```
    */
   addMCPServer(server, key) {
+    if (!server) {
+      throw createUndefinedPrimitiveError("mcp-server", server, key);
+    }
     if (key) {
       server.setId(key);
     }
@@ -1778,6 +2325,201 @@ var Mastra = class {
     }
     await this.#pubsub.flush();
   }
+  /**
+   * Retrieves a registered gateway by its key.
+   *
+   * @throws {MastraError} When the gateway with the specified key is not found
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   gateways: {
+   *     myGateway: new CustomGateway()
+   *   }
+   * });
+   *
+   * const gateway = mastra.getGateway('myGateway');
+   * ```
+   */
+  getGateway(key) {
+    const gateway = this.#gateways?.[key];
+    if (!gateway) {
+      const error = new MastraError({
+        id: "MASTRA_GET_GATEWAY_BY_KEY_NOT_FOUND",
+        domain: "MASTRA" /* MASTRA */,
+        category: "USER" /* USER */,
+        text: `Gateway with key ${key} not found`,
+        details: {
+          status: 404,
+          gatewayKey: key,
+          gateways: Object.keys(this.#gateways ?? {}).join(", ")
+        }
+      });
+      this.#logger?.trackException(error);
+      throw error;
+    }
+    return gateway;
+  }
+  /**
+   * Retrieves a registered gateway by its ID.
+   *
+   * Searches through all registered gateways and returns the one whose ID matches.
+   * If a gateway doesn't have an explicit ID, its name is used as the ID.
+   *
+   * @throws {MastraError} When no gateway with the specified ID is found
+   *
+   * @example
+   * ```typescript
+   * class CustomGateway extends MastraModelGateway {
+   *   readonly id = 'custom-gateway-v1';
+   *   readonly name = 'Custom Gateway';
+   *   // ...
+   * }
+   *
+   * const mastra = new Mastra({
+   *   gateways: {
+   *     myGateway: new CustomGateway()
+   *   }
+   * });
+   *
+   * const gateway = mastra.getGatewayById('custom-gateway-v1');
+   * ```
+   */
+  getGatewayById(id) {
+    const gateways = this.#gateways ?? {};
+    for (const gateway of Object.values(gateways)) {
+      if (gateway.getId() === id) {
+        return gateway;
+      }
+    }
+    const error = new MastraError({
+      id: "MASTRA_GET_GATEWAY_BY_ID_NOT_FOUND",
+      domain: "MASTRA" /* MASTRA */,
+      category: "USER" /* USER */,
+      text: `Gateway with ID ${id} not found`,
+      details: {
+        status: 404,
+        gatewayId: id,
+        availableIds: Object.values(gateways).map((g) => g.getId()).join(", ")
+      }
+    });
+    this.#logger?.trackException(error);
+    throw error;
+  }
+  /**
+   * Returns all registered gateways as a record keyed by their names.
+   *
+   * @example
+   * ```typescript
+   * const mastra = new Mastra({
+   *   gateways: {
+   *     netlify: new NetlifyGateway(),
+   *     custom: new CustomGateway()
+   *   }
+   * });
+   *
+   * const allGateways = mastra.listGateways();
+   * console.log(Object.keys(allGateways)); // ['netlify', 'custom']
+   * ```
+   */
+  listGateways() {
+    return this.#gateways;
+  }
+  /**
+   * Adds a new gateway to the Mastra instance.
+   *
+   * This method allows dynamic registration of gateways after the Mastra instance
+   * has been created. Gateways enable access to LLM providers through custom
+   * authentication and routing logic.
+   *
+   * If no key is provided, the gateway's ID (or name if no ID is set) will be used as the key.
+   *
+   * @example
+   * ```typescript
+   * import { MastraModelGateway } from '@mastra/core';
+   *
+   * class CustomGateway extends MastraModelGateway {
+   *   readonly id = 'custom-gateway-v1';  // Optional, defaults to name
+   *   readonly name = 'custom';
+   *   readonly prefix = 'custom';
+   *
+   *   async fetchProviders() {
+   *     return {
+   *       myProvider: {
+   *         name: 'My Provider',
+   *         models: ['model-1', 'model-2'],
+   *         apiKeyEnvVar: 'MY_API_KEY',
+   *         gateway: 'custom'
+   *       }
+   *     };
+   *   }
+   *
+   *   buildUrl(modelId: string) {
+   *     return 'https://api.myprovider.com/v1';
+   *   }
+   *
+   *   async getApiKey(modelId: string) {
+   *     return process.env.MY_API_KEY || '';
+   *   }
+   *
+   *   async resolveLanguageModel({ modelId, providerId, apiKey }) {
+   *     const baseURL = this.buildUrl(`${providerId}/${modelId}`);
+   *     return createOpenAICompatible({
+   *       name: providerId,
+   *       apiKey,
+   *       baseURL,
+   *       supportsStructuredOutputs: true,
+   *     }).chatModel(modelId);
+   *   }
+   * }
+   *
+   * const mastra = new Mastra();
+   * const newGateway = new CustomGateway();
+   * mastra.addGateway(newGateway); // Uses gateway.getId() as key (gateway.id)
+   * // or
+   * mastra.addGateway(newGateway, 'customKey'); // Uses custom key
+   * ```
+   */
+  addGateway(gateway, key) {
+    if (!gateway) {
+      throw createUndefinedPrimitiveError("gateway", gateway, key);
+    }
+    const gatewayKey = key || gateway.getId();
+    const gateways = this.#gateways;
+    if (gateways[gatewayKey]) {
+      const logger = this.getLogger();
+      logger.debug(`Gateway with key ${gatewayKey} already exists. Skipping addition.`);
+      return;
+    }
+    gateways[gatewayKey] = gateway;
+    this.#syncGatewayRegistry();
+  }
+  /**
+   * Sync custom gateways with the GatewayRegistry for type generation
+   * @private
+   */
+  #syncGatewayRegistry() {
+    try {
+      if (process.env.MASTRA_DEV !== "true" && process.env.MASTRA_DEV !== "1") {
+        return;
+      }
+      import('./provider-registry-F67Y6OF2.js').then(async ({ GatewayRegistry }) => {
+        const registry = GatewayRegistry.getInstance();
+        const customGateways = Object.values(this.#gateways || {});
+        registry.registerCustomGateways(customGateways);
+        const logger = this.getLogger();
+        logger.info("\u{1F504} Syncing custom gateway types...");
+        await registry.syncGateways(true);
+        logger.info("\u2705 Custom gateway types synced! Restart your TypeScript server to see autocomplete.");
+      }).catch((err) => {
+        const logger = this.getLogger();
+        logger.debug("Gateway registry sync skipped:", err);
+      });
+    } catch (err) {
+      const logger = this.getLogger();
+      logger.debug("Gateway registry sync failed:", err);
+    }
+  }
   /**
    * Gracefully shuts down the Mastra instance and cleans up all resources.
    *
@@ -1815,5 +2557,5 @@ var Mastra = class {
 };
 
 export { Mastra };
-//# sourceMappingURL=chunk-VOQ3ULMT.js.map
-//# sourceMappingURL=chunk-VOQ3ULMT.js.map
+//# sourceMappingURL=chunk-U3XOLEPX.js.map
+//# sourceMappingURL=chunk-U3XOLEPX.js.map