mcp-event-intelligence 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable public changes are documented here.
 
+## [0.2.0] - 2026-09-20
+
+Production-hardening release for shared Event Intelligence hosts.
+
+### Shared-host isolation
+
+- explicit `scopeId` partitions for tenant/workspace isolation;
+- scoped host views via `host.scope(scopeId)`;
+- isolated triggers, matches, event sources, cursors, deadlines, derived events and wake delivery state;
+- persistent scope restoration after restart;
+- root host documented as a trusted operator/control-plane capability.
+
+### Pluggable persistence
+
+- `createEventIntelligenceHost({ store })` now accepts an external storage backend;
+- `PersistentEventStore` remains the zero-dependency default;
+- scoped custom backends can implement `forScope(scopeId)`;
+- storage contract validates the operations required by Event Intelligence at startup.
+
+### Durable wake delivery
+
+- persisted wake-delivery state with `pending`, `claimed`, `retry_pending`, `delivered` and `dead_letter`;
+- atomic claim/lease API for concurrent workers;
+- bounded exponential retry and retry scheduler;
+- restart recovery without a new provider event;
+- reconciliation of a persisted runtime receipt after a crash without redelivering the wake;
+- the direct `EventProcessor` path now uses the same durable retry semantics.
+
+### Polling and load control
+
+- single-flight polling per MCP connection;
+- bounded `hasMore` page draining;
+- cursor persistence after every drained page;
+- explicit batch-limit reporting.
+
+### Internal modularity
+
+- composite store contracts extracted from `engine.ts`;
+- matching/correlation helpers extracted into a dedicated module;
+- derived-event cycle validation extracted into a graph module;
+- lifecycle, deadline and audit support extracted from the engine.
+
+### Provider coverage
+
+- new `mcp-event-intelligence/provider/erpnext` export;
+- provider-native ERPNext adapter for `erpnext.sales_invoice.submitted` and `erpnext.sales_order.created`;
+- schema-validation and provider-generalization regression coverage.
+
+### Verification
+
+- tenant-isolation tests with identical trigger IDs in separate scopes;
+- custom-store injection and restart persistence tests;
+- polling single-flight and bounded-batching tests;
+- retry, dead-letter, lease-contention and post-receipt crash-reconciliation tests;
+- ERPNext provider adapter tests;
+- CI, Security Scan, MCP Launch Check, Clean-room Smoke and Public Release Check green before release.
+
+## [0.1.1] - 2026-09-20
+
+Provider integration patch.
+
+### Provider-facing MCP Events adapter
+
+- public `mcp-event-intelligence/provider` package export;
+- callback-backed `createMcpEventsProvider()` for stateless provider runtimes;
+- generic experimental Events capability advertisement plus `server/discover`, `events/list`, and `events/poll` dispatch;
+- provider-owned opaque cursors, authentication context, data queries and domain event semantics;
+- fail-closed EventOccurrence and payload-schema validation;
+- lower-level store-backed `ExperimentalMcpEventsServer` remains available through the provider export;
+- packed-artifact smoke coverage for the new subpath.
+
+The Event Intelligence and composite-trigger protocol/schema versions remain `0.1.0` / `v0.1`; this patch adds a package integration surface without changing persisted protocol contracts.
+
 ## [0.1.0] - 2026-09-20
 
 Initial public reference release.

package/README.md

@@ -3,6 +3,8 @@
 > Durable temporal event intelligence for sleeping agents.
 
 [![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.2.0-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.
@@ -21,12 +23,14 @@ Event Intelligence persists that continuation independently of the model, waits
 
 ## Embed it in an existing agent host
 
-After publication:
+Install from npm:
 
 ```bash
 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)
+
 Pass the harness-level MCP registry once — not every MCP one by one:
 
 ```js
@@ -50,6 +54,94 @@ const ei = await createEventIntelligenceHost({
 
 Event Intelligence enumerates the host registry automatically. GitHub, Gmail, private/company MCPs and future connections do not need to be configured again inside EI. Tools-only MCPs remain available to the agent and are ignored by the Events layer; Events-capable MCPs are attached automatically.
 
+
+### Shared hosts, tenant isolation and storage
+
+One EI host can serve many tenants/workspaces without sharing trigger state. Give each host-owned MCP connection a `scopeId` and give tenant-facing code only the corresponding scoped view:
+
+```js
+const tenant = await ei.scope('tenant-acme');
+
+await tenant.triggerControl.createTrigger({
+  definition,
+  connectionIds: ['acme-erp'],
+  actor,
+  owner,
+});
+
+const acmeConnections = tenant.mcpStatus();
+```
+
+The default reference store physically namespaces non-default scopes under separate persistent store partitions. Trigger IDs, match IDs, cursors, event sources, deadlines, derived events and wake delivery state are therefore resolved inside a scope rather than filtered out of a global result after the fact. The root host object is the trusted operator/control-plane capability; tenant code should receive a scoped view.
+
+Storage is injectable:
+
+```js
+const ei = await createEventIntelligenceHost({
+  store: myEventIntelligenceStore,
+  mcpRegistry,
+  wake,
+});
+```
+
+`PersistentEventStore` remains the zero-dependency default. A custom backend can implement `forScope(scopeId)` to return an isolated tenant view. For horizontally scaled workers, its wake-delivery claim/lease operations must be atomic across processes; the bundled JSONL store provides serialized atomicity inside one process and is a reference backend, not a distributed database.
+
+
+## Add Events to an MCP provider
+
+Providers can expose the experimental Events boundary without reimplementing the generic JSON-RPC glue:
+
+```js
+import { createMcpEventsProvider } from 'mcp-event-intelligence/provider';
+
+const events = createMcpEventsProvider({
+  events: [
+    {
+      descriptor: {
+        name: 'erpnext.sales_invoice.submitted',
+        description: 'A submitted Sales Invoice was observed.',
+        delivery: ['poll'],
+        inputSchema: { type: 'object' },
+        payloadSchema: {
+          type: 'object',
+          required: ['name', 'company', 'grand_total'],
+          properties: {
+            name: { type: 'string' },
+            company: { type: 'string' },
+            grand_total: { type: 'number' },
+          },
+        },
+      },
+      poll: async ({ cursor, maxEvents, context }) => {
+        return providerRuntime.pollInvoices({ cursor, maxEvents, context });
+      },
+    },
+  ],
+});
+```
+
+The package owns capability advertisement, `server/discover`, `events/list`, `events/poll`, common validation and response shapes. The provider owns domain event definitions, authentication, data queries, occurrence IDs and opaque cursor semantics.
+
+This adapter remains experimental compatibility work around MCP Events; it is not a claim of finalized MCP Events conformance.
+
+
+A concrete ERP-shaped adapter is also exported, so the provider abstraction is exercised against a source structurally different from GitHub:
+
+```js
+import {
+  createErpNextEventsProvider,
+} from 'mcp-event-intelligence/provider/erpnext';
+
+const events = createErpNextEventsProvider({
+  pollSalesInvoices: ({ cursor, maxEvents }) =>
+    erp.pollSubmittedInvoices({ cursor, maxEvents }),
+  pollSalesOrders: ({ cursor, maxEvents }) =>
+    erp.pollCreatedSalesOrders({ cursor, maxEvents }),
+});
+```
+
+It exposes `erpnext.sales_invoice.submitted` and `erpnext.sales_order.created` while leaving ERP authentication/query ownership with the provider.
+
 ## What v0.1 implements
 
 ### Host-owned event sources
@@ -59,6 +151,8 @@ Event Intelligence enumerates the host registry automatically. GitHub, Gmail, pr
 - experimental MCP Events capability discovery;
 - `events/list` and `events/poll`;
 - persistent opaque cursors;
+- per-scope source/cursor isolation for shared hosts;
+- single-flight polling per connection plus bounded `hasMore` batch draining;
 - automatic event-source registration;
 - dynamic attach/detach of host MCP clients;
 - provider-native compatibility adapters such as GitHub webhooks.
@@ -118,6 +212,8 @@ Derived event names are versioned contracts such as `release.ready@1`.
 
 An embedded harness can provide one in-process wake dispatcher that routes by `target.runtime`, `target.kind` and `target.id`; runtime-specific handlers remain available as a lower-level option. A standalone deployment can instead use signed HMAC callbacks. Both paths return a stable `runtimeReceiptId`.
 
+Runtime delivery is durable: a stable wake ID gets a persisted delivery record, a worker claims it with a lease, transient failures are retried with bounded exponential backoff, expired claims can be recovered after restart, and only an exhausted retry budget enters dead-letter. This prevents two workers sharing an atomic store from intentionally owning the same delivery at the same time. The runtime should still treat the stable wake ID as an idempotency key because no system can make an arbitrary external side effect transactionally exactly-once without cooperation from the receiver.
+
 ## Why this exists
 
 MCP Events is concerned with the event transport/subscription boundary. Event Intelligence explores the layer **above transport**:
@@ -153,6 +249,10 @@ The v0.1 acceptance suite verifies:
 - process shutdown while a temporal deadline is pending;
 - restart on the same datastore after the deadline;
 - wake recovery **without a new provider event**;
+- retry-state recovery after process restart and lease-based concurrent-worker exclusion;
+- shared-host tenant isolation with identical trigger IDs in different scopes;
+- bounded/single-flight provider polling;
+- provider-generalization coverage with ERPNext-shaped invoice/order events;
 - hash-linked audit verification.
 
 A separate live regression also verified real GitHub webhook ingress into the MCP EventOccurrence / composite fan-in path.
@@ -166,7 +266,7 @@ A separate live regression also verified real GitHub webhook ingress into the MC
 
 ```bash
 git clone https://github.com/sarooo17/event-intelligence.git
-cd mcp-event-intelligence
+cd event-intelligence
 npm ci
 npm run check
 
@@ -221,6 +321,11 @@ Standalone/core environment variables:
 | `RUNTIME_WAKE_TARGETS_JSON` | no | signed standalone runtime callbacks |
 | `GITHUB_WEBHOOK_SECRET` | no | verify GitHub webhook ingress |
 | `TYPESAFE_API_KEY` | no | bundled TypeSafe Jev semantic evaluator |
+| `WAKE_DELIVERY_MAX_ATTEMPTS` | no | maximum wake delivery attempts, default `5` |
+| `WAKE_DELIVERY_LEASE_MS` | no | claim lease duration, default `30000` |
+| `WAKE_RETRY_BASE_DELAY_MS` | no | first retry delay, default `1000` |
+| `WAKE_RETRY_MAX_DELAY_MS` | no | retry backoff cap, default `60000` |
+| `WAKE_RETRY_TICK_MS` | no | retry scheduler tick, default `1000` |
 
 Embedded hosts pass one MCP registry adapter. Event Intelligence discovers already-connected clients from that registry; provider MCP connection settings are not duplicated inside EI.
 
@@ -244,7 +349,7 @@ Absence/deadline progression uses Event Intelligence processing time. This separ
 
 The implementation does not claim theoretical distributed exactly-once delivery.
 
-It uses stable wake IDs, persistence, deduplication, runtime receipts and replay handling to provide effectively-once runtime activation in the validated reference scenarios.
+It uses stable wake IDs, persisted delivery state, atomic claim leases, bounded retries, runtime receipts and replay handling to provide effectively-once runtime activation in the validated reference scenarios.
 
 ### Derived event vs current state
 
@@ -256,7 +361,7 @@ v0.1 intentionally does not implement a mutable current-state/facts database.
 
 Read [SECURITY.md](SECURITY.md) and [docs/SECURITY-MODEL.md](docs/SECURITY-MODEL.md).
 
-In embedded mode, the host retains MCP authorization and credentials; Event Intelligence discovers only the client objects exposed through the host-provided MCP registry. The v0.1 reference store is JSONL and single-writer.
+In embedded mode, the host retains MCP authorization and credentials; Event Intelligence discovers only the client objects exposed through the host-provided MCP registry. Tenant-facing callers should receive only `host.scope(scopeId)`. The reference JSONL store is scope-partitioned and single-process; distributed custom stores must preserve scope isolation and atomic wake claims.
 
 ## MCP compatibility status
 
@@ -277,7 +382,7 @@ io.github.sarooo17/event-intelligence
 
 **v0.1 reference implementation / experimental.**
 
-The architecture is implemented and exercised end-to-end. Remaining work is primarily production storage/HA, broader host/provider evidence, scale benchmarks and upstream feedback.
+The architecture is implemented and exercised end-to-end. Storage is now injectable and scoped, while the bundled JSONL backend remains a single-process reference implementation. Remaining work is primarily production database adapters/HA validation, scale benchmarks and upstream feedback.
 
 ## Example
 

package/bin/mcp-event-intelligence.mjs

@@ -4,7 +4,7 @@ const args = process.argv.slice(2);
 const flags = new Set(args);
 
 if (flags.has('--version') || flags.has('-v')) {
-  console.log('0.1.0');
+  console.log('0.2.0');
   process.exit(0);
 }
 
@@ -39,6 +39,10 @@ Embedded hosts:
   import { createEventIntelligenceHost } from 'mcp-event-intelligence/host'
   Pass the harness MCP registry once; EI discovers Events-capable clients automatically.
 
+Provider runtimes:
+  import { createMcpEventsProvider } from 'mcp-event-intelligence/provider'
+  Keep domain events, auth, data access and opaque cursors provider-owned.
+
 Important:
   stdout is reserved for MCP JSON-RPC in stdio mode.
 `);

package/dist/src/composite/derivedGraph.d.ts

@@ -0,0 +1,4 @@
+import type { CompositeTriggerDefinition } from '../intelligenceProtocol/triggerSchemas.js';
+export declare function assertNoDerivedEventCycle(existing: CompositeTriggerDefinition[], candidate: CompositeTriggerDefinition, getState?: (triggerId: string, version: string) => {
+    status: string;
+} | null): void;

package/dist/src/composite/derivedGraph.js

@@ -0,0 +1,46 @@
+const DERIVED_SERVER_ID = 'event-intelligence:derived';
+function eventNode(eventName, serverId) {
+    return `${serverId || DERIVED_SERVER_ID}::${eventName}`;
+}
+export function assertNoDerivedEventCycle(existing, candidate, getState) {
+    const definitions = [
+        ...existing.filter((definition) => {
+            const state = getState?.(definition.triggerId, definition.version);
+            return !state || state.status === 'active' || state.status === 'paused';
+        }),
+        candidate,
+    ].filter((definition) => definition.derivedEvent);
+    const graph = new Map();
+    for (const definition of definitions) {
+        const output = eventNode(definition.derivedEvent.name, DERIVED_SERVER_ID);
+        for (const clause of definition.clauses) {
+            const input = eventNode(clause.event, clause.serverId);
+            const edges = graph.get(input) ?? new Set();
+            edges.add(output);
+            graph.set(input, edges);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const dfs = (node) => {
+        if (visiting.has(node))
+            return true;
+        if (visited.has(node))
+            return false;
+        visiting.add(node);
+        for (const next of graph.get(node) ?? []) {
+            if (dfs(next))
+                return true;
+        }
+        visiting.delete(node);
+        visited.add(node);
+        return false;
+    };
+    for (const node of graph.keys()) {
+        if (dfs(node)) {
+            const error = new Error(`Derived event graph contains a cycle involving ${node}`);
+            error.code = 'TRIGGER_DERIVED_EVENT_CYCLE';
+            throw error;
+        }
+    }
+}

package/dist/src/composite/engine.d.ts

@@ -1,63 +1,7 @@
 import type { SemanticEvaluator } from '../semantic/types.js';
 import { type CompositeTriggerDefinition, type TriggerMatchRecord } from '../intelligenceProtocol/triggerSchemas.js';
-export interface CompositeTriggerStore {
-    putTrigger(definition: CompositeTriggerDefinition): Promise<void>;
-    listTriggers(): CompositeTriggerDefinition[];
-    getTriggerState?(triggerId: string, version: string): {
-        status: 'active' | 'paused' | 'completed' | 'expired' | 'deleted';
-        owner?: unknown;
-        connectionIds?: string[];
-        fireCount?: number;
-        lastFiredAt?: string | null;
-        revision?: number;
-    } | null;
-    setTriggerState?(triggerId: string, version: string, status: 'active' | 'paused' | 'completed' | 'expired' | 'deleted', actor?: unknown, metadata?: Record<string, unknown>): Promise<unknown>;
-    appendTriggerMatch(record: TriggerMatchRecord): Promise<void>;
-    listTriggerMatches(triggerId?: string): TriggerMatchRecord[];
-    getTemporalDeadline?(deadlineId: string): {
-        deadlineId: string;
-        triggerId: string;
-        triggerVersion: string;
-        matchId: string;
-        conditionId: string;
-        dueAt: string;
-        status: 'pending' | 'cancelled' | 'fired';
-    } | null;
-    listTemporalDeadlines?(filter?: {
-        triggerId?: string;
-        matchId?: string;
-        status?: string;
-    }): Array<{
-        deadlineId: string;
-        triggerId: string;
-        triggerVersion: string;
-        matchId: string;
-        conditionId: string;
-        dueAt: string;
-        status: string;
-    }>;
-    putTemporalDeadline?(input: {
-        deadlineId: string;
-        triggerId: string;
-        triggerVersion: string;
-        matchId: string;
-        conditionId: string;
-        dueAt: string;
-        status: 'pending' | 'cancelled' | 'fired';
-    }): Promise<unknown>;
-    setTemporalDeadlineStatus?(deadlineId: string, status: 'pending' | 'cancelled' | 'fired'): Promise<unknown>;
-}
-export interface CompositeTriggerAudit {
-    appendAudit(input: {
-        auditId: string;
-        traceId: string;
-        timestamp: string;
-        kind: string;
-        entityType: 'trigger_match' | 'trigger';
-        entityId: string;
-        details?: Record<string, unknown>;
-    }): Promise<unknown>;
-}
+import type { CompositeTriggerAudit, CompositeTriggerStore } from './store.js';
+export type { CompositeTriggerAudit, CompositeTriggerStore, } from './store.js';
 export interface CompositeIngestResult {
     triggerId: string;
     match: TriggerMatchRecord | null;
@@ -68,6 +12,7 @@ export declare class CompositeTriggerEngine {
     private readonly store;
     private readonly evaluator;
     private readonly now;
+    private readonly support;
     constructor(store: CompositeTriggerStore & CompositeTriggerAudit, evaluator?: SemanticEvaluator | null, now?: () => Date);
     register(definitionInput: unknown): Promise<CompositeTriggerDefinition>;
     ingest(eventInput: unknown): Promise<CompositeIngestResult[]>;
@@ -76,12 +21,6 @@ export declare class CompositeTriggerEngine {
     private ingestTimerEvent;
     private applyEvent;
     private finalizeEligible;
-    private scheduleDeadlines;
-    private cancelDeadlinesForMatch;
-    private advanceLifecycleAfterEffect;
-    private lifecycleAllows;
-    private auditTriggerLifecycle;
     private newMatch;
     private latestMatch;
-    private audit;
 }