mcp-ai-agent-guidelines 0.11.2 → 0.12.0

package/README.md

@@ -95,6 +95,8 @@ Configuration is in `.mlc_config.json`. Ignored patterns and retries are configu
 ### Advanced Features
 
 - **[🌊 Flow-Based Prompting](./docs/tips/flow-prompting-examples.md)** - Multi-step prompt workflows
+- **[🔗 Agent-to-Agent (A2A) Orchestration](./docs/tips/a2a-orchestration-guide.md)** - Tool-to-tool chaining with context propagation
+- **[📋 A2A Practical Examples](./docs/tips/a2a-examples.md)** - Real-world A2A workflow patterns
 - **[🎨 Mermaid Diagram Generation](./docs/tips/mermaid-diagram-examples.md)** - Create flowcharts, sequences, ER diagrams
 - **[🔍 Code Quality Analysis](./docs/tips/code-quality-improvements.md)** - Hygiene scoring and best practices
 - **[⚡ Sprint Planning](./docs/tips/sprint-planning-reliability.md)** - Dependency-aware timeline calculation

package/dist/tools/agent-orchestrator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Agent Orchestrator Tool
+ *
+ * High-level MCP tool for Agent-to-Agent (A2A) orchestration.
+ * Enables declarative workflow execution using registered tools.
+ *
+ * Features:
+ * - Execute pre-defined workflow templates
+ * - Custom workflow execution from user-provided plans
+ * - Automatic context management and tracing
+ * - Error handling with fallback strategies
+ * - Execution visualization and reporting
+ */
+/**
+ * Workflow template identifier
+ */
+export type WorkflowTemplate = "quality-audit" | "security-scan" | "code-analysis-pipeline" | "documentation-generation";
+/**
+ * Agent Orchestrator Tool
+ *
+ * Orchestrates multi-tool workflows with A2A chaining capabilities.
+ *
+ * @param args - Orchestrator configuration
+ * @returns Workflow execution result with trace and summary
+ */
+export declare function agentOrchestrator(args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;
+//# sourceMappingURL=agent-orchestrator.d.ts.map

package/dist/tools/agent-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-orchestrator.d.ts","sourceRoot":"","sources":["../../src/tools/agent-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiBH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACzB,eAAe,GACf,eAAe,GACf,wBAAwB,GACxB,0BAA0B,CAAC;AA6F9B;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,OAAO;;;;;;;;;;;;GA0HpD"}

package/dist/tools/agent-orchestrator.js

@@ -0,0 +1,360 @@
+/**
+ * Agent Orchestrator Tool
+ *
+ * High-level MCP tool for Agent-to-Agent (A2A) orchestration.
+ * Enables declarative workflow execution using registered tools.
+ *
+ * Features:
+ * - Execute pre-defined workflow templates
+ * - Custom workflow execution from user-provided plans
+ * - Automatic context management and tracing
+ * - Error handling with fallback strategies
+ * - Execution visualization and reporting
+ */
+import { z } from "zod";
+import { createA2AContext, getExecutionSummary, } from "./shared/a2a-context.js";
+import { executeChain, } from "./shared/execution-controller.js";
+import { logger } from "./shared/logger.js";
+import { createTraceFromContext, traceLogger } from "./shared/trace-logger.js";
+/**
+ * Input schema for agent orchestrator
+ */
+const AgentOrchestratorSchema = z.object({
+    // Workflow execution mode
+    mode: z
+        .enum(["template", "custom"])
+        .describe("Execution mode: template for pre-defined workflows, custom for user-defined"),
+    // Template workflow (for mode: template)
+    template: z
+        .enum([
+        "quality-audit",
+        "security-scan",
+        "code-analysis-pipeline",
+        "documentation-generation",
+    ])
+        .optional()
+        .describe("Pre-defined workflow template to execute"),
+    // Custom execution plan (for mode: custom)
+    executionPlan: z
+        .object({
+        strategy: z.enum([
+            "sequential",
+            "parallel",
+            "parallel-with-join",
+            "conditional",
+            "retry-with-backoff",
+        ]),
+        steps: z.array(z.object({
+            id: z.string(),
+            toolName: z.string(),
+            args: z.unknown().describe("Arguments to pass to the tool"),
+            dependencies: z.array(z.string()).optional(),
+        })),
+        onError: z.enum(["abort", "skip", "fallback"]),
+        fallbackTool: z.string().optional(),
+        fallbackArgs: z
+            .unknown()
+            .optional()
+            .describe("Arguments for fallback tool"),
+    })
+        .optional()
+        .describe("Custom execution plan for the workflow"),
+    // Workflow parameters (passed to tools in the workflow)
+    parameters: z
+        .record(z.unknown())
+        .optional()
+        .describe("Parameters to pass to workflow steps"),
+    // Orchestration config
+    config: z
+        .object({
+        maxDepth: z.number().optional().describe("Maximum recursion depth"),
+        timeoutMs: z
+            .number()
+            .optional()
+            .describe("Per-tool timeout in milliseconds"),
+        chainTimeoutMs: z
+            .number()
+            .optional()
+            .describe("Total chain timeout in milliseconds"),
+        correlationId: z
+            .string()
+            .optional()
+            .describe("Custom correlation ID for tracing"),
+    })
+        .optional()
+        .describe("Orchestration configuration"),
+    // Output options
+    includeTrace: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Include execution trace in output"),
+    includeVisualization: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include Mermaid visualization of execution"),
+});
+/**
+ * Agent Orchestrator Tool
+ *
+ * Orchestrates multi-tool workflows with A2A chaining capabilities.
+ *
+ * @param args - Orchestrator configuration
+ * @returns Workflow execution result with trace and summary
+ */
+export async function agentOrchestrator(args) {
+    const input = AgentOrchestratorSchema.parse(args);
+    logger.info("Starting agent orchestration", {
+        mode: input.mode,
+        template: input.template,
+    });
+    // Create A2A context
+    const context = createA2AContext(input.config?.correlationId, input.config);
+    // Start tracing
+    if (input.includeTrace) {
+        traceLogger.startChain(context);
+    }
+    try {
+        // Get execution plan
+        let plan;
+        if (input.mode === "template") {
+            if (!input.template) {
+                throw new Error("Template name is required for template mode");
+            }
+            plan = getTemplateWorkflow(input.template, input.parameters || {});
+        }
+        else {
+            if (!input.executionPlan) {
+                throw new Error("Execution plan is required for custom mode");
+            }
+            plan = convertCustomPlan(input.executionPlan, input.parameters || {});
+        }
+        // Execute workflow
+        const result = await executeChain(plan, context);
+        // End tracing
+        if (input.includeTrace) {
+            traceLogger.endChain(context, result.success);
+        }
+        // Get execution summary
+        const summary = getExecutionSummary(context);
+        // Build response
+        const response = {
+            success: result.success,
+            finalOutput: result.finalOutput,
+            summary: {
+                ...result.summary,
+                correlationId: summary.correlationId,
+                maxDepthReached: summary.maxDepthReached,
+            },
+        };
+        // Add trace if requested
+        if (input.includeTrace) {
+            const trace = createTraceFromContext(context);
+            response.trace = {
+                correlationId: trace.correlationId,
+                spans: trace.spans.map((span) => ({
+                    toolName: span.toolName,
+                    durationMs: span.durationMs,
+                    status: span.status,
+                    depth: span.depth,
+                })),
+            };
+        }
+        // Add visualization if requested
+        if (input.includeVisualization) {
+            response.visualization = generateWorkflowVisualization(context, result);
+        }
+        // Add step details
+        response.steps = Array.from(result.stepResults.entries()).map(([id, stepResult]) => ({
+            id,
+            success: stepResult.success,
+            error: stepResult.error,
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        // End tracing with error
+        if (input.includeTrace) {
+            traceLogger.endChain(context, false, error instanceof Error ? error.message : String(error));
+        }
+        logger.error("Agent orchestration failed", {
+            error: error instanceof Error ? error.message : String(error),
+            correlationId: context.correlationId,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                        correlationId: context.correlationId,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Get pre-defined workflow template
+ */
+function getTemplateWorkflow(template, parameters) {
+    switch (template) {
+        case "quality-audit":
+            return {
+                strategy: "sequential",
+                onError: "abort",
+                steps: [
+                    {
+                        id: "clean-code",
+                        toolName: "clean-code-scorer",
+                        args: {
+                            projectPath: parameters.projectPath || ".",
+                            ...parameters,
+                        },
+                    },
+                    {
+                        id: "code-hygiene",
+                        toolName: "code-hygiene-analyzer",
+                        args: {
+                            codeContent: parameters.codeContent || "",
+                            language: parameters.language || "typescript",
+                            ...parameters,
+                        },
+                        dependencies: ["clean-code"],
+                    },
+                ],
+            };
+        case "security-scan":
+            return {
+                strategy: "parallel",
+                onError: "skip",
+                steps: [
+                    {
+                        id: "dependency-audit",
+                        toolName: "dependency-auditor",
+                        args: {
+                            dependencyContent: parameters.dependencyContent || "",
+                            ...parameters,
+                        },
+                    },
+                    {
+                        id: "security-hardening",
+                        toolName: "security-hardening-prompt-builder",
+                        args: {
+                            codeContext: parameters.codeContext || "",
+                            ...parameters,
+                        },
+                    },
+                ],
+            };
+        case "code-analysis-pipeline":
+            return {
+                strategy: "sequential",
+                onError: "abort",
+                steps: [
+                    {
+                        id: "semantic-analysis",
+                        toolName: "semantic-code-analyzer",
+                        args: {
+                            codeContent: parameters.codeContent || "",
+                            ...parameters,
+                        },
+                    },
+                    {
+                        id: "clean-code-score",
+                        toolName: "clean-code-scorer",
+                        args: {
+                            projectPath: parameters.projectPath || ".",
+                            ...parameters,
+                        },
+                        dependencies: ["semantic-analysis"],
+                    },
+                    {
+                        id: "diagram-generation",
+                        toolName: "mermaid-diagram-generator",
+                        args: {
+                            description: parameters.description || "Code analysis results",
+                            diagramType: "flowchart",
+                            ...parameters,
+                        },
+                        dependencies: ["clean-code-score"],
+                    },
+                ],
+            };
+        case "documentation-generation":
+            return {
+                strategy: "sequential",
+                onError: "abort",
+                steps: [
+                    {
+                        id: "project-onboarding",
+                        toolName: "project-onboarding",
+                        args: {
+                            projectPath: parameters.projectPath || ".",
+                            ...parameters,
+                        },
+                    },
+                    {
+                        id: "doc-generation",
+                        toolName: "documentation-generator-prompt-builder",
+                        args: {
+                            contentType: parameters.contentType || "API",
+                            ...parameters,
+                        },
+                        dependencies: ["project-onboarding"],
+                    },
+                ],
+            };
+    }
+}
+/**
+ * Convert custom execution plan to internal format
+ */
+function convertCustomPlan(customPlan, parameters) {
+    const steps = customPlan.steps.map((step) => ({
+        id: step.id,
+        toolName: step.toolName,
+        args: typeof step.args === "object" && step.args !== null
+            ? { ...step.args, ...parameters }
+            : parameters || step.args,
+        dependencies: step.dependencies,
+    }));
+    return {
+        strategy: customPlan.strategy,
+        steps,
+        onError: customPlan.onError,
+        fallbackTool: customPlan.fallbackTool,
+        fallbackArgs: customPlan.fallbackArgs,
+    };
+}
+/**
+ * Generate Mermaid visualization of workflow execution
+ */
+function generateWorkflowVisualization(context, _result) {
+    const lines = ["```mermaid", "graph TD"];
+    // Add nodes for each tool invocation
+    for (const entry of context.executionLog) {
+        const nodeId = `${entry.toolName}_${entry.depth}`;
+        const status = entry.status === "success" ? "✅" : "❌";
+        const label = `${status} ${entry.toolName}<br/>${entry.durationMs}ms`;
+        lines.push(`    ${nodeId}["${label}"]`);
+        // Add edge from parent if exists
+        if (entry.parentToolName) {
+            const parentId = `${entry.parentToolName}_${entry.depth - 1}`;
+            lines.push(`    ${parentId} --> ${nodeId}`);
+        }
+    }
+    lines.push("```");
+    return lines.join("\n");
+}
+//# sourceMappingURL=agent-orchestrator.js.map

package/dist/tools/agent-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-orchestrator.js","sourceRoot":"","sources":["../../src/tools/agent-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEN,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIN,YAAY,GACZ,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAW/E;;GAEG;AACH,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,0BAA0B;IAC1B,IAAI,EAAE,CAAC;SACL,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;SAC5B,QAAQ,CACR,6EAA6E,CAC7E;IAEF,yCAAyC;IACzC,QAAQ,EAAE,CAAC;SACT,IAAI,CAAC;QACL,eAAe;QACf,eAAe;QACf,wBAAwB;QACxB,0BAA0B;KAC1B,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,0CAA0C,CAAC;IAEtD,2CAA2C;IAC3C,aAAa,EAAE,CAAC;SACd,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC;YAChB,YAAY;YACZ,UAAU;YACV,oBAAoB;YACpB,aAAa;YACb,oBAAoB;SACpB,CAAC;QACF,KAAK,EAAE,CAAC,CAAC,KAAK,CACb,CAAC,CAAC,MAAM,CAAC;YACR,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;YACd,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;YACpB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;YAC3D,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;SAC5C,CAAC,CACF;QACD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QAC9C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACnC,YAAY,EAAE,CAAC;aACb,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,6BAA6B,CAAC;KACzC,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,wCAAwC,CAAC;IAEpD,wDAAwD;IACxD,UAAU,EAAE,CAAC;SACX,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnB,QAAQ,EAAE;SACV,QAAQ,CAAC,sCAAsC,CAAC;IAElD,uBAAuB;IACvB,MAAM,EAAE,CAAC;SACP,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QACnE,SAAS,EAAE,CAAC;aACV,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kCAAkC,CAAC;QAC9C,cAAc,EAAE,CAAC;aACf,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,qCAAqC,CAAC;QACjD,aAAa,EAAE,CAAC;aACd,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,mCAAmC,CAAC;KAC/C,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,6BAA6B,CAAC;IAEzC,iBAAiB;IACjB,YAAY,EAAE,CAAC;SACb,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,mCAAmC,CAAC;IAC/C,oBAAoB,EAAE,CAAC;SACrB,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,4CAA4C,CAAC;CACxD,CAAC,CAAC;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAa;IACpD,MAAM,KAAK,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAElD,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;QAC3C,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACxB,CAAC,CAAC;IAEH,qBAAqB;IACrB,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5E,gBAAgB;IAChB,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,CAAC;QACJ,qBAAqB;QACrB,IAAI,IAAmB,CAAC;QACxB,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;YAChE,CAAC;YACD,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC/D,CAAC;YACD,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,mBAAmB;QACnB,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAEjD,cAAc;QACd,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACxB,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QAED,wBAAwB;QACxB,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAE7C,iBAAiB;QACjB,MAAM,QAAQ,GAA4B;YACzC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,OAAO,EAAE;gBACR,GAAG,MAAM,CAAC,OAAO;gBACjB,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,eAAe,EAAE,OAAO,CAAC,eAAe;aACxC;SACD,CAAC;QAEF,yBAAyB;QACzB,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;YAC9C,QAAQ,CAAC,KAAK,GAAG;gBAChB,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;oBACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;iBACjB,CAAC,CAAC;aACH,CAAC;QACH,CAAC;QAED,iCAAiC;QACjC,IAAI,KAAK,CAAC,oBAAoB,EAAE,CAAC;YAChC,QAAQ,CAAC,aAAa,GAAG,6BAA6B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzE,CAAC;QAED,mBAAmB;QACnB,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAC5D,CAAC,CAAC,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,EAAE;YACF,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,KAAK,EAAE,UAAU,CAAC,KAAK;SACvB,CAAC,CACF,CAAC;QAEF,OAAO;YACN,OAAO,EAAE;gBACR;oBACC,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACvC;aACD;SACD,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,yBAAyB;QACzB,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACxB,WAAW,CAAC,QAAQ,CACnB,OAAO,EACP,KAAK,EACL,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACtD,CAAC;QACH,CAAC;QAED,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE;YAC1C,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YAC7D,aAAa,EAAE,OAAO,CAAC,aAAa;SACpC,CAAC,CAAC;QAEH,OAAO;YACN,OAAO,EAAE;gBACR;oBACC,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CACnB;wBACC,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;wBAC7D,aAAa,EAAE,OAAO,CAAC,aAAa;qBACpC,EACD,IAAI,EACJ,CAAC,CACD;iBACD;aACD;YACD,OAAO,EAAE,IAAI;SACb,CAAC;IACH,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAC3B,QAA0B,EAC1B,UAAmC;IAEnC,QAAQ,QAAQ,EAAE,CAAC;QAClB,KAAK,eAAe;YACnB,OAAO;gBACN,QAAQ,EAAE,YAAY;gBACtB,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACN;wBACC,EAAE,EAAE,YAAY;wBAChB,QAAQ,EAAE,mBAAmB;wBAC7B,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,GAAG;4BAC1C,GAAG,UAAU;yBACb;qBACD;oBACD;wBACC,EAAE,EAAE,cAAc;wBAClB,QAAQ,EAAE,uBAAuB;wBACjC,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;4BACzC,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,YAAY;4BAC7C,GAAG,UAAU;yBACb;wBACD,YAAY,EAAE,CAAC,YAAY,CAAC;qBAC5B;iBACD;aACD,CAAC;QAEH,KAAK,eAAe;YACnB,OAAO;gBACN,QAAQ,EAAE,UAAU;gBACpB,OAAO,EAAE,MAAM;gBACf,KAAK,EAAE;oBACN;wBACC,EAAE,EAAE,kBAAkB;wBACtB,QAAQ,EAAE,oBAAoB;wBAC9B,IAAI,EAAE;4BACL,iBAAiB,EAAE,UAAU,CAAC,iBAAiB,IAAI,EAAE;4BACrD,GAAG,UAAU;yBACb;qBACD;oBACD;wBACC,EAAE,EAAE,oBAAoB;wBACxB,QAAQ,EAAE,mCAAmC;wBAC7C,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;4BACzC,GAAG,UAAU;yBACb;qBACD;iBACD;aACD,CAAC;QAEH,KAAK,wBAAwB;YAC5B,OAAO;gBACN,QAAQ,EAAE,YAAY;gBACtB,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACN;wBACC,EAAE,EAAE,mBAAmB;wBACvB,QAAQ,EAAE,wBAAwB;wBAClC,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;4BACzC,GAAG,UAAU;yBACb;qBACD;oBACD;wBACC,EAAE,EAAE,kBAAkB;wBACtB,QAAQ,EAAE,mBAAmB;wBAC7B,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,GAAG;4BAC1C,GAAG,UAAU;yBACb;wBACD,YAAY,EAAE,CAAC,mBAAmB,CAAC;qBACnC;oBACD;wBACC,EAAE,EAAE,oBAAoB;wBACxB,QAAQ,EAAE,2BAA2B;wBACrC,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,uBAAuB;4BAC9D,WAAW,EAAE,WAAW;4BACxB,GAAG,UAAU;yBACb;wBACD,YAAY,EAAE,CAAC,kBAAkB,CAAC;qBAClC;iBACD;aACD,CAAC;QAEH,KAAK,0BAA0B;YAC9B,OAAO;gBACN,QAAQ,EAAE,YAAY;gBACtB,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACN;wBACC,EAAE,EAAE,oBAAoB;wBACxB,QAAQ,EAAE,oBAAoB;wBAC9B,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,GAAG;4BAC1C,GAAG,UAAU;yBACb;qBACD;oBACD;wBACC,EAAE,EAAE,gBAAgB;wBACpB,QAAQ,EAAE,wCAAwC;wBAClD,IAAI,EAAE;4BACL,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,KAAK;4BAC5C,GAAG,UAAU;yBACb;wBACD,YAAY,EAAE,CAAC,oBAAoB,CAAC;qBACpC;iBACD;aACD,CAAC;IACJ,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CACzB,UAAgE,EAChE,UAAmC;IAEnC,MAAM,KAAK,GAAoB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9D,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EACH,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAClD,CAAC,CAAC,EAAE,GAAI,IAAI,CAAC,IAAgC,EAAE,GAAG,UAAU,EAAE;YAC9D,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI;QAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;KAC/B,CAAC,CAAC,CAAC;IAEJ,OAAO;QACN,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,KAAK;QACL,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,YAAY,EAAE,UAAU,CAAC,YAAY;QACrC,YAAY,EAAE,UAAU,CAAC,YAAY;KACrC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,6BAA6B,CACrC,OAAmB,EACnB,OAAoB;IAEpB,MAAM,KAAK,GAAa,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAEnD,qCAAqC;IACrC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QACtD,MAAM,KAAK,GAAG,GAAG,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,KAAK,CAAC,UAAU,IAAI,CAAC;QAEtE,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,KAAK,KAAK,IAAI,CAAC,CAAC;QAExC,iCAAiC;QACjC,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAC9D,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,QAAQ,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;IACF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAElB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/tools/shared/a2a-context.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Agent-to-Agent (A2A) Context Management
+ *
+ * Provides context propagation, state management, and execution tracing
+ * for tool-to-tool invocation chains within the MCP server.
+ *
+ * Key Features:
+ * - Correlation ID tracking for distributed tracing
+ * - Recursion depth guards to prevent infinite loops
+ * - Shared state management across tool invocations
+ * - Execution audit trail for observability
+ * - Timeout enforcement per step and total chain
+ */
+/**
+ * Execution log entry for a single tool invocation
+ */
+export interface ExecutionLogEntry {
+    /** Timestamp when the tool was invoked */
+    timestamp: Date;
+    /** Name of the tool that was invoked */
+    toolName: string;
+    /** Hash of input parameters for deduplication */
+    inputHash: string;
+    /** Summary of the tool's output */
+    outputSummary: string;
+    /** Duration of tool execution in milliseconds */
+    durationMs: number;
+    /** Execution status */
+    status: "success" | "error" | "skipped";
+    /** Error details if status is 'error' */
+    errorDetails?: string;
+    /** Parent tool that invoked this tool (if nested) */
+    parentToolName?: string;
+    /** Nesting depth at time of invocation */
+    depth: number;
+}
+/**
+ * A2A Context for managing tool-to-tool invocation state
+ *
+ * This context is passed between tools during orchestration to:
+ * - Track execution flow with correlation IDs
+ * - Prevent infinite recursion with depth tracking
+ * - Share state between tool invocations
+ * - Maintain audit trail for debugging and monitoring
+ */
+export interface A2AContext {
+    /** Unique trace ID for the entire invocation chain */
+    correlationId: string;
+    /** Name of the calling tool (undefined for initial invocation) */
+    parentToolName?: string;
+    /** Current nesting depth (0 for top-level invocation) */
+    depth: number;
+    /** Maximum allowed recursion depth (default: 10) */
+    maxDepth: number;
+    /** Shared state accessible to all tools in the chain */
+    sharedState: Map<string, unknown>;
+    /** Audit trail of all tool invocations */
+    executionLog: ExecutionLogEntry[];
+    /** Timeout for individual tool invocations (milliseconds) */
+    timeoutMs?: number;
+    /** Start time of the entire chain execution */
+    chainStartTime: Date;
+    /** Maximum total chain execution time (milliseconds) */
+    chainTimeoutMs?: number;
+}
+/**
+ * Default configuration for A2A contexts
+ */
+export declare const A2A_DEFAULTS: {
+    /** Default maximum recursion depth */
+    readonly MAX_DEPTH: 10;
+    /** Default per-tool timeout (30 seconds) */
+    readonly DEFAULT_TIMEOUT_MS: 30000;
+    /** Default total chain timeout (5 minutes) */
+    readonly DEFAULT_CHAIN_TIMEOUT_MS: 300000;
+};
+/**
+ * Create a new A2A context for a top-level tool invocation
+ *
+ * @param correlationId - Optional correlation ID (generated if not provided)
+ * @param config - Optional configuration overrides
+ * @returns A new A2A context
+ */
+export declare function createA2AContext(correlationId?: string, config?: {
+    maxDepth?: number;
+    timeoutMs?: number;
+    chainTimeoutMs?: number;
+}): A2AContext;
+/**
+ * Create a child context for a nested tool invocation
+ *
+ * @param parent - Parent context
+ * @param toolName - Name of the calling tool
+ * @returns A new child context
+ * @throws Error if maximum depth would be exceeded
+ */
+export declare function createChildContext(parent: A2AContext, toolName: string): A2AContext;
+/**
+ * Add an execution log entry to the context
+ *
+ * @param context - A2A context
+ * @param entry - Execution log entry to add
+ */
+export declare function addExecutionLogEntry(context: A2AContext, entry: Omit<ExecutionLogEntry, "timestamp" | "depth">): void;
+/**
+ * Check if the chain has exceeded its total timeout
+ *
+ * @param context - A2A context
+ * @returns true if chain has timed out
+ */
+export declare function hasChainTimedOut(context: A2AContext): boolean;
+/**
+ * Get remaining time in milliseconds for the chain
+ *
+ * @param context - A2A context
+ * @returns Remaining time in milliseconds (undefined if no timeout set)
+ */
+export declare function getRemainingChainTime(context: A2AContext): number | undefined;
+/**
+ * Create a hash of input parameters for deduplication
+ *
+ * @param input - Input parameters
+ * @returns Hash string
+ *
+ * @remarks
+ * This is a demonstration implementation using a simple string-based hash.
+ * For production deployments, replace with a proper hashing library like
+ * `crypto.createHash('sha256')` for better collision resistance and performance
+ * with large inputs.
+ *
+ * @example
+ * ```typescript
+ * // Production implementation:
+ * import { createHash } from 'crypto';
+ * const hash = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+ * ```
+ */
+export declare function hashInput(input: unknown): string;
+/**
+ * Get execution summary from context
+ *
+ * @param context - A2A context
+ * @returns Execution summary
+ */
+export declare function getExecutionSummary(context: A2AContext): {
+    correlationId: string;
+    totalDurationMs: number;
+    toolCount: number;
+    successCount: number;
+    errorCount: number;
+    skippedCount: number;
+    maxDepthReached: number;
+};
+//# sourceMappingURL=a2a-context.d.ts.map

package/dist/tools/shared/a2a-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-context.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/a2a-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,0CAA0C;IAC1C,SAAS,EAAE,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IAC1B,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,0CAA0C;IAC1C,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,cAAc,EAAE,IAAI,CAAC;IACrB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;IACxB,sCAAsC;;IAEtC,4CAA4C;;IAE5C,8CAA8C;;CAErC,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,GACC,UAAU,CAYZ;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,GACd,UAAU,CAkBZ;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,OAAO,CAAC,GACnD,IAAI,CAMN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAO7D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAQ7E;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAahD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACxB,CAgCA"}