mcp-event-intelligence 0.8.1 → 0.9.0

package/scripts/host-integration.mjs

@@ -127,6 +127,7 @@ export async function createEventIntelligenceHost({
   wake,
   wakeHandlers = {},
   semanticEvaluator,
+  observability,
 } = {}) {
   const explicitConnections = mcpClients.map(normalizeMcpConnection);
   const runtime = await createLocalEventIntelligenceRuntime({
@@ -140,7 +141,9 @@ export async function createEventIntelligenceHost({
     wakeHandlers,
     semanticEvaluator,
     store,
+    observability,
   });
+  const observer = runtime.observability;
 
   const registryManaged = new Set();
   let unsubscribe = null;
@@ -212,6 +215,21 @@ export async function createEventIntelligenceHost({
       }
     }
 
+    await Promise.all(outcomes.map((outcome) => observer.emit({
+      event: 'ei.source.registry_update',
+      level:
+        outcome.status === 'error'
+          ? 'error'
+          : outcome.status === 'ignored_no_events' ||
+              outcome.status === 'already_attached'
+            ? 'debug'
+            : 'info',
+      connectionId: outcome.connectionId,
+      status: outcome.status,
+      ...(outcome.error ? { error: new Error(outcome.error) } : {}),
+      ...(outcome.events ? { metadata: { eventNames: outcome.events } } : {}),
+    })));
+
     return outcomes;
   };
 
@@ -241,10 +259,11 @@ export async function createEventIntelligenceHost({
     if (typeof mcpRegistry.subscribe === 'function') {
       const maybeUnsubscribe = mcpRegistry.subscribe(() => {
         refreshMcpRegistry().catch((error) => {
-          console.error(JSON.stringify({
-            message: 'event_intelligence_mcp_registry_refresh_failed',
-            error: error instanceof Error ? error.message : String(error),
-          }));
+          void observer.emit({
+            event: 'ei.source.refresh_failed',
+            level: 'error',
+            error,
+          });
         });
       });
       if (typeof maybeUnsubscribe === 'function') {

package/scripts/lib/composite-event-consumer.mjs

@@ -10,6 +10,7 @@ export class CompositeEventConsumer {
     wakeCoordinators = null,
     derivedEventCoordinator = null,
     maxDerivedDepth = 16,
+    observability = null,
   }) {
     this.store = store;
     this.triggerEngine = triggerEngine;
@@ -19,6 +20,7 @@ export class CompositeEventConsumer {
       : new Map();
     this.derivedEventCoordinator = derivedEventCoordinator;
     this.maxDerivedDepth = Math.max(1, Number(maxDerivedDepth) || 16);
+    this.observability = observability;
   }
 
   coordinatorFor(runtime) {
@@ -58,6 +60,15 @@ export class CompositeEventConsumer {
     for (const result of results) {
       if (!result.matched || !result.match) continue;
 
+      await this.observability?.emit({
+        event: 'ei.match.matched',
+        level: 'info',
+        traceId: event.traceId,
+        triggerId: result.match.triggerId,
+        matchId: result.match.matchId,
+        status: result.match.status,
+      });
+
       const definition = (await this.store.listTriggers()).find(
         (candidate) =>
           candidate.triggerId === result.match.triggerId &&
@@ -72,6 +83,14 @@ export class CompositeEventConsumer {
           status: 'trigger_definition_missing',
           runtimeReceiptId: null,
         });
+        await this.observability?.emit({
+          event: 'ei.match.definition_missing',
+          level: 'error',
+          traceId: event.traceId,
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          status: 'trigger_definition_missing',
+        });
         continue;
       }
 
@@ -131,6 +150,15 @@ export class CompositeEventConsumer {
           status: 'runtime_unconfigured',
           runtimeReceiptId: null,
         });
+        await this.observability?.emit({
+          event: 'ei.wake.runtime_unconfigured',
+          level: 'warn',
+          traceId: event.traceId,
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          status: 'runtime_unconfigured',
+          metadata: { runtime: definition.target.runtime },
+        });
         continue;
       }
 

package/scripts/lib/composite-wake-coordinator.mjs

@@ -31,6 +31,7 @@ export class CompositeWakeCoordinator {
     maxAttempts = 5,
     retryBaseDelayMs = 1000,
     retryMaxDelayMs = 60000,
+    observability = null,
   }) {
     this.store = store;
     this.triggerEngine = triggerEngine;
@@ -45,6 +46,7 @@ export class CompositeWakeCoordinator {
       this.retryBaseDelayMs,
       Number(retryMaxDelayMs) || 60000,
     );
+    this.observability = observability;
 
     for (const method of [
       'ensureWakeDelivery',
@@ -101,6 +103,16 @@ export class CompositeWakeCoordinator {
           composite: true,
         },
       });
+      await this.observability?.emit({
+        event: 'ei.wake.delivered',
+        level: 'info',
+        traceId: delivered.traceId,
+        triggerId: match.triggerId,
+        matchId: match.matchId,
+        wakeId,
+        status: 'wake_delivered',
+        metadata: { recoveredFromDeliveryState: true },
+      });
     }
 
     if (match.status !== 'fired') {
@@ -193,6 +205,15 @@ export class CompositeWakeCoordinator {
             composite: true,
           },
         });
+        await this.observability?.emit({
+          event: 'ei.wake.queued',
+          level: 'debug',
+          traceId: queued.traceId,
+          triggerId: match.triggerId,
+          matchId: match.matchId,
+          wakeId,
+          status: 'wake_queued',
+        });
       }
       return {
         status: 'wake_queued',
@@ -272,6 +293,15 @@ export class CompositeWakeCoordinator {
           composite: true,
         },
       });
+      await this.observability?.emit({
+        event: 'ei.wake.queued',
+        level: 'debug',
+        traceId: queued.traceId,
+        triggerId: match.triggerId,
+        matchId: match.matchId,
+        wakeId,
+        status: 'wake_queued',
+      });
     }
 
     try {
@@ -322,6 +352,17 @@ export class CompositeWakeCoordinator {
           composite: true,
         },
       });
+      await this.observability?.emit({
+        event: 'ei.wake.delivered',
+        level: 'info',
+        traceId: delivered.traceId,
+        triggerId: match.triggerId,
+        matchId: match.matchId,
+        wakeId,
+        status: 'wake_delivered',
+        attempt: delivery?.attemptCount ?? claim.attemptCount,
+        metadata: { duplicate: receipt.duplicate === true },
+      });
 
       await this.triggerEngine.markFired(match.matchId, wakeId);
 
@@ -365,6 +406,18 @@ export class CompositeWakeCoordinator {
             composite: true,
           },
         });
+        await this.observability?.emit({
+          event: 'ei.wake.retry_scheduled',
+          level: 'warn',
+          traceId: queued.traceId,
+          triggerId: match.triggerId,
+          matchId: match.matchId,
+          wakeId,
+          status: 'retry_scheduled',
+          attempt: delivery?.attemptCount ?? claim.attemptCount,
+          nextAttemptAt: delivery?.nextAttemptAt ?? undefined,
+          error,
+        });
         return {
           status: 'retry_scheduled',
           wake: persistedQueued,
@@ -398,6 +451,17 @@ export class CompositeWakeCoordinator {
           composite: true,
         },
       });
+      await this.observability?.emit({
+        event: 'ei.wake.dead_letter',
+        level: 'error',
+        traceId: deadLetter.traceId,
+        triggerId: match.triggerId,
+        matchId: match.matchId,
+        wakeId,
+        status: 'dead_letter',
+        attempt: delivery?.attemptCount ?? claim.attemptCount,
+        error,
+      });
       return {
         status: 'dead_letter',
         wake: deadLetter,

package/scripts/lib/local-event-intelligence-runtime.mjs

@@ -48,6 +48,9 @@ import {
 import {
   ActivationHydrator,
 } from './activation-hydrator.mjs';
+import {
+  createObservabilityEmitter,
+} from './observability.mjs';
 
 const REQUIRED_STORE_METHODS = [
   'putTrigger',
@@ -114,7 +117,9 @@ export async function createLocalEventIntelligenceRuntime({
   wake,
   semanticEvaluator,
   store: providedStore,
+  observability,
 } = {}) {
+  const observer = createObservabilityEmitter(observability);
   const dataDir = env.DATA_DIR ?? './data';
   const rootStore = providedStore ?? new PersistentEventStore(dataDir);
   const restored = await initializeStore(rootStore);
@@ -212,6 +217,7 @@ export async function createLocalEventIntelligenceRuntime({
           triggerEngine,
           deliverer: createSignedRuntimeWakeDeliverer(target),
           packetBuilder,
+          observability: observer,
           ...deliveryOptions,
         }),
       );
@@ -224,6 +230,7 @@ export async function createLocalEventIntelligenceRuntime({
           store,
           triggerEngine,
           packetBuilder,
+          observability: observer,
           ...deliveryOptions,
           deliverer: async (packet) => {
             const activation = await activationHydrator.hydrateWake(packet.wake_id);
@@ -253,6 +260,7 @@ export async function createLocalEventIntelligenceRuntime({
         store,
         triggerEngine,
         packetBuilder,
+        observability: observer,
         ...deliveryOptions,
         deliverer: async (packet) => {
           const activation = await activationHydrator.hydrateWake(packet.wake_id);
@@ -281,18 +289,21 @@ export async function createLocalEventIntelligenceRuntime({
       wakeCoordinators,
       derivedEventCoordinator,
       maxDerivedDepth: Number(env.MAX_DERIVED_EVENT_DEPTH ?? 16),
+      observability: observer,
     });
 
     const temporalScheduler = new TemporalDeadlineScheduler({
       store,
       compositeEventConsumer,
       intervalMs: Number(env.TEMPORAL_TICK_MS ?? 1000),
+      observability: observer,
     });
     temporalScheduler.start();
 
     const triggerControl = new TriggerControlPlane({
       store,
       triggerEngine,
+      observability: observer,
     });
     const triggerInspector = new TriggerInspector({ store });
 
@@ -302,6 +313,7 @@ export async function createLocalEventIntelligenceRuntime({
       store,
       resolveCoordinator: coordinatorFor,
       intervalMs: Number(env.WAKE_RETRY_TICK_MS ?? 1000),
+      observability: observer,
     });
     wakeRetryScheduler.start();
 
@@ -354,13 +366,38 @@ export async function createLocalEventIntelligenceRuntime({
           principal_id: 'event-intelligence:host-mcp-client',
         },
       ),
+    observability: observer,
   });
 
   const discovery = await mcpEventsClient.discoverAll();
   mcpEventsClient.start();
 
+  for (const source of discovery) {
+    await observer.emit({
+      event: source.status === 'error'
+        ? 'ei.source.discovery_failed'
+        : 'ei.source.discovered',
+      level: source.status === 'error' ? 'warn' : 'info',
+      connectionId: source.connectionId,
+      status: source.status,
+      ...(source.error ? { error: new Error(source.error) } : {}),
+      ...(source.events ? { metadata: { eventNames: source.events } } : {}),
+    });
+  }
+  await observer.emit({
+    event: 'ei.lifecycle.started',
+    level: 'info',
+    metadata: {
+      restoredScopes:
+        typeof rootStore.listScopeIds === 'function'
+          ? await rootStore.listScopeIds()
+          : [DEFAULT_EVENT_SCOPE_ID],
+    },
+  });
+
   return {
     restored,
+    observability: observer,
     storeCapabilities,
     store: defaultContext.store,
     evaluator,
@@ -378,6 +415,7 @@ export async function createLocalEventIntelligenceRuntime({
       return [...scopeContexts.keys()].sort();
     },
     async close() {
+      await observer.emit({ event: 'ei.lifecycle.closing', level: 'debug' });
       await mcpEventsClient.close();
       const contexts = [...scopeContexts.values()];
       await Promise.all(contexts.map((context) => context.close()));
@@ -390,6 +428,7 @@ export async function createLocalEventIntelligenceRuntime({
           await store.drain();
         }
       }
+      await observer.emit({ event: 'ei.lifecycle.closed', level: 'info' });
     },
   };
 }

package/scripts/lib/mcp-events-client.mjs

@@ -286,6 +286,7 @@ export class McpEventsClientManager {
     resolveScope = null,
     connections = [],
     now = () => new Date(),
+    observability = null,
   }) {
     this.store = store;
     this.compositeEventConsumer = compositeEventConsumer;
@@ -293,6 +294,7 @@ export class McpEventsClientManager {
     this.resolveScope = resolveScope;
     this.connections = new Map();
     this.now = now;
+    this.observability = observability;
     this.descriptors = new Map();
     this.profiles = new Map();
     this.timers = new Map();
@@ -877,6 +879,15 @@ export class McpEventsClientManager {
         connection.connectionId,
         error instanceof Error ? error.message : String(error),
       );
+      void this.observability?.emit({
+        event: 'ei.source.delivery_failed',
+        level: 'warn',
+        scopeId: connection.scopeId,
+        connectionId: connection.connectionId,
+        serverId: connection.serverId,
+        eventName: subscription.eventName,
+        error,
+      });
     };
 
     const onTerminated = async (detail) => {
@@ -887,6 +898,15 @@ export class McpEventsClientManager {
           typeof detail === 'string' ? detail : JSON.stringify(detail),
         );
       }
+      void this.observability?.emit({
+        event: 'ei.source.delivery_terminated',
+        level: detail ? 'warn' : 'debug',
+        scopeId: connection.scopeId,
+        connectionId: connection.connectionId,
+        serverId: connection.serverId,
+        eventName: subscription.eventName,
+        status: 'terminated',
+      });
     };
 
     const open =
@@ -1054,6 +1074,14 @@ export class McpEventsClientManager {
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         this.lastErrors.set(connection.connectionId, message);
+        await this.observability?.emit({
+          event: 'ei.source.poll_failed',
+          level: 'warn',
+          scopeId: connection.scopeId,
+          connectionId: connection.connectionId,
+          serverId: connection.serverId,
+          error,
+        });
         results.push({
           connectionId: connection.connectionId,
           error: message,
@@ -1097,6 +1125,14 @@ export class McpEventsClientManager {
           connection.connectionId,
           error instanceof Error ? error.message : String(error),
         );
+        await this.observability?.emit({
+          event: 'ei.source.poll_failed',
+          level: 'warn',
+          scopeId: connection.scopeId,
+          connectionId: connection.connectionId,
+          serverId: connection.serverId,
+          error,
+        });
       } finally {
         if (
           this.started &&

package/scripts/lib/observability.d.mts

@@ -0,0 +1,77 @@
+export type EventIntelligenceObservabilityLevel =
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error';
+
+export interface EventIntelligenceObservabilityEvent {
+  schema: 'event-intelligence.observability.v1' | string;
+  timestamp: string;
+  level: EventIntelligenceObservabilityLevel;
+  event: `ei.${string}`;
+  component: string;
+  traceId?: string;
+  scopeId?: string;
+  triggerId?: string;
+  matchId?: string;
+  wakeId?: string;
+  connectionId?: string;
+  serverId?: string;
+  eventName?: string;
+  status?: string;
+  attempt?: number;
+  nextAttemptAt?: string;
+  error?: {
+    name?: string;
+    code?: string;
+    message: string;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export type EventIntelligenceObservabilitySink =
+  | ((event: EventIntelligenceObservabilityEvent) => void | Promise<void>)
+  | {
+      emit(
+        event: EventIntelligenceObservabilityEvent,
+      ): void | Promise<void>;
+    };
+
+export interface EventIntelligenceObservabilityEmitter {
+  readonly enabled: boolean;
+  emit(input: {
+    event: `ei.${string}`;
+    level?: EventIntelligenceObservabilityLevel;
+    timestamp?: string;
+    component?: string;
+    traceId?: string;
+    scopeId?: string;
+    triggerId?: string;
+    matchId?: string;
+    wakeId?: string;
+    connectionId?: string;
+    serverId?: string;
+    eventName?: string;
+    status?: string;
+    attempt?: number;
+    nextAttemptAt?: string;
+    error?: unknown;
+    metadata?: Record<string, unknown>;
+  }): Promise<boolean>;
+}
+
+export const EI_OBSERVABILITY_SCHEMA_VERSION: '1';
+
+export function serializeObservabilityError(error: unknown): Readonly<{
+  name?: string;
+  code?: string;
+  message: string;
+}>;
+
+export function createObservabilityEmitter(
+  sink?: EventIntelligenceObservabilitySink | null,
+  options?: {
+    now?: () => Date;
+    component?: string;
+  },
+): EventIntelligenceObservabilityEmitter;

package/scripts/lib/observability.mjs

@@ -0,0 +1,134 @@
+const LEVELS = new Set(['debug', 'info', 'warn', 'error']);
+const SENSITIVE_KEY = /(authorization|cookie|credential|password|secret|token|payload|instruction|context|evidence|body|content|data)/i;
+
+export const EI_OBSERVABILITY_SCHEMA_VERSION = '1';
+
+function truncate(value, max = 1000) {
+  const text = String(value ?? '')
+    .replace(/Bearer\\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+    .replace(
+      /((?:api[_-]?key|authorization|password|secret|token)\\s*[=:]\\s*)[^\\s,;]+/gi,
+      '$1[redacted]',
+    );
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function sanitize(value, depth = 0) {
+  if (value == null || typeof value === 'boolean' || typeof value === 'number') {
+    return value;
+  }
+  if (typeof value === 'string') return truncate(value);
+  if (depth >= 3) return '[truncated]';
+  if (Array.isArray(value)) {
+    return value.slice(0, 20).map((item) => sanitize(item, depth + 1));
+  }
+  if (value instanceof Error) {
+    return {
+      name: truncate(value.name, 120),
+      message: truncate(value.message),
+      ...(value.code == null ? {} : { code: truncate(value.code, 200) }),
+    };
+  }
+  if (typeof value === 'object') {
+    const result = {};
+    for (const [key, item] of Object.entries(value).slice(0, 40)) {
+      if (SENSITIVE_KEY.test(key)) continue;
+      const sanitized = sanitize(item, depth + 1);
+      if (sanitized !== undefined) result[key] = sanitized;
+    }
+    return result;
+  }
+  return undefined;
+}
+
+function normalizeSink(input) {
+  if (input == null) return null;
+  if (typeof input === 'function') return { emit: input };
+  if (typeof input === 'object' && typeof input.emit === 'function') {
+    return input;
+  }
+  throw new Error('observability must be a function or { emit(event) }');
+}
+
+export function serializeObservabilityError(error) {
+  if (error instanceof Error) {
+    return Object.freeze({
+      name: truncate(error.name, 120),
+      message: truncate(error.message),
+      ...(error.code == null ? {} : { code: truncate(error.code, 200) }),
+    });
+  }
+  return Object.freeze({ message: truncate(error) });
+}
+
+/**
+ * Runtime-neutral, best-effort observability boundary.
+ *
+ * Async sinks are detached after invocation, so slow telemetry cannot stall
+ * event processing. Sink failures are intentionally swallowed: telemetry must never
+ * change Event Intelligence delivery semantics. Event payloads, continuation
+ * instructions, evidence and credentials are not accepted as first-class
+ * fields and sensitive keys in metadata are dropped defensively.
+ */
+export function createObservabilityEmitter(
+  sinkInput,
+  { now = () => new Date(), component = 'event-intelligence' } = {},
+) {
+  const sink = normalizeSink(sinkInput);
+
+  return Object.freeze({
+    enabled: Boolean(sink),
+    async emit(input = {}) {
+      if (!sink) return false;
+
+      const event = String(input.event ?? '').trim();
+      if (!event.startsWith('ei.')) {
+        throw new Error('observability event must use the ei.* namespace');
+      }
+
+      const level = String(input.level ?? 'info').toLowerCase();
+      if (!LEVELS.has(level)) {
+        throw new Error(`unsupported observability level: ${level}`);
+      }
+
+      const record = {
+        schema: `event-intelligence.observability.v${EI_OBSERVABILITY_SCHEMA_VERSION}`,
+        timestamp: input.timestamp
+          ? String(input.timestamp)
+          : now().toISOString(),
+        level,
+        event,
+        component: String(input.component ?? component),
+        ...(input.traceId ? { traceId: String(input.traceId) } : {}),
+        ...(input.scopeId ? { scopeId: String(input.scopeId) } : {}),
+        ...(input.triggerId ? { triggerId: String(input.triggerId) } : {}),
+        ...(input.matchId ? { matchId: String(input.matchId) } : {}),
+        ...(input.wakeId ? { wakeId: String(input.wakeId) } : {}),
+        ...(input.connectionId ? { connectionId: String(input.connectionId) } : {}),
+        ...(input.serverId ? { serverId: String(input.serverId) } : {}),
+        ...(input.eventName ? { eventName: String(input.eventName) } : {}),
+        ...(input.status ? { status: String(input.status) } : {}),
+        ...(input.attempt != null ? { attempt: Number(input.attempt) } : {}),
+        ...(input.nextAttemptAt
+          ? { nextAttemptAt: String(input.nextAttemptAt) }
+          : {}),
+        ...(input.error
+          ? { error: serializeObservabilityError(input.error) }
+          : {}),
+        ...(input.metadata && typeof input.metadata === 'object'
+          ? { metadata: sanitize(input.metadata) }
+          : {}),
+      };
+
+      try {
+        const pending = sink.emit(Object.freeze(record));
+        if (pending && typeof pending.then === 'function') {
+          void Promise.resolve(pending).catch(() => {});
+        }
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+}

package/scripts/lib/temporal-deadline-scheduler.mjs

@@ -4,11 +4,13 @@ export class TemporalDeadlineScheduler {
     compositeEventConsumer,
     now = () => new Date(),
     intervalMs = 1000,
+    observability = null,
   }) {
     this.store = store;
     this.compositeEventConsumer = compositeEventConsumer;
     this.now = now;
     this.intervalMs = Math.max(250, Number(intervalMs) || 1000);
+    this.observability = observability;
     this.timer = null;
     this.running = false;
   }
@@ -94,6 +96,14 @@ export class TemporalDeadlineScheduler {
     if (this.timer) return;
     this.timer = setInterval(() => {
       this.runDue().catch((error) => {
+        if (this.observability?.enabled) {
+          void this.observability.emit({
+            event: 'ei.scheduler.temporal_deadline_failed',
+            level: 'error',
+            error,
+          });
+          return;
+        }
         console.error(JSON.stringify({
           message: 'temporal_deadline_scheduler_error',
           error: error instanceof Error ? error.message : String(error),