@animalabs/agent-framework 0.8.0 → 0.9.0

package/src/mcpl/hook-orchestrator.ts

@@ -3,8 +3,9 @@
  *
  * 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.
+ * and feeds them into context-manager's compile(). Turn boundaries are announced
+ * via metadata-only `inference/lifecycle` notifications (§10.5) —
+ * context/afterInference and its modifiedResponse are removed in 0.5.0.
  *
  * Design principles:
  * - Fail-open: timeouts and errors never block inference
@@ -20,18 +21,24 @@ import type {
   McplContextInjection,
   BeforeInferenceParams,
   BeforeInferenceResult,
-  AfterInferenceParams,
-  AfterInferenceResult,
+  InferenceLifecycleParams,
 } 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';
+import { CapabilityGrant } from './capability-grant.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;
+/** The three injection positions and their §6.2 capability paths. Position
+ *  is the TYPED field on the injection — authorization never reads the
+ *  response's featureSet (§5.4). */
+const INJECT_LEAVES: ReadonlyArray<{ position: string; path: string }> = [
+  { position: 'system', path: 'contextHooks.beforeInference.inject.system' },
+  { position: 'beforeUser', path: 'contextHooks.beforeInference.inject.beforeUser' },
+  { position: 'afterUser', path: 'contextHooks.beforeInference.inject.afterUser' },
+];
 
 /**
  * Races a promise against a timeout. Rejects with a descriptive error on timeout.
@@ -141,7 +148,16 @@ export class HookOrchestrator {
    * Fail-open: servers that time out or error are silently skipped.
    */
   async beforeInference(params: BeforeInferenceParams): Promise<ContextInjection[]> {
-    const servers = this.registry.getServersWithCapability('contextHooks.beforeInference');
+    // §5.4: the GRANT decides fan-out, not the raw advertisement — which
+    // also fixes selection for the recursive §5.1 shape, where
+    // `beforeInference: {observe: true, …}` is an object, not `true`. A
+    // server granted any inject.* leaf but not observe is still CALLED
+    // (§10.1 — the hook is how injection happens) and receives
+    // `userMessage: null` instead of the user's text.
+    const servers = this.registry.getAllServers().filter((s) =>
+      CapabilityGrant.of(s).has('contextHooks.beforeInference.observe')
+      || INJECT_LEAVES.some((leaf) => CapabilityGrant.of(s).has(leaf.path)),
+    );
     if (servers.length === 0) {
       return [];
     }
@@ -155,23 +171,20 @@ export class HookOrchestrator {
   }
 
   /**
-   * 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.
+   * Fan out `inference/lifecycle` (§10.5) — the metadata-only replacement
+   * for context/afterInference. Notifications, fire-and-forget, gated on the
+   * inferenceLifecycle grant. BEST-EFFORT by design: the host attempts one
+   * terminal per `started` on every exit path it controls; consumers dedupe
+   * by inferenceId and keep a safety timeout. Never blocks the turn.
    */
-  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;
+  emitLifecycle(params: InferenceLifecycleParams): void {
+    for (const server of this.registry.getAllServers()) {
+      if (!CapabilityGrant.of(server).has('inferenceLifecycle')) continue;
+      try {
+        server.sendInferenceLifecycle(params);
+      } catch {
+        /* best-effort — a failed notify never disturbs the turn */
+      }
     }
   }
 
@@ -184,13 +197,21 @@ export class HookOrchestrator {
     params: BeforeInferenceParams,
   ): Promise<ContextInjection[]> {
     const results = await Promise.allSettled(
-      servers.map((server) =>
-        withTimeout(
-          server.sendBeforeInference(params),
+      servers.map((server) => {
+        // §10.1: a server not granted observe MUST receive
+        // `userMessage: null` — the field is ABSENT authority, not merely
+        // discouraged — while the hook is still invoked so granted
+        // injection positions keep working (write-without-read).
+        const perServer: BeforeInferenceParams =
+          CapabilityGrant.of(server).has('contextHooks.beforeInference.observe')
+            ? params
+            : { ...params, userMessage: null };
+        return withTimeout(
+          server.sendBeforeInference(perServer),
           BEFORE_INFERENCE_TIMEOUT_MS,
           `beforeInference to "${server.id}"`,
-        ).then((result) => ({ server, result })),
-      ),
+        ).then((result) => ({ server, result }));
+      }),
     );
 
     const injections: ContextInjection[] = [];
@@ -203,7 +224,9 @@ export class HookOrchestrator {
 
       const { server, result } = settled.value;
 
-      // Validate feature set
+      // Feature-set discipline (diagnostics; §5.4 forbids using the
+      // response-supplied featureSet as AUTHORIZATION — that is the
+      // position check below).
       try {
         this.featureSetManager.validateInbound(server.id, result.featureSet);
       } catch {
@@ -211,9 +234,20 @@ export class HookOrchestrator {
         continue;
       }
 
-      // Convert wire-format injections to context-manager format
+      // §5.4/§10.8: authorize EACH injection by its typed position against
+      // the grant CURRENT NOW, at response receipt — not when the request
+      // was sent. A revocation that landed while the hook was in flight is
+      // enforced here without extra machinery.
       if (result.contextInjections && result.contextInjections.length > 0) {
         for (const mcplInj of result.contextInjections) {
+          const leaf = INJECT_LEAVES.find((l) => l.position === mcplInj.position);
+          if (!leaf || !CapabilityGrant.of(server).has(leaf.path)) {
+            console.error(
+              `[mcpl] ${server.id}: dropped beforeInference injection at position ` +
+                `"${mcplInj.position}" — not in the effective grant (§10.8)`,
+            );
+            continue;
+          }
           injections.push(convertMcplInjection(mcplInj));
         }
       }
@@ -222,60 +256,4 @@ export class HookOrchestrator {
     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;
-  }
 }

package/src/mcpl/index.ts

@@ -47,8 +47,6 @@ export type {
   BeforeInferenceParams,
   McplContextInjection,
   BeforeInferenceResult,
-  AfterInferenceParams,
-  AfterInferenceResult,
 
   // Server-initiated inference
   McplMessage,

package/src/mcpl/prose-stream-router.ts

@@ -59,6 +59,23 @@ export class ProseStreamRouter {
     return this.accumulated;
   }
 
+  /**
+   * Drop everything routed so far and return to the constructed state.
+   *
+   * For a membrane refusal retry (RetryingEvent): the abandoned attempt's
+   * prose must not survive into the new one, and `accumulated` feeds
+   * outgoing/complete — leaving it would finalize text the model never
+   * actually said in the attempt that stands.
+   */
+  reset(): void {
+    this.target = this.opts.initialTarget;
+    this.state = this.opts.mode === 'locus' ? 'body' : 'line-start';
+    this.held = '';
+    this.token = '';
+    this.sawBang = false;
+    this.accumulated = new Map();
+  }
+
   feed(delta: string): RoutedDelta[] {
     const out: RoutedDelta[] = [];
     for (const ch of delta) this.step(ch, out);

package/src/mcpl/push-handler.ts

@@ -16,6 +16,7 @@ import type {
 } from './types.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
+import { expandCoreTags } from './tags.js';
 
 // ============================================================================
 // McplPushEvent (the ProcessEvent shape pushed to the queue)
@@ -165,7 +166,18 @@ export class PushHandler {
     params: PushEventParams,
     responder?: Responder,
   ): void {
-    // 1. Validate feature set
+    // §16.3: expand the normative chat:* core closure once, at entry, so
+    // every downstream consumer (wake matching, metadata, the queued event)
+    // sees the closed set. Producer `implies` edges are NOT consumed —
+    // advisory pending acceptance (§16.4). Tags were admitted before this
+    // point and grant nothing (§16.6).
+    if (params.tags) params.tags = expandCoreTags(params.tags);
+    // 1. Validate feature set. §6.6: rejection is diagnostics, not
+    // authorization, and MUST be a JSON-RPC error object — not a result
+    // carrying a failure flag. (The old `{accepted:false, reason}` result
+    // was AUDIT-001's finding: the error factories existed and were never
+    // invoked.) Falls back to the result shape only for a legacy responder
+    // with no error path.
     try {
       this.featureSetManager.validateInbound(serverId, params.featureSet);
     } catch (err) {
@@ -175,7 +187,11 @@ export class PushHandler {
       // Loud rejection — a rejected push event is an agent that silently
       // never hears the message. (2026-07-09 diagnosability pass.)
       console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=${reason}`);
-      responder?.respond({ accepted: false, reason });
+      if (err instanceof McplFeatureSetError && responder?.respondError) {
+        responder.respondError(err.code, reason, { featureSet: err.featureSet });
+      } else {
+        responder?.respond({ accepted: false, reason });
+      }
       return;
     }