mcp-event-intelligence 0.2.1 → 0.3.0

package/scripts/lib/trigger-planner.mjs

@@ -0,0 +1,247 @@
+import {
+  canonicalJson,
+  parseCompositeTriggerDefinition,
+  parseTriggerPlanInput,
+  sha256Hex,
+} from '../../dist/src/intelligenceProtocol/index.js';
+
+function schemaNodeAtPath(schema, path) {
+  if (!schema || typeof schema !== 'object') return null;
+  let node = schema;
+  for (const part of String(path).split('.')) {
+    const properties = node?.properties;
+    if (!properties || typeof properties !== 'object' || !(part in properties)) {
+      return null;
+    }
+    node = properties[part];
+  }
+  return node;
+}
+
+function sourceSummary(source) {
+  return {
+    sourceId: source.sourceId,
+    connectionId: source.connectionId,
+    serverId: source.serverId,
+    eventName: source.eventName,
+    description: source.description ?? null,
+  };
+}
+
+function sourceError(code, message, sources = []) {
+  const error = new Error(message);
+  error.code = code;
+  if (sources.length) error.sources = sources.map(sourceSummary);
+  return error;
+}
+
+function validatePredicateAgainstSource(source, predicate, warnings) {
+  const schema = source.payloadSchema;
+  if (!schema || typeof schema !== 'object' || Object.keys(schema).length === 0) {
+    warnings.push({
+      code: 'SOURCE_SCHEMA_UNAVAILABLE',
+      event: source.eventName,
+      serverId: source.serverId,
+      path: predicate.path,
+      message: 'Source does not advertise a payload schema; predicate path cannot be prevalidated.',
+    });
+    return;
+  }
+
+  const node = schemaNodeAtPath(schema, predicate.path);
+  if (!node) {
+    throw sourceError(
+      'TRIGGER_PLAN_FIELD_UNAVAILABLE',
+      `Field ${predicate.path} is not advertised by ${source.serverId}/${source.eventName}`,
+      [source],
+    );
+  }
+
+  if (
+    ['gt', 'gte', 'lt', 'lte'].includes(predicate.op) &&
+    node?.type &&
+    !['number', 'integer'].includes(node.type)
+  ) {
+    throw sourceError(
+      'TRIGGER_PLAN_NUMERIC_FIELD_REQUIRED',
+      `Predicate ${predicate.op} requires a numeric field, but ${predicate.path} is ${node.type}`,
+      [source],
+    );
+  }
+}
+
+function expressionFor(match, refs) {
+  if (typeof match === 'object' && match?.kind === 'count') {
+    if (!refs.includes(match.eventId)) {
+      const error = new Error(`Count match references unknown event id: ${match.eventId}`);
+      error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+      throw error;
+    }
+    return { kind: 'count', ref: match.eventId, atLeast: match.atLeast };
+  }
+
+  if (match === 'sequence') {
+    if (refs.length < 2) {
+      const error = new Error('Sequence match requires at least two events');
+      error.code = 'TRIGGER_PLAN_SEQUENCE_REQUIRES_MULTIPLE_EVENTS';
+      throw error;
+    }
+    return { kind: 'sequence', refs };
+  }
+
+  if (match === 'any' || refs.length === 1) {
+    return { kind: 'anyOf', refs };
+  }
+
+  return { kind: 'allOf', refs };
+}
+
+function lifecycleFor(input = {}) {
+  return {
+    oneShot: input.oneShot ?? false,
+    cooldownMs: input.cooldownMs ?? 0,
+    completeOnGoal: input.completeOnGoal ?? false,
+    ...(input.maxFirings !== undefined ? { maxFirings: input.maxFirings } : {}),
+    ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+    ...(input.leaseUntil ? { leaseUntil: input.leaseUntil } : {}),
+  };
+}
+
+export class TriggerPlanner {
+  constructor({ store }) {
+    this.store = store;
+  }
+
+  async plan(input) {
+    const plan = parseTriggerPlanInput(input);
+    const activeSources = this.store.listEventSources({ enabledOnly: true });
+    const warnings = [];
+    const resolvedSources = [];
+    const seenIds = new Set();
+
+    const clauses = plan.events.map((event, index) => {
+      const id = String(event.id || `event_${index + 1}`);
+      if (seenIds.has(id)) {
+        const error = new Error(`Duplicate plan event id: ${id}`);
+        error.code = 'TRIGGER_PLAN_DUPLICATE_EVENT_ID';
+        throw error;
+      }
+      seenIds.add(id);
+
+      const matches = activeSources.filter((source) =>
+        source.eventName === event.event &&
+        (!event.serverId || source.serverId === event.serverId)
+      );
+
+      if (matches.length === 0) {
+        throw sourceError(
+          'TRIGGER_PLAN_SOURCE_NOT_FOUND',
+          `No active source exposes ${event.serverId ? `${event.serverId}/` : ''}${event.event}`,
+          activeSources.filter((source) => source.eventName === event.event),
+        );
+      }
+      if (matches.length > 1 && !event.serverId) {
+        throw sourceError(
+          'TRIGGER_PLAN_SOURCE_AMBIGUOUS',
+          `Event ${event.event} is exposed by multiple sources; provide serverId`,
+          matches,
+        );
+      }
+
+      const source = matches[0];
+      for (const predicate of event.where) {
+        validatePredicateAgainstSource(source, predicate, warnings);
+      }
+      resolvedSources.push(source);
+
+      return {
+        id,
+        event: event.event,
+        serverId: source.serverId,
+        where: event.where,
+      };
+    });
+
+    const refs = clauses.map((clause) => clause.id);
+    const correlation = {};
+    if (plan.correlateBy) {
+      for (const field of plan.correlateBy) {
+        if (!refs.includes(field.eventId)) {
+          const error = new Error(
+            `Correlation references unknown event id: ${field.eventId}`,
+          );
+          error.code = 'TRIGGER_PLAN_EVENT_REF_UNKNOWN';
+          throw error;
+        }
+        const clause = clauses.find((candidate) => candidate.id === field.eventId);
+        const source = resolvedSources[clauses.indexOf(clause)];
+        validatePredicateAgainstSource(
+          source,
+          { path: field.path, op: 'exists', value: true },
+          warnings,
+        );
+      }
+      correlation.deterministic = {
+        kind: 'same_value',
+        fields: plan.correlateBy.map((field) => ({
+          ref: field.eventId,
+          path: field.path,
+        })),
+      };
+    }
+    if (plan.semanticCorrelation) {
+      correlation.semantic = plan.semanticCorrelation;
+    }
+
+    const triggerId = plan.triggerId || `planned_${(
+      await sha256Hex(canonicalJson({
+        target: plan.target,
+        events: plan.events,
+        match: plan.match,
+        continuation: plan.continuation.instruction,
+      }))
+    ).slice(0, 24)}`;
+
+    const definition = parseCompositeTriggerDefinition({
+      triggerId,
+      version: plan.version,
+      description:
+        plan.description ||
+        plan.continuation.instruction.slice(0, 500),
+      continuation: plan.continuation,
+      clauses,
+      expression: expressionFor(plan.match, refs),
+      withinMs: plan.withinMs,
+      lifecycle: lifecycleFor(plan.lifecycle),
+      ...(Object.keys(correlation).length ? { correlation } : {}),
+      target: plan.target,
+    });
+
+    return {
+      planVersion: '1',
+      definition,
+      connectionIds: [...new Set(resolvedSources.map((source) => source.connectionId))],
+      resolvedSources: resolvedSources.map(sourceSummary),
+      warnings,
+      explanation: {
+        when: {
+          expression: definition.expression,
+          events: clauses.map((clause) => ({
+            id: clause.id,
+            event: clause.event,
+            serverId: clause.serverId,
+            where: clause.where,
+          })),
+          withinMs: definition.withinMs,
+        },
+        then: {
+          target: definition.target,
+          instruction: definition.continuation?.instruction ?? null,
+          evidence: definition.continuation?.contextPolicy?.evidence ?? 'matched_events',
+        },
+      },
+    };
+  }
+}
+
+export default { TriggerPlanner };

package/scripts/mcp-stdio-server.mjs

@@ -57,6 +57,59 @@ 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 = 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(),
+    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),
+    }),
+  ]).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(),
+});
+
 function registerReadTools(server, runtime) {
   server.registerTool(
     'event_sources_list',
@@ -80,6 +133,22 @@ function registerReadTools(server, runtime) {
     },
   );
 
+  server.registerTool(
+    'trigger_plan',
+    {
+      description:
+        'Compile an agent-friendly trigger plan into a validated durable trigger definition using the event sources currently available. This does not mutate state and does not call another model.',
+      inputSchema: triggerPlanInputSchema,
+    },
+    async (input) => {
+      try {
+        return jsonResult(await runtime.triggerPlanner.plan(input));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
   server.registerTool(
     'trigger_list',
     {
@@ -163,6 +232,24 @@ function registerReadTools(server, runtime) {
     },
   );
 
+  server.registerTool(
+    'wake_hydrate',
+    {
+      description:
+        'Hydrate a composite wake into an Activation Envelope containing the configured continuation and matched event evidence. Evidence data is included only according to the trigger context policy.',
+      inputSchema: z.object({
+        wakeId: z.string().min(1),
+      }),
+    },
+    async ({ wakeId }) => {
+      try {
+        return jsonResult(runtime.activationHydrator.hydrateWake(wakeId));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
   server.registerTool(
     'runtime_status',
     {
@@ -198,22 +285,45 @@ function registerWriteTools(server, runtime) {
       description:
         'Create a durable trigger. Persistent MCP mutations require explicit confirmationId and MCP_WRITE_ENABLED=true.',
       inputSchema: z.object({
-        definition: z.record(z.string(), z.unknown()),
-        connectionIds: z.array(z.string()).min(1),
+        definition: z.record(z.string(), z.unknown()).optional(),
+        plan: triggerPlanInputSchema.optional(),
+        connectionIds: z.array(z.string()).min(1).optional(),
         confirmationId: z.string().min(1),
       }),
     },
-    async ({ definition, connectionIds, confirmationId }) => {
+    async ({ definition, plan, connectionIds, confirmationId }) => {
       try {
-        return jsonResult(
-          await runtime.triggerControl.createTrigger({
-            definition,
-            connectionIds,
-            actor: actor(),
-            owner: owner(),
-            confirmationId,
-          }),
-        );
+        if ((definition ? 1 : 0) + (plan ? 1 : 0) !== 1) {
+          const error = new Error('trigger_create requires exactly one of definition or plan');
+          error.code = 'TRIGGER_CREATE_INPUT_INVALID';
+          throw error;
+        }
+
+        let resolvedDefinition = definition;
+        let resolvedConnectionIds = connectionIds;
+        let planning = null;
+        if (plan) {
+          planning = await runtime.triggerPlanner.plan(plan);
+          resolvedDefinition = planning.definition;
+          resolvedConnectionIds = planning.connectionIds;
+        }
+        if (!Array.isArray(resolvedConnectionIds) || resolvedConnectionIds.length === 0) {
+          const error = new Error('connectionIds are required when trigger_create uses a raw definition');
+          error.code = 'TRIGGER_CONNECTION_REQUIRED';
+          throw error;
+        }
+
+        const receipt = await runtime.triggerControl.createTrigger({
+          definition: resolvedDefinition,
+          connectionIds: resolvedConnectionIds,
+          actor: actor(),
+          owner: owner(),
+          confirmationId,
+        });
+        return jsonResult({
+          ...receipt,
+          ...(planning ? { planning } : {}),
+        });
       } catch (error) {
         return errorResult(error);
       }
@@ -341,7 +451,7 @@ export async function buildEventIntelligenceMcpServer({
   const server = new McpServer(
     {
       name: 'mcp-event-intelligence',
-      version: '0.2.1',
+      version: '0.3.0',
     },
     {
       instructions:

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sarooo17/event-intelligence",
   "title": "MCP Event Intelligence",
   "description": "Durable temporal event intelligence: composite triggers, derived events, and runtime wakeups.",
-  "version": "0.2.1",
+  "version": "0.3.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.2.1",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },