mcp-event-intelligence 0.3.1 → 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/dist/src/protocol/types.d.ts

@@ -26,6 +26,7 @@ export interface EventDescriptor {
     delivery: Array<'poll' | 'push' | 'webhook'>;
     inputSchema: Record<string, unknown>;
     payloadSchema: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
 }
 export interface EventOccurrence<TData extends Record<string, unknown> = Record<string, unknown>> {
     eventId: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.3.1",
-  "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

@@ -11,6 +11,33 @@ export interface HostMcpClientLike {
   getServerCapabilities?(): unknown;
 }
 
+export interface HostMcpEventDeliveryCallbacks {
+  subscriptionId: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  cursor: string | null;
+  onEvent(event: Record<string, unknown>): Promise<void>;
+  onActive(state?: Record<string, unknown>): Promise<void>;
+  onGap(state?: Record<string, unknown>): Promise<void>;
+  onError(error: unknown): void;
+  onTerminated(detail?: unknown): Promise<void>;
+}
+
+export type HostMcpEventDeliveryHandle =
+  | (() => void | Promise<void>)
+  | {
+      cursor?: string | null;
+      truncated?: boolean;
+      close?(): void | Promise<void>;
+      cancel?(): void | Promise<void>;
+      unsubscribe?(): void | Promise<void>;
+    };
+
+export type HostMcpEventDeliveryOpener = (
+  input: HostMcpEventDeliveryCallbacks,
+) => HostMcpEventDeliveryHandle | Promise<HostMcpEventDeliveryHandle>;
+
+
 export interface HostMcpConnectionOptions {
   connectionId?: string;
   id?: string;
@@ -18,6 +45,8 @@ export interface HostMcpConnectionOptions {
   serverId?: string;
   client?: HostMcpClientLike;
   request?: (method: string, params?: unknown) => Promise<unknown>;
+  getCapabilities?: () => unknown | Promise<unknown>;
+  capabilities?: Record<string, unknown>;
   enabled?: boolean;
   /** Isolation partition used by the shared EI host. Defaults to \"default\". */
   scopeId?: string;
@@ -25,6 +54,14 @@ export interface HostMcpConnectionOptions {
   maxEvents?: number;
   /** Maximum number of immediately drained pages when the provider reports hasMore. */
   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. */
+  createWebhookSubscription?: HostMcpEventDeliveryOpener;
 }
 
 export interface HostMcpRegistry {
@@ -78,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;
@@ -113,9 +154,15 @@ export function createHostMcpEventsConnection(
   connectionId: string;
   serverId: string;
   request(method: string, params?: unknown): Promise<unknown>;
+  getCapabilities(): unknown | Promise<unknown>;
   enabled: boolean;
   pollIntervalMs: number;
   maxEvents: number;
+  maxPollBatches: number;
+  preferredDelivery: 'poll' | 'push' | 'webhook' | null;
+  compatibilityProfile: string;
+  openEventStream: HostMcpEventDeliveryOpener | null;
+  createWebhookSubscription: HostMcpEventDeliveryOpener | null;
 };
 
 export function createEventIntelligenceHost(

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

@@ -34,6 +34,8 @@ export class CompositeEventConsumer {
     serverId,
     provider,
     traceId,
+    subscriptionArguments,
+    receivedAt,
   }) {
     const correlatable = await mcpOccurrenceToCorrelatableEvent(
       event,
@@ -41,6 +43,8 @@ export class CompositeEventConsumer {
         traceId,
         ...(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/json-schema.mjs

@@ -0,0 +1,134 @@
+function assertRecord(value, message) {
+  if (!value || Array.isArray(value) || typeof value !== 'object') {
+    throw new Error(message);
+  }
+  return value;
+}
+
+function schemaTypes(schema) {
+  if (Array.isArray(schema?.type)) return schema.type.map(String);
+  return schema?.type === undefined ? [] : [String(schema.type)];
+}
+
+export function assertJsonSchemaValue(schemaInput, value, path = '$') {
+  if (!schemaInput || Array.isArray(schemaInput) || typeof schemaInput !== 'object') {
+    return;
+  }
+  const schema = schemaInput;
+
+  if (
+    Object.prototype.hasOwnProperty.call(schema, 'const') &&
+    !Object.is(schema.const, value)
+  ) {
+    throw new Error(`JSON Schema violation at ${path}: const mismatch`);
+  }
+
+  if (
+    Array.isArray(schema.enum) &&
+    !schema.enum.some((entry) => Object.is(entry, value))
+  ) {
+    throw new Error(`JSON Schema violation at ${path}: value not in enum`);
+  }
+
+  const types = schemaTypes(schema);
+  if (types.length) {
+    const matches = types.some((type) => {
+      if (type === 'null') return value === null;
+      if (type === 'array') return Array.isArray(value);
+      if (type === 'object') {
+        return value !== null && !Array.isArray(value) && typeof value === 'object';
+      }
+      if (type === 'integer') return Number.isInteger(value);
+      if (type === 'number') return typeof value === 'number' && Number.isFinite(value);
+      if (type === 'string') return typeof value === 'string';
+      if (type === 'boolean') return typeof value === 'boolean';
+      return false;
+    });
+    if (!matches) {
+      throw new Error(
+        `JSON Schema violation at ${path}: expected ${types.join('|')}`,
+      );
+    }
+  }
+
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+      throw new Error(`JSON Schema violation at ${path}: string too short`);
+    }
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+      throw new Error(`JSON Schema violation at ${path}: string too long`);
+    }
+    if (typeof schema.pattern === 'string') {
+      const re = new RegExp(schema.pattern);
+      if (!re.test(value)) {
+        throw new Error(`JSON Schema violation at ${path}: pattern mismatch`);
+      }
+    }
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    if (typeof schema.minimum === 'number' && value < schema.minimum) {
+      throw new Error(`JSON Schema violation at ${path}: below minimum`);
+    }
+    if (typeof schema.maximum === 'number' && value > schema.maximum) {
+      throw new Error(`JSON Schema violation at ${path}: above maximum`);
+    }
+  }
+
+  if (value !== null && !Array.isArray(value) && typeof value === 'object') {
+    const record = value;
+    const required = Array.isArray(schema.required)
+      ? schema.required.map(String)
+      : [];
+    for (const key of required) {
+      if (!Object.prototype.hasOwnProperty.call(record, key)) {
+        throw new Error(
+          `JSON Schema violation at ${path}: missing required property ${key}`,
+        );
+      }
+    }
+
+    const properties =
+      schema.properties &&
+      !Array.isArray(schema.properties) &&
+      typeof schema.properties === 'object'
+        ? schema.properties
+        : {};
+
+    for (const [key, childSchema] of Object.entries(properties)) {
+      if (
+        Object.prototype.hasOwnProperty.call(record, key) &&
+        childSchema &&
+        !Array.isArray(childSchema) &&
+        typeof childSchema === 'object'
+      ) {
+        assertJsonSchemaValue(childSchema, record[key], `${path}.${key}`);
+      }
+    }
+
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(record)) {
+        if (!Object.prototype.hasOwnProperty.call(properties, key)) {
+          throw new Error(
+            `JSON Schema violation at ${path}: unexpected property ${key}`,
+          );
+        }
+      }
+    }
+  }
+
+  if (
+    Array.isArray(value) &&
+    schema.items &&
+    !Array.isArray(schema.items) &&
+    typeof schema.items === 'object'
+  ) {
+    value.forEach((entry, index) =>
+      assertJsonSchemaValue(schema.items, entry, `${path}[${index}]`),
+    );
+  }
+}
+
+export function assertJsonObject(value, message) {
+  return assertRecord(value, message);
+}

package/scripts/lib/local-event-intelligence-runtime.mjs

@@ -65,6 +65,7 @@ const REQUIRED_STORE_METHODS = [
   'appendAudit',
   'auditLength',
   'getMcpClientState',
+  'listMcpClientStates',
   'putMcpClientState',
   'appendMcpOccurrence',
 ];