mcp-event-intelligence 0.4.0 → 0.5.0

package/dist/src/patternV2/legacyCompiler.d.ts

@@ -0,0 +1,3 @@
+import type { CompositeTriggerDefinition } from '../intelligenceProtocol/triggerSchemas.js';
+import { type PatternAstV2Definition } from '../intelligenceProtocol/patternV2Schemas.js';
+export declare function compileLegacyTriggerToPatternV2(definition: CompositeTriggerDefinition): PatternAstV2Definition;

package/dist/src/patternV2/legacyCompiler.js

@@ -0,0 +1,184 @@
+import { PatternAstV2DefinitionSchema, } from '../intelligenceProtocol/patternV2Schemas.js';
+function eventNode(ref) {
+    return { kind: 'event', ref };
+}
+function expressionNode(definition) {
+    const expression = definition.expression;
+    if (expression.kind === 'allOf') {
+        return {
+            kind: 'allOf',
+            children: expression.refs.map(eventNode),
+        };
+    }
+    if (expression.kind === 'anyOf') {
+        return {
+            kind: 'anyOf',
+            children: expression.refs.map(eventNode),
+        };
+    }
+    if (expression.kind === 'sequence') {
+        return {
+            kind: 'sequence',
+            children: expression.refs.map(eventNode),
+            contiguity: 'followedBy',
+        };
+    }
+    return {
+        kind: 'repeat',
+        child: eventNode(expression.ref),
+        min: expression.atLeast,
+        mode: 'greedy',
+    };
+}
+function wrapTemporal(root, condition) {
+    if (condition.kind === 'calendar') {
+        return {
+            kind: 'calendar',
+            child: root,
+            ref: condition.ref,
+            timezone: condition.timezone,
+            ...(condition.before ? { before: condition.before } : {}),
+            ...(condition.after ? { after: condition.after } : {}),
+            ...(condition.weekdays ? { weekdays: condition.weekdays } : {}),
+            ...(condition.dates ? { dates: condition.dates } : {}),
+            ...(condition.dateRange ? { dateRange: condition.dateRange } : {}),
+            ...(condition.dayOfMonth ? { dayOfMonth: condition.dayOfMonth } : {}),
+        };
+    }
+    if (condition.kind === 'absence') {
+        return {
+            kind: 'absence',
+            id: condition.id,
+            child: root,
+            ref: condition.ref,
+            afterRef: condition.afterRef,
+            ...(condition.forMs ? { forMs: condition.forMs } : {}),
+            ...(condition.untilLocalTime
+                ? { untilLocalTime: condition.untilLocalTime }
+                : {}),
+            ...(condition.timezone ? { timezone: condition.timezone } : {}),
+        };
+    }
+    if (condition.kind === 'not' || condition.kind === 'unless') {
+        return {
+            kind: 'notPresent',
+            child: root,
+            ref: condition.ref,
+        };
+    }
+    if (condition.kind === 'after') {
+        return {
+            kind: 'after',
+            child: root,
+            ref: condition.ref,
+            afterRef: condition.afterRef,
+        };
+    }
+    if (condition.kind === 'until') {
+        return {
+            kind: 'until',
+            child: root,
+            ref: condition.ref,
+            beforeRef: condition.beforeRef,
+        };
+    }
+    if (condition.kind === 'debounce') {
+        return {
+            kind: 'debounce',
+            id: condition.id,
+            child: root,
+            ref: condition.ref,
+            forMs: condition.forMs,
+        };
+    }
+    if (condition.kind === 'threshold') {
+        return {
+            kind: 'threshold',
+            child: root,
+            ref: condition.ref,
+            atLeast: condition.atLeast,
+        };
+    }
+    if (condition.kind === 'rate') {
+        return {
+            kind: 'rate',
+            child: root,
+            ref: condition.ref,
+            atLeast: condition.atLeast,
+            perMs: condition.perMs,
+        };
+    }
+    return {
+        kind: 'distinct',
+        child: root,
+        ref: condition.ref,
+        path: condition.path,
+        atLeast: condition.atLeast,
+    };
+}
+export function compileLegacyTriggerToPatternV2(definition) {
+    let root = expressionNode(definition);
+    const deterministic = definition.correlation?.deterministic;
+    if (deterministic?.fields?.length) {
+        const [anchorField, ...otherFields] = deterministic.fields;
+        if (!anchorField) {
+            throw new Error('Deterministic correlation requires at least one field');
+        }
+        for (const field of otherFields) {
+            root = {
+                kind: 'compare',
+                child: root,
+                left: {
+                    kind: 'field',
+                    ref: anchorField.ref,
+                    path: anchorField.path,
+                    select: 'last',
+                },
+                op: 'eq',
+                right: {
+                    kind: 'field',
+                    ref: field.ref,
+                    path: field.path,
+                    select: 'last',
+                },
+            };
+        }
+    }
+    for (const condition of definition.temporal ?? []) {
+        root = wrapTemporal(root, condition);
+    }
+    if (definition.correlation?.semantic) {
+        const semantic = definition.correlation.semantic;
+        root = {
+            kind: 'semantic',
+            id: 'legacy-semantic-correlation',
+            child: root,
+            refs: [...new Set(semantic.input
+                    .map((path) => path.split('.')[0])
+                    .filter(Boolean))],
+            instruction: semantic.instruction,
+            input: semantic.input,
+            matchThreshold: semantic.matchThreshold,
+            rejectThreshold: semantic.rejectThreshold,
+            uncertain: semantic.uncertain,
+            execution: {
+                cache: true,
+                timeoutMs: 5000,
+            },
+        };
+    }
+    return PatternAstV2DefinitionSchema.parse({
+        version: '2',
+        root,
+        partitionBy: [],
+        selection: {
+            overlap: 'disallow',
+            afterMatch: 'skipPastLast',
+            maxMatchesPerEvent: 10,
+        },
+        execution: {
+            maxCandidates: 512,
+            maxSemanticEvaluations: 16,
+        },
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.4.0",
-  "description": "Durable temporal event intelligence for agent hosts: host-owned MCP event discovery, composite triggers, derived events, and targeted wakeups.",
+  "version": "0.5.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",
   "main": "./dist/src/intelligenceProtocol/index.js",
@@ -61,6 +61,9 @@
     "model-context-protocol",
     "ai-agents",
     "event-driven",
+    "complex-event-processing",
+    "cep",
+    "event-time",
     "temporal",
     "durable-execution",
     "triggers",

package/scripts/host-integration.d.mts

@@ -56,6 +56,8 @@ export interface HostMcpConnectionOptions {
   maxPollBatches?: number;
   /** Prefer one advertised delivery mode when the host can provide it. */
   preferredDelivery?: 'poll' | 'push' | 'webhook';
+  /** Versioned MCP Events wire profile. Defaults to auto/current experimental snapshot. */
+  compatibilityProfile?: 'auto' | 'experimental-extension-2026-09-25' | string;
   /** Host-owned adapter for events/stream delivery. */
   openEventStream?: HostMcpEventDeliveryOpener;
   /** Host-owned adapter for webhook subscription/receiver delivery. */
@@ -113,6 +115,10 @@ export interface EventIntelligenceScopedHost {
   readonly triggerPlanner: any;
   readonly activationHydrator: any;
   readonly eventSources: any[];
+  describeTriggerLanguage(input?: {
+    category?: 'predicates' | 'composition' | 'temporal' | 'pattern' | 'windows' | 'aggregates' | 'state' | 'selection' | 'semantic' | 'execution' | 'correlation' | 'timing' | 'lifecycle';
+    operator?: string;
+  }): Record<string, unknown>;
   planTrigger(input: TriggerPlanInput): Promise<{
     planVersion: '1';
     definition: any;
@@ -154,6 +160,7 @@ export function createHostMcpEventsConnection(
   maxEvents: number;
   maxPollBatches: number;
   preferredDelivery: 'poll' | 'push' | 'webhook' | null;
+  compatibilityProfile: string;
   openEventStream: HostMcpEventDeliveryOpener | null;
   createWebhookSubscription: HostMcpEventDeliveryOpener | null;
 };

package/scripts/host-integration.mjs

@@ -1,3 +1,6 @@
+import {
+  describeTriggerLanguage,
+} from '../dist/src/intelligenceProtocol/index.js';
 import {
   createLocalEventIntelligenceRuntime,
 } from './lib/local-event-intelligence-runtime.mjs';
@@ -79,6 +82,9 @@ function scopedHostView(runtime, context) {
     planTrigger(input) {
       return context.triggerPlanner.plan(input);
     },
+    describeTriggerLanguage(input = {}) {
+      return describeTriggerLanguage(input);
+    },
     hydrateWake(wakeId) {
       return context.activationHydrator.hydrateWake(wakeId);
     },
@@ -240,6 +246,9 @@ export async function createEventIntelligenceHost({
     planTrigger(input) {
       return runtime.triggerPlanner.plan(input);
     },
+    describeTriggerLanguage(input = {}) {
+      return describeTriggerLanguage(input);
+    },
     hydrateWake(wakeId) {
       return runtime.activationHydrator.hydrateWake(wakeId);
     },

package/scripts/lib/activation-hydrator.mjs

@@ -100,6 +100,7 @@ export class ActivationHydrator {
       eventName: event.eventName,
       traceId: event.traceId,
       occurredAt: event.occurredAt,
+      ...(event.receivedAt ? { receivedAt: event.receivedAt } : {}),
       payloadHash: event.payloadHash ?? null,
       ...(includeData ? { data: event.data } : {}),
     }));

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

@@ -35,6 +35,7 @@ export class CompositeEventConsumer {
     provider,
     traceId,
     subscriptionArguments,
+    receivedAt,
   }) {
     const correlatable = await mcpOccurrenceToCorrelatableEvent(
       event,
@@ -43,6 +44,7 @@ export class CompositeEventConsumer {
         ...(provider ? { provider } : {}),
         ...(serverId ? { serverId } : {}),
         subscriptionArguments: subscriptionArguments ?? {},
+        ...(receivedAt ? { receivedAt } : {}),
       },
     );
 

package/scripts/lib/derived-event-coordinator.mjs

@@ -2,6 +2,12 @@ import {
   parseDerivedEventRecord,
   sha256Hex,
 } from '../../dist/src/intelligenceProtocol/index.js';
+import {
+  evaluateTemporalConditions,
+} from '../../dist/src/composite/temporal.js';
+import {
+  evaluatePatternMeasure,
+} from '../../dist/src/patternV2/evaluator.js';
 
 export const DERIVED_EVENT_SERVER_ID = 'event-intelligence:derived';
 export const DERIVED_EVENT_CONNECTION_ID = 'event-intelligence:derived';
@@ -26,6 +32,7 @@ function evidenceRef(source) {
     sourceEventId: source.sourceEventId,
     traceId: source.traceId,
     occurredAt: source.occurredAt,
+    ...(source.receivedAt ? { receivedAt: source.receivedAt } : {}),
     payloadHash: source.payloadHash ?? null,
     contractVersion:
       source.data?._derived?.contractVersion ?? null,
@@ -60,6 +67,51 @@ function latestForClause(match, clauseId) {
     )[0] ?? null;
 }
 
+function patternCandidateForMatch(match) {
+  const bindings = {};
+  for (const event of match.sourceEvents) {
+    bindings[event.clauseId] ??= [];
+    bindings[event.clauseId].push(event);
+  }
+  for (const events of Object.values(bindings)) {
+    events.sort((a, b) =>
+      Date.parse(a.occurredAt) - Date.parse(b.occurredAt) ||
+      a.sourceEventId.localeCompare(b.sourceEventId)
+    );
+  }
+  const events = [...match.sourceEvents].sort((a, b) =>
+    Date.parse(a.occurredAt) - Date.parse(b.occurredAt) ||
+    a.sourceEventId.localeCompare(b.sourceEventId)
+  );
+  return {
+    bindings,
+    events,
+    startIndex: events.length ? 0 : -1,
+    endIndex: events.length ? events.length - 1 : -1,
+    semanticDecisions: [],
+  };
+}
+
+function derivedOccurredAt(match, definition) {
+  const candidates = match.sourceEvents
+    .map((event) => Date.parse(event.occurredAt))
+    .filter(Number.isFinite);
+
+  const temporal = evaluateTemporalConditions(
+    definition,
+    match,
+    new Date(match.updatedAt),
+  );
+  for (const state of temporal.conditionStates) {
+    if (state.status !== 'satisfied' || !state.dueAt) continue;
+    const dueAt = Date.parse(state.dueAt);
+    if (Number.isFinite(dueAt)) candidates.push(dueAt);
+  }
+
+  if (!candidates.length) return match.updatedAt;
+  return new Date(Math.max(...candidates)).toISOString();
+}
+
 export class DerivedEventCoordinator {
   constructor({
     store,
@@ -147,6 +199,26 @@ export class DerivedEventCoordinator {
       }
     }
 
+    const measured = {};
+    if (spec.measures?.length) {
+      const candidate = patternCandidateForMatch(match);
+      for (const measure of spec.measures) {
+        const value = evaluatePatternMeasure(candidate, measure);
+        if (
+          value === undefined ||
+          (
+            value !== null &&
+            !['string', 'number', 'boolean'].includes(typeof value)
+          )
+        ) {
+          throw new Error(
+            `Derived event measure must resolve to scalar or null: ${measure.key}`,
+          );
+        }
+        measured[measure.key] = value;
+      }
+    }
+
     const contract = this.store.getDerivedContract(
       spec.name,
       spec.contractVersion,
@@ -162,6 +234,7 @@ export class DerivedEventCoordinator {
     const data = {
       ...(spec.constants ?? {}),
       ...projected,
+      ...measured,
       _derived: {
         triggerId: definition.triggerId,
         triggerVersion: definition.version,
@@ -176,7 +249,8 @@ export class DerivedEventCoordinator {
       traceId: `derived:${eventId}`,
       sourceEventId: eventId,
       name: spec.name,
-      occurredAt: match.updatedAt,
+      occurredAt: derivedOccurredAt(match, definition),
+      receivedAt: this.now().toISOString(),
       provider: 'event-intelligence',
       serverId: DERIVED_EVENT_SERVER_ID,
       payloadHash,

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

@@ -8,10 +8,14 @@ import {
   normalizeEventScopeId,
 } from './persistent-event-store.mjs';
 import { assertJsonSchemaValue } from './json-schema.mjs';
+import {
+  MCP_EVENTS_EXTENSION_ID,
+  getMcpEventsCompatibilityProfile,
+  resolveMcpEventsCompatibilityProfile,
+} from './mcp-events-compatibility.mjs';
 
 export { assertJsonSchemaValue } from './json-schema.mjs';
-
-export const MCP_EVENTS_EXTENSION_ID = 'io.modelcontextprotocol/events';
+export { MCP_EVENTS_EXTENSION_ID } from './mcp-events-compatibility.mjs';
 const UnknownResultSchema = z.unknown();
 
 function assertObject(value, message) {
@@ -116,6 +120,10 @@ function normalizeConnection(connection) {
       'maxPollBatches',
     ),
     preferredDelivery,
+    compatibilityProfile:
+      connection.compatibilityProfile === undefined
+        ? 'auto'
+        : String(connection.compatibilityProfile),
     openEventStream:
       typeof connection.openEventStream === 'function'
         ? connection.openEventStream
@@ -148,6 +156,7 @@ export function createHostMcpEventsConnection({
   maxPollBatches = 4,
   scopeId = DEFAULT_EVENT_SCOPE_ID,
   preferredDelivery,
+  compatibilityProfile = 'auto',
   openEventStream,
   createWebhookSubscription,
 } = {}) {
@@ -185,12 +194,13 @@ export function createHostMcpEventsConnection({
     maxPollBatches,
     scopeId,
     preferredDelivery,
+    compatibilityProfile,
     openEventStream,
     createWebhookSubscription,
   });
 }
 
-function sourceDescriptor(raw) {
+function sourceDescriptor(raw, profile) {
   const descriptor = assertObject(raw, 'Invalid MCP event descriptor');
   const name = String(descriptor.name || '').trim();
   if (!name) throw new Error('MCP event descriptor requires name');
@@ -199,7 +209,7 @@ function sourceDescriptor(raw) {
     : [];
   if (
     delivery.length === 0 ||
-    delivery.some((mode) => !['poll', 'push', 'webhook'].includes(mode))
+    delivery.some((mode) => !profile.deliveryModes.includes(mode))
   ) {
     throw new Error(`MCP event descriptor ${name} has invalid delivery modes`);
   }
@@ -284,6 +294,7 @@ export class McpEventsClientManager {
     this.connections = new Map();
     this.now = now;
     this.descriptors = new Map();
+    this.profiles = new Map();
     this.timers = new Map();
     this.lastErrors = new Map();
     this.scopeContexts = new Map();
@@ -364,6 +375,7 @@ export class McpEventsClientManager {
     if (timer) clearTimeout(timer);
     this.timers.delete(connectionId);
     this.descriptors.delete(connectionId);
+    this.profiles.delete(connectionId);
     this.lastErrors.delete(connectionId);
     this.pollInFlight.delete(connectionId);
 
@@ -426,20 +438,16 @@ export class McpEventsClientManager {
 
     const context = await this.scopeContext(connection);
     const capabilities = (await connection.getCapabilities()) ?? {};
-    const extensions =
-      capabilities.extensions &&
-      !Array.isArray(capabilities.extensions) &&
-      typeof capabilities.extensions === 'object'
-        ? capabilities.extensions
-        : {};
-    if (
-      !Object.prototype.hasOwnProperty.call(
-        extensions,
-        MCP_EVENTS_EXTENSION_ID,
-      )
-    ) {
+    const profile = resolveMcpEventsCompatibilityProfile({
+      capabilities,
+      requested: connection.compatibilityProfile,
+    });
+    if (!profile) {
+      const expected = getMcpEventsCompatibilityProfile(
+        connection.compatibilityProfile,
+      );
       const error = new Error(
-        `MCP server ${connectionId} does not advertise ${MCP_EVENTS_EXTENSION_ID}`,
+        `MCP server ${connectionId} does not advertise the ${expected.id} Events profile`,
       );
       error.code = 'MCP_EVENTS_CAPABILITY_UNAVAILABLE';
       throw error;
@@ -451,7 +459,7 @@ export class McpEventsClientManager {
     do {
       const listed = await this.rpc(
         connection,
-        'events/list',
+        profile.listMethod,
         cursor ? { cursor } : {},
       );
       if (!Array.isArray(listed?.events)) {
@@ -460,7 +468,7 @@ export class McpEventsClientManager {
         );
       }
       for (const raw of listed.events) {
-        const descriptor = sourceDescriptor(raw);
+        const descriptor = sourceDescriptor(raw, profile);
         if (names.has(descriptor.name)) {
           throw new Error(
             `MCP server ${connectionId} returned duplicate event descriptor ${descriptor.name}`,
@@ -492,7 +500,9 @@ export class McpEventsClientManager {
         JSON.stringify(existing.inputSchema || {}) ===
           JSON.stringify(normalized.inputSchema) &&
         JSON.stringify(existing.payloadSchema || {}) ===
-          JSON.stringify(normalized.payloadSchema);
+          JSON.stringify(normalized.payloadSchema) &&
+        existing.metadata?.compatibilityProfile === profile.id &&
+        existing.metadata?.extensionId === profile.extensionId;
 
       if (!same) {
         const register = context.triggerControl?.registerEventSource
@@ -514,7 +524,8 @@ export class McpEventsClientManager {
             metadata: {
               transport: 'host-managed-mcp',
               hostManaged: true,
-              extensionId: MCP_EVENTS_EXTENSION_ID,
+              extensionId: profile.extensionId,
+              compatibilityProfile: profile.id,
               ...(normalized._meta ? { descriptorMeta: normalized._meta } : {}),
             },
           },
@@ -527,6 +538,7 @@ export class McpEventsClientManager {
     }
 
     this.descriptors.set(connection.connectionId, descriptors);
+    this.profiles.set(connection.connectionId, profile);
     this.lastErrors.delete(connection.connectionId);
     return descriptors;
   }
@@ -596,12 +608,18 @@ export class McpEventsClientManager {
           clause.event,
           args,
         );
-        if (!desired.has(subscriptionId)) {
+        const consumerRef =
+          `${definition.triggerId}@${definition.version}:${clause.id}`;
+        const existing = desired.get(subscriptionId);
+        if (existing) {
+          existing.consumerRefs.push(consumerRef);
+        } else {
           desired.set(subscriptionId, {
             subscriptionId,
             eventName: clause.event,
             arguments: args,
             descriptor,
+            consumerRefs: [consumerRef],
           });
         }
       }
@@ -620,6 +638,7 @@ export class McpEventsClientManager {
     }
     assertJsonSchemaValue(descriptor.payloadSchema, occurrence.data);
 
+    const receivedAt = this.now().toISOString();
     const receipt = await context.store.appendMcpOccurrence(
       connection.serverId,
       occurrence,
@@ -634,6 +653,7 @@ export class McpEventsClientManager {
       traceId:
         `mcp:${connection.serverId}:${subscription.subscriptionId}:${occurrence.eventId}`,
       subscriptionArguments: subscription.arguments,
+      receivedAt,
     });
     return { accepted: true, occurrence };
   }
@@ -683,6 +703,7 @@ export class McpEventsClientManager {
         delivery: 'poll',
         status: 'scheduled',
         accepted: 0,
+        consumerCount: subscription.consumerRefs.length,
         cursor: current.cursor,
         nextPollAt: current.nextPollAt,
       };
@@ -697,7 +718,10 @@ export class McpEventsClientManager {
     let nextPollMs = connection.pollIntervalMs;
 
     do {
-      const result = await this.rpc(connection, 'events/poll', {
+      const profile =
+        this.profiles.get(connection.connectionId) ??
+        getMcpEventsCompatibilityProfile(connection.compatibilityProfile);
+      const result = await this.rpc(connection, profile.pollMethod, {
         name: subscription.eventName,
         arguments: subscription.arguments,
         cursor,
@@ -757,6 +781,7 @@ export class McpEventsClientManager {
       delivery: 'poll',
       status: 'ok',
       accepted,
+      consumerCount: subscription.consumerRefs.length,
       cursor,
       truncated,
       hasMore,
@@ -780,6 +805,7 @@ export class McpEventsClientManager {
         delivery,
         status: 'active',
         accepted: existing.accepted,
+        consumerCount: subscription.consumerRefs.length,
       };
     }
     if (existing) await this.closeSession(subscription.subscriptionId);
@@ -922,6 +948,7 @@ export class McpEventsClientManager {
       delivery,
       status: 'active',
       accepted,
+      consumerCount: subscription.consumerRefs.length,
     };
   }
 
@@ -981,6 +1008,7 @@ export class McpEventsClientManager {
           status: 'delivery_not_supported',
           delivery: null,
           accepted: 0,
+          consumerCount: subscription.consumerRefs.length,
         });
         continue;
       }
@@ -1115,12 +1143,20 @@ export class McpEventsClientManager {
       );
       const store = context?.store ?? this.store;
       const states = store.listMcpClientStates(connection.connectionId);
+      const desired = context
+        ? this.desiredSubscriptions(connection, context)
+        : new Map();
       return {
         connectionId: connection.connectionId,
         scopeId: connection.scopeId,
         serverId: connection.serverId,
         hostManaged: true,
-        extensionId: MCP_EVENTS_EXTENSION_ID,
+        extensionId:
+          this.profiles.get(connection.connectionId)?.extensionId ??
+          MCP_EVENTS_EXTENSION_ID,
+        compatibilityProfile:
+          this.profiles.get(connection.connectionId)?.id ??
+          connection.compatibilityProfile,
         events: (this.descriptors.get(connection.connectionId) || []).map(
           (event) => ({
             name: event.name,
@@ -1130,6 +1166,8 @@ export class McpEventsClientManager {
               .map((state) => ({
                 subscriptionId: state.subscriptionId,
                 arguments: state.arguments ?? {},
+                consumerCount:
+                  desired.get(state.subscriptionId)?.consumerRefs.length ?? 0,
                 delivery: state.deliveryMode,
                 cursor: state.cursor,
                 nextPollAt: state.nextPollAt ?? null,