mcp-agent-foundry 1.0.0

package/dist/router/pattern-executor.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Pattern Executor
+ *
+ * Orchestrates multi-agent workflows using various execution patterns.
+ * Provides high-level patterns for agent collaboration including:
+ * - Sequential pipelines (A → B → C)
+ * - Parallel comparison (same task to multiple agents)
+ * - Generator-Critic loops (generate → critique → improve)
+ * - Consensus building (propose → vote → synthesize)
+ *
+ * Each pattern leverages the RouterEngine for individual agent invocations
+ * while managing the overall workflow state and data flow between agents.
+ */
+import { type Logger } from '../observability/logger.js';
+import type { AgentResponse } from '../types.js';
+import type { RouterEngine } from './engine.js';
+/**
+ * Step definition for sequential pipeline execution.
+ */
+export interface SequentialStep {
+    /** The role of the agent to invoke for this step */
+    role: string;
+    /** Task template for this step. Use {{input}} or {{previousOutput}} placeholders */
+    taskTemplate: string;
+    /** Optional transform function to modify input before sending to agent */
+    transform?: (input: string) => string;
+}
+/**
+ * Result of a sequential pipeline execution.
+ */
+export interface SequentialResult {
+    /** Pattern identifier */
+    pattern: 'sequential';
+    /** All step responses in order */
+    steps: AgentResponse[];
+    /** Final output text from the last step */
+    finalOutput: string;
+    /** Total duration in milliseconds */
+    totalDurationMs: number;
+    /** Trace ID for correlation */
+    traceId: string;
+}
+/**
+ * Result of a parallel comparison execution.
+ */
+export interface ParallelResult {
+    /** Pattern identifier */
+    pattern: 'parallel';
+    /** Map of role names to their responses */
+    responses: Map<string, AgentResponse>;
+    /** Errors for roles that failed */
+    errors: Map<string, Error>;
+    /** Total duration in milliseconds */
+    totalDurationMs: number;
+    /** Trace ID for correlation */
+    traceId: string;
+}
+/**
+ * Result of a generator-critic loop execution.
+ */
+export interface CriticLoopResult {
+    /** Pattern identifier */
+    pattern: 'critic-loop';
+    /** Number of iterations completed */
+    iterations: number;
+    /** Final response from the generator */
+    finalResponse: AgentResponse;
+    /** Complete history of all generation and critique responses */
+    history: CriticLoopIteration[];
+    /** Whether the critic approved the final result */
+    approved: boolean;
+    /** Final output text */
+    finalOutput: string;
+    /** Total duration in milliseconds */
+    totalDurationMs: number;
+    /** Trace ID for correlation */
+    traceId: string;
+}
+/**
+ * Single iteration of a critic loop.
+ */
+export interface CriticLoopIteration {
+    /** Iteration number (1-indexed) */
+    iteration: number;
+    /** Generator's response */
+    generation: AgentResponse;
+    /** Critic's response */
+    critique: AgentResponse;
+    /** Whether the critic approved this iteration */
+    approved: boolean;
+}
+/**
+ * Result of a consensus building execution.
+ */
+export interface ConsensusResult {
+    /** Pattern identifier */
+    pattern: 'consensus';
+    /** Initial proposals from all participating roles */
+    proposals: Map<string, AgentResponse>;
+    /** Votes/assessments from each role on all proposals */
+    votes: Map<string, AgentResponse>;
+    /** Final synthesized recommendation */
+    synthesis: AgentResponse;
+    /** Final output text */
+    finalOutput: string;
+    /** Total duration in milliseconds */
+    totalDurationMs: number;
+    /** Trace ID for correlation */
+    traceId: string;
+}
+/**
+ * Options for critic loop execution.
+ */
+export interface CriticLoopOptions {
+    /** Maximum number of iterations (default: 3) */
+    maxIterations?: number;
+    /** Custom approval detection function */
+    isApproved?: (critique: string) => boolean;
+    /** Custom task template for critique requests */
+    critiqueTaskTemplate?: string;
+    /** Custom task template for improvement requests */
+    improvementTaskTemplate?: string;
+}
+/**
+ * Options for consensus building execution.
+ */
+export interface ConsensusOptions {
+    /** Role to use for final synthesis (default: first role in list) */
+    synthesizeRole?: string;
+    /** Custom task template for voting phase */
+    voteTaskTemplate?: string;
+    /** Custom task template for synthesis phase */
+    synthesisTaskTemplate?: string;
+}
+/**
+ * Union type of all orchestration results.
+ */
+export type OrchestrationResult = SequentialResult | ParallelResult | CriticLoopResult | ConsensusResult;
+/**
+ * Orchestrates multi-agent workflows using various execution patterns.
+ *
+ * @example
+ * ```typescript
+ * const executor = new PatternExecutor(routerEngine, logger);
+ *
+ * // Sequential pipeline
+ * const result = await executor.executeSequential([
+ *   { role: 'coder', taskTemplate: 'Implement: {{input}}' },
+ *   { role: 'reviewer', taskTemplate: 'Review this code: {{previousOutput}}' },
+ * ], 'Create a sorting function');
+ *
+ * // Parallel comparison
+ * const comparison = await executor.executeParallel(
+ *   ['coder', 'researcher'],
+ *   'What are the best practices for error handling?'
+ * );
+ *
+ * // Critic loop
+ * const improved = await executor.executeCriticLoop(
+ *   'coder',
+ *   'critic',
+ *   'Write a REST API endpoint',
+ *   { maxIterations: 3 }
+ * );
+ * ```
+ */
+export declare class PatternExecutor {
+    private readonly router;
+    private readonly logger;
+    constructor(router: RouterEngine, logger: Logger);
+    /**
+     * Execute a sequential pipeline of agents.
+     *
+     * Each agent's output becomes input to the next. Task templates can use
+     * placeholders:
+     * - `{{input}}` - The original input or previous step's output
+     * - `{{previousOutput}}` - Alias for input from previous step
+     *
+     * @param steps - Array of step definitions with roles and task templates
+     * @param initialInput - Initial input to the first step
+     * @returns Promise resolving to SequentialResult with all step outputs
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.executeSequential([
+     *   { role: 'coder', taskTemplate: '{{input}}' },
+     *   { role: 'reviewer', taskTemplate: 'Review: {{previousOutput}}' },
+     *   { role: 'coder', taskTemplate: 'Fix issues: {{previousOutput}}' },
+     * ], 'Write a function to validate email addresses');
+     * ```
+     */
+    executeSequential(steps: SequentialStep[], initialInput: string): Promise<SequentialResult>;
+    /**
+     * Execute the same task through multiple agents in parallel.
+     *
+     * All agents receive the same task and run concurrently. Results are
+     * collected for comparison. Errors for individual agents don't fail
+     * the entire operation.
+     *
+     * @param roles - Array of role names to invoke
+     * @param task - The task to send to all agents
+     * @returns Promise resolving to ParallelResult with all agent responses
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.executeParallel(
+     *   ['coder', 'researcher', 'critic'],
+     *   'What is the best approach to implement caching?'
+     * );
+     *
+     * for (const [role, response] of result.responses) {
+     *   console.log(`${role}: ${extractText(response)}`);
+     * }
+     * ```
+     */
+    executeParallel(roles: string[], task: string): Promise<ParallelResult>;
+    /**
+     * Execute a generator-critic improvement loop.
+     *
+     * The generator creates an initial response, then the critic reviews it.
+     * If the critic identifies issues, the generator improves based on feedback.
+     * This continues until the critic approves or max iterations is reached.
+     *
+     * @param generatorRole - Role for generating content
+     * @param criticRole - Role for critiquing content
+     * @param task - Initial task for the generator
+     * @param options - Optional configuration for the loop
+     * @returns Promise resolving to CriticLoopResult with iteration history
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.executeCriticLoop(
+     *   'coder',
+     *   'critic',
+     *   'Write a function to parse JSON with error handling',
+     *   { maxIterations: 3 }
+     * );
+     *
+     * if (result.approved) {
+     *   console.log('Critic approved the final version');
+     * }
+     * console.log(`Completed in ${result.iterations} iterations`);
+     * ```
+     */
+    executeCriticLoop(generatorRole: string, criticRole: string, task: string, options?: CriticLoopOptions): Promise<CriticLoopResult>;
+    /**
+     * Execute a consensus building workflow.
+     *
+     * Three phases:
+     * 1. Proposals: All roles respond to the initial question
+     * 2. Voting: Each role evaluates all proposals
+     * 3. Synthesis: A designated role synthesizes a final recommendation
+     *
+     * @param roles - Array of role names to participate
+     * @param question - The question or decision to reach consensus on
+     * @param options - Optional configuration for the workflow
+     * @returns Promise resolving to ConsensusResult with all phases
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.executeConsensus(
+     *   ['coder', 'critic', 'designer'],
+     *   'What is the best architecture for a real-time chat application?',
+     *   { synthesizeRole: 'coder' }
+     * );
+     *
+     * console.log('Final recommendation:', result.finalOutput);
+     * ```
+     */
+    executeConsensus(roles: string[], question: string, options?: ConsensusOptions): Promise<ConsensusResult>;
+    /**
+     * Extract text content from an agent response.
+     *
+     * @param response - Agent response to extract text from
+     * @returns Concatenated text content from all text blocks
+     */
+    extractText(response: AgentResponse): string;
+    /**
+     * Interpolate a template string with variable values.
+     *
+     * @param template - Template string with {{variable}} placeholders
+     * @param variables - Object mapping variable names to values
+     * @returns Interpolated string
+     */
+    private interpolateTemplate;
+    /**
+     * Format proposals for display in templates.
+     *
+     * @param proposals - Map of role names to responses
+     * @returns Formatted string with numbered proposals
+     */
+    private formatProposals;
+    /**
+     * Format votes/assessments for display in templates.
+     *
+     * @param votes - Map of role names to vote responses
+     * @returns Formatted string with role assessments
+     */
+    private formatVotes;
+    /**
+     * Truncate a string to a maximum length.
+     *
+     * @param str - String to truncate
+     * @param maxLength - Maximum length before truncation
+     * @returns Truncated string with ellipsis if needed
+     */
+    private truncate;
+}
+/**
+ * Create a PatternExecutor instance.
+ *
+ * @param router - RouterEngine for agent invocations
+ * @param logger - Logger for observability
+ * @returns Configured PatternExecutor instance
+ */
+export declare function createPatternExecutor(router: RouterEngine, logger: Logger): PatternExecutor;
+//# sourceMappingURL=pattern-executor.d.ts.map

package/dist/router/pattern-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-executor.d.ts","sourceRoot":"","sources":["../../src/router/pattern-executor.ts"],"names":[],"mappings":"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"}