@mastra/editor 0.0.0-om-20260204032032

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# @mastra/editor
+
+## 0.0.0-om-20260204032032
+
+### Minor Changes
+
+- Created @mastra/editor package for managing and resolving stored agent configurations ([#12631](https://github.com/mastra-ai/mastra/pull/12631))
+
+  This major addition introduces the editor package, which provides a complete solution for storing, versioning, and instantiating agent configurations from a database. The editor seamlessly integrates with Mastra's storage layer to enable dynamic agent management.
+
+  **Key Features:**
+  - **Agent Storage & Retrieval**: Store complete agent configurations including instructions, model settings, tools, workflows, nested agents, scorers, processors, and memory configuration
+  - **Version Management**: Create and manage multiple versions of agents, with support for activating specific versions
+  - **Dependency Resolution**: Automatically resolves and instantiates all agent dependencies (tools, workflows, sub-agents, etc.) from the Mastra registry
+  - **Caching**: Built-in caching for improved performance when repeatedly accessing stored agents
+  - **Type Safety**: Full TypeScript support with proper typing for stored configurations
+
+  **Usage Example:**
+
+  ```typescript
+  import { MastraEditor } from '@mastra/editor';
+  import { Mastra } from '@mastra/core';
+
+  // Initialize editor with Mastra
+  const mastra = new Mastra({
+    /* config */
+    editor: new MastraEditor(),
+  });
+
+  // Store an agent configuration
+  const agentId = await mastra.storage.stores?.agents?.createAgent({
+    name: 'customer-support',
+    instructions: 'Help customers with inquiries',
+    model: { provider: 'openai', name: 'gpt-4' },
+    tools: ['search-kb', 'create-ticket'],
+    workflows: ['escalation-flow'],
+    memory: { vector: 'pinecone-db' },
+  });
+
+  // Retrieve and use the stored agent
+  const agent = await mastra.getEditor()?.getStoredAgentById(agentId);
+  const response = await agent?.generate('How do I reset my password?');
+
+  // List all stored agents
+  const agents = await mastra.getEditor()?.listStoredAgents({ pageSize: 10 });
+  ```
+
+  **Storage Improvements:**
+  - Fixed JSONB handling in LibSQL, PostgreSQL, and MongoDB adapters
+  - Improved agent resolution queries to properly merge version data
+  - Enhanced type safety for serialized configurations
+
+### Patch Changes
+
+- Updated dependencies [[`e6fc281`](https://github.com/mastra-ai/mastra/commit/e6fc281896a3584e9e06465b356a44fe7faade65), [`97be6c8`](https://github.com/mastra-ai/mastra/commit/97be6c8963130fca8a664fcf99d7b3a38e463595), [`e41c549`](https://github.com/mastra-ai/mastra/commit/e41c549e51f45ecdfa12473b7d97ce29d3fa7fd2), [`b1695db`](https://github.com/mastra-ai/mastra/commit/b1695db2d7be0c329d499619c7881899649188d0), [`5fe1fe0`](https://github.com/mastra-ai/mastra/commit/5fe1fe0109faf2c87db34b725d8a4571a594f80e), [`13e0a2a`](https://github.com/mastra-ai/mastra/commit/13e0a2a2bcec01ff4d701274b3727d5e907a6a01), [`f6673b8`](https://github.com/mastra-ai/mastra/commit/f6673b893b65b7d273ad25ead42e990704cc1e17), [`cd6be8a`](https://github.com/mastra-ai/mastra/commit/cd6be8ad32741cd41cabf508355bb31b71e8a5bd), [`9eb4e8e`](https://github.com/mastra-ai/mastra/commit/9eb4e8e39efbdcfff7a40ff2ce07ce2714c65fa8), [`aa37c84`](https://github.com/mastra-ai/mastra/commit/aa37c84d29b7db68c72517337932ef486c316275), [`47eba72`](https://github.com/mastra-ai/mastra/commit/47eba72f0397d0d14fbe324b97940c3d55e5a525)]:
+  - @mastra/core@0.0.0-om-20260204032032
+  - @mastra/memory@0.0.0-om-20260204032032
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of @mastra/editor
+  - Agent storage and retrieval from database
+  - Dynamic agent creation from stored configurations
+  - Support for tools, workflows, nested agents, memory, and scorers
+  - Integration with Mastra core for seamless agent management

package/LICENSE.md

@@ -0,0 +1,15 @@
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/dist/index.cjs

@@ -0,0 +1,424 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MastraEditor: () => MastraEditor
+});
+module.exports = __toCommonJS(index_exports);
+var import_memory = require("@mastra/memory");
+var import_core = require("@mastra/core");
+var MastraEditor = class {
+  constructor(config) {
+    this.logger = config?.logger;
+  }
+  /**
+   * Register this editor with a Mastra instance.
+   * This gives the editor access to Mastra's storage, tools, workflows, etc.
+   */
+  registerWithMastra(mastra) {
+    this.mastra = mastra;
+    if (!this.logger) {
+      this.logger = mastra.getLogger();
+    }
+  }
+  /**
+   * Get the agents storage domain from the Mastra storage.
+   */
+  async getAgentsStore() {
+    const storage = this.mastra.getStorage();
+    if (!storage) throw new Error("Storage is not configured");
+    const agentsStore = await storage.getStore("agents");
+    if (!agentsStore) throw new Error("Agents storage domain is not available");
+    return agentsStore;
+  }
+  async getStoredAgentById(id, options) {
+    if (!this.mastra) {
+      throw new Error("MastraEditor is not registered with a Mastra instance");
+    }
+    const agentsStore = await this.getAgentsStore();
+    if (options?.versionId && options?.versionNumber !== void 0) {
+      this.logger?.warn(`Both versionId and versionNumber provided for agent "${id}". Using versionId.`);
+    }
+    if (options?.versionId) {
+      const version = await agentsStore.getVersion(options.versionId);
+      if (!version) {
+        return null;
+      }
+      if (version.agentId !== id) {
+        return null;
+      }
+      const {
+        id: _versionId,
+        agentId: _agentId,
+        versionNumber: _versionNumber,
+        changedFields: _changedFields,
+        changeMessage: _changeMessage,
+        createdAt: _createdAt,
+        ...snapshotConfig
+      } = version;
+      const agentRecord = await agentsStore.getAgentById({ id });
+      if (!agentRecord) {
+        return null;
+      }
+      const { activeVersionId: _activeVersionId, ...agentRecordWithoutActiveVersion } = agentRecord;
+      const resolvedAgent = { ...agentRecordWithoutActiveVersion, ...snapshotConfig };
+      if (options?.returnRaw) {
+        return resolvedAgent;
+      }
+      return this.createAgentFromStoredConfig(resolvedAgent);
+    }
+    if (options?.versionNumber !== void 0) {
+      const version = await agentsStore.getVersionByNumber(id, options.versionNumber);
+      if (!version) {
+        return null;
+      }
+      const {
+        id: _versionId,
+        agentId: _agentId,
+        versionNumber: _versionNumber,
+        changedFields: _changedFields,
+        changeMessage: _changeMessage,
+        createdAt: _createdAt,
+        ...snapshotConfig
+      } = version;
+      const agentRecord = await agentsStore.getAgentById({ id });
+      if (!agentRecord) {
+        return null;
+      }
+      const { activeVersionId: _activeVersionId, ...agentRecordWithoutActiveVersion } = agentRecord;
+      const resolvedAgent = { ...agentRecordWithoutActiveVersion, ...snapshotConfig };
+      if (options?.returnRaw) {
+        return resolvedAgent;
+      }
+      return this.createAgentFromStoredConfig(resolvedAgent);
+    }
+    if (!options?.returnRaw) {
+      const agentCache2 = this.mastra.getStoredAgentCache();
+      if (agentCache2) {
+        const cached = agentCache2.get(id);
+        if (cached) {
+          this.logger?.debug(`[getStoredAgentById] Returning cached agent "${id}"`);
+          return cached;
+        }
+        this.logger?.debug(`[getStoredAgentById] Cache miss for agent "${id}", fetching from storage`);
+      }
+    }
+    const storedAgent = await agentsStore.getAgentByIdResolved({ id });
+    if (!storedAgent) {
+      return null;
+    }
+    if (options?.returnRaw) {
+      return storedAgent;
+    }
+    const agent = this.createAgentFromStoredConfig(storedAgent);
+    const agentCache = this.mastra.getStoredAgentCache();
+    if (agentCache) {
+      agentCache.set(id, agent);
+    }
+    return agent;
+  }
+  async listStoredAgents(options) {
+    if (!this.mastra) {
+      throw new Error("MastraEditor is not registered with a Mastra instance");
+    }
+    const agentsStore = await this.getAgentsStore();
+    const result = await agentsStore.listAgentsResolved({
+      page: options?.page,
+      perPage: options?.pageSize,
+      orderBy: { field: "createdAt", direction: "DESC" }
+    });
+    if (options?.returnRaw) {
+      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
+    };
+  }
+  /**
+   * Clear the stored agent cache for a specific agent ID, or all cached agents.
+   */
+  clearStoredAgentCache(agentId) {
+    if (!this.mastra) return;
+    const agentCache = this.mastra.getStoredAgentCache();
+    if (!agentCache) return;
+    if (agentId) {
+      agentCache.delete(agentId);
+      this.logger?.debug(`[clearStoredAgentCache] Cleared cache for agent "${agentId}"`);
+    } else {
+      agentCache.clear();
+      this.logger?.debug("[clearStoredAgentCache] Cleared all cached agents");
+    }
+  }
+  /**
+   * Create an Agent instance from stored configuration.
+   * Resolves all stored references (tools, workflows, agents, memory, scorers)
+   * and registers the agent with the Mastra instance.
+   */
+  createAgentFromStoredConfig(storedAgent) {
+    if (!this.mastra) {
+      throw new Error("MastraEditor is not registered with a Mastra instance");
+    }
+    this.logger?.debug(`[createAgentFromStoredConfig] Creating agent from stored config "${storedAgent.id}"`);
+    const tools = this.resolveStoredTools(storedAgent.tools);
+    const workflows = this.resolveStoredWorkflows(storedAgent.workflows);
+    const agents = this.resolveStoredAgents(storedAgent.agents);
+    const memory = this.resolveStoredMemory(storedAgent.memory);
+    console.log(
+      `[createAgentFromStoredConfig] Resolved memory: ${memory ? "Memory instance created" : "No memory"} for agent "${storedAgent.id}"`,
+      { memory }
+    );
+    const scorers = this.resolveStoredScorers(storedAgent.scorers);
+    const inputProcessors = this.resolveStoredInputProcessors(storedAgent.inputProcessors);
+    const outputProcessors = this.resolveStoredOutputProcessors(storedAgent.outputProcessors);
+    const modelConfig = storedAgent.model;
+    if (!modelConfig || !modelConfig.provider || !modelConfig.name) {
+      throw new Error(
+        `Stored agent "${storedAgent.id}" has no active version or invalid model configuration. Both provider and name are required.`
+      );
+    }
+    const model = `${modelConfig.provider}/${modelConfig.name}`;
+    const defaultOptions = storedAgent.defaultOptions;
+    const agent = new import_core.Agent({
+      id: storedAgent.id,
+      name: storedAgent.name,
+      description: storedAgent.description,
+      instructions: storedAgent.instructions,
+      model,
+      memory,
+      tools,
+      workflows,
+      agents,
+      scorers,
+      mastra: this.mastra,
+      inputProcessors,
+      outputProcessors,
+      defaultOptions: {
+        maxSteps: defaultOptions?.maxSteps,
+        modelSettings: {
+          temperature: modelConfig.temperature,
+          topP: modelConfig.topP,
+          frequencyPenalty: modelConfig.frequencyPenalty,
+          presencePenalty: modelConfig.presencePenalty,
+          maxOutputTokens: modelConfig.maxCompletionTokens
+        }
+      }
+    });
+    this.mastra?.addAgent(agent, storedAgent.id, { source: "stored" });
+    this.logger?.debug(`[createAgentFromStoredConfig] Successfully created agent "${storedAgent.id}"`);
+    return agent;
+  }
+  /**
+   * Resolve stored tool IDs to actual tool instances from Mastra's registry.
+   */
+  resolveStoredTools(storedTools) {
+    if (!storedTools || storedTools.length === 0) {
+      return {};
+    }
+    if (!this.mastra) {
+      return {};
+    }
+    const resolvedTools = {};
+    for (const toolKey of storedTools) {
+      try {
+        const tool = this.mastra.getToolById(toolKey);
+        resolvedTools[toolKey] = tool;
+      } catch {
+        this.logger?.warn(`Tool "${toolKey}" referenced in stored agent but not registered in Mastra`);
+      }
+    }
+    return resolvedTools;
+  }
+  /**
+   * Resolve stored workflow IDs to actual workflow instances from Mastra's registry.
+   */
+  resolveStoredWorkflows(storedWorkflows) {
+    if (!storedWorkflows || storedWorkflows.length === 0) {
+      return {};
+    }
+    if (!this.mastra) {
+      return {};
+    }
+    const resolvedWorkflows = {};
+    for (const workflowKey of storedWorkflows) {
+      try {
+        const workflow = this.mastra.getWorkflow(workflowKey);
+        resolvedWorkflows[workflowKey] = workflow;
+      } catch {
+        try {
+          const workflow = this.mastra.getWorkflowById(workflowKey);
+          resolvedWorkflows[workflowKey] = workflow;
+        } catch {
+          this.logger?.warn(`Workflow "${workflowKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return resolvedWorkflows;
+  }
+  /**
+   * Resolve stored agent IDs to actual agent instances from Mastra's registry.
+   */
+  resolveStoredAgents(storedAgents) {
+    if (!storedAgents || storedAgents.length === 0) {
+      return {};
+    }
+    if (!this.mastra) {
+      return {};
+    }
+    const resolvedAgents = {};
+    for (const agentKey of storedAgents) {
+      try {
+        const agent = this.mastra.getAgent(agentKey);
+        resolvedAgents[agentKey] = agent;
+      } catch {
+        try {
+          const agent = this.mastra.getAgentById(agentKey);
+          resolvedAgents[agentKey] = agent;
+        } catch {
+          this.logger?.warn(`Agent "${agentKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return resolvedAgents;
+  }
+  /**
+   * Resolve stored memory config to a MastraMemory instance.
+   * Uses @mastra/memory Memory class to instantiate from serialized config.
+   */
+  resolveStoredMemory(memoryConfig) {
+    this.logger?.debug(`[resolveStoredMemory] Called with config:`, { memoryConfig });
+    if (!memoryConfig) {
+      this.logger?.debug(`[resolveStoredMemory] No memory config provided`);
+      return void 0;
+    }
+    if (!this.mastra) {
+      this.logger?.warn("MastraEditor not registered with Mastra instance. Cannot instantiate memory.");
+      return void 0;
+    }
+    try {
+      let vector;
+      if (memoryConfig.vector) {
+        const vectors = this.mastra.listVectors();
+        vector = vectors?.[memoryConfig.vector];
+        if (!vector) {
+          this.logger?.warn(`Vector provider "${memoryConfig.vector}" not found in Mastra instance`);
+        }
+      }
+      const sharedConfig = {
+        storage: this.mastra.getStorage(),
+        vector,
+        options: memoryConfig.options,
+        embedder: memoryConfig.embedder,
+        embedderOptions: memoryConfig.embedderOptions
+      };
+      return new import_memory.Memory(sharedConfig);
+    } catch (error) {
+      this.logger?.error("Failed to resolve memory from config", { error });
+      return void 0;
+    }
+  }
+  /**
+   * Resolve stored scorer configs to MastraScorers instances.
+   */
+  resolveStoredScorers(storedScorers) {
+    if (!storedScorers || Object.keys(storedScorers).length === 0) {
+      return void 0;
+    }
+    if (!this.mastra) {
+      return void 0;
+    }
+    const resolvedScorers = {};
+    for (const [scorerKey, scorerConfig] of Object.entries(storedScorers)) {
+      try {
+        const scorer = this.mastra.getScorer(scorerKey);
+        resolvedScorers[scorerKey] = {
+          scorer,
+          sampling: scorerConfig.sampling
+        };
+      } catch {
+        try {
+          const scorer = this.mastra.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;
+  }
+  /**
+   * Look up a processor by key or ID from Mastra's registry.
+   */
+  findProcessor(processorKey) {
+    if (!this.mastra) return void 0;
+    try {
+      return this.mastra.getProcessor(processorKey);
+    } catch {
+      try {
+        return this.mastra.getProcessorById(processorKey);
+      } catch {
+        this.logger?.warn(`Processor "${processorKey}" referenced in stored agent but not registered in Mastra`);
+        return void 0;
+      }
+    }
+  }
+  /**
+   * Resolve stored input processor keys to actual processor instances.
+   */
+  resolveStoredInputProcessors(storedProcessors) {
+    if (!storedProcessors || storedProcessors.length === 0) return void 0;
+    const resolved = [];
+    for (const key of storedProcessors) {
+      const processor = this.findProcessor(key);
+      if (processor && (processor.processInput || processor.processInputStep)) {
+        resolved.push(processor);
+      }
+    }
+    return resolved.length > 0 ? resolved : void 0;
+  }
+  /**
+   * Resolve stored output processor keys to actual processor instances.
+   */
+  resolveStoredOutputProcessors(storedProcessors) {
+    if (!storedProcessors || storedProcessors.length === 0) return void 0;
+    const resolved = [];
+    for (const key of storedProcessors) {
+      const processor = this.findProcessor(key);
+      if (processor && (processor.processOutputStream || processor.processOutputResult || processor.processOutputStep)) {
+        resolved.push(processor);
+      }
+    }
+    return resolved.length > 0 ? resolved : void 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MastraEditor
+});

package/dist/index.d.cts

@@ -0,0 +1,102 @@
+import { IMastraEditor, MastraEditorConfig, Mastra, Agent, StorageResolvedAgentType } from '@mastra/core';
+export { MastraEditorConfig } from '@mastra/core';
+
+declare class MastraEditor implements IMastraEditor {
+    private logger?;
+    private mastra?;
+    constructor(config?: MastraEditorConfig);
+    /**
+     * Register this editor with a Mastra instance.
+     * This gives the editor access to Mastra's storage, tools, workflows, etc.
+     */
+    registerWithMastra(mastra: Mastra): void;
+    /**
+     * Get the agents storage domain from the Mastra storage.
+     */
+    private getAgentsStore;
+    /**
+     * Get a stored agent by its ID.
+     * Returns null when agent is not found. Returns an Agent instance by default,
+     * or raw StorageResolvedAgentType when raw option is true.
+     */
+    getStoredAgentById(id: string, options?: {
+        returnRaw?: false;
+        versionId?: string;
+        versionNumber?: number;
+    }): Promise<Agent | null>;
+    getStoredAgentById(id: string, options: {
+        returnRaw: true;
+        versionId?: string;
+        versionNumber?: number;
+    }): Promise<StorageResolvedAgentType | null>;
+    /**
+     * List all stored agents with page-based pagination.
+     */
+    listStoredAgents(options?: {
+        returnRaw?: false;
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        agents: Agent[];
+        total: number;
+        page: number;
+        perPage: number;
+        hasMore: boolean;
+    }>;
+    listStoredAgents(options: {
+        returnRaw: true;
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        agents: StorageResolvedAgentType[];
+        total: number;
+        page: number;
+        perPage: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Clear the stored agent cache for a specific agent ID, or all cached agents.
+     */
+    clearStoredAgentCache(agentId?: string): void;
+    /**
+     * Create an Agent instance from stored configuration.
+     * Resolves all stored references (tools, workflows, agents, memory, scorers)
+     * and registers the agent with the Mastra instance.
+     */
+    private createAgentFromStoredConfig;
+    /**
+     * Resolve stored tool IDs to actual tool instances from Mastra's registry.
+     */
+    private resolveStoredTools;
+    /**
+     * Resolve stored workflow IDs to actual workflow instances from Mastra's registry.
+     */
+    private resolveStoredWorkflows;
+    /**
+     * Resolve stored agent IDs to actual agent instances from Mastra's registry.
+     */
+    private resolveStoredAgents;
+    /**
+     * Resolve stored memory config to a MastraMemory instance.
+     * Uses @mastra/memory Memory class to instantiate from serialized config.
+     */
+    private resolveStoredMemory;
+    /**
+     * Resolve stored scorer configs to MastraScorers instances.
+     */
+    private resolveStoredScorers;
+    /**
+     * Look up a processor by key or ID from Mastra's registry.
+     */
+    private findProcessor;
+    /**
+     * Resolve stored input processor keys to actual processor instances.
+     */
+    private resolveStoredInputProcessors;
+    /**
+     * Resolve stored output processor keys to actual processor instances.
+     */
+    private resolveStoredOutputProcessors;
+}
+
+export { MastraEditor };

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import { IMastraEditor, MastraEditorConfig, Mastra, Agent, StorageResolvedAgentType } from '@mastra/core';
+export { MastraEditorConfig } from '@mastra/core';
+
+declare class MastraEditor implements IMastraEditor {
+    private logger?;
+    private mastra?;
+    constructor(config?: MastraEditorConfig);
+    /**
+     * Register this editor with a Mastra instance.
+     * This gives the editor access to Mastra's storage, tools, workflows, etc.
+     */
+    registerWithMastra(mastra: Mastra): void;
+    /**
+     * Get the agents storage domain from the Mastra storage.
+     */
+    private getAgentsStore;
+    /**
+     * Get a stored agent by its ID.
+     * Returns null when agent is not found. Returns an Agent instance by default,
+     * or raw StorageResolvedAgentType when raw option is true.
+     */
+    getStoredAgentById(id: string, options?: {
+        returnRaw?: false;
+        versionId?: string;
+        versionNumber?: number;
+    }): Promise<Agent | null>;
+    getStoredAgentById(id: string, options: {
+        returnRaw: true;
+        versionId?: string;
+        versionNumber?: number;
+    }): Promise<StorageResolvedAgentType | null>;
+    /**
+     * List all stored agents with page-based pagination.
+     */
+    listStoredAgents(options?: {
+        returnRaw?: false;
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        agents: Agent[];
+        total: number;
+        page: number;
+        perPage: number;
+        hasMore: boolean;
+    }>;
+    listStoredAgents(options: {
+        returnRaw: true;
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        agents: StorageResolvedAgentType[];
+        total: number;
+        page: number;
+        perPage: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Clear the stored agent cache for a specific agent ID, or all cached agents.
+     */
+    clearStoredAgentCache(agentId?: string): void;
+    /**
+     * Create an Agent instance from stored configuration.
+     * Resolves all stored references (tools, workflows, agents, memory, scorers)
+     * and registers the agent with the Mastra instance.
+     */
+    private createAgentFromStoredConfig;
+    /**
+     * Resolve stored tool IDs to actual tool instances from Mastra's registry.
+     */
+    private resolveStoredTools;
+    /**
+     * Resolve stored workflow IDs to actual workflow instances from Mastra's registry.
+     */
+    private resolveStoredWorkflows;
+    /**
+     * Resolve stored agent IDs to actual agent instances from Mastra's registry.
+     */
+    private resolveStoredAgents;
+    /**
+     * Resolve stored memory config to a MastraMemory instance.
+     * Uses @mastra/memory Memory class to instantiate from serialized config.
+     */
+    private resolveStoredMemory;
+    /**
+     * Resolve stored scorer configs to MastraScorers instances.
+     */
+    private resolveStoredScorers;
+    /**
+     * Look up a processor by key or ID from Mastra's registry.
+     */
+    private findProcessor;
+    /**
+     * Resolve stored input processor keys to actual processor instances.
+     */
+    private resolveStoredInputProcessors;
+    /**
+     * Resolve stored output processor keys to actual processor instances.
+     */
+    private resolveStoredOutputProcessors;
+}
+
+export { MastraEditor };

package/dist/index.js

@@ -0,0 +1,399 @@
+// src/index.ts
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core";
+var MastraEditor = class {
+  constructor(config) {
+    this.logger = config?.logger;
+  }
+  /**
+   * Register this editor with a Mastra instance.
+   * This gives the editor access to Mastra's storage, tools, workflows, etc.
+   */
+  registerWithMastra(mastra) {
+    this.mastra = mastra;
+    if (!this.logger) {
+      this.logger = mastra.getLogger();
+    }
+  }
+  /**
+   * Get the agents storage domain from the Mastra storage.
+   */
+  async getAgentsStore() {
+    const storage = this.mastra.getStorage();
+    if (!storage) throw new Error("Storage is not configured");
+    const agentsStore = await storage.getStore("agents");
+    if (!agentsStore) throw new Error("Agents storage domain is not available");
+    return agentsStore;
+  }
+  async getStoredAgentById(id, options) {
+    if (!this.mastra) {
+      throw new Error("MastraEditor is not registered with a Mastra instance");
+    }
+    const agentsStore = await this.getAgentsStore();
+    if (options?.versionId && options?.versionNumber !== void 0) {
+      this.logger?.warn(`Both versionId and versionNumber provided for agent "${id}". Using versionId.`);
+    }
+    if (options?.versionId) {
+      const version = await agentsStore.getVersion(options.versionId);
+      if (!version) {
+        return null;
+      }
+      if (version.agentId !== id) {
+        return null;
+      }
+      const {
+        id: _versionId,
+        agentId: _agentId,
+        versionNumber: _versionNumber,
+        changedFields: _changedFields,
+        changeMessage: _changeMessage,
+        createdAt: _createdAt,
+        ...snapshotConfig
+      } = version;
+      const agentRecord = await agentsStore.getAgentById({ id });
+      if (!agentRecord) {
+        return null;
+      }
+      const { activeVersionId: _activeVersionId, ...agentRecordWithoutActiveVersion } = agentRecord;
+      const resolvedAgent = { ...agentRecordWithoutActiveVersion, ...snapshotConfig };
+      if (options?.returnRaw) {
+        return resolvedAgent;
+      }
+      return this.createAgentFromStoredConfig(resolvedAgent);
+    }
+    if (options?.versionNumber !== void 0) {
+      const version = await agentsStore.getVersionByNumber(id, options.versionNumber);
+      if (!version) {
+        return null;
+      }
+      const {
+        id: _versionId,
+        agentId: _agentId,
+        versionNumber: _versionNumber,
+        changedFields: _changedFields,
+        changeMessage: _changeMessage,
+        createdAt: _createdAt,
+        ...snapshotConfig
+      } = version;
+      const agentRecord = await agentsStore.getAgentById({ id });
+      if (!agentRecord) {
+        return null;
+      }
+      const { activeVersionId: _activeVersionId, ...agentRecordWithoutActiveVersion } = agentRecord;
+      const resolvedAgent = { ...agentRecordWithoutActiveVersion, ...snapshotConfig };
+      if (options?.returnRaw) {
+        return resolvedAgent;
+      }
+      return this.createAgentFromStoredConfig(resolvedAgent);
+    }
+    if (!options?.returnRaw) {
+      const agentCache2 = this.mastra.getStoredAgentCache();
+      if (agentCache2) {
+        const cached = agentCache2.get(id);
+        if (cached) {
+          this.logger?.debug(`[getStoredAgentById] Returning cached agent "${id}"`);
+          return cached;
+        }
+        this.logger?.debug(`[getStoredAgentById] Cache miss for agent "${id}", fetching from storage`);
+      }
+    }
+    const storedAgent = await agentsStore.getAgentByIdResolved({ id });
+    if (!storedAgent) {
+      return null;
+    }
+    if (options?.returnRaw) {
+      return storedAgent;
+    }
+    const agent = this.createAgentFromStoredConfig(storedAgent);
+    const agentCache = this.mastra.getStoredAgentCache();
+    if (agentCache) {
+      agentCache.set(id, agent);
+    }
+    return agent;
+  }
+  async listStoredAgents(options) {
+    if (!this.mastra) {
+      throw new Error("MastraEditor is not registered with a Mastra instance");
+    }
+    const agentsStore = await this.getAgentsStore();
+    const result = await agentsStore.listAgentsResolved({
+      page: options?.page,
+      perPage: options?.pageSize,
+      orderBy: { field: "createdAt", direction: "DESC" }
+    });
+    if (options?.returnRaw) {
+      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
+    };
+  }
+  /**
+   * Clear the stored agent cache for a specific agent ID, or all cached agents.
+   */
+  clearStoredAgentCache(agentId) {
+    if (!this.mastra) return;
+    const agentCache = this.mastra.getStoredAgentCache();
+    if (!agentCache) return;
+    if (agentId) {
+      agentCache.delete(agentId);
+      this.logger?.debug(`[clearStoredAgentCache] Cleared cache for agent "${agentId}"`);
+    } else {
+      agentCache.clear();
+      this.logger?.debug("[clearStoredAgentCache] Cleared all cached agents");
+    }
+  }
+  /**
+   * Create an Agent instance from stored configuration.
+   * Resolves all stored references (tools, workflows, agents, memory, scorers)
+   * and registers the agent with the Mastra instance.
+   */
+  createAgentFromStoredConfig(storedAgent) {
+    if (!this.mastra) {
+      throw new Error("MastraEditor is not registered with a Mastra instance");
+    }
+    this.logger?.debug(`[createAgentFromStoredConfig] Creating agent from stored config "${storedAgent.id}"`);
+    const tools = this.resolveStoredTools(storedAgent.tools);
+    const workflows = this.resolveStoredWorkflows(storedAgent.workflows);
+    const agents = this.resolveStoredAgents(storedAgent.agents);
+    const memory = this.resolveStoredMemory(storedAgent.memory);
+    console.log(
+      `[createAgentFromStoredConfig] Resolved memory: ${memory ? "Memory instance created" : "No memory"} for agent "${storedAgent.id}"`,
+      { memory }
+    );
+    const scorers = this.resolveStoredScorers(storedAgent.scorers);
+    const inputProcessors = this.resolveStoredInputProcessors(storedAgent.inputProcessors);
+    const outputProcessors = this.resolveStoredOutputProcessors(storedAgent.outputProcessors);
+    const modelConfig = storedAgent.model;
+    if (!modelConfig || !modelConfig.provider || !modelConfig.name) {
+      throw new Error(
+        `Stored agent "${storedAgent.id}" has no active version or invalid model configuration. Both provider and name are required.`
+      );
+    }
+    const model = `${modelConfig.provider}/${modelConfig.name}`;
+    const defaultOptions = storedAgent.defaultOptions;
+    const agent = new Agent({
+      id: storedAgent.id,
+      name: storedAgent.name,
+      description: storedAgent.description,
+      instructions: storedAgent.instructions,
+      model,
+      memory,
+      tools,
+      workflows,
+      agents,
+      scorers,
+      mastra: this.mastra,
+      inputProcessors,
+      outputProcessors,
+      defaultOptions: {
+        maxSteps: defaultOptions?.maxSteps,
+        modelSettings: {
+          temperature: modelConfig.temperature,
+          topP: modelConfig.topP,
+          frequencyPenalty: modelConfig.frequencyPenalty,
+          presencePenalty: modelConfig.presencePenalty,
+          maxOutputTokens: modelConfig.maxCompletionTokens
+        }
+      }
+    });
+    this.mastra?.addAgent(agent, storedAgent.id, { source: "stored" });
+    this.logger?.debug(`[createAgentFromStoredConfig] Successfully created agent "${storedAgent.id}"`);
+    return agent;
+  }
+  /**
+   * Resolve stored tool IDs to actual tool instances from Mastra's registry.
+   */
+  resolveStoredTools(storedTools) {
+    if (!storedTools || storedTools.length === 0) {
+      return {};
+    }
+    if (!this.mastra) {
+      return {};
+    }
+    const resolvedTools = {};
+    for (const toolKey of storedTools) {
+      try {
+        const tool = this.mastra.getToolById(toolKey);
+        resolvedTools[toolKey] = tool;
+      } catch {
+        this.logger?.warn(`Tool "${toolKey}" referenced in stored agent but not registered in Mastra`);
+      }
+    }
+    return resolvedTools;
+  }
+  /**
+   * Resolve stored workflow IDs to actual workflow instances from Mastra's registry.
+   */
+  resolveStoredWorkflows(storedWorkflows) {
+    if (!storedWorkflows || storedWorkflows.length === 0) {
+      return {};
+    }
+    if (!this.mastra) {
+      return {};
+    }
+    const resolvedWorkflows = {};
+    for (const workflowKey of storedWorkflows) {
+      try {
+        const workflow = this.mastra.getWorkflow(workflowKey);
+        resolvedWorkflows[workflowKey] = workflow;
+      } catch {
+        try {
+          const workflow = this.mastra.getWorkflowById(workflowKey);
+          resolvedWorkflows[workflowKey] = workflow;
+        } catch {
+          this.logger?.warn(`Workflow "${workflowKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return resolvedWorkflows;
+  }
+  /**
+   * Resolve stored agent IDs to actual agent instances from Mastra's registry.
+   */
+  resolveStoredAgents(storedAgents) {
+    if (!storedAgents || storedAgents.length === 0) {
+      return {};
+    }
+    if (!this.mastra) {
+      return {};
+    }
+    const resolvedAgents = {};
+    for (const agentKey of storedAgents) {
+      try {
+        const agent = this.mastra.getAgent(agentKey);
+        resolvedAgents[agentKey] = agent;
+      } catch {
+        try {
+          const agent = this.mastra.getAgentById(agentKey);
+          resolvedAgents[agentKey] = agent;
+        } catch {
+          this.logger?.warn(`Agent "${agentKey}" referenced in stored agent but not registered in Mastra`);
+        }
+      }
+    }
+    return resolvedAgents;
+  }
+  /**
+   * Resolve stored memory config to a MastraMemory instance.
+   * Uses @mastra/memory Memory class to instantiate from serialized config.
+   */
+  resolveStoredMemory(memoryConfig) {
+    this.logger?.debug(`[resolveStoredMemory] Called with config:`, { memoryConfig });
+    if (!memoryConfig) {
+      this.logger?.debug(`[resolveStoredMemory] No memory config provided`);
+      return void 0;
+    }
+    if (!this.mastra) {
+      this.logger?.warn("MastraEditor not registered with Mastra instance. Cannot instantiate memory.");
+      return void 0;
+    }
+    try {
+      let vector;
+      if (memoryConfig.vector) {
+        const vectors = this.mastra.listVectors();
+        vector = vectors?.[memoryConfig.vector];
+        if (!vector) {
+          this.logger?.warn(`Vector provider "${memoryConfig.vector}" not found in Mastra instance`);
+        }
+      }
+      const sharedConfig = {
+        storage: this.mastra.getStorage(),
+        vector,
+        options: memoryConfig.options,
+        embedder: memoryConfig.embedder,
+        embedderOptions: memoryConfig.embedderOptions
+      };
+      return new Memory(sharedConfig);
+    } catch (error) {
+      this.logger?.error("Failed to resolve memory from config", { error });
+      return void 0;
+    }
+  }
+  /**
+   * Resolve stored scorer configs to MastraScorers instances.
+   */
+  resolveStoredScorers(storedScorers) {
+    if (!storedScorers || Object.keys(storedScorers).length === 0) {
+      return void 0;
+    }
+    if (!this.mastra) {
+      return void 0;
+    }
+    const resolvedScorers = {};
+    for (const [scorerKey, scorerConfig] of Object.entries(storedScorers)) {
+      try {
+        const scorer = this.mastra.getScorer(scorerKey);
+        resolvedScorers[scorerKey] = {
+          scorer,
+          sampling: scorerConfig.sampling
+        };
+      } catch {
+        try {
+          const scorer = this.mastra.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;
+  }
+  /**
+   * Look up a processor by key or ID from Mastra's registry.
+   */
+  findProcessor(processorKey) {
+    if (!this.mastra) return void 0;
+    try {
+      return this.mastra.getProcessor(processorKey);
+    } catch {
+      try {
+        return this.mastra.getProcessorById(processorKey);
+      } catch {
+        this.logger?.warn(`Processor "${processorKey}" referenced in stored agent but not registered in Mastra`);
+        return void 0;
+      }
+    }
+  }
+  /**
+   * Resolve stored input processor keys to actual processor instances.
+   */
+  resolveStoredInputProcessors(storedProcessors) {
+    if (!storedProcessors || storedProcessors.length === 0) return void 0;
+    const resolved = [];
+    for (const key of storedProcessors) {
+      const processor = this.findProcessor(key);
+      if (processor && (processor.processInput || processor.processInputStep)) {
+        resolved.push(processor);
+      }
+    }
+    return resolved.length > 0 ? resolved : void 0;
+  }
+  /**
+   * Resolve stored output processor keys to actual processor instances.
+   */
+  resolveStoredOutputProcessors(storedProcessors) {
+    if (!storedProcessors || storedProcessors.length === 0) return void 0;
+    const resolved = [];
+    for (const key of storedProcessors) {
+      const processor = this.findProcessor(key);
+      if (processor && (processor.processOutputStream || processor.processOutputResult || processor.processOutputStep)) {
+        resolved.push(processor);
+      }
+    }
+    return resolved.length > 0 ? resolved : void 0;
+  }
+};
+export {
+  MastraEditor
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mastra/editor",
+  "version": "0.0.0-om-20260204032032",
+  "description": "Mastra Editor for agent management and instantiation",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mastra-ai/mastra.git",
+    "directory": "packages/editor"
+  },
+  "homepage": "https://mastra.ai",
+  "bugs": {
+    "url": "https://github.com/mastra-ai/mastra/issues"
+  },
+  "dependencies": {
+    "@mastra/memory": "0.0.0-om-20260204032032"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3",
+    "vitest": "4.0.16",
+    "zod": "^3.25.76",
+    "@internal/ai-sdk-v4": "0.0.0-om-20260204032032",
+    "@internal/ai-sdk-v5": "0.0.0-om-20260204032032",
+    "@internal/ai-v6": "0.0.0-om-20260204032032",
+    "@mastra/core": "0.0.0-om-20260204032032",
+    "@mastra/libsql": "0.0.0-om-20260204032032"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0",
+    "@mastra/core": "0.0.0-om-20260204032032"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "validate:package": "echo 'Validating package.json...'"
+  }
+}