agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/tasks/task-router.d.ts

@@ -0,0 +1,270 @@
+/**
+ * A2A Task Router
+ *
+ * Routes incoming tasks to appropriate agents based on their capabilities,
+ * skills, and current load. Integrates with the discovery service for
+ * agent capability matching.
+ *
+ * @module adapters/a2a/tasks/task-router
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+import { EventEmitter } from 'events';
+import type { A2AMessage } from '../jsonrpc/methods.js';
+import type { DiscoveryService } from '../discovery/discovery-service.js';
+import type { QEAgentCard, AgentSkill, AgentCapabilities } from '../agent-cards/schema.js';
+import type { A2ATask } from './task-store.js';
+/**
+ * Routing decision result
+ */
+export interface RoutingDecision {
+    /** Selected agent ID */
+    readonly agentId: string;
+    /** Agent card */
+    readonly agentCard: QEAgentCard;
+    /** Matched skill (if any) */
+    readonly matchedSkill?: AgentSkill;
+    /** Routing score (0-1) */
+    readonly score: number;
+    /** Reason for selection */
+    readonly reason: string;
+    /** Alternative agents considered */
+    readonly alternatives: AlternativeAgent[];
+}
+/**
+ * Alternative agent considered during routing
+ */
+export interface AlternativeAgent {
+    /** Agent ID */
+    readonly agentId: string;
+    /** Score */
+    readonly score: number;
+    /** Reason not selected */
+    readonly reason: string;
+}
+/**
+ * Routing request with context
+ */
+export interface RoutingRequest {
+    /** The message to route */
+    readonly message: A2AMessage;
+    /** Preferred agent ID (optional) */
+    readonly preferredAgentId?: string;
+    /** Required capabilities */
+    readonly requiredCapabilities?: (keyof AgentCapabilities)[];
+    /** Required skill */
+    readonly requiredSkill?: string;
+    /** Required tags */
+    readonly requiredTags?: string[];
+    /** Required domain */
+    readonly requiredDomain?: string;
+    /** Context ID for multi-turn routing */
+    readonly contextId?: string;
+    /** Priority level */
+    readonly priority?: 'low' | 'normal' | 'high' | 'urgent';
+    /** Whether to exclude overloaded agents */
+    readonly excludeOverloaded?: boolean;
+}
+/**
+ * Agent load information for load balancing
+ */
+export interface AgentLoad {
+    /** Agent ID */
+    readonly agentId: string;
+    /** Number of active tasks */
+    readonly activeTasks: number;
+    /** Maximum concurrent tasks */
+    readonly maxTasks: number;
+    /** Current load percentage (0-100) */
+    readonly loadPercentage: number;
+    /** Average response time in ms */
+    readonly avgResponseTime: number;
+    /** Last updated timestamp */
+    readonly lastUpdated: Date;
+}
+/**
+ * Score weights for routing factors (all required for type safety)
+ */
+export interface ScoreWeights {
+    readonly skillMatch: number;
+    readonly tagMatch: number;
+    readonly loadBalance: number;
+    readonly capability: number;
+    readonly domain: number;
+}
+/**
+ * Default score weights - single source of truth
+ */
+export declare const DEFAULT_SCORE_WEIGHTS: ScoreWeights;
+/**
+ * Task router configuration
+ */
+export interface TaskRouterConfig {
+    /** Discovery service for agent lookup */
+    readonly discoveryService: DiscoveryService;
+    /** Default maximum tasks per agent */
+    readonly defaultMaxTasksPerAgent?: number;
+    /** Load percentage threshold for considering agent overloaded */
+    readonly overloadThreshold?: number;
+    /** Whether to enable skill-based routing */
+    readonly enableSkillRouting?: boolean;
+    /** Whether to enable load balancing */
+    readonly enableLoadBalancing?: boolean;
+    /** Minimum score threshold for agent selection */
+    readonly minScoreThreshold?: number;
+    /** Score weights for routing factors (partial allowed, merged with defaults) */
+    readonly scoreWeights?: Partial<ScoreWeights>;
+}
+/**
+ * Default router configuration
+ */
+export declare const DEFAULT_ROUTER_CONFIG: Required<Omit<TaskRouterConfig, 'discoveryService' | 'scoreWeights'>> & {
+    scoreWeights: ScoreWeights;
+};
+/**
+ * Priority queue item for task routing
+ */
+export interface QueuedTask {
+    /** Task ID */
+    readonly taskId: string;
+    /** Message */
+    readonly message: A2AMessage;
+    /** Routing request */
+    readonly request: RoutingRequest;
+    /** Queued timestamp */
+    readonly queuedAt: Date;
+    /** Priority value (higher = more urgent) */
+    readonly priorityValue: number;
+}
+/**
+ * A2A Task Router
+ *
+ * Routes tasks to capable agents using skill matching, load balancing,
+ * and priority queuing.
+ */
+export declare class TaskRouter extends EventEmitter {
+    private readonly config;
+    private readonly agentLoads;
+    private readonly contextAgentMapping;
+    private readonly taskQueue;
+    private readonly skillKeywordMap;
+    constructor(config: TaskRouterConfig);
+    /**
+     * Route a message to an appropriate agent
+     */
+    route(request: RoutingRequest): Promise<RoutingDecision>;
+    /**
+     * Route and assign task to agent, returning the agent ID
+     */
+    routeTask(task: A2ATask, request: Omit<RoutingRequest, 'message'>): Promise<RoutingDecision>;
+    /**
+     * Update agent load information
+     */
+    updateAgentLoad(agentId: string, activeTasks: number, avgResponseTime?: number): void;
+    /**
+     * Set maximum tasks for an agent
+     */
+    setAgentMaxTasks(agentId: string, maxTasks: number): void;
+    /**
+     * Increment agent load (when task is assigned)
+     */
+    incrementAgentLoad(agentId: string): void;
+    /**
+     * Decrement agent load (when task completes)
+     */
+    decrementAgentLoad(agentId: string): void;
+    /**
+     * Get current load for an agent
+     */
+    getAgentLoad(agentId: string): AgentLoad | null;
+    /**
+     * Get all agent loads
+     */
+    getAllAgentLoads(): AgentLoad[];
+    /**
+     * Check if an agent is overloaded
+     */
+    isAgentOverloaded(agentId: string, checkEnabled?: boolean): boolean;
+    /**
+     * Add a task to the priority queue
+     */
+    enqueue(taskId: string, message: A2AMessage, request: RoutingRequest): void;
+    /**
+     * Dequeue the next task
+     */
+    dequeue(): QueuedTask | null;
+    /**
+     * Get queue length
+     */
+    get queueLength(): number;
+    /**
+     * Get queued tasks
+     */
+    getQueuedTasks(): readonly QueuedTask[];
+    /**
+     * Remove a task from the queue
+     */
+    removeFromQueue(taskId: string): boolean;
+    /**
+     * Get priority value from priority level
+     */
+    private getPriorityValue;
+    /**
+     * Get the agent assigned to a context
+     */
+    getContextAgent(contextId: string): string | null;
+    /**
+     * Set the agent for a context
+     */
+    setContextAgent(contextId: string, agentId: string): void;
+    /**
+     * Remove context-agent mapping
+     */
+    clearContextAgent(contextId: string): boolean;
+    /**
+     * Get all context mappings
+     */
+    getAllContextMappings(): Map<string, string>;
+    /**
+     * Build skill keyword map for text-based matching
+     */
+    private buildSkillKeywordMap;
+    /**
+     * Match message text to skills
+     */
+    private matchTextToSkills;
+    /**
+     * Build search criteria from routing request
+     */
+    private buildSearchCriteria;
+    /**
+     * Check if an agent meets requirements
+     */
+    private meetsRequirements;
+    /**
+     * Score and rank agents for a request
+     */
+    private scoreAgents;
+    /**
+     * Get router statistics
+     */
+    getStats(): {
+        trackedAgents: number;
+        averageLoad: number;
+        overloadedAgents: number;
+        queueLength: number;
+        contextMappings: number;
+    };
+    /**
+     * Clear all state
+     */
+    clear(): void;
+    /**
+     * Destroy the router
+     */
+    destroy(): void;
+}
+/**
+ * Create a new TaskRouter instance
+ */
+export declare function createTaskRouter(config: TaskRouterConfig): TaskRouter;
+//# sourceMappingURL=task-router.d.ts.map

package/v3/dist/adapters/a2a/tasks/task-router.d.ts.map

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