agentic-qe 1.8.3 → 1.9.0

package/dist/telemetry/instrumentation/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Telemetry Instrumentation - Agent and Task Tracing
+ *
+ * Comprehensive OpenTelemetry instrumentation for all 18 QE agents
+ * with automatic span management, context propagation, and semantic attributes.
+ *
+ * @module telemetry/instrumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withMemoryDelete = exports.withMemorySearch = exports.withMemoryRetrieve = exports.withMemoryStore = exports.memorySpanManager = exports.MemorySpanManager = exports.withTaskSpan = exports.taskSpanManager = exports.TaskSpanManager = exports.withAgentSpan = exports.InstrumentAgent = exports.agentSpanManager = exports.AgentSpanManager = void 0;
+exports.initializeInstrumentation = initializeInstrumentation;
+exports.cleanupInstrumentation = cleanupInstrumentation;
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "AgentSpanManager", { enumerable: true, get: function () { return agent_1.AgentSpanManager; } });
+Object.defineProperty(exports, "agentSpanManager", { enumerable: true, get: function () { return agent_1.agentSpanManager; } });
+Object.defineProperty(exports, "InstrumentAgent", { enumerable: true, get: function () { return agent_1.InstrumentAgent; } });
+Object.defineProperty(exports, "withAgentSpan", { enumerable: true, get: function () { return agent_1.withAgentSpan; } });
+var task_1 = require("./task");
+Object.defineProperty(exports, "TaskSpanManager", { enumerable: true, get: function () { return task_1.TaskSpanManager; } });
+Object.defineProperty(exports, "taskSpanManager", { enumerable: true, get: function () { return task_1.taskSpanManager; } });
+Object.defineProperty(exports, "withTaskSpan", { enumerable: true, get: function () { return task_1.withTaskSpan; } });
+var memory_1 = require("./memory");
+Object.defineProperty(exports, "MemorySpanManager", { enumerable: true, get: function () { return memory_1.MemorySpanManager; } });
+Object.defineProperty(exports, "memorySpanManager", { enumerable: true, get: function () { return memory_1.memorySpanManager; } });
+Object.defineProperty(exports, "withMemoryStore", { enumerable: true, get: function () { return memory_1.withMemoryStore; } });
+Object.defineProperty(exports, "withMemoryRetrieve", { enumerable: true, get: function () { return memory_1.withMemoryRetrieve; } });
+Object.defineProperty(exports, "withMemorySearch", { enumerable: true, get: function () { return memory_1.withMemorySearch; } });
+Object.defineProperty(exports, "withMemoryDelete", { enumerable: true, get: function () { return memory_1.withMemoryDelete; } });
+/**
+ * Initialize all instrumentation managers
+ *
+ * Call this during application startup to ensure proper cleanup on shutdown.
+ */
+function initializeInstrumentation() {
+    // Register cleanup handlers
+    process.on('SIGTERM', cleanupInstrumentation);
+    process.on('SIGINT', cleanupInstrumentation);
+    process.on('beforeExit', cleanupInstrumentation);
+}
+/**
+ * Cleanup all active instrumentation spans
+ *
+ * Ensures all spans are properly ended during graceful shutdown.
+ */
+function cleanupInstrumentation() {
+    const { agentSpanManager } = require('./agent');
+    const { taskSpanManager } = require('./task');
+    const { memorySpanManager } = require('./memory');
+    agentSpanManager.cleanup();
+    taskSpanManager.cleanup();
+    memorySpanManager.cleanup();
+}
+//# sourceMappingURL=index.js.map

package/dist/telemetry/instrumentation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/instrumentation/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAyCH,8DAKC;AAOD,wDAQC;AA3DD,iCAOiB;AANf,yGAAA,gBAAgB,OAAA;AAChB,yGAAA,gBAAgB,OAAA;AAGhB,wGAAA,eAAe,OAAA;AACf,sGAAA,aAAa,OAAA;AAGf,+BAMgB;AALd,uGAAA,eAAe,OAAA;AACf,uGAAA,eAAe,OAAA;AAGf,oGAAA,YAAY,OAAA;AAGd,mCAekB;AAdhB,2GAAA,iBAAiB,OAAA;AACjB,2GAAA,iBAAiB,OAAA;AASjB,yGAAA,eAAe,OAAA;AACf,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAGlB;;;;GAIG;AACH,SAAgB,yBAAyB;IACvC,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,sBAAsB,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB;IACpC,MAAM,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAElD,gBAAgB,CAAC,OAAO,EAAE,CAAC;IAC3B,eAAe,CAAC,OAAO,EAAE,CAAC;IAC1B,iBAAiB,CAAC,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/telemetry/instrumentation/memory.d.ts

@@ -0,0 +1,313 @@
+/**
+ * Memory Instrumentation - OpenTelemetry spans for memory operations
+ *
+ * Provides comprehensive tracing for memory store/retrieve/search/delete operations
+ * with semantic attributes following OpenTelemetry conventions. Automatically instruments
+ * all memory operations with context propagation and performance tracking.
+ *
+ * @module telemetry/instrumentation/memory
+ */
+import { Span, Context } from '@opentelemetry/api';
+import { AgentId } from '../../types';
+/**
+ * Memory store span configuration
+ */
+export interface MemoryStoreConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Memory key */
+    key: string;
+    /** Value size in bytes */
+    valueSize: number;
+    /** Time-to-live in seconds (optional) */
+    ttl?: number;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory retrieve span configuration
+ */
+export interface MemoryRetrieveConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Memory key */
+    key: string;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory search span configuration
+ */
+export interface MemorySearchConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Search pattern (glob or regex) */
+    pattern: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory delete span configuration
+ */
+export interface MemoryDeleteConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Memory key */
+    key: string;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory store operation result
+ */
+export interface MemoryStoreResult {
+    /** Whether the store operation was successful */
+    success: boolean;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory retrieve operation result
+ */
+export interface MemoryRetrieveResult {
+    /** Whether the key was found */
+    found: boolean;
+    /** Value size in bytes (if found) */
+    valueSize?: number;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory search operation result
+ */
+export interface MemorySearchResult {
+    /** Number of results found */
+    resultCount: number;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory delete operation result
+ */
+export interface MemoryDeleteResult {
+    /** Whether the delete operation was successful */
+    success: boolean;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory operation span manager
+ *
+ * Manages OpenTelemetry spans for memory operations with automatic
+ * context propagation and semantic attribute attachment following
+ * OTEL conventions for distributed tracing.
+ */
+export declare class MemorySpanManager {
+    private readonly tracer;
+    private activeSpans;
+    /**
+     * Start memory store span
+     *
+     * Records memory store operation with semantic attributes for namespace,
+     * key, value size, and optional TTL.
+     *
+     * @param config - Memory store configuration
+     * @returns Active span with context
+     */
+    startStoreSpan(config: MemoryStoreConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory store span
+     *
+     * @param span - Active span from startStoreSpan
+     * @param result - Store operation result
+     */
+    completeStoreSpan(span: Span, result: MemoryStoreResult): void;
+    /**
+     * Start memory retrieve span
+     *
+     * Records memory retrieve operation with semantic attributes for namespace
+     * and key lookup.
+     *
+     * @param config - Memory retrieve configuration
+     * @returns Active span with context
+     */
+    startRetrieveSpan(config: MemoryRetrieveConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory retrieve span
+     *
+     * @param span - Active span from startRetrieveSpan
+     * @param result - Retrieve operation result
+     */
+    completeRetrieveSpan(span: Span, result: MemoryRetrieveResult): void;
+    /**
+     * Start memory search span
+     *
+     * Records memory search operation with semantic attributes for namespace,
+     * search pattern, and result limits.
+     *
+     * @param config - Memory search configuration
+     * @returns Active span with context
+     */
+    startSearchSpan(config: MemorySearchConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory search span
+     *
+     * @param span - Active span from startSearchSpan
+     * @param result - Search operation result
+     */
+    completeSearchSpan(span: Span, result: MemorySearchResult): void;
+    /**
+     * Start memory delete span
+     *
+     * Records memory delete operation with semantic attributes for namespace
+     * and key deletion.
+     *
+     * @param config - Memory delete configuration
+     * @returns Active span with context
+     */
+    startDeleteSpan(config: MemoryDeleteConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory delete span
+     *
+     * @param span - Active span from startDeleteSpan
+     * @param result - Delete operation result
+     */
+    completeDeleteSpan(span: Span, result: MemoryDeleteResult): void;
+    /**
+     * Record memory operation error
+     *
+     * Records an error event on the currently active span.
+     *
+     * @param operation - Operation type (store, retrieve, search, delete)
+     * @param namespace - Memory namespace
+     * @param key - Memory key (if applicable)
+     * @param error - Error that occurred
+     */
+    recordError(operation: 'store' | 'retrieve' | 'search' | 'delete', namespace: string, key: string | undefined, error: Error): void;
+    /**
+     * Cleanup all active spans (for graceful shutdown)
+     *
+     * Ensures all memory operation spans are properly ended during
+     * application shutdown or cleanup.
+     */
+    cleanup(): void;
+}
+/**
+ * Global memory span manager instance
+ */
+export declare const memorySpanManager: MemorySpanManager;
+/**
+ * Execute function within memory store span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory store span around the provided function.
+ *
+ * @param config - Memory store configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result
+ *
+ * @example
+ * const result = await withMemoryStore(
+ *   { agentId, namespace: 'aqe', key: 'test-plan', valueSize: 1024 },
+ *   async (ctx) => {
+ *     return await memoryService.store('test-plan', data);
+ *   }
+ * );
+ */
+export declare function withMemoryStore<T>(config: MemoryStoreConfig, fn: (context: Context) => Promise<T>): Promise<T>;
+/**
+ * Execute function within memory retrieve span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory retrieve span around the provided function.
+ *
+ * @param config - Memory retrieve configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result with found flag
+ *
+ * @example
+ * const { found, value } = await withMemoryRetrieve(
+ *   { agentId, namespace: 'aqe', key: 'test-plan' },
+ *   async (ctx) => {
+ *     return await memoryService.retrieve('test-plan');
+ *   }
+ * );
+ */
+export declare function withMemoryRetrieve<T>(config: MemoryRetrieveConfig, fn: (context: Context) => Promise<{
+    found: boolean;
+    value?: T;
+    valueSize?: number;
+}>): Promise<{
+    found: boolean;
+    value?: T;
+    valueSize?: number;
+}>;
+/**
+ * Execute function within memory search span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory search span around the provided function.
+ *
+ * @param config - Memory search configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result with result count
+ *
+ * @example
+ * const results = await withMemorySearch(
+ *   { agentId, namespace: 'aqe', pattern: 'test-*', limit: 10 },
+ *   async (ctx) => {
+ *     return await memoryService.search('test-*');
+ *   }
+ * );
+ */
+export declare function withMemorySearch<T>(config: MemorySearchConfig, fn: (context: Context) => Promise<T[]>): Promise<T[]>;
+/**
+ * Execute function within memory delete span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory delete span around the provided function.
+ *
+ * @param config - Memory delete configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result
+ *
+ * @example
+ * await withMemoryDelete(
+ *   { agentId, namespace: 'aqe', key: 'test-plan' },
+ *   async (ctx) => {
+ *     await memoryService.delete('test-plan');
+ *   }
+ * );
+ */
+export declare function withMemoryDelete<T>(config: MemoryDeleteConfig, fn: (context: Context) => Promise<T>): Promise<T>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/telemetry/instrumentation/memory.d.ts.map

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