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

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { Mastra } from '@mastra/core';
-import { GetByIdOptions, IEditorFavoritesNamespace, EditorFavoriteTargetInput, EditorFavoriteToggleResult, EditorIsFavoritedBatchInput, EditorListFavoritedIdsInput, FilesystemProvider, SandboxProvider, IMastraEditor, BlobStoreProvider, MastraEditorConfig } from '@mastra/core/editor';
-export { MastraEditorConfig } from '@mastra/core/editor';
+import { IAgentBuilder } from '@mastra/core/agent-builder/ee';
+import { GetByIdOptions, IEditorFavoritesNamespace, EditorFavoriteTargetInput, EditorFavoriteToggleResult, EditorIsFavoritedBatchInput, EditorListFavoritedIdsInput, FilesystemProvider, SandboxProvider, IMastraEditor, BlobStoreProvider, BrowserProvider, MastraEditorConfig } from '@mastra/core/editor';
+export { BrowserProvider, MastraEditorConfig } from '@mastra/core/editor';
 import { IMastraLogger } from '@mastra/core/logger';
 import { ProcessorProvider } from '@mastra/core/processor-provider';
 import { StorageCreateAgentInput, StorageUpdateAgentInput, StorageListAgentsInput, StorageListAgentsOutput, StorageListAgentsResolvedOutput, StorageResolvedAgentType, StorageCreateMCPClientInput, StorageUpdateMCPClientInput, StorageListMCPClientsInput, StorageListMCPClientsOutput, StorageListMCPClientsResolvedOutput, StorageResolvedMCPClientType, StorageMCPServerConfig, StorageCreateMCPServerInput, StorageUpdateMCPServerInput, StorageListMCPServersInput, StorageListMCPServersOutput, StorageListMCPServersResolvedOutput, StorageResolvedMCPServerType, StorageCreatePromptBlockInput, StorageUpdatePromptBlockInput, StorageListPromptBlocksInput, StorageListPromptBlocksOutput, StorageListPromptBlocksResolvedOutput, StorageResolvedPromptBlockType, AgentInstructionBlock, StorageCreateScorerDefinitionInput, StorageUpdateScorerDefinitionInput, StorageListScorerDefinitionsInput, StorageListScorerDefinitionsOutput, StorageListScorerDefinitionsResolvedOutput, StorageResolvedScorerDefinitionType, StorageCreateWorkspaceInput, StorageUpdateWorkspaceInput, StorageListWorkspacesInput, StorageListWorkspacesOutput, StorageListWorkspacesResolvedOutput, StorageResolvedWorkspaceType, StorageWorkspaceSnapshotType, StorageCreateSkillInput, StorageUpdateSkillInput, StorageListSkillsInput, StorageListSkillsOutput, StorageListSkillsResolvedOutput, StorageResolvedSkillType, RuleGroup, PromptBlocksStorage, BlobStore } from '@mastra/core/storage';
@@ -95,6 +96,21 @@ declare class EditorAgentNamespace extends CrudEditorNamespace<StorageCreateAgen
      * Hydrate a stored agent config into a runtime Agent instance.
      */
     protected hydrate(storedAgent: StorageResolvedAgentType): Promise<Agent>;
+    /**
+     * 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.
+     */
+    create(input: StorageCreateAgentInput): Promise<Agent>;
+    /**
+     * 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.
+     */
+    private ensureStoredWorkspace;
     protected onCacheEvict(id: string): void;
     /**
      * Evict all cached agents that reference a given skill ID.
@@ -181,6 +197,7 @@ declare class EditorAgentNamespace extends CrudEditorNamespace<StorageCreateAgen
         newName?: string;
         metadata?: Record<string, unknown>;
         authorId?: string;
+        visibility?: 'private' | 'public';
         requestContext?: RequestContext;
     }): Promise<StorageResolvedAgentType>;
     /**
@@ -193,6 +210,12 @@ declare class EditorAgentNamespace extends CrudEditorNamespace<StorageCreateAgen
      * instead of filesystem-based discovery.
      */
     private resolveStoredWorkspace;
+    /**
+     * 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).
+     */
+    private resolveStoredBrowser;
     /**
      * Resolve agent-level skill configurations into a CompositeVersionedSkillSource.
      *
@@ -419,6 +442,9 @@ declare class MastraEditor implements IMastraEditor {
     __logger?: IMastraLogger;
     private __toolProviders;
     private __processorProviders;
+    private readonly __builderConfig?;
+    private __builderInstance?;
+    private __builderResolved;
     /**
      * @internal — exposed for namespace classes to hydrate stored workspace configs.
      * Maps provider ID (e.g., 'local', 's3') to the provider descriptor.
@@ -438,6 +464,12 @@ declare class MastraEditor implements IMastraEditor {
      * Additional providers come from config.
      */
     readonly __blobStores: Map<string, BlobStoreProvider>;
+    /**
+     * @internal — exposed for namespace classes to hydrate stored browser configs.
+     * Maps provider ID (e.g., 'stagehand', 'agent-browser') to the provider descriptor.
+     * No built-in providers — browser packages must be registered via config.
+     */
+    readonly __browsers: Map<string, BrowserProvider>;
     readonly agent: EditorAgentNamespace;
     readonly mcp: EditorMCPNamespace;
     readonly mcpServer: EditorMCPServerNamespace;
@@ -452,8 +484,50 @@ declare class MastraEditor implements IMastraEditor {
      * This gives the editor access to Mastra's storage, tools, workflows, etc.
      */
     registerWithMastra(mastra: Mastra): void;
+    /**
+     * 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.
+     */
+    private ensureBuilderWorkspaces;
+    /**
+     * 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.
+     */
+    private reconcileBuilderWorkspaces;
+    /**
+     * Sync. OSS-safe. Does NOT import @mastra/editor/ee.
+     * Returns true if builder config is present and enabled.
+     */
+    hasEnabledBuilderConfig(): boolean;
+    /**
+     * Async. Dynamic-imports @mastra/editor/ee on first call. Caches result.
+     * Returns undefined if builder is not enabled.
+     */
+    resolveBuilder(): Promise<IAgentBuilder | undefined>;
+    /**
+     * 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()`.
+     */
+    private assertAgentBuilderLicensed;
     /** Registered tool providers */
     getToolProvider(id: string): ToolProvider | undefined;
+    /**
+     * Like {@link getToolProvider}, but throws {@link UnknownToolProviderError}
+     * when the id is unknown.
+     */
+    getToolProviderOrThrow(id: string): ToolProvider;
     /** List all registered tool providers */
     getToolProviders(): Record<string, ToolProvider>;
     /** Get a processor provider by ID */

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Mastra } from '@mastra/core';
-import { GetByIdOptions, IEditorFavoritesNamespace, EditorFavoriteTargetInput, EditorFavoriteToggleResult, EditorIsFavoritedBatchInput, EditorListFavoritedIdsInput, FilesystemProvider, SandboxProvider, IMastraEditor, BlobStoreProvider, MastraEditorConfig } from '@mastra/core/editor';
-export { MastraEditorConfig } from '@mastra/core/editor';
+import { IAgentBuilder } from '@mastra/core/agent-builder/ee';
+import { GetByIdOptions, IEditorFavoritesNamespace, EditorFavoriteTargetInput, EditorFavoriteToggleResult, EditorIsFavoritedBatchInput, EditorListFavoritedIdsInput, FilesystemProvider, SandboxProvider, IMastraEditor, BlobStoreProvider, BrowserProvider, MastraEditorConfig } from '@mastra/core/editor';
+export { BrowserProvider, MastraEditorConfig } from '@mastra/core/editor';
 import { IMastraLogger } from '@mastra/core/logger';
 import { ProcessorProvider } from '@mastra/core/processor-provider';
 import { StorageCreateAgentInput, StorageUpdateAgentInput, StorageListAgentsInput, StorageListAgentsOutput, StorageListAgentsResolvedOutput, StorageResolvedAgentType, StorageCreateMCPClientInput, StorageUpdateMCPClientInput, StorageListMCPClientsInput, StorageListMCPClientsOutput, StorageListMCPClientsResolvedOutput, StorageResolvedMCPClientType, StorageMCPServerConfig, StorageCreateMCPServerInput, StorageUpdateMCPServerInput, StorageListMCPServersInput, StorageListMCPServersOutput, StorageListMCPServersResolvedOutput, StorageResolvedMCPServerType, StorageCreatePromptBlockInput, StorageUpdatePromptBlockInput, StorageListPromptBlocksInput, StorageListPromptBlocksOutput, StorageListPromptBlocksResolvedOutput, StorageResolvedPromptBlockType, AgentInstructionBlock, StorageCreateScorerDefinitionInput, StorageUpdateScorerDefinitionInput, StorageListScorerDefinitionsInput, StorageListScorerDefinitionsOutput, StorageListScorerDefinitionsResolvedOutput, StorageResolvedScorerDefinitionType, StorageCreateWorkspaceInput, StorageUpdateWorkspaceInput, StorageListWorkspacesInput, StorageListWorkspacesOutput, StorageListWorkspacesResolvedOutput, StorageResolvedWorkspaceType, StorageWorkspaceSnapshotType, StorageCreateSkillInput, StorageUpdateSkillInput, StorageListSkillsInput, StorageListSkillsOutput, StorageListSkillsResolvedOutput, StorageResolvedSkillType, RuleGroup, PromptBlocksStorage, BlobStore } from '@mastra/core/storage';
@@ -95,6 +96,21 @@ declare class EditorAgentNamespace extends CrudEditorNamespace<StorageCreateAgen
      * Hydrate a stored agent config into a runtime Agent instance.
      */
     protected hydrate(storedAgent: StorageResolvedAgentType): Promise<Agent>;
+    /**
+     * 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.
+     */
+    create(input: StorageCreateAgentInput): Promise<Agent>;
+    /**
+     * 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.
+     */
+    private ensureStoredWorkspace;
     protected onCacheEvict(id: string): void;
     /**
      * Evict all cached agents that reference a given skill ID.
@@ -181,6 +197,7 @@ declare class EditorAgentNamespace extends CrudEditorNamespace<StorageCreateAgen
         newName?: string;
         metadata?: Record<string, unknown>;
         authorId?: string;
+        visibility?: 'private' | 'public';
         requestContext?: RequestContext;
     }): Promise<StorageResolvedAgentType>;
     /**
@@ -193,6 +210,12 @@ declare class EditorAgentNamespace extends CrudEditorNamespace<StorageCreateAgen
      * instead of filesystem-based discovery.
      */
     private resolveStoredWorkspace;
+    /**
+     * 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).
+     */
+    private resolveStoredBrowser;
     /**
      * Resolve agent-level skill configurations into a CompositeVersionedSkillSource.
      *
@@ -419,6 +442,9 @@ declare class MastraEditor implements IMastraEditor {
     __logger?: IMastraLogger;
     private __toolProviders;
     private __processorProviders;
+    private readonly __builderConfig?;
+    private __builderInstance?;
+    private __builderResolved;
     /**
      * @internal — exposed for namespace classes to hydrate stored workspace configs.
      * Maps provider ID (e.g., 'local', 's3') to the provider descriptor.
@@ -438,6 +464,12 @@ declare class MastraEditor implements IMastraEditor {
      * Additional providers come from config.
      */
     readonly __blobStores: Map<string, BlobStoreProvider>;
+    /**
+     * @internal — exposed for namespace classes to hydrate stored browser configs.
+     * Maps provider ID (e.g., 'stagehand', 'agent-browser') to the provider descriptor.
+     * No built-in providers — browser packages must be registered via config.
+     */
+    readonly __browsers: Map<string, BrowserProvider>;
     readonly agent: EditorAgentNamespace;
     readonly mcp: EditorMCPNamespace;
     readonly mcpServer: EditorMCPServerNamespace;
@@ -452,8 +484,50 @@ declare class MastraEditor implements IMastraEditor {
      * This gives the editor access to Mastra's storage, tools, workflows, etc.
      */
     registerWithMastra(mastra: Mastra): void;
+    /**
+     * 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.
+     */
+    private ensureBuilderWorkspaces;
+    /**
+     * 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.
+     */
+    private reconcileBuilderWorkspaces;
+    /**
+     * Sync. OSS-safe. Does NOT import @mastra/editor/ee.
+     * Returns true if builder config is present and enabled.
+     */
+    hasEnabledBuilderConfig(): boolean;
+    /**
+     * Async. Dynamic-imports @mastra/editor/ee on first call. Caches result.
+     * Returns undefined if builder is not enabled.
+     */
+    resolveBuilder(): Promise<IAgentBuilder | undefined>;
+    /**
+     * 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()`.
+     */
+    private assertAgentBuilderLicensed;
     /** Registered tool providers */
     getToolProvider(id: string): ToolProvider | undefined;
+    /**
+     * Like {@link getToolProvider}, but throws {@link UnknownToolProviderError}
+     * when the id is unknown.
+     */
+    getToolProviderOrThrow(id: string): ToolProvider;
     /** List all registered tool providers */
     getToolProviders(): Record<string, ToolProvider>;
     /** Get a processor provider by ID */