mcp-event-intelligence 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.7.1] - 2026-10-04
+
+### Fixed
+
+- serialize and coalesce concurrent host MCP registry refreshes so an embedded runtime cannot observe a half-attached Events connection while `events/list` is still in flight;
+- add a regression test for the subscribe + explicit-refresh race found while integrating Artemis.
+
+## [0.7.0] - 2026-10-04
+
+Embedded-host integration release.
+
+### Runtime-neutral embedded host kit
+
+- add `mcp-event-intelligence/embedded` as the high-level in-process integration surface;
+- add `createEmbeddedEventIntelligence()` to compose host-owned MCP connections, lifecycle, activation delivery and optional portable agent tools;
+- add `createActivationDispatcher()` for runtime-neutral target resolution, host-side receipt/idempotency checks and activation delivery;
+- add `createEventIntelligenceAgentTools()` with portable tool descriptors independent of OpenAI, Anthropic, MCP tool objects, Muffin, Artemis or any other runtime;
+- make continuation target `kind` host-defined rather than constrained to Event Intelligence's historical task vocabulary;
+- expose runtime-neutral `EventActivation`, `EventEvidence` and `ContinuationTarget` type aliases.
+
+### Host ownership boundaries
+
+- Event Intelligence remains embedded: it does not become a separate MCP server or own agent-runtime credentials;
+- MCP transports, OAuth/API credentials and connection lifecycle remain host-owned;
+- authorization, tenant policy and continuation semantics remain host-owned;
+- EI persists and evaluates future conditions, then returns the opaque continuation target and activation evidence to the host.
+
+### Packaging and verification
+
+- build `dist/` during git-based installs through `prepare`, so pinned GitHub revisions are usable by embedded hosts;
+- add generic host-kit tests with a third-party runtime-shaped target to guard against Muffin/Artemis coupling;
+- validate the packed npm surface including the new `./embedded` export.
+
 ## [0.6.1] - 2026-09-30
 
 Patch release for post-merge v0.6 review findings.
@@ -363,4 +396,4 @@ Initial public reference release.
 - JSONL persistence is single-writer and reference-grade;
 - no multi-replica / HA storage backend is included;
 - the v0.1 MCP control plane is stdio-only; a Streamable HTTP control-plane transport is not included;
-- Stateful Facts / current-state materialization is intentionally deferred.
+- Stateful Facts / current-state materialization is intentionally deferred.

package/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/mcp-event-intelligence.svg)](https://www.npmjs.com/package/mcp-event-intelligence)
-[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.6.1-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.7.1-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
 MCP Event Intelligence is an experimental event runtime for agents that need to react to **future conditions over multiple event sources** without keeping an LLM or agent loop alive.
@@ -31,6 +31,56 @@ npm install mcp-event-intelligence
 
 Published package: [npm](https://www.npmjs.com/package/mcp-event-intelligence) · [Official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
 
+For most runtimes, start with the runtime-neutral embedded host kit:
+
+```js
+import {
+  createEmbeddedEventIntelligence,
+} from 'mcp-event-intelligence/embedded';
+
+const ei = await createEmbeddedEventIntelligence({
+  dataDir: './data/event-intelligence',
+
+  // The host keeps ownership of MCP transports, auth and connection lifecycle.
+  mcp: {
+    listConnections: () => runtime.mcp.connections(),
+    subscribe: (refresh) => runtime.mcp.onConnectionsChanged(refresh),
+  },
+
+  // EI produces an activation; the host decides how its own work resumes.
+  activation: {
+    resolveTarget: (target) => runtime.resolveContinuation(target),
+    hasReceipt: (receiptId) => runtime.hasWakeReceipt(receiptId),
+    deliver: ({ activation, target, receiptId }) =>
+      runtime.resumeFromEvent({ activation, target, receiptId }),
+  },
+});
+```
+
+The continuation target is intentionally opaque to EI apart from
+`{ runtime, kind, id }`. A host may map it to a Turn, Execution, thread,
+graph checkpoint, workflow, Case, or any other durable continuation primitive.
+The package contains no `runtime === "muffin"` / `"artemis"` branches.
+
+Portable agent-facing trigger tools are optional:
+
+```js
+const tools = ei.createAgentTools({
+  resolveContext: (ctx) => ({
+    target: runtime.currentContinuation(ctx),
+    actor: runtime.currentActor(ctx),
+    owner: runtime.currentOwner(ctx),
+  }),
+  authorize: (request) => runtime.policy.authorize(request),
+});
+```
+
+Each tool is a neutral `{ name, description, inputSchema, execute }`
+descriptor. Adapt that descriptor to OpenAI, Anthropic, an internal capability
+graph, or any other host SDK without changing EI core.
+
+The lower-level host API remains available when a runtime needs direct control:
+
 Pass the harness-level MCP registry once — not every MCP one by one:
 
 ```js
@@ -275,7 +325,7 @@ timezone normalization and deterministic occurrence IDs. The local factory in
 this package should therefore be read as a typed convenience API, not as the
 production ERP connector itself.
 
-## What v0.6 implements
+## What v0.7 implements
 
 ### Host-owned event sources
 
@@ -558,4 +608,4 @@ Apache License 2.0. See [LICENSE](LICENSE).
 
 ## Disclaimer
 
-This is an independent open-source project. It is not an official Model Context Protocol specification and is not affiliated with or endorsed by the MCP maintainers.
+This is an independent open-source project. It is not an official Model Context Protocol specification and is not affiliated with or endorsed by the MCP maintainers.

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

@@ -100,3 +100,104 @@ export declare const ActivationEnvelopeSchema: z.ZodObject<{
 export type ActivationEvidence = z.infer<typeof ActivationEvidenceSchema>;
 export type ActivationEnvelope = z.infer<typeof ActivationEnvelopeSchema>;
 export declare function parseActivationEnvelope(value: unknown): ActivationEnvelope;
+/** Runtime-neutral public names for embedded-host integrations. */
+export declare const EventEvidenceSchema: z.ZodObject<{
+    clauseId: z.ZodString;
+    serverId: z.ZodNullable<z.ZodString>;
+    eventId: z.ZodString;
+    eventName: z.ZodString;
+    traceId: z.ZodString;
+    occurredAt: z.ZodString;
+    receivedAt: z.ZodOptional<z.ZodString>;
+    payloadHash: z.ZodNullable<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const EventActivationSchema: z.ZodObject<{
+    activationVersion: z.ZodLiteral<"2">;
+    wake: z.ZodObject<{
+        wakeId: z.ZodString;
+        status: z.ZodString;
+        runtimeReceiptId: z.ZodNullable<z.ZodString>;
+        matchedAt: z.ZodString;
+    }, z.core.$strict>;
+    target: z.ZodObject<{
+        runtime: z.ZodString;
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    trigger: z.ZodObject<{
+        triggerId: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        pattern: z.ZodObject<{
+            version: z.ZodDefault<z.ZodLiteral<"2">>;
+            root: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
+            partitionBy: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                fields: z.ZodArray<z.ZodObject<{
+                    ref: z.ZodString;
+                    path: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>>;
+            selection: z.ZodDefault<z.ZodObject<{
+                overlap: z.ZodDefault<z.ZodEnum<{
+                    allow: "allow";
+                    disallow: "disallow";
+                }>>;
+                afterMatch: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+                    skipPastLast: "skipPastLast";
+                    skipToNext: "skipToNext";
+                    keepAll: "keepAll";
+                }>, z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        skipToFirst: "skipToFirst";
+                        skipToLast: "skipToLast";
+                    }>;
+                    ref: z.ZodString;
+                }, z.core.$strict>]>>;
+                maxMatchesPerEvent: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+            execution: z.ZodDefault<z.ZodObject<{
+                maxCandidates: z.ZodDefault<z.ZodNumber>;
+                maxSemanticEvaluations: z.ZodDefault<z.ZodNumber>;
+                maxBufferedEvents: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        lifecycle: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>;
+    continuation: z.ZodNullable<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>>;
+    match: z.ZodObject<{
+        matchId: z.ZodString;
+        status: z.ZodString;
+        partitionKey: z.ZodNullable<z.ZodString>;
+        openedAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>;
+    evidence: z.ZodArray<z.ZodObject<{
+        clauseId: z.ZodString;
+        serverId: z.ZodNullable<z.ZodString>;
+        eventId: z.ZodString;
+        eventName: z.ZodString;
+        traceId: z.ZodString;
+        occurredAt: z.ZodString;
+        receivedAt: z.ZodOptional<z.ZodString>;
+        payloadHash: z.ZodNullable<z.ZodString>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    trust: z.ZodObject<{
+        continuation: z.ZodLiteral<"configured_trigger_instruction">;
+        evidence: z.ZodLiteral<"untrusted_external_signal">;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type EventEvidence = ActivationEvidence;
+export type EventActivation = ActivationEnvelope;

package/dist/src/intelligenceProtocol/activationSchemas.js

@@ -51,3 +51,6 @@ export const ActivationEnvelopeSchema = z.object({
 export function parseActivationEnvelope(value) {
     return ActivationEnvelopeSchema.parse(value);
 }
+/** Runtime-neutral public names for embedded-host integrations. */
+export const EventEvidenceSchema = ActivationEvidenceSchema;
+export const EventActivationSchema = ActivationEnvelopeSchema;

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

@@ -15,5 +15,5 @@ export { COMPOSITE_TRIGGER_PROTOCOL_VERSION, COMPOSITE_TRIGGER_SCHEMA_VERSION, S
 export type { StructuredPredicate, TriggerClause, ContinuationContextPolicy, ContinuationContract, EventTimePolicy, DerivedEventDefinition, DerivedEventRecord, CompositeTriggerDefinition, CorrelatableEvent, TriggerSourceEvent, PatternMatchState, TriggerMatchRecord, PatternSemanticDecision, } from './triggerSchemas.js';
 export { TriggerPlanEventSchema, TriggerPlanInputSchema, parseTriggerPlanInput, } from './triggerPlanSchemas.js';
 export type { TriggerPlanEvent, TriggerPlanInput, } from './triggerPlanSchemas.js';
-export { ActivationEvidenceSchema, ActivationEnvelopeSchema, parseActivationEnvelope, } from './activationSchemas.js';
-export type { ActivationEvidence, ActivationEnvelope, } from './activationSchemas.js';
+export { ActivationEvidenceSchema, ActivationEnvelopeSchema, EventEvidenceSchema, EventActivationSchema, parseActivationEnvelope, } from './activationSchemas.js';
+export type { ActivationEvidence, ActivationEnvelope, EventEvidence, EventActivation, } from './activationSchemas.js';

package/dist/src/intelligenceProtocol/index.js

@@ -8,4 +8,4 @@ export { canonicalJson, sha256Hex, } from './canonical.js';
 export { AuditChain, } from './audit.js';
 export { COMPOSITE_TRIGGER_PROTOCOL_VERSION, COMPOSITE_TRIGGER_SCHEMA_VERSION, StructuredPredicateSchema, TriggerClauseSchema, ContinuationContextPolicySchema, ContinuationContractSchema, EventTimePolicySchema, DerivedEventProjectionSchema, DerivedEventDefinitionSchema, DerivedEventEvidenceRefSchema, DerivedEventRecordSchema, CompositeTriggerDefinitionSchema, CorrelatableEventSchema, TriggerSourceEventSchema, PatternSemanticDecisionSchema, TriggerMatchStatusSchema, PatternMatchStateSchema, TriggerMatchRecordSchema, parseCompositeTriggerDefinition, parseCorrelatableEvent, parseTriggerMatchRecord, parseDerivedEventRecord, } from './triggerSchemas.js';
 export { TriggerPlanEventSchema, TriggerPlanInputSchema, parseTriggerPlanInput, } from './triggerPlanSchemas.js';
-export { ActivationEvidenceSchema, ActivationEnvelopeSchema, parseActivationEnvelope, } from './activationSchemas.js';
+export { ActivationEvidenceSchema, ActivationEnvelopeSchema, EventEvidenceSchema, EventActivationSchema, parseActivationEnvelope, } from './activationSchemas.js';

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

@@ -1,13 +1,7 @@
 import { z } from 'zod';
 export declare const RuntimeTargetSchema: z.ZodObject<{
     runtime: z.ZodString;
-    kind: z.ZodEnum<{
-        goal: "goal";
-        session: "session";
-        conversation: "conversation";
-        task: "task";
-        spawn_template: "spawn_template";
-    }>;
+    kind: z.ZodString;
     id: z.ZodString;
 }, z.core.$strip>;
 export declare const WakeRecordSchema: z.ZodObject<{
@@ -19,13 +13,7 @@ export declare const WakeRecordSchema: z.ZodObject<{
     createdAt: z.ZodString;
     target: z.ZodObject<{
         runtime: z.ZodString;
-        kind: z.ZodEnum<{
-            goal: "goal";
-            session: "session";
-            conversation: "conversation";
-            task: "task";
-            spawn_template: "spawn_template";
-        }>;
+        kind: z.ZodString;
         id: z.ZodString;
     }, z.core.$strip>;
     status: z.ZodEnum<{

package/dist/src/intelligenceProtocol/schemas.js

@@ -3,7 +3,9 @@ const Id = z.string().min(1).max(200);
 const Timestamp = z.string().datetime({ offset: true });
 export const RuntimeTargetSchema = z.object({
     runtime: z.string().min(1),
-    kind: z.enum(['goal', 'session', 'conversation', 'task', 'spawn_template']),
+    // Host-owned continuation kind. Event Intelligence persists and returns
+    // this opaque discriminator; it must not encode one runtime's task model.
+    kind: z.string().min(1).max(100),
     id: Id,
 });
 export const WakeRecordSchema = z.object({

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

@@ -210,13 +210,7 @@ export declare const TriggerPlanInputSchema: z.ZodObject<{
     conditionOnly: z.ZodDefault<z.ZodBoolean>;
     target: z.ZodOptional<z.ZodObject<{
         runtime: z.ZodString;
-        kind: z.ZodEnum<{
-            goal: "goal";
-            session: "session";
-            conversation: "conversation";
-            task: "task";
-            spawn_template: "spawn_template";
-        }>;
+        kind: z.ZodString;
         id: z.ZodString;
     }, z.core.$strip>>;
     continuation: z.ZodOptional<z.ZodObject<{

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

@@ -379,13 +379,7 @@ export declare const CompositeTriggerDefinitionSchema: z.ZodObject<{
     withinMs: z.ZodNumber;
     target: z.ZodOptional<z.ZodObject<{
         runtime: z.ZodString;
-        kind: z.ZodEnum<{
-            goal: "goal";
-            session: "session";
-            conversation: "conversation";
-            task: "task";
-            spawn_template: "spawn_template";
-        }>;
+        kind: z.ZodString;
         id: z.ZodString;
     }, z.core.$strip>>;
     derivedEvent: z.ZodOptional<z.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "MCP-native complex event processing for durable agent workflows: event-time patterns, semantic predicates, derived events, and targeted wakeups.",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,10 @@
     "./provider/erpnext": {
       "types": "./dist/src/mcpEvents/erpnextProvider.d.ts",
       "import": "./dist/src/mcpEvents/erpnextProvider.js"
+    },
+    "./embedded": {
+      "types": "./scripts/embedded-host-kit.d.mts",
+      "import": "./scripts/embedded-host-kit.mjs"
     }
   },
   "bin": {
@@ -41,7 +45,9 @@
     "scripts/mcp-stdio-server.mjs",
     "scripts/host-integration.mjs",
     "scripts/host-integration.d.mts",
-    "scripts/run-tests.mjs"
+    "scripts/run-tests.mjs",
+    "scripts/embedded-host-kit.mjs",
+    "scripts/embedded-host-kit.d.mts"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -57,7 +63,8 @@
     "pack:mcp-smoke": "node scripts/package-mcp-smoke.mjs",
     "conformance:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-conformance.mjs",
     "bench:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-benchmark.mjs --profile quick",
-    "evidence:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-conformance.mjs && node scripts/evidence/pattern-v2-benchmark.mjs --profile quick"
+    "evidence:pattern-v2": "npm run build && node scripts/evidence/pattern-v2-conformance.mjs && node scripts/evidence/pattern-v2-benchmark.mjs --profile quick",
+    "prepare": "npm run build"
   },
   "keywords": [
     "mcp",

package/scripts/embedded-host-kit.d.mts

@@ -0,0 +1,160 @@
+import type {
+  ActivationEnvelope,
+  RuntimeTarget,
+} from '../dist/src/intelligenceProtocol/index.js';
+
+export type {
+  ActivationEnvelope as EventActivation,
+  RuntimeTarget as ContinuationTarget,
+};
+import type {
+  EventIntelligenceHost,
+  EventIntelligenceHostOptions,
+  HostMcpConnectionOptions,
+  HostMcpRegistry,
+  HostWakeHandler,
+  HostWakeReceipt,
+} from './host-integration.d.mts';
+
+export interface EmbeddedHostIdentity {
+  type: string;
+  principal_id: string;
+  tenant_id?: string;
+}
+
+export interface EmbeddedToolContext {
+  scopeId?: string;
+  target: RuntimeTarget;
+  actor: EmbeddedHostIdentity;
+  owner: EmbeddedHostIdentity;
+  confirmationId?: string;
+  [key: string]: unknown;
+}
+
+export interface PortableToolResult {
+  ok: boolean;
+  data?: any;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+export interface PortableAgentTool<RuntimeContext = unknown> {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  execute(
+    args: unknown,
+    runtimeContext: RuntimeContext,
+  ): Promise<PortableToolResult>;
+}
+
+export interface AuthorizationDecision {
+  allowed: boolean;
+  code?: string;
+  message?: string;
+  actor?: EmbeddedHostIdentity;
+  owner?: EmbeddedHostIdentity;
+  confirmationId?: string;
+}
+
+export interface ActivationDeliveryInput<Target = unknown> {
+  packet: Record<string, unknown>;
+  activation: ActivationEnvelope;
+  target: Target;
+  receiptId: string;
+}
+
+export interface ActivationDispatcherOptions<Target = RuntimeTarget> {
+  resolveTarget?: (
+    target: RuntimeTarget,
+    activation: ActivationEnvelope,
+  ) => Target | null | Promise<Target | null>;
+  hasReceipt?: (
+    receiptId: string,
+    activation: ActivationEnvelope,
+  ) => boolean | Promise<boolean>;
+  receiptId?: (input: {
+    packet: Record<string, unknown>;
+    activation: ActivationEnvelope;
+  }) => string | Promise<string>;
+  deliver(
+    input: ActivationDeliveryInput<Target>,
+  ): HostWakeReceipt | string | void | Promise<HostWakeReceipt | string | void>;
+}
+
+export interface EventIntelligenceAgentToolsOptions<RuntimeContext = unknown> {
+  host: EventIntelligenceHost;
+  resolveContext(
+    runtimeContext: RuntimeContext,
+    request: {
+      action: 'event.sources.list' | 'trigger.create';
+      input?: unknown;
+    },
+  ): EmbeddedToolContext | Promise<EmbeddedToolContext>;
+  authorize(input: {
+    action: 'trigger.create';
+    runtimeContext: RuntimeContext;
+    context: EmbeddedToolContext;
+    input: unknown;
+    plan: any;
+  }):
+    | boolean
+    | AuthorizationDecision
+    | Promise<boolean | AuthorizationDecision>;
+  names?: {
+    sources?: string;
+    create?: string;
+  };
+}
+
+export interface EmbeddedEventIntelligenceOptions<RuntimeContext = unknown>
+  extends Omit<EventIntelligenceHostOptions, 'wake' | 'mcpRegistry'> {
+  mcpRegistry?: HostMcpRegistry;
+  mcp?: {
+    listConnections(): Iterable<HostMcpConnectionOptions> | Promise<Iterable<HostMcpConnectionOptions>>;
+    subscribe?: (listener: () => void) => void | (() => void);
+  };
+  activation?: ActivationDispatcherOptions<any>;
+  wake?: HostWakeHandler;
+  agentTools?: Omit<EventIntelligenceAgentToolsOptions<RuntimeContext>, 'host'>;
+  /** Test/advanced injection; normal callers should omit it. */
+  createHost?: (options: EventIntelligenceHostOptions) => Promise<EventIntelligenceHost>;
+}
+
+export interface EmbeddedEventIntelligence<RuntimeContext = unknown> {
+  readonly host: EventIntelligenceHost;
+  readonly runtime: any;
+  readonly tools: PortableAgentTool<RuntimeContext>[];
+  createAgentTools<Context = RuntimeContext>(
+    options: Omit<EventIntelligenceAgentToolsOptions<Context>, 'host'>,
+  ): PortableAgentTool<Context>[];
+  refresh(): Promise<any[]>;
+  status(): Promise<any[]> | any[];
+  scope(scopeId?: string): ReturnType<EventIntelligenceHost['scope']>;
+  close(): Promise<void>;
+}
+
+export function createContinuationTarget(input: {
+  runtime: string;
+  kind: string;
+  id: string;
+}): RuntimeTarget;
+
+export function createActivationDispatcher<Target = RuntimeTarget>(
+  options: ActivationDispatcherOptions<Target>,
+): HostWakeHandler;
+
+export function createEventIntelligenceAgentTools<RuntimeContext = unknown>(
+  options: EventIntelligenceAgentToolsOptions<RuntimeContext>,
+): PortableAgentTool<RuntimeContext>[];
+
+export function createEmbeddedEventIntelligence<RuntimeContext = unknown>(
+  options?: EmbeddedEventIntelligenceOptions<RuntimeContext>,
+): Promise<EmbeddedEventIntelligence<RuntimeContext>>;
+
+export const PORTABLE_EVENT_INTELLIGENCE_TOOL_NAMES: Readonly<{
+  sources: 'event_sources_list';
+  create: 'trigger_create';
+}>;

package/scripts/embedded-host-kit.mjs

@@ -0,0 +1,567 @@
+import { z } from 'zod';
+import {
+  RuntimeTargetSchema,
+  parseActivationEnvelope,
+} from '../dist/src/intelligenceProtocol/index.js';
+import {
+  createEventIntelligenceHost,
+  createMcpRegistryAdapter,
+} from './host-integration.mjs';
+
+const DEFAULT_TOOL_NAMES = Object.freeze({
+  sources: 'event_sources_list',
+  create: 'trigger_create',
+});
+
+const TriggerClauseInput = z.object({
+  id: z.string().min(1).max(200).optional(),
+  event: z.string().min(1).max(200),
+  serverId: z.string().min(1).max(200).optional(),
+  arguments: z.record(z.string(), z.unknown()).optional(),
+  where: z.array(z.record(z.string(), z.unknown())).max(32).optional(),
+}).strict();
+
+const TriggerCreateInput = z.object({
+  trigger_id: z.string().min(1).max(200).optional(),
+  version: z.string().min(1).max(100).optional(),
+  description: z.string().max(500).optional(),
+  events: z.array(TriggerClauseInput).min(1).max(32),
+  pattern: z.record(z.string(), z.unknown()).optional(),
+  within_ms: z.number().int().positive().max(30 * 24 * 60 * 60 * 1000)
+    .optional(),
+  event_time: z.object({
+    allowed_lateness_ms: z.number().int().nonnegative()
+      .max(30 * 24 * 60 * 60 * 1000),
+  }).strict().optional(),
+  instruction: z.string().min(1).max(4000),
+  one_shot: z.boolean().optional(),
+  max_firings: z.number().int().min(1).optional(),
+  cooldown_ms: z.number().int().nonnegative().optional(),
+  expires_at: z.string().datetime({ offset: true }).optional(),
+  lease_until: z.string().datetime({ offset: true }).optional(),
+  complete_on_goal: z.boolean().optional(),
+}).strict();
+
+const SOURCES_INPUT_SCHEMA = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {},
+});
+
+const CREATE_INPUT_SCHEMA = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  required: ['events', 'instruction'],
+  properties: {
+    trigger_id: { type: 'string', minLength: 1, maxLength: 200 },
+    version: { type: 'string', minLength: 1, maxLength: 100 },
+    description: { type: 'string', maxLength: 500 },
+    events: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 32,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['event'],
+        properties: {
+          id: { type: 'string', minLength: 1, maxLength: 200 },
+          event: { type: 'string', minLength: 1, maxLength: 200 },
+          serverId: { type: 'string', minLength: 1, maxLength: 200 },
+          arguments: { type: 'object', additionalProperties: true },
+          where: {
+            type: 'array',
+            maxItems: 32,
+            items: { type: 'object', additionalProperties: true },
+          },
+        },
+      },
+    },
+    pattern: { type: 'object', additionalProperties: true },
+    within_ms: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 30 * 24 * 60 * 60 * 1000,
+    },
+    event_time: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['allowed_lateness_ms'],
+      properties: {
+        allowed_lateness_ms: {
+          type: 'integer',
+          minimum: 0,
+          maximum: 30 * 24 * 60 * 60 * 1000,
+        },
+      },
+    },
+    instruction: { type: 'string', minLength: 1, maxLength: 4000 },
+    one_shot: { type: 'boolean' },
+    max_firings: { type: 'integer', minimum: 1 },
+    cooldown_ms: { type: 'integer', minimum: 0 },
+    expires_at: { type: 'string' },
+    lease_until: { type: 'string' },
+    complete_on_goal: { type: 'boolean' },
+  },
+});
+
+function errorCode(error, fallback) {
+  return String(error?.code || fallback);
+}
+
+function fail(error, fallbackCode = 'EVENT_INTELLIGENCE_TOOL_FAILED') {
+  return {
+    ok: false,
+    error: {
+      code: errorCode(error, fallbackCode),
+      message: error instanceof Error ? error.message : String(error),
+    },
+  };
+}
+
+function normalizeIdentity(input, label) {
+  if (!input || typeof input !== 'object') {
+    throw new Error(`${label} is required`);
+  }
+  const type = String(input.type || '').trim();
+  const principalId = String(
+    input.principal_id ?? input.principalId ?? '',
+  ).trim();
+  const tenantId = String(
+    input.tenant_id ?? input.tenantId ?? '',
+  ).trim();
+  if (!type || !principalId) {
+    throw new Error(`${label} requires type and principal_id`);
+  }
+  return {
+    type,
+    principal_id: principalId,
+    ...(tenantId ? { tenant_id: tenantId } : {}),
+  };
+}
+
+function normalizeAuthorization(decision) {
+  if (decision === true) return { allowed: true };
+  if (decision === false || decision == null) return { allowed: false };
+  if (typeof decision !== 'object') {
+    throw new Error('authorize() must return boolean or an authorization decision');
+  }
+  return {
+    ...decision,
+    allowed: decision.allowed === true,
+  };
+}
+
+function normalizedReceipt(result, fallbackId) {
+  if (typeof result === 'string' && result.trim()) {
+    return { runtimeReceiptId: result };
+  }
+  if (
+    result &&
+    typeof result === 'object' &&
+    typeof result.runtimeReceiptId === 'string' &&
+    result.runtimeReceiptId.trim()
+  ) {
+    return result;
+  }
+  if (result === undefined && fallbackId) {
+    return { runtimeReceiptId: fallbackId };
+  }
+  throw new Error('Activation delivery must return runtimeReceiptId');
+}
+
+function wakeIdFromPacket(packet) {
+  if (!packet || typeof packet !== 'object') return null;
+  const value = packet.wake_id ?? packet.wakeId;
+  return typeof value === 'string' && value.trim() ? value : null;
+}
+
+/**
+ * A runtime-neutral continuation target. EI persists and returns this value
+ * without assigning semantics to runtime/kind/id.
+ */
+export function createContinuationTarget(input) {
+  return RuntimeTargetSchema.parse(input);
+}
+
+/**
+ * Runtime-neutral wake boundary.
+ *
+ * EI owns wake retries; the host owns target resolution and the side effect
+ * that resumes work. Optional receipt hooks close the host-side crash window
+ * without teaching EI what a Turn, Execution, thread, graph or Case is.
+ */
+export function createActivationDispatcher({
+  resolveTarget,
+  hasReceipt,
+  receiptId,
+  deliver,
+} = {}) {
+  if (resolveTarget !== undefined && typeof resolveTarget !== 'function') {
+    throw new Error('resolveTarget must be a function');
+  }
+  if (hasReceipt !== undefined && typeof hasReceipt !== 'function') {
+    throw new Error('hasReceipt must be a function');
+  }
+  if (receiptId !== undefined && typeof receiptId !== 'function') {
+    throw new Error('receiptId must be a function');
+  }
+  if (typeof deliver !== 'function') {
+    throw new Error('Activation dispatcher requires deliver()');
+  }
+
+  return async (packet = {}, activationInput) => {
+    const activation = parseActivationEnvelope(activationInput);
+    const packetWakeId = wakeIdFromPacket(packet);
+    if (packetWakeId && packetWakeId !== activation.wake.wakeId) {
+      const error = new Error(
+        `Wake id mismatch: packet ${packetWakeId} != activation ${activation.wake.wakeId}`,
+      );
+      error.code = 'EVENT_ACTIVATION_WAKE_ID_MISMATCH';
+      throw error;
+    }
+
+    const candidateReceiptId = String(
+      await (receiptId
+        ? receiptId({ packet, activation })
+        : activation.wake.wakeId),
+    ).trim();
+    if (!candidateReceiptId) {
+      const error = new Error('Activation receipt id must be non-empty');
+      error.code = 'EVENT_ACTIVATION_RECEIPT_ID_REQUIRED';
+      throw error;
+    }
+
+    if (hasReceipt && await hasReceipt(candidateReceiptId, activation)) {
+      return {
+        runtimeReceiptId: candidateReceiptId,
+        duplicate: true,
+      };
+    }
+
+    const target = resolveTarget
+      ? await resolveTarget(activation.target, activation)
+      : activation.target;
+    if (target == null) {
+      const error = new Error(
+        `Continuation target unavailable: ${activation.target.runtime}/${activation.target.kind}/${activation.target.id}`,
+      );
+      error.code = 'EVENT_ACTIVATION_TARGET_UNAVAILABLE';
+      throw error;
+    }
+
+    try {
+      return normalizedReceipt(
+        await deliver({
+          packet,
+          activation,
+          target,
+          receiptId: candidateReceiptId,
+        }),
+        candidateReceiptId,
+      );
+    } catch (error) {
+      if (hasReceipt && await hasReceipt(candidateReceiptId, activation)) {
+        return {
+          runtimeReceiptId: candidateReceiptId,
+          duplicate: true,
+        };
+      }
+      throw error;
+    }
+  };
+}
+
+async function scopedHostFor(host, resolvedContext) {
+  if (
+    resolvedContext?.scopeId !== undefined &&
+    typeof host.scope === 'function'
+  ) {
+    return host.scope(resolvedContext.scopeId);
+  }
+  return host;
+}
+
+function sourceSummary(source) {
+  return {
+    connectionId: source.connectionId,
+    serverId: source.serverId,
+    eventName: source.eventName,
+    description: source.description ?? null,
+    delivery: source.delivery ?? [],
+    inputSchema: source.inputSchema ?? {},
+    payloadSchema: source.payloadSchema ?? {},
+  };
+}
+
+function buildPlanInput(parsed, target) {
+  return {
+    ...(parsed.trigger_id ? { triggerId: parsed.trigger_id } : {}),
+    ...(parsed.version ? { version: parsed.version } : {}),
+    ...(parsed.description ? { description: parsed.description } : {}),
+    events: parsed.events.map((event) => ({
+      ...(event.id ? { id: event.id } : {}),
+      event: event.event,
+      ...(event.serverId ? { serverId: event.serverId } : {}),
+      arguments: event.arguments ?? {},
+      where: event.where ?? [],
+    })),
+    ...(parsed.pattern ? { pattern: parsed.pattern } : {}),
+    ...(parsed.within_ms !== undefined ? { withinMs: parsed.within_ms } : {}),
+    ...(parsed.event_time
+      ? { eventTime: { allowedLatenessMs: parsed.event_time.allowed_lateness_ms } }
+      : {}),
+    lifecycle: {
+      oneShot: parsed.one_shot ?? true,
+      ...(parsed.max_firings !== undefined
+        ? { maxFirings: parsed.max_firings }
+        : {}),
+      ...(parsed.cooldown_ms !== undefined
+        ? { cooldownMs: parsed.cooldown_ms }
+        : {}),
+      ...(parsed.expires_at ? { expiresAt: parsed.expires_at } : {}),
+      ...(parsed.lease_until ? { leaseUntil: parsed.lease_until } : {}),
+      ...(parsed.complete_on_goal !== undefined
+        ? { completeOnGoal: parsed.complete_on_goal }
+        : {}),
+    },
+    target,
+    continuation: {
+      instruction: parsed.instruction,
+      contextPolicy: {
+        evidence: 'matched_events',
+        maxEvents: 20,
+        includeData: true,
+      },
+    },
+  };
+}
+
+/**
+ * Portable agent-facing tools. The descriptors do not depend on OpenAI,
+ * Anthropic, MCP tool objects, Muffin, Artemis, LangGraph, or any other host.
+ * Adapters only need to translate {name, description, inputSchema, execute}.
+ */
+export function createEventIntelligenceAgentTools({
+  host,
+  resolveContext,
+  authorize,
+  names = {},
+} = {}) {
+  if (!host || typeof host !== 'object') {
+    throw new Error('Agent tools require an Event Intelligence host');
+  }
+  if (typeof resolveContext !== 'function') {
+    throw new Error('Agent tools require resolveContext()');
+  }
+  if (typeof authorize !== 'function') {
+    throw new Error('Agent tools require authorize() for durable mutations');
+  }
+
+  const toolNames = {
+    ...DEFAULT_TOOL_NAMES,
+    ...names,
+  };
+
+  return [
+    {
+      name: toolNames.sources,
+      description:
+        'List live future-event sources discovered from MCP connections already owned by the host runtime. Use this before creating a trigger so event names and schemas are not guessed.',
+      inputSchema: SOURCES_INPUT_SCHEMA,
+      async execute(_args, runtimeContext) {
+        try {
+          const resolved = await resolveContext(runtimeContext, {
+            action: 'event.sources.list',
+          });
+          if (typeof host.refreshMcpRegistry === 'function') {
+            await host.refreshMcpRegistry();
+          }
+          const scoped = await scopedHostFor(host, resolved);
+          const sources = await Promise.resolve(scoped.eventSources);
+          return {
+            ok: true,
+            data: {
+              sources: Array.isArray(sources)
+                ? sources.map(sourceSummary)
+                : [],
+            },
+          };
+        } catch (error) {
+          return fail(error, 'EVENT_SOURCES_LIST_FAILED');
+        }
+      },
+    },
+    {
+      name: toolNames.create,
+      description:
+        'Create a durable future condition. The host, not the model, supplies the continuation target and authority context; Event Intelligence wakes that target only when the condition matches.',
+      inputSchema: CREATE_INPUT_SCHEMA,
+      async execute(args, runtimeContext) {
+        const parsed = TriggerCreateInput.safeParse(args ?? {});
+        if (!parsed.success) {
+          const issue = parsed.error.issues[0];
+          return {
+            ok: false,
+            error: {
+              code: 'EVENT_TRIGGER_INPUT_INVALID',
+              message:
+                `${issue?.path?.join('.') || 'input'} — ${issue?.message || 'invalid'}`,
+            },
+          };
+        }
+
+        try {
+          const resolved = await resolveContext(runtimeContext, {
+            action: 'trigger.create',
+            input: parsed.data,
+          });
+          const target = createContinuationTarget(resolved?.target);
+          if (typeof host.refreshMcpRegistry === 'function') {
+            await host.refreshMcpRegistry();
+          }
+          const scoped = await scopedHostFor(host, resolved);
+          const plan = await scoped.planTrigger(
+            buildPlanInput(parsed.data, target),
+          );
+
+          const decision = normalizeAuthorization(
+            await authorize({
+              action: 'trigger.create',
+              runtimeContext,
+              context: resolved,
+              input: parsed.data,
+              plan,
+            }),
+          );
+          if (!decision.allowed) {
+            return {
+              ok: false,
+              error: {
+                code: String(
+                  decision.code || 'EVENT_TRIGGER_AUTHORIZATION_DENIED',
+                ),
+                message: String(
+                  decision.message || 'Host denied durable trigger creation',
+                ),
+              },
+            };
+          }
+
+          const actor = normalizeIdentity(
+            decision.actor ?? resolved?.actor,
+            'actor',
+          );
+          const owner = normalizeIdentity(
+            decision.owner ?? resolved?.owner,
+            'owner',
+          );
+          const confirmationId = String(
+            decision.confirmationId ?? resolved?.confirmationId ?? '',
+          ).trim();
+
+          const created = await scoped.triggerControl.createTrigger({
+            definition: plan.definition,
+            connectionIds: plan.connectionIds,
+            actor,
+            owner,
+            ...(confirmationId ? { confirmationId } : {}),
+          });
+
+          return {
+            ok: true,
+            data: {
+              receiptId: created.receiptId,
+              triggerId: created.definition?.triggerId,
+              version: created.definition?.version,
+              state: created.state,
+              connectionIds: plan.connectionIds,
+              warnings: plan.warnings ?? [],
+            },
+          };
+        } catch (error) {
+          return fail(error, 'EVENT_TRIGGER_CREATE_FAILED');
+        }
+      },
+    },
+  ];
+}
+
+/**
+ * High-level embedded install. EI remains in-process; MCP transports/auth and
+ * continuation semantics remain owned by the host.
+ */
+export async function createEmbeddedEventIntelligence({
+  dataDir,
+  store,
+  env = {},
+  mcpRegistry,
+  mcp,
+  mcpClients = [],
+  semanticEvaluator,
+  activation,
+  wake,
+  wakeHandlers = {},
+  agentTools,
+  createHost = createEventIntelligenceHost,
+} = {}) {
+  if (activation !== undefined && wake !== undefined) {
+    throw new Error('Provide activation or wake, not both');
+  }
+
+  let registry = mcpRegistry;
+  if (!registry && mcp) {
+    registry = createMcpRegistryAdapter({
+      listConnections: mcp.listConnections,
+      ...(mcp.subscribe ? { subscribe: mcp.subscribe } : {}),
+    });
+  }
+
+  const wakeHandler = activation
+    ? createActivationDispatcher(activation)
+    : wake;
+
+  const host = await createHost({
+    dataDir,
+    store,
+    env,
+    mcpRegistry: registry,
+    mcpClients,
+    semanticEvaluator,
+    ...(wakeHandler ? { wake: wakeHandler } : {}),
+    wakeHandlers,
+  });
+
+  const tools = agentTools
+    ? createEventIntelligenceAgentTools({
+        host,
+        ...agentTools,
+      })
+    : [];
+
+  return {
+    host,
+    runtime: host.runtime,
+    tools,
+    createAgentTools(options) {
+      return createEventIntelligenceAgentTools({
+        host,
+        ...options,
+      });
+    },
+    refresh() {
+      return host.refreshMcpRegistry();
+    },
+    status() {
+      return host.mcpStatus();
+    },
+    scope(scopeId) {
+      return host.scope(scopeId);
+    },
+    close() {
+      return host.close();
+    },
+  };
+}
+
+export const PORTABLE_EVENT_INTELLIGENCE_TOOL_NAMES = DEFAULT_TOOL_NAMES;

package/scripts/host-integration.mjs

@@ -144,8 +144,10 @@ export async function createEventIntelligenceHost({
 
   const registryManaged = new Set();
   let unsubscribe = null;
+  let registryRefreshPromise = null;
+  let registryRefreshRequested = false;
 
-  const refreshMcpRegistry = async () => {
+  const refreshMcpRegistryOnce = async () => {
     const entries = await listRegistryConnections(mcpRegistry);
     const desired = new Map();
 
@@ -213,6 +215,26 @@ export async function createEventIntelligenceHost({
     return outcomes;
   };
 
+  const refreshMcpRegistry = () => {
+    if (registryRefreshPromise) {
+      registryRefreshRequested = true;
+      return registryRefreshPromise;
+    }
+
+    registryRefreshPromise = (async () => {
+      const outcomes = [];
+      do {
+        registryRefreshRequested = false;
+        outcomes.push(...await refreshMcpRegistryOnce());
+      } while (registryRefreshRequested);
+      return outcomes;
+    })().finally(() => {
+      registryRefreshPromise = null;
+    });
+
+    return registryRefreshPromise;
+  };
+
   if (mcpRegistry) {
     await refreshMcpRegistry();
 
@@ -297,4 +319,4 @@ export {
   describeStoreCapabilities,
   PersistentEventStore,
   validateSharedStoreCapabilities,
-};
+};

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sarooo17/event-intelligence",
   "title": "MCP Event Intelligence",
   "description": "MCP-native CEP for durable agents: event-time patterns, semantic predicates, derived events.",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "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.6.1",
+      "version": "0.7.1",
       "transport": {
         "type": "stdio"
       },