mcp-event-intelligence 0.8.2 → 0.9.0

package/scripts/host-conformance.mjs

@@ -0,0 +1,238 @@
+const REPORT_SCHEMA = 'event-intelligence.host-conformance.v1';
+
+function assertFunction(value, name) {
+  if (typeof value !== 'function') {
+    throw new Error(`Host conformance adapter requires ${name}()`);
+  }
+}
+
+function validateHarness(harness) {
+  if (!harness || typeof harness !== 'object') {
+    throw new Error('createHarness() must return a harness object');
+  }
+  for (const method of [
+    'createTrigger',
+    'emitEvent',
+    'deliveries',
+    'restart',
+    'inspectTrigger',
+    'close',
+  ]) {
+    assertFunction(harness[method], method);
+  }
+  return harness;
+}
+
+function deliveryCount(rows, triggerId) {
+  return rows.filter((row) => row?.triggerId === triggerId).length;
+}
+
+async function runCase(id, execute) {
+  const startedAt = Date.now();
+  try {
+    const detail = await execute();
+    return Object.freeze({
+      id,
+      status: 'pass',
+      durationMs: Date.now() - startedAt,
+      ...(detail ? { detail } : {}),
+    });
+  } catch (error) {
+    return Object.freeze({
+      id,
+      status: 'fail',
+      durationMs: Date.now() - startedAt,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function requireCondition(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+/**
+ * Run the runtime-neutral EI host contract against an isolated host harness.
+ *
+ * The adapter owns all runtime-specific translation. The kit only uses a
+ * canonical value-change source and inspects externally visible deliveries,
+ * persisted trigger state and structured observability events.
+ */
+export async function runHostConformance(
+  adapter,
+  { throwOnFailure = false } = {},
+) {
+  if (!adapter || typeof adapter !== 'object') {
+    throw new Error('Host conformance adapter is required');
+  }
+  assertFunction(adapter.createHarness, 'createHarness');
+
+  const observed = [];
+  const harness = validateHarness(await adapter.createHarness({
+    observability(event) {
+      observed.push(event);
+    },
+  }));
+
+  const results = [];
+  try {
+    results.push(await runCase('core.once-threshold', async () => {
+      await harness.createTrigger({
+        triggerId: 'conformance-once',
+        threshold: 1000,
+        oneShot: true,
+      });
+
+      await harness.emitEvent({
+        eventId: 'once-below',
+        value: 999,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-once') === 0,
+        'below-threshold event produced a delivery',
+      );
+
+      await harness.emitEvent({
+        eventId: 'once-match',
+        value: 1001,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-once') === 1,
+        'matching event did not produce exactly one delivery',
+      );
+
+    }));
+
+    results.push(await runCase('core.replay-dedup', async () => {
+      await harness.createTrigger({
+        triggerId: 'conformance-replay',
+        threshold: 1000,
+        oneShot: false,
+        maxFirings: 2,
+      });
+
+      await harness.emitEvent({
+        eventId: 'replay-same-id',
+        value: 1100,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      await harness.emitEvent({
+        eventId: 'replay-same-id',
+        value: 1100,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-replay') === 1,
+        'replayed event produced a duplicate delivery on a persistent trigger',
+      );
+      const state = await harness.inspectTrigger('conformance-replay');
+      requireCondition(
+        Number(state?.fireCount) === 1,
+        `replayed event advanced fireCount to ${state?.fireCount}`,
+      );
+    }));
+
+    results.push(await runCase('core.restart-durability', async () => {
+      await harness.createTrigger({
+        triggerId: 'conformance-restart',
+        threshold: 1000,
+        oneShot: false,
+        maxFirings: 2,
+      });
+      await harness.restart();
+
+      await harness.emitEvent({
+        eventId: 'restart-1',
+        value: 1200,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-restart') === 1,
+        'trigger did not survive runtime restart',
+      );
+    }));
+
+    results.push(await runCase('core.max-firings', async () => {
+      await harness.emitEvent({
+        eventId: 'restart-2',
+        value: 1300,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      await harness.emitEvent({
+        eventId: 'restart-3',
+        value: 1400,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-restart') === 2,
+        'maxFirings=2 did not cap external deliveries at two',
+      );
+
+      const state = await harness.inspectTrigger('conformance-restart');
+      requireCondition(Boolean(state), 'trigger state unavailable after firing');
+      requireCondition(
+        Number(state.fireCount) === 2,
+        `expected fireCount=2, got ${state.fireCount}`,
+      );
+    }));
+
+    results.push(await runCase('observability.required-events', async () => {
+      const names = new Set(observed.map((event) => event?.event));
+      for (const name of [
+        'ei.trigger.created',
+        'ei.match.matched',
+        'ei.wake.delivered',
+      ]) {
+        requireCondition(
+          names.has(name),
+          `missing required observability event ${name}`,
+        );
+      }
+
+      const serialized = JSON.stringify(observed);
+      requireCondition(
+        !serialized.includes('ei-conformance-secret-probe'),
+        'observability leaked event payload content',
+      );
+    }));
+  } finally {
+    await harness.close();
+  }
+
+  const failed = results.filter((result) => result.status === 'fail');
+  const report = Object.freeze({
+    schema: REPORT_SCHEMA,
+    adapter: String(adapter.name ?? 'unnamed-host'),
+    passed: failed.length === 0,
+    summary: Object.freeze({
+      total: results.length,
+      passed: results.length - failed.length,
+      failed: failed.length,
+    }),
+    results: Object.freeze(results),
+    observability: Object.freeze({
+      captured: observed.length,
+      eventNames: Object.freeze([...new Set(
+        observed.map((event) => event?.event).filter(Boolean),
+      )].sort()),
+    }),
+  });
+
+  if (throwOnFailure && !report.passed) {
+    const error = new Error(
+      `Event Intelligence host conformance failed: ${failed
+        .map((item) => item.id)
+        .join(', ')}`,
+    );
+    error.report = report;
+    throw error;
+  }
+
+  return report;
+}
+
+export const HOST_CONFORMANCE_REPORT_SCHEMA = REPORT_SCHEMA;

package/scripts/host-integration.d.mts

@@ -2,6 +2,9 @@ import type {
   ActivationEnvelope,
   TriggerPlanInput,
 } from '../dist/src/intelligenceProtocol/index.js';
+import type {
+  EventIntelligenceObservabilitySink,
+} from './lib/observability.d.mts';
 
 export interface HostMcpClientLike {
   request(
@@ -130,6 +133,8 @@ export interface EventIntelligenceHostOptions {
   /** Optional runtime-specific dispatchers. */
   wakeHandlers?: Map<string, HostWakeHandler> | Record<string, HostWakeHandler>;
   semanticEvaluator?: unknown;
+  /** Runtime-neutral structured operational events. Sink failures never affect EI semantics. */
+  observability?: EventIntelligenceObservabilitySink;
 }
 
 export interface EventIntelligenceScopedHost {

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 &&