@animalabs/agent-framework 0.28.0 → 0.29.0

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-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)})` : ''}`;
   }
 
 }

package/src/mcpl/tool-signature.ts

@@ -10,6 +10,7 @@
  * reference host of RFC-014. Dependency-free.
  */
 import { createHash } from 'node:crypto';
+import { nameToTypeBack, quotedValue, suppliedValue } from '../supplied-text.js';
 
 export type JsonSchema = Record<string, unknown>;
 
@@ -34,7 +35,7 @@ function nestsWithin(value: unknown, depth = 0): boolean {
 
 /** A schema's literal value (an enum's, a const or a default) as JSON, or … where it's nested too deeply to write. */
 function literal(value: unknown): string {
-  return nestsWithin(value) ? JSON.stringify(value) ?? 'null' : '…';
+  return nestsWithin(value) ? quotedValue(value) : '…';
 }
 
 function typeSig(schema: JsonSchema | undefined, depth = 0): string {
@@ -80,12 +81,12 @@ function typeSig(schema: JsonSchema | undefined, depth = 0): string {
       if (!isObj(props) || Object.keys(props).length === 0) return 'object';
       if (depth >= 3) return '{…}';
       const req = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
-      return `{${Object.entries(props).map(([k, v]) => `${k}${req.has(k) ? '' : '?'}: ${typeSig(v, depth + 1)}`).join(', ')}}`;
+      return `{${Object.entries(props).map(([k, v]) => `${nameToTypeBack(k)}${req.has(k) ? '' : '?'}: ${typeSig(v, depth + 1)}`).join(', ')}}`;
     }
     case undefined:
       return 'any';
     default:
-      return t;
+      return suppliedValue(t);
   }
 }
 
@@ -98,9 +99,9 @@ export function signature(tool: HintedTool): string {
   const req = new Set(Array.isArray(s.required) ? (s.required as string[]) : []);
   const params = Object.entries(props).map(([k, v]) => {
     const def = isObj(v) && v.default !== undefined ? ` =${literal(v.default)}` : '';
-    return `${k}${req.has(k) ? '' : '?'}: ${typeSig(v, 1)}${def}`;
+    return `${nameToTypeBack(k)}${req.has(k) ? '' : '?'}: ${typeSig(v, 1)}${def}`;
   });
-  return `${tool.name}(${params.join(', ')})`;
+  return `${nameToTypeBack(String(tool.name))}(${params.join(', ')})`;
 }
 
 /** An options schema as `{size?: 9|13|19 =9, …}` (a toolset's options). */
@@ -153,7 +154,7 @@ export function renderToolLines(tools: HintedTool[], shown: Shown, opts: { descr
     const describe = opts.describeAll || !shown.has(d);
     shown.add(d);
     const sentence = describe ? firstSentence(t.description) : '';
-    return `${indent}${signature(t)}${sentence ? ` — ${sentence}` : ''}`;
+    return `${indent}${signature(t)}${sentence ? ` — ${suppliedValue(sentence)}` : ''}`;
   });
 }
 
@@ -161,7 +162,7 @@ export function renderToolLines(tools: HintedTool[], shown: Shown, opts: { descr
 export function jsonText(value: unknown, space?: number): string {
   if (!nestsWithin(value)) return '(nested too deeply to show)';
   try {
-    return JSON.stringify(value, null, space) ?? '';
+    return JSON.stringify(value) === undefined ? '' : quotedValue(value, space);
   } catch {
     return '(too long to show)';
   }
@@ -173,8 +174,8 @@ export function renderToolDefinition(tool: HintedTool): string {
   const classes = Array.isArray(cls) ? cls.filter((c): c is string => typeof c === 'string') : [];
   return [
     signature(tool),
-    typeof tool.description === 'string' ? tool.description : '',
-    ...(classes.length ? [`class: ${classes.join(', ')}`] : []),
+    typeof tool.description === 'string' ? suppliedValue(tool.description) : '',
+    ...(classes.length ? [`class: ${classes.map(suppliedValue).join(', ')}`] : []),
     'inputSchema:',
     jsonText(tool.inputSchema ?? {}, 2),
   ]
@@ -252,15 +253,15 @@ function check(schema: unknown, value: unknown, at: string, depth: number, budge
   const s = schema;
   if (s.type !== undefined) {
     const types = Array.isArray(s.type) ? (s.type as string[]) : [s.type as string];
-    if (!types.some((t) => typeOk(t, value))) return `${at}: must be ${types.join(' or ')}`;
+    if (!types.some((t) => typeOk(t, value))) return `${at}: must be ${types.map(suppliedValue).join(' or ')}`;
   }
   if (Array.isArray(s.enum) || s.const !== undefined) {
     const own = canonicalJson(value);
     if (Array.isArray(s.enum)) {
       spend(budget, s.enum.length);
-      if (!s.enum.some((e) => canonicalJson(e) === own)) return `${at}: must be one of ${s.enum.map((e) => JSON.stringify(e)).join('|')}`;
+      if (!s.enum.some((e) => canonicalJson(e) === own)) return `${at}: must be one of ${s.enum.map((e) => quotedValue(e)).join('|')}`;
     }
-    if (s.const !== undefined && canonicalJson(s.const) !== own) return `${at}: must be ${JSON.stringify(s.const)}`;
+    if (s.const !== undefined && canonicalJson(s.const) !== own) return `${at}: must be ${quotedValue(s.const)}`;
   }
   if (typeof value === 'string') {
     const n = [...value].length;
@@ -286,16 +287,16 @@ function check(schema: unknown, value: unknown, at: string, depth: number, budge
   if (isObj(value)) {
     const props = isObj(s.properties) ? s.properties : {};
     for (const r of Array.isArray(s.required) ? (s.required as unknown[]) : []) {
-      if (typeof r === 'string' && !Object.hasOwn(value, r)) return `${at}.${r}: required`;
+      if (typeof r === 'string' && !Object.hasOwn(value, r)) return `${at}.${nameToTypeBack(r)}: required`;
     }
     for (const [k, v] of Object.entries(value)) {
       if (Object.hasOwn(props, k)) {
-        const e = check(props[k], v, `${at}.${k}`, depth + 1, budget);
+        const e = check(props[k], v, `${at}.${nameToTypeBack(k)}`, depth + 1, budget);
         if (e) return e;
       } else if (s.additionalProperties === false) {
-        return `${at}.${k}: not an argument of this tool`;
+        return `${at}.${nameToTypeBack(k)}: not an argument of this tool`;
       } else if (isObj(s.additionalProperties)) {
-        const e = check(s.additionalProperties, v, `${at}.${k}`, depth + 1, budget);
+        const e = check(s.additionalProperties, v, `${at}.${nameToTypeBack(k)}`, depth + 1, budget);
         if (e) return e;
       }
     }