@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/mcpl/conversation-router.ts

@@ -34,6 +34,7 @@
  * follow-up.
  */
 
+import { NOTICE_TAG } from '../notice-tags.js';
 import { createHash } from 'node:crypto';
 import type { ContextStrategy } from '@animalabs/context-manager';
 import type { ChannelDescriptor } from './types.js';
@@ -144,7 +145,7 @@ export type RoutingDecision =
 const DEFAULT_IDLE_TTL_MS = 12 * 60 * 60 * 1000;
 
 export const DEFAULT_CLOSURE_PROMPT =
-  '[system] This engagement is closing due to inactivity. Finalize your ' +
+  `[${NOTICE_TAG.system}] This engagement is closing due to inactivity. Finalize your ` +
   'work: post any promised results to the channel and record outstanding ' +
   'threads as unresolved. Do not ask follow-up questions.';
 

package/src/mcpl/convert-block.ts

@@ -4,6 +4,7 @@
  * about a malformed block holds on all three.
  */
 
+import { NOTICE_TAG } from '../notice-tags.js';
 import type { ContentBlock } from '@animalabs/membrane';
 import {
   AUDIO_NO_DATA_TEXT,
@@ -18,6 +19,7 @@ import {
 } from './references.js';
 import { NON_STRING_TEXT_PLACEHOLDER } from './visible-content.js';
 import type { McplContentBlock } from './types.js';
+import { markNoticeOpenings } from '../supplied-text.js';
 
 /**
  * Convert a single MCPL wire-format content block to a membrane ContentBlock.
@@ -50,7 +52,7 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
         // is a claim, one the reference rejects included, as classifyBlock
         // and isInlineContradiction read it: a falsy one such as 0, false
         // or '' stubs too, rather than sending the URI as the image's source.
-        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
+        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? `[${NOTICE_TAG.reference}]` };
       }
       if (isFilledString(block.data) && isFilledString(block.mimeType)) {
         return {
@@ -76,7 +78,7 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
         // RFC-005 uri-form media with a disposition claim, a falsy one
         // included, as for an image (above): stub, do not hand the URI to
         // the provider or inline it.
-        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
+        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? `[${NOTICE_TAG.reference}]` };
       }
       if (isFilledString(block.data) && isFilledString(block.mimeType)) {
         return {
@@ -95,14 +97,14 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
       }
       // 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]' };
+      return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? `[${NOTICE_TAG.reference}]` };
     }
 
     default: {
       // MCP's link to a resource isn't one of MCPL's own blocks, but a server
       // can send one, and RFC-005 §8.1 makes it a reference, shown as one.
       if ((block as { type?: unknown }).type === 'resource_link') {
-        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
+        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? `[${NOTICE_TAG.reference}]` };
       }
       // Unknown wire block types previously fell off the exhaustive switch
       // and propagated `undefined` into ContentBlock[]. Fail visibly. A type
@@ -113,6 +115,17 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
   }
 }
 
+export function convertBlocks(blocks: readonly McplContentBlock[], provenance: string, serverId: string): ContentBlock[] {
+  const converted = blocks.map((block) => convertBlock(block, provenance, serverId));
+  return markNoticeOpenings(converted, (index) => sendersText(blocks[index]));
+}
+
+function sendersText(block: McplContentBlock | undefined): boolean {
+  if (block?.type === 'text') return typeof block.text === 'string';
+  const c = classifyBlock(block);
+  return c.kind === 'embedded' && c.contents.kind === 'block' && c.contents.block.type === 'text';
+}
+
 /** 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

package/src/mcpl/hook-orchestrator.ts

@@ -14,7 +14,8 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import { convertBlock } from './convert-block.js';
+import { convertBlocks } from './convert-block.js';
+import { markedText } from '../supplied-text.js';
 import type { ContextInjection } from '@animalabs/context-manager';
 
 import type {
@@ -64,9 +65,9 @@ function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise
  */
 function convertContent(content: string | McplContentBlock[], serverId: string): ContentBlock[] {
   if (typeof content === 'string') {
-    return [{ type: 'text', text: content }];
+    return [{ type: 'text', text: markedText(content) }];
   }
-  return content.map((block) => convertBlock(block, 'attachment on context injection', serverId));
+  return convertBlocks(content, 'attachment on context injection', serverId);
 }
 
 /**

package/src/mcpl/inbound-source.ts

@@ -217,7 +217,9 @@ function storedBlock(block: unknown): unknown {
  * The version identity of a delivered body (agreed with the receipts lane,
  * room-220 #46752–#47210): SHA-256 hex of `canonicalJson([blocks])` over the
  * ContentBlock[] the framework stores for the body — after MCPL conversion,
- * before any host decoration is added and before storage shards it — with
+ * which marks the server's text at the framework's notice openings
+ * (supplied-text.ts), before any host decoration is added and before storage
+ * shards it — with
  * each block as the store keeps it, which context-manager's `blockAsStored`
  * gives. So a body hashes alike as delivered, as handed to storage, and as
  * read back unsharded from the store with its blobs resolved, except one

package/src/mcpl/modern-connection.ts

@@ -68,7 +68,7 @@ import {
 
 import { StdioTransport, type McplTransport } from './transport.js';
 import { McplProtocolVersionError, McplRequestError, McplUnreapedLaunchError } from './server-connection.js';
-import { LEGACY_MCP_PROTOCOL_VERSION, MAX_TIMER_MS, MODERN_MCP_PROTOCOL_VERSION, checkServerConfig, describeCredentialError, maskedError, noteDialSent, redactServerText, redactedData, serverTextRedactor, type ServerTextRedactor } from './protocol-family.js';
+import { LEGACY_MCP_PROTOCOL_VERSION, MAX_TIMER_MS, MODERN_MCP_PROTOCOL_VERSION, checkServerConfig, describeCredentialError, logDroppedLine, maskedError, noteDialSent, redactServerText, redactedData, serverTextRedactor, type ServerTextRedactor } from './protocol-family.js';
 import type { McplServerConfig, McpToolDefinition } from './types.js';
 import { boundedForLog } from './errors.js';
 import { logDetail, logValue, logValueRedacted, loggedCode } from './log-value.js';
@@ -297,8 +297,9 @@ export function malformedLineDiagnostic(
 
 /**
  * SDK `Transport` over Connectome's stdio spawner. Framing is the same
- * newline-delimited JSON-RPC as legacy. Lines that are not JSON are ignored,
- * as the legacy engine ignores them. Because this is a custom transport, the
+ * newline-delimited JSON-RPC as legacy. Lines that are not JSON are dropped,
+ * and the first three on a connection that aren't blank are logged by their
+ * length, as the legacy engine does. Because this is a custom transport, the
  * SDK runs `server/discover` on this very process instead of starting a
  * throwaway copy, and cancels with `notifications/cancelled`, which is the
  * stdio binding's mechanism.
@@ -332,14 +333,17 @@ class SpawnerStdioTransport implements Transport {
     const line = await this.spawning;
     this.line = line;
     line.on('line', (text: string) => {
-      // A line that isn't JSON is ignored, as the legacy engine ignores it.
-      // A line that is JSON but not a JSON-RPC message (`null`, an array, a
-      // bare value) is a diagnostic. It must never reach a handler that
-      // assumes the shape: thrown from this callback, it would end the host.
+      // A line that isn't JSON is dropped, and the first three on a
+      // connection that aren't blank are logged by their length, as the
+      // legacy engine does. A line that is JSON but not a JSON-RPC message
+      // (`null`, an array, a bare value) is a diagnostic. It must never reach
+      // a handler that assumes the shape: thrown from this callback, it would
+      // end the host.
       let parsed: unknown;
       try {
         parsed = JSON.parse(text);
       } catch {
+        logDroppedLine(this.config.id, text, 'unparsed', line);
         return;
       }
       let message: JSONRPCMessage;

package/src/mcpl/protocol-family.ts

@@ -22,6 +22,7 @@
  * isn't `initialize`), the SDK's stdio probe launches the server twice, and a
  * server's era is a stable fact its configuration can state.
  */
+import { NOTICE_TAG } from '../notice-tags.js';
 import { DENY_BY_DEFAULT, capabilityPatternMatches } from './capability-grant.js';
 import { DEFAULT_EAGER_FETCH_MAX_BYTES, DEFAULT_MAX_TOTAL_BYTES } from './reference-fetcher.js';
 import { DEFAULT_MAX_INPUT_BYTES } from './tool-lifecycle.js';
@@ -198,11 +199,11 @@ export function serverTextRedactor(config: Pick<McplServerConfig, 'url' | 'token
 
 /** What a redaction gives in place of text when the configuration it
  *  redacts with can't be read ({@link redactServerText}). */
-export const WITHHELD_TEXT = "[withheld: the server's configuration couldn't be read to redact this]";
+export const WITHHELD_TEXT = `[${NOTICE_TAG.withheld}: the server's configuration couldn't be read to redact this]`;
 
 /** What {@link redactedData} gives in place of data nested deeper than it
  *  walks. */
-export const TOO_DEEP_TEXT = '[withheld: nested too deep to redact]';
+export const TOO_DEEP_TEXT = `[${NOTICE_TAG.withheld}: nested too deep to redact]`;
 
 /** How deep {@link redactedData} walks. A server's JSON can nest deeper than
  *  a recursive walk's stack holds (10,000 levels overflow it), and the walk
@@ -528,7 +529,7 @@ export function credentialRedactor(patterns: readonly CredentialPattern[]): Reda
 /** Any value as text: a value that can't be printed reads as a placeholder. */
 export function asText(text: unknown): string {
   if (typeof text === 'string') return text;
-  try { return String(text); } catch { return '[a value that cannot be printed]'; }
+  try { return String(text); } catch { return `[${NOTICE_TAG.unprintableValue}]`; }
 }
 
 /** A part of an environment variable's name that ends with a credential word, in the singular or plural, with any digits after it. */
@@ -869,3 +870,23 @@ export function checkServerConfig(config: McplServerConfig): ServerBinding {
   for (const warning of serverConfigWarnings(config)) console.warn(`[mcp] ${warning}`);
   return resolveServerBinding(config);
 }
+
+const DROPPED_LINES_LOGGED = 3;
+const droppedLinesLogged = new WeakMap<object, number>();
+
+export function logDroppedLine(serverId: string, line: string, reason: 'unparsed' | 'not-object', connection: object): void {
+  if (/^[ \t]*$/.test(line)) return;
+  const logged = droppedLinesLogged.get(connection) ?? 0;
+  if (logged > DROPPED_LINES_LOGGED) return;
+  droppedLinesLogged.set(connection, logged + 1);
+  if (logged === DROPPED_LINES_LOGGED) {
+    console.error(`MCP server "${serverId}" sent another line that isn't a JSON object, so it was dropped; more such lines on this connection are dropped without a log line`);
+    return;
+  }
+  let length = 0;
+  for (const _ of line) length++;
+  const why = reason === 'not-object' ? 'is JSON but not an object'
+    : /^[ \t]*\{/.test(line) ? "starts like a JSON object but doesn't parse"
+    : "isn't JSON";
+  console.error(`MCP server "${serverId}" sent a line of length ${length} that ${why}, so it was dropped`);
+}

package/src/mcpl/push-coalescer.ts

@@ -1000,6 +1000,25 @@ export class PushCoalescer<E = unknown> {
     return result;
   }
 
+  /**
+   * Render and materialize one subject's pending batch for `agentName` now,
+   * outside a turn's assembly: a batch whose wake a hold keeps back, stored
+   * as it renders (held, as a plain push under the hold is), so whoever reads
+   * held traffic sees it and the turn after the hold doesn't take it again.
+   * A batch that opened while another render ran is rendered once that
+   * render settles. Resolves whether it materialized.
+   */
+  async materializeNow(agentName: string, subject: string): Promise<boolean> {
+    for (;;) {
+      if (this.suspended) return false;
+      const started = await this.locked(() => this.freeze(subject, agentName));
+      if (!started || started === 'declined') return false;
+      await started.done;
+      this.persist();
+      if (!started.joined) return started.rendering.materialized === true;
+    }
+  }
+
   /**
    * Under the lock: decide whether `subject`'s batch renders for `agentName`,
    * freeze it, make the render-start durable, re-check authority, and start

package/src/mcpl/push-handler.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import { convertBlock } from './convert-block.js';
+import { convertBlocks } from './convert-block.js';
 
 import type {
   PushEventParams,
@@ -204,7 +204,7 @@ export class PushHandler {
 
     // 2. Convert content blocks, and refuse content with nothing visible in
     // it — before dedup, so a refused eventId is not burned for a retry.
-    const content: ContentBlock[] = params.payload.content.map((block) => convertBlock(block, 'attachment on push event', serverId));
+    const content: ContentBlock[] = convertBlocks(params.payload.content, 'attachment on push event', serverId);
     if (!emptyAllowed && isVisiblyEmptyConversion(params.payload.content, content)) {
       const err = new EmptyContentError();
       this.traceEmptyRejection(serverId, params);

package/src/mcpl/references.ts

@@ -26,6 +26,9 @@
  * the registry is what makes a future host-mediated fetcher and the
  * code-execution materialization hook possible.
  */
+import { cutToFit, suppliedValue } from '../supplied-text.js';
+import { NOTICE_TAG } from '../notice-tags.js';
+
 
 export const REFERENCE_LIMITS = { uri: 4096, mimeType: 255, name: 255, expiresAt: 64 } as const;
 export const DIGEST_PATTERN = /^sha256:[A-Za-z0-9_-]{43}$/;
@@ -210,7 +213,7 @@ export function isInlineContradiction(block: unknown): boolean {
 }
 
 export const INLINE_WITHHELD_TEXT =
-  '[Content not shown: its inline data arrived marked as a reference too, so this host withheld it.]';
+  `[${NOTICE_TAG.contentNotShown}: its inline data arrived marked as a reference too, so this host withheld it.]`;
 
 /*
  * What the model-visible lanes (push, channel, context injection and tool
@@ -220,28 +223,28 @@ export const INLINE_WITHHELD_TEXT =
  * agent to do about any of them. The text marker is NON_STRING_TEXT_PLACEHOLDER
  * (visible-content.ts).
  */
-export const IMAGE_NO_MEDIA_TYPE_TEXT = '[Image not shown: its data arrived without a media type.]';
-export const IMAGE_NO_DATA_TEXT = '[Image not shown: it arrived with no usable data or link.]';
-export const AUDIO_NO_MEDIA_TYPE_TEXT = '[Audio not shown: its data arrived without a media type.]';
+export const IMAGE_NO_MEDIA_TYPE_TEXT = `[${NOTICE_TAG.imageNotShown}: its data arrived without a media type.]`;
+export const IMAGE_NO_DATA_TEXT = `[${NOTICE_TAG.imageNotShown}: it arrived with no usable data or link.]`;
+export const AUDIO_NO_MEDIA_TYPE_TEXT = `[${NOTICE_TAG.audioNotShown}: its data arrived without a media type.]`;
 /** On the push, channel and context-injection lanes, audio shows only as
  *  inline data, so a plain link isn't enough either. (A tool result's audio
  *  with a link is a reference, as any block with one is there.) */
-export const AUDIO_NO_DATA_TEXT = '[Audio not shown: it arrived with no usable inline data.]';
+export const AUDIO_NO_DATA_TEXT = `[${NOTICE_TAG.audioNotShown}: it arrived with no usable inline data.]`;
 /** MCP's embedded resource whose contents are neither text nor a blob, or
  *  both. */
-export const EMBEDDED_RESOURCE_UNREADABLE_TEXT = '[Resource not shown: its contents arrived as neither text nor data, or as both.]';
+export const EMBEDDED_RESOURCE_UNREADABLE_TEXT = `[${NOTICE_TAG.resourceNotShown}: its contents arrived as neither text nor data, or as both.]`;
 /** MCP's embedded resource whose blob has no media type, so it can't be
  *  shown as an image or audio. */
-export const EMBEDDED_RESOURCE_NO_MEDIA_TYPE_TEXT = '[Resource not shown: its data arrived without a media type.]';
+export const EMBEDDED_RESOURCE_NO_MEDIA_TYPE_TEXT = `[${NOTICE_TAG.resourceNotShown}: its data arrived without a media type.]`;
 
 /** MCP's embedded resource whose blob is of a type no lane can show: what
  *  it was, by its type and size. Made well formed (a lone UTF-16 surrogate
  *  becomes U+FFFD), as a stub is (#695), since it names the block's media
- *  type, which sanitizeLabel leaves as it is: every lane then shows the same
- *  text. */
+ *  type, whose lone surrogates referenceTypeLabel leaves as they are: every
+ *  lane then shows the same text. */
 export function embeddedBinaryText(mimeType: string, blob: string): string {
   const what = [referenceTypeLabel(mimeType), formatSizeBytes(Math.floor(blob.length * 3 / 4))].filter(Boolean).join(', ');
-  return `[Resource not shown: this host can't display its data (${what}).]`.toWellFormed();
+  return `[${NOTICE_TAG.resourceNotShown}: this host can't display its data (${what}).]`.toWellFormed();
 }
 /**
  * What the converter (convertBlock, on every lane) shows for a text
@@ -250,10 +253,10 @@ export function embeddedBinaryText(mimeType: string, blob: string): string {
  * sender's, so it never makes content visible (isVisiblyEmptyConversion in
  * visible-content.ts, which re-exports it).
  */
-export const NON_STRING_TEXT_PLACEHOLDER = '[Text not shown: a text part arrived without readable text.]';
-export const REFERENCE_NO_LINK_TEXT = '[Reference not shown: it arrived without a link.]';
-export const REFERENCE_LINK_TOO_LONG_TEXT = '[Reference not shown: its link is longer than this host accepts.]';
-const UNREADABLE_BLOCK_TEXT = "[Content not shown: a part arrived in a form this host can't read.]";
+export const NON_STRING_TEXT_PLACEHOLDER = `[${NOTICE_TAG.textNotShown}: a text part arrived without readable text.]`;
+export const REFERENCE_NO_LINK_TEXT = `[${NOTICE_TAG.referenceNotShown}: it arrived without a link.]`;
+export const REFERENCE_LINK_TOO_LONG_TEXT = `[${NOTICE_TAG.referenceNotShown}: its link is longer than this host accepts.]`;
+const UNREADABLE_BLOCK_TEXT = `[${NOTICE_TAG.contentNotShown}: a part arrived in a form this host can't read.]`;
 
 /** A block of a type the host doesn't show, of no type at all, or no block.
  *  The type is the sender's word, so it's shown as a label is: bounded, with
@@ -261,10 +264,10 @@ const UNREADABLE_BLOCK_TEXT = "[Content not shown: a part arrived in a form this
  *  converted to one. */
 export function unknownBlockText(block: unknown): string {
   if (!isRecord(block)) return UNREADABLE_BLOCK_TEXT;
-  const label = typeof block.type === 'string' ? sanitizeLabel(block.type, STUB_FIELD_CHARS) : '';
+  const label = typeof block.type === 'string' ? suppliedLabel(block.type, STUB_FIELD_CHARS) : '';
   return label
-    ? `[Content not shown: this host can't display "${label}" content.]`
-    : '[Content not shown: a part arrived with no type.]';
+    ? `[${NOTICE_TAG.contentNotShown}: this host can't display "${label}" content.]`
+    : `[${NOTICE_TAG.contentNotShown}: a part arrived with no type.]`;
 }
 
 /**
@@ -654,6 +657,11 @@ export function sanitizeLabel(s: string, maxChars: number): string {
   return cut + '…';
 }
 
+function suppliedLabel(s: string, maxChars: number): string {
+  const shown = suppliedValue(s).replace(/[\p{Cc}\p{Bidi_Control}]/gu, '').trim();
+  return shown.length <= maxChars ? shown : `${cutToFit(shown, maxChars - 1)}…`;
+}
+
 export function formatSizeBytes(n: number): string {
   if (n < 1024) return `${n}B`;
   if (n < 1024 * 1024) return `~${Math.round(n / 1024)}KB`;
@@ -786,7 +794,7 @@ export class ReferenceRegistry {
         return existing;
       }
     }
-    const refId = `ref_${(++this.counter).toString(36)}_${Math.random().toString(36).slice(2, 2 + REF_ID_SUFFIX_CHARS)}`;
+    const refId = `${NOTICE_TAG.referenceId}_${(++this.counter).toString(36)}_${Math.random().toString(36).slice(2, 2 + REF_ID_SUFFIX_CHARS)}`;
     const record: ReferenceRecord = { refId, serverIds: serverId === undefined ? [] : [serverId], testimony, receivedAt: Date.now() };
     this.records.set(refId, record);
     this.byKey.set(testimony.uri, refId);
@@ -871,7 +879,7 @@ export interface ScriptLine {
 /** A reference's type as its stub shows one, or '' when nothing is left of
  *  it once sanitized (the stub then leaves it out). */
 export function referenceTypeLabel(mimeType: string | undefined): string {
-  return mimeType ? sanitizeLabel(mimeType, STUB_FIELD_CHARS) : '';
+  return mimeType ? suppliedLabel(mimeType, STUB_FIELD_CHARS) : '';
 }
 
 /**
@@ -886,7 +894,7 @@ export function referenceTypeLabel(mimeType: string | undefined): string {
  * stub, so it's no slot whatever its length.
  */
 export const REFERENCE_STUB_MAX_CHARS =
-  `[ref_${MAX_SAFE.toString(36)}_] `.length + REF_ID_SUFFIX_CHARS
+  `[${NOTICE_TAG.referenceId}_${MAX_SAFE.toString(36)}_] `.length + REF_ID_SUFFIX_CHARS
   + STUB_FIELD_CHARS
   + ' — '.length + STUB_FIELD_CHARS + ', '.length + `${formatSizeBytes(MAX_SAFE)} claimed`.length
   + ' — '.length + STUB_FIELD_CHARS
@@ -1099,7 +1107,7 @@ export function buildReferenceStub(t: ReferenceTestimony, provenance?: string, s
   const nowMs = Date.now();
   const parts: string[] = [];
   // A label is shown only when something is left of it once sanitized.
-  const name = t.name ? sanitizeLabel(t.name, STUB_FIELD_CHARS) : '';
+  const name = t.name ? suppliedLabel(t.name, STUB_FIELD_CHARS) : '';
   if (name) parts.push(name);
   const meta: string[] = [];
   const mimeType = referenceTypeLabel(t.mimeType);
@@ -1130,9 +1138,9 @@ export function buildReferenceStub(t: ReferenceTestimony, provenance?: string, s
  * server's link shows (StubOptions.unfetchedLinkUri).
  */
 function unfetchedLinkText(t: ReferenceTestimony, uri: string): string {
-  const name = t.name ? sanitizeLabel(t.name, STUB_FIELD_CHARS) : '';
+  const name = t.name ? suppliedLabel(t.name, STUB_FIELD_CHARS) : '';
   const mimeType = referenceTypeLabel(t.mimeType);
-  return `[resource link${name ? ` "${name}"` : ''}: ${uri}${mimeType ? `, ${mimeType}` : ''}; not fetched]`;
+  return `[${NOTICE_TAG.resourceLink}${name ? ` "${name}"` : ''}: ${uri}${mimeType ? `, ${mimeType}` : ''}; not fetched]`;
 }
 
 /**

package/src/mcpl/server-connection.ts

@@ -20,6 +20,7 @@ import {
   LEGACY_MCP_PROTOCOL_VERSION,
   MODERN_MCP_PROTOCOL_VERSION,
   checkServerConfig,
+  logDroppedLine,
   redactServerText,
   redactedData,
   serverTextRedactor,
@@ -1330,13 +1331,8 @@ export class McplServerConnection extends EventEmitter {
           reject(closedWhileConnecting());
         };
         const onLine = (line: string) => {
-          let msg: JsonRpcResponse;
-          try {
-            msg = JSON.parse(line) as JsonRpcResponse;
-          } catch {
-            return; // Ignore non-JSON lines (e.g. logback output from Java servers)
-          }
-          if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) return;
+          const msg = messageFromLine(config.id, line, transport) as JsonRpcResponse | undefined;
+          if (!msg) return;
           // A request or a notification from the server is never the
           // initialize response, whatever its id: a server's own ids can start
           // at 0, this handshake's. MCP lets a server ping before
@@ -2376,17 +2372,8 @@ export class McplServerConnection extends EventEmitter {
     // passed is the dead process's (afterBoundary).
     const epoch = this.transportEpoch;
     transport.on('line', (line: string) => {
-      let msg: JsonRpcRequest | JsonRpcResponse;
-      try {
-        msg = JSON.parse(line);
-      } catch {
-        // Ignore non-JSON lines
-        return;
-      }
-
-      // JSON-RPC messages must be objects. Ignore unrelated stdout/log values
-      // before property access, just as malformed JSON lines are ignored.
-      if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) return;
+      const msg = messageFromLine(this.id, line, transport) as JsonRpcRequest | JsonRpcResponse | undefined;
+      if (!msg) return;
       try {
         this.dispatchMessage(msg, epoch);
       } catch (error) {
@@ -2829,3 +2816,18 @@ export class McplServerConnection extends EventEmitter {
     });
   }
 }
+
+function messageFromLine(serverId: string, line: string, transport: McplTransport): object | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    logDroppedLine(serverId, line, 'unparsed', transport);
+    return undefined;
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    logDroppedLine(serverId, line, 'not-object', transport);
+    return undefined;
+  }
+  return value;
+}

package/src/mcpl/skip-reply-wake.ts

@@ -43,6 +43,41 @@ export function readSkipReplyWake(input: unknown): SkipReplyWake {
   return { kind: 'wake', seconds: Math.floor(Math.min(SKIP_REPLY_WAKE_MAX_SECONDS, seconds)) };
 }
 
+/**
+ * A wake the heartbeat has due before a skip_reply's self-wake: its next tick
+ * or a reminder, one the agent's rules would let wake it as they stand when
+ * the self-wake is armed. `what` names it to the agent ("your heartbeat
+ * (…)"); `inSeconds` is how far off it is then.
+ */
+export interface SkipReplyEarlierWake {
+  inSeconds: number;
+  what: string;
+}
+
+/**
+ * The note a skip_reply's result carries: that the turn ended, and, when the
+ * agent set a wake, when it fires unless something wakes the agent first.
+ * When the heartbeat has a wake due sooner, the note adds it, and what it
+ * would mean: any turn start cancels a pending self-wake
+ * (EventGate.onInferenceStarted), so a timer the agent still wants after the
+ * heartbeat's turn is one it sets again then, for the time that was left.
+ *
+ * It says when the heartbeat is due, not that it will wake the agent: the
+ * rules can change before then, a rate limit can have no token left, a
+ * gate.js or a host's inference policy can hold the wake back, and a batch or
+ * a queued request can wake the agent sooner. Each of those leaves the note
+ * true.
+ */
+export function skipReplyNote(selfWakeSeconds: number | undefined, earlier?: SkipReplyEarlierWake): string {
+  if (selfWakeSeconds === undefined) return 'Turn ended; nothing sent.';
+  const note = `Turn ended; nothing sent. Self-wake in ~${selfWakeSeconds}s unless something wakes you first.`;
+  if (earlier === undefined) return note;
+  const what = earlier.what.charAt(0).toUpperCase() + earlier.what.slice(1);
+  const left = Math.max(1, selfWakeSeconds - earlier.inSeconds);
+  return `${note} ${what} is due sooner, in ~${earlier.inSeconds}s; if it wakes you, the self-wake is cancelled, `
+    + `so set it again for the ~${left}s left if you still want it.`;
+}
+
 /** The refusal the model reads when its host has no EventGate to set a timer. */
 export const SKIP_REPLY_WAKE_NO_GATE_REFUSAL =
   "Your turn didn't end, and no wake was set: this host can't wake you on a timer, so skip_reply can't take wake_in_seconds here. To end the turn and wait for the next message, call skip_reply without it. Anything you meant to come back to, do now.";

package/src/mcpl/tool-presence.ts

@@ -26,6 +26,7 @@
  * Ported from mcpl-cc-bridge's presence.ts, the reference host.
  */
 import { objectSignature, renderToolLines, toolDigest, type HintedTool, type Shown } from './tool-signature.js';
+import { nameToTypeBack, quotedValue, suppliedValue } from '../supplied-text.js';
 
 export interface ToolsetDecl {
   title?: string;
@@ -531,7 +532,7 @@ export class ToolPresence {
     const endedKeys = new Set<string>();
     for (const e of ended) {
       if (!e.id || !this.toldEnded.has(e.id)) endedKeys.add(keyOf(e.toolset, e.instance));
-      const note = `${this.label(keyOf(e.toolset, e.instance))} ended${e.reason ? `: ${e.reason}` : ''}.`;
+      const note = `${this.label(keyOf(e.toolset, e.instance))} ended${e.reason ? `: ${suppliedValue(e.reason)}` : ''}.`;
       if (e.id) {
         if (!this.toldEnded.has(e.id)) told.push({ id: e.id, note });
       } else notes.push(note);
@@ -588,27 +589,27 @@ export class ToolPresence {
   /** The marker a key's announcements begin with, `[server/toolset:instance]`, which a reminder looks for. */
   label(key: string): string {
     const { toolset, instance } = splitKey(key);
-    return `[${this.server}${toolset ? `/${toolset}` : ''}${instance ? `:${instance}` : ''}]`;
+    return `[${this.server}${toolset ? `/${nameToTypeBack(toolset)}` : ''}${instance ? `:${nameToTypeBack(instance)}` : ''}]`;
   }
 
   callHint(key: string): string {
     const { instance } = splitKey(key);
-    return `${this.names.act} {server:"${this.server}"${instance ? `, instance:"${instance}"` : ''}, tool, args}`;
+    return `${this.names.act} {server:"${this.server}"${instance ? `, instance:${quotedValue(instance)}` : ''}, tool, args}`;
   }
 
   closeHint(key: string): string | null {
     const { toolset, instance } = splitKey(key);
     if (!toolset) return null;
-    return `${this.names.close} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${instance}"` : ''}}`;
+    return `${this.names.close} {server:"${this.server}", toolset:${quotedValue(toolset)}${instance ? `, instance:${quotedValue(instance)}` : ''}}`;
   }
 
   openHint(toolset: string, instance?: string): string {
-    return `${this.names.open} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${instance}"` : ''}}`;
+    return `${this.names.open} {server:"${this.server}", toolset:${quotedValue(toolset)}${instance ? `, instance:${quotedValue(instance)}` : ''}}`;
   }
 
   /** The tool block for one key: its label, how to call, and the visible tools (new or changed ones described). */
   toolBlock(key: string, tools: HintedTool[], opts: { describeAll?: boolean; headed?: boolean; title?: string; seen?: Shown } = {}): string[] {
-    const head = opts.headed === false ? '' : `${this.label(key)}${opts.title ? ` ${opts.title}` : ''} `;
+    const head = opts.headed === false ? '' : `${this.label(key)}${opts.title ? ` ${suppliedValue(opts.title)}` : ''} `;
     if (!tools.length) return [`${head}no tools available right now.`];
     return [`${head}tools now — ${this.callHint(key)}:`, ...renderToolLines(tools, opts.seen ?? this.shown, { describeAll: opts.describeAll })];
   }
@@ -627,13 +628,13 @@ export class ToolPresence {
     for (const c of cs.changes) {
       const bare = opts.bare === c.key;
       if (c.closed) {
-        lines.push(`${this.label(c.key)} closed.${c.gone.length ? ` Now unavailable: ${c.gone.join(', ')}.` : ''}`);
+        lines.push(`${this.label(c.key)} closed.${c.gone.length ? ` Now unavailable: ${c.gone.map(suppliedValue).join(', ')}.` : ''}`);
         continue;
       }
       const title = (c.opened || c.retitled) && !bare ? c.title : undefined;
       if (showsBlock(c)) lines.push(...this.toolBlock(c.key, c.now, { headed: !bare, title, seen, describeAll: opts.describeAll }));
-      else if (title) lines.push(`${this.label(c.key)} ${title}`);
-      if (c.gone.length) lines.push(`now unavailable: ${c.gone.join(', ')}`);
+      else if (title) lines.push(`${this.label(c.key)} ${suppliedValue(title)}`);
+      if (c.gone.length) lines.push(`now unavailable: ${c.gone.map(suppliedValue).join(', ')}`);
       if (c.opened && !bare) {
         const close = this.closeHint(c.key);
         if (close) lines.push(`${close} closes it.`);
@@ -646,9 +647,9 @@ export class ToolPresence {
 
   /** RFC §6.2: a suggestion is shown, never acted on. */
   renderSuggestion(s: Suggestion): string {
-    const what = `${s.toolset}${s.instance ? `:${s.instance}` : ''}`;
+    const what = suppliedValue(`${s.toolset}${s.instance ? `:${s.instance}` : ''}`);
     const how = s.action === 'open' ? this.openHint(s.toolset, s.instance) : this.closeHint(keyOf(s.toolset, s.instance));
-    return `${this.server} suggests ${s.action === 'open' ? 'opening' : 'closing'} ${what}${s.reason ? `: ${s.reason}` : ''} — ${how} if you want to (nothing was done).`;
+    return `${this.server} suggests ${s.action === 'open' ? 'opening' : 'closing'} ${what}${s.reason ? `: ${suppliedValue(s.reason)}` : ''} — ${how} if you want to (nothing was done).`;
   }
 
   /** The keys a reminder restates: every open key of this server's view. */
@@ -674,7 +675,7 @@ export class ToolPresence {
    *  reach no agent. */
   catalog(opts: { mark?: boolean } = {}): string {
     const lines: string[] = [];
-    lines.push(this.surface ? `${this.server} — ${[this.surface.title, this.surface.summary].filter(Boolean).join(': ')}` : this.server);
+    lines.push(this.surface ? `${this.server} — ${[this.surface.title, this.surface.summary].filter(Boolean).map(suppliedValue).join(': ')}` : this.server);
     const v = this.view();
     if (v.size) {
       for (const [key, e] of v) {
@@ -689,7 +690,7 @@ export class ToolPresence {
     for (const [name, d] of Object.entries(this.declared)) {
       if (!d.instances && this.isOpen(name)) continue;
       openable.push(
-        `  ${name}${d.title ? ` — ${d.title}` : ''}${d.summary ? `: ${d.summary}` : ''}` +
+        `  ${nameToTypeBack(name)}${d.title ? ` — ${suppliedValue(d.title)}` : ''}${d.summary ? `: ${suppliedValue(d.summary)}` : ''}` +
           (d.instances ? ' (several can be open at once; name each with instance)' : '') +
           (d.options ? ` · options ${objectSignature(d.options)}` : ''),
       );
@@ -697,7 +698,7 @@ export class ToolPresence {
     for (const g of this.undeclaredGroups) {
       if (this.groups.has(g)) continue;
       const names = this.allTools.filter((t) => this.toolsetOf(t.name) === g).map((t) => t.name);
-      openable.push(`  ${g}: ${names.join(', ')}`);
+      openable.push(`  ${nameToTypeBack(g)}: ${names.map(nameToTypeBack).join(', ')}`);
     }
     if (openable.length) lines.push(`can open — ${this.names.open} {server:"${this.server}", toolset, instance?, options?}:`, ...openable);
     return lines.join('\n');
@@ -705,12 +706,12 @@ export class ToolPresence {
 
   /** Where a tool can be called from now, for `look` naming it. */
   toolStatus(tool: string): string {
-    if (this.presenceOf(tool) === 'static') return `static — called by name, as ${this.listedName(tool)}`;
+    if (this.presenceOf(tool) === 'static') return `static — called by name, as ${nameToTypeBack(this.listedName(tool))}`;
     const where = [...this.view().entries()].filter(([, e]) => e.tools.has(tool)).map(([k]) => k);
     const ts = this.toolsetOf(tool);
     return where.length
-      ? `available now in ${where.map((k) => this.label(k)).join(', ')} — ${this.names.act} {server:"${this.server}", tool:"${tool}"${where.length > 1 ? ', instance' : ''}, args}`
-      : `not available right now${ts ? ` (toolset ${ts})` : ''}`;
+      ? `available now in ${where.map((k) => this.label(k)).join(', ')} — ${this.names.act} {server:"${this.server}", tool:${quotedValue(tool)}${where.length > 1 ? ', instance' : ''}, args}`
+      : `not available right now${ts ? ` (toolset ${nameToTypeBack(ts)})` : ''}`;
   }
 
 }