@mastra/editor 0.9.1-alpha.0 → 0.10.0-alpha.2

package/dist/index.cjs

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,6 +30,281 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/ee/agent-builder.ts
+var import_ee, EditorAgentBuilder;
+var init_agent_builder = __esm({
+  "src/ee/agent-builder.ts"() {
+    "use strict";
+    import_ee = require("@mastra/core/agent-builder/ee");
+    EditorAgentBuilder = class {
+      constructor(options) {
+        this.modelPolicyWarnings = [];
+        /** Non-fatal warnings for browser config issues (surfaced alongside model policy warnings). */
+        this.browserConfigWarnings = [];
+        const source = options ?? {};
+        this.options = {
+          ...source,
+          features: source.features ? {
+            ...source.features,
+            agent: source.features.agent ? { ...source.features.agent } : void 0
+          } : void 0
+        };
+        this.validateModelPolicy();
+        this.validateBrowserConfig();
+        this.resolvedFeatures = {
+          agent: (0, import_ee.resolveAgentFeatures)(this.options.features?.agent, {
+            hasBrowserConfig: this.hasValidBrowserConfig()
+          })
+        };
+      }
+      get enabled() {
+        return this.options.enabled !== false;
+      }
+      getFeatures() {
+        return this.resolvedFeatures;
+      }
+      getConfiguration() {
+        return this.options.configuration;
+      }
+      getRegistries() {
+        return this.options.registries;
+      }
+      getModelPolicyWarnings() {
+        return [...this.modelPolicyWarnings, ...this.browserConfigWarnings];
+      }
+      /**
+       * True when `configuration.agent.browser` declares a provider. The
+       * EditorAgentBuilder does NOT verify the provider is registered with the
+       * Mastra instance — that cross-validation lives in `MastraEditor.resolveBuilder`
+       * because only the editor knows the registered browser providers.
+       */
+      hasValidBrowserConfig() {
+        const browserConfig = this.options.configuration?.agent?.browser;
+        return Boolean(browserConfig?.config?.provider);
+      }
+      /**
+       * Browser config validation only runs for **explicit** `browser: true`.
+       * With default-on semantics, an omitted `browser` no longer means "admin
+       * opted in" — it means "admin didn't opt out". The default-on path is
+       * resolved later by `resolveAgentFeatures`, which already gates `browser`
+       * on `hasValidBrowserConfig`. We don't want to spam every default-config
+       * deployment with warnings.
+       */
+      validateBrowserConfig() {
+        const explicitBrowser = this.options.features?.agent?.browser;
+        if (explicitBrowser !== true) return;
+        const browserConfig = this.options.configuration?.agent?.browser;
+        if (!browserConfig) {
+          const warning = 'Agent Builder browser feature is enabled but no default browser config was provided. Set `editor.builder.configuration.agent.browser` to a valid browser config (e.g. `{ type: "inline", config: { provider: "stagehand" } }`). The browser toggle will be hidden until a default is configured.';
+          this.browserConfigWarnings.push(warning);
+          console.warn(`[mastra:editor:builder] ${warning}`);
+          if (this.options.features?.agent) {
+            this.options.features.agent.browser = false;
+          }
+          return;
+        }
+        if (!browserConfig.config?.provider) {
+          const warning = 'Agent Builder browser config is missing a `provider` field. Set `editor.builder.configuration.agent.browser.config.provider` (e.g. `"stagehand"`). The browser toggle will be hidden until a provider is configured.';
+          this.browserConfigWarnings.push(warning);
+          console.warn(`[mastra:editor:builder] ${warning}`);
+          if (this.options.features?.agent) {
+            this.options.features.agent.browser = false;
+          }
+        }
+      }
+      validateModelPolicy() {
+        const enabled = this.options.enabled !== false;
+        const explicitModel = this.options.features?.agent?.model;
+        const pickerVisible = explicitModel !== false;
+        const models = this.options.configuration?.agent?.models;
+        const allowed = models?.allowed;
+        const defaultModel = models?.default;
+        const active = (0, import_ee.isBuilderModelPolicyActive)({
+          enabled,
+          pickerVisible,
+          allowed,
+          default: defaultModel
+        });
+        if (!active) return;
+        if (explicitModel === false && defaultModel === void 0) {
+          throw new Error(
+            "Agent Builder model policy is active in locked mode but no default was set. Set `editor.builder.configuration.agent.models.default`, or remove `editor.builder.features.agent.model = false` to allow end-users to pick a model."
+          );
+        }
+        if (defaultModel !== void 0 && allowed !== void 0 && allowed.length > 0) {
+          if (!(0, import_ee.isModelAllowed)(allowed, defaultModel)) {
+            throw new Error(
+              "Agent Builder default model is not in the allowlist. Either add it to `editor.builder.configuration.agent.models.allowed` or change `editor.builder.configuration.agent.models.default`."
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/ee/agent-builder-agent.ts
+function createBuilderAgent() {
+  const memory = new import_memory2.Memory();
+  return new import_agent3.Agent({
+    id: "builder-agent",
+    name: "Agent Builder Agent",
+    description: "An agent that can build agents",
+    instructions: `You are the Agent Builder.
+
+Your job: turn a non-technical user's plain-language request into a fully configured, production-quality agent in a single turn.
+
+# Non-negotiables
+
+- Never ask the user follow-up questions. Make the most reasonable assumption and move forward.
+- Never expose internal names, tool ids, file paths, schemas, code, or jargon to the user.
+- Speak only in user-facing capability terms.
+- Always finish the build in the same turn as the request \u2014 configure the agent end-to-end and deliver a short summary.
+- Always define the new agent's name, description, model, and system prompt yourself. Do not ask the user for any of these.
+
+Examples of communication style:
+- Bad: "Added weatherTool to agent-yzx capabilities."
+- Good: "Your new agent can now check the weather for you."
+- Bad: "Calling set-agent-tools with [weatherTool]."
+- Good: "Checking what capabilities to bring to your agent\u2026"
+- Bad: "Agent created with weatherTool and recipeWorkflow attached."
+- Good: "Your agent can check the weather and suggest recipes that match the day's conditions."
+
+# Authoring loop
+
+Follow these five steps in order, every time:
+
+## Step A \u2014 Understand the real outcome
+
+Analyze what the user actually wants to achieve. Focus on the final result, not just the literal wording of the request.
+
+Ask yourself:
+- What should the agent help the user accomplish?
+- Who will use this agent?
+- What decisions should the agent make on its own?
+- What kind of output should the agent produce?
+- What recurring tasks, reasoning, or actions does the agent need to perform?
+
+## Step B \u2014 Define the agent's identity
+
+Before building the agent, define:
+- Agent name: short, memorable, anchored to the outcome. Never "Agent X" or generic labels
+- Description: exactly one sentence in plain user-facing language explaining what the agent helps with.
+
+Call \`set-agent-name\` and \`set-agent-description\` to set the agent's identity. Skip any whose feature is not available in the form snapshot.
+
+## Step C \u2014 Decide capabilities
+
+Read the form snapshot already injected into your context. It lists the user's current selections plus the available tools, agents, workflows, stored skills, models, and workspaces.
+
+Then:
+- Pick the *minimum* set of existing tools/agents/workflows/stored skills that satisfies the outcome. Adding irrelevant capabilities makes the agent worse, not better.
+- Prefer existing tools, workflows, agents, and stored skills before creating anything new.
+- \`set-agent-skills\` attaches user-available stored skills from the form snapshot.
+- Only call \`createSkillTool\` when (a) no existing stored skill matches reusable operating instructions the produced agent needs, AND (b) that operating instruction is genuinely needed for the outcome. Do not use stored skills as a substitute for missing integrations or tools.
+- If a specific external connection is required (e.g. a sheet tool for a spreadsheet-driven outcome) and none is available, the new agent's system prompt must instruct it to refuse cleanly and explain what the user needs to connect.
+
+## Step D \u2014 Synthesize the run contract
+
+Before calling \`set-agent-instructions\`, privately write a concrete run contract for the produced agent. The system prompt must instantiate each item:
+
+1. **Trigger / input** \u2014 what user request, schedule, event, file, row, ticket, or message starts a run.
+2. **Owned outcome** \u2014 the exact result the produced agent is responsible for finishing.
+3. **Available capabilities** \u2014 only capabilities actually attached or already available from the form snapshot, described in user-facing outcome terms.
+4. **Missing-capability fallback** \u2014 what the produced agent does when a required integration, workspace, credential, or source is absent.
+5. **Done criteria** \u2014 verifiable conditions that prove the job is finished, including tool confirmation or an explicit "not run" reason when verification is impossible.
+6. **Final response format** \u2014 the receipt, summary, draft, diff summary, report, or confirmation the user receives.
+
+## Step E \u2014 Write the agent
+
+Call the capability tools. Skip any whose feature is not available in the form snapshot.
+
+1. \`set-agent-model\` \u2014 pick the best model for the use case from the available models list. Rules:
+   - Choose only a model id that appears in the available models list. Never invent, assume, or copy example model ids.
+   - For coding, reasoning-heavy, or planning agents, prefer the most capable available model.
+   - For short, simple, structured, or high-volume tasks, prefer a lower-latency/lower-cost available model when quality will not materially suffer.
+   - If several plausible models are available, choose the newest or strongest option based on the metadata visible in the snapshot.
+2. \`set-agent-tools\` \u2014 attach the minimum set chosen in Step C. Also use \`set-agent-skills\` and \`set-agent-browser-enabled\` only when applicable and supported by the snapshot.
+3. \`set-agent-instructions\` \u2014 write the new agent's system prompt from scratch, tailored to the user's specific outcome and the run contract from Step D.
+
+Before calling \`set-agent-instructions\`, self-audit the draft. It must pass every check:
+- No placeholders remain (no \`<...>\`, "TBD", "TODO", "your tool", or generic policy gaps).
+- No internal tool ids, file paths, schemas, or builder-only terms appear.
+- No generic "helpful assistant" identity remains.
+- No unsupported capabilities are promised.
+- Completion criteria are present, concrete, and tool-aware.
+- Refusal / fallback path is present for missing integrations, credentials, permissions, workspace, or sources.
+- Final response format is specified.
+
+## Step F \u2014 Confirm the agent configuration to the user
+
+End your turn with one short, friendly paragraph confirming that the agent has been configured and is ready to use.
+
+Use this shape:
+
+"Your agent, [Agent Name], has been configured with its initial parameters. It can now [plain-language outcome]. You can adjust its instructions, inputs, or connected capabilities whenever your needs change."
+
+Do not mention internal capability names, tools, workflows, skills, or configuration steps.
+
+Good:
+"Your agent, Sales Drop Watcher, has been configured with its initial parameters. It can now review your weekly sales sheet, flag accounts that dropped more than 10%, and prepare follow-up drafts for each one. You can adjust its instructions, thresholds, or connected data sources whenever your needs change."
+
+Bad:
+"Agent created with sheetsTool, scoringWorkflow, and emailSkill attached."
+
+Bad:
+"I configured the sheets integration and called set-agent-instructions."
+
+# Quality bar for the produced agent's system prompt
+
+The system prompt written into \`set-agent-instructions\` MUST include all of the following:
+
+1. **Role and outcome.** Define what the agent is and the concrete result it owns.
+2. **Trigger and input.** Define what starts a run and what input the agent expects.
+3. **Decision rules.** Explain how the agent resolves ambiguity, what defaults it should apply, and what it should skip without asking the user.
+4. **Capability awareness.** Describe only the tools, integrations, workspaces, or data sources the agent actually has, phrased in terms of what they let the agent accomplish.
+5. **Missing-capability fallback.** Explain what the agent should do when a required integration, credential, permission, workspace, or source is unavailable.
+6. **Completion criteria.** Define exactly when the task is done in observable, verifiable terms.
+7. **Final response format.** Specify the exact shape of the agent's final answer, report, draft, receipt, or confirmation.
+8. **Communication style.** Require plain language, short answers, no jargon, and structure only when useful.
+9. **Refusal rules.** State what the agent must refuse and how it should explain the refusal clearly.
+10. **Worked example.** Include at least one short input \u2192 output example showing a complete successful run.
+
+# Hard rules
+
+- If the user's request requires CLI or local-machine actions and no workspace is connected, refuse in plain language and tell the user they need to connect a workspace first.
+- Never reveal that you are calling configuration tools. Describe progress only in terms of the user's intended outcome.
+- Never produce a system prompt without explicit completion criteria.
+- Never attach a capability "just in case." Every tool, agent, workflow, or skill must directly support the requested outcome.
+- The final message to the user must be concise, friendly, and focused on what the configured agent can now do.
+- The final message should make clear that the agent starts with initial parameters and can be adjusted later.`,
+    model: "openai/gpt-5.5",
+    memory
+  });
+}
+var import_agent3, import_memory2;
+var init_agent_builder_agent = __esm({
+  "src/ee/agent-builder-agent.ts"() {
+    "use strict";
+    import_agent3 = require("@mastra/core/agent");
+    import_memory2 = require("@mastra/memory");
+  }
+});
+
+// src/ee/index.ts
+var ee_exports = {};
+__export(ee_exports, {
+  EditorAgentBuilder: () => EditorAgentBuilder,
+  createBuilderAgent: () => createBuilderAgent
+});
+var init_ee = __esm({
+  "src/ee/index.ts"() {
+    "use strict";
+    init_agent_builder();
+    init_agent_builder_agent();
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -567,6 +845,36 @@ var EditorMCPNamespace = class _EditorMCPNamespace extends CrudEditorNamespace {
 };
 
 // src/namespaces/agent.ts
+var BUILDER_DEFAULT_FIELDS = ["memory", "workspace", "browser"];
+function defaultModelToStored(entry) {
+  return { provider: entry.provider, name: entry.modelId };
+}
+var BUILDER_BASELINE_DEFAULTS = {
+  memory: { observationalMemory: true }
+};
+function applyBuilderDefaults(input, builderAgentConfig) {
+  const defaults = {};
+  for (const field of BUILDER_DEFAULT_FIELDS) {
+    if (input[field] !== void 0) continue;
+    const adminValue = builderAgentConfig?.[field];
+    if (adminValue !== void 0) {
+      defaults[field] = adminValue;
+      continue;
+    }
+    const baseline = BUILDER_BASELINE_DEFAULTS[field];
+    if (baseline !== void 0) {
+      defaults[field] = baseline;
+    }
+  }
+  if (input.model === void 0 && builderAgentConfig) {
+    const models = builderAgentConfig.models ?? void 0;
+    const adminDefault = models?.default;
+    if (adminDefault && typeof adminDefault.provider === "string" && typeof adminDefault.modelId === "string") {
+      defaults.model = defaultModelToStored(adminDefault);
+    }
+  }
+  return Object.keys(defaults).length > 0 ? { ...input, ...defaults } : input;
+}
 var EditorAgentNamespace = class extends CrudEditorNamespace {
   async getStorageAdapter() {
     const storage = this.mastra?.getStorage();
@@ -609,6 +917,67 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
   async hydrate(storedAgent) {
     return this.createAgentFromStoredConfig(storedAgent);
   }
+  /**
+   * Create a new agent, applying builder defaults for fields not specified in input.
+   * Also ensures the referenced workspace (if any) is persisted as a stored workspace.
+   */
+  async create(input) {
+    let finalInput = input;
+    if (this.editor.hasEnabledBuilderConfig()) {
+      const builder = await this.editor.resolveBuilder();
+      const agentConfig = builder?.getConfiguration()?.agent;
+      finalInput = applyBuilderDefaults(input, agentConfig);
+    }
+    await this.ensureStoredWorkspace(finalInput.workspace);
+    return super.create(finalInput);
+  }
+  /**
+   * Ensure a workspace reference is persisted in the DB.
+   *
+   * For `type: 'id'`: looks up the runtime workspace, serializes its config,
+   * and creates a stored workspace record if one doesn't already exist.
+   *
+   * For `type: 'inline'`: derives a deterministic ID from the config and
+   * persists it as a stored workspace if one doesn't already exist.
+   */
+  async ensureStoredWorkspace(workspaceRef) {
+    if (!workspaceRef) return;
+    const workspaceNs = this.editor.workspace;
+    if (!workspaceNs) return;
+    try {
+      if (workspaceRef.type === "id") {
+        const existing = await workspaceNs.getById(workspaceRef.workspaceId);
+        if (existing) return;
+        const runtimeWorkspace = this.mastra?.getWorkspaceById(workspaceRef.workspaceId);
+        if (!runtimeWorkspace) {
+          this.logger?.warn(
+            `[ensureStoredWorkspace] Workspace '${workspaceRef.workspaceId}' not found in runtime registry, cannot persist`
+          );
+          return;
+        }
+        const snapshot = await workspaceNs.snapshotFromWorkspace(runtimeWorkspace);
+        await workspaceNs.create({
+          id: workspaceRef.workspaceId,
+          metadata: { source: "builder", builderWorkspaceId: workspaceRef.workspaceId },
+          ...snapshot
+        });
+        this.logger?.debug(`[ensureStoredWorkspace] Persisted runtime workspace '${workspaceRef.workspaceId}' to DB`);
+      } else if (workspaceRef.type === "inline") {
+        const configHash = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(workspaceRef.config)).digest("hex").slice(0, 12);
+        const workspaceId = `inline-${configHash}`;
+        const existing = await workspaceNs.getById(workspaceId);
+        if (existing) return;
+        await workspaceNs.create({
+          id: workspaceId,
+          metadata: { source: "builder", builderConfigHash: configHash },
+          ...workspaceRef.config
+        });
+        this.logger?.debug(`[ensureStoredWorkspace] Persisted inline workspace '${workspaceId}' to DB`);
+      }
+    } catch (error) {
+      this.logger?.warn("[ensureStoredWorkspace] Failed to persist workspace", { error });
+    }
+  }
   onCacheEvict(id) {
     try {
       const existing = this.mastra?.getAgentById(id);
@@ -798,6 +1167,7 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
     const hasConditionalDefaultOptions = storedAgent.defaultOptions != null && this.isConditionalVariants(storedAgent.defaultOptions);
     const hasConditionalModel = this.isConditionalVariants(storedAgent.model);
     const hasConditionalWorkspace = storedAgent.workspace != null && this.isConditionalVariants(storedAgent.workspace);
+    const hasConditionalBrowser = storedAgent.browser != null && this.isConditionalVariants(storedAgent.browser);
     const hasIntegrationTools = storedAgent.integrationTools != null;
     const isDynamicTools = hasConditionalTools || hasConditionalMCPClients || hasConditionalIntegrationTools || hasIntegrationTools;
     let tools;
@@ -964,6 +1334,14 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
       );
       return this.resolveStoredWorkspace(resolvedRef, skillSource);
     } : await this.resolveStoredWorkspace(storedAgent.workspace, skillSource);
+    const browser = hasConditionalBrowser ? async ({ requestContext }) => {
+      const ctx = requestContext.toJSON();
+      const resolvedRef = this.accumulateObjectVariants(
+        storedAgent.browser,
+        ctx
+      );
+      return this.resolveStoredBrowser(resolvedRef);
+    } : await this.resolveStoredBrowser(storedAgent.browser);
     const skillsFormat = storedAgent.skillsFormat;
     const agent = new import_agent.Agent({
       id: storedAgent.id,
@@ -984,6 +1362,7 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
       defaultOptions,
       requestContextSchema,
       workspace,
+      browser,
       ...skillsFormat && { skillsFormat }
     });
     const existingCodeAgent = (() => {
@@ -1382,7 +1761,8 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
       scorers: storedScorers,
       defaultOptions: storageDefaultOptions,
       metadata: resolvedMetadata,
-      authorId: options.authorId
+      authorId: options.authorId,
+      visibility: options.visibility
     };
     const adapter = await this.getStorageAdapter();
     await adapter.create(createInput);
@@ -1414,13 +1794,23 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
     const hydrateOptions = skillSource ? { skillSource } : void 0;
     if (workspaceRef.type === "id") {
       const resolved = await workspaceNs.getById(workspaceRef.workspaceId);
-      if (!resolved) {
-        this.logger?.warn(
-          `[resolveStoredWorkspace] Workspace '${workspaceRef.workspaceId}' not found in storage, skipping`
-        );
-        return void 0;
+      if (resolved) {
+        return workspaceNs.hydrateSnapshotToWorkspace(workspaceRef.workspaceId, resolved, hydrateOptions);
+      }
+      try {
+        const runtimeWorkspace = this.mastra?.getWorkspaceById(workspaceRef.workspaceId);
+        if (runtimeWorkspace) {
+          this.logger?.debug(
+            `[resolveStoredWorkspace] Workspace '${workspaceRef.workspaceId}' found in runtime registry (not in DB)`
+          );
+          return runtimeWorkspace;
+        }
+      } catch {
       }
-      return workspaceNs.hydrateSnapshotToWorkspace(workspaceRef.workspaceId, resolved, hydrateOptions);
+      this.logger?.warn(
+        `[resolveStoredWorkspace] Workspace '${workspaceRef.workspaceId}' not found in storage or runtime registry, skipping`
+      );
+      return void 0;
     }
     if (workspaceRef.type === "inline") {
       const configHash = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(workspaceRef.config)).digest("hex").slice(0, 12);
@@ -1428,6 +1818,26 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
     }
     return void 0;
   }
+  /**
+   * Resolve a stored browser config to a runtime MastraBrowser instance.
+   * Looks up the provider by ID in the editor's browser registry.
+   * Only supports `type: 'inline'` refs (config is embedded in the agent snapshot).
+   */
+  async resolveStoredBrowser(browserRef) {
+    if (!browserRef) return void 0;
+    if (browserRef.type === "inline") {
+      const { provider: providerId, ...config } = browserRef.config;
+      const browserProvider = this.editor.__browsers.get(providerId);
+      if (!browserProvider) {
+        this.logger?.warn(
+          `[resolveStoredBrowser] Browser provider "${providerId}" is not registered. Register it via new MastraEditor({ browsers: { '${providerId}': yourProvider } })`
+        );
+        return void 0;
+      }
+      return await browserProvider.createBrowser(config);
+    }
+    return void 0;
+  }
   /**
    * Resolve agent-level skill configurations into a CompositeVersionedSkillSource.
    *
@@ -2063,9 +2473,35 @@ var localSandboxProvider = {
   createSandbox: (config) => new import_workspace6.LocalSandbox(config)
 };
 
+// src/snapshots-match.ts
+function snapshotsMatch(stored, runtime) {
+  const keys = [
+    "name",
+    "description",
+    "filesystem",
+    "sandbox",
+    "mounts",
+    "search",
+    "skills",
+    "tools",
+    "autoSync",
+    "operationTimeout"
+  ];
+  const replacer = (_k, v) => v === false || v === null || v === 0 ? void 0 : v;
+  for (const key of keys) {
+    const storedVal = stored[key];
+    const runtimeVal = runtime[key];
+    const storedJSON = storedVal == null || storedVal === false ? void 0 : JSON.stringify(storedVal, replacer);
+    const runtimeJSON = runtimeVal == null || runtimeVal === false ? void 0 : JSON.stringify(runtimeVal, replacer);
+    if (storedJSON !== runtimeJSON) return false;
+  }
+  return true;
+}
+
 // src/index.ts
 var MastraEditor = class {
   constructor(config) {
+    this.__builderResolved = false;
     this.__logger = config?.logger;
     this.__toolProviders = config?.toolProviders ?? {};
     this.__processorProviders = { ...import_processor_provider2.BUILT_IN_PROCESSOR_PROVIDERS, ...config?.processorProviders };
@@ -2083,6 +2519,10 @@ var MastraEditor = class {
     for (const [id, provider] of Object.entries(config?.blobStores ?? {})) {
       this.__blobStores.set(id, provider);
     }
+    this.__browsers = /* @__PURE__ */ new Map();
+    for (const [id, provider] of Object.entries(config?.browsers ?? {})) {
+      this.__browsers.set(id, provider);
+    }
     this.agent = new EditorAgentNamespace(this);
     this.mcp = new EditorMCPNamespace(this);
     this.mcpServer = new EditorMCPServerNamespace(this);
@@ -2091,6 +2531,7 @@ var MastraEditor = class {
     this.workspace = new EditorWorkspaceNamespace(this);
     this.skill = new EditorSkillNamespace(this);
     this.favorites = new EditorFavoritesNamespace(this);
+    this.__builderConfig = config?.builder;
   }
   /**
    * Register this editor with a Mastra instance.
@@ -2101,11 +2542,171 @@ var MastraEditor = class {
     if (!this.__logger) {
       this.__logger = mastra.getLogger();
     }
+    this.ensureBuilderWorkspaces().then(() => this.reconcileBuilderWorkspaces()).catch((err) => {
+      this.__logger?.warn("[MastraEditor] Failed to persist/reconcile builder workspaces on startup", {
+        error: err
+      });
+    });
+  }
+  /**
+   * Ensure the builder default workspace is persisted to the DB.
+   * Called automatically on startup when the editor registers with Mastra.
+   * Goes through the normal create() path so hydration validates that
+   * all providers (filesystem, sandbox) are properly registered.
+   *
+   * If the workspace already exists but its config has drifted from the
+   * runtime workspace, the DB record is updated (creating a new version).
+   * Builder-created workspaces are tagged with `metadata.source = 'builder'`
+   * so they can be identified during reconciliation.
+   */
+  async ensureBuilderWorkspaces() {
+    if (!this.hasEnabledBuilderConfig()) return;
+    const builder = await this.resolveBuilder();
+    const agentConfig = builder?.getConfiguration()?.agent;
+    const workspaceRef = agentConfig?.workspace;
+    if (!workspaceRef || workspaceRef.type !== "id" || !workspaceRef.workspaceId) return;
+    const runtimeWorkspace = this.__mastra?.getWorkspaceById(workspaceRef.workspaceId);
+    if (!runtimeWorkspace) return;
+    const snapshot = await this.workspace.snapshotFromWorkspace(runtimeWorkspace);
+    const builderMetadata = { source: "builder", builderWorkspaceId: workspaceRef.workspaceId };
+    const existing = await this.workspace.getById(workspaceRef.workspaceId);
+    if (!existing) {
+      await this.workspace.create({
+        id: workspaceRef.workspaceId,
+        metadata: builderMetadata,
+        ...snapshot
+      });
+      this.__logger?.info(`[MastraEditor] Persisted builder workspace '${workspaceRef.workspaceId}' to DB`);
+      return;
+    }
+    const needsMetadataBackfill = !existing.metadata?.source;
+    const configDrifted = !snapshotsMatch(existing, snapshot);
+    if (needsMetadataBackfill || configDrifted) {
+      const updateInput = { id: workspaceRef.workspaceId };
+      if (needsMetadataBackfill) {
+        updateInput.metadata = { ...existing.metadata, ...builderMetadata };
+      }
+      if (configDrifted) {
+        Object.assign(updateInput, snapshot);
+        this.__logger?.info(
+          `[MastraEditor] Workspace '${workspaceRef.workspaceId}' config drifted \u2014 updating DB record`
+        );
+      }
+      await this.workspace.update(updateInput);
+    }
+  }
+  /**
+   * Archive builder-created workspaces that no longer match the current
+   * builder configuration. Called after `ensureBuilderWorkspaces()` on startup.
+   *
+   * Only touches workspaces tagged with `metadata.source === 'builder'`.
+   * The current builder workspace (if any) is never archived.
+   */
+  async reconcileBuilderWorkspaces() {
+    if (!this.hasEnabledBuilderConfig()) return;
+    const builder = await this.resolveBuilder();
+    const agentConfig = builder?.getConfiguration()?.agent;
+    const workspaceRef = agentConfig?.workspace;
+    let currentWorkspaceId;
+    if (workspaceRef?.type === "id" && workspaceRef.workspaceId) {
+      currentWorkspaceId = workspaceRef.workspaceId;
+    }
+    if (!currentWorkspaceId) return;
+    const { workspaces: allWorkspaces } = await this.workspace.listResolved({
+      perPage: false,
+      // fetch all
+      metadata: { source: "builder" }
+    });
+    for (const ws of allWorkspaces) {
+      if (ws.id === currentWorkspaceId) continue;
+      if (ws.status === "archived") continue;
+      try {
+        await this.workspace.update({ id: ws.id, status: "archived" });
+        this.__logger?.info(`[MastraEditor] Archived orphaned builder workspace '${ws.id}'`);
+      } catch (err) {
+        this.__logger?.warn(`[MastraEditor] Failed to archive workspace '${ws.id}'`, { error: err });
+      }
+    }
+  }
+  /**
+   * Sync. OSS-safe. Does NOT import @mastra/editor/ee.
+   * Returns true if builder config is present and enabled.
+   */
+  hasEnabledBuilderConfig() {
+    if (!this.__builderConfig) return false;
+    return this.__builderConfig.enabled !== false;
+  }
+  /**
+   * Async. Dynamic-imports @mastra/editor/ee on first call. Caches result.
+   * Returns undefined if builder is not enabled.
+   */
+  async resolveBuilder() {
+    if (this.__builderResolved) {
+      return this.__builderInstance;
+    }
+    if (!this.hasEnabledBuilderConfig()) {
+      this.__builderResolved = true;
+      return void 0;
+    }
+    await this.assertAgentBuilderLicensed();
+    const { EditorAgentBuilder: EditorAgentBuilder2 } = await Promise.resolve().then(() => (init_ee(), ee_exports));
+    this.__builderInstance = new EditorAgentBuilder2(this.__builderConfig);
+    const browserRef = this.__builderInstance.getConfiguration()?.agent?.browser;
+    const browserFeatureOn = this.__builderInstance.getFeatures()?.agent?.browser === true;
+    if (browserFeatureOn && browserRef?.config?.provider) {
+      const providerId = browserRef.config.provider;
+      if (!this.__browsers.has(providerId)) {
+        const warning = `Agent Builder browser config references provider "${providerId}" but no matching browser provider is registered in \`editor.browsers\`. The browser toggle will be hidden. Register the provider: \`new MastraEditor({ browsers: { "${providerId}": yourProvider } })\`.`;
+        console.warn(`[mastra:editor] ${warning}`);
+        const features = this.__builderInstance.getFeatures()?.agent;
+        if (features) {
+          features.browser = false;
+        }
+      }
+    }
+    this.__builderResolved = true;
+    return this.__builderInstance;
+  }
+  /**
+   * Defense-in-depth license guard for the Agent Builder. Mirrors the
+   * startup-time check in `MastraServer.validateAgentBuilderLicense()` so the
+   * builder cannot be instantiated outside the server boot path without a
+   * valid EE license. Dev environments bypass via `isEEEnabled()`.
+   */
+  async assertAgentBuilderLicensed() {
+    try {
+      const { isEEEnabled } = await import("@mastra/core/auth/ee");
+      if (!isEEEnabled()) {
+        throw new Error(
+          "[mastra/auth-ee] Agent Builder is configured but no valid EE license was found.\nAgent Builder requires a Mastra Enterprise License for production use.\nSet the MASTRA_EE_LICENSE environment variable with your license key.\nLearn more: https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE"
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("[mastra/auth-ee]")) {
+        throw err;
+      }
+      throw new Error(
+        "[mastra/auth-ee] Agent Builder is configured but the EE module (@mastra/core/auth/ee) could not be loaded.\nEnsure @mastra/core is updated to a version that includes EE support."
+      );
+    }
   }
   /** Registered tool providers */
   getToolProvider(id) {
     return this.__toolProviders[id];
   }
+  /**
+   * Like {@link getToolProvider}, but throws {@link UnknownToolProviderError}
+   * when the id is unknown.
+   */
+  getToolProviderOrThrow(id) {
+    const provider = this.__toolProviders[id];
+    if (!provider) {
+      throw new Error(
+        `Unknown tool provider "${id}". Available: ${Object.keys(this.__toolProviders).join(", ") || "(none)"}`
+      );
+    }
+    return provider;
+  }
   /** List all registered tool providers */
   getToolProviders() {
     return this.__toolProviders;
@@ -2178,3 +2779,4 @@ var MastraEditor = class {
   renderTemplate,
   resolveInstructionBlocks
 });
+//# sourceMappingURL=index.cjs.map