@animalabs/agent-framework 0.1.0

package/src/mcpl/feature-set-manager.ts

@@ -0,0 +1,333 @@
+/**
+ * FeatureSetManager — Permission gate for MCPL feature sets.
+ *
+ * Manages per-server feature set state: which feature sets each server declares,
+ * which are enabled/disabled, and validates inbound messages against that state.
+ *
+ * Spec references: Section 6 (Feature Sets), Appendix A (Error Codes).
+ */
+
+import type {
+  McplCapabilities,
+  FeatureSetDeclaration,
+  FeatureSetsUpdateParams,
+  FeatureSetsChangedParams,
+} from './types.js';
+
+import {
+  FEATURE_SET_NOT_ENABLED,
+  UNKNOWN_FEATURE_SET,
+} from './errors.js';
+
+// ============================================================================
+// Error Class
+// ============================================================================
+
+/**
+ * Error thrown when a feature set validation fails.
+ * Carries the JSON-RPC error code and the offending feature set name.
+ */
+export class McplFeatureSetError extends Error {
+  constructor(
+    public readonly code: number,
+    public readonly featureSet: string,
+    message: string
+  ) {
+    super(message);
+    this.name = 'McplFeatureSetError';
+  }
+}
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+/** Per-server tracking state. */
+interface ServerState {
+  /** All declared feature sets (keyed by name). */
+  declared: Record<string, FeatureSetDeclaration>;
+  /** Set of currently enabled feature set names. */
+  enabled: Set<string>;
+}
+
+// ============================================================================
+// Wildcard Matching
+// ============================================================================
+
+/**
+ * Check whether a wildcard pattern matches a feature set name.
+ *
+ * Rules:
+ *   - Split both pattern and name on `.`
+ *   - `*` in a pattern segment matches exactly one segment (any value)
+ *   - Literal segments must match exactly
+ *   - Pattern and name must have the same number of segments
+ *     (unless the last pattern segment is `*`, which matches one segment)
+ *
+ * Examples:
+ *   `memory.*` matches `memory.retrieval` but not `memory.a.b`
+ *   `memory.retrieval` matches only `memory.retrieval`
+ */
+function wildcardMatch(pattern: string, name: string): boolean {
+  const patternParts = pattern.split('.');
+  const nameParts = name.split('.');
+
+  if (patternParts.length !== nameParts.length) {
+    return false;
+  }
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const p = patternParts[i];
+    if (p === '*') {
+      // Wildcard segment matches any single segment
+      continue;
+    }
+    if (p !== nameParts[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Find all declared feature set names that match any of the given patterns.
+ * Patterns may contain wildcards (e.g., `memory.*`).
+ */
+function resolvePatterns(
+  patterns: string[],
+  declared: Record<string, FeatureSetDeclaration>
+): string[] {
+  const matched = new Set<string>();
+  const declaredNames = Object.keys(declared);
+
+  for (const pattern of patterns) {
+    for (const name of declaredNames) {
+      if (wildcardMatch(pattern, name)) {
+        matched.add(name);
+      }
+    }
+  }
+
+  return [...matched];
+}
+
+// ============================================================================
+// FeatureSetManager
+// ============================================================================
+
+/**
+ * Manages feature set state across all MCPL servers.
+ *
+ * This is the permission gate that all MCPL interactions pass through.
+ * Every inbound server message tagged with a `featureSet` must be validated
+ * through this manager before processing.
+ */
+export class FeatureSetManager {
+  /** Per-server state, keyed by server ID. */
+  private servers = new Map<string, ServerState>();
+
+  /**
+   * Initialize a server's feature set state from its capabilities and host config.
+   *
+   * Called after a server connects and advertises its capabilities.
+   * Returns the `FeatureSetsUpdateParams` that should be sent to the server
+   * via `featureSets/update`.
+   *
+   * Initialization logic:
+   * 1. Store all declared feature sets from capabilities.
+   * 2. If `config.enabledFeatureSets` is provided, enable matching sets (supports wildcards).
+   * 3. If `config.disabledFeatureSets` is provided, disable matching sets (supports wildcards).
+   * 4. Feature sets not mentioned in either list default to disabled.
+   */
+  initializeServer(
+    serverId: string,
+    capabilities: McplCapabilities,
+    config?: { enabledFeatureSets?: string[]; disabledFeatureSets?: string[] }
+  ): FeatureSetsUpdateParams {
+    const declared = capabilities.featureSets ?? {};
+
+    const state: ServerState = {
+      declared: { ...declared },
+      enabled: new Set<string>(),
+    };
+
+    // Resolve which feature sets to enable
+    const enablePatterns = config?.enabledFeatureSets ?? [];
+    const disablePatterns = config?.disabledFeatureSets ?? [];
+
+    const toEnable = resolvePatterns(enablePatterns, declared);
+    const toDisable = resolvePatterns(disablePatterns, declared);
+
+    // Enable matching sets
+    for (const name of toEnable) {
+      state.enabled.add(name);
+    }
+
+    // Disable explicitly overrides enable (disable wins on conflict)
+    for (const name of toDisable) {
+      state.enabled.delete(name);
+    }
+
+    this.servers.set(serverId, state);
+
+    // Build the update params to send to the server
+    const enabled = [...state.enabled];
+    const allDeclared = Object.keys(declared);
+    const disabled = allDeclared.filter((n) => !state.enabled.has(n));
+
+    const params: FeatureSetsUpdateParams = {};
+    if (enabled.length > 0) {
+      params.enabled = enabled;
+    }
+    if (disabled.length > 0) {
+      params.disabled = disabled;
+    }
+
+    return params;
+  }
+
+  /**
+   * Remove all tracking state for a server.
+   * Called when a server disconnects.
+   */
+  removeServer(serverId: string): void {
+    this.servers.delete(serverId);
+  }
+
+  /**
+   * Check whether a feature set is enabled for a server.
+   * Returns false if the server is unknown or the feature set is not enabled.
+   */
+  isEnabled(serverId: string, featureSet: string): boolean {
+    const state = this.servers.get(serverId);
+    if (!state) {
+      return false;
+    }
+    return state.enabled.has(featureSet);
+  }
+
+  /**
+   * Validate that an inbound message's feature set is declared and enabled.
+   *
+   * @throws McplFeatureSetError with code -32003 if the feature set is unknown
+   * @throws McplFeatureSetError with code -32001 if the feature set is not enabled
+   */
+  validateInbound(serverId: string, featureSet: string): void {
+    const state = this.servers.get(serverId);
+
+    if (!state) {
+      throw new McplFeatureSetError(
+        UNKNOWN_FEATURE_SET,
+        featureSet,
+        `Unknown server: ${serverId}`
+      );
+    }
+
+    if (!(featureSet in state.declared)) {
+      throw new McplFeatureSetError(
+        UNKNOWN_FEATURE_SET,
+        featureSet,
+        `Unknown feature set: ${featureSet}`
+      );
+    }
+
+    if (!state.enabled.has(featureSet)) {
+      throw new McplFeatureSetError(
+        FEATURE_SET_NOT_ENABLED,
+        featureSet,
+        `Feature set not enabled: ${featureSet}`
+      );
+    }
+  }
+
+  /**
+   * Enable feature sets for a server (supports wildcard patterns).
+   * Only declared feature sets can be enabled.
+   */
+  enable(serverId: string, featureSets: string[]): void {
+    const state = this.servers.get(serverId);
+    if (!state) {
+      return;
+    }
+
+    const resolved = resolvePatterns(featureSets, state.declared);
+    for (const name of resolved) {
+      state.enabled.add(name);
+    }
+  }
+
+  /**
+   * Disable feature sets for a server (supports wildcard patterns).
+   * Only declared feature sets can be disabled.
+   */
+  disable(serverId: string, featureSets: string[]): void {
+    const state = this.servers.get(serverId);
+    if (!state) {
+      return;
+    }
+
+    const resolved = resolvePatterns(featureSets, state.declared);
+    for (const name of resolved) {
+      state.enabled.delete(name);
+    }
+  }
+
+  /**
+   * Handle a `featureSets/changed` notification from a server.
+   *
+   * - Adds new feature sets from `params.added` (default to disabled).
+   * - Removes feature sets listed in `params.removed`.
+   */
+  handleFeatureSetsChanged(
+    serverId: string,
+    params: FeatureSetsChangedParams
+  ): void {
+    const state = this.servers.get(serverId);
+    if (!state) {
+      return;
+    }
+
+    // Add new feature sets (default to disabled)
+    if (params.added) {
+      for (const [name, declaration] of Object.entries(params.added)) {
+        state.declared[name] = declaration;
+        // New feature sets default to disabled — do not add to enabled set
+      }
+    }
+
+    // Remove feature sets
+    if (params.removed) {
+      for (const name of params.removed) {
+        delete state.declared[name];
+        state.enabled.delete(name);
+      }
+    }
+  }
+
+  /**
+   * Get all declared feature sets for a server.
+   * Returns null if the server is unknown.
+   */
+  getDeclaredFeatureSets(
+    serverId: string
+  ): Record<string, FeatureSetDeclaration> | null {
+    const state = this.servers.get(serverId);
+    if (!state) {
+      return null;
+    }
+    return { ...state.declared };
+  }
+
+  /**
+   * Get the names of all enabled feature sets for a server.
+   * Returns an empty array if the server is unknown.
+   */
+  getEnabledFeatureSets(serverId: string): string[] {
+    const state = this.servers.get(serverId);
+    if (!state) {
+      return [];
+    }
+    return [...state.enabled];
+  }
+}

package/src/mcpl/hook-orchestrator.ts

@@ -0,0 +1,281 @@
+/**
+ * HookOrchestrator — manages before/after inference fan-out to MCPL servers.
+ *
+ * This is the bridge between the MCPL protocol and the agent-framework inference
+ * pipeline. It collects ContextInjection[] from MCPL servers via beforeInference
+ * and feeds them into context-manager's compile(). After inference, it notifies
+ * servers of the result via afterInference.
+ *
+ * Design principles:
+ * - Fail-open: timeouts and errors never block inference
+ * - Parallel fan-out with per-server timeouts
+ * - Loop prevention: rejects inference/request while inside a hook
+ */
+
+import type { ContentBlock } from '@animalabs/membrane';
+import type { ContextInjection } from '@animalabs/context-manager';
+
+import type {
+  McplContentBlock,
+  McplContextInjection,
+  BeforeInferenceParams,
+  BeforeInferenceResult,
+  AfterInferenceParams,
+  AfterInferenceResult,
+} from './types.js';
+import type { McplServerRegistry } from './server-registry.js';
+import type { McplServerConnection } from './server-connection.js';
+import type { FeatureSetManager } from './feature-set-manager.js';
+
+/** Timeout for beforeInference per server (fail-open). */
+const BEFORE_INFERENCE_TIMEOUT_MS = 5_000;
+
+/** Timeout for blocking afterInference per server. */
+const AFTER_INFERENCE_BLOCKING_TIMEOUT_MS = 10_000;
+
+/**
+ * Races a promise against a timeout. Rejects with a descriptive error on timeout.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_resolve, reject) =>
+      setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms),
+    ),
+  ]);
+}
+
+// ============================================================================
+// Content conversion: McplContentBlock / McplContextInjection → membrane types
+// ============================================================================
+
+/**
+ * Convert a single MCPL wire-format content block to a membrane ContentBlock.
+ */
+function convertBlock(block: McplContentBlock): ContentBlock {
+  switch (block.type) {
+    case 'text':
+      return { type: 'text', text: block.text };
+
+    case 'image':
+      if (block.data && block.mimeType) {
+        return {
+          type: 'image',
+          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
+        };
+      }
+      if (block.uri) {
+        return {
+          type: 'image',
+          source: { type: 'url', url: block.uri },
+        };
+      }
+      // Malformed image block — degrade to text
+      return { type: 'text', text: '[Image: missing data]' };
+
+    case 'audio':
+      if (block.data && block.mimeType) {
+        return {
+          type: 'audio',
+          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
+        };
+      }
+      // Audio without inline data — degrade to text
+      return { type: 'text', text: `[Audio: ${block.uri ?? 'missing data'}]` };
+
+    case 'resource':
+      // Resources don't have a direct membrane equivalent — degrade to text
+      return { type: 'text', text: `[Resource: ${block.uri}]` };
+  }
+}
+
+/**
+ * Convert MCPL injection content (string shorthand or block array) to membrane ContentBlock[].
+ */
+function convertContent(content: string | McplContentBlock[]): ContentBlock[] {
+  if (typeof content === 'string') {
+    return [{ type: 'text', text: content }];
+  }
+  return content.map(convertBlock);
+}
+
+/**
+ * Convert an MCPL wire-format context injection to a context-manager ContextInjection.
+ */
+function convertMcplInjection(mcplInj: McplContextInjection): ContextInjection {
+  return {
+    namespace: mcplInj.namespace,
+    position: mcplInj.position,
+    content: convertContent(mcplInj.content),
+    metadata: mcplInj.metadata,
+  };
+}
+
+// ============================================================================
+// HookOrchestrator
+// ============================================================================
+
+export class HookOrchestrator {
+  private registry: McplServerRegistry;
+  private featureSetManager: FeatureSetManager;
+  private _isInHook = false;
+
+  constructor(registry: McplServerRegistry, featureSetManager: FeatureSetManager) {
+    this.registry = registry;
+    this.featureSetManager = featureSetManager;
+  }
+
+  /**
+   * Whether a hook is currently executing.
+   * Used for loop prevention: inference/request from servers should be rejected
+   * while this is true (enforced by Step 6's InferenceRouter).
+   */
+  get isInHook(): boolean {
+    return this._isInHook;
+  }
+
+  /**
+   * Fan out `context/beforeInference` to all capable MCPL servers in parallel.
+   *
+   * Returns aggregated ContextInjection[] ready for context-manager's compile().
+   * Fail-open: servers that time out or error are silently skipped.
+   */
+  async beforeInference(params: BeforeInferenceParams): Promise<ContextInjection[]> {
+    const servers = this.registry.getServersWithCapability('contextHooks.beforeInference');
+    if (servers.length === 0) {
+      return [];
+    }
+
+    this._isInHook = true;
+    try {
+      return await this.fanOutBeforeInference(servers, params);
+    } finally {
+      this._isInHook = false;
+    }
+  }
+
+  /**
+   * Fan out `context/afterInference` to all capable MCPL servers.
+   *
+   * Non-blocking servers receive a notification (fire-and-forget).
+   * Blocking servers receive a request with a 10s timeout.
+   * Returns the first valid AfterInferenceResult from a blocking server, or null.
+   */
+  async afterInference(params: AfterInferenceParams): Promise<AfterInferenceResult | null> {
+    const servers = this.registry.getServersWithCapability('contextHooks.afterInference');
+    if (servers.length === 0) {
+      return null;
+    }
+
+    this._isInHook = true;
+    try {
+      return await this.fanOutAfterInference(servers, params);
+    } finally {
+      this._isInHook = false;
+    }
+  }
+
+  // ==========================================================================
+  // Private: beforeInference fan-out
+  // ==========================================================================
+
+  private async fanOutBeforeInference(
+    servers: McplServerConnection[],
+    params: BeforeInferenceParams,
+  ): Promise<ContextInjection[]> {
+    const results = await Promise.allSettled(
+      servers.map((server) =>
+        withTimeout(
+          server.sendBeforeInference(params),
+          BEFORE_INFERENCE_TIMEOUT_MS,
+          `beforeInference to "${server.id}"`,
+        ).then((result) => ({ server, result })),
+      ),
+    );
+
+    const injections: ContextInjection[] = [];
+
+    for (const settled of results) {
+      if (settled.status === 'rejected') {
+        // Fail-open: timeout or transport error — skip this server
+        continue;
+      }
+
+      const { server, result } = settled.value;
+
+      // Validate feature set
+      try {
+        this.featureSetManager.validateInbound(server.id, result.featureSet);
+      } catch {
+        // Feature set not enabled or unknown — skip injections from this server
+        continue;
+      }
+
+      // Convert wire-format injections to context-manager format
+      if (result.contextInjections && result.contextInjections.length > 0) {
+        for (const mcplInj of result.contextInjections) {
+          injections.push(convertMcplInjection(mcplInj));
+        }
+      }
+    }
+
+    return injections;
+  }
+
+  // ==========================================================================
+  // Private: afterInference fan-out
+  // ==========================================================================
+
+  private async fanOutAfterInference(
+    servers: McplServerConnection[],
+    params: AfterInferenceParams,
+  ): Promise<AfterInferenceResult | null> {
+    const blockingPromises: Promise<AfterInferenceResult | null>[] = [];
+
+    for (const server of servers) {
+      const isBlocking = this.isBlockingAfterInference(server);
+
+      if (isBlocking) {
+        // Send as request, await response with timeout
+        const promise = withTimeout(
+          server.sendAfterInference(params, true) as Promise<AfterInferenceResult>,
+          AFTER_INFERENCE_BLOCKING_TIMEOUT_MS,
+          `afterInference (blocking) to "${server.id}"`,
+        ).catch((): null => {
+          // Fail-open: timeout or error — treat as no modification
+          return null;
+        });
+        blockingPromises.push(promise);
+      } else {
+        // Send as notification (fire-and-forget)
+        server.sendAfterInference(params, false);
+      }
+    }
+
+    if (blockingPromises.length === 0) {
+      return null;
+    }
+
+    // Await all blocking responses and return the first valid result
+    const results = await Promise.all(blockingPromises);
+    for (const result of results) {
+      if (result && result.modifiedResponse) {
+        return result;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if a server's afterInference capability is blocking.
+   */
+  private isBlockingAfterInference(server: McplServerConnection): boolean {
+    const caps = server.capabilities;
+    if (!caps?.contextHooks?.afterInference) {
+      return false;
+    }
+    const afterCap = caps.contextHooks.afterInference;
+    return typeof afterCap === 'object' && afterCap !== null && 'blocking' in afterCap && afterCap.blocking === true;
+  }
+}