@mastra/agent-builder 0.0.0-experimental-agent-builder-20250815195917 → 0.0.1-alpha.1

package/integration-tests/CHANGELOG.md

@@ -1,20 +1,9 @@
 # @mastra/agent-builder-integration-tests
 
-## 0.0.0-experimental-agent-builder-20250815195917
+## 0.1.1-alpha.0
 
 ### Patch Changes
 
-- Updated dependencies [8e59433]
-- Updated dependencies [49281f5]
-- Updated dependencies [6faaee5]
-- Updated dependencies [4232b14]
-- Updated dependencies [6720c51]
-- Updated dependencies [2256977]
-- Updated dependencies [c597dc5]
-- Updated dependencies [a722c0b]
-- Updated dependencies [c30bca8]
-- Updated dependencies [7444737]
-- Updated dependencies [83d180b]
-- Updated dependencies [3b5fec7]
-  - @mastra/core@0.0.0-experimental-agent-builder-20250815195917
-  - @mastra/agent-builder@0.0.0-experimental-agent-builder-20250815195917
+- Updated dependencies [[`aedbbfa`](https://github.com/mastra-ai/mastra/commit/aedbbfa064124ddde039111f12629daebfea7e48), [`f643c65`](https://github.com/mastra-ai/mastra/commit/f643c651bdaf57c2343cf9dbfc499010495701fb), [`fef7375`](https://github.com/mastra-ai/mastra/commit/fef737534574f41b432a7361a285f776c3bac42b), [`e3d8fea`](https://github.com/mastra-ai/mastra/commit/e3d8feaacfb8b5c5c03c13604cc06ea2873d45fe), [`48b9e55`](https://github.com/mastra-ai/mastra/commit/48b9e553a39528dcc20fbbeb798c3b1a1961468e), [`3412597`](https://github.com/mastra-ai/mastra/commit/3412597a6644c0b6bf3236d6e319ed1450c5bae8)]:
+  - @mastra/core@0.15.3-alpha.3
+  - @mastra/agent-builder@0.0.1-alpha.1

package/integration-tests/docker-compose.yml

@@ -2,7 +2,7 @@ services:
   postgres:
     image: ankane/pgvector:v0.5.1
     ports:
-      - '5434:5432'
+      - '5435:5432'
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: password
@@ -17,7 +17,7 @@ services:
   redis:
     image: redis:7-alpine
     ports:
-      - '6370:6379'
+      - '6371:6379'
     command: redis-server --requirepass redis_password
     healthcheck:
       test: ['CMD', 'redis-cli', 'ping']
@@ -27,7 +27,7 @@ services:
   serverless-redis-http:
     image: hiett/serverless-redis-http:latest
     ports:
-      - '8079:80'
+      - '8080:80'
     environment:
       SRH_MODE: env
       SRH_TOKEN: test_token

package/integration-tests/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@mastra/agent-builder-integration-tests",
   "private": true,
-  "version": "0.0.0-experimental-agent-builder-20250815195917",
+  "version": "0.1.1-alpha.0",
   "scripts": {
-    "test": "vitest run ./src/**/*.test.ts",
+    "test": "vitest run",
     "test:agent": "vitest run ./src/agent-template-behavior.test.ts",
     "test:template": "vitest run ./src/template-integration.test.ts",
     "dev": "mastra dev"
@@ -33,6 +33,6 @@
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "@mastra/core": "workspace:*"
+    "@mastra/core": ">=0.15.2-0 <0.16.0-0"
   }
 }

package/integration-tests/src/agent-template-behavior.test.ts

@@ -99,5 +99,5 @@ Template repository: ${realTemplateGit}`;
 
     // Verify response contains confirmation
     expect(response.text.toLowerCase()).toMatch(/merge|template|success|applied|complete/);
-  }, 300000); // Longer timeout for full merge operation
+  }, 600000); // Longer timeout for full merge operation
 });

package/integration-tests/src/fixtures/minimal-mastra-project/package.json

@@ -7,8 +7,8 @@
     "build": "mastra build"
   },
   "dependencies": {
-    "@mastra/core": "workspace:*",
-    "@mastra/mcp": "workspace:*",
+    "@mastra/core": "latest",
+    "@mastra/mcp": "latest",
     "zod": "^3.25.0"
   },
   "devDependencies": {

package/integration-tests/src/fixtures/minimal-mastra-project/src/mastra/tools/weather.ts

@@ -7,7 +7,8 @@ export const weatherTool = createTool({
   inputSchema: z.object({
     postalCode: z.string().describe('The location to get the weather for'),
   }),
-  execute: async ({ context: { postalCode } }) => {
+  execute: async ({ context }) => {
+    const { postalCode } = context;
     return `The weather in ${postalCode} is sunny. It is currently 70 degrees and feels like 65 degrees.`;
   },
 });

package/integration-tests/src/template-integration.test.ts

@@ -6,7 +6,7 @@ import { join, resolve } from 'node:path';
 import { Mastra } from '@mastra/core';
 import { describe, expect, it, beforeAll, afterAll } from 'vitest';
 import { fetchMastraTemplates } from '../../src/utils';
-import { mergeTemplateWorkflow } from '../../src/workflows';
+import { agentBuilderTemplateWorkflow } from '../../src/workflows';
 
 function exec(cmd: string, cwd?: string): string {
   return execSync(cmd, { stdio: 'pipe', cwd, encoding: 'utf-8' });
@@ -36,7 +36,7 @@ describe('Template Workflow Integration Tests', () => {
   beforeAll(async () => {
     mastraInstance = new Mastra({
       workflows: {
-        mergeTemplateWorkflow,
+        agentBuilderTemplateWorkflow,
       },
     });
 
@@ -92,7 +92,7 @@ describe('Template Workflow Integration Tests', () => {
 
     console.log(`Starting template merge workflow in ${targetRepo}`);
 
-    const templateWorkflow = mastraInstance.getWorkflow(`mergeTemplateWorkflow`);
+    const templateWorkflow = mastraInstance.getWorkflow(`agentBuilderTemplateWorkflow`);
 
     // Run the merge template workflow
     const workflowRun = await templateWorkflow.createRunAsync();
@@ -141,7 +141,7 @@ describe('Template Workflow Integration Tests', () => {
     expect(hasTemplateScript).toBe(true);
 
     console.log('Template merge completed successfully');
-  }, 300000); // 5 minute timeout for full workflow
+  }, 600000); // 10 minute timeout for full workflow
 
   it('should start Mastra server and validate both original and new agents work', async () => {
     // Skip test if no OPENAI_API_KEY available
@@ -164,7 +164,7 @@ describe('Template Workflow Integration Tests', () => {
       let output = '';
       const timeout = setTimeout(() => {
         reject(new Error('Mastra server failed to start within timeout'));
-      }, 300000);
+      }, 600000);
 
       mastraServer.stdout?.on('data', data => {
         output += data.toString();
@@ -248,7 +248,7 @@ describe('Template Workflow Integration Tests', () => {
     expect(hasCSVWorkflow).toBe(true);
 
     console.log('All agent and workflow tests passed!');
-  }, 300000); // 5 minute timeout for server startup and testing
+  }, 600000); // 10 minute timeout for server startup and testing
 
   it('should validate git history shows proper template integration', async () => {
     // Check git log for template commits
@@ -285,7 +285,7 @@ describe('Template Workflow Integration Tests', () => {
 
     console.log('Testing duplicate template merge...');
 
-    const templateWorkflow = mastraInstance.getWorkflow(`mergeTemplateWorkflow`);
+    const templateWorkflow = mastraInstance.getWorkflow(`agentBuilderTemplateWorkflow`);
     const workflowRun = await templateWorkflow.createRunAsync();
     const result = await workflowRun.start({
       inputData: {
@@ -308,5 +308,5 @@ describe('Template Workflow Integration Tests', () => {
     }
 
     console.log('Duplicate merge test completed');
-  }, 300000);
+  }, 600000);
 });

package/integration-tests/tsconfig.json

@@ -1,12 +1,8 @@
 {
+  "extends": "../../../tsconfig.node.json",
   "compilerOptions": {
-    "target": "ES2020",
     "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
+    "moduleResolution": "bundler"
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules"]

package/integration-tests/vitest.config.ts

@@ -5,6 +5,7 @@ export default defineConfig({
     pool: 'forks',
     globals: true,
     environment: 'node',
+    include: ['src/**/*.test.ts'],
     testTimeout: 120000,
     hookTimeout: 60000,
     coverage: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/agent-builder",
-  "version": "0.0.0-experimental-agent-builder-20250815195917",
+  "version": "0.0.1-alpha.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -20,11 +20,12 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^1.3.0",
+    "ignore": "^7.0.5",
     "semver": "^7.7.2",
     "swpm": "^2.6.0",
     "zod": "^3.25.67",
-    "@mastra/mcp": "0.0.0-experimental-agent-builder-20250815195917",
-    "@mastra/memory": "0.0.0-experimental-agent-builder-20250815195917"
+    "@mastra/mcp": "0.11.3-alpha.0",
+    "@mastra/memory": "0.14.3-alpha.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",
@@ -34,11 +35,11 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.38.0",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.0-experimental-agent-builder-20250815195917",
-    "@mastra/core": "0.0.0-experimental-agent-builder-20250815195917"
+    "@mastra/core": "0.15.3-alpha.3",
+    "@internal/lint": "0.0.34"
   },
   "peerDependencies": {
-    "@mastra/core": "0.0.0-experimental-agent-builder-20250815195917"
+    "@mastra/core": ">=0.10.7-0 <0.14.0-0"
   },
   "engines": {
     "node": ">=20"

package/src/agent/index.ts

@@ -0,0 +1,187 @@
+import type { CoreMessage } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import type { AiMessageType, AgentGenerateOptions, AgentStreamOptions } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { TokenLimiter } from '@mastra/memory/processors';
+import { AgentBuilderDefaults } from '../defaults';
+import { ToolSummaryProcessor } from '../processors/tool-summary';
+import { WriteToDiskProcessor } from '../processors/write-file';
+import type { AgentBuilderConfig, GenerateAgentOptions } from '../types';
+import { agentBuilderTemplateWorkflow } from '../workflows';
+
+// =============================================================================
+// Template Merge Workflow Implementation
+// =============================================================================
+//
+// This workflow implements a comprehensive template merging system that:
+// 1. Clones template repositories at specific refs (tags/commits)
+// 2. Discovers units (agents, workflows, MCP servers/tools) in templates
+// 3. Topologically orders units based on dependencies
+// 4. Analyzes conflicts and creates safety classifications
+// 5. Applies changes with git branching and checkpoints per unit
+//
+// The workflow follows the "auto-decide vs ask" principles:
+// - Auto: adding new files, missing deps, appending arrays, new scripts with template:slug:* namespace
+// - Prompt: overwriting files, major upgrades, renaming conflicts, new ports, postInstall commands
+// - Block: removing files, downgrading deps, changing TS target/module, modifying CI/CD secrets
+//
+// Usage with Mastra templates (see https://mastra.ai/api/templates.json):
+//   const run = await agentBuilderTemplateWorkflow.createRunAsync();
+//   const result = await run.start({
+//     inputData: {
+//       repo: 'https://github.com/mastra-ai/template-pdf-questions',
+//       ref: 'main', // optional
+//       targetPath: './my-project', // optional, defaults to cwd
+//     }
+//   });
+//   // The workflow will automatically analyze and merge the template structure
+//
+// =============================================================================
+
+export class AgentBuilder extends Agent {
+  private builderConfig: AgentBuilderConfig;
+
+  /**
+   * Constructor for AgentBuilder
+   */
+  constructor(config: AgentBuilderConfig) {
+    const additionalInstructions = config.instructions ? `## Priority Instructions \n\n${config.instructions}` : '';
+    const combinedInstructions = additionalInstructions + AgentBuilderDefaults.DEFAULT_INSTRUCTIONS(config.projectPath);
+
+    const agentConfig = {
+      name: 'agent-builder',
+      description:
+        'An AI agent specialized in generating Mastra agents, tools, and workflows from natural language requirements.',
+      instructions: combinedInstructions,
+      model: config.model,
+      tools: async () => {
+        return {
+          ...(await AgentBuilderDefaults.DEFAULT_TOOLS(config.projectPath, config.mode)),
+          ...(config.tools || {}),
+        };
+      },
+      workflows: {
+        'merge-template': agentBuilderTemplateWorkflow,
+      },
+      memory: new Memory({
+        options: AgentBuilderDefaults.DEFAULT_MEMORY_CONFIG,
+        processors: [
+          new WriteToDiskProcessor({ prefix: 'before-filter' }),
+          new ToolSummaryProcessor({ summaryModel: config.summaryModel || config.model }),
+          new TokenLimiter(100000),
+          new WriteToDiskProcessor({ prefix: 'after-filter' }),
+        ],
+      }),
+    };
+
+    super(agentConfig);
+    this.builderConfig = config;
+  }
+
+  /**
+   * Enhanced generate method with AgentBuilder-specific configuration
+   * Overrides the base Agent generate method to provide additional project context
+   */
+  generate: Agent['generate'] = async (
+    messages: string | string[] | CoreMessage[] | AiMessageType[],
+    generateOptions: (GenerateAgentOptions & AgentGenerateOptions<any, any>) | undefined = {},
+  ): Promise<any> => {
+    const { ...baseOptions } = generateOptions;
+
+    const originalInstructions = await this.getInstructions({ runtimeContext: generateOptions?.runtimeContext });
+    const additionalInstructions = baseOptions.instructions;
+
+    let enhancedInstructions = originalInstructions as string;
+    if (additionalInstructions) {
+      enhancedInstructions = `${originalInstructions}\n\n${additionalInstructions}`;
+    }
+
+    const enhancedContext = [...(baseOptions.context || [])];
+
+    const enhancedOptions = {
+      ...baseOptions,
+      maxSteps: 300, // Higher default for code generation
+      temperature: 0.3, // Lower temperature for more consistent code generation
+      instructions: enhancedInstructions,
+      context: enhancedContext,
+    } satisfies AgentGenerateOptions<any, any>;
+
+    this.logger.debug(`[AgentBuilder:${this.name}] Starting generation with enhanced context`, {
+      projectPath: this.builderConfig.projectPath,
+    });
+
+    return super.generate(messages, enhancedOptions);
+  };
+
+  /**
+   * Enhanced stream method with AgentBuilder-specific configuration
+   * Overrides the base Agent stream method to provide additional project context
+   */
+  stream: Agent['stream'] = async (
+    messages: string | string[] | CoreMessage[] | AiMessageType[],
+    streamOptions: (GenerateAgentOptions & AgentStreamOptions<any, any>) | undefined = {},
+  ): Promise<any> => {
+    const { ...baseOptions } = streamOptions;
+
+    const originalInstructions = await this.getInstructions({ runtimeContext: streamOptions?.runtimeContext });
+    const additionalInstructions = baseOptions.instructions;
+
+    let enhancedInstructions = originalInstructions as string;
+    if (additionalInstructions) {
+      enhancedInstructions = `${originalInstructions}\n\n${additionalInstructions}`;
+    }
+    const enhancedContext = [...(baseOptions.context || [])];
+
+    const enhancedOptions = {
+      ...baseOptions,
+      maxSteps: 100, // Higher default for code generation
+      temperature: 0.3, // Lower temperature for more consistent code generation
+      instructions: enhancedInstructions,
+      context: enhancedContext,
+    };
+
+    this.logger.debug(`[AgentBuilder:${this.name}] Starting streaming with enhanced context`, {
+      projectPath: this.builderConfig.projectPath,
+    });
+
+    return super.stream(messages, enhancedOptions);
+  };
+
+  /**
+   * Generate a Mastra agent from natural language requirements
+   */
+  async generateAgent(
+    requirements: string,
+    options?: {
+      outputFormat?: 'code' | 'explanation' | 'both';
+      runtimeContext?: any;
+    },
+  ) {
+    const prompt = `Generate a Mastra agent based on these requirements: ${requirements}
+
+Please provide:
+1. Complete agent code with proper configuration
+2. Any custom tools the agent needs
+3. Example usage
+4. Testing recommendations
+
+${options?.outputFormat === 'explanation' ? 'Focus on explaining the approach and architecture.' : ''}
+${options?.outputFormat === 'code' ? 'Focus on providing complete, working code.' : ''}
+${!options?.outputFormat || options.outputFormat === 'both' ? 'Provide both explanation and complete code.' : ''}`;
+
+    return this.generate(prompt, {
+      runtimeContext: options?.runtimeContext,
+    });
+  }
+
+  /**
+   * Get the default configuration for AgentBuilder
+   */
+  static defaultConfig(projectPath?: string) {
+    return {
+      instructions: AgentBuilderDefaults.DEFAULT_INSTRUCTIONS(projectPath),
+      memoryConfig: AgentBuilderDefaults.DEFAULT_MEMORY_CONFIG,
+      tools: AgentBuilderDefaults.DEFAULT_TOOLS,
+    };
+  }
+}

package/src/agent-builder.test.ts

@@ -21,20 +21,20 @@ const mockConfig = {
 describe('AgentBuilder', () => {
   describe('AgentBuilderDefaults', () => {
     it('should have default instructions', () => {
-      expect(AgentBuilderDefaults.DEFAULT_INSTRUCTIONS).toContain('expert Mastra Agent Builder');
+      expect(AgentBuilderDefaults.DEFAULT_INSTRUCTIONS()).toContain('Mastra Expert Agent');
     });
 
     it('should have default memory config', () => {
       expect(AgentBuilderDefaults.DEFAULT_MEMORY_CONFIG).toEqual({
-        maxMessages: 20,
-        tokenLimit: 10000,
+        lastMessages: 20,
       });
     });
 
-    it('should have default tools', () => {
-      expect(AgentBuilderDefaults.DEFAULT_TOOLS).toHaveProperty('manageProject');
-      expect(AgentBuilderDefaults.DEFAULT_TOOLS).toHaveProperty('searchReplace');
-      expect(AgentBuilderDefaults.DEFAULT_TOOLS).toHaveProperty('validateCode');
+    it('should have default tools', async () => {
+      const tools = await AgentBuilderDefaults.DEFAULT_TOOLS('test');
+      expect(tools).toHaveProperty('manageProject');
+      expect(tools).toHaveProperty('multiEdit');
+      expect(tools).toHaveProperty('validateCode');
     });
   });
 
@@ -170,6 +170,32 @@ describe('AgentBuilder', () => {
       expect(key1).toBe(key2);
       expect(key1).toBe('myTool:{"a":1,"b":2}');
     });
+
+    it('should use Promise.allSettled for resilient parallel processing', async () => {
+      // This test verifies that the ToolSummaryProcessor uses Promise.allSettled
+      // instead of Promise.all, so that one failed summary doesn't break all summaries
+
+      const processor = new ToolSummaryProcessor({ summaryModel: mockModel });
+
+      // Test that the processor handles empty messages gracefully
+      const emptyMessages: any[] = [];
+      const result = await processor.process(emptyMessages);
+      expect(result).toEqual([]);
+
+      // Test that the processor doesn't throw when processing messages
+      // (the actual resilience testing would require more complex mocking,
+      // but this ensures the basic structure works)
+      const basicMessages = [
+        {
+          role: 'user' as const,
+          content: 'Hello',
+        },
+      ];
+
+      const basicResult = await processor.process(basicMessages);
+      expect(basicResult).toHaveLength(1);
+      expect(basicResult[0].content).toBe('Hello');
+    });
   });
 
   describe('Server Management Tools', () => {
@@ -279,13 +305,9 @@ Found 2 errors in 2 files.`;
     it('should include validation workflow in instructions', () => {
       const instructions = AgentBuilderDefaults.DEFAULT_INSTRUCTIONS('/test/path');
 
-      expect(instructions).toContain('VALIDATE CODE AFTER CHANGES');
       expect(instructions).toContain('validateCode');
-      expect(instructions).toContain("['types', 'lint']");
+      expect(instructions).toContain('Run \`validateCode\` with types and lint checks');
       expect(instructions).toContain('Re-validate until clean');
-      expect(instructions).toContain(
-        'Documentation → Web Research → Clarification → Project Exploration → Implementation → Validation',
-      );
     });
   });
 });