@animalabs/agent-framework 0.22.2 → 0.23.0

package/src/mcpl/checkpoint-manager.ts

@@ -13,6 +13,8 @@
  */
 
 import type { JsStore } from '@animalabs/chronicle';
+import { ensureStateRegistered } from '../module-registry.js';
+import { boundedErrorMessage as thrownText } from '../error-message.js';
 
 import type { StateCheckpoint, JsonPatchOperation } from './types.js';
 
@@ -26,6 +28,23 @@ const CHECKPOINTS_STATE_ID = 'mcpl/checkpoints';
 /** Prefix for per-feature-set host-managed state. */
 const STATE_PREFIX = 'mcpl/state';
 
+/** What the refusals below say about MCPL when stored trees or state can't be taken. */
+const MCPL_STOPS = `MCPL doesn't start without them, and neither does create() with MCPL servers configured, ` +
+  `nor a first connectMcplServer()`;
+
+/** A stored JSON value's kind, for a refusal that names what it found without its content. */
+function storedKind(value: unknown): string {
+  return value === undefined ? 'missing'
+    : value === null ? 'null'
+      : Array.isArray(value) ? 'an array'
+        : typeof value === 'object' ? 'an object'
+          : `a ${typeof value}`;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
 // ============================================================================
 // Internal types
 // ============================================================================
@@ -190,11 +209,7 @@ export class CheckpointManager {
     this.emitTraceFn = emitTraceFn;
 
     // Register the checkpoint metadata state slot
-    try {
-      store.registerState({ id: CHECKPOINTS_STATE_ID, strategy: 'snapshot' });
-    } catch {
-      // Already registered (e.g. framework restart)
-    }
+    ensureStateRegistered(store, { id: CHECKPOINTS_STATE_ID, strategy: 'snapshot' });
 
     // Load existing tree from Chronicle
     this.loadFromStore();
@@ -214,31 +229,22 @@ export class CheckpointManager {
     opts: { hostState: boolean; rollback: boolean },
   ): void {
     const key = this.key(serverId, featureSet);
-    if (this.trees.has(key)) return; // Already registered (e.g. from loaded state)
+    // Already registered, or restored from the store by loadFromStore, whose
+    // host-managed state loadHostStates reads before its server connects.
+    if (this.trees.has(key)) return;
 
-    this.trees.set(key, {
+    const tree: FeatureSetState = {
       hostState: opts.hostState,
       rollback: opts.rollback,
       currentCheckpoint: null,
       currentState: undefined,
       nodes: new Map(),
-    });
-
-    // Register per-feature-set state slot for host-managed state
-    if (opts.hostState) {
-      const stateId = this.stateId(serverId, featureSet);
-      try {
-        this.store.registerState({ id: stateId, strategy: 'snapshot' });
-      } catch {
-        // Already registered
-      }
-      // Load existing state if any
-      const existing = this.store.getStateJson(stateId);
-      if (existing !== null && existing !== undefined) {
-        const tree = this.trees.get(key)!;
-        tree.currentState = existing;
-      }
-    }
+    };
+    // The state's slot is registered, and its stored value read, before the
+    // tree is held, so a registration that fails here leaves nothing behind
+    // and is made whole by the next one (a reconnect's re-run).
+    if (opts.hostState) this.loadHostState(serverId, featureSet, tree, 'registration');
+    this.trees.set(key, tree);
 
     this.emitTraceFn({
       type: 'mcpl:state_registered',
@@ -540,12 +546,81 @@ export class CheckpointManager {
     this.store.setStateJson(CHECKPOINTS_STATE_ID, serialized);
   }
 
-  /** Load checkpoint tree from Chronicle on startup. */
+  /** A host-managed feature set's stored state, read into its tree; nothing
+   *  stored leaves it unset. A registration or read that fails throws,
+   *  naming the state: taken as nothing stored, the next patch would apply
+   *  to nothing and store over it. `when` says what the refusal stops: a
+   *  restored tree's read comes before its server connects, and a feature
+   *  set with no tree is read when it registers, once its server has
+   *  connected. */
+  private loadHostState(
+    serverId: string,
+    featureSet: string,
+    tree: FeatureSetState,
+    when: 'before-connect' | 'registration',
+  ): void {
+    const stateId = this.stateId(serverId, featureSet);
+    let existing: unknown;
+    try {
+      ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
+      existing = this.store.getStateJson(stateId);
+    } catch (error) {
+      throw new Error(
+        `the host-managed state of feature set "${featureSet}" on MCPL server "${serverId}" (${stateId}) could not ` +
+          `be registered or read: ${thrownText(error)}. ` +
+          (when === 'before-connect'
+            ? `Neither create() with the server configured nor a connectMcplServer() of it goes on without it, since ` +
+              `the feature set's next checkpoint would store over it. It's unchanged, and they go on once it can be read.`
+            : `The feature set isn't registered without it, since its next checkpoint would store over it, so the ` +
+              `server's connect fails. It's unchanged, and it's read again when the feature set next registers.`),
+        { cause: error },
+      );
+    }
+    if (existing !== null && existing !== undefined) tree.currentState = existing;
+  }
+
+  /** Read the stored state of every host-managed tree held for `serverId`
+   *  with none in memory, whatever its feature sets declare now. The
+   *  framework calls it at MCPL's start for each configured server and
+   *  before a runtime connect adds its server, so no server connects with a
+   *  restored tree whose state its next checkpoint would store over unread.
+   *  A tree whose state is in memory, as a connected server's is, keeps it.
+   *  A server's trees are the keys `${serverId}:`, as removeServer finds
+   *  them. */
+  loadHostStates(serverId: string): void {
+    const prefix = `${serverId}:`;
+    for (const [key, tree] of this.trees) {
+      if (!tree.hostState || tree.currentState !== undefined || !key.startsWith(prefix)) continue;
+      this.loadHostState(serverId, key.slice(prefix.length), tree, 'before-connect');
+    }
+  }
+
+  /** Load checkpoint trees from Chronicle on startup. Nothing stored is no
+   *  trees. Trees that can't be read, or a stored value that isn't an object
+   *  whose trees is an object, throw: taken as no trees, the next feature set
+   *  registered would store over them. */
   private loadFromStore(): void {
-    const data = this.store.getStateJson(CHECKPOINTS_STATE_ID) as SerializedTrees | null;
-    if (!data?.trees) return;
+    const what = `the MCPL checkpoint trees (${CHECKPOINTS_STATE_ID})`;
+    const stops = `${MCPL_STOPS}, since the next feature set registered would store over them.`;
+    let data: unknown;
+    try {
+      data = this.store.getStateJson(CHECKPOINTS_STATE_ID);
+    } catch (error) {
+      throw new Error(
+        `${what} could not be read: ${thrownText(error)}. ${stops} They're unchanged, and MCPL starts once they can be read.`,
+        { cause: error },
+      );
+    }
+    if (data === null || data === undefined) return;
+    const trees = isObject(data) ? data.trees : undefined;
+    if (!isObject(trees)) {
+      throw new Error(
+        `${what} are ${isObject(data) ? `an object whose trees is ${storedKind(trees)}` : storedKind(data)}, not ` +
+          `checkpoint trees. ${stops} They're unchanged, and starting again won't help until they're repaired.`,
+      );
+    }
 
-    for (const [key, entry] of Object.entries(data.trees)) {
+    for (const [key, entry] of Object.entries(trees as SerializedTrees['trees'])) {
       const nodes = new Map<string, CheckpointNode>();
       for (const [id, nodeData] of Object.entries(entry.nodes)) {
         nodes.set(id, {
@@ -561,7 +636,7 @@ export class CheckpointManager {
         hostState: entry.hostState,
         rollback: entry.rollback,
         currentCheckpoint: entry.current,
-        currentState: undefined, // Will be loaded per-feature-set during registerFeatureSet
+        currentState: undefined, // a host-managed tree's state is read by loadHostStates, before its server connects
         nodes,
       });
     }

package/src/mcpl/conversation-router.ts

@@ -34,6 +34,7 @@
  * follow-up.
  */
 
+import { createHash } from 'node:crypto';
 import type { ContextStrategy } from '@animalabs/context-manager';
 import type { ChannelDescriptor } from './types.js';
 
@@ -118,6 +119,10 @@ export interface ConversationBinding {
  * framework so the router stays free of event-shape knowledge. */
 export interface IncomingMessageFacts {
   channelId: string;
+  /** The MCPL server the channel belongs to. A spawned fork's name hashes it
+   *  with the channel id (see forkAgentName); left out, `null` stands in for
+   *  it there. */
+  serverId?: string;
   /** Personal mention of the bot (metadata.mentioned from the adapter). */
   mentioned: boolean;
   /** Channel classification (see classifyChannel). */
@@ -208,7 +213,7 @@ export class ConversationRouter {
     const generation = (this.generations.get(facts.channelId) ?? 0) + 1;
     return {
       kind: 'spawn',
-      agentName: this.forkAgentName(facts.channelId, generation),
+      agentName: forkAgentName(this.config.agentPrefix ?? 'conversation', facts.serverId, facts.channelId, generation),
       generation,
       trigger: this.shouldTrigger(facts),
     };
@@ -310,12 +315,27 @@ export class ConversationRouter {
       ?? (facts.kind === 'dm' ? 'always' : 'mention');
     return rule === 'always' || facts.mentioned;
   }
+}
 
-  /** `conversation-slack-C123-g2` — agent names double as Chronicle
-   * namespace components, so the channel id is sanitized. */
-  private forkAgentName(channelId: string, generation: number): string {
-    const prefix = this.config.agentPrefix ?? 'conversation';
-    const safe = channelId.replace(/[^A-Za-z0-9_-]+/g, '-');
-    return `${prefix}-${safe}-g${generation}`;
-  }
+/** The readable part of a fork's name stops here: uniqueness rides on the hash. */
+const FORK_NAME_READABLE_MAX = 64;
+
+/**
+ * A fork's agent name: `<prefix>-<readable>-g<generation>-<hash>`, such as
+ * `conversation-C123-g2-e08e564271867d16` for Slack's channel `C123` on the
+ * server `slack`. Agent names double as context-manager namespace components,
+ * so the readable part is the channel id with each run of characters other
+ * than letters, digits, `_` and `-` replaced by `-`, cut to 64 characters.
+ * Different ids can read alike (`foo bar`, `foo-bar`), so the hash is the first
+ * 64 bits of a SHA-256 of `JSON.stringify([serverId, channelId])`, where an
+ * absent server id is written as `null`: two channels' forks share a name, and
+ * with it a namespace, only if those 64 bits collide. The hash is fixed-length
+ * and last, so a name's parts read back unambiguously, and a pattern over its
+ * readable part and `-g`, such as `conversation-C123-g*`, matches each
+ * generation's fork.
+ */
+export function forkAgentName(prefix: string, serverId: string | undefined, channelId: string, generation: number): string {
+  const readable = channelId.replace(/[^A-Za-z0-9_-]+/g, '-').slice(0, FORK_NAME_READABLE_MAX);
+  const hash = createHash('sha256').update(JSON.stringify([serverId, channelId])).digest('hex').slice(0, 16);
+  return `${prefix}-${readable}-g${generation}-${hash}`;
 }

package/src/mcpl/convert-block.ts

@@ -0,0 +1,105 @@
+/**
+ * MCPL wire content to membrane content: the one conversion every lane uses,
+ * for pushed events, channel messages and context injections alike, so a rule
+ * about a malformed block holds on all three.
+ */
+
+import type { ContentBlock } from '@animalabs/membrane';
+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';
+
+/**
+ * Convert a single MCPL wire-format content block to a membrane ContentBlock.
+ * It takes any block but null or undefined without throwing (those two throw,
+ * for the caller to refuse or leave out): a type, data, mimeType or uri that
+ * isn't a string counts as absent, and a text block whose text isn't a string
+ * 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 through that
+ * server's address, where it has one.
+ */
+export function convertBlock(block: McplContentBlock, provenance: string, serverId: string): ContentBlock {
+  switch (block.type) {
+    case 'text':
+      // Text that isn't a string can't be shown, so the agent reads that a
+      // block was there; the emptiness checks still count it as no text
+      // (isVisiblyEmptyConversion), as the request sanitizer would.
+      return { type: 'text', text: typeof block.text === 'string' ? block.text : NON_STRING_TEXT_PLACEHOLDER };
+
+    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 (isFilledString(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, provenance, serverId) ?? '[reference]' };
+      }
+      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
+        return {
+          type: 'image',
+          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
+        } as ContentBlock;
+      }
+      if (isFilledString(block.uri)) {
+        return {
+          type: 'image',
+          source: { type: 'url', url: block.uri },
+        } as ContentBlock;
+      }
+      return { type: 'text', text: isFilledString(block.data) ? IMAGE_NO_MEDIA_TYPE_TEXT : IMAGE_NO_DATA_TEXT };
+
+    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 (isFilledString(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, provenance, serverId) ?? '[reference]' };
+      }
+      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
+        return {
+          type: 'audio',
+          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
+        } as ContentBlock;
+      }
+      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
+      // (a signed URL is a bearer credential that looks like a location).
+      return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
+
+    default: {
+      // Unknown wire block types previously fell off the exhaustive switch
+      // 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.
+      return { type: 'text', text: unknownBlockText(block) };
+    }
+  }
+}
+
+/** A string with something in it: the only data, mimeType or uri a block's
+ *  source is built from, and the only uri that makes it a reference. Anything
+ *  else a sender puts there leaves the block without it, so conversion never
+ *  throws and never copies a non-string. */
+function isFilledString(value: unknown): value is string {
+  return typeof value === 'string' && value !== '';
+}

package/src/mcpl/errors.ts

@@ -40,6 +40,34 @@ export const CHANNEL_OPEN_FAILED = -32024;
 // Error Factories
 // ============================================================================
 
+/** The text of any value: anything thrown or rejected, or a value a server
+ *  sent, such as an error answer's code. Never throws, whatever it is: a
+ *  null-prototype object, or a message getter or toString that throws. */
+export function describeCause(cause: unknown): string {
+  try {
+    return cause instanceof Error ? String(cause.message) : String(cause);
+  } catch {
+    try {
+      return Object.prototype.toString.call(cause);
+    } catch {
+      return 'an error that could not be printed';
+    }
+  }
+}
+
+/** Text a server or a handler chose, made fit for an error's message or a
+ *  trace field: control and format characters replaced (C0 and C1 controls,
+ *  bidi and other \p{Cf} characters, and the line and paragraph separators
+ *  some log readers break lines on), and cut after `max` code points, with
+ *  "…" marking the cut. Those are read as data, by a trace's or an error
+ *  listener's reader, so the text is bounded rather than escaped. A log line
+ *  prints text a server or a handler chose through log-value instead
+ *  (logValue for a field, logDetail for the free text that ends the line). */
+export function boundedForLog(text: string, max = 200): string {
+  const points = [...text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, '?')];
+  return points.length > max ? `${points.slice(0, max).join('')}…` : points.join('');
+}
+
 /**
  * Create a "feature set not enabled" error.
  * Returned when a server sends a message tagged with a feature set

package/src/mcpl/hook-orchestrator.ts

@@ -14,7 +14,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
+import { convertBlock } from './convert-block.js';
 import type { ContextInjection } from '@animalabs/context-manager';
 
 import type {
@@ -28,6 +28,7 @@ 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';
+import { logDetail, logValue } from './log-value.js';
 
 /** Timeout for beforeInference per server (fail-open). */
 const BEFORE_INFERENCE_TIMEOUT_MS = 5_000;
@@ -58,89 +59,25 @@ function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise
 // ============================================================================
 
 /**
- * Convert a single MCPL wire-format content block to a membrane ContentBlock.
+ * Convert MCPL injection content (string shorthand or block array), from the
+ * server `serverId`, to membrane ContentBlock[].
  */
-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 context injection') ?? '[reference]' };
-      }
-      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 (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',
-          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':
-      // 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'}]` };
-  }
-}
-
-/**
- * Convert MCPL injection content (string shorthand or block array) to membrane ContentBlock[].
- */
-function convertContent(content: string | McplContentBlock[]): ContentBlock[] {
+function convertContent(content: string | McplContentBlock[], serverId: string): ContentBlock[] {
   if (typeof content === 'string') {
     return [{ type: 'text', text: content }];
   }
-  return content.map(convertBlock);
+  return content.map((block) => convertBlock(block, 'attachment on context injection', serverId));
 }
 
 /**
- * Convert an MCPL wire-format context injection to a context-manager ContextInjection.
+ * Convert an MCPL wire-format context injection, from the server `serverId`,
+ * to a context-manager ContextInjection.
  */
-function convertMcplInjection(mcplInj: McplContextInjection): ContextInjection {
+function convertMcplInjection(mcplInj: McplContextInjection, serverId: string): ContextInjection {
   return {
     namespace: mcplInj.namespace,
     position: mcplInj.position,
-    content: convertContent(mcplInj.content),
+    content: convertContent(mcplInj.content, serverId),
     metadata: mcplInj.metadata,
   };
 }
@@ -153,6 +90,10 @@ export class HookOrchestrator {
   private registry: McplServerRegistry;
   private featureSetManager: FeatureSetManager;
   private _isInHook = false;
+  /** Servers already told that an injection's namespace wasn't a string. */
+  private readonly namespaceWarned = new Set<string>();
+  /** Server and namespace pairs already told that a system injection held a block that isn't text. */
+  private readonly notShownWarned = new Set<string>();
 
   constructor(registry: McplServerRegistry, featureSetManager: FeatureSetManager) {
     this.registry = registry;
@@ -261,21 +202,42 @@ export class HookOrchestrator {
         continue;
       }
 
+      // One server's malformed answer, or one malformed injection in it, is
+      // that server's to fix: it's left out with a line naming the server,
+      // and every other injection still arrives. Unguarded, a throw here
+      // leaves fanOutBeforeInference, and the framework's catch around the
+      // whole hook drops every server's injections for the turn.
+      const answered: unknown = result.contextInjections;
+      if (answered !== undefined && answered !== null && !Array.isArray(answered)) {
+        console.error(`[mcpl] ${server.id}: dropped its beforeInference injections — contextInjections isn't an array`);
+        continue;
+      }
       // §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) {
+      for (const mcplInj of (answered ?? []) as McplContextInjection[]) {
+        try {
           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)`,
+                `${logValue(mcplInj.position)} — not in the effective grant (§10.8)`,
             );
             continue;
           }
-          injections.push(convertMcplInjection(mcplInj));
+          if (typeof mcplInj.namespace !== 'string') this.readNamespace(server.id, mcplInj.namespace);
+          const injection = convertMcplInjection(mcplInj, server.id);
+          if (injection.position === 'system') this.noteBlocksNotShown(server.id, mcplInj.namespace, injection.content);
+          injections.push(injection);
+        } catch (error) {
+          // Such as a null block, content that isn't an array, a null
+          // injection, or a namespace that can't be read as text.
+          const position = (mcplInj as { position?: unknown } | null | undefined)?.position;
+          console.error(
+            `[mcpl] ${server.id}: dropped beforeInference injection at position ${logValue(position)} ` +
+              `— it couldn't be read: ${logDetail(error instanceof Error ? error.message : error)}`,
+          );
         }
       }
     }
@@ -283,4 +245,49 @@ export class HookOrchestrator {
     return injections;
   }
 
+  /**
+   * Checks a namespace that isn't a string, which §10.4 doesn't allow. One
+   * that can be read as text is kept as it is, and its server's operator is
+   * told once: context-manager reads it as its text when it writes a
+   * beforeUser or afterUser injection's namespace into a participant's name,
+   * as it always has. One with no text form would throw there, after the
+   * catch around each injection, and fail the turn, so it throws here, and
+   * its injection alone is left out, whatever its position.
+   */
+  private readNamespace(serverId: string, namespace: unknown): void {
+    let text: string;
+    try {
+      text = String(namespace);
+    } catch {
+      throw new Error("its namespace isn't a string and can't be read as text");
+    }
+    if (this.namespaceWarned.has(serverId)) return;
+    this.namespaceWarned.add(serverId);
+    console.error(
+      `[mcpl] ${serverId}: a beforeInference injection's namespace isn't a string, which §10.4 requires, so it keeps the ` +
+        `injection to no channel and every agent gets it; where it names a participant, it's read as its text, ${logValue(text)}; ` +
+        'this line prints once per server while the host runs',
+    );
+  }
+
+  /**
+   * The system prompt is text, so an agent given a `system` injection reads
+   * a line in place of each of its blocks that isn't text (the agent's
+   * buildSystemPrompt). The server meant those blocks for the model, so its
+   * operator is told, once per server and namespace, as the server's
+   * injections are gathered, whichever agents are given them. The namespace
+   * is read as its text, which readNamespace has checked it has.
+   */
+  private noteBlocksNotShown(serverId: string, namespace: unknown, content: ContentBlock[]): void {
+    if (!content.some((block) => block.type !== 'text')) return;
+    const key = `${serverId}\u0000${String(namespace)}`;
+    if (this.notShownWarned.has(key)) return;
+    this.notShownWarned.add(key);
+    console.error(
+      `[mcpl] ${serverId}: a system injection in namespace ${logValue(namespace)} holds a block that isn't text, ` +
+        "which the system prompt can't carry, so an agent given the injection reads a line in place of each such block; " +
+        'this line prints once per server and namespace while the host runs',
+    );
+  }
+
 }