@animalabs/agent-framework 0.8.0 → 0.10.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-grammar.ts

@@ -38,3 +38,24 @@ export function parseProsePrefix(text: string): ProsePrefix {
   }
   return { kind: 'target', target, continueTurn, body };
 }
+
+/** A real hybrid routing line: exact triple-arrow plus an optional whitespace
+ * run and a non-whitespace target token. */
+export const HYBRID_PROSE_PREFIX_LINE = /^>>>[ \t]*\S/;
+
+/**
+ * Hybrid/locus-preserving routing grammar.
+ *
+ * `>>>#cafe body` and `>>> #cafe body` route this envelope explicitly while
+ * unprefixed prose remains ordinary frozen-locus speech. The authored source
+ * is never rewritten; callers consume this view only for publication.
+ */
+export function parseHybridProsePrefix(text: string): ProsePrefix {
+  const m = /^>>>[ \t]*(\S+)([ \t]+!)?[ \t]*\n?/.exec(text);
+  if (!m) return { kind: 'none', continueTurn: false, body: text };
+  const target = m[1]!;
+  const continueTurn = m[2] !== undefined;
+  const body = text.slice(m[0].length);
+  if (target === 'skip_reply') return { kind: 'private', continueTurn, body };
+  return { kind: 'target', target, continueTurn, body };
+}

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

@@ -30,7 +30,7 @@ export interface RoutedDelta {
   delta: string;
 }
 
-type State = 'line-start' | 'maybe-prefix' | 'prefix-token' | 'after-token' | 'body';
+type State = 'line-start' | 'hybrid-indent' | 'maybe-prefix' | 'prefix-gap' | 'prefix-token' | 'after-token' | 'body';
 
 export class ProseStreamRouter {
   private target: string | null;
@@ -42,8 +42,8 @@ export class ProseStreamRouter {
 
   constructor(
     private opts: {
-      /** 'explicit' parses `>>` prefixes; 'locus' is pure passthrough. */
-      mode: 'explicit' | 'locus';
+      /** explicit parses `>>`; hybrid parses `>>>` while retaining locus fallback. */
+      mode: 'explicit' | 'hybrid' | 'locus';
       /** Initial destination: the frozen turn locus (locus mode) or null. */
       initialTarget: string | null;
       /** Resolve a `>>spec` to a channelId, or null (unresolved/ambiguous). */
@@ -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);
@@ -70,7 +87,12 @@ export class ProseStreamRouter {
    *  no body — dropped, matching delivery which would deliver empty body). */
   finish(): RoutedDelta[] {
     const out: RoutedDelta[] = [];
-    if (this.state === 'maybe-prefix') this.emit(this.held, out); // "" | ">" | ">>"
+    if (this.state === 'hybrid-indent') this.emit(this.held, out);
+    if (this.state === 'maybe-prefix') {
+      const full = this.opts.mode === 'hybrid' ? '>>>' : '>>';
+      const arrows = this.opts.mode === 'hybrid' ? this.held.trimStart() : this.held;
+      if (arrows !== full) this.emit(this.held, out);
+    }
     // prefix-token / after-token at EOF: prefix without body — nothing to emit.
     this.held = '';
     this.state = 'line-start';
@@ -80,7 +102,7 @@ export class ProseStreamRouter {
   private step(ch: string, out: RoutedDelta[]): void {
     switch (this.state) {
       case 'body':
-        if (ch === '\n' && this.opts.mode === 'explicit') {
+        if (ch === '\n' && this.opts.mode !== 'locus') {
           this.emit('\n', out);
           this.state = 'line-start';
         } else {
@@ -89,34 +111,63 @@ export class ProseStreamRouter {
         return;
 
       case 'line-start':
+        if (this.opts.mode === 'hybrid' && (ch === ' ' || ch === '\t')) {
+          this.state = 'hybrid-indent';
+          this.held = ch;
+          return;
+        }
         if (ch === '>') { this.state = 'maybe-prefix'; this.held = '>'; return; }
         this.state = 'body';
         this.step(ch, out);
         return;
 
-      case 'maybe-prefix':
-        if (this.held === '>' && ch === '>') { this.held = '>>'; return; }
-        if (this.held === '>>') {
+      case 'hybrid-indent':
+        if (ch === ' ' || ch === '\t') { this.held += ch; return; }
+        if (ch === '>') { this.held += ch; this.state = 'maybe-prefix'; return; }
+        this.emit(this.held, out);
+        this.held = '';
+        this.state = 'body';
+        this.step(ch, out);
+        return;
+
+      case 'maybe-prefix': {
+        const prefix = this.opts.mode === 'hybrid' ? '>>>' : '>>';
+        const arrows = this.opts.mode === 'hybrid' ? this.held.trimStart() : this.held;
+        if (ch === '>' && arrows.length < prefix.length) {
+          this.held += '>';
+          return;
+        }
+        if (arrows === prefix) {
+          if (this.opts.mode === 'hybrid' && (ch === ' ' || ch === '\t')) {
+            this.held = '';
+            this.state = 'prefix-gap';
+            return;
+          }
           if (ch === '\n' || ch === ' ' || ch === '\t') {
-            // `>> quoted arrow` / bare `>>`: body text, not a prefix.
-            this.emit(this.held, out);
+            if (this.opts.mode === 'explicit') this.emit(this.held, out);
             this.held = '';
-            this.state = 'body';
-            this.step(ch, out);
+            this.state = ch === '\n' ? 'line-start' : 'body';
+            if (ch !== '\n') this.step(ch, out);
             return;
           }
-          // real prefix begins
           this.state = 'prefix-token';
           this.token = ch;
           this.held = '';
           return;
         }
-        // held === '>' and ch !== '>': plain body starting with '>'
         this.emit(this.held, out);
         this.held = '';
         this.state = 'body';
         this.step(ch, out);
         return;
+      }
+
+      case 'prefix-gap':
+        if (ch === ' ' || ch === '\t') return;
+        if (ch === '\n') { this.target = null; this.state = 'line-start'; return; }
+        this.state = 'prefix-token';
+        this.token = ch;
+        return;
 
       case 'prefix-token':
         if (ch === ' ' || ch === '\t') { this.applyTarget(); this.state = 'after-token'; this.sawBang = false; return; }

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;
     }