mcp-event-intelligence 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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
+
+- add deterministic namespaced activation receipts without ambiguous component encoding;
+- allow static host-owned event connection iterables directly, snapshotting one-shot iterators safely;
+- add normalized event-source diagnostics including registry attach failures and raw refresh outcomes;
+- add generic tool/lifecycle binding for embedded runtime integrations;
+- add host-owned error projection with canonical EI fallback semantics;
+- document the reusable runtime-neutral host glue and keep named-runtime adapters out of EI core.
+
+### Fixed
+
+- prevent one-shot event iterables from disappearing on the second registry refresh;
+- preserve failed source attachment information in diagnostics instead of reporting a clean empty setup;
+- prevent receipt namespace/wake-id tuple collisions.
+
 ## [0.8.1] - 2026-10-05
 
 ### Fixed

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.1-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.1",
+  "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.d.mts

@@ -134,6 +134,8 @@ export interface ActivationDispatcherOptions<Target = RuntimeTarget> {
     packet: Record<string, unknown>;
     activation: ActivationEnvelope;
   }) => string | Promise<string>;
+  /** Optional deterministic SHA-256 receipt namespace. Mutually exclusive with receiptId. */
+  receiptNamespace?: string;
   deliver(
     input: ActivationDeliveryInput<Target>,
   ): HostWakeReceipt | string | void | Promise<HostWakeReceipt | string | void>;
@@ -160,6 +162,27 @@ export interface PortableToolCatalog<RuntimeContext = unknown> {
   capabilities(): EventIntelligenceCapabilityMetadata[];
 }
 
+export interface EventSourceDiagnostics {
+  readonly connections: number;
+  readonly eventsCapable: number;
+  readonly eventDefinitions: number;
+  readonly errors: number;
+  readonly statuses: readonly any[];
+  readonly refreshOutcomes: readonly any[];
+}
+
+export interface EmbeddedRuntimeBindOptions<
+  RuntimeContext = unknown,
+  HostTool = unknown,
+> {
+  adapt(tool: PortableAgentTool<RuntimeContext>): HostTool;
+  register(
+    tool: HostTool,
+    portableTool: PortableAgentTool<RuntimeContext>,
+  ): void;
+  onClose?(close: () => Promise<void>): void;
+}
+
 export interface EventIntelligenceAgentToolsOptions<RuntimeContext = unknown> {
   host: EventIntelligenceHost;
   resolveContext(
@@ -198,6 +221,19 @@ export interface EventIntelligenceAgentToolsOptions<RuntimeContext = unknown> {
     value: unknown;
   }): PortableProjectedResult | void | Promise<PortableProjectedResult | void>;
 
+  /**
+   * Optional host-owned projection for canonical EI failures. Returning null
+   * keeps the canonical error; projection failures also fall back to it.
+   */
+  projectError?(input: {
+    capability: EventIntelligenceCapabilityMetadata;
+    runtimeContext: RuntimeContext;
+    context?: EmbeddedToolContext;
+    phase: string;
+    error?: PortableToolResult['error'];
+    result: PortableToolResult;
+  }): PortableToolResult | void | Promise<PortableToolResult | void>;
+
   /**
    * @deprecated Compatibility only. New integrations should use control().
    */
@@ -249,6 +285,7 @@ export interface EmbeddedRuntimeTooling<RuntimeContext = unknown> {
   resolveContext: EventIntelligenceAgentToolsOptions<RuntimeContext>['resolveContext'];
   control: NonNullable<EventIntelligenceAgentToolsOptions<RuntimeContext>['control']>;
   projectResult?: EventIntelligenceAgentToolsOptions<RuntimeContext>['projectResult'];
+  projectError?: EventIntelligenceAgentToolsOptions<RuntimeContext>['projectError'];
   names?: {
     sources?: string;
     create?: string;
@@ -260,7 +297,10 @@ export interface EmbeddedRuntimeIntegrationOptions<RuntimeContext = unknown>
     EmbeddedEventIntelligenceOptions<RuntimeContext>,
     'mcpRegistry' | 'mcp' | 'agentTools'
   > {
-  eventSources?: EventSourceRegistry | EventSourceRegistryOptions;
+  eventSources?:
+    | EventSourceRegistry
+    | EventSourceRegistryOptions
+    | Iterable<EventSourceConnection>;
   tooling?: EmbeddedRuntimeTooling<RuntimeContext>;
 }
 
@@ -270,8 +310,34 @@ export interface EmbeddedRuntimeIntegration<RuntimeContext = unknown>
   readonly toolCatalog: PortableToolCatalog<RuntimeContext>;
   readonly capabilities: readonly EventIntelligenceCapabilityMetadata[];
   readonly eventSources: EventSourceRegistry | null;
+  diagnostics(): Promise<EventSourceDiagnostics>;
+  bind<HostTool>(
+    options: EmbeddedRuntimeBindOptions<RuntimeContext, HostTool>,
+  ): readonly HostTool[];
 }
 
+export function createDeterministicReceiptId(
+  namespace: string,
+  wakeId: string,
+  options?: { length?: number },
+): string;
+
+export function summarizeEventSourceStatus(
+  statuses?: readonly any[],
+  refreshOutcomes?: readonly any[],
+): EventSourceDiagnostics;
+
+export function bindEmbeddedRuntimeIntegration<
+  RuntimeContext = unknown,
+  HostTool = unknown,
+>(
+  integration: Pick<
+    EmbeddedRuntimeIntegration<RuntimeContext>,
+    'tools' | 'close'
+  >,
+  options: EmbeddedRuntimeBindOptions<RuntimeContext, HostTool>,
+): readonly HostTool[];
+
 export function createResultReference(
   input: PortableResultReference,
 ): PortableResultReference;