mcp-event-intelligence 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.8.0] - 2026-10-05
+
+### Embedded runtime integration
+
+- add `createEmbeddedRuntimeIntegration()` above the lower-level host kit;
+- add a runtime-neutral `EventSourceRegistry` over host-owned event connections;
+- add portable EI capability metadata and a neutral tool catalog for host-owned exposure;
+- add host-owned result projection with optional runtime result references;
+- replace boolean authorization in the new integration surface with a host control contract that can execute or return an opaque deny/approval/interrupt/defer result;
+- preserve native host interrupt/suspension exceptions instead of normalizing them into EI errors;
+- keep tooling optional so headless/workflow runtimes can embed EI without exposing agent tools;
+- document and test the invariant that EI core contains no named-runtime dispatch or per-runtime adapter matrix.
+
+## [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.

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.7.0-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.8.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.
@@ -31,53 +31,92 @@ 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:
+For most runtimes, start with the runtime-neutral integration surface:
 
 ```js
 import {
-  createEmbeddedEventIntelligence,
+  createEmbeddedRuntimeIntegration,
+  createEventSourceRegistry,
 } from 'mcp-event-intelligence/embedded';
 
-const ei = await createEmbeddedEventIntelligence({
+const ei = await createEmbeddedRuntimeIntegration({
   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),
-  },
+  // The host owns transports, auth and connection lifecycle.
+  eventSources: createEventSourceRegistry({
+    list: () => runtime.events.connections(),
+    subscribe: (refresh) => runtime.events.onConnectionsChanged(refresh),
+  }),
 
-  // EI produces an activation; the host decides how its own work resumes.
+  // EI emits an activation. The host decides what "resume" means.
   activation: {
     resolveTarget: (target) => runtime.resolveContinuation(target),
     hasReceipt: (receiptId) => runtime.hasWakeReceipt(receiptId),
     deliver: ({ activation, target, receiptId }) =>
       runtime.resumeFromEvent({ activation, target, receiptId }),
   },
+
+  // Optional. Runtimes without an agent-tool surface can omit tooling entirely.
+  tooling: {
+    resolveContext: (ctx) => ({
+      target: runtime.currentContinuation(ctx),
+      actor: runtime.currentActor(ctx),
+      owner: runtime.currentOwner(ctx),
+    }),
+
+    // Host-owned control. EI does not reduce authorization/approval/interrupt
+    // semantics to a boolean.
+    control: (request) => runtime.policy.control(request),
+
+    // Optional host-owned result projection. Large results may be externalized
+    // behind a runtime-specific reference instead of entering model context.
+    projectResult: (request) => runtime.results.project(request),
+  },
 });
 ```
 
 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:
+The returned tools are neutral descriptors with EI-neutral capability metadata:
 
 ```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),
-});
+for (const tool of ei.toolCatalog.all) {
+  // The host translates this descriptor into its own tool/capability system.
+  runtime.tools.register(tool);
+}
 ```
 
-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.
+EI intentionally ships **no per-runtime adapter matrix** such as
+`toOpenAI()`, `toAnthropic()`, `toMuffin()` or `toArtemis()`.
+There are too many runtimes, and adding one runtime must never require changing
+EI core. The host consumes the same neutral contract and performs the final
+translation at its own boundary.
+
+Tool exposure is also host-owned. `toolCatalog.list({ capabilityIds })` can
+project only the capabilities the host has decided to expose. EI supplies
+metadata such as read vs durable mutation; it does not decide the host's RBAC,
+risk tiers, approval flow or interrupt UX.
+
+For durable mutations, `tooling.control()` returns either:
+
+- `{ action: 'execute', execution?: ... }` — proceed, optionally attaching
+  host policy/approval provenance; or
+- `{ action: 'return', result: ... }` — stop and return an opaque host-owned
+  outcome. That outcome may mean denied, approval required, interrupted,
+  deferred, or anything else the host runtime supports.
+
+EI never interprets the second case. This keeps authorization, human approval
+and interrupt semantics entirely outside the event engine.
+
+Result handling follows the same boundary. `projectResult()` may keep a small
+value inline or replace it with a host-owned reference. EI does not become a
+blob store, artifact system or model-context manager.
+
+The package contains no named-runtime dispatch such as
+`if (runtime === "muffin")`, `"artemis"`, `"openai"` or `"anthropic"`.
+A new runtime should require only host-boundary code outside EI core.
 
 The lower-level host API remains available when a runtime needs direct control:
 

package/bin/mcp-event-intelligence.mjs

@@ -1,15 +1,22 @@
 #!/usr/bin/env node
 
+import { readFileSync } from 'node:fs';
+
+const packageJson = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+);
+const packageVersion = String(packageJson.version || '').trim();
+
 const args = process.argv.slice(2);
 const flags = new Set(args);
 
 if (flags.has('--version') || flags.has('-v')) {
-  console.log('0.6.1');
+  console.log(packageVersion);
   process.exit(0);
 }
 
 if (flags.has('--help') || flags.has('-h')) {
-  console.log(`MCP Event Intelligence v0.6.1
+  console.log(`MCP Event Intelligence v${packageVersion}
 
 MCP-native complex event processing for durable agents.
 
@@ -53,4 +60,4 @@ if (args[0] === 'mcp' || flags.has('--mcp')) {
   await import('../scripts/mcp-stdio.mjs');
 } else {
   await import('../scripts/service.mjs');
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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",

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

@@ -7,6 +7,7 @@ export type {
   ActivationEnvelope as EventActivation,
   RuntimeTarget as ContinuationTarget,
 };
+
 import type {
   EventIntelligenceHost,
   EventIntelligenceHostOptions,
@@ -25,31 +26,58 @@ export interface EmbeddedHostIdentity {
 export interface EmbeddedToolContext {
   scopeId?: string;
   target: RuntimeTarget;
-  actor: EmbeddedHostIdentity;
-  owner: EmbeddedHostIdentity;
+  actor?: EmbeddedHostIdentity;
+  owner?: EmbeddedHostIdentity;
   confirmationId?: string;
   [key: string]: unknown;
 }
 
+export interface EventIntelligenceCapabilityMetadata {
+  id: string;
+  operation: 'read' | 'create' | 'update' | 'delete' | string;
+  resource: string;
+  effect: 'none' | 'durable-state' | string;
+  durability: 'ephemeral' | 'durable' | string;
+  hostControl: 'none' | 'required' | string;
+}
+
+export interface PortableResultReference {
+  id: string;
+  kind?: string;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface PortableProjectedResult {
+  inline?: unknown;
+  reference?: PortableResultReference;
+  summary?: string;
+  metadata?: Record<string, unknown>;
+}
+
 export interface PortableToolResult {
   ok: boolean;
   data?: any;
+  result?: PortableProjectedResult;
   error?: {
     code: string;
     message: string;
   };
+  [key: string]: unknown;
 }
 
 export interface PortableAgentTool<RuntimeContext = unknown> {
   name: string;
   description: string;
   inputSchema: Record<string, unknown>;
+  capability: EventIntelligenceCapabilityMetadata;
   execute(
     args: unknown,
     runtimeContext: RuntimeContext,
   ): Promise<PortableToolResult>;
 }
 
+/** @deprecated Prefer the host-owned control() contract. */
 export interface AuthorizationDecision {
   allowed: boolean;
   code?: string;
@@ -59,6 +87,33 @@ export interface AuthorizationDecision {
   confirmationId?: string;
 }
 
+export interface HostControlExecuteDecision {
+  action: 'execute';
+  execution?: {
+    actor?: EmbeddedHostIdentity;
+    owner?: EmbeddedHostIdentity;
+    /** Host policy/approval receipt persisted by EI as confirmation provenance. */
+    receiptId?: string;
+    /** Legacy alias accepted for compatibility. */
+    confirmationId?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface HostControlReturnDecision {
+  action: 'return';
+  /**
+   * Opaque host-owned outcome. It may represent deny, approval required,
+   * interruption, deferral or another runtime-specific control path.
+   * EI does not interpret the reason.
+   */
+  result: PortableToolResult;
+}
+
+export type HostControlDecision =
+  | HostControlExecuteDecision
+  | HostControlReturnDecision;
+
 export interface ActivationDeliveryInput<Target = unknown> {
   packet: Record<string, unknown>;
   activation: ActivationEnvelope;
@@ -84,16 +139,69 @@ export interface ActivationDispatcherOptions<Target = RuntimeTarget> {
   ): HostWakeReceipt | string | void | Promise<HostWakeReceipt | string | void>;
 }
 
+export type EventSourceConnection = HostMcpConnectionOptions;
+
+export interface EventSourceRegistry {
+  list(): Iterable<EventSourceConnection> | Promise<Iterable<EventSourceConnection>>;
+  subscribe?: (listener: () => void) => void | (() => void);
+}
+
+export interface EventSourceRegistryOptions {
+  list(): Iterable<EventSourceConnection> | Promise<Iterable<EventSourceConnection>>;
+  subscribe?: (listener: () => void) => void | (() => void);
+}
+
+export interface PortableToolCatalog<RuntimeContext = unknown> {
+  readonly all: readonly PortableAgentTool<RuntimeContext>[];
+  get(name: string): PortableAgentTool<RuntimeContext> | null;
+  list(options?: {
+    capabilityIds?: Iterable<string>;
+  }): PortableAgentTool<RuntimeContext>[];
+  capabilities(): EventIntelligenceCapabilityMetadata[];
+}
+
 export interface EventIntelligenceAgentToolsOptions<RuntimeContext = unknown> {
   host: EventIntelligenceHost;
   resolveContext(
     runtimeContext: RuntimeContext,
     request: {
       action: 'event.sources.list' | 'trigger.create';
+      capability: EventIntelligenceCapabilityMetadata;
       input?: unknown;
     },
   ): EmbeddedToolContext | Promise<EmbeddedToolContext>;
-  authorize(input: {
+
+  /**
+   * Host-owned control gate for durable mutations.
+   *
+   * Return action:'execute' to allow EI to perform the mutation, or
+   * action:'return' with a fully host-owned PortableToolResult to represent
+   * deny/interrupt/approval/defer semantics without EI interpreting them.
+   */
+  control?(input: {
+    capability: EventIntelligenceCapabilityMetadata;
+    action: 'trigger.create';
+    runtimeContext: RuntimeContext;
+    context: EmbeddedToolContext;
+    input: unknown;
+    plan: any;
+  }): HostControlDecision | Promise<HostControlDecision>;
+
+  /**
+   * Host-owned result projection. Use it to inline, summarize or externalize
+   * large results behind a runtime-specific reference.
+   */
+  projectResult?(input: {
+    capability: EventIntelligenceCapabilityMetadata;
+    runtimeContext: RuntimeContext;
+    context: EmbeddedToolContext;
+    value: unknown;
+  }): PortableProjectedResult | void | Promise<PortableProjectedResult | void>;
+
+  /**
+   * @deprecated Compatibility only. New integrations should use control().
+   */
+  authorize?(input: {
     action: 'trigger.create';
     runtimeContext: RuntimeContext;
     context: EmbeddedToolContext;
@@ -103,6 +211,7 @@ export interface EventIntelligenceAgentToolsOptions<RuntimeContext = unknown> {
     | boolean
     | AuthorizationDecision
     | Promise<boolean | AuthorizationDecision>;
+
   names?: {
     sources?: string;
     create?: string;
@@ -136,6 +245,45 @@ export interface EmbeddedEventIntelligence<RuntimeContext = unknown> {
   close(): Promise<void>;
 }
 
+export interface EmbeddedRuntimeTooling<RuntimeContext = unknown> {
+  resolveContext: EventIntelligenceAgentToolsOptions<RuntimeContext>['resolveContext'];
+  control: NonNullable<EventIntelligenceAgentToolsOptions<RuntimeContext>['control']>;
+  projectResult?: EventIntelligenceAgentToolsOptions<RuntimeContext>['projectResult'];
+  names?: {
+    sources?: string;
+    create?: string;
+  };
+}
+
+export interface EmbeddedRuntimeIntegrationOptions<RuntimeContext = unknown>
+  extends Omit<
+    EmbeddedEventIntelligenceOptions<RuntimeContext>,
+    'mcpRegistry' | 'mcp' | 'agentTools'
+  > {
+  eventSources?: EventSourceRegistry | EventSourceRegistryOptions;
+  tooling?: EmbeddedRuntimeTooling<RuntimeContext>;
+}
+
+export interface EmbeddedRuntimeIntegration<RuntimeContext = unknown>
+  extends Omit<EmbeddedEventIntelligence<RuntimeContext>, 'tools'> {
+  readonly tools: readonly PortableAgentTool<RuntimeContext>[];
+  readonly toolCatalog: PortableToolCatalog<RuntimeContext>;
+  readonly capabilities: readonly EventIntelligenceCapabilityMetadata[];
+  readonly eventSources: EventSourceRegistry | null;
+}
+
+export function createResultReference(
+  input: PortableResultReference,
+): PortableResultReference;
+
+export function createEventSourceRegistry(
+  options: EventSourceRegistryOptions,
+): EventSourceRegistry;
+
+export function createPortableToolCatalog<RuntimeContext = unknown>(
+  tools?: PortableAgentTool<RuntimeContext>[],
+): PortableToolCatalog<RuntimeContext>;
+
 export function createContinuationTarget(input: {
   runtime: string;
   kind: string;
@@ -154,6 +302,15 @@ export function createEmbeddedEventIntelligence<RuntimeContext = unknown>(
   options?: EmbeddedEventIntelligenceOptions<RuntimeContext>,
 ): Promise<EmbeddedEventIntelligence<RuntimeContext>>;
 
+export function createEmbeddedRuntimeIntegration<RuntimeContext = unknown>(
+  options: EmbeddedRuntimeIntegrationOptions<RuntimeContext>,
+): Promise<EmbeddedRuntimeIntegration<RuntimeContext>>;
+
+export const EVENT_INTELLIGENCE_CAPABILITIES: Readonly<{
+  eventSourcesList: Readonly<EventIntelligenceCapabilityMetadata>;
+  triggerCreate: Readonly<EventIntelligenceCapabilityMetadata>;
+}>;
+
 export const PORTABLE_EVENT_INTELLIGENCE_TOOL_NAMES: Readonly<{
   sources: 'event_sources_list';
   create: 'trigger_create';

package/scripts/embedded-host-kit.mjs

@@ -13,6 +13,25 @@ const DEFAULT_TOOL_NAMES = Object.freeze({
   create: 'trigger_create',
 });
 
+export const EVENT_INTELLIGENCE_CAPABILITIES = Object.freeze({
+  eventSourcesList: Object.freeze({
+    id: 'event-intelligence.event-sources.list',
+    operation: 'read',
+    resource: 'event-source',
+    effect: 'none',
+    durability: 'ephemeral',
+    hostControl: 'none',
+  }),
+  triggerCreate: Object.freeze({
+    id: 'event-intelligence.trigger.create',
+    operation: 'create',
+    resource: 'trigger',
+    effect: 'durable-state',
+    durability: 'durable',
+    hostControl: 'required',
+  }),
+});
+
 const TriggerClauseInput = z.object({
   id: z.string().min(1).max(200).optional(),
   event: z.string().min(1).max(200),
@@ -140,15 +159,121 @@ function normalizeIdentity(input, label) {
   };
 }
 
-function normalizeAuthorization(decision) {
-  if (decision === true) return { allowed: true };
-  if (decision === false || decision == null) return { allowed: false };
+function normalizeLegacyAuthorization(decision) {
+  if (decision === true) return { action: 'execute' };
+  if (decision === false || decision == null) {
+    return {
+      action: 'return',
+      result: {
+        ok: false,
+        error: {
+          code: 'EVENT_TRIGGER_AUTHORIZATION_DENIED',
+          message: 'Host denied durable trigger creation',
+        },
+      },
+    };
+  }
   if (typeof decision !== 'object') {
     throw new Error('authorize() must return boolean or an authorization decision');
   }
+  if (decision.allowed === true) {
+    return {
+      action: 'execute',
+      execution: {
+        actor: decision.actor,
+        owner: decision.owner,
+        receiptId: decision.confirmationId,
+      },
+    };
+  }
+  return {
+    action: 'return',
+    result: {
+      ok: false,
+      error: {
+        code: String(decision.code || 'EVENT_TRIGGER_AUTHORIZATION_DENIED'),
+        message: String(
+          decision.message || 'Host denied durable trigger creation',
+        ),
+      },
+    },
+  };
+}
+
+function normalizeHostControlDecision(decision) {
+  if (!decision || typeof decision !== 'object') {
+    throw new Error(
+      'Host control must return { action: "execute" } or { action: "return", result }',
+    );
+  }
+  if (decision.action === 'return') {
+    if (!decision.result || typeof decision.result.ok !== 'boolean') {
+      throw new Error('Host control return action requires a portable tool result');
+    }
+    return decision;
+  }
+  if (decision.action !== 'execute') {
+    throw new Error(
+      'Host control action must be "execute" or "return"',
+    );
+  }
+  return {
+    action: 'execute',
+    execution:
+      decision.execution && typeof decision.execution === 'object'
+        ? decision.execution
+        : {},
+  };
+}
+
+export function createResultReference(reference) {
+  if (reference == null) return undefined;
+  if (typeof reference !== 'object') {
+    throw new Error('result reference must be an object');
+  }
+  const id = String(reference.id || '').trim();
+  if (!id) throw new Error('result reference id is required');
+  return {
+    ...reference,
+    id,
+    ...(reference.kind == null
+      ? {}
+      : { kind: String(reference.kind).trim() || undefined }),
+  };
+}
+
+async function projectPortableResult(projectResult, input) {
+  if (typeof projectResult !== 'function') {
+    return { ok: true, data: input.value };
+  }
+
+  const projected = await projectResult(input);
+  if (projected == null) {
+    return { ok: true, data: input.value };
+  }
+  if (typeof projected !== 'object') {
+    throw new Error('projectResult() must return an object');
+  }
+
+  const reference = createResultReference(projected.reference);
+  const hasInline = Object.prototype.hasOwnProperty.call(projected, 'inline');
+  if (!hasInline && !reference) {
+    throw new Error('projectResult() must return inline and/or reference');
+  }
+
   return {
-    ...decision,
-    allowed: decision.allowed === true,
+    ok: true,
+    ...(hasInline ? { data: projected.inline } : {}),
+    result: {
+      ...(hasInline ? { inline: projected.inline } : {}),
+      ...(reference ? { reference } : {}),
+      ...(projected.summary == null
+        ? {}
+        : { summary: String(projected.summary) }),
+      ...(projected.metadata && typeof projected.metadata === 'object'
+        ? { metadata: projected.metadata }
+        : {}),
+    },
   };
 }
 
@@ -176,6 +301,53 @@ function wakeIdFromPacket(packet) {
   return typeof value === 'string' && value.trim() ? value : null;
 }
 
+/**
+ * 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.
+ */
+export function createEventSourceRegistry({
+  list,
+  subscribe,
+} = {}) {
+  if (typeof list !== 'function') {
+    throw new Error('Event source registry requires list()');
+  }
+  if (subscribe !== undefined && typeof subscribe !== 'function') {
+    throw new Error('Event source registry subscribe must be a function');
+  }
+
+  return Object.freeze({
+    list,
+    ...(subscribe ? { subscribe } : {}),
+  });
+}
+
+/**
+ * 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 createPortableToolCatalog(tools = []) {
+  const all = Object.freeze([...tools]);
+  const byName = new Map(all.map((tool) => [tool.name, tool]));
+
+  return Object.freeze({
+    all,
+    get(name) {
+      return byName.get(name) ?? null;
+    },
+    list({ capabilityIds } = {}) {
+      if (!capabilityIds) return [...all];
+      const allowed = new Set(capabilityIds);
+      return all.filter((tool) => allowed.has(tool.capability?.id));
+    },
+    capabilities() {
+      return all.map((tool) => tool.capability).filter(Boolean);
+    },
+  });
+}
+
 /**
  * A runtime-neutral continuation target. EI persists and returns this value
  * without assigning semantics to runtime/kind/id.
@@ -338,13 +510,14 @@ function buildPlanInput(parsed, target) {
 }
 
 /**
- * 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}.
+ * Portable agent-facing tools. The descriptors are runtime-neutral.
+ * The embedding host performs any final translation into its own tool system.
  */
 export function createEventIntelligenceAgentTools({
   host,
   resolveContext,
+  control,
+  projectResult,
   authorize,
   names = {},
 } = {}) {
@@ -354,8 +527,19 @@ export function createEventIntelligenceAgentTools({
   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');
+  if (control !== undefined && typeof control !== 'function') {
+    throw new Error('Agent tools control must be a function');
+  }
+  if (authorize !== undefined && typeof authorize !== 'function') {
+    throw new Error('Agent tools authorize must be a function');
+  }
+  if (!control && !authorize) {
+    throw new Error(
+      'Durable mutations require a host control() callback',
+    );
+  }
+  if (projectResult !== undefined && typeof projectResult !== 'function') {
+    throw new Error('Agent tools projectResult must be a function');
   }
 
   const toolNames = {
@@ -363,30 +547,40 @@ export function createEventIntelligenceAgentTools({
     ...names,
   };
 
+  const sourcesCapability =
+    EVENT_INTELLIGENCE_CAPABILITIES.eventSourcesList;
+  const createCapability =
+    EVENT_INTELLIGENCE_CAPABILITIES.triggerCreate;
+
   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.',
+        'List live future-event sources discovered from event 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,
+      capability: sourcesCapability,
       async execute(_args, runtimeContext) {
         try {
           const resolved = await resolveContext(runtimeContext, {
             action: 'event.sources.list',
+            capability: sourcesCapability,
           });
           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)
-                : [],
-            },
+          const value = {
+            sources: Array.isArray(sources)
+              ? sources.map(sourceSummary)
+              : [],
           };
+          return await projectPortableResult(projectResult, {
+            capability: sourcesCapability,
+            runtimeContext,
+            context: resolved,
+            value,
+          });
         } catch (error) {
           return fail(error, 'EVENT_SOURCES_LIST_FAILED');
         }
@@ -395,8 +589,9 @@ export function createEventIntelligenceAgentTools({
     {
       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.',
+        'Create a durable future condition. The host supplies continuation, control and identity context; Event Intelligence wakes the opaque continuation target only when the condition matches.',
       inputSchema: CREATE_INPUT_SCHEMA,
+      capability: createCapability,
       async execute(args, runtimeContext) {
         const parsed = TriggerCreateInput.safeParse(args ?? {});
         if (!parsed.success) {
@@ -411,53 +606,69 @@ export function createEventIntelligenceAgentTools({
           };
         }
 
+        let resolved;
+        let scoped;
+        let plan;
         try {
-          const resolved = await resolveContext(runtimeContext, {
+          resolved = await resolveContext(runtimeContext, {
             action: 'trigger.create',
+            capability: createCapability,
             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(
+          scoped = await scopedHostFor(host, resolved);
+          plan = await scoped.planTrigger(
             buildPlanInput(parsed.data, target),
           );
+        } catch (error) {
+          return fail(error, 'EVENT_TRIGGER_PLAN_FAILED');
+        }
 
-          const decision = normalizeAuthorization(
-            await authorize({
+        // Host control is intentionally outside EI's error-normalization
+        // boundary. A runtime may return an opaque result or throw its native
+        // interrupt/suspension signal; EI must not reinterpret that mechanism.
+        const rawDecision = control
+          ? await control({
+              capability: createCapability,
               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',
-                ),
-              },
-            };
-          }
+            })
+          : normalizeLegacyAuthorization(
+              await authorize({
+                action: 'trigger.create',
+                runtimeContext,
+                context: resolved,
+                input: parsed.data,
+                plan,
+              }),
+            );
+        const decision = normalizeHostControlDecision(rawDecision);
+
+        if (decision.action === 'return') {
+          return decision.result;
+        }
 
+        try {
+          const execution = decision.execution ?? {};
           const actor = normalizeIdentity(
-            decision.actor ?? resolved?.actor,
+            execution.actor ?? resolved?.actor,
             'actor',
           );
           const owner = normalizeIdentity(
-            decision.owner ?? resolved?.owner,
+            execution.owner ?? resolved?.owner,
             'owner',
           );
           const confirmationId = String(
-            decision.confirmationId ?? resolved?.confirmationId ?? '',
+            execution.receiptId ??
+              execution.confirmationId ??
+              resolved?.confirmationId ??
+              '',
           ).trim();
 
           const created = await scoped.triggerControl.createTrigger({
@@ -468,17 +679,21 @@ export function createEventIntelligenceAgentTools({
             ...(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 ?? [],
-            },
+          const value = {
+            receiptId: created.receiptId,
+            triggerId: created.definition?.triggerId,
+            version: created.definition?.version,
+            state: created.state,
+            connectionIds: plan.connectionIds,
+            warnings: plan.warnings ?? [],
           };
+
+          return await projectPortableResult(projectResult, {
+            capability: createCapability,
+            runtimeContext,
+            context: resolved,
+            value,
+          });
         } catch (error) {
           return fail(error, 'EVENT_TRIGGER_CREATE_FAILED');
         }
@@ -564,4 +779,91 @@ export async function createEmbeddedEventIntelligence({
   };
 }
 
-export const PORTABLE_EVENT_INTELLIGENCE_TOOL_NAMES = DEFAULT_TOOL_NAMES;
+
+/**
+ * Runtime-level composition over the lower-level embedded host kit.
+ *
+ * This is deliberately not an adapter for any named runtime. It returns
+ * neutral tool descriptors + capability metadata; the embedding host decides
+ * how those descriptors are exposed to its model/tool system.
+ */
+export async function createEmbeddedRuntimeIntegration({
+  dataDir,
+  store,
+  env = {},
+  eventSources,
+  mcpClients = [],
+  semanticEvaluator,
+  activation,
+  wake,
+  wakeHandlers = {},
+  tooling,
+  createHost = createEventIntelligenceHost,
+} = {}) {
+  if (tooling !== undefined && (!tooling || typeof tooling !== 'object')) {
+    throw new Error('tooling must be an object when provided');
+  }
+  if (tooling && typeof tooling.resolveContext !== 'function') {
+    throw new Error('tooling.resolveContext() is required');
+  }
+  if (tooling && typeof tooling.control !== 'function') {
+    throw new Error(
+      'tooling.control() is required for host-owned mutation control',
+    );
+  }
+  if (
+    tooling?.projectResult !== undefined &&
+    typeof tooling.projectResult !== 'function'
+  ) {
+    throw new Error('tooling.projectResult must be a function');
+  }
+
+  const sourceRegistry = eventSources
+    ? createEventSourceRegistry(eventSources)
+    : null;
+
+  const embedded = await createEmbeddedEventIntelligence({
+    dataDir,
+    store,
+    env,
+    ...(sourceRegistry
+      ? {
+          mcpRegistry: createMcpRegistryAdapter({
+            listConnections: () => sourceRegistry.list(),
+            ...(typeof sourceRegistry.subscribe === 'function'
+              ? { subscribe: (listener) => sourceRegistry.subscribe(listener) }
+              : {}),
+          }),
+        }
+      : {}),
+    mcpClients,
+    semanticEvaluator,
+    activation,
+    wake,
+    wakeHandlers,
+    createHost,
+  });
+
+  const tools = tooling
+    ? createEventIntelligenceAgentTools({
+        host: embedded.host,
+        resolveContext: tooling.resolveContext,
+        control: tooling.control,
+        ...(tooling.projectResult
+          ? { projectResult: tooling.projectResult }
+          : {}),
+        names: tooling.names ?? {},
+      })
+    : [];
+  const toolCatalog = createPortableToolCatalog(tools);
+
+  return Object.freeze({
+    ...embedded,
+    tools: toolCatalog.all,
+    toolCatalog,
+    capabilities: Object.freeze(toolCatalog.capabilities()),
+    eventSources: sourceRegistry,
+  });
+}
+
+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.7.0",
+  "version": "0.8.0",
   "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.7.0",
+      "version": "0.8.0",
       "transport": {
         "type": "stdio"
       },