network-ai 5.5.8 → 5.6.0

package/dist/lib/telemetry-provider.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Telemetry Provider — BYOT (Bring Your Own Telemetry) abstraction.
+ *
+ * Defines a minimal interface over distributed tracing providers such as
+ * OpenTelemetry, Datadog APM, Honeycomb, etc.  Network-AI core never imports
+ * a concrete telemetry SDK — only this interface — preserving the zero-
+ * dependency BYOC design.
+ *
+ * ## Wiring into adapter lifecycle hooks
+ *
+ * ```typescript
+ * import { createOtelHooks, CapturingTelemetryProvider } from 'network-ai';
+ * import { AdapterHookManager } from 'network-ai';
+ *
+ * const provider = new CapturingTelemetryProvider(); // or your own impl
+ * const hookManager = new AdapterHookManager();
+ * createOtelHooks(provider).forEach(h => hookManager.register(h));
+ * ```
+ *
+ * ## Implementing for OpenTelemetry
+ *
+ * ```typescript
+ * import { trace, SpanStatusCode } from '@opentelemetry/api';
+ * import type { ITelemetryProvider, SpanAttributes } from 'network-ai';
+ *
+ * class OtelProvider implements ITelemetryProvider {
+ *   private tracer = trace.getTracer('network-ai');
+ *   private spans = new Map<string, Span>();
+ *
+ *   startSpan(name: string, attrs: SpanAttributes = {}): string {
+ *     const span = this.tracer.startSpan(name, { attributes: attrs as Attributes });
+ *     const id = `span_${Date.now()}`;
+ *     this.spans.set(id, span);
+ *     return id;
+ *   }
+ *   endSpan(id: string, status: 'ok' | 'error'): void {
+ *     const span = this.spans.get(id);
+ *     if (!span) return;
+ *     span.setStatus({ code: status === 'ok' ? SpanStatusCode.OK : SpanStatusCode.ERROR });
+ *     span.end();
+ *     this.spans.delete(id);
+ *   }
+ *   recordEvent(id: string, name: string, attrs: SpanAttributes = {}): void {
+ *     this.spans.get(id)?.addEvent(name, attrs as Attributes);
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapturingTelemetryProvider = exports.NullTelemetryProvider = void 0;
+exports.createOtelHooks = createOtelHooks;
+// ============================================================================
+// NULL PROVIDER (default — zero overhead when no telemetry is configured)
+// ============================================================================
+/**
+ * No-op implementation.  Used as the default when no telemetry provider is
+ * supplied so the instrumentation path compiles to a handful of dead calls
+ * that the JIT eliminates.
+ */
+class NullTelemetryProvider {
+    /** @inheritdoc */
+    startSpan(_name, _attributes) { return ''; }
+    /** @inheritdoc */
+    endSpan(_spanId, _status, _attributes) { }
+    /** @inheritdoc */
+    recordEvent(_spanId, _name, _attributes) { }
+}
+exports.NullTelemetryProvider = NullTelemetryProvider;
+// ============================================================================
+// CAPTURING PROVIDER (for testing)
+// ============================================================================
+/**
+ * In-memory provider that stores every span and event for test assertions.
+ *
+ * @example
+ * ```typescript
+ * const provider = new CapturingTelemetryProvider();
+ * createOtelHooks(provider).forEach(h => hookManager.register(h));
+ *
+ * await registry.executeAgent('agent:foo', payload, ctx);
+ *
+ * const span = provider.spans.find(s => s.name === 'adapter.execute');
+ * expect(span?.status).toBe('ok');
+ * ```
+ */
+class CapturingTelemetryProvider {
+    /** All spans created since construction or last `clear()`. */
+    spans = [];
+    counter = 0;
+    /** @inheritdoc */
+    startSpan(name, attributes = {}) {
+        const spanId = `span_${++this.counter}`;
+        this.spans.push({ spanId, name, attributes: { ...attributes }, startedAt: Date.now(), events: [] });
+        return spanId;
+    }
+    /** @inheritdoc */
+    endSpan(spanId, status, attributes = {}) {
+        const span = this.spans.find(s => s.spanId === spanId);
+        if (!span)
+            return;
+        span.endedAt = Date.now();
+        span.status = status;
+        Object.assign(span.attributes, attributes);
+    }
+    /** @inheritdoc */
+    recordEvent(spanId, name, attributes = {}) {
+        const span = this.spans.find(s => s.spanId === spanId);
+        if (!span)
+            return;
+        span.events.push({ name, attributes: { ...attributes }, ts: Date.now() });
+    }
+    /** Clear all captured data and reset span counter. */
+    clear() {
+        this.spans.length = 0;
+        this.counter = 0;
+    }
+}
+exports.CapturingTelemetryProvider = CapturingTelemetryProvider;
+// ============================================================================
+// HOOK FACTORY
+// ============================================================================
+/** Metadata key used to propagate spanId through `HookContext`. @internal */
+const SPAN_ID_META_KEY = '_otelSpanId';
+/**
+ * Create a set of `ExecutionHook` objects that emit traces to `provider`.
+ *
+ * Register the returned hooks with an `AdapterHookManager`:
+ * ```typescript
+ * createOtelHooks(provider).forEach(h => hookManager.register(h));
+ * ```
+ *
+ * Three hooks are created — one per `HookPhase`:
+ * - `otel:beforeExecute` — calls `provider.startSpan('adapter.execute', {...})`
+ * - `otel:afterExecute`  — calls `provider.endSpan(spanId, 'ok')`
+ * - `otel:onError`       — calls `provider.endSpan(spanId, 'error')`
+ *
+ * Each hook has `priority: 100` so it runs before most user-defined hooks.
+ * The spanId is stored in `ctx.metadata._otelSpanId` for downstream hooks
+ * that wish to add their own `recordEvent` calls.
+ *
+ * **Permission check semantics:** `beforeExecute` fires once when execution
+ * begins — not per streaming chunk — matching the documented "once at start"
+ * semantics of `StreamingBaseAdapter`.
+ */
+function createOtelHooks(provider) {
+    return [
+        {
+            name: 'otel:beforeExecute',
+            phase: 'beforeExecute',
+            priority: 100,
+            handler(ctx) {
+                try {
+                    const spanId = provider.startSpan('adapter.execute', {
+                        agentId: ctx.agentId,
+                        action: ctx.payload.action ?? '',
+                        depth: ctx.depth,
+                    });
+                    ctx.metadata[SPAN_ID_META_KEY] = spanId;
+                }
+                catch {
+                    // Telemetry must never break execution
+                }
+                return ctx;
+            },
+        },
+        {
+            name: 'otel:afterExecute',
+            phase: 'afterExecute',
+            priority: 100,
+            handler(ctx) {
+                try {
+                    const spanId = ctx.metadata[SPAN_ID_META_KEY];
+                    if (spanId) {
+                        provider.endSpan(spanId, 'ok', {
+                            success: ctx.result?.success === true,
+                        });
+                    }
+                }
+                catch {
+                    // no-op
+                }
+                return ctx;
+            },
+        },
+        {
+            name: 'otel:onError',
+            phase: 'onError',
+            priority: 100,
+            handler(ctx) {
+                try {
+                    const spanId = ctx.metadata[SPAN_ID_META_KEY];
+                    if (spanId) {
+                        provider.endSpan(spanId, 'error', {
+                            errorMessage: ctx.error?.message ?? 'unknown',
+                        });
+                    }
+                }
+                catch {
+                    // no-op
+                }
+                return ctx;
+            },
+        },
+    ];
+}
+//# sourceMappingURL=telemetry-provider.js.map

package/dist/lib/telemetry-provider.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "5.5.8",
+  "version": "5.6.0",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 29 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, OpenAI Agents SDK, Vertex AI, Pydantic AI, Browser Agent, Hermes, Orchestrator, RLM + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://network-ai.org",
   "main": "dist/index.js",
@@ -102,9 +102,9 @@
     "python": ">=3.9"
   },
   "devDependencies": {
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.0",
     "dotenv": "^17.4.2",
-    "openai": "^6.37.0",
+    "openai": "^6.38.0",
     "ts-node": "^10.9.2",
     "typescript": "^6.0.3"
   },

package/types/agent-adapter.d.ts

@@ -238,7 +238,10 @@ export type AdapterEventType =
   | 'agent:execution:retry'
   | 'agent:execution:fallback'
   | 'agent:discovered'
-  | 'agent:unavailable';
+  | 'agent:unavailable'
+  | 'circuit:open'
+  | 'circuit:half-open'
+  | 'circuit:close';
 
 export interface AdapterEvent {
   type: AdapterEventType;