agentic-qe 3.6.0 → 3.6.2

package/v3/dist/coordination/agent-teams/mailbox.js

@@ -0,0 +1,395 @@
+/**
+ * Agentic QE v3 - Agent Teams Mailbox Service
+ * ADR-064: Per-agent message queue management
+ *
+ * Manages in-memory mailboxes for inter-agent communication.
+ * Each agent gets a dedicated mailbox that supports:
+ * - Direct message delivery (point-to-point)
+ * - Domain-wide broadcasts
+ * - TTL-based message expiration
+ * - Unread tracking with peek support
+ * - Event callbacks for message arrival
+ */
+// ============================================================================
+// Mailbox Service
+// ============================================================================
+/**
+ * Service managing per-agent message queues with in-memory storage.
+ * Provides thread-safe message delivery, broadcast support, and TTL expiration.
+ */
+export class MailboxService {
+    /** Agent mailboxes keyed by agent ID */
+    mailboxes = new Map();
+    /** Message delivery listeners keyed by agent ID */
+    messageHandlers = new Map();
+    /** Broadcast listeners keyed by domain */
+    broadcastHandlers = new Map();
+    /** Index of agents by domain for efficient broadcast */
+    domainAgents = new Map();
+    // ============================================================================
+    // Mailbox Lifecycle
+    // ============================================================================
+    /**
+     * Create a mailbox for an agent. If a mailbox already exists for this
+     * agent ID, the existing mailbox is returned unchanged.
+     *
+     * @param agentId - Unique agent identifier
+     * @param domain - Domain the agent belongs to
+     * @returns The created or existing mailbox snapshot
+     */
+    createMailbox(agentId, domain) {
+        const existing = this.mailboxes.get(agentId);
+        if (existing) {
+            return this.toSnapshot(existing);
+        }
+        const mailbox = {
+            agentId,
+            domain,
+            messages: [],
+            unreadCount: 0,
+            lastRead: Date.now(),
+        };
+        this.mailboxes.set(agentId, mailbox);
+        // Track agent in domain index
+        let agents = this.domainAgents.get(domain);
+        if (!agents) {
+            agents = new Set();
+            this.domainAgents.set(domain, agents);
+        }
+        agents.add(agentId);
+        return this.toSnapshot(mailbox);
+    }
+    /**
+     * Get the full mailbox state for an agent.
+     *
+     * @param agentId - Agent whose mailbox to retrieve
+     * @returns Mailbox snapshot or undefined if agent has no mailbox
+     */
+    getMailbox(agentId) {
+        const mailbox = this.mailboxes.get(agentId);
+        if (!mailbox)
+            return undefined;
+        return this.toSnapshot(mailbox);
+    }
+    /**
+     * Delete an agent's mailbox and remove the agent from domain tracking.
+     *
+     * @param agentId - Agent whose mailbox to delete
+     * @returns True if a mailbox was deleted, false if none existed
+     */
+    deleteMailbox(agentId) {
+        const mailbox = this.mailboxes.get(agentId);
+        if (!mailbox)
+            return false;
+        // Remove from domain index
+        const agents = this.domainAgents.get(mailbox.domain);
+        if (agents) {
+            agents.delete(agentId);
+            if (agents.size === 0) {
+                this.domainAgents.delete(mailbox.domain);
+            }
+        }
+        // Remove handlers
+        this.messageHandlers.delete(agentId);
+        // Remove mailbox
+        this.mailboxes.delete(agentId);
+        return true;
+    }
+    // ============================================================================
+    // Message Delivery
+    // ============================================================================
+    /**
+     * Send a message to a specific agent's mailbox.
+     * If the target is 'broadcast', use the `broadcast()` method instead.
+     *
+     * @param message - The message to deliver
+     * @throws Error if the target agent has no mailbox
+     */
+    send(message) {
+        if (message.to === 'broadcast') {
+            this.broadcast(message.domain, message);
+            return;
+        }
+        const mailbox = this.mailboxes.get(message.to);
+        if (!mailbox) {
+            throw new Error(`No mailbox found for agent '${message.to}'. ` +
+                `Create a mailbox first with createMailbox().`);
+        }
+        mailbox.messages.push(message);
+        mailbox.unreadCount++;
+        // Notify listeners
+        const handlers = this.messageHandlers.get(message.to);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(message);
+                }
+                catch {
+                    // Swallow handler errors to avoid breaking delivery
+                }
+            }
+        }
+    }
+    /**
+     * Broadcast a message to all agents in a domain.
+     * The sender (if they have a mailbox in the domain) is excluded.
+     *
+     * @param domain - Domain to broadcast to
+     * @param message - The message to broadcast
+     */
+    broadcast(domain, message) {
+        const agents = this.domainAgents.get(domain);
+        if (!agents)
+            return;
+        for (const agentId of agents) {
+            // Skip the sender
+            if (agentId === message.from)
+                continue;
+            const mailbox = this.mailboxes.get(agentId);
+            if (mailbox) {
+                mailbox.messages.push(message);
+                mailbox.unreadCount++;
+                // Notify per-agent listeners
+                const handlers = this.messageHandlers.get(agentId);
+                if (handlers) {
+                    for (const handler of handlers) {
+                        try {
+                            handler(message);
+                        }
+                        catch {
+                            // Swallow handler errors
+                        }
+                    }
+                }
+            }
+        }
+        // Notify broadcast listeners
+        const broadcastListeners = this.broadcastHandlers.get(domain);
+        if (broadcastListeners) {
+            for (const handler of broadcastListeners) {
+                try {
+                    handler(domain, message);
+                }
+                catch {
+                    // Swallow handler errors
+                }
+            }
+        }
+    }
+    // ============================================================================
+    // Message Retrieval
+    // ============================================================================
+    /**
+     * Retrieve unread messages for an agent, marking them as read.
+     *
+     * @param agentId - Agent whose messages to retrieve
+     * @param options - Optional filtering and limiting
+     * @returns Array of unread messages (empty if no mailbox or no unread)
+     */
+    receive(agentId, options) {
+        const mailbox = this.mailboxes.get(agentId);
+        if (!mailbox || mailbox.unreadCount === 0)
+            return [];
+        const now = Date.now();
+        const readIndex = mailbox.messages.length - mailbox.unreadCount;
+        // Get unread messages
+        let unread = mailbox.messages.slice(readIndex);
+        // Filter expired messages
+        unread = unread.filter(msg => !this.isExpired(msg, now));
+        // Apply type filter
+        if (options?.type) {
+            unread = unread.filter(msg => msg.type === options.type);
+        }
+        // Apply since filter
+        if (options?.since !== undefined) {
+            unread = unread.filter(msg => msg.timestamp >= options.since);
+        }
+        // Apply limit
+        if (options?.limit !== undefined && options.limit > 0) {
+            unread = unread.slice(0, options.limit);
+        }
+        // Mark all as read (regardless of filters, reading marks the mailbox)
+        mailbox.unreadCount = 0;
+        mailbox.lastRead = now;
+        return unread;
+    }
+    /**
+     * Check unread message count without marking any as read.
+     *
+     * @param agentId - Agent whose unread count to check
+     * @returns Number of unread messages (0 if no mailbox)
+     */
+    peek(agentId) {
+        const mailbox = this.mailboxes.get(agentId);
+        if (!mailbox)
+            return 0;
+        // Count non-expired unread messages
+        const now = Date.now();
+        const readIndex = mailbox.messages.length - mailbox.unreadCount;
+        let validCount = 0;
+        for (let i = readIndex; i < mailbox.messages.length; i++) {
+            if (!this.isExpired(mailbox.messages[i], now)) {
+                validCount++;
+            }
+        }
+        return validCount;
+    }
+    // ============================================================================
+    // Cleanup
+    // ============================================================================
+    /**
+     * Remove expired messages from all mailboxes.
+     * Messages older than `maxAge` milliseconds are removed regardless of TTL.
+     * Messages with TTL that have expired are also removed.
+     *
+     * @param maxAge - Maximum message age in milliseconds
+     * @returns Number of messages removed
+     */
+    cleanup(maxAge) {
+        const now = Date.now();
+        const cutoff = now - maxAge;
+        let removed = 0;
+        for (const mailbox of this.mailboxes.values()) {
+            const before = mailbox.messages.length;
+            const readIndex = mailbox.messages.length - mailbox.unreadCount;
+            mailbox.messages = mailbox.messages.filter((msg, index) => {
+                // Remove if older than max age
+                if (msg.timestamp < cutoff)
+                    return false;
+                // Remove if TTL expired
+                if (this.isExpired(msg, now))
+                    return false;
+                return true;
+            });
+            const removedFromMailbox = before - mailbox.messages.length;
+            removed += removedFromMailbox;
+            // Recalculate unread count
+            if (removedFromMailbox > 0) {
+                // The unread messages are at the tail. After filtering, we need
+                // to recalculate based on the new message array and lastRead.
+                mailbox.unreadCount = mailbox.messages.filter(msg => msg.timestamp > mailbox.lastRead).length;
+            }
+        }
+        return removed;
+    }
+    // ============================================================================
+    // Event Subscriptions
+    // ============================================================================
+    /**
+     * Register a handler for messages delivered to a specific agent.
+     *
+     * @param agentId - Agent whose messages to listen for
+     * @param handler - Callback invoked on each message delivery
+     * @returns Unsubscribe function
+     */
+    onMessage(agentId, handler) {
+        let handlers = this.messageHandlers.get(agentId);
+        if (!handlers) {
+            handlers = [];
+            this.messageHandlers.set(agentId, handlers);
+        }
+        handlers.push(handler);
+        return () => {
+            const list = this.messageHandlers.get(agentId);
+            if (list) {
+                const idx = list.indexOf(handler);
+                if (idx >= 0)
+                    list.splice(idx, 1);
+            }
+        };
+    }
+    /**
+     * Register a handler for broadcasts to a specific domain.
+     *
+     * @param domain - Domain to listen for broadcasts on
+     * @param handler - Callback invoked on each broadcast
+     * @returns Unsubscribe function
+     */
+    onBroadcast(domain, handler) {
+        let handlers = this.broadcastHandlers.get(domain);
+        if (!handlers) {
+            handlers = [];
+            this.broadcastHandlers.set(domain, handlers);
+        }
+        handlers.push(handler);
+        return () => {
+            const list = this.broadcastHandlers.get(domain);
+            if (list) {
+                const idx = list.indexOf(handler);
+                if (idx >= 0)
+                    list.splice(idx, 1);
+            }
+        };
+    }
+    // ============================================================================
+    // Query Methods
+    // ============================================================================
+    /**
+     * Get all agent IDs that have mailboxes in a given domain.
+     *
+     * @param domain - Domain to query
+     * @returns Array of agent IDs
+     */
+    getAgentsInDomain(domain) {
+        const agents = this.domainAgents.get(domain);
+        return agents ? Array.from(agents) : [];
+    }
+    /**
+     * Get all registered domains.
+     *
+     * @returns Array of domain names
+     */
+    getDomains() {
+        return Array.from(this.domainAgents.keys());
+    }
+    /**
+     * Get total number of mailboxes.
+     */
+    get size() {
+        return this.mailboxes.size;
+    }
+    /**
+     * Clear all mailboxes, handlers, and domain indexes.
+     */
+    clear() {
+        this.mailboxes.clear();
+        this.messageHandlers.clear();
+        this.broadcastHandlers.clear();
+        this.domainAgents.clear();
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /**
+     * Check if a message has expired based on its TTL.
+     */
+    isExpired(message, now) {
+        if (!message.ttl || message.ttl <= 0)
+            return false;
+        return now > message.timestamp + message.ttl;
+    }
+    /**
+     * Create an immutable snapshot of a mutable mailbox.
+     */
+    toSnapshot(mailbox) {
+        return {
+            agentId: mailbox.agentId,
+            domain: mailbox.domain,
+            messages: [...mailbox.messages],
+            unreadCount: mailbox.unreadCount,
+            lastRead: mailbox.lastRead,
+        };
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new MailboxService instance.
+ *
+ * @returns A fresh MailboxService
+ */
+export function createMailboxService() {
+    return new MailboxService();
+}
+//# sourceMappingURL=mailbox.js.map

package/v3/dist/coordination/agent-teams/mailbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.js","sourceRoot":"","sources":["../../../src/coordination/agent-teams/mailbox.ts"],"names":[],"mappings":"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"}

package/v3/dist/coordination/agent-teams/tracing.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Agentic QE v3 - Distributed Tracing for Agent Teams
+ * ADR-064 Phase 3: Learning & Observability
+ *
+ * Provides trace context propagation across agent messages, enabling
+ * end-to-end visibility into multi-agent workflows. Trace contexts are
+ * encoded into the existing `correlationId` field on AgentMessage so
+ * no schema changes are required.
+ *
+ * Usage:
+ * ```typescript
+ * import { createTraceCollector, encodeTraceContext } from './tracing.js';
+ *
+ * const collector = createTraceCollector();
+ *
+ * // Start a root trace for an incoming request
+ * const { context, span } = collector.startTrace({
+ *   operationName: 'generate-tests',
+ *   agentId: 'lead-1',
+ *   domain: 'test-generation',
+ * });
+ *
+ * // Propagate context via correlationId
+ * adapter.sendMessage('lead-1', 'agent-a', 'task-assignment', payload, {
+ *   correlationId: encodeTraceContext(context),
+ * });
+ *
+ * // On the receiving side, extract and continue the trace
+ * const parentCtx = extractTraceContext(message.correlationId);
+ * const child = collector.startSpan({
+ *   operationName: 'execute-task',
+ *   agentId: 'agent-a',
+ *   domain: 'test-generation',
+ *   parentContext: parentCtx,
+ * });
+ *
+ * // Complete or fail the span
+ * collector.completeSpan(child.span.spanId);
+ * ```
+ */
+/**
+ * Trace context propagated across agent messages.
+ * Follows W3C Trace Context semantics adapted for in-process agent messaging.
+ */
+export interface TraceContext {
+    /** Root trace ID (same across all spans in a trace) */
+    readonly traceId: string;
+    /** Current span ID */
+    readonly spanId: string;
+    /** Parent span ID (undefined for root spans) */
+    readonly parentSpanId?: string;
+    /** Baggage: key-value pairs propagated through the trace */
+    readonly baggage?: Record<string, string>;
+}
+/**
+ * A recorded span in the trace, representing a single unit of work
+ * performed by an agent within a domain.
+ */
+export interface TraceSpan {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly operationName: string;
+    readonly agentId: string;
+    readonly domain: string;
+    readonly startTime: number;
+    endTime?: number;
+    readonly tags: Record<string, string | number | boolean>;
+    readonly status: 'active' | 'completed' | 'error';
+    readonly errorMessage?: string;
+}
+/** Options for starting a new span */
+export interface StartSpanOptions {
+    /** Name of the operation being traced */
+    readonly operationName: string;
+    /** Agent performing the operation */
+    readonly agentId: string;
+    /** Domain the operation belongs to */
+    readonly domain: string;
+    /** Parent trace context (omit to start a root span via startTrace) */
+    readonly parentContext?: TraceContext;
+    /** Optional tags to attach to the span */
+    readonly tags?: Record<string, string | number | boolean>;
+}
+/**
+ * Collects, stores, and queries trace spans across agent workflows.
+ * Spans are stored in memory with configurable capacity and automatic
+ * purging of completed traces.
+ */
+export declare class TraceCollector {
+    private readonly spans;
+    private readonly traceIndex;
+    private readonly maxSpans;
+    constructor(maxSpans?: number);
+    /**
+     * Start a new root trace. Creates a fresh traceId and root span.
+     *
+     * @param options - Operation metadata (parentContext is ignored)
+     * @returns The new trace context and root span
+     */
+    startTrace(options: Omit<StartSpanOptions, 'parentContext'>): {
+        context: TraceContext;
+        span: TraceSpan;
+    };
+    /**
+     * Start a child span within an existing trace.
+     * If `parentContext` is provided, the child inherits the traceId and
+     * records the parent's spanId as its parentSpanId.
+     * If no parentContext is provided, a new root trace is started.
+     *
+     * @param options - Operation metadata including optional parent context
+     * @returns The new trace context and child span
+     */
+    startSpan(options: StartSpanOptions): {
+        context: TraceContext;
+        span: TraceSpan;
+    };
+    /**
+     * Mark a span as successfully completed.
+     *
+     * @param spanId - The span to complete
+     */
+    completeSpan(spanId: string): void;
+    /**
+     * Mark a span as failed with an error message.
+     *
+     * @param spanId - The span to fail
+     * @param errorMessage - Description of the failure
+     */
+    failSpan(spanId: string, errorMessage: string): void;
+    /**
+     * Get all spans belonging to a trace, ordered by start time.
+     *
+     * @param traceId - The trace to retrieve
+     * @returns Spans sorted by startTime (empty if trace not found)
+     */
+    getTrace(traceId: string): TraceSpan[];
+    /**
+     * Get a single span by its ID.
+     *
+     * @param spanId - The span to retrieve
+     * @returns The span or undefined if not found
+     */
+    getSpan(spanId: string): TraceSpan | undefined;
+    /**
+     * Get all currently active (not yet completed or failed) spans.
+     *
+     * @returns Array of active spans
+     */
+    getActiveSpans(): TraceSpan[];
+    /**
+     * Get summary statistics about the collector's state.
+     *
+     * @returns Counts of total spans, active traces, and completed traces
+     */
+    getStats(): {
+        totalSpans: number;
+        activeTraces: number;
+        completedTraces: number;
+    };
+    /**
+     * Purge completed traces whose spans are all older than `maxAge` ms.
+     * Only removes traces where every span has finished (completed or error)
+     * and all end/start timestamps are past the cutoff.
+     *
+     * @param maxAge - Maximum age in milliseconds
+     * @returns Number of spans removed
+     */
+    purge(maxAge: number): number;
+    /**
+     * Dispose the collector, clearing all stored spans and indexes.
+     */
+    dispose(): void;
+    private createSpan;
+}
+/**
+ * Extract a TraceContext from an AgentMessage's correlationId field.
+ * Returns undefined if the correlationId is not trace-encoded or is malformed.
+ *
+ * @param correlationId - The correlationId string from an AgentMessage
+ * @returns Parsed TraceContext or undefined
+ */
+export declare function extractTraceContext(correlationId?: string): TraceContext | undefined;
+/**
+ * Encode a TraceContext into a correlationId string that can be set on
+ * an AgentMessage. The encoding uses a `trace:` prefix followed by JSON.
+ *
+ * @param context - The trace context to encode
+ * @returns Encoded correlationId string
+ */
+export declare function encodeTraceContext(context: TraceContext): string;
+/**
+ * Create a new TraceCollector instance.
+ *
+ * @param maxSpans - Maximum number of spans to retain (default 10,000)
+ * @returns A fresh TraceCollector
+ */
+export declare function createTraceCollector(maxSpans?: number): TraceCollector;
+//# sourceMappingURL=tracing.d.ts.map

package/v3/dist/coordination/agent-teams/tracing.d.ts.map

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