@compilr-dev/agents 0.3.14 → 0.3.15

package/dist/tracing/otel-hooks.js

@@ -0,0 +1,220 @@
+/**
+ * Native OpenTelemetry Hooks
+ *
+ * Creates real OTel spans during agent execution with proper context propagation
+ * and gen_ai semantic conventions. Unlike the post-hoc `createOTelExporter()`,
+ * these hooks create spans in real time with correct parent-child relationships.
+ *
+ * Requires `@opentelemetry/api` (regular dependency, no-ops without SDK registered).
+ *
+ * @example
+ * ```typescript
+ * import { createOTelHooks } from '@compilr-dev/agents';
+ *
+ * const hooks = createOTelHooks({
+ *   providerName: 'claude',
+ *   tracerName: 'my-agent',
+ * });
+ *
+ * const agent = new Agent({ provider, hooks });
+ * ```
+ */
+import { trace, context, SpanStatusCode, SpanKind as OTelSpanKind } from '@opentelemetry/api';
+import { GenAIAttributes, AgentAttributes, PROVIDER_TO_SYSTEM } from './otel-attributes.js';
+/**
+ * Truncate a value to a maximum length for span attributes
+ */
+function truncateValue(value, maxLength) {
+    const str = typeof value === 'string' ? value : JSON.stringify(value);
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Create native OpenTelemetry hooks for agent instrumentation.
+ *
+ * These hooks create real OTel spans during execution, as opposed to the
+ * post-hoc `createOTelExporter()` which recreates spans after the fact.
+ *
+ * Span hierarchy:
+ * ```
+ * agent.iteration [INTERNAL]
+ *   ├── gen_ai.chat [CLIENT]           (gen_ai.system, tokens, model)
+ *   ├── agent.tool.read_file [INTERNAL] (tool.name, success, duration)
+ *   └── agent.tool.bash [INTERNAL]
+ * ```
+ *
+ * @param config - Optional configuration
+ * @returns HooksConfig ready to pass to Agent constructor
+ */
+export function createOTelHooks(config = {}) {
+    const { tracerName = '@compilr-dev/agents', tracerVersion, providerName, traceIterations = true, traceLLM = true, traceTools = true, includeIO = false, truncateAt = 1000, } = config;
+    const tracer = trace.getTracer(tracerName, tracerVersion);
+    const system = providerName ? (PROVIDER_TO_SYSTEM[providerName] ?? providerName) : undefined;
+    // Track active spans per session
+    const activeSessions = new Map();
+    const getSession = (sessionId) => {
+        let session = activeSessions.get(sessionId);
+        if (!session) {
+            session = {};
+            activeSessions.set(sessionId, session);
+        }
+        return session;
+    };
+    const hooks = {};
+    // ==========================================================================
+    // Iteration Hooks
+    // ==========================================================================
+    if (traceIterations) {
+        const beforeIteration = (ctx) => {
+            const session = getSession(ctx.sessionId);
+            const span = tracer.startSpan('agent.iteration', {
+                kind: OTelSpanKind.INTERNAL,
+                attributes: {
+                    [AgentAttributes.SESSION_ID]: ctx.sessionId,
+                    [AgentAttributes.ITERATION_NUMBER]: ctx.iteration,
+                    [AgentAttributes.ITERATION_MAX]: ctx.maxIterations,
+                    [AgentAttributes.MESSAGE_COUNT]: ctx.messages.length,
+                },
+            }, context.active());
+            session.iterationSpan = span;
+            session.iterationContext = trace.setSpan(context.active(), span);
+            return undefined;
+        };
+        const afterIteration = (ctx) => {
+            const session = getSession(ctx.sessionId);
+            const span = session.iterationSpan;
+            if (span) {
+                span.setAttributes({
+                    [AgentAttributes.TOOL_CALL_COUNT]: ctx.toolCalls.length,
+                    [AgentAttributes.COMPLETED_WITH_TEXT]: ctx.completedWithText,
+                });
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                session.iterationSpan = undefined;
+                session.iterationContext = undefined;
+            }
+            return undefined;
+        };
+        hooks.beforeIteration = [beforeIteration];
+        hooks.afterIteration = [afterIteration];
+    }
+    // ==========================================================================
+    // LLM Hooks
+    // ==========================================================================
+    if (traceLLM) {
+        const beforeLLM = (ctx) => {
+            const session = getSession(ctx.sessionId);
+            const parentCtx = session.iterationContext ?? context.active();
+            const attributes = {
+                [GenAIAttributes.OPERATION_NAME]: 'chat',
+                [AgentAttributes.SESSION_ID]: ctx.sessionId,
+                [AgentAttributes.MESSAGE_COUNT]: ctx.messages.length,
+            };
+            if (system) {
+                attributes[GenAIAttributes.SYSTEM] = system;
+            }
+            if (includeIO && ctx.messages.length > 0) {
+                const lastMessage = ctx.messages[ctx.messages.length - 1];
+                if (typeof lastMessage.content === 'string') {
+                    attributes['gen_ai.request.last_message'] = truncateValue(lastMessage.content, truncateAt);
+                }
+            }
+            const span = tracer.startSpan('gen_ai.chat', {
+                kind: OTelSpanKind.CLIENT,
+                attributes,
+            }, parentCtx);
+            session.llmSpan = span;
+            return undefined;
+        };
+        const afterLLM = (ctx) => {
+            const session = getSession(ctx.sessionId);
+            const span = session.llmSpan;
+            if (span) {
+                if (ctx.usage) {
+                    span.setAttributes({
+                        [GenAIAttributes.USAGE_INPUT_TOKENS]: ctx.usage.inputTokens,
+                        [GenAIAttributes.USAGE_OUTPUT_TOKENS]: ctx.usage.outputTokens,
+                    });
+                }
+                if (ctx.model) {
+                    span.setAttribute(GenAIAttributes.RESPONSE_MODEL, ctx.model);
+                }
+                // Set finish reason based on whether tool calls were made
+                const finishReason = ctx.toolUses.length > 0 ? 'tool_calls' : 'end_turn';
+                span.setAttribute(GenAIAttributes.RESPONSE_FINISH_REASON, finishReason);
+                if (includeIO && ctx.text) {
+                    span.setAttribute('gen_ai.response.text', truncateValue(ctx.text, truncateAt));
+                }
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                session.llmSpan = undefined;
+            }
+            return undefined;
+        };
+        hooks.beforeLLM = [beforeLLM];
+        hooks.afterLLM = [afterLLM];
+    }
+    // ==========================================================================
+    // Tool Hooks
+    // ==========================================================================
+    if (traceTools) {
+        const beforeTool = (ctx) => {
+            const session = getSession(ctx.sessionId);
+            // Tools are children of the iteration span (LLM span is already ended)
+            const parentCtx = session.iterationContext ?? context.active();
+            const attributes = {
+                [AgentAttributes.TOOL_NAME]: ctx.toolName,
+                [AgentAttributes.SESSION_ID]: ctx.sessionId,
+            };
+            if (includeIO) {
+                attributes['agent.tool.input'] = truncateValue(ctx.input, truncateAt);
+            }
+            const span = tracer.startSpan(`agent.tool.${ctx.toolName}`, {
+                kind: OTelSpanKind.INTERNAL,
+                attributes,
+            }, parentCtx);
+            session.toolSpan = span;
+            return undefined;
+        };
+        const afterTool = (ctx) => {
+            const session = getSession(ctx.sessionId);
+            const span = session.toolSpan;
+            if (span) {
+                span.setAttributes({
+                    [AgentAttributes.TOOL_SUCCESS]: ctx.result.success,
+                    [AgentAttributes.TOOL_DURATION_MS]: ctx.durationMs,
+                });
+                if (!ctx.result.success && ctx.result.error) {
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.result.error });
+                }
+                else {
+                    span.setStatus({ code: SpanStatusCode.OK });
+                }
+                if (includeIO && ctx.result.result !== undefined) {
+                    span.setAttribute('agent.tool.output', truncateValue(ctx.result.result, truncateAt));
+                }
+                span.end();
+                session.toolSpan = undefined;
+            }
+            return undefined;
+        };
+        hooks.beforeTool = [beforeTool];
+        hooks.afterTool = [afterTool];
+    }
+    // ==========================================================================
+    // Error Hook
+    // ==========================================================================
+    const onError = (ctx) => {
+        const session = getSession(ctx.sessionId);
+        // Record exception on the most specific active span
+        const span = session.toolSpan ?? session.llmSpan ?? session.iterationSpan;
+        if (span) {
+            span.recordException(ctx.error);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error.message });
+        }
+        return undefined;
+    };
+    hooks.onError = [onError];
+    return hooks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -67,6 +67,7 @@
     "@anthropic-ai/sdk": "^0.74.0",
     "@eslint/js": "^9.39.1",
     "@modelcontextprotocol/sdk": "^1.23.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.1",
     "@types/node": "^25.2.3",
     "@vitest/coverage-v8": "^4.0.18",
     "dotenv": "^17.2.3",
@@ -78,6 +79,7 @@
   },
   "dependencies": {
     "@google/genai": "^1.42.0",
+    "@opentelemetry/api": "^1.9.0",
     "js-tiktoken": "^1.0.21"
   },
   "overrides": {