@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/mcpl/inbound-source.ts

@@ -0,0 +1,156 @@
+/**
+ * Where an inbound item came from, decided once at Agent Framework's
+ * ingestion boundary and stored on the message as `metadata.inboundSource`.
+ *
+ * A consumer of where an item came from reads this one value
+ * (readInboundSource) rather than re-deriving identity from the lane the
+ * item happened to arrive on, and compares conversations with
+ * conversationKey. It is frozen when the host ACCEPTS the item. A coalesced
+ * occurrence (RFC-006) carries the value stamped at its acceptance through
+ * deferral, fan-out and replay, so a later rename, reconnect or re-render
+ * never rewrites where an old item says it came from.
+ *
+ * The field is framework-owned. It is written after any adapter-supplied
+ * metadata is spread, so an adapter cannot supply or spoof it, and one a
+ * module's messages carry is dropped (adapter `origin` objects already use a
+ * free-form `source` string, which is why this is not called `source`).
+ *
+ * Facts only, no policy: whether an item is a body, an edit or a deletion
+ * stays in its tags (`chat:edited`, `chat:deleted`); `deferred` and
+ * `materialized` record what RFC-006 did with it. Nothing here is a version
+ * key: `eventId` is present only when the producer supplied one.
+ */
+
+/** The MCPL admission lane that accepted an item. Its contract decides what
+ *  an `eventId` is worth: `push/event` deduplicates by eventId, and RFC-006
+ *  coalesced admission (`coalesced: true`) guarantees stable retries and
+ *  distinct versions; a `channels/incoming` eventId outside coalescing is
+ *  adapter-supplied with no such guarantee. */
+export type InboundLane = 'channels/incoming' | 'push/event';
+
+/** An item that belongs to a registered channel. */
+export interface InboundChannelSource {
+  kind: 'channel';
+  /** The admission lane that accepted it (see InboundLane). */
+  lane: InboundLane;
+  /** Accepted through RFC-006 coalesced admission. */
+  coalesced?: true;
+  /** MCPL server (connection) id the item arrived through, as the host names it. */
+  serverId: string;
+  /** RFC-006 endpoint binding of that connection at acceptance. A recipe that
+   *  later points the same server id at a different endpoint gets a
+   *  different binding, so old items never acquire the new endpoint's identity. */
+  binding: string;
+  /** The registered canonical channel id (on the push lane: the composite id
+   *  the host derived from `origin`, never the adapter's raw platform id). */
+  channelId: string;
+  /** Thread within the channel, when the adapter supplied one. */
+  threadId?: string;
+  /** The platform message this item is (or, for an edit/delete, refers to). */
+  messageId?: string;
+  /** The producer's occurrence id, when it supplied one. */
+  eventId?: string;
+  /** The channel's human label when the host accepted the item. */
+  label?: string;
+  /** Message this one replies to, when the adapter supplied a reply edge. */
+  replyTo?: string;
+  /** Host acceptance time (epoch ms). */
+  acceptedAt: number;
+  /** The adapter's own timestamp for the item, verbatim. */
+  sourceTimestamp?: string;
+  /** RFC-006: accepted as a deferred notification (body rendered later). */
+  deferred?: true;
+  /** RFC-006: this delivery carries the materialized (rendered) body. */
+  materialized?: true;
+}
+
+/** An MCPL push that names no channel (heartbeats, timers, feature-set events). */
+export interface InboundUnscopedSource {
+  kind: 'unscoped';
+  lane: 'push/event';
+  coalesced?: true;
+  serverId: string;
+  binding: string;
+  eventId?: string;
+  acceptedAt: number;
+  sourceTimestamp?: string;
+  deferred?: true;
+  materialized?: true;
+}
+
+/** Conversational input from a non-channel surface (console, TUI, API). */
+export interface InboundSurfaceSource {
+  kind: 'surface';
+  /** The surface's name as its module reported it (e.g. `tui`, `api`). */
+  surface: string;
+  acceptedAt: number;
+}
+
+export type InboundSource = InboundChannelSource | InboundUnscopedSource | InboundSurfaceSource;
+
+/**
+ * Told once per inbound acceptance, with that acceptance's envelope: when an
+ * ordinary item reaches the framework, and when the RFC-006 coalescer admits
+ * an occurrence (deferred work included). Deliveries that reuse a frozen
+ * envelope (replay, fan-out, materialization, corrections) are not
+ * acceptances and are not reported. Observation only: the framework contains
+ * and reports a throw, which never affects delivery.
+ */
+export interface InboundAcceptanceObserver {
+  inboundAccepted(source: InboundSource): void;
+}
+
+/** Metadata key the framework stamps. */
+export const INBOUND_SOURCE_KEY = 'inboundSource';
+
+const isText = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+const optionalText = (v: unknown): boolean => v === undefined || isText(v);
+const optionalTrue = (v: unknown): boolean => v === undefined || v === true;
+
+/**
+ * Read a stored item's source back from its metadata, validating every field
+ * a consumer relies on: identity strings are non-empty strings, `acceptedAt`
+ * is a finite number, flags are exactly `true` when present, and the lane is
+ * one this version knows. Anything else (older messages, a shape this
+ * version does not recognize, a damaged import) is undefined — never a guess.
+ */
+export function readInboundSource(metadata: unknown): InboundSource | undefined {
+  if (!metadata || typeof metadata !== 'object') return undefined;
+  const raw = (metadata as Record<string, unknown>)[INBOUND_SOURCE_KEY];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const s = raw as Record<string, unknown>;
+  if (typeof s.acceptedAt !== 'number' || !Number.isFinite(s.acceptedAt)) return undefined;
+  if (s.kind === 'surface') {
+    return isText(s.surface) ? (s as unknown as InboundSurfaceSource) : undefined;
+  }
+  const effectFlags = optionalTrue(s.coalesced) && optionalTrue(s.deferred) && optionalTrue(s.materialized);
+  if (!isText(s.serverId) || !isText(s.binding) || !effectFlags) return undefined;
+  if (!optionalText(s.eventId) || !optionalText(s.sourceTimestamp)) return undefined;
+  if (s.kind === 'channel') {
+    if (s.lane !== 'channels/incoming' && s.lane !== 'push/event') return undefined;
+    if (!isText(s.channelId)) return undefined;
+    for (const field of ['threadId', 'messageId', 'label', 'replyTo'] as const) {
+      if (!optionalText(s[field])) return undefined;
+    }
+    return s as unknown as InboundChannelSource;
+  }
+  if (s.kind === 'unscoped') {
+    return s.lane === 'push/event' ? (s as unknown as InboundUnscopedSource) : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * The conversation an item belongs to, as a comparable key: server + channel
+ * + thread for a channel item, the surface for console input. Undefined for an
+ * unscoped push, which belongs to no conversation. The parts are server-chosen
+ * strings, so they are encoded as a JSON array, never joined with a separator
+ * one of them could contain: two keys are equal only for the same parts.
+ */
+export function conversationKey(source: InboundSource): string | undefined {
+  if (source.kind === 'channel') {
+    return JSON.stringify(['channel', source.serverId, source.channelId, source.threadId ?? null]);
+  }
+  if (source.kind === 'surface') return JSON.stringify(['surface', source.surface]);
+  return undefined;
+}

package/src/mcpl/index.ts

@@ -106,7 +106,7 @@ export {
 } from './errors.js';
 
 // Server connection and registry
-export { McplServerConnection } from './server-connection.js';
+export { McplServerConnection, McplRequestError } 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';
@@ -159,6 +159,15 @@ export { InferenceRouter } from './inference-router.js';
 // Channel registry (channel lifecycle, incoming messages, synthesized tools)
 export { ChannelRegistry } from './channel-registry.js';
 
+// Inbound source envelope: where each accepted item came from, stamped once
+export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey } from './inbound-source.js';
+export type {
+  InboundSource,
+  InboundChannelSource,
+  InboundUnscopedSource,
+  InboundSurfaceSource,
+} from './inbound-source.js';
+
 // Per-channel conversation routing (fork-per-channel agents)
 /** @deprecated Per-channel conversation routing is deprecated and will be removed (anima-research/agent-framework#235). */
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './conversation-router.js';

package/src/mcpl/inference-router.ts

@@ -8,7 +8,14 @@
  * Spec reference: Section 11 (Server-Initiated Inference).
  */
 
-import type { Membrane, ContentBlock, NormalizedRequest } from '@animalabs/membrane';
+import type {
+  Membrane,
+  ContentBlock,
+  NormalizedRequest,
+  NormalizedResponse,
+  StopReason,
+  ToolCall,
+} from '@animalabs/membrane';
 
 import type {
   McplInferenceRequestParams,
@@ -60,6 +67,100 @@ function wildcardMatch(pattern: string, name: string): boolean {
   return true;
 }
 
+// ============================================================================
+// Results
+// ============================================================================
+
+/**
+ * The inference/request result for a completed inference, the same for both
+ * modes: the response's text, the model that served it, why it stopped, and
+ * its usage.
+ *
+ * A response MCPL can't report as a completion throws, and is answered with
+ * the error: one the provider ended with an error, one where the model wrote a
+ * tool call, since inference/request offers the model none, and one with a
+ * stop reason FinishReason has no value for (see finishReasonFor).
+ */
+function resultFrom(response: NormalizedResponse, routedModel: string): McplInferenceRequestResult {
+  // A provider can end an inference with finish_reason 'error' and no error
+  // object. membrane 0.5.87's OpenAI-style adapters fail a stream on a frame
+  // that carries one, as OpenRouter's mid-stream error does, but pass the token
+  // alone through, and membrane, having no stop reason for it, normalizes it
+  // to end_turn and keeps it as providerReason.
+  if (response.details.stop.providerReason === 'error') {
+    throw new Error("The provider ended the inference with an error (finish_reason 'error')");
+  }
+  // membrane's yielding stream lists a native tool call in toolCalls only
+  // when the stop was tool_use, so a tool_use block cut off by another stop is
+  // only in the content. membrane's complete() lists every tool_use block in
+  // toolCalls, whatever the stop.
+  const toolUses = response.content.filter((b: ContentBlock): b is ContentBlock & { type: 'tool_use' } => b.type === 'tool_use');
+  if (response.toolCalls.length > 0 || toolUses.length > 0) {
+    throw toolCallError(response.toolCalls.length > 0 ? response.toolCalls : toolUses);
+  }
+  // In XML tool mode membrane reads tool calls out of the text. Markup it
+  // reads no call from still shows in how the output ended: with a tool-call
+  // block still open (a call cut off at max_tokens, or an opening tag written
+  // in prose), or at `</function_calls>`, the stop sequence XML tool mode adds
+  // so that it can run calls (inference/request asks for no stop sequence of
+  // its own). Either way the markup is in the text.
+  if (response.details.stop.unclosedToolBlock) {
+    throw new Error("The model's output ended with a tool-call block still open, and inference/request offers no tools");
+  }
+  if (response.details.stop.triggeredSequence === '</function_calls>') {
+    throw new Error('The model wrote tool-call markup, and inference/request offers no tools');
+  }
+  return {
+    content: response.content
+      .filter((b: ContentBlock): b is ContentBlock & { type: 'text' } => b.type === 'text')
+      .map((b) => b.text)
+      .join(''),
+    // Spec §11.3: the actual model used, which can differ from the routed one
+    // where routing or fallback applies. When membrane names none, the routed
+    // model is the only one there is to report.
+    model: actualModelOf(response) ?? routedModel,
+    finishReason: finishReasonFor(response.stopReason),
+    usage: {
+      inputTokens: response.usage.inputTokens,
+      outputTokens: response.usage.outputTokens,
+    },
+  };
+}
+
+/**
+ * The model membrane says served the response, or undefined when it names
+ * none. membrane's type says it always names one, but some of its adapters
+ * pass the provider's own value through as it is, which can be empty.
+ */
+function actualModelOf(response: NormalizedResponse): string | undefined {
+  return response.details.model.actual || undefined;
+}
+
+/**
+ * MCPL's finishReason for membrane's stop reason. Spec §11.3 closes
+ * FinishReason at these three, so any other stop throws: `end_turn` for a
+ * refusal, or for a turn membrane's resumption guard ended (`no_progress`,
+ * `round_limit`), would tell the server the model had finished.
+ */
+function finishReasonFor(stopReason: StopReason): McplInferenceRequestResult['finishReason'] {
+  switch (stopReason) {
+    case 'end_turn':
+    case 'max_tokens':
+    case 'stop_sequence':
+      return stopReason;
+    default:
+      throw new Error(
+        `The inference ended with stop reason '${stopReason}', for which inference/request has no finishReason`,
+      );
+  }
+}
+
+/** The error for a model that called a tool, which inference/request doesn't offer. */
+function toolCallError(calls: Array<Pick<ToolCall, 'name'>>): Error {
+  const names = calls.map((call) => call.name).join(', ');
+  return new Error(`The model called a tool (${names}), and inference/request offers none`);
+}
+
 // ============================================================================
 // Constants
 // ============================================================================
@@ -101,9 +202,10 @@ export class InferenceRouter {
    * 1. Validate feature set
    * 2. Check loop prevention (reject if inside a hook)
    * 3. Resolve model from routing policy
-   * 4. Build membrane request and run inference
-   * 5. Optionally stream chunks
-   * 6. Return result via responder
+   * 4. Build membrane request
+   * 5. Run inference, streaming its visible text as chunks when asked
+   * 6. Answer with the result, or with the error for any ending that isn't
+   *    a completion
    */
   async handleInferenceRequest(
     serverId: string,
@@ -161,49 +263,46 @@ 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 streamed = chunkRequestId != null;
+
     try {
-      // 5. Run inference
-      if (params.stream && this.sendChunkFn && responder.requestId != null) {
-        // Streaming mode
-        await this.handleStreaming(serverId, model, request, responder);
-      } else {
-        // Non-streaming mode
-        const response = await this.membrane.complete(request);
-
-        // Extract text content from response
-        const contentText = response.content
-          .filter((b: ContentBlock): b is ContentBlock & { type: 'text' } => b.type === 'text')
-          .map((b: ContentBlock & { type: 'text' }) => b.text)
-          .join('');
-
-        const result: McplInferenceRequestResult = {
-          content: contentText,
-          model,
-          finishReason: this.mapStopReason(response.stopReason),
-          usage: {
-            inputTokens: response.usage.inputTokens,
-            outputTokens: response.usage.outputTokens,
-          },
-        };
-
-        // Emit trace: inference complete
-        this.emitTraceFn({
-          type: 'mcpl:inference_complete',
-          serverId,
-          model,
-          inputTokens: result.usage.inputTokens,
-          outputTokens: result.usage.outputTokens,
-        });
-
-        responder.respond(result);
-      }
+      // 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.membrane.complete(request);
+
+      // 6. Answer
+      const result = resultFrom(response, model);
+      const actualModel = actualModelOf(response);
+
+      this.emitTraceFn({
+        type: 'mcpl:inference_complete',
+        serverId,
+        // The routed model, as inference_start has it. actualModel is the one
+        // the result reports, left out when membrane named none.
+        model,
+        ...(actualModel !== undefined ? { actualModel } : {}),
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        streamed,
+      });
+
+      responder.respond(result);
     } catch (err) {
-      // Emit trace: inference failed
+      // Every ending that isn't a completion lands here, in either mode:
+      // membrane's error, a stream that stopped early, a tool call, or a
+      // stop FinishReason can't name. The answer is the JSON-RPC error, never
+      // a result carrying what arrived.
       this.emitTraceFn({
         type: 'mcpl:inference_fail',
         serverId,
         model,
         error: err instanceof Error ? err.message : String(err),
+        streamed,
       });
 
       responder.respondError(
@@ -263,73 +362,49 @@ export class InferenceRouter {
   // ==========================================================================
 
   /**
-   * Handle streaming inference by sending chunks back to the server.
+   * Run the inference as a stream, sending each visible text delta to the
+   * server as an inference/chunk, and return membrane's response once the
+   * stream completes.
    *
-   * Uses membrane.streamYielding when available; falls back to non-streaming
-   * membrane.complete otherwise.
+   * Every other ending throws, so the request is answered with the error
+   * rather than with the text that arrived: membrane's `error`, an `aborted`
+   * stream, a stream that ends with no terminal event, and `tool-calls`. A
+   * stream that has yielded tool calls waits for their results until it is
+   * cancelled, and inference/request offers the model no tools. Leaving the
+   * loop by return or throw calls the stream's return(), which cancels it,
+   * so nothing keeps running once the request is answered.
    */
-  private async handleStreaming(
+  private async streamResponse(
     serverId: string,
-    model: string,
     request: NormalizedRequest,
-    responder: Responder,
-  ): Promise<void> {
-    const requestId = responder.requestId!;
-
-    // Check if streamYielding is available on the membrane instance.
-    // We use streamYielding to iterate events and forward text deltas as chunks.
+    requestId: string | number,
+  ): Promise<NormalizedResponse> {
     const stream = this.membrane.streamYielding(request);
-    let chunkIndex = 0;
-    let fullContent = '';
+    let index = 0;
 
     for await (const event of stream) {
-      if (event.type === 'tokens' && 'content' in event) {
-        const delta = (event as { type: 'tokens'; content: string }).content;
-        fullContent += delta;
-        this.sendChunkFn!(serverId, {
-          requestId,
-          index: chunkIndex++,
-          delta,
-        });
+      switch (event.type) {
+        case 'tokens':
+          // Only text membrane marks visible is sent, which leaves out
+          // thinking and tool-call markup. The result's content is the
+          // response's text blocks, which membrane parses on its own, so in
+          // XML tool mode the chunks can miss text the content holds: prose
+          // 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 });
+          }
+          break;
+        case 'tool-calls':
+          throw toolCallError(event.calls);
+        case 'complete':
+          return event.response;
+        case 'error':
+          throw event.error;
+        case 'aborted':
+          throw new Error(`The inference stopped before it finished (${event.reason})`);
       }
     }
-
-    // After streaming completes, send the final result
-    const result: McplInferenceRequestResult = {
-      content: fullContent,
-      model,
-      finishReason: 'end_turn',
-      usage: { inputTokens: 0, outputTokens: 0 },
-    };
-
-    this.emitTraceFn({
-      type: 'mcpl:inference_complete',
-      serverId,
-      model,
-      streamed: true,
-    });
-
-    responder.respond(result);
-  }
-
-  // ==========================================================================
-  // Private: Helpers
-  // ==========================================================================
-
-  /**
-   * Map membrane's stopReason string to MCPL's finishReason enum.
-   */
-  private mapStopReason(
-    stopReason: string | undefined,
-  ): 'end_turn' | 'max_tokens' | 'stop_sequence' {
-    switch (stopReason) {
-      case 'max_tokens':
-        return 'max_tokens';
-      case 'stop_sequence':
-        return 'stop_sequence';
-      case 'end_turn':
-      default:
-        return 'end_turn';
-    }
+    throw new Error('The inference stream ended without a result');
   }
 }

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;