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

package/src/index.ts

@@ -1,187 +0,0 @@
-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 { mergeTemplateWorkflow } 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 mergeTemplateWorkflow.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;
-
-  /**
-   * Private constructor - use AgentBuilder.create() instead
-   */
-  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': mergeTemplateWorkflow,
-      },
-      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,
-    };
-
-    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/processors/tool-summary.ts

@@ -1,136 +0,0 @@
-import type { CoreMessage, MastraLanguageModel } from '@mastra/core';
-import { Agent, MemoryProcessor } from '@mastra/core';
-
-/**
- * Summarizes tool calls and caches results to avoid re-summarizing identical calls
- */
-export class ToolSummaryProcessor extends MemoryProcessor {
-  private summaryAgent: Agent;
-  private summaryCache: Map<string, string> = new Map();
-
-  constructor({ summaryModel }: { summaryModel: MastraLanguageModel }) {
-    super({ name: 'ToolSummaryProcessor' });
-    this.summaryAgent = new Agent({
-      name: 'ToolSummaryAgent',
-      description: 'A summary agent that summarizes tool calls and results',
-      instructions: 'You are a summary agent that summarizes tool calls and results',
-      model: summaryModel,
-    });
-  }
-
-  /**
-   * Creates a cache key from tool call arguments
-   */
-  public createCacheKey(toolCall: any): string {
-    if (!toolCall) return 'unknown';
-
-    // Create a deterministic key from tool name and arguments
-    const toolName = toolCall.toolName || 'unknown';
-    const args = toolCall.args || {};
-
-    // Sort keys for consistent hashing
-    const sortedArgs = Object.keys(args)
-      .sort()
-      .reduce((result: Record<string, any>, key) => {
-        result[key] = args[key];
-        return result;
-      }, {});
-
-    return `${toolName}:${JSON.stringify(sortedArgs)}`;
-  }
-
-  /**
-   * Clears the summary cache
-   */
-  public clearCache(): void {
-    this.summaryCache.clear();
-  }
-
-  /**
-   * Gets cache statistics
-   */
-  public getCacheStats(): { size: number; keys: string[] } {
-    return {
-      size: this.summaryCache.size,
-      keys: Array.from(this.summaryCache.keys()),
-    };
-  }
-
-  async process(messages: CoreMessage[]): Promise<CoreMessage[]> {
-    // Collect all tool calls that need summarization
-    const summaryTasks: Array<{
-      content: any;
-      promise: Promise<any>;
-      cacheKey: string;
-    }> = [];
-
-    // First pass: collect all tool results that need summarization
-    for (const message of messages) {
-      if (
-        message.role === 'tool' &&
-        Array.isArray(message.content) &&
-        message.content.length > 0 &&
-        message.content?.some(content => content.type === 'tool-result')
-      ) {
-        for (const content of message.content) {
-          if (content.type === 'tool-result') {
-            const assistantMessageWithToolCall = messages.find(
-              message =>
-                message.role === 'assistant' &&
-                Array.isArray(message.content) &&
-                message.content.length > 0 &&
-                message.content?.some(
-                  assistantContent =>
-                    assistantContent.type === 'tool-call' && assistantContent.toolCallId === content.toolCallId,
-                ),
-            );
-            const toolCall = Array.isArray(assistantMessageWithToolCall?.content)
-              ? assistantMessageWithToolCall?.content.find(
-                  assistantContent =>
-                    assistantContent.type === 'tool-call' && assistantContent.toolCallId === content.toolCallId,
-                )
-              : null;
-
-            const cacheKey = this.createCacheKey(toolCall);
-            const cachedSummary = this.summaryCache.get(cacheKey);
-
-            if (cachedSummary) {
-              // Use cached summary immediately
-              content.result = `Tool call summary: ${cachedSummary}`;
-            } else {
-              // Create a promise for this summary (but don't await yet)
-              const summaryPromise = this.summaryAgent.generate(
-                `Summarize the following tool call: ${JSON.stringify(toolCall)} and result: ${JSON.stringify(content)}`,
-              );
-
-              summaryTasks.push({
-                content,
-                promise: summaryPromise,
-                cacheKey,
-              });
-            }
-          }
-        }
-      }
-    }
-
-    // Execute all non-cached summaries in parallel
-    if (summaryTasks.length > 0) {
-      const summaryResults = await Promise.all(summaryTasks.map(task => task.promise));
-
-      // Apply the results back to the content and cache them
-      summaryTasks.forEach((task, index) => {
-        const summaryResult = summaryResults[index];
-        const summaryText = summaryResult.text;
-
-        // Cache the summary for future use
-        this.summaryCache.set(task.cacheKey, summaryText);
-
-        // Apply to content
-        task.content.result = `Tool call summary: ${summaryText}`;
-      });
-    }
-
-    return messages;
-  }
-}

package/src/processors/write-file.ts

@@ -1,17 +0,0 @@
-import { writeFile } from 'fs/promises';
-import { MemoryProcessor } from '@mastra/core';
-import type { CoreMessage } from '@mastra/core';
-
-export class WriteToDiskProcessor extends MemoryProcessor {
-  private prefix: string;
-
-  constructor({ prefix = 'messages' }: { prefix?: string } = {}) {
-    super({ name: 'WriteToDiskProcessor' });
-    this.prefix = prefix;
-  }
-
-  async process(messages: CoreMessage[]): Promise<CoreMessage[]> {
-    await writeFile(`${this.prefix}-${Date.now()}.json`, JSON.stringify(messages, null, 2));
-    return messages;
-  }
-}

package/src/types.ts

@@ -1,120 +0,0 @@
-import type { MastraLanguageModel, ToolsInput } from '@mastra/core/agent';
-import { z } from 'zod';
-
-/**
- * Configuration options for the AgentBuilder
- */
-export interface AgentBuilderConfig {
-  /** The language model to use for agent generation */
-  model: MastraLanguageModel;
-  /** Storage provider for memory (optional) */
-  storage?: any;
-  /** Vector provider for memory (optional) */
-  vectorProvider?: any;
-  /** Additional tools to include beyond the default set */
-  tools?: ToolsInput;
-  /** Custom instructions to append to the default system prompt */
-  instructions?: string;
-  /** Memory configuration options */
-  memoryConfig?: {
-    maxMessages?: number;
-    tokenLimit?: number;
-  };
-  /** Project path */
-  projectPath: string;
-  /** Summary model */
-  summaryModel?: MastraLanguageModel;
-  /** Mode */
-  mode?: 'template' | 'code-editor';
-}
-
-/**
- * Options for generating agents with AgentBuilder
- */
-export interface GenerateAgentOptions {
-  /** Runtime context for the generation */
-  runtimeContext?: any;
-  /** Output format preference */
-  outputFormat?: 'code' | 'explanation' | 'both';
-}
-
-/**
- * Project management action types
- */
-export type ProjectAction = 'create' | 'install' | 'upgrade' | 'check';
-
-/**
- * Project types that can be created
- */
-export type ProjectType = 'standalone' | 'api' | 'nextjs';
-
-/**
- * Package manager options
- */
-export type PackageManager = 'npm' | 'pnpm' | 'yarn';
-
-/**
- * Validation types for code validation
- */
-export type ValidationType = 'types' | 'schemas' | 'tests' | 'integration';
-
-// Processing order for units (lower index = higher priority)
-export const UNIT_KINDS = ['mcp-server', 'tool', 'workflow', 'agent', 'integration', 'network', 'other'] as const;
-
-// Types for the merge template workflow
-export type UnitKind = (typeof UNIT_KINDS)[number];
-
-export interface TemplateUnit {
-  kind: UnitKind;
-  id: string;
-  file: string;
-}
-
-export interface TemplateManifest {
-  slug: string;
-  ref?: string;
-  description?: string;
-  units: TemplateUnit[];
-}
-
-export interface MergePlan {
-  slug: string;
-  commitSha: string;
-  templateDir: string;
-  units: TemplateUnit[];
-}
-
-// Schema definitions
-export const TemplateUnitSchema = z.object({
-  kind: z.enum(UNIT_KINDS),
-  id: z.string(),
-  file: z.string(),
-});
-
-export const TemplateManifestSchema = z.object({
-  slug: z.string(),
-  ref: z.string().optional(),
-  description: z.string().optional(),
-  units: z.array(TemplateUnitSchema),
-});
-
-export const MergeInputSchema = z.object({
-  repo: z.string().describe('Git URL or local path of the template repo'),
-  ref: z.string().optional().describe('Tag/branch/commit to checkout (defaults to main/master)'),
-  slug: z.string().optional().describe('Slug for branch/scripts; defaults to inferred from repo'),
-  targetPath: z.string().optional().describe('Project path to merge into; defaults to current directory'),
-});
-
-export const MergePlanSchema = z.object({
-  slug: z.string(),
-  commitSha: z.string(),
-  templateDir: z.string(),
-  units: z.array(TemplateUnitSchema),
-});
-
-export const ApplyResultSchema = z.object({
-  success: z.boolean(),
-  applied: z.boolean(),
-  branchName: z.string().optional(),
-  error: z.string().optional(),
-});

package/src/utils.ts

@@ -1,133 +0,0 @@
-import { exec as execNodejs, spawn as nodeSpawn } from 'child_process';
-import { existsSync } from 'fs';
-import { copyFile } from 'fs/promises';
-import { createRequire } from 'module';
-import { dirname, basename, extname, resolve } from 'path';
-import { promisify } from 'util';
-import { UNIT_KINDS } from './types';
-import type { UnitKind } from './types';
-
-export const exec = promisify(execNodejs);
-
-export function spawn(command: string, args: string[], options: any) {
-  return new Promise((resolve, reject) => {
-    const childProcess = nodeSpawn(command, args, {
-      // stdio: 'inherit',
-      ...options,
-    });
-    childProcess.on('error', error => {
-      reject(error);
-    });
-    let stderr = '';
-    childProcess.stderr?.on('data', message => {
-      stderr += message;
-    });
-    childProcess.on('close', code => {
-      if (code === 0) {
-        resolve(void 0);
-      } else {
-        reject(new Error(stderr));
-      }
-    });
-  });
-}
-
-export async function spawnSWPM(cwd: string, command: string, packageNames: string[]) {
-  await spawn(createRequire(import.meta.filename).resolve('swpm'), [command, ...packageNames], {
-    cwd,
-  });
-}
-
-// Utility functions
-export function kindWeight(kind: UnitKind): number {
-  const idx = UNIT_KINDS.indexOf(kind as any);
-  return idx === -1 ? UNIT_KINDS.length : idx;
-}
-
-// Utility functions to work with Mastra templates
-export async function fetchMastraTemplates(): Promise<
-  Array<{
-    slug: string;
-    title: string;
-    description: string;
-    githubUrl: string;
-    tags: string[];
-    agents: string[];
-    workflows: string[];
-    tools: string[];
-  }>
-> {
-  try {
-    const response = await fetch('https://mastra.ai/api/templates.json');
-    const data = (await response.json()) as Array<{
-      slug: string;
-      title: string;
-      description: string;
-      githubUrl: string;
-      tags: string[];
-      agents: string[];
-      workflows: string[];
-      tools: string[];
-    }>;
-    return data;
-  } catch (error) {
-    throw new Error(`Failed to fetch Mastra templates: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-// Helper to get a specific template by slug
-export async function getMastraTemplate(slug: string) {
-  const templates = await fetchMastraTemplates();
-  const template = templates.find(t => t.slug === slug);
-  if (!template) {
-    throw new Error(`Template "${slug}" not found. Available templates: ${templates.map(t => t.slug).join(', ')}`);
-  }
-  return template;
-}
-
-// Git commit tracking utility
-export async function logGitState(targetPath: string, label: string): Promise<void> {
-  try {
-    const gitStatusResult = await exec('git status --porcelain', { cwd: targetPath });
-    const gitLogResult = await exec('git log --oneline -3', { cwd: targetPath });
-    const gitCountResult = await exec('git rev-list --count HEAD', { cwd: targetPath });
-
-    console.log(`📊 Git state ${label}:`);
-    console.log('Status:', gitStatusResult.stdout.trim() || 'Clean working directory');
-    console.log('Recent commits:', gitLogResult.stdout.trim());
-    console.log('Total commits:', gitCountResult.stdout.trim());
-  } catch (gitError) {
-    console.warn(`Could not get git state ${label}:`, gitError);
-  }
-}
-
-// File conflict resolution utilities (for future use)
-export async function backupAndReplaceFile(sourceFile: string, targetFile: string): Promise<void> {
-  // Create backup of existing file
-  const backupFile = `${targetFile}.backup-${Date.now()}`;
-  await copyFile(targetFile, backupFile);
-  console.log(`📦 Created backup: ${basename(backupFile)}`);
-
-  // Replace with template file
-  await copyFile(sourceFile, targetFile);
-  console.log(`🔄 Replaced file with template version (backup created)`);
-}
-
-export async function renameAndCopyFile(sourceFile: string, targetFile: string): Promise<string> {
-  // Find unique filename
-  let counter = 1;
-  let uniqueTargetFile = targetFile;
-  const baseName = basename(targetFile, extname(targetFile));
-  const extension = extname(targetFile);
-  const directory = dirname(targetFile);
-
-  while (existsSync(uniqueTargetFile)) {
-    const uniqueName = `${baseName}.template-${counter}${extension}`;
-    uniqueTargetFile = resolve(directory, uniqueName);
-    counter++;
-  }
-
-  await copyFile(sourceFile, uniqueTargetFile);
-  console.log(`📝 Copied with unique name: ${basename(uniqueTargetFile)}`);
-  return uniqueTargetFile;
-}