@animalabs/agent-framework 0.22.3 → 0.23.0

package/src/mcpl/convert-block.ts

@@ -5,7 +5,16 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
+import {
+  AUDIO_NO_DATA_TEXT,
+  AUDIO_NO_MEDIA_TYPE_TEXT,
+  IMAGE_NO_DATA_TEXT,
+  IMAGE_NO_MEDIA_TYPE_TEXT,
+  INLINE_WITHHELD_TEXT,
+  isInlineContradiction,
+  referenceStubOrNull,
+  unknownBlockText,
+} from './references.js';
 import { NON_STRING_TEXT_PLACEHOLDER } from './visible-content.js';
 import type { McplContentBlock } from './types.js';
 
@@ -17,8 +26,8 @@ import type { McplContentBlock } from './types.js';
  * shows as NON_STRING_TEXT_PLACEHOLDER. `provenance` is what a reference stub
  * says the reference came on, such as 'attachment on push event'. `serverId`
  * is the server that sent the content: a reference is registered with it, as
- * a tool result's references are, so fetch_reference can fetch it from that
- * server.
+ * a tool result's references are, so fetch_reference can fetch it through that
+ * server's address, where it has one.
  */
 export function convertBlock(block: McplContentBlock, provenance: string, serverId: string): ContentBlock {
   switch (block.type) {
@@ -51,7 +60,7 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
           source: { type: 'url', url: block.uri },
         } as ContentBlock;
       }
-      return { type: 'text', text: isFilledString(block.data) ? '[Image: no media type]' : '[Image: no data]' };
+      return { type: 'text', text: isFilledString(block.data) ? IMAGE_NO_MEDIA_TYPE_TEXT : IMAGE_NO_DATA_TEXT };
 
     case 'audio':
       if (isInlineContradiction(block)) {
@@ -70,7 +79,7 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
           source: { type: 'base64', data: block.data, mediaType: block.mimeType },
         } as ContentBlock;
       }
-      return { type: 'text', text: isFilledString(block.data) ? '[Audio: no media type]' : '[Audio: no data]' };
+      return { type: 'text', text: isFilledString(block.data) ? AUDIO_NO_MEDIA_TYPE_TEXT : AUDIO_NO_DATA_TEXT };
 
     case 'resource':
       // RFC-005: reference blocks become bounded stubs — never raw URIs
@@ -82,8 +91,7 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
       // and propagated `undefined` into ContentBlock[]. Fail visibly. A type
       // that isn't a string is no type, and is never converted to one: an
       // object can throw when it is.
-      const type: unknown = (block as { type?: unknown }).type;
-      return { type: 'text', text: `[unrecognized content block: ${typeof type === 'string' ? type : 'untyped'}]` };
+      return { type: 'text', text: unknownBlockText(block) };
     }
   }
 }

package/src/mcpl/index.ts

@@ -106,9 +106,22 @@ export {
 } from './errors.js';
 
 // Server connection and registry
-export { McplServerConnection, McplRequestError } from './server-connection.js';
+export { McplServerConnection, McplRequestError, McplProtocolVersionError, McplUnreapedLaunchError } from './server-connection.js';
 export type { McplConnectionCloseInfo } from './server-connection.js';
 export type { TransportCloseInfo } from './transport.js';
+export { ModernMcpConnection } from './modern-connection.js';
+export type { ModernToolCallResult } from './modern-connection.js';
+export {
+  LEGACY_MCP_PROTOCOL_VERSION,
+  MODERN_MCP_PROTOCOL_VERSION,
+  MAX_TIMER_MS,
+  mcplPolicyGrants,
+  resolveServerBinding,
+  serverConfigProblems,
+  serverConfigWarnings,
+  checkServerConfig,
+} from './protocol-family.js';
+export type { McpProtocolFamily, McpTransportKind, ServerBinding } from './protocol-family.js';
 export { McplServerRegistry, type McplCapabilityQuery } from './server-registry.js';
 
 // Feature set management (permission layer)

package/src/mcpl/inference-router.ts

@@ -37,6 +37,9 @@ interface Responder {
   respondError(code: number, message: string, data?: unknown): void;
   /** The JSON-RPC request ID, used for streaming chunk correlation. */
   requestId?: string | number;
+  /** Sends a streamed chunk on the transport the request came on, as its
+   *  answer is sent. */
+  sendChunk?(params: InferenceChunkParams): void;
 }
 
 // ============================================================================
@@ -178,7 +181,6 @@ export class InferenceRouter {
   private featureSetManager: FeatureSetManager;
   private routingPolicy: InferenceRoutingPolicy | null;
   private emitTraceFn: (event: { type: string; [key: string]: unknown }) => void;
-  private sendChunkFn?: (serverId: string, params: InferenceChunkParams) => void;
 
   constructor(
     membrane: Membrane,
@@ -186,14 +188,12 @@ export class InferenceRouter {
     featureSetManager: FeatureSetManager,
     routingPolicy: InferenceRoutingPolicy | null,
     emitTraceFn: (event: { type: string; [key: string]: unknown }) => void,
-    sendChunkFn?: (serverId: string, params: InferenceChunkParams) => void,
   ) {
     this.membrane = membrane;
     this.hookOrchestrator = hookOrchestrator;
     this.featureSetManager = featureSetManager;
     this.routingPolicy = routingPolicy;
     this.emitTraceFn = emitTraceFn;
-    this.sendChunkFn = sendChunkFn;
   }
 
   /**
@@ -265,14 +265,15 @@ export class InferenceRouter {
 
     // Streaming needs a way to send chunks and an id to tag them with;
     // without either, the request is answered whole.
-    const chunkRequestId = params.stream && this.sendChunkFn ? responder.requestId : undefined;
+    const sendChunk = params.stream ? responder.sendChunk?.bind(responder) : undefined;
+    const chunkRequestId = sendChunk ? responder.requestId : undefined;
     const streamed = chunkRequestId != null;
 
     try {
       // 5. Run inference. Both modes end in membrane's response, and one
       // builder makes the result from it.
       const response = chunkRequestId != null
-        ? await this.streamResponse(serverId, request, chunkRequestId)
+        ? await this.streamResponse(request, chunkRequestId, sendChunk!)
         : await this.membrane.complete(request);
 
       // 6. Answer
@@ -375,9 +376,9 @@ export class InferenceRouter {
    * so nothing keeps running once the request is answered.
    */
   private async streamResponse(
-    serverId: string,
     request: NormalizedRequest,
     requestId: string | number,
+    sendChunk: (params: InferenceChunkParams) => void,
   ): Promise<NormalizedResponse> {
     const stream = this.membrane.streamYielding(request);
     let index = 0;
@@ -392,7 +393,7 @@ export class InferenceRouter {
           // naming a tag the stream parser opens a block for, or a thinking
           // block cut off before its close tag.
           if (event.meta.visible) {
-            this.sendChunkFn!(serverId, { requestId, index: index++, delta: event.content });
+            sendChunk({ requestId, index: index++, delta: event.content });
           }
           break;
         case 'tool-calls':

package/src/mcpl/log-value.ts

@@ -45,6 +45,16 @@ export function logValue(value: unknown): string {
   return printed(textOf(value), FIELD);
 }
 
+/**
+ * `logValue` of a value a server chose whose text may hold a credential:
+ * its text, as logValue reads it (a JSON value as its JSON text), with
+ * `redact` applied, then printed as logValue prints a field. A value whose
+ * text holds nothing `redact` replaces prints exactly as logValue prints it.
+ */
+export function logValueRedacted(value: unknown, redact: (text: string) => string): string {
+  return printed(redact(textOf(value)), FIELD);
+}
+
 /**
  * The host's own message, as the free text that ends a log line after its
  * fields: `reason=coalesce-invalid field=payload.content: "content must be an