mcp-event-intelligence 0.4.0 → 0.5.0

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

@@ -0,0 +1,54 @@
+export const MCP_EVENTS_EXTENSION_ID = 'io.modelcontextprotocol/events';
+
+export const MCP_EVENTS_COMPATIBILITY_PROFILES = Object.freeze({
+  'experimental-extension-2026-09-25': Object.freeze({
+    id: 'experimental-extension-2026-09-25',
+    capabilityStyle: 'extension',
+    extensionId: MCP_EVENTS_EXTENSION_ID,
+    listMethod: 'events/list',
+    pollMethod: 'events/poll',
+    deliveryModes: Object.freeze(['poll', 'push', 'webhook']),
+    experimental: true,
+  }),
+});
+
+export const DEFAULT_MCP_EVENTS_COMPATIBILITY_PROFILE =
+  'experimental-extension-2026-09-25';
+
+export function getMcpEventsCompatibilityProfile(profileId) {
+  const id =
+    !profileId || profileId === 'auto'
+      ? DEFAULT_MCP_EVENTS_COMPATIBILITY_PROFILE
+      : String(profileId);
+  const profile = MCP_EVENTS_COMPATIBILITY_PROFILES[id];
+  if (!profile) {
+    const error = new Error(`Unknown MCP Events compatibility profile: ${id}`);
+    error.code = 'MCP_EVENTS_PROFILE_UNKNOWN';
+    throw error;
+  }
+  return profile;
+}
+
+export function profileAdvertisedByCapabilities(profile, capabilities = {}) {
+  if (profile.capabilityStyle !== 'extension') return false;
+  const extensions =
+    capabilities?.extensions &&
+    !Array.isArray(capabilities.extensions) &&
+    typeof capabilities.extensions === 'object'
+      ? capabilities.extensions
+      : {};
+  return Object.prototype.hasOwnProperty.call(
+    extensions,
+    profile.extensionId,
+  );
+}
+
+export function resolveMcpEventsCompatibilityProfile({
+  capabilities,
+  requested = 'auto',
+} = {}) {
+  const profile = getMcpEventsCompatibilityProfile(requested);
+  return profileAdvertisedByCapabilities(profile, capabilities)
+    ? profile
+    : null;
+}

package/scripts/lib/trigger-control-plane.mjs

@@ -67,6 +67,47 @@ function scalarSchemaForConstant(value) {
   return {};
 }
 
+function walkPatternValue(value, visitor) {
+  if (!value || typeof value !== 'object') return;
+  if (value.kind === 'field') {
+    visitor(value.ref, value.path, 'pattern value');
+    return;
+  }
+  if (value.kind === 'arithmetic') {
+    for (const arg of value.args ?? []) walkPatternValue(arg, visitor);
+  }
+}
+
+function walkPatternNode(node, visitor) {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.kind === 'compare') {
+    walkPatternValue(node.left, visitor);
+    if (node.right) walkPatternValue(node.right, visitor);
+  }
+  if (
+    node.kind === 'aggregate' ||
+    node.kind === 'state' ||
+    node.kind === 'distinct'
+  ) {
+    if (node.path) visitor(node.ref, node.path, `pattern ${node.kind}`);
+  }
+  if (node.kind === 'semantic') {
+    for (const input of node.input ?? []) {
+      const [ref, ...parts] = String(input).split('.');
+      if (ref && parts.length) {
+        visitor(ref, parts.join('.'), 'pattern semantic input');
+      }
+    }
+  }
+
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) walkPatternNode(child, visitor);
+  }
+  if (node.child) walkPatternNode(node.child, visitor);
+  if (node.forbidden) walkPatternNode(node.forbidden, visitor);
+}
+
 function assertSubscriptionArguments(source, args, purpose) {
   const inputSchema = source?.inputSchema;
   if (
@@ -742,6 +783,59 @@ export class TriggerControlPlane {
       );
     }
 
+    if (definition.patternV2) {
+      const clauseForRef = (ref) =>
+        definition.clauses.find((candidate) => candidate.id === ref);
+      const sourceForRef = (ref) => {
+        const clause = clauseForRef(ref);
+        return clause ? resolveSource(clause) : null;
+      };
+
+      for (const dimension of definition.patternV2.partitionBy ?? []) {
+        for (const field of dimension.fields ?? []) {
+          assertAdvertisedPath(
+            sourceForRef(field.ref),
+            field.path,
+            `Pattern partition ${dimension.key}`,
+          );
+        }
+      }
+
+      walkPatternNode(definition.patternV2.root, (ref, fieldPath, purpose) => {
+        assertAdvertisedPath(
+          sourceForRef(ref),
+          fieldPath,
+          purpose,
+        );
+      });
+    }
+
+    for (const measure of definition.derivedEvent?.measures ?? []) {
+      const expression = measure.expression;
+      const clauseForRef = (ref) =>
+        definition.clauses.find((candidate) => candidate.id === ref);
+      const sourceForRef = (ref) => {
+        const clause = clauseForRef(ref);
+        return clause ? resolveSource(clause) : null;
+      };
+
+      if (expression.kind === 'aggregate' && expression.path) {
+        assertAdvertisedPath(
+          sourceForRef(expression.ref),
+          expression.path,
+          `Derived measure ${measure.key}`,
+        );
+      } else {
+        walkPatternValue(expression, (ref, fieldPath) => {
+          assertAdvertisedPath(
+            sourceForRef(ref),
+            fieldPath,
+            `Derived measure ${measure.key}`,
+          );
+        });
+      }
+    }
+
     for (const projection of definition.derivedEvent?.projections ?? []) {
       const clause = definition.clauses.find(
         (candidate) => candidate.id === projection.ref,
@@ -806,6 +900,65 @@ export class TriggerControlPlane {
     }
 
     const allSources = this.store.listEventSources();
+    const sourceSchemaForRefPath = (ref, fieldPath) => {
+      const clause = definition.clauses.find(
+        (candidate) => candidate.id === ref,
+      );
+      const source = clause
+        ? allSources.find(
+            (candidate) =>
+              candidate.eventName === clause.event &&
+              candidate.serverId === clause.serverId &&
+              (
+                !clause.contractVersion ||
+                String(candidate.metadata?.contractVersion || '') ===
+                  String(clause.contractVersion)
+              ),
+          )
+        : null;
+      return getSchemaNode(source?.payloadSchema, fieldPath) ?? {};
+    };
+
+    const schemaForMeasureExpression = (expression) => {
+      if (!expression || typeof expression !== 'object') return {};
+      if (expression.kind === 'literal') {
+        if (expression.value === null) return { type: 'null' };
+        return scalarSchemaForConstant(expression.value);
+      }
+      if (expression.kind === 'field') {
+        return sourceSchemaForRefPath(expression.ref, expression.path);
+      }
+      if (
+        expression.kind === 'occurredAt' ||
+        expression.kind === 'arithmetic'
+      ) {
+        return { type: 'number' };
+      }
+      if (expression.kind === 'aggregate') {
+        if (
+          ['count', 'countDistinct'].includes(expression.function)
+        ) {
+          return { type: 'integer' };
+        }
+        if (
+          ['sum', 'avg', 'min', 'max', 'stddev', 'percentile']
+            .includes(expression.function)
+        ) {
+          return { type: 'number' };
+        }
+        return sourceSchemaForRefPath(
+          expression.ref,
+          expression.path,
+        );
+      }
+      return {};
+    };
+
+    for (const measure of definition.derivedEvent.measures ?? []) {
+      properties[measure.key] =
+        schemaForMeasureExpression(measure.expression);
+    }
+
     for (const projection of definition.derivedEvent.projections ?? []) {
       const clause = definition.clauses.find(
         (candidate) => candidate.id === projection.ref,
@@ -832,6 +985,7 @@ export class TriggerControlPlane {
       required: [
         '_derived',
         ...Object.keys(definition.derivedEvent.constants ?? {}),
+        ...(definition.derivedEvent.measures ?? []).map((measure) => measure.key),
       ],
     };
   }

package/scripts/lib/trigger-inspector.mjs

@@ -166,6 +166,18 @@ function explain({
     };
   }
 
+  if (definition.patternV2) {
+    return {
+      code: 'pattern_v2_waiting',
+      summary:
+        'Pattern AST v2 has buffered evidence but no new complete match is currently eligible.',
+      patternVersion: '2',
+      bufferRole: match.patternState?.role ?? null,
+      semanticDecisions:
+        match.patternState?.semanticDecisions ?? [],
+    };
+  }
+
   const missing = clauses
     .filter((clause) => clause.status !== 'satisfied')
     .map((clause) => clause.clauseId);
@@ -312,6 +324,7 @@ export class TriggerInspector {
         derivedEvent: definition.derivedEvent ?? null,
         expression: definition.expression,
         temporal: definition.temporal ?? [],
+        patternV2: definition.patternV2 ?? null,
         lifecycle: definition.lifecycle ?? {},
       },
       lifecycle: state,
@@ -323,6 +336,7 @@ export class TriggerInspector {
             openedAt: match.openedAt,
             expiresAt: match.expiresAt,
             updatedAt: match.updatedAt,
+            patternState: match.patternState ?? null,
           }
         : null,
       clauses,
@@ -360,6 +374,7 @@ export class TriggerInspector {
           rootEvidence: record.rootEvidence,
         })),
         matchHistory,
+        patternState: match?.patternState ?? null,
       },
       why: explain({
         definition,

package/scripts/lib/trigger-planner.mjs

@@ -1,5 +1,6 @@
 import {
   canonicalJson,
+  collectPatternRefs,
   parseCompositeTriggerDefinition,
   parseTriggerPlanInput,
   sha256Hex,
@@ -88,6 +89,104 @@ function validatePredicateAgainstSource(source, predicate, warnings) {
       [source],
     );
   }
+
+  if (
+    ['startsWith', 'endsWith', 'regex'].includes(predicate.op) &&
+    node?.type &&
+    node.type !== 'string'
+  ) {
+    throw sourceError(
+      'TRIGGER_PLAN_STRING_FIELD_REQUIRED',
+      `Predicate ${predicate.op} requires a string field, but ${predicate.path} is ${node.type}`,
+      [source],
+    );
+  }
+}
+
+function clauseSourceForRef(ref, clauses, resolvedSources) {
+  const index = clauses.findIndex((clause) => clause.id === ref);
+  if (index < 0) {
+    const error = new Error(`Temporal condition references unknown event id: ${ref}`);
+    error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+    throw error;
+  }
+  return resolvedSources[index];
+}
+
+function validateTemporalConditions(conditions, clauses, resolvedSources, warnings) {
+  const refs = new Set(clauses.map((clause) => clause.id));
+
+  for (const condition of conditions) {
+    const referenced = [];
+    if ('ref' in condition) referenced.push(condition.ref);
+    if ('afterRef' in condition) referenced.push(condition.afterRef);
+    if ('beforeRef' in condition) referenced.push(condition.beforeRef);
+
+    for (const ref of referenced) {
+      if (!refs.has(ref)) {
+        const error = new Error(
+          `Temporal condition ${condition.id} references unknown event id: ${ref}`,
+        );
+        error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+        throw error;
+      }
+    }
+
+    if (condition.kind === 'distinct') {
+      const source = clauseSourceForRef(
+        condition.ref,
+        clauses,
+        resolvedSources,
+      );
+      validatePredicateAgainstSource(
+        source,
+        { path: condition.path, op: 'exists', value: true },
+        warnings,
+      );
+    }
+  }
+}
+
+function walkPatternValue(value, visitor) {
+  if (!value || typeof value !== 'object') return;
+  if (value.kind === 'field') {
+    visitor(value.ref, value.path, 'pattern value');
+    return;
+  }
+  if (value.kind === 'arithmetic') {
+    for (const arg of value.args ?? []) walkPatternValue(arg, visitor);
+  }
+}
+
+function walkPatternNode(node, visitor) {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.kind === 'compare') {
+    walkPatternValue(node.left, visitor);
+    if (node.right) walkPatternValue(node.right, visitor);
+  }
+  if (
+    (node.kind === 'aggregate' ||
+      node.kind === 'state' ||
+      node.kind === 'distinct') &&
+    node.path
+  ) {
+    visitor(node.ref, node.path, `pattern ${node.kind}`);
+  }
+  if (node.kind === 'semantic') {
+    for (const input of node.input ?? []) {
+      const [ref, ...parts] = String(input).split('.');
+      if (ref && parts.length) {
+        visitor(ref, parts.join('.'), 'pattern semantic input');
+      }
+    }
+  }
+
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) walkPatternNode(child, visitor);
+  }
+  if (node.child) walkPatternNode(node.child, visitor);
+  if (node.forbidden) walkPatternNode(node.forbidden, visitor);
 }
 
 function expressionFor(match, refs) {
@@ -185,8 +284,69 @@ export class TriggerPlanner {
     });
 
     const refs = clauses.map((clause) => clause.id);
+
+    if (plan.patternV2) {
+      const patternRefs = collectPatternRefs(plan.patternV2.root);
+      for (const ref of patternRefs) {
+        if (!refs.includes(ref)) {
+          const error = new Error(
+            `Pattern AST v2 references unknown event id: ${ref}`,
+          );
+          error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+          throw error;
+        }
+      }
+
+      const sourceForRef = (ref) => {
+        const index = clauses.findIndex((candidate) => candidate.id === ref);
+        if (index < 0) {
+          const error = new Error(
+            `Pattern AST v2 references unknown event id: ${ref}`,
+          );
+          error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+          throw error;
+        }
+        return resolvedSources[index];
+      };
+
+      walkPatternNode(plan.patternV2.root, (ref, fieldPath, purpose) => {
+        validatePredicateAgainstSource(
+          sourceForRef(ref),
+          { path: fieldPath, op: 'exists', value: true },
+          warnings,
+        );
+      });
+
+      for (const dimension of plan.patternV2.partitionBy) {
+        for (const field of dimension.fields) {
+          const clauseIndex = clauses.findIndex(
+            (candidate) => candidate.id === field.ref,
+          );
+          if (clauseIndex < 0) {
+            const error = new Error(
+              `Pattern partition references unknown event id: ${field.ref}`,
+            );
+            error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+            throw error;
+          }
+          validatePredicateAgainstSource(
+            resolvedSources[clauseIndex],
+            { path: field.path, op: 'exists', value: true },
+            warnings,
+          );
+        }
+      }
+    } else {
+      validateTemporalConditions(
+        plan.temporal,
+        clauses,
+        resolvedSources,
+        warnings,
+      );
+    }
+
     const correlation = {};
-    if (plan.correlateBy) {
+    if (!plan.patternV2 && plan.correlateBy) {
       for (const field of plan.correlateBy) {
         if (!refs.includes(field.eventId)) {
           const error = new Error(
@@ -211,32 +371,46 @@ export class TriggerPlanner {
         })),
       };
     }
-    if (plan.semanticCorrelation) {
+    if (!plan.patternV2 && plan.semanticCorrelation) {
       correlation.semantic = plan.semanticCorrelation;
     }
 
     const triggerId = plan.triggerId || `planned_${(
       await sha256Hex(canonicalJson({
-        target: plan.target,
+        target: plan.target ?? null,
         events: plan.events,
         match: plan.match,
-        continuation: plan.continuation.instruction,
+        temporal: plan.temporal,
+        patternV2: plan.patternV2 ?? null,
+        eventTime: plan.eventTime ?? null,
+        conditionOnly: plan.conditionOnly,
+        continuation: plan.continuation?.instruction ?? null,
       }))
     ).slice(0, 24)}`;
 
     const definition = parseCompositeTriggerDefinition({
       triggerId,
       version: plan.version,
-      description:
-        plan.description ||
-        plan.continuation.instruction.slice(0, 500),
-      continuation: plan.continuation,
+      ...(plan.description || plan.continuation?.instruction
+        ? {
+            description:
+              plan.description ||
+              plan.continuation.instruction.slice(0, 500),
+          }
+        : {}),
+      conditionOnly: plan.conditionOnly,
+      ...(plan.continuation ? { continuation: plan.continuation } : {}),
       clauses,
-      expression: expressionFor(plan.match, refs),
+      expression: plan.patternV2
+        ? { kind: 'anyOf', refs }
+        : expressionFor(plan.match, refs),
+      temporal: plan.patternV2 ? [] : plan.temporal,
+      ...(plan.patternV2 ? { patternV2: plan.patternV2 } : {}),
       withinMs: plan.withinMs,
+      ...(plan.eventTime ? { eventTime: plan.eventTime } : {}),
       lifecycle: lifecycleFor(plan.lifecycle),
       ...(Object.keys(correlation).length ? { correlation } : {}),
-      target: plan.target,
+      ...(plan.target ? { target: plan.target } : {}),
     });
 
     return {
@@ -255,12 +429,16 @@ export class TriggerPlanner {
             arguments: clause.arguments,
             where: clause.where,
           })),
+          temporal: definition.temporal,
+          patternV2: definition.patternV2 ?? null,
           withinMs: definition.withinMs,
+          eventTime: definition.eventTime ?? { allowedLatenessMs: 0 },
         },
         then: {
-          target: definition.target,
+          conditionOnly: definition.conditionOnly,
+          target: definition.target ?? null,
           instruction: definition.continuation?.instruction ?? null,
-          evidence: definition.continuation?.contextPolicy?.evidence ?? 'matched_events',
+          evidence: definition.continuation?.contextPolicy?.evidence ?? null,
         },
       },
     };

package/scripts/mcp-stdio-server.mjs

@@ -2,6 +2,8 @@ import { McpServer } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
 import {
+  TriggerPlanInputSchema,
+  describeTriggerLanguage,
   parseCompositeTriggerDefinition,
 } from '../dist/src/intelligenceProtocol/index.js';
 import {
@@ -57,59 +59,26 @@ function ownerFromEnv(env) {
   };
 }
 
-const predicateInputSchema = z.object({
-  path: z.string().min(1),
-  op: z.enum(['eq', 'neq', 'contains', 'in', 'exists', 'gt', 'gte', 'lt', 'lte']),
-  value: z.unknown().optional(),
-});
+const triggerPlanInputSchema = TriggerPlanInputSchema;
 
-const triggerPlanInputSchema = z.object({
-  triggerId: z.string().min(1).optional(),
-  version: z.string().min(1).optional(),
-  description: z.string().max(500).optional(),
-  events: z.array(z.object({
-    id: z.string().min(1).optional(),
-    event: z.string().min(1),
-    serverId: z.string().min(1).optional(),
-    arguments: z.record(z.string(), z.unknown()).optional(),
-    where: z.array(predicateInputSchema).optional(),
-  })).min(1),
-  match: z.union([
-    z.enum(['all', 'any', 'sequence']),
-    z.object({
-      kind: z.literal('count'),
-      eventId: z.string().min(1),
-      atLeast: z.number().int().min(1),
-    }),
+const triggerLanguageDescribeInputSchema = z.object({
+  category: z.enum([
+    'predicates',
+    'composition',
+    'temporal',
+    'pattern',
+    'windows',
+    'aggregates',
+    'state',
+    'selection',
+    'semantic',
+    'execution',
+    'correlation',
+    'timing',
+    'lifecycle',
   ]).optional(),
-  withinMs: z.number().int().positive().optional(),
-  lifecycle: z.object({
-    oneShot: z.boolean().optional(),
-    maxFirings: z.number().int().min(1).optional(),
-    cooldownMs: z.number().int().nonnegative().optional(),
-    expiresAt: z.string().optional(),
-    leaseUntil: z.string().optional(),
-    completeOnGoal: z.boolean().optional(),
-  }).optional(),
-  target: z.object({
-    runtime: z.string().min(1),
-    kind: z.enum(['goal', 'session', 'conversation', 'task', 'spawn_template']),
-    id: z.string().min(1),
-  }),
-  continuation: z.object({
-    instruction: z.string().min(1).max(4000),
-    contextPolicy: z.object({
-      evidence: z.enum(['matched_events', 'refs_only']).optional(),
-      maxEvents: z.number().int().min(1).max(50).optional(),
-      includeData: z.boolean().optional(),
-    }).optional(),
-  }),
-  correlateBy: z.array(z.object({
-    eventId: z.string().min(1),
-    path: z.string().min(1),
-  })).min(2).optional(),
-  semanticCorrelation: z.record(z.string(), z.unknown()).optional(),
-});
+  operator: z.string().min(1).optional(),
+}).strict();
 
 function registerReadTools(server, runtime) {
   server.registerTool(
@@ -134,6 +103,22 @@ function registerReadTools(server, runtime) {
     },
   );
 
+  server.registerTool(
+    'trigger_language_describe',
+    {
+      description:
+        'Describe the public Event Intelligence trigger authoring language. Use this when you need to discover supported predicates, composition, temporal, correlation, timing, or lifecycle operators before planning a trigger.',
+      inputSchema: triggerLanguageDescribeInputSchema,
+    },
+    async (input) => {
+      try {
+        return jsonResult(describeTriggerLanguage(input));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
   server.registerTool(
     'trigger_plan',
     {
@@ -452,11 +437,11 @@ export async function buildEventIntelligenceMcpServer({
   const server = new McpServer(
     {
       name: 'mcp-event-intelligence',
-      version: '0.3.1',
+      version: '0.5.0',
     },
     {
       instructions:
-        'Use Event Intelligence to discover event sources, inspect/simulate durable trigger programs, and govern continuations. The agent authors structured trigger definitions using the discovered source schemas. Persistent mutations are unavailable unless the operator enables MCP_WRITE_ENABLED=true, and each mutation requires confirmationId.',
+        'Use Event Intelligence to discover event sources and the trigger authoring language, plan/inspect/simulate durable trigger programs, and govern continuations. Prefer event_sources_list plus trigger_language_describe when needed, then author through trigger_plan instead of raw canonical definitions. Persistent mutations are unavailable unless the operator enables MCP_WRITE_ENABLED=true, and each mutation requires confirmationId.',
     },
   );
 

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.sarooo17/event-intelligence",
   "title": "MCP Event Intelligence",
-  "description": "Durable temporal event intelligence: composite triggers, derived events, and runtime wakeups.",
-  "version": "0.4.0",
+  "description": "MCP-native CEP for durable agents: event-time patterns, semantic predicates, derived events.",
+  "version": "0.5.0",
   "repository": {
     "url": "https://github.com/sarooo17/event-intelligence",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-event-intelligence",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -49,7 +49,7 @@
         },
         {
           "name": "TYPESAFE_API_KEY",
-          "description": "Optional TypeSafe Jev API key for semantic-correlation triggers.",
+          "description": "Optional TypeSafe Jev API key for semantic Pattern AST nodes and legacy semantic-correlation triggers.",
           "isRequired": false,
           "isSecret": true,
           "format": "string"