mcp-event-intelligence 0.8.1 → 0.9.0

package/scripts/embedded-host-kit.mjs

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import {
   RuntimeTargetSchema,
@@ -242,6 +243,24 @@ export function createResultReference(reference) {
   };
 }
 
+async function projectPortableFailure(projectError, input, canonical) {
+  if (typeof projectError !== 'function') return canonical;
+  try {
+    const projected = await projectError({
+      ...input,
+      error: canonical.error,
+      result: canonical,
+    });
+    if (projected == null) return canonical;
+    if (typeof projected !== 'object' || projected.ok !== false) {
+      throw new Error('projectError() must return a PortableToolResult with ok:false');
+    }
+    return projected;
+  } catch {
+    return canonical;
+  }
+}
+
 async function projectPortableResult(projectResult, input) {
   if (typeof projectResult !== 'function') {
     return { ok: true, data: input.value };
@@ -301,11 +320,33 @@ function wakeIdFromPacket(packet) {
   return typeof value === 'string' && value.trim() ? value : null;
 }
 
+export function createDeterministicReceiptId(
+  namespace,
+  wakeId,
+  { length = 32 } = {},
+) {
+  const normalizedNamespace = String(namespace ?? '').trim();
+  const normalizedWakeId = String(wakeId ?? '').trim();
+  if (!normalizedNamespace) {
+    throw new Error('receipt namespace is required');
+  }
+  if (!normalizedWakeId) {
+    throw new Error('wake id is required');
+  }
+  if (!Number.isInteger(length) || length < 8 || length > 64) {
+    throw new Error('receipt id length must be an integer between 8 and 64');
+  }
+  return createHash('sha256')
+    .update(JSON.stringify([normalizedNamespace, normalizedWakeId]))
+    .digest('hex')
+    .slice(0, length);
+}
+
 /**
  * Runtime-neutral registry over host-owned event connections.
  *
- * The host keeps credentials, transport and lifecycle ownership. EI only asks
- * for the currently available connections and listens for topology changes.
+ * Static iterables are accepted directly by createEmbeddedRuntimeIntegration();
+ * use this explicit factory when the host has dynamic discovery/subscription.
  */
 export function createEventSourceRegistry({
   list,
@@ -328,6 +369,83 @@ export function createEventSourceRegistry({
  * Neutral catalog for host tool exposure. It does not decide policy or adapt
  * descriptors to any vendor SDK; the embedding runtime owns both.
  */
+export function summarizeEventSourceStatus(
+  statuses = [],
+  refreshOutcomes = [],
+) {
+  const rows = Array.isArray(statuses) ? statuses : [];
+  const refresh = Array.isArray(refreshOutcomes) ? refreshOutcomes : [];
+  const connectionIds = new Set();
+  const errorIds = new Set();
+  let anonymousErrors = 0;
+  let eventsCapable = 0;
+  let eventDefinitions = 0;
+
+  for (const outcome of refresh) {
+    if (!outcome || typeof outcome !== 'object') continue;
+    const id = String(outcome.connectionId ?? '').trim();
+    if (outcome.status !== 'detached' && id) connectionIds.add(id);
+    if (outcome.status === 'error' || outcome.error != null) {
+      if (id) errorIds.add(id);
+      else anonymousErrors += 1;
+    }
+  }
+
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue;
+    const id = String(row.connectionId ?? row.id ?? '').trim();
+    if (id) connectionIds.add(id);
+    if (row.error != null) {
+      if (id) errorIds.add(id);
+      else anonymousErrors += 1;
+      continue;
+    }
+    if (Array.isArray(row.events) && row.events.length > 0) {
+      eventsCapable += 1;
+      eventDefinitions += row.events.length;
+    }
+  }
+
+  return Object.freeze({
+    connections: connectionIds.size || rows.length,
+    eventsCapable,
+    eventDefinitions,
+    errors: errorIds.size + anonymousErrors,
+    statuses: rows,
+    refreshOutcomes: refresh,
+  });
+}
+
+export function bindEmbeddedRuntimeIntegration(
+  integration,
+  { adapt, register, onClose } = {},
+) {
+  if (!integration || typeof integration !== 'object') {
+    throw new Error('embedded integration is required');
+  }
+  if (typeof adapt !== 'function') {
+    throw new Error('bind adapt() is required');
+  }
+  if (typeof register !== 'function') {
+    throw new Error('bind register() is required');
+  }
+  if (onClose !== undefined && typeof onClose !== 'function') {
+    throw new Error('bind onClose must be a function');
+  }
+
+  const adapted = integration.tools.map((portableTool) => {
+    const hostTool = adapt(portableTool);
+    register(hostTool, portableTool);
+    return hostTool;
+  });
+
+  if (onClose) {
+    onClose(() => integration.close());
+  }
+
+  return Object.freeze(adapted);
+}
+
 export function createPortableToolCatalog(tools = []) {
   const all = Object.freeze([...tools]);
   const byName = new Map(all.map((tool) => [tool.name, tool]));
@@ -367,6 +485,7 @@ export function createActivationDispatcher({
   resolveTarget,
   hasReceipt,
   receiptId,
+  receiptNamespace,
   deliver,
 } = {}) {
   if (resolveTarget !== undefined && typeof resolveTarget !== 'function') {
@@ -378,6 +497,15 @@ export function createActivationDispatcher({
   if (receiptId !== undefined && typeof receiptId !== 'function') {
     throw new Error('receiptId must be a function');
   }
+  if (
+    receiptNamespace !== undefined &&
+    (typeof receiptNamespace !== 'string' || !receiptNamespace.trim())
+  ) {
+    throw new Error('receiptNamespace must be a non-empty string');
+  }
+  if (receiptId !== undefined && receiptNamespace !== undefined) {
+    throw new Error('Provide receiptId or receiptNamespace, not both');
+  }
   if (typeof deliver !== 'function') {
     throw new Error('Activation dispatcher requires deliver()');
   }
@@ -394,9 +522,16 @@ export function createActivationDispatcher({
     }
 
     const candidateReceiptId = String(
-      await (receiptId
-        ? receiptId({ packet, activation })
-        : activation.wake.wakeId),
+      await (
+        receiptId
+          ? receiptId({ packet, activation })
+          : receiptNamespace
+            ? createDeterministicReceiptId(
+                receiptNamespace,
+                activation.wake.wakeId,
+              )
+            : activation.wake.wakeId
+      ),
     ).trim();
     if (!candidateReceiptId) {
       const error = new Error('Activation receipt id must be non-empty');
@@ -518,6 +653,7 @@ export function createEventIntelligenceAgentTools({
   resolveContext,
   control,
   projectResult,
+  projectError,
   authorize,
   names = {},
 } = {}) {
@@ -541,6 +677,9 @@ export function createEventIntelligenceAgentTools({
   if (projectResult !== undefined && typeof projectResult !== 'function') {
     throw new Error('Agent tools projectResult must be a function');
   }
+  if (projectError !== undefined && typeof projectError !== 'function') {
+    throw new Error('Agent tools projectError must be a function');
+  }
 
   const toolNames = {
     ...DEFAULT_TOOL_NAMES,
@@ -582,7 +721,13 @@ export function createEventIntelligenceAgentTools({
             value,
           });
         } catch (error) {
-          return fail(error, 'EVENT_SOURCES_LIST_FAILED');
+          const canonical = fail(error, 'EVENT_SOURCES_LIST_FAILED');
+          return projectPortableFailure(projectError, {
+            capability: sourcesCapability,
+            runtimeContext,
+            context: undefined,
+            phase: 'event.sources.list',
+          }, canonical);
         }
       },
     },
@@ -596,7 +741,7 @@ export function createEventIntelligenceAgentTools({
         const parsed = TriggerCreateInput.safeParse(args ?? {});
         if (!parsed.success) {
           const issue = parsed.error.issues[0];
-          return {
+          const canonical = {
             ok: false,
             error: {
               code: 'EVENT_TRIGGER_INPUT_INVALID',
@@ -604,6 +749,12 @@ export function createEventIntelligenceAgentTools({
                 `${issue?.path?.join('.') || 'input'} — ${issue?.message || 'invalid'}`,
             },
           };
+          return projectPortableFailure(projectError, {
+            capability: createCapability,
+            runtimeContext,
+            context: undefined,
+            phase: 'trigger.input',
+          }, canonical);
         }
 
         let resolved;
@@ -624,7 +775,13 @@ export function createEventIntelligenceAgentTools({
             buildPlanInput(parsed.data, target),
           );
         } catch (error) {
-          return fail(error, 'EVENT_TRIGGER_PLAN_FAILED');
+          const canonical = fail(error, 'EVENT_TRIGGER_PLAN_FAILED');
+          return projectPortableFailure(projectError, {
+            capability: createCapability,
+            runtimeContext,
+            context: resolved,
+            phase: 'trigger.plan',
+          }, canonical);
         }
 
         // Host control is intentionally outside EI's error-normalization
@@ -656,7 +813,13 @@ export function createEventIntelligenceAgentTools({
               }),
             );
           } catch (error) {
-            return fail(error, 'EVENT_TRIGGER_CREATE_FAILED');
+            const canonical = fail(error, 'EVENT_TRIGGER_CREATE_FAILED');
+            return projectPortableFailure(projectError, {
+              capability: createCapability,
+              runtimeContext,
+              context: resolved,
+              phase: 'trigger.control',
+            }, canonical);
           }
         }
         const decision = normalizeHostControlDecision(rawDecision);
@@ -700,7 +863,13 @@ export function createEventIntelligenceAgentTools({
             warnings: plan.warnings ?? [],
           };
         } catch (error) {
-          return fail(error, 'EVENT_TRIGGER_CREATE_FAILED');
+          const canonical = fail(error, 'EVENT_TRIGGER_CREATE_FAILED');
+          return projectPortableFailure(projectError, {
+            capability: createCapability,
+            runtimeContext,
+            context: resolved,
+            phase: 'trigger.create',
+          }, canonical);
         }
 
         // Trigger creation is already durable at this point. Projection is a
@@ -734,6 +903,7 @@ export async function createEmbeddedEventIntelligence({
   mcp,
   mcpClients = [],
   semanticEvaluator,
+  observability,
   activation,
   wake,
   wakeHandlers = {},
@@ -763,6 +933,7 @@ export async function createEmbeddedEventIntelligence({
     mcpRegistry: registry,
     mcpClients,
     semanticEvaluator,
+    observability,
     ...(wakeHandler ? { wake: wakeHandler } : {}),
     wakeHandlers,
   });
@@ -814,6 +985,7 @@ export async function createEmbeddedRuntimeIntegration({
   eventSources,
   mcpClients = [],
   semanticEvaluator,
+  observability,
   activation,
   wake,
   wakeHandlers = {},
@@ -837,9 +1009,24 @@ export async function createEmbeddedRuntimeIntegration({
   ) {
     throw new Error('tooling.projectResult must be a function');
   }
+  if (
+    tooling?.projectError !== undefined &&
+    typeof tooling.projectError !== 'function'
+  ) {
+    throw new Error('tooling.projectError must be a function');
+  }
 
   const sourceRegistry = eventSources
-    ? createEventSourceRegistry(eventSources)
+    ? (
+        typeof eventSources?.list === 'function'
+          ? createEventSourceRegistry(eventSources)
+          : (() => {
+              const staticSources = Object.freeze([...eventSources]);
+              return createEventSourceRegistry({
+                list: () => staticSources,
+              });
+            })()
+      )
     : null;
 
   const embedded = await createEmbeddedEventIntelligence({
@@ -858,6 +1045,7 @@ export async function createEmbeddedRuntimeIntegration({
       : {}),
     mcpClients,
     semanticEvaluator,
+    observability,
     activation,
     wake,
     wakeHandlers,
@@ -872,6 +1060,9 @@ export async function createEmbeddedRuntimeIntegration({
         ...(tooling.projectResult
           ? { projectResult: tooling.projectResult }
           : {}),
+        ...(tooling.projectError
+          ? { projectError: tooling.projectError }
+          : {}),
         names: tooling.names ?? {},
       })
     : [];
@@ -883,6 +1074,22 @@ export async function createEmbeddedRuntimeIntegration({
     toolCatalog,
     capabilities: Object.freeze(toolCatalog.capabilities()),
     eventSources: sourceRegistry,
+    async diagnostics() {
+      const refreshOutcomes = sourceRegistry ? await embedded.refresh() : [];
+      return summarizeEventSourceStatus(
+        await embedded.status(),
+        refreshOutcomes,
+      );
+    },
+    bind(options) {
+      return bindEmbeddedRuntimeIntegration(
+        {
+          ...embedded,
+          tools: toolCatalog.all,
+        },
+        options,
+      );
+    },
   });
 }
 

package/scripts/host-conformance.d.mts

@@ -0,0 +1,75 @@
+import type {
+  EventIntelligenceObservabilityEvent,
+} from './lib/observability.d.mts';
+
+export interface HostConformanceTriggerInput {
+  triggerId: string;
+  threshold: number;
+  oneShot: boolean;
+  maxFirings?: number;
+}
+
+export interface HostConformanceEventInput {
+  eventId: string;
+  value: number;
+  secretProbe?: string;
+}
+
+export interface HostConformanceDelivery {
+  triggerId: string;
+  wakeId?: string;
+  runtimeReceiptId?: string;
+  [key: string]: unknown;
+}
+
+export interface HostConformanceHarness {
+  createTrigger(input: HostConformanceTriggerInput): Promise<void>;
+  emitEvent(input: HostConformanceEventInput): Promise<void>;
+  deliveries(): Promise<readonly HostConformanceDelivery[]> | readonly HostConformanceDelivery[];
+  restart(): Promise<void>;
+  inspectTrigger(triggerId: string): Promise<{
+    status?: string;
+    fireCount?: number;
+    [key: string]: unknown;
+  } | null>;
+  close(): Promise<void>;
+}
+
+export interface HostConformanceAdapter {
+  name?: string;
+  createHarness(input: {
+    observability(event: EventIntelligenceObservabilityEvent): void;
+  }): Promise<HostConformanceHarness> | HostConformanceHarness;
+}
+
+export interface HostConformanceResult {
+  id: string;
+  status: 'pass' | 'fail';
+  durationMs: number;
+  detail?: unknown;
+  error?: string;
+}
+
+export interface HostConformanceReport {
+  schema: 'event-intelligence.host-conformance.v1' | string;
+  adapter: string;
+  passed: boolean;
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+  };
+  results: readonly HostConformanceResult[];
+  observability: {
+    captured: number;
+    eventNames: readonly string[];
+  };
+}
+
+export const HOST_CONFORMANCE_REPORT_SCHEMA:
+  'event-intelligence.host-conformance.v1';
+
+export function runHostConformance(
+  adapter: HostConformanceAdapter,
+  options?: { throwOnFailure?: boolean },
+): Promise<HostConformanceReport>;

package/scripts/host-conformance.mjs

@@ -0,0 +1,238 @@
+const REPORT_SCHEMA = 'event-intelligence.host-conformance.v1';
+
+function assertFunction(value, name) {
+  if (typeof value !== 'function') {
+    throw new Error(`Host conformance adapter requires ${name}()`);
+  }
+}
+
+function validateHarness(harness) {
+  if (!harness || typeof harness !== 'object') {
+    throw new Error('createHarness() must return a harness object');
+  }
+  for (const method of [
+    'createTrigger',
+    'emitEvent',
+    'deliveries',
+    'restart',
+    'inspectTrigger',
+    'close',
+  ]) {
+    assertFunction(harness[method], method);
+  }
+  return harness;
+}
+
+function deliveryCount(rows, triggerId) {
+  return rows.filter((row) => row?.triggerId === triggerId).length;
+}
+
+async function runCase(id, execute) {
+  const startedAt = Date.now();
+  try {
+    const detail = await execute();
+    return Object.freeze({
+      id,
+      status: 'pass',
+      durationMs: Date.now() - startedAt,
+      ...(detail ? { detail } : {}),
+    });
+  } catch (error) {
+    return Object.freeze({
+      id,
+      status: 'fail',
+      durationMs: Date.now() - startedAt,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function requireCondition(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+/**
+ * Run the runtime-neutral EI host contract against an isolated host harness.
+ *
+ * The adapter owns all runtime-specific translation. The kit only uses a
+ * canonical value-change source and inspects externally visible deliveries,
+ * persisted trigger state and structured observability events.
+ */
+export async function runHostConformance(
+  adapter,
+  { throwOnFailure = false } = {},
+) {
+  if (!adapter || typeof adapter !== 'object') {
+    throw new Error('Host conformance adapter is required');
+  }
+  assertFunction(adapter.createHarness, 'createHarness');
+
+  const observed = [];
+  const harness = validateHarness(await adapter.createHarness({
+    observability(event) {
+      observed.push(event);
+    },
+  }));
+
+  const results = [];
+  try {
+    results.push(await runCase('core.once-threshold', async () => {
+      await harness.createTrigger({
+        triggerId: 'conformance-once',
+        threshold: 1000,
+        oneShot: true,
+      });
+
+      await harness.emitEvent({
+        eventId: 'once-below',
+        value: 999,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-once') === 0,
+        'below-threshold event produced a delivery',
+      );
+
+      await harness.emitEvent({
+        eventId: 'once-match',
+        value: 1001,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-once') === 1,
+        'matching event did not produce exactly one delivery',
+      );
+
+    }));
+
+    results.push(await runCase('core.replay-dedup', async () => {
+      await harness.createTrigger({
+        triggerId: 'conformance-replay',
+        threshold: 1000,
+        oneShot: false,
+        maxFirings: 2,
+      });
+
+      await harness.emitEvent({
+        eventId: 'replay-same-id',
+        value: 1100,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      await harness.emitEvent({
+        eventId: 'replay-same-id',
+        value: 1100,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-replay') === 1,
+        'replayed event produced a duplicate delivery on a persistent trigger',
+      );
+      const state = await harness.inspectTrigger('conformance-replay');
+      requireCondition(
+        Number(state?.fireCount) === 1,
+        `replayed event advanced fireCount to ${state?.fireCount}`,
+      );
+    }));
+
+    results.push(await runCase('core.restart-durability', async () => {
+      await harness.createTrigger({
+        triggerId: 'conformance-restart',
+        threshold: 1000,
+        oneShot: false,
+        maxFirings: 2,
+      });
+      await harness.restart();
+
+      await harness.emitEvent({
+        eventId: 'restart-1',
+        value: 1200,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-restart') === 1,
+        'trigger did not survive runtime restart',
+      );
+    }));
+
+    results.push(await runCase('core.max-firings', async () => {
+      await harness.emitEvent({
+        eventId: 'restart-2',
+        value: 1300,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+      await harness.emitEvent({
+        eventId: 'restart-3',
+        value: 1400,
+        secretProbe: 'ei-conformance-secret-probe',
+      });
+
+      requireCondition(
+        deliveryCount(await harness.deliveries(), 'conformance-restart') === 2,
+        'maxFirings=2 did not cap external deliveries at two',
+      );
+
+      const state = await harness.inspectTrigger('conformance-restart');
+      requireCondition(Boolean(state), 'trigger state unavailable after firing');
+      requireCondition(
+        Number(state.fireCount) === 2,
+        `expected fireCount=2, got ${state.fireCount}`,
+      );
+    }));
+
+    results.push(await runCase('observability.required-events', async () => {
+      const names = new Set(observed.map((event) => event?.event));
+      for (const name of [
+        'ei.trigger.created',
+        'ei.match.matched',
+        'ei.wake.delivered',
+      ]) {
+        requireCondition(
+          names.has(name),
+          `missing required observability event ${name}`,
+        );
+      }
+
+      const serialized = JSON.stringify(observed);
+      requireCondition(
+        !serialized.includes('ei-conformance-secret-probe'),
+        'observability leaked event payload content',
+      );
+    }));
+  } finally {
+    await harness.close();
+  }
+
+  const failed = results.filter((result) => result.status === 'fail');
+  const report = Object.freeze({
+    schema: REPORT_SCHEMA,
+    adapter: String(adapter.name ?? 'unnamed-host'),
+    passed: failed.length === 0,
+    summary: Object.freeze({
+      total: results.length,
+      passed: results.length - failed.length,
+      failed: failed.length,
+    }),
+    results: Object.freeze(results),
+    observability: Object.freeze({
+      captured: observed.length,
+      eventNames: Object.freeze([...new Set(
+        observed.map((event) => event?.event).filter(Boolean),
+      )].sort()),
+    }),
+  });
+
+  if (throwOnFailure && !report.passed) {
+    const error = new Error(
+      `Event Intelligence host conformance failed: ${failed
+        .map((item) => item.id)
+        .join(', ')}`,
+    );
+    error.report = report;
+    throw error;
+  }
+
+  return report;
+}
+
+export const HOST_CONFORMANCE_REPORT_SCHEMA = REPORT_SCHEMA;

package/scripts/host-integration.d.mts

@@ -2,6 +2,9 @@ import type {
   ActivationEnvelope,
   TriggerPlanInput,
 } from '../dist/src/intelligenceProtocol/index.js';
+import type {
+  EventIntelligenceObservabilitySink,
+} from './lib/observability.d.mts';
 
 export interface HostMcpClientLike {
   request(
@@ -130,6 +133,8 @@ export interface EventIntelligenceHostOptions {
   /** Optional runtime-specific dispatchers. */
   wakeHandlers?: Map<string, HostWakeHandler> | Record<string, HostWakeHandler>;
   semanticEvaluator?: unknown;
+  /** Runtime-neutral structured operational events. Sink failures never affect EI semantics. */
+  observability?: EventIntelligenceObservabilitySink;
 }
 
 export interface EventIntelligenceScopedHost {