mcp-ai-agent-guidelines/dist/tools/shared/a2a-context.d.ts

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * 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