agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/discovery/discovery-service.d.ts

@@ -0,0 +1,296 @@
+/**
+ * A2A Discovery Service
+ *
+ * Provides agent discovery functionality per RFC 8615 well-known URI standard.
+ * Supports platform aggregate cards, individual agent cards, and extended cards
+ * for authenticated clients.
+ *
+ * @module adapters/a2a/discovery/discovery-service
+ * @see https://tools.ietf.org/html/rfc8615
+ * @see https://a2a-protocol.org/latest/topics/agent-discovery/
+ */
+import { AgentCard, QEAgentCard, ExtendedAgentCard, AgentCapabilities } from '../agent-cards/schema.js';
+import { AgentCardGenerator } from '../agent-cards/generator.js';
+/**
+ * Configuration for the Discovery Service
+ */
+export interface DiscoveryServiceConfig {
+    /** Agent card generator instance */
+    readonly generator: AgentCardGenerator;
+    /** Base URL for the platform */
+    readonly baseUrl: string;
+    /** Cache TTL in milliseconds (default: 1 hour) */
+    readonly cacheTtl?: number;
+    /** Platform name for aggregate card */
+    readonly platformName?: string;
+    /** Platform description */
+    readonly platformDescription?: string;
+    /** Platform version */
+    readonly platformVersion?: string;
+    /** Enable access metrics tracking */
+    readonly enableMetrics?: boolean;
+}
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_DISCOVERY_CONFIG: {
+    readonly cacheTtl: 3600000;
+    readonly platformName: "Agentic QE Platform";
+    readonly platformDescription: "AI-powered Quality Engineering platform with 68+ specialized agents";
+    readonly platformVersion: "3.0.0";
+    readonly enableMetrics: true;
+};
+/**
+ * Access metrics for a card
+ */
+export interface CardAccessMetrics {
+    readonly agentId: string;
+    readonly accessCount: number;
+    readonly lastAccessedAt: number;
+    readonly extendedAccessCount: number;
+}
+/**
+ * Search criteria for finding agents
+ */
+export interface AgentSearchCriteria {
+    /** Filter by capability */
+    readonly capability?: keyof AgentCapabilities;
+    /** Filter by skill ID */
+    readonly skill?: string;
+    /** Filter by tag */
+    readonly tag?: string;
+    /** Filter by domain (QE-specific) */
+    readonly domain?: string;
+    /** Filter by streaming support */
+    readonly streaming?: boolean;
+    /** Maximum results to return */
+    readonly limit?: number;
+}
+/**
+ * Search result
+ */
+export interface AgentSearchResult {
+    readonly agents: QEAgentCard[];
+    readonly total: number;
+    readonly criteria: AgentSearchCriteria;
+}
+/**
+ * Rate limit information for extended cards
+ */
+export interface RateLimitInfo {
+    readonly requestsPerMinute: number;
+    readonly requestsPerHour: number;
+    readonly requestsPerDay: number;
+}
+/**
+ * Usage statistics for extended cards
+ */
+export interface UsageStats {
+    readonly totalRequests: number;
+    readonly successfulRequests: number;
+    readonly failedRequests: number;
+    readonly averageResponseTimeMs: number;
+}
+/**
+ * Extended card data available to authenticated clients
+ */
+export interface ExtendedCardData {
+    readonly rateLimits: RateLimitInfo;
+    readonly usageStats?: UsageStats;
+    readonly supportContact?: string;
+    readonly sla?: {
+        readonly uptimeTarget: number;
+        readonly responseTimeTarget: number;
+    };
+    readonly authenticationRequired: boolean;
+    readonly requiredScopes?: string[];
+}
+/**
+ * Discovery Service for A2A agent discovery
+ *
+ * Provides RFC 8615 compliant agent discovery with caching, metrics tracking,
+ * and support for extended cards for authenticated clients.
+ */
+export declare class DiscoveryService {
+    private readonly config;
+    /** Cache for individual agent cards */
+    private readonly cardCache;
+    /** Cache for platform aggregate card */
+    private platformCardCache;
+    /** Access metrics by agent ID */
+    private readonly accessMetrics;
+    /** All loaded agent cards */
+    private agentCards;
+    /** Flag indicating if cards have been loaded */
+    private cardsLoaded;
+    constructor(config: DiscoveryServiceConfig);
+    /**
+     * Load agent cards from the generator
+     */
+    loadCards(agentsBasePath: string): Promise<void>;
+    /**
+     * Register a pre-generated agent card
+     */
+    registerCard(card: QEAgentCard): void;
+    /**
+     * Register multiple pre-generated agent cards
+     */
+    registerCards(cards: Map<string, QEAgentCard>): void;
+    /**
+     * Check if cards have been loaded
+     */
+    hasLoadedCards(): boolean;
+    /**
+     * Get the number of registered agents
+     */
+    getAgentCount(): number;
+    /**
+     * Get the aggregate platform card
+     *
+     * Returns a card representing the entire QE platform with aggregated
+     * capabilities and skills from all registered agents.
+     */
+    getPlatformCard(): Promise<AgentCard>;
+    /**
+     * Get the ETag for the platform card
+     */
+    getPlatformCardEtag(): string | null;
+    /**
+     * Generate the aggregate platform card
+     */
+    private generatePlatformCard;
+    /**
+     * Get an individual agent card by ID
+     *
+     * @param agentId - The agent identifier (e.g., 'qe-test-architect')
+     * @returns The agent card or null if not found
+     */
+    getAgentCard(agentId: string): Promise<QEAgentCard | null>;
+    /**
+     * Get the ETag for an agent card
+     */
+    getAgentCardEtag(agentId: string): string | null;
+    /**
+     * Check if an agent exists
+     */
+    hasAgent(agentId: string): boolean;
+    /**
+     * Get all registered agent IDs
+     */
+    getAgentIds(): string[];
+    /**
+     * Get an extended agent card for authenticated clients
+     *
+     * Extended cards include additional information such as rate limits,
+     * usage statistics, and authentication requirements.
+     *
+     * @param agentId - The agent identifier
+     * @returns Extended agent card or null if not found
+     */
+    getExtendedAgentCard(agentId: string): Promise<ExtendedAgentCard | null>;
+    /**
+     * Get default rate limits for agents
+     */
+    private getDefaultRateLimits;
+    /**
+     * Get required scopes for an agent
+     */
+    private getRequiredScopesForAgent;
+    /**
+     * Find agents by capability
+     *
+     * @param capability - The capability to filter by (e.g., 'streaming')
+     * @returns List of agents that support the capability
+     */
+    findByCapability(capability: keyof AgentCapabilities): Promise<QEAgentCard[]>;
+    /**
+     * Find agents by skill ID
+     *
+     * @param skillId - The skill ID to search for
+     * @returns List of agents that have the skill
+     */
+    findBySkill(skillId: string): Promise<QEAgentCard[]>;
+    /**
+     * Find agents by tag
+     *
+     * @param tag - The tag to search for
+     * @returns List of agents that have the tag
+     */
+    findByTag(tag: string): Promise<QEAgentCard[]>;
+    /**
+     * Find agents by domain (QE-specific)
+     *
+     * @param domain - The domain to filter by (e.g., 'test-generation')
+     * @returns List of agents in the domain
+     */
+    findByDomain(domain: string): Promise<QEAgentCard[]>;
+    /**
+     * Search agents with multiple criteria
+     *
+     * @param criteria - Search criteria
+     * @returns Search result with matching agents
+     */
+    search(criteria: AgentSearchCriteria): Promise<AgentSearchResult>;
+    /**
+     * Get access metrics for an agent
+     */
+    getAccessMetrics(agentId: string): CardAccessMetrics | null;
+    /**
+     * Get all access metrics
+     */
+    getAllAccessMetrics(): CardAccessMetrics[];
+    /**
+     * Record an access to an agent card
+     */
+    private recordAccess;
+    /**
+     * Check if a cache entry is expired
+     */
+    private isCacheExpired;
+    /**
+     * Generate an ETag for a card
+     */
+    private generateEtag;
+    /**
+     * Invalidate cache for a specific agent
+     */
+    invalidateCache(agentId: string): void;
+    /**
+     * Invalidate all caches
+     */
+    invalidateAllCaches(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        cardCacheSize: number;
+        hasPlatformCard: boolean;
+        oldestEntry: number | null;
+    };
+}
+/**
+ * Create a Discovery Service instance
+ *
+ * @param config - Service configuration
+ * @returns Discovery service instance
+ *
+ * @example
+ * ```typescript
+ * const discovery = createDiscoveryService({
+ *   generator: agentCardGenerator,
+ *   baseUrl: 'https://qe.example.com',
+ *   cacheTtl: 3600000, // 1 hour
+ * });
+ *
+ * // Get platform card
+ * const platformCard = await discovery.getPlatformCard();
+ *
+ * // Get agent card
+ * const agentCard = await discovery.getAgentCard('qe-test-architect');
+ *
+ * // Search by capability
+ * const agents = await discovery.findByCapability('streaming');
+ * ```
+ */
+export declare function createDiscoveryService(config: DiscoveryServiceConfig): DiscoveryService;
+//# sourceMappingURL=discovery-service.d.ts.map

package/v3/dist/adapters/a2a/discovery/discovery-service.d.ts.map

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