mcp-event-intelligence 0.1.0

package/scripts/lib/generic-runtime-wake.mjs

@@ -0,0 +1,76 @@
+import { createHmac } from 'node:crypto';
+import { canonicalWakeJson } from './wake-signature.mjs';
+
+export function buildGenericRuntimeWakePacket({ wakeId, match, definition }) {
+  if (!definition.target) {
+    throw new Error('Composite trigger has no runtime target');
+  }
+  return {
+    version: '1.0.0',
+    wake_id: wakeId,
+    trigger_match_id: match.matchId,
+    trigger_id: match.triggerId,
+    trigger_version: match.triggerVersion,
+    correlation_id: match.sourceEvents[0]?.traceId ?? match.matchId,
+    target: definition.target,
+    source_event_refs: match.sourceEvents.slice(-50).map((event) => ({
+      server_id: event.serverId ?? event.provider ?? 'event-intelligence',
+      event_id: event.sourceEventId,
+      event_name: event.eventName,
+      trace_id: event.traceId,
+    })),
+    matched_at: match.updatedAt,
+  };
+}
+
+export function createSignedRuntimeWakeDeliverer({ url, secret, fetchFn = fetch, now = () => Date.now() }) {
+  if (!url || !secret) return null;
+  return async (packet) => {
+    const timestamp = String(now());
+    const signature = createHmac('sha256', secret)
+      .update(`${timestamp}.${canonicalWakeJson(packet)}`)
+      .digest('hex');
+    const response = await fetchFn(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Event-Wake-Timestamp': timestamp,
+        'X-Event-Wake-Signature': `v1=${signature}`,
+      },
+      body: JSON.stringify(packet),
+    });
+    if (!response.ok) throw new Error(`Runtime wake callback failed: HTTP_${response.status}`);
+    const receipt = await response.json();
+    if (typeof receipt.runtimeReceiptId !== 'string' || !receipt.runtimeReceiptId) {
+      throw new Error('Runtime wake callback did not return runtimeReceiptId');
+    }
+    return {
+      runtimeReceiptId: receipt.runtimeReceiptId,
+      duplicate: receipt.duplicate === true,
+      status: receipt.status ?? 'completed',
+    };
+  };
+}
+
+export function readRuntimeWakeTargets(raw) {
+  if (!raw) return new Map();
+  const parsed = JSON.parse(raw);
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+    throw new Error('RUNTIME_WAKE_TARGETS_JSON must be an object');
+  }
+  const targets = new Map();
+  for (const [runtime, value] of Object.entries(parsed)) {
+    if (!runtime || !value || typeof value !== 'object') {
+      throw new Error('Invalid runtime wake target');
+    }
+    const url = new URL(value.url);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname))) {
+      throw new Error('Runtime wake target must use HTTPS or local HTTP');
+    }
+    if (typeof value.secret !== 'string' || value.secret.length < 32) {
+      throw new Error('Runtime wake target secret must have at least 32 characters');
+    }
+    targets.set(runtime, { url: url.toString(), secret: value.secret });
+  }
+  return targets;
+}

package/scripts/lib/github-mcp-events-adapter.mjs

@@ -0,0 +1,66 @@
+const ISSUE_ACTIONS = ['opened', 'reopened', 'edited', 'closed'];
+
+function descriptor(action) {
+  return {
+    name: `github.issue.${action}`,
+    description: `A GitHub issue was ${action}.`,
+    delivery: ['poll'],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repository: { type: 'string' },
+        label: { type: 'string' },
+        sender: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+    payloadSchema: {
+      type: 'object',
+      required: ['repository', 'number', 'title', 'labels', 'action'],
+      properties: {
+        repository: { type: 'string' },
+        number: { type: 'integer' },
+        title: { type: 'string' },
+        bodyPreview: { type: 'string' },
+        labels: { type: 'array', items: { type: 'string' } },
+        sender: { type: ['string', 'null'] },
+        action: { type: 'string' },
+        url: { type: ['string', 'null'] },
+      },
+    },
+  };
+}
+
+export function githubMcpEventDescriptors() {
+  return ISSUE_ACTIONS.map(descriptor);
+}
+
+export function githubMcpEventMatcher(args, event) {
+  if (args.repository && event.data.repository !== args.repository) return false;
+  if (args.sender && event.data.sender !== args.sender) return false;
+  if (
+    args.label &&
+    (!Array.isArray(event.data.labels) ||
+      !event.data.labels.includes(args.label))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export function registerGitHubMcpEvents(server) {
+  for (const eventDescriptor of githubMcpEventDescriptors()) {
+    server.registerEvent({
+      descriptor: eventDescriptor,
+      matcher: githubMcpEventMatcher,
+    });
+  }
+}
+
+export async function ingestGitHubMcpEvent(store, event) {
+  if (!ISSUE_ACTIONS.some((action) => event.name === `github.issue.${action}`)) {
+    throw new Error(`Unsupported GitHub MCP event: ${event.name}`);
+  }
+
+  return store.appendMcpOccurrence('github-mcp-events', event);
+}

package/scripts/lib/github-webhook.mjs

@@ -0,0 +1,88 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function verifyGitHubWebhookSignature(rawBody, signature, secret) {
+  if (!secret || !signature?.startsWith('sha256=')) return false;
+
+  const expected = createHmac('sha256', secret)
+    .update(rawBody)
+    .digest('hex');
+  const actual = signature.slice('sha256='.length);
+
+  const expectedBuffer = Buffer.from(expected, 'hex');
+  const actualBuffer = Buffer.from(actual, 'hex');
+
+  if (expectedBuffer.length !== actualBuffer.length) return false;
+  return timingSafeEqual(expectedBuffer, actualBuffer);
+}
+
+export function translateGitHubWebhook({
+  eventName,
+  deliveryId,
+  payload,
+}) {
+  if (eventName === 'ping') {
+    return { kind: 'ping' };
+  }
+
+  if (eventName !== 'issues') {
+    return { kind: 'ignored', reason: 'unsupported_event' };
+  }
+
+  const action = String(payload.action ?? '');
+  if (!['opened', 'reopened', 'edited', 'closed'].includes(action)) {
+    return { kind: 'ignored', reason: 'unsupported_action' };
+  }
+
+  const issue = payload.issue;
+  const repository = payload.repository;
+  if (!issue || !repository?.full_name || !deliveryId) {
+    throw new Error('Invalid GitHub issues webhook payload');
+  }
+
+  return {
+    kind: 'event',
+    event: {
+      eventId: deliveryId,
+      name: `github.issue.${action}`,
+      timestamp:
+        issue.updated_at ??
+        issue.created_at ??
+        new Date().toISOString(),
+      data: {
+        repository: repository.full_name,
+        number: issue.number,
+        title: issue.title ?? '',
+        bodyPreview:
+          typeof issue.body === 'string'
+            ? issue.body.slice(0, 1000)
+            : '',
+        labels: Array.isArray(issue.labels)
+          ? issue.labels
+              .map((label) =>
+                typeof label === 'string' ? label : label?.name,
+              )
+              .filter(Boolean)
+          : [],
+        sender: payload.sender?.login ?? null,
+        action,
+        url: issue.html_url ?? null,
+      },
+      cursor: null,
+    },
+  };
+}
+
+export function githubEventPassesStructuredFilter(
+  event,
+  { repository, label } = {},
+) {
+  if (repository && event.data.repository !== repository) return false;
+  if (
+    label &&
+    (!Array.isArray(event.data.labels) ||
+      !event.data.labels.includes(label))
+  ) {
+    return false;
+  }
+  return true;
+}

package/scripts/lib/http-wake-deliverer.mjs

@@ -0,0 +1,31 @@
+export function createHttpWakeDeliverer(url, fetchFn = fetch) {
+  if (!url) return null;
+
+  return async (envelope) => {
+    const response = await fetchFn(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(envelope),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Runtime wake callback failed with HTTP ${response.status}`);
+    }
+
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
+      // A 2xx response without JSON is still a valid acceptance.
+    }
+
+    return {
+      runtimeReceiptId:
+        typeof body.runtimeReceiptId === 'string'
+          ? body.runtimeReceiptId
+          : undefined,
+    };
+  };
+}

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

@@ -0,0 +1,193 @@
+import {
+  TypeSafeJevEvaluator,
+} from '../../dist/src/semantic/typesafeJevEvaluator.js';
+import {
+  CompositeTriggerEngine,
+} from '../../dist/src/composite/engine.js';
+import {
+  CompositeWakeCoordinator,
+} from './composite-wake-coordinator.mjs';
+import {
+  buildGenericRuntimeWakePacket,
+  createSignedRuntimeWakeDeliverer,
+  readRuntimeWakeTargets,
+} from './generic-runtime-wake.mjs';
+import {
+  CompositeEventConsumer,
+} from './composite-event-consumer.mjs';
+import {
+  DerivedEventCoordinator,
+} from './derived-event-coordinator.mjs';
+import {
+  TriggerControlPlane,
+} from './trigger-control-plane.mjs';
+import {
+  PersistentEventStore,
+} from './persistent-event-store.mjs';
+import {
+  TriggerInspector,
+} from './trigger-inspector.mjs';
+import {
+  TemporalDeadlineScheduler,
+} from './temporal-deadline-scheduler.mjs';
+import {
+  McpEventsClientManager,
+} from './mcp-events-client.mjs';
+
+export async function createLocalEventIntelligenceRuntime({
+  env = process.env,
+  mcpEventConnections = [],
+  wakeHandlers = {},
+  wake,
+  semanticEvaluator,
+} = {}) {
+  const dataDir = env.DATA_DIR ?? './data';
+  const store = new PersistentEventStore(dataDir);
+  const restored = await store.init();
+
+  const evaluator =
+    semanticEvaluator !== undefined
+      ? semanticEvaluator
+      : env.TYPESAFE_API_KEY
+        ? TypeSafeJevEvaluator.fromEnvironment(env)
+        : null;
+
+  const triggerEngine = new CompositeTriggerEngine(store, evaluator);
+
+  const wakeCoordinators = new Map();
+
+  const runtimeWakeTargets = readRuntimeWakeTargets(
+    env.RUNTIME_WAKE_TARGETS_JSON,
+  );
+  for (const [runtime, target] of runtimeWakeTargets) {
+    wakeCoordinators.set(
+      runtime,
+      new CompositeWakeCoordinator({
+        store,
+        triggerEngine,
+        deliverer: createSignedRuntimeWakeDeliverer(target),
+        packetBuilder: buildGenericRuntimeWakePacket,
+      }),
+    );
+  }
+
+  const hostWakeEntries =
+    wakeHandlers instanceof Map
+      ? [...wakeHandlers.entries()]
+      : Object.entries(wakeHandlers || {});
+
+  for (const [runtime, handler] of hostWakeEntries) {
+    if (typeof handler !== 'function') {
+      throw new Error(`Host wake handler for ${runtime} must be a function`);
+    }
+    wakeCoordinators.set(
+      runtime,
+      new CompositeWakeCoordinator({
+        store,
+        triggerEngine,
+        packetBuilder: buildGenericRuntimeWakePacket,
+        deliverer: async (packet) => {
+          const result = await handler(packet);
+          if (typeof result === 'string' && result) {
+            return { runtimeReceiptId: result };
+          }
+          if (
+            result &&
+            typeof result === 'object' &&
+            typeof result.runtimeReceiptId === 'string' &&
+            result.runtimeReceiptId
+          ) {
+            return result;
+          }
+          throw new Error(
+            `Host wake handler for ${runtime} must return runtimeReceiptId`,
+          );
+        },
+      }),
+    );
+  }
+
+  let wakeCoordinator = null;
+  if (wake !== undefined) {
+    if (typeof wake !== 'function') {
+      throw new Error('Host wake dispatcher must be a function');
+    }
+    wakeCoordinator = new CompositeWakeCoordinator({
+      store,
+      triggerEngine,
+      packetBuilder: buildGenericRuntimeWakePacket,
+      deliverer: async (packet) => {
+        const result = await wake(packet);
+        if (typeof result === 'string' && result) {
+          return { runtimeReceiptId: result };
+        }
+        if (
+          result &&
+          typeof result === 'object' &&
+          typeof result.runtimeReceiptId === 'string' &&
+          result.runtimeReceiptId
+        ) {
+          return result;
+        }
+        throw new Error('Host wake dispatcher must return runtimeReceiptId');
+      },
+    });
+  }
+
+  const derivedEventCoordinator = new DerivedEventCoordinator({ store });
+  const compositeEventConsumer = new CompositeEventConsumer({
+    store,
+    triggerEngine,
+    wakeCoordinator,
+    wakeCoordinators,
+    derivedEventCoordinator,
+    maxDerivedDepth: Number(env.MAX_DERIVED_EVENT_DEPTH ?? 16),
+  });
+
+  const temporalScheduler = new TemporalDeadlineScheduler({
+    store,
+    compositeEventConsumer,
+    intervalMs: Number(env.TEMPORAL_TICK_MS ?? 1000),
+  });
+  temporalScheduler.start();
+
+  const triggerControl = new TriggerControlPlane({
+    store,
+    triggerEngine,
+  });
+  const triggerInspector = new TriggerInspector({ store });
+
+  const mcpEventsClient = new McpEventsClientManager({
+    store,
+    compositeEventConsumer,
+    connections: mcpEventConnections,
+    registerEventSource: (source) =>
+      triggerControl.registerEventSource(
+        source,
+        {
+          type: 'system',
+          principal_id: 'event-intelligence:host-mcp-client',
+        },
+      ),
+  });
+
+  const discovery = await mcpEventsClient.discoverAll();
+  mcpEventsClient.start();
+
+  return {
+    restored,
+    store,
+    evaluator,
+    triggerEngine,
+    triggerControl,
+    triggerInspector,
+    compositeEventConsumer,
+    temporalScheduler,
+    mcpEventsClient,
+    discovery,
+    async close() {
+      temporalScheduler.stop();
+      mcpEventsClient.stop();
+    },
+  };
+}