mcp-event-intelligence 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.9.0] - 2026-10-05
+
+### Runtime-neutral observability
+
+- add the public `mcp-event-intelligence/observability` surface for structured operational `ei.*` events;
+- cover lifecycle, MCP/event-source health, trigger mutations, matches, wake delivery, retry/dead-letter and scheduler failures;
+- keep observability best-effort and non-blocking so slow or failing telemetry sinks cannot change Event Intelligence execution semantics;
+- defensively exclude event payloads, evidence, continuation instructions and credential-like metadata from operational events;
+- keep audit and observability separate: the audit chain remains durable and tamper-evident while observability stays host-owned and ephemeral.
+
+### Host conformance
+
+- add the public `mcp-event-intelligence/conformance` runner with a six-method runtime-neutral host adapter contract;
+- emit machine-readable `event-intelligence.host-conformance.v1` reports;
+- verify threshold/one-shot behavior, replay deduplication on persistent triggers, restart durability, bounded `maxFirings`, required observability and payload non-leakage;
+- add a real embedded reference host and `npm run conformance:host`;
+- document the integration contract without introducing Muffin, Artemis, OpenAI, Anthropic or logger-vendor adapters into EI core.
+
+
 ## [0.8.2] - 2026-10-05
 
 ### Embedded integration

package/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/mcp-event-intelligence.svg)](https://www.npmjs.com/package/mcp-event-intelligence)
-[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.8.2-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.9.0-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
 MCP Event Intelligence is an experimental event runtime for agents that need to react to **future conditions over multiple event sources** without keeping an LLM or agent loop alive.

package/conformance/README.md

@@ -0,0 +1,59 @@
+# Host conformance
+
+Event Intelligence ships two separate conformance layers.
+
+## Runtime contract conformance
+
+The existing fixtures and regression suite validate EI's own protocol, Pattern,
+storage, audit and MCP Events boundaries.
+
+A conforming EI adapter must preserve canonical schemas, stable event identity,
+source evidence, lifecycle correctness, replay deduplication, hash-linked audit
+history and the rule that external event data is evidence rather than
+authorization.
+
+Run the full internal suite with:
+
+```bash
+npm run check
+```
+
+## Embedded host conformance
+
+The public `mcp-event-intelligence/conformance` entry point validates an
+embedding runtime without teaching EI about that runtime.
+
+Implement `createHarness({ observability })` and return six operations:
+
+- `createTrigger()`
+- `emitEvent()`
+- `deliveries()`
+- `restart()`
+- `inspectTrigger()`
+- `close()`
+
+Then run:
+
+```js
+import { runHostConformance } from 'mcp-event-intelligence/conformance';
+
+const report = await runHostConformance(myRuntimeAdapter, {
+  throwOnFailure: true,
+});
+```
+
+Core v1 checks cover one-shot delivery, replay deduplication, restart
+persistence, bounded `maxFirings`, and required structured observability
+(`ei.trigger.created`, `ei.match.matched`, `ei.wake.delivered`).
+
+The scenarios are intentionally isolated and synthetic. Do not point the
+conformance harness at production continuations or production event sources.
+
+The repository reference adapter can be run with:
+
+```bash
+npm run conformance:host
+```
+
+The MCP Events draft remains upstream and experimental. These checks certify
+Event Intelligence host behavior, not official MCP conformance.

package/conformance/fixtures/composite-trigger.valid.json

@@ -0,0 +1,70 @@
+{
+  "protocolVersion": "0.2.0",
+  "schemaVersion": "trigger.v0.2",
+  "triggerId": "issue-and-pippo-mail",
+  "version": "1",
+  "description": "Wake only when an issue exists and Pippo sends a related email.",
+  "clauses": [
+    {
+      "id": "issue",
+      "event": "github.issue.opened",
+      "where": [
+        {
+          "path": "repository",
+          "op": "eq",
+          "value": "acme/app"
+        }
+      ]
+    },
+    {
+      "id": "mail",
+      "event": "email.received",
+      "where": [
+        {
+          "path": "from",
+          "op": "eq",
+          "value": "pippo@example.com"
+        }
+      ]
+    }
+  ],
+  "pattern": {
+    "version": "2",
+    "root": {
+      "kind": "semantic",
+      "id": "same-problem",
+      "refs": [
+        "issue",
+        "mail"
+      ],
+      "instruction": "The email concerns the GitHub issue.",
+      "input": [
+        "issue.title",
+        "mail.subject",
+        "mail.bodyPreview"
+      ],
+      "matchThreshold": 0.8,
+      "rejectThreshold": 0.2,
+      "uncertain": "escalate",
+      "child": {
+        "kind": "allOf",
+        "children": [
+          {
+            "kind": "event",
+            "ref": "issue"
+          },
+          {
+            "kind": "event",
+            "ref": "mail"
+          }
+        ]
+      }
+    }
+  },
+  "withinMs": 86400000,
+  "target": {
+    "runtime": "runtime-probe",
+    "kind": "task",
+    "id": "issue-report"
+  }
+}

package/conformance/fixtures/event-lineage.valid.json

@@ -0,0 +1,26 @@
+{
+  "protocol": "mcp-event-intelligence",
+  "protocolVersion": "0.1.0",
+  "schemaVersion": "ei.v0.1",
+  "traceId": "trace_fixture_001",
+  "environmentId": "env_test",
+  "subscriptionId": "sub_fixture",
+  "sourceEventId": "evt_fixture",
+  "observedAt": "2026-09-18T06:30:00.000Z",
+  "source": {
+    "serverId": "github-mcp",
+    "transport": "webhook",
+    "provider": "github",
+    "cursor": null
+  },
+  "target": {
+    "runtime": "openai-agents",
+    "kind": "session",
+    "id": "session_fixture"
+  },
+  "event": {
+    "name": "issue.opened",
+    "occurredAt": "2026-09-18T06:29:59.000Z",
+    "payloadHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  }
+}

package/conformance/reference-host.mjs

@@ -0,0 +1,145 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createEventIntelligenceHost } from '../scripts/host-integration.mjs';
+import { runHostConformance } from '../scripts/host-conformance.mjs';
+
+export const referenceHostAdapter = {
+  name: 'event-intelligence-reference-host',
+
+  async createHarness({ observability }) {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), 'ei-host-conformance-'));
+    const externalDeliveries = [];
+    let host = null;
+
+    const start = async () => {
+      host = await createEventIntelligenceHost({
+        dataDir,
+        observability,
+        env: {
+          TYPESAFE_API_KEY: '',
+          RUNTIME_WAKE_TARGETS_JSON: '{}',
+          TEMPORAL_TICK_MS: '100000',
+          WAKE_RETRY_TICK_MS: '100000',
+        },
+        wake: async (packet, activation) => {
+          const runtimeReceiptId = `conformance:${packet.wake_id}`;
+          externalDeliveries.push({
+            triggerId: activation.trigger.triggerId,
+            wakeId: packet.wake_id,
+            runtimeReceiptId,
+          });
+          return { runtimeReceiptId };
+        },
+      });
+    };
+
+    await start();
+
+    await host.triggerControl.registerEventSource({
+      sourceId: 'conformance:value-changed',
+      connectionId: 'conformance-connection',
+      serverId: 'conformance',
+      eventName: 'conformance.value.changed',
+      delivery: ['poll'],
+      payloadSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['value'],
+        properties: {
+          value: { type: 'number' },
+          secretProbe: { type: 'string' },
+        },
+      },
+      enabled: true,
+    }, {
+      type: 'system',
+      principal_id: 'host-conformance',
+    });
+
+    return {
+      async createTrigger({
+        triggerId,
+        threshold,
+        oneShot,
+        maxFirings,
+      }) {
+        const planned = await host.planTrigger({
+          triggerId,
+          events: [{
+            id: 'value',
+            event: 'conformance.value.changed',
+            serverId: 'conformance',
+            where: [{
+              path: 'value',
+              op: 'gt',
+              value: threshold,
+            }],
+          }],
+          lifecycle: {
+            oneShot,
+            ...(maxFirings === undefined ? {} : { maxFirings }),
+          },
+          target: {
+            runtime: 'conformance-host',
+            kind: 'task',
+            id: triggerId,
+          },
+          continuation: {
+            instruction: 'Continue the isolated Event Intelligence conformance scenario.',
+          },
+        });
+
+        await host.triggerControl.createTrigger({
+          definition: planned.definition,
+          connectionIds: planned.connectionIds,
+          actor: { type: 'user', principal_id: 'host-conformance-user' },
+          owner: { type: 'user', principal_id: 'host-conformance-user' },
+        });
+      },
+
+      async emitEvent({ eventId, value, secretProbe }) {
+        await host.runtime.compositeEventConsumer.ingestCorrelatable({
+          traceId: `conformance:${eventId}`,
+          sourceEventId: eventId,
+          name: 'conformance.value.changed',
+          serverId: 'conformance',
+          provider: 'conformance',
+          occurredAt: new Date().toISOString(),
+          data: {
+            value,
+            ...(secretProbe ? { secretProbe } : {}),
+          },
+        });
+      },
+
+      deliveries() {
+        return [...externalDeliveries];
+      },
+
+      async restart() {
+        await host.close();
+        await start();
+      },
+
+      async inspectTrigger(triggerId) {
+        const rows = await host.triggerControl.listTriggers();
+        const entry = rows.find(
+          (candidate) => candidate.definition.triggerId === triggerId,
+        );
+        return entry?.state ?? null;
+      },
+
+      async close() {
+        await host?.close();
+        await rm(dataDir, { recursive: true, force: true });
+      },
+    };
+  },
+};
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const report = await runHostConformance(referenceHostAdapter);
+  console.log(JSON.stringify(report, null, 2));
+  if (!report.passed) process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "MCP-native complex event processing for durable agent workflows: event-time patterns, semantic predicates, derived events, and targeted wakeups.",
   "license": "Apache-2.0",
   "type": "module",
@@ -26,6 +26,14 @@
     "./embedded": {
       "types": "./scripts/embedded-host-kit.d.mts",
       "import": "./scripts/embedded-host-kit.mjs"
+    },
+    "./observability": {
+      "types": "./scripts/lib/observability.d.mts",
+      "import": "./scripts/lib/observability.mjs"
+    },
+    "./conformance": {
+      "types": "./scripts/host-conformance.d.mts",
+      "import": "./scripts/host-conformance.mjs"
     }
   },
   "bin": {
@@ -47,7 +55,10 @@
     "scripts/host-integration.d.mts",
     "scripts/run-tests.mjs",
     "scripts/embedded-host-kit.mjs",
-    "scripts/embedded-host-kit.d.mts"
+    "scripts/embedded-host-kit.d.mts",
+    "scripts/host-conformance.mjs",
+    "scripts/host-conformance.d.mts",
+    "conformance/"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -64,7 +75,8 @@
     "conformance:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-conformance.mjs",
     "bench:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-benchmark.mjs --profile quick",
     "evidence:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-conformance.mjs && node scripts/evidence/pattern-v2-benchmark.mjs --profile quick",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "conformance:host": "npm run build && node conformance/reference-host.mjs"
   },
   "keywords": [
     "mcp",

package/scripts/embedded-host-kit.mjs

@@ -903,6 +903,7 @@ export async function createEmbeddedEventIntelligence({
   mcp,
   mcpClients = [],
   semanticEvaluator,
+  observability,
   activation,
   wake,
   wakeHandlers = {},
@@ -932,6 +933,7 @@ export async function createEmbeddedEventIntelligence({
     mcpRegistry: registry,
     mcpClients,
     semanticEvaluator,
+    observability,
     ...(wakeHandler ? { wake: wakeHandler } : {}),
     wakeHandlers,
   });
@@ -983,6 +985,7 @@ export async function createEmbeddedRuntimeIntegration({
   eventSources,
   mcpClients = [],
   semanticEvaluator,
+  observability,
   activation,
   wake,
   wakeHandlers = {},
@@ -1042,6 +1045,7 @@ export async function createEmbeddedRuntimeIntegration({
       : {}),
     mcpClients,
     semanticEvaluator,
+    observability,
     activation,
     wake,
     wakeHandlers,

package/scripts/host-conformance.d.mts

@@ -0,0 +1,75 @@
+import type {
+  EventIntelligenceObservabilityEvent,
+} from './lib/observability.d.mts';
+
+export interface HostConformanceTriggerInput {
+  triggerId: string;
+  threshold: number;
+  oneShot: boolean;
+  maxFirings?: number;
+}
+
+export interface HostConformanceEventInput {
+  eventId: string;
+  value: number;
+  secretProbe?: string;
+}
+
+export interface HostConformanceDelivery {
+  triggerId: string;
+  wakeId?: string;
+  runtimeReceiptId?: string;
+  [key: string]: unknown;
+}
+
+export interface HostConformanceHarness {
+  createTrigger(input: HostConformanceTriggerInput): Promise<void>;
+  emitEvent(input: HostConformanceEventInput): Promise<void>;
+  deliveries(): Promise<readonly HostConformanceDelivery[]> | readonly HostConformanceDelivery[];
+  restart(): Promise<void>;
+  inspectTrigger(triggerId: string): Promise<{
+    status?: string;
+    fireCount?: number;
+    [key: string]: unknown;
+  } | null>;
+  close(): Promise<void>;
+}
+
+export interface HostConformanceAdapter {
+  name?: string;
+  createHarness(input: {
+    observability(event: EventIntelligenceObservabilityEvent): void;
+  }): Promise<HostConformanceHarness> | HostConformanceHarness;
+}
+
+export interface HostConformanceResult {
+  id: string;
+  status: 'pass' | 'fail';
+  durationMs: number;
+  detail?: unknown;
+  error?: string;
+}
+
+export interface HostConformanceReport {
+  schema: 'event-intelligence.host-conformance.v1' | string;
+  adapter: string;
+  passed: boolean;
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+  };
+  results: readonly HostConformanceResult[];
+  observability: {
+    captured: number;
+    eventNames: readonly string[];
+  };
+}
+
+export const HOST_CONFORMANCE_REPORT_SCHEMA:
+  'event-intelligence.host-conformance.v1';
+
+export function runHostConformance(
+  adapter: HostConformanceAdapter,
+  options?: { throwOnFailure?: boolean },
+): Promise<HostConformanceReport>;