mcp-event-intelligence 0.2.1 → 0.3.1

package/dist/src/intelligenceProtocol/triggerSchemas.d.ts

@@ -21,6 +21,22 @@ export declare const StructuredPredicateSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     path: z.ZodString;
     op: z.ZodLiteral<"exists">;
     value: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    op: z.ZodLiteral<"gt">;
+    value: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    op: z.ZodLiteral<"gte">;
+    value: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    op: z.ZodLiteral<"lt">;
+    value: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    op: z.ZodLiteral<"lte">;
+    value: z.ZodNumber;
 }, z.core.$strip>], "op">;
 export declare const TriggerClauseSchema: z.ZodObject<{
     id: z.ZodString;
@@ -47,6 +63,22 @@ export declare const TriggerClauseSchema: z.ZodObject<{
         path: z.ZodString;
         op: z.ZodLiteral<"exists">;
         value: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        path: z.ZodString;
+        op: z.ZodLiteral<"gt">;
+        value: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        path: z.ZodString;
+        op: z.ZodLiteral<"gte">;
+        value: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        path: z.ZodString;
+        op: z.ZodLiteral<"lt">;
+        value: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        path: z.ZodString;
+        op: z.ZodLiteral<"lte">;
+        value: z.ZodNumber;
     }, z.core.$strip>], "op">>>;
 }, z.core.$strip>;
 export declare const CalendarTemporalConditionSchema: z.ZodObject<{
@@ -169,6 +201,25 @@ export declare const TriggerLifecyclePolicySchema: z.ZodObject<{
     leaseUntil: z.ZodOptional<z.ZodString>;
     completeOnGoal: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+export declare const ContinuationContextPolicySchema: z.ZodObject<{
+    evidence: z.ZodDefault<z.ZodEnum<{
+        matched_events: "matched_events";
+        refs_only: "refs_only";
+    }>>;
+    maxEvents: z.ZodDefault<z.ZodNumber>;
+    includeData: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const ContinuationContractSchema: z.ZodObject<{
+    instruction: z.ZodString;
+    contextPolicy: z.ZodDefault<z.ZodObject<{
+        evidence: z.ZodDefault<z.ZodEnum<{
+            matched_events: "matched_events";
+            refs_only: "refs_only";
+        }>>;
+        maxEvents: z.ZodDefault<z.ZodNumber>;
+        includeData: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const DeterministicCorrelationSchema: z.ZodObject<{
     kind: z.ZodLiteral<"same_value">;
     fields: z.ZodArray<z.ZodObject<{
@@ -193,6 +244,17 @@ export declare const CompositeTriggerDefinitionSchema: z.ZodObject<{
     triggerId: z.ZodString;
     version: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    continuation: z.ZodOptional<z.ZodObject<{
+        instruction: z.ZodString;
+        contextPolicy: z.ZodDefault<z.ZodObject<{
+            evidence: z.ZodDefault<z.ZodEnum<{
+                matched_events: "matched_events";
+                refs_only: "refs_only";
+            }>>;
+            maxEvents: z.ZodDefault<z.ZodNumber>;
+            includeData: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     clauses: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         event: z.ZodString;
@@ -218,6 +280,22 @@ export declare const CompositeTriggerDefinitionSchema: z.ZodObject<{
             path: z.ZodString;
             op: z.ZodLiteral<"exists">;
             value: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            path: z.ZodString;
+            op: z.ZodLiteral<"gt">;
+            value: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            path: z.ZodString;
+            op: z.ZodLiteral<"gte">;
+            value: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            path: z.ZodString;
+            op: z.ZodLiteral<"lt">;
+            value: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            path: z.ZodString;
+            op: z.ZodLiteral<"lte">;
+            value: z.ZodNumber;
         }, z.core.$strip>], "op">>>;
     }, z.core.$strip>>;
     expression: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -475,6 +553,8 @@ export type StructuredPredicate = z.infer<typeof StructuredPredicateSchema>;
 export type TriggerClause = z.infer<typeof TriggerClauseSchema>;
 export type TemporalCondition = z.infer<typeof TemporalConditionSchema>;
 export type TriggerLifecyclePolicy = z.infer<typeof TriggerLifecyclePolicySchema>;
+export type ContinuationContextPolicy = z.infer<typeof ContinuationContextPolicySchema>;
+export type ContinuationContract = z.infer<typeof ContinuationContractSchema>;
 export type DerivedEventDefinition = z.infer<typeof DerivedEventDefinitionSchema>;
 export type DerivedEventRecord = z.infer<typeof DerivedEventRecordSchema>;
 export type CompositeTriggerDefinition = z.infer<typeof CompositeTriggerDefinitionSchema>;

package/dist/src/intelligenceProtocol/triggerSchemas.js

@@ -13,6 +13,10 @@ export const StructuredPredicateSchema = z.discriminatedUnion('op', [
     z.object({ path: z.string().min(1), op: z.literal('contains'), value: Scalar }),
     z.object({ path: z.string().min(1), op: z.literal('in'), value: z.array(Scalar).min(1) }),
     z.object({ path: z.string().min(1), op: z.literal('exists'), value: z.boolean().default(true) }),
+    z.object({ path: z.string().min(1), op: z.literal('gt'), value: z.number() }),
+    z.object({ path: z.string().min(1), op: z.literal('gte'), value: z.number() }),
+    z.object({ path: z.string().min(1), op: z.literal('lt'), value: z.number() }),
+    z.object({ path: z.string().min(1), op: z.literal('lte'), value: z.number() }),
 ]);
 export const TriggerClauseSchema = z.object({
     id: Id,
@@ -142,6 +146,19 @@ export const TriggerLifecyclePolicySchema = z.object({
         });
     }
 });
+export const ContinuationContextPolicySchema = z.object({
+    evidence: z.enum(['matched_events', 'refs_only']).default('matched_events'),
+    maxEvents: z.number().int().min(1).max(50).default(50),
+    includeData: z.boolean().default(true),
+}).strict();
+export const ContinuationContractSchema = z.object({
+    instruction: z.string().min(1).max(4000),
+    contextPolicy: ContinuationContextPolicySchema.default({
+        evidence: 'matched_events',
+        maxEvents: 50,
+        includeData: true,
+    }),
+}).strict();
 export const DeterministicCorrelationSchema = z.object({
     kind: z.literal('same_value'),
     fields: z.array(z.object({
@@ -164,6 +181,7 @@ export const CompositeTriggerDefinitionSchema = z.object({
     triggerId: Id,
     version: z.string().min(1),
     description: z.string().max(500).optional(),
+    continuation: ContinuationContractSchema.optional(),
     clauses: z.array(TriggerClauseSchema).min(1),
     expression: TriggerExpressionSchema,
     temporal: z.array(TemporalConditionSchema).default([]),
@@ -186,6 +204,12 @@ export const CompositeTriggerDefinitionSchema = z.object({
             message: 'Trigger requires target, derivedEvent, or both',
         });
     }
+    if (value.continuation && !value.target) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Trigger continuation requires a runtime target',
+        });
+    }
     const ids = new Set(value.clauses.map((clause) => clause.id));
     if (ids.size !== value.clauses.length) {
         ctx.addIssue({ code: 'custom', message: 'Trigger clause ids must be unique' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Durable temporal event intelligence for agent hosts: host-owned MCP event discovery, composite triggers, derived events, and targeted wakeups.",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/host-integration.d.mts

@@ -1,3 +1,8 @@
+import type {
+  ActivationEnvelope,
+  TriggerPlanInput,
+} from '../dist/src/intelligenceProtocol/index.js';
+
 export interface HostMcpClientLike {
   request(
     request: { method: string; params?: unknown },
@@ -38,6 +43,7 @@ export interface HostWakeReceipt {
 
 export type HostWakeHandler = (
   packet: Record<string, unknown>,
+  activation?: ActivationEnvelope,
 ) => Promise<HostWakeReceipt | string> | HostWakeReceipt | string;
 
 export interface EventIntelligenceStore {
@@ -69,7 +75,18 @@ export interface EventIntelligenceScopedHost {
   readonly store: EventIntelligenceStore;
   readonly triggerControl: any;
   readonly triggerInspector: any;
+  readonly triggerPlanner: any;
+  readonly activationHydrator: any;
   readonly eventSources: any[];
+  planTrigger(input: TriggerPlanInput): Promise<{
+    planVersion: '1';
+    definition: any;
+    connectionIds: string[];
+    resolvedSources: any[];
+    warnings: any[];
+    explanation: any;
+  }>;
+  hydrateWake(wakeId: string): ActivationEnvelope;
   attachMcpClient(connection: HostMcpConnectionOptions): Promise<{
     connectionId: string;
     events: any[];

package/scripts/host-integration.mjs

@@ -74,6 +74,14 @@ function scopedHostView(runtime, context) {
     store: context.store,
     triggerControl: context.triggerControl,
     triggerInspector: context.triggerInspector,
+    triggerPlanner: context.triggerPlanner,
+    activationHydrator: context.activationHydrator,
+    planTrigger(input) {
+      return context.triggerPlanner.plan(input);
+    },
+    hydrateWake(wakeId) {
+      return context.activationHydrator.hydrateWake(wakeId);
+    },
     get eventSources() {
       return context.triggerControl.listEventSources();
     },
@@ -223,6 +231,18 @@ export async function createEventIntelligenceHost({
     get triggerInspector() {
       return runtime.triggerInspector;
     },
+    get triggerPlanner() {
+      return runtime.triggerPlanner;
+    },
+    get activationHydrator() {
+      return runtime.activationHydrator;
+    },
+    planTrigger(input) {
+      return runtime.triggerPlanner.plan(input);
+    },
+    hydrateWake(wakeId) {
+      return runtime.activationHydrator.hydrateWake(wakeId);
+    },
     get eventSources() {
       return runtime.triggerControl.listEventSources();
     },

package/scripts/lib/activation-hydrator.mjs

@@ -0,0 +1,140 @@
+import {
+  parseActivationEnvelope,
+} from '../../dist/src/intelligenceProtocol/index.js';
+
+function latestMatchForWake(store, wake, delivery) {
+  const matchId =
+    delivery?.matchId ||
+    (wake?.subscriptionId?.startsWith('trigger:') ? wake.sourceEventId : null);
+  if (!matchId) return null;
+
+  return store.listTriggerMatches()
+    .find((candidate) => candidate.matchId === matchId) ?? null;
+}
+
+function definitionForMatch(store, match, delivery) {
+  if (!match && !delivery) return null;
+  const triggerId = match?.triggerId ?? delivery?.triggerId;
+  const triggerVersion = match?.triggerVersion ?? delivery?.triggerVersion;
+  return store.listTriggers().find((candidate) =>
+    candidate.triggerId === triggerId &&
+    candidate.version === triggerVersion
+  ) ?? null;
+}
+
+function continuationFor(definition) {
+  if (definition?.continuation) return definition.continuation;
+
+  const fallback = String(definition?.description || '').trim();
+  if (!fallback) return null;
+  return {
+    instruction: fallback,
+    contextPolicy: {
+      evidence: 'refs_only',
+      maxEvents: 50,
+      includeData: false,
+    },
+  };
+}
+
+export class ActivationHydrator {
+  constructor({ store }) {
+    this.store = store;
+  }
+
+  hydrateWake(wakeIdInput) {
+    const wakeId = String(wakeIdInput || '').trim();
+    if (!wakeId) {
+      const error = new Error('wakeId is required');
+      error.code = 'ACTIVATION_WAKE_ID_REQUIRED';
+      throw error;
+    }
+
+    const wake = this.store.latestWake(wakeId);
+    if (!wake) {
+      const error = new Error(`Unknown wake: ${wakeId}`);
+      error.code = 'ACTIVATION_WAKE_NOT_FOUND';
+      throw error;
+    }
+
+    const delivery =
+      typeof this.store.getWakeDelivery === 'function'
+        ? this.store.getWakeDelivery(wakeId)
+        : null;
+    const match = latestMatchForWake(this.store, wake, delivery);
+    if (!match) {
+      const error = new Error(
+        `Wake ${wakeId} is not backed by a composite trigger match`,
+      );
+      error.code = 'ACTIVATION_TRIGGER_MATCH_NOT_FOUND';
+      throw error;
+    }
+
+    const definition = definitionForMatch(this.store, match, delivery);
+    if (!definition?.target) {
+      const error = new Error(
+        `Trigger definition missing for wake ${wakeId}`,
+      );
+      error.code = 'ACTIVATION_TRIGGER_NOT_FOUND';
+      throw error;
+    }
+
+    const continuation = continuationFor(definition);
+    const policy = continuation?.contextPolicy ?? {
+      evidence: 'refs_only',
+      maxEvents: 50,
+      includeData: false,
+    };
+    const includeData =
+      policy.evidence === 'matched_events' &&
+      policy.includeData !== false;
+    const maxEvents = Math.max(
+      1,
+      Math.min(50, Number(policy.maxEvents) || 50),
+    );
+
+    const evidence = match.sourceEvents.slice(-maxEvents).map((event) => ({
+      clauseId: event.clauseId,
+      serverId: event.serverId ?? null,
+      eventId: event.sourceEventId,
+      eventName: event.eventName,
+      traceId: event.traceId,
+      occurredAt: event.occurredAt,
+      payloadHash: event.payloadHash ?? null,
+      ...(includeData ? { data: event.data } : {}),
+    }));
+
+    return parseActivationEnvelope({
+      activationVersion: '1',
+      wake: {
+        wakeId,
+        status: wake.status,
+        runtimeReceiptId: wake.runtimeReceiptId ?? null,
+        matchedAt: match.updatedAt,
+      },
+      target: definition.target,
+      trigger: {
+        triggerId: definition.triggerId,
+        version: definition.version,
+        description: definition.description ?? null,
+        expression: definition.expression,
+        lifecycle: definition.lifecycle ?? {},
+      },
+      continuation,
+      match: {
+        matchId: match.matchId,
+        status: match.status,
+        correlationKey: match.correlationKey,
+        openedAt: match.openedAt,
+        updatedAt: match.updatedAt,
+      },
+      evidence,
+      trust: {
+        continuation: 'configured_trigger_instruction',
+        evidence: 'untrusted_external_signal',
+      },
+    });
+  }
+}
+
+export default { ActivationHydrator };

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

@@ -38,6 +38,12 @@ import {
 import {
   WakeRetryScheduler,
 } from './wake-retry-scheduler.mjs';
+import {
+  TriggerPlanner,
+} from './trigger-planner.mjs';
+import {
+  ActivationHydrator,
+} from './activation-hydrator.mjs';
 
 const REQUIRED_STORE_METHODS = [
   'putTrigger',
@@ -155,6 +161,8 @@ export async function createLocalEventIntelligenceRuntime({
     }
 
     const triggerEngine = new CompositeTriggerEngine(store, evaluator);
+    const triggerPlanner = new TriggerPlanner({ store });
+    const activationHydrator = new ActivationHydrator({ store });
     const wakeCoordinators = new Map();
     const packetBuilder = scopedPacketBuilder(scopeId);
     const deliveryOptions = {
@@ -186,7 +194,8 @@ export async function createLocalEventIntelligenceRuntime({
           packetBuilder,
           ...deliveryOptions,
           deliverer: async (packet) => {
-            const result = await handler(packet);
+            const activation = activationHydrator.hydrateWake(packet.wake_id);
+            const result = await handler(packet, activation);
             if (typeof result === 'string' && result) {
               return { runtimeReceiptId: result };
             }
@@ -214,7 +223,8 @@ export async function createLocalEventIntelligenceRuntime({
         packetBuilder,
         ...deliveryOptions,
         deliverer: async (packet) => {
-          const result = await wake(packet);
+          const activation = activationHydrator.hydrateWake(packet.wake_id);
+          const result = await wake(packet, activation);
           if (typeof result === 'string' && result) {
             return { runtimeReceiptId: result };
           }
@@ -270,6 +280,8 @@ export async function createLocalEventIntelligenceRuntime({
       triggerEngine,
       triggerControl,
       triggerInspector,
+      triggerPlanner,
+      activationHydrator,
       compositeEventConsumer,
       temporalScheduler,
       wakeRetryScheduler,
@@ -322,6 +334,8 @@ export async function createLocalEventIntelligenceRuntime({
     triggerEngine: defaultContext.triggerEngine,
     triggerControl: defaultContext.triggerControl,
     triggerInspector: defaultContext.triggerInspector,
+    triggerPlanner: defaultContext.triggerPlanner,
+    activationHydrator: defaultContext.activationHydrator,
     compositeEventConsumer: defaultContext.compositeEventConsumer,
     temporalScheduler: defaultContext.temporalScheduler,
     mcpEventsClient,

package/scripts/lib/trigger-inspector.mjs

@@ -307,6 +307,7 @@ export class TriggerInspector {
         triggerId: definition.triggerId,
         version: definition.version,
         description: definition.description ?? null,
+        continuation: definition.continuation ?? null,
         target: definition.target ?? null,
         derivedEvent: definition.derivedEvent ?? null,
         expression: definition.expression,