mcp-event-intelligence 0.8.2 → 0.9.0

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),

package/scripts/lib/trigger-control-plane.mjs

@@ -152,10 +152,12 @@ export class TriggerControlPlane {
     store,
     triggerEngine,
     now = () => new Date(),
+    observability = null,
   }) {
     this.store = store;
     this.triggerEngine = triggerEngine;
     this.now = now;
+    this.observability = observability;
     this.contractRegistry = new DerivedContractRegistry({
       store,
       now,
@@ -1110,5 +1112,29 @@ export class TriggerControlPlane {
       entityId,
       details,
     });
+
+    const event =
+      kind === 'event_source.registered'
+        ? 'ei.source.registered'
+        : kind.startsWith('trigger.')
+          ? `ei.${kind}`
+          : null;
+    if (event) {
+      await this.observability?.emit({
+        event,
+        level: 'info',
+        traceId,
+        ...(entityType === 'trigger' ? { triggerId: entityId } : {}),
+        ...(details?.connectionId ? { connectionId: details.connectionId } : {}),
+        ...(details?.serverId ? { serverId: details.serverId } : {}),
+        ...(details?.eventName ? { eventName: details.eventName } : {}),
+        metadata: {
+          entityType,
+          ...(details?.version ? { version: details.version } : {}),
+          ...(details?.fromVersion ? { fromVersion: details.fromVersion } : {}),
+          ...(details?.toVersion ? { toVersion: details.toVersion } : {}),
+        },
+      });
+    }
   }
 }

package/scripts/lib/wake-retry-scheduler.mjs

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

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sarooo17/event-intelligence",
   "title": "MCP Event Intelligence",
   "description": "MCP-native CEP for durable agents: event-time patterns, semantic predicates, derived events.",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "repository": {
     "url": "https://github.com/sarooo17/event-intelligence",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-event-intelligence",
-      "version": "0.8.2",
+      "version": "0.9.0",
       "transport": {
         "type": "stdio"
       },