@animalabs/agent-framework 0.22.0 → 0.22.2

package/src/index.ts

@@ -2,7 +2,7 @@
 export * from './types/index.js';
 
 // Core classes
-export { AgentFramework, BudgetPreflightError, ResumeBlockedError } from './framework.js';
+export { AgentFramework, BudgetPreflightError, ProviderWaitNotSleptError, ResumeBlockedError } from './framework.js';
 export type { RuntimeSettingsPreview, HostModeStatus } from './framework.js';
 export { Agent } from './agent.js';
 export type { StartStreamResult } from './agent.js';
@@ -17,7 +17,7 @@ export * from './modules/index.js';
 
 // API
 export { ApiServer } from './api/server.js';
-export { McpServer } from './api/mcp-server.js';
+export { McpServer } from './api/mcp-server-core.js';
 export type {
   ApiServerConfig,
   ApiMessage,
@@ -92,7 +92,7 @@ export type { McplServerConfig } from './mcpl/index.js';
 // health probes, protocol harnesses — can dial an MCPL server exactly the
 // way the framework host does, over stdio or WebSocket)
 export { McplServerConnection } from './mcpl/index.js';
-export type { McplHostCapabilities } from './mcpl/index.js';
+export type { McplHostCapabilities, McplConnectionCloseInfo } from './mcpl/index.js';
 
 // MCPL tool lifecycle (RFC-007) and tool classes (RFC-008): the types a host
 // needs to write McplServerConfig.toolLifecycle policy and class tables, and
@@ -143,7 +143,12 @@ export type {
 } from './recovery/discord-awareness-outbox.js';
 // Live operator surgery (rollback / suppress) and its durable action log
 export { OperatorLog, OperatorActionError, defaultOperatorLogPath } from './operator-log.js';
-export type { OperatorLogEntry, OperatorLogInput, OperatorRequester } from './operator-log.js';
+export type {
+  OperatorLogEntry,
+  OperatorLogInput,
+  OperatorRequester,
+  SurgeryMarkerReceipt,
+} from './operator-log.js';
 export { createOfflineRecoveryBranch } from './recovery/offline-branch.js';
 export type {
   OfflineRecoveryBranchOptions,

package/src/mcpl/channel-registry.ts

@@ -37,8 +37,10 @@ import type { McplServerRegistry } from './server-registry.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js';
 import { expandCoreTags } from './tags.js';
-import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
 import { isVisiblyEmptyContent } from './visible-content.js';
+import { logDetail, logValue } from './log-value.js';
+import { RefusalLines } from './refusal-lines.js';
 import { CapabilityGrant } from './capability-grant.js';
 
 // ============================================================================
@@ -249,7 +251,9 @@ interface McplChannelIncomingEvent {
 function convertBlock(block: McplContentBlock): ContentBlock {
   switch (block.type) {
     case 'text':
-      return { type: 'text', text: block.text };
+      // Text that isn't a string is no text, as the request sanitizer and
+      // the visible-content check already read it.
+      return { type: 'text', text: typeof block.text === 'string' ? block.text : '' };
 
     case 'image':
       if (isInlineContradiction(block)) {
@@ -257,24 +261,24 @@ function convertBlock(block: McplContentBlock): ContentBlock {
         // closed, withhold the data (checked BEFORE the data branch).
         return { type: 'text', text: INLINE_WITHHELD_TEXT };
       }
-      if (block.uri && block.disposition) {
+      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, 'attachment on channel message') ?? '[reference]' };
       }
-      if (block.data && block.mimeType) {
+      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
         return {
           type: 'image',
           source: { type: 'base64', data: block.data, mediaType: block.mimeType },
         } as ContentBlock;
       }
-      if (block.uri) {
+      if (isFilledString(block.uri)) {
         return {
           type: 'image',
           source: { type: 'url', url: block.uri },
         } as ContentBlock;
       }
-      return { type: 'text', text: '[Image: no data]' };
+      return { type: 'text', text: isFilledString(block.data) ? '[Image: no media type]' : '[Image: no data]' };
 
     case 'audio':
       if (isInlineContradiction(block)) {
@@ -282,31 +286,43 @@ function convertBlock(block: McplContentBlock): ContentBlock {
         // closed, withhold the data (checked BEFORE the data branch).
         return { type: 'text', text: INLINE_WITHHELD_TEXT };
       }
-      if (block.uri && block.disposition) {
+      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, 'attachment on channel message') ?? '[reference]' };
       }
-      if (block.data && block.mimeType) {
+      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: '[Audio: no data]' };
+      return { type: 'text', text: isFilledString(block.data) ? '[Audio: no media type]' : '[Audio: no 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 channel message') ?? '[reference]' };
 
-    default:
+    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'}]` };
+      // 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'}]` };
+    }
   }
 }
 
+/** 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 !== '';
+}
+
 // ============================================================================
 // Channel Tool Definitions
 // ============================================================================
@@ -512,17 +528,19 @@ interface ChannelRegistryOptions {
    */
   homeChannelResolver?: (agentName: string) => string | undefined;
   /**
-   * Resolve the channel that triggered an agent's CURRENT inference turn, by
-   * agent name. This is the fix for single-TRUNK agents (the only mode
+   * Resolve an agent's channel for its CURRENT inference turn, by agent name:
+   * the turn's locus once it has one, else the channel that triggered the
+   * turn. This is the fix for single-TRUNK agents (the only mode
    * connectome-host runs — it never exposes conversation forks). A trunk agent
    * has no fork home, so without this its plain-text speech falls back to the
    * process-global `defaultPublishChannel`, which tracks the most-recent inbound
    * across ALL channels and misroutes a reply to whichever channel last spoke
-   * under concurrency (item-3 redux). The framework tracks the triggering
-   * channel of the live turn per-agent and exposes it here; resolves to
-   * undefined for a heartbeat / no-trigger turn, which correctly keeps the
-   * global fallback. Consulted AFTER `homeChannelResolver` (a fork's home always
-   * wins), BEFORE `defaultPublishChannel`.
+   * under concurrency (item-3 redux). The framework keeps both on the live
+   * turn's routing state and exposes them here. For a heartbeat / no-trigger
+   * turn it resolves to undefined until the turn's locus is resolved, so that
+   * resolution takes the global fallback, which the turn then keeps.
+   * Consulted AFTER `homeChannelResolver` (a fork's home always wins), BEFORE
+   * `defaultPublishChannel`.
    */
   activeChannelResolver?: (agentName: string) => string | undefined;
 }
@@ -577,6 +595,10 @@ export class ChannelRegistry {
   /** Registered channels, keyed by `{serverId}:{channelId}`. */
   private channels = new Map<string, ChannelEntry>();
 
+  /** Holds back repeats of the line for a message refused because its
+   *  channel isn't registered (RefusalLines). */
+  private unknownChannelLines = new RefusalLines();
+
   /**
    * Most-recently-known label per channelId, replayed from
    * `CHANNEL_LABEL_HISTORY_LOG_ID` (last sighting wins) and kept current by
@@ -848,6 +870,45 @@ export class ChannelRegistry {
     });
   }
 
+  /**
+   * A coalesced message the host refused. Until now the host said nothing, so
+   * a dropped message (agent-framework#266: every Discord message with a
+   * screenshot) left no trace where operators look. The sender gets the
+   * per-message result this lane gives: `coalesce_invalid` for a malformed
+   * item, or the thrown error's message for anything else. `answered` is the
+   * code that result stands for (-32602 for `coalesce_invalid`), and the
+   * reason follows it (coalesceRejectionReason): `coalesce-failed` when the
+   * host itself failed, `coalesce-invalid` when the sender's item was
+   * refused, with the failing `field` and the error's message as `detail`.
+   * The line prints the ids the sender sent, whatever their type; the trace
+   * carries them when they are strings.
+   */
+  private traceCoalesceRejection(
+    serverId: string,
+    message: { channelId?: unknown; messageId?: unknown } | null | undefined,
+    error: { field?: unknown; message: string },
+    answered: number,
+  ): void {
+    const reason = coalesceRejectionReason(answered);
+    const field = typeof error.field === 'string' && error.field ? error.field : undefined;
+    const channelId = typeof message?.channelId === 'string' ? message.channelId : '';
+    const messageId = typeof message?.messageId === 'string' && message.messageId ? message.messageId : undefined;
+    console.error(
+      `[channel-incoming-rejected] server=${serverId} channel=${logValue(message?.channelId ?? '')} ` +
+      `messageId=${logValue(message?.messageId ?? '')} ` +
+      `reason=${reason}${field ? ` field=${logValue(field)}` : ''}: ${logDetail(error.message)}`,
+    );
+    this.emitTraceFn({
+      type: 'mcpl:channel-incoming-rejected',
+      serverId,
+      channelId,
+      ...(messageId ? { messageId } : {}),
+      reason,
+      ...(field ? { field } : {}),
+      detail: error.message,
+    });
+  }
+
   /**
    * Handle `channels/incoming` from a server.
    *
@@ -864,10 +925,20 @@ export class ChannelRegistry {
     for (const message of params.messages) {
       if (!message || typeof message.channelId !== 'string' || !message.channelId
         || typeof message.messageId !== 'string' || !message.messageId) {
+        // The same gate as admission below: with no coalescer wired, a
+        // message carrying `coalesce` is handled uncoalesced, and refused as
+        // any uncoalesced message without an identity is.
+        const coalescedItem = message?.coalesce !== undefined && !!this.handleCoalescedIncoming;
+        if (coalescedItem) {
+          this.traceCoalesceRejection(serverId, message, {
+            field: typeof message.channelId !== 'string' || !message.channelId ? 'channelId' : 'messageId',
+            message: 'a coalesced message needs a channelId and a messageId',
+          }, -32602);
+        }
         results.push({
           messageId: typeof message?.messageId === 'string' ? message.messageId : '',
           accepted: false,
-          reason: message?.coalesce !== undefined ? 'coalesce_invalid' : 'invalid channel/message identity',
+          reason: coalescedItem ? 'coalesce_invalid' : 'invalid channel/message identity',
         });
         continue;
       }
@@ -899,11 +970,24 @@ export class ChannelRegistry {
       // routable entry rather than an open self-attested one.
       const incomingKey = `${serverId}:${message.channelId}`;
       if (!this.channels.has(incomingKey)) {
+        // Loud, coalesced or not, like every other refusal of a message, but
+        // at most once a minute per channel (RefusalLines): a server that
+        // never registered a busy channel would otherwise print a line for
+        // every message in it. Every refusal is traced.
+        const held = this.unknownChannelLines.admit(serverId, message.channelId);
+        if (held !== null) {
+          console.error(
+            `[channel-incoming-rejected] server=${serverId} channel=${logValue(message.channelId)} ` +
+            `messageId=${logValue(message.messageId)} reason=unknown-channel ` +
+            `(not registered, §14.5${held ? `; ${held} more since the last line` : ''})`,
+          );
+        }
         this.emitTraceFn({
           type: 'mcpl:channel-incoming-rejected',
           serverId,
           channelId: message.channelId,
-          reason: 'unknown channel — not registered (§14.5)',
+          messageId: message.messageId,
+          reason: 'unknown-channel',
         });
         results.push({
           messageId: message.messageId,
@@ -921,7 +1005,7 @@ export class ChannelRegistry {
       // shows the model nothing would wake it with no visible cause.
       const emptyAllowed = coalesced && (message.coalesce as { retract?: unknown } | null)?.retract === true;
       const rejectEmpty = () => {
-        console.error(`[channel-incoming-rejected] server=${serverId} channel=${message.channelId} messageId=${message.messageId} reason=empty-content`);
+        console.error(`[channel-incoming-rejected] server=${serverId} channel=${logValue(message.channelId)} messageId=${logValue(message.messageId)} reason=empty-content`);
         this.emitTraceFn({
           type: 'mcpl:channel-incoming-rejected',
           serverId,
@@ -935,10 +1019,14 @@ export class ChannelRegistry {
         // RFC-006 §13: malformed content on a coalesced item is that item's
         // failure, not the batch's — check the shape before converting.
         try {
-          validateCoalescedContent(message.content, undefined, { allowEmpty: emptyAllowed });
+          validateCoalescedContent(message.content, { allowEmpty: emptyAllowed });
         } catch (error) {
           if (error instanceof EmptyContentError) rejectEmpty();
-          else results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+          else {
+            // Answered coalesce_invalid whatever the error's code: -32602.
+            this.traceCoalesceRejection(serverId, message, error as Error & { field?: string }, -32602);
+            results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+          }
           continue;
         }
       }
@@ -970,8 +1058,11 @@ export class ChannelRegistry {
       // Determine whether to trigger inference
       let triggerInference = true;
       if (this.shouldTriggerInference) {
-        const textContent = message.content
-          .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+        // The text the agent's context gets, as the push lane's filter reads
+        // it: the converted text blocks, a placeholder or reference stub
+        // among them, and a text block's non-string text as empty text.
+        const textContent = convertedContent
+          .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
           .map((b) => b.text)
           .join('\n');
         triggerInference = this.shouldTriggerInference(
@@ -1014,7 +1105,10 @@ export class ChannelRegistry {
           if (result.accepted) markAccepted();
           results.push(result);
         } catch (error) {
-          const err = error as Error & { code?: number };
+          const err = error as Error & { code?: number; field?: string };
+          // -32602 is answered coalesce_invalid; anything else as its message,
+          // a plain Error standing for an internal error (-32603).
+          this.traceCoalesceRejection(serverId, message, err, typeof err.code === 'number' ? err.code : -32603);
           results.push({
             messageId: message.messageId,
             accepted: false,
@@ -1361,8 +1455,9 @@ export class ChannelRegistry {
 
     // Resolve the outbound locus the SAME way routeSpeech does, so the agent is
     // told the channel its speech will actually land in: a conversation fork's
-    // home channel, else this turn's triggering channel (single trunk agent —
-    // item-3 redux), else the global default (heartbeats). Without this, a fork
+    // home channel, else this turn's channel (single trunk agent — item-3
+    // redux: its locus, else its triggering channel), else the global default
+    // (heartbeats). Without this, a fork
     // was advertised the global locus but published somewhere else; and a trunk
     // agent was told the wrong channel under concurrency.
     const home = agentName ? this.homeChannelResolver?.(agentName) : undefined;
@@ -3018,7 +3113,7 @@ export class ChannelRegistry {
       try {
         await this.openChannelNow(entry, 'opened-by-delivery');
         console.error(
-          `[routeSpeech] ${conversationId}: locus ${channelId} was closed — opened by delivery (speech implies engagement)`,
+          `[routeSpeech] ${conversationId}: locus ${logValue(channelId)} was closed — opened by delivery (speech implies engagement)`,
         );
         this.emitTraceFn({
           type: 'mcpl:channel-opened-by-send',
@@ -3071,7 +3166,7 @@ export class ChannelRegistry {
       return fail(channelId, `server "${entry.serverId}" reported delivered:false for "${channelId}"`);
     }
 
-    console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
+    console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${logValue(channelId)} (server=${entry.serverId}, delivered=${delivered})`);
     this.emitTraceFn({
       type: 'mcpl:speech-routed',
       conversationId,

package/src/mcpl/feature-set-manager.ts

@@ -19,6 +19,7 @@ import {
   UNKNOWN_FEATURE_SET,
 } from './errors.js';
 import { isKnownCapabilityPath } from './capability-grant.js';
+import { logValue } from './log-value.js';
 
 // ============================================================================
 // Error Class
@@ -222,7 +223,7 @@ export class FeatureSetManager {
       ): void => {
         const selectedByConfig = state.enabled.delete(name);
         const note = explicitSelection && selectedByConfig ? ' — overrides enabledFeatureSets' : '';
-        console.error(`[mcpl] ${serverId}/${name} disabled: ${detail}${note}`);
+        console.error(`[mcpl] ${serverId}/${logValue(name)} disabled: ${detail}${note}`);
         this.emitTrace?.({
           type: 'mcpl:feature-set-disabled',
           serverId,
@@ -240,14 +241,14 @@ export class FeatureSetManager {
         }
         const unknown = uses.filter((u) => typeof u !== 'string' || !isKnownCapabilityPath(u));
         if (unknown.length > 0) {
-          disable(name, 'invalid_uses', `invalid_uses (§6.4 — unrecognized: ${unknown.join(', ')})`, {
+          disable(name, 'invalid_uses', `invalid_uses (§6.4 — unrecognized: ${unknown.map(logValue).join(', ')})`, {
             unrecognized: unknown.map((u) => (typeof u === 'string' ? u : JSON.stringify(u))),
           });
           continue;
         }
         const missing = (uses as string[]).filter((u) => !grant.has(u));
         if (missing.length > 0) {
-          disable(name, 'missing_capabilities', `missing capabilities ${missing.join(', ')} (§6.4)`, { missing });
+          disable(name, 'missing_capabilities', `missing capabilities ${missing.map(logValue).join(', ')} (§6.4)`, { missing });
         }
       }
     }

package/src/mcpl/index.ts

@@ -107,6 +107,8 @@ export {
 
 // Server connection and registry
 export { McplServerConnection } from './server-connection.js';
+export type { McplConnectionCloseInfo } from './server-connection.js';
+export type { TransportCloseInfo } from './transport.js';
 export { McplServerRegistry, type McplCapabilityQuery } from './server-registry.js';
 
 // Feature set management (permission layer)

package/src/mcpl/log-value.ts

@@ -0,0 +1,116 @@
+/**
+ * A value a connected server chose, as one field of a host log line.
+ *
+ * The rejection lines (`[channel-incoming-rejected]`, `[push-event-rejected]`)
+ * and the other host lines that name a server's own identifiers are read a
+ * line at a time, by eye and with grep. Printed raw, an identifier carrying a
+ * line break prints a second line that reads as another host record, about
+ * another server; one carrying a space can pose as another field of the same
+ * line; and one carrying `=` can hold a lookalike field (`reason=…`) that a
+ * search for that field finds before the real one.
+ *
+ * A plain token (visible characters only: no space, quote, backslash or `=`)
+ * prints as it is, so ordinary ids read and grep as they always have.
+ * Anything else prints as a JSON string with every `=` and every invisible
+ * character escaped: controls, format and bidi characters, line and paragraph
+ * separators, every space (the plain one included), default-ignorable
+ * characters (Hangul fillers, the combining grapheme joiner, variation
+ * selectors) and the blank Braille pattern. So it stays one field on one line,
+ * a reader that splits on whitespace keeps it whole, no field holds a raw
+ * `=` (so every `=` before a line's free-text tail, `logDetail`, belongs to
+ * a real field), and `JSON.parse` of a quoted value that isn't cut gives
+ * back exactly what was sent. Escaping rather than stripping keeps two
+ * identifiers that differ in invisible characters within the units a line
+ * prints from printing alike; canonically equivalent or lookalike
+ * identifiers still can.
+ *
+ * A value longer than 256 UTF-16 units is cut, so one value can't make a line
+ * long: it prints quoted, as its first 256 units (255 when the 256th is a
+ * high surrogate, so a pair is never split), each at most six characters once
+ * escaped, followed by `…(N)`, N being its full length. `JSON.parse` of the
+ * quoted part gives back those first units. A cut value always opens with a
+ * quote, and its marker follows the closing quote. A plain token never holds
+ * a quote, and a quoted value that isn't cut ends at its closing quote, so
+ * only a value that was cut prints as one.
+ *
+ * A value that isn't a string prints as its JSON text, quoted as any text is
+ * that isn't a plain token: the number 5 prints as `5`, and `{"toString":1}`
+ * as `"{\"toString\":1}"`. So the number 5 and the string "5" print alike, as
+ * they name the same message. A number JSON writes as `null` (NaN, Infinity)
+ * prints as `String()` of it. Converting a value never throws: one JSON can't
+ * write prints as `String()` of it, or else as its object tag, and one none
+ * of those can read (a revoked Proxy) as `[unprintable]`.
+ */
+export function logValue(value: unknown): string {
+  return printed(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
+ * array"`. It prints as `logValue` prints a field, cut the same way, except
+ * that a plain space and `=` stay raw, for reading. That is safe because the
+ * text is the host's (an error the host raised), not an id a sender chose,
+ * and every real field of the line comes before it.
+ */
+export function logDetail(value: unknown): string {
+  return printed(textOf(value), DETAIL);
+}
+
+/** How a form prints: the text that stands as it is, and what it escapes. */
+interface Form {
+  plain: RegExp;
+  escaped: RegExp;
+}
+
+const FIELD: Form = {
+  plain: /^[^"\\=\p{C}\p{Z}\p{Default_Ignorable_Code_Point}\u2800]+$/u,
+  escaped: /[=\p{C}\p{Z}\p{Default_Ignorable_Code_Point}\u2800]/gu,
+};
+
+const DETAIL: Form = {
+  plain: /^[^"\\\p{C}\p{Z}\p{Default_Ignorable_Code_Point}\u2800]+$/u,
+  escaped: /(?! )[\p{C}\p{Z}\p{Default_Ignorable_Code_Point}\u2800]/gu,
+};
+
+/** The most of a value's text a line prints, in UTF-16 units. */
+const MAX_PRINTED = 256;
+
+function printed(text: string, form: Form): string {
+  if (text.length <= MAX_PRINTED) return form.plain.test(text) ? text : quoted(text, form);
+  let end = MAX_PRINTED;
+  const last = text.charCodeAt(end - 1);
+  if (last >= 0xd800 && last <= 0xdbff) end--;
+  return `${quoted(text.slice(0, end), form)}…(${text.length})`;
+}
+
+function quoted(text: string, form: Form): string {
+  // JSON escapes C0 controls, quotes and backslashes and leaves the rest of
+  // the escaped set raw: escape those here, per UTF-16 unit, as JSON does.
+  return JSON.stringify(text).replace(form.escaped, escapeUnits);
+}
+
+function textOf(value: unknown): string {
+  if (typeof value === 'string') return value;
+  // JSON writes a non-finite number as null, which reads as a missing value.
+  if (typeof value === 'number' && !Number.isFinite(value)) return String(value);
+  const readers = [
+    () => JSON.stringify(value) ?? String(value),
+    () => String(value),
+    () => Object.prototype.toString.call(value),
+  ];
+  for (const read of readers) {
+    try {
+      return read();
+    } catch {
+      // the next reader
+    }
+  }
+  return '[unprintable]';
+}
+
+function escapeUnits(chars: string): string {
+  let out = '';
+  for (let i = 0; i < chars.length; i++) out += `\\u${chars.charCodeAt(i).toString(16).padStart(4, '0')}`;
+  return out;
+}

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

@@ -21,13 +21,13 @@
  *
  * Three modes, mirroring proseRouting:
  *  - explicit: parse `>>` prefixes. A fresh turn's stream starts suppressed;
- *              one that resumes a turn starts at the turn's destination, and
- *              each round's end returns the stream to it (retarget).
- *  - hybrid:   parse `>>>` envelopes, with the frozen turn locus as the
+ *              a later stream of the turn starts at the turn's destination,
+ *              and each round's end returns the stream to it (retarget).
+ *  - hybrid:   parse `>>>` envelopes, with the turn's locus as the
  *              fallback. An envelope with no target, or `>>>skip_reply`,
  *              holds back what follows until a later `>>>` names a target.
  *  - locus:    NO prefix parsing (locus mode's `>>` lines are plain text);
- *              everything streams to the frozen turn locus.
+ *              everything streams to the turn's locus.
  */
 
 export interface RoutedDelta {
@@ -52,9 +52,9 @@ export class ProseStreamRouter {
     private opts: {
       /** explicit parses `>>`; hybrid parses `>>>` while retaining locus fallback. */
       mode: 'explicit' | 'hybrid' | 'locus';
-      /** Initial destination: the frozen turn locus (locus and hybrid mode); in
+      /** Initial destination: the turn's locus (locus and hybrid mode); in
        *  explicit mode, null on a fresh turn, or the turn's destination on a
-       *  stream that resumes one. */
+       *  later stream of the turn. */
       initialTarget: string | null;
       /** Resolve a `>>spec` to a channelId, or null (unresolved/ambiguous). */
       resolve: (spec: string) => string | null;