MCPL RFC-005 host treatment: reference blocks stub into context, never inline

src/framework.ts

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './mcpl/references.js';
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
 import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult, ToolResultContentBlock } from '@animalabs/membrane';
@@ -7925,6 +7926,11 @@ export class AgentFramework {
     for (const raw of data) {
       if (!raw || typeof raw !== 'object') return null;
       const b = raw as { type?: unknown; text?: unknown; data?: unknown; mimeType?: unknown };
+      if (isInlineContradiction(b)) {
+        // RFC-005 vector 2: withhold inline data claiming bulk disposition.
+        blocks.push({ type: 'text', text: INLINE_WITHHELD_TEXT });
+        continue;
+      }
       if (b.type === 'text' && typeof b.text === 'string') {
         let text = b.text;
         if (maxChars && text.length > maxChars) {
@@ -7940,6 +7946,13 @@ export class AgentFramework {
           type: 'image',
           source: { type: 'base64', data: b.data, mediaType: b.mimeType },
         });
+      } else if (b.type === 'resource' || ((b.type === 'image' || b.type === 'audio') && typeof (b as { uri?: unknown }).uri === 'string')) {
+        // RFC-005 reference block → bounded stub. Previously this bailed the
+        // whole array to JSON, which both inlined the reference verbatim and
+        // demoted any adjacent image block to stringified base64.
+        const stub = referenceStubOrNull(b, 'from tool result');
+        if (stub === null) return null;
+        blocks.push({ type: 'text', text: stub });
       } else {
         return null; // unknown shape — bail to JSON path
       }

src/mcpl/channel-registry.ts

@@ -14,6 +14,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
 import type { JsStore } from '@animalabs/chronicle';
 
 import type {
@@ -124,6 +125,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: block.text };
 
     case 'image':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'image',
@@ -139,6 +150,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Image: no data]' };
 
     case 'audio':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'audio',
@@ -148,7 +169,14 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Audio: no data]' };
 
     case 'resource':
-      return { type: 'text', text: `[Resource: ${block.uri}]` };
+      // RFC-005: reference blocks become bounded stubs — never raw URIs
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
+
+    default:
+      // Unknown wire block types previously fell off the exhaustive switch
+      // and propagated `undefined` into ContentBlock[]. Fail visibly.
+      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
   }
 }
 

src/mcpl/hook-orchestrator.ts

@@ -14,6 +14,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
 import type { ContextInjection } from '@animalabs/context-manager';
 
 import type {
@@ -65,6 +66,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: block.text };
 
     case 'image':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on context injection') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'image',
@@ -81,6 +92,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Image: missing data]' };
 
     case 'audio':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on context injection') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'audio',
@@ -91,8 +112,14 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       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}]` };
+      // RFC-005: reference blocks become bounded stubs — never raw URIs
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, 'attachment on context injection') ?? '[reference]' };
+
+    default:
+      // Unknown wire block types previously fell off the exhaustive switch
+      // and propagated `undefined` into ContentBlock[]. Fail visibly.
+      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
   }
 }
 

src/mcpl/push-handler.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
 
 import type {
   McplContentBlock,
@@ -51,12 +52,22 @@ export interface McplPushEvent {
  * Convert a single MCPL wire-format content block to a membrane ContentBlock.
  * Same logic as hook-orchestrator.ts.
  */
-function convertBlock(block: McplContentBlock): ContentBlock {
+export function convertBlock(block: McplContentBlock): ContentBlock {
   switch (block.type) {
     case 'text':
       return { type: 'text', text: block.text };
 
     case 'image':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'image',
@@ -72,6 +83,16 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Image: no data]' };
 
     case 'audio':
+      if (isInlineContradiction(block)) {
+        // RFC-005 vector 2: inline data claiming bulk disposition — fail
+        // closed, withhold the data (checked BEFORE the data branch).
+        return { type: 'text', text: INLINE_WITHHELD_TEXT };
+      }
+      if (block.uri && block.disposition) {
+        // RFC-005 uri-form media with a disposition claim: stub, do not
+        // hand the URI to the provider or inline it.
+        return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
+      }
       if (block.data && block.mimeType) {
         return {
           type: 'audio',
@@ -81,7 +102,14 @@ function convertBlock(block: McplContentBlock): ContentBlock {
       return { type: 'text', text: '[Audio: no data]' };
 
     case 'resource':
-      return { type: 'text', text: `[Resource: ${block.uri}]` };
+      // RFC-005: reference blocks become bounded stubs — never raw URIs
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
+
+    default:
+      // Unknown wire block types previously fell off the exhaustive switch
+      // and propagated `undefined` into ContentBlock[]. Fail visibly.
+      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
   }
 }