@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/mcpl/inbound-source.ts

@@ -22,6 +22,8 @@
  */
 
 import { createHash } from 'node:crypto';
+import { blockAsStored, MalformedContentError } from '@animalabs/context-manager';
+import { logDetail, logValue } from './log-value.js';
 
 /** The MCPL admission lane that accepted an item. Its contract decides what
  *  an `eventId` is worth: `push/event` deduplicates by eventId, and RFC-006
@@ -192,92 +194,65 @@ export function canonicalJson(value: unknown): string {
 }
 
 /**
- * A block as the store hands it back. Context-manager keeps inline media as
- * blobs (blob-manager.ts): an image whose source isn't a URL, and every
- * document, audio or video block, comes back as `{ type, source: { type:
- * 'base64', data, mediaType } }` and nothing else, its data re-encoded from
- * the decoded bytes, and an image's media type taken from its bytes'
- * signature where they have one. Any other block comes back as it was given,
- * except a store-internal `blob_ref` from an unresolved read, which resolves
- * to inline media by default. It is digested as given here, so an unresolved
- * read and its resolved form differ. Context-manager refuses caller-supplied
- * blob_ref writes; the MCPL lanes never store one.
+ * blockAsStored throws a `MalformedContentError` for a block the store
+ * refuses on write, a caller-supplied `blob_ref` among them. Such a block
+ * has no stored form, and whatever is thrown, it is digested as given.
  */
 function storedBlock(block: unknown): unknown {
-  const media = block as { type?: unknown; source?: { type?: unknown; data?: unknown; mediaType?: unknown } } | null;
-  const blob = media?.type === 'image'
-    ? media.source?.type !== 'url'
-    : media?.type === 'document' || media?.type === 'audio' || media?.type === 'video';
-  const source = media?.source;
-  if (!blob || typeof source?.data !== 'string') return block;
-  const data = canonicalBase64(source.data);
-  const mediaType = media!.type === 'image'
-    ? sniffRasterImageMediaType(Buffer.from(data.slice(0, 32), 'base64')) ?? source.mediaType
-    : source.mediaType;
-  return { type: media!.type, source: { type: 'base64', data, mediaType } };
-}
-
-/**
- * Base64 as the store writes it back from the decoded bytes: padded, with no
- * whitespace, the standard alphabet and zero unused bits. Data already in
- * that form, as every stored copy's is, is returned without decoding it all.
- */
-function canonicalBase64(data: string): string {
-  if (data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
-    const last = data.slice(-4);
-    if (Buffer.from(last, 'base64').toString('base64') === last) return data;
-  }
-  return Buffer.from(data, 'base64').toString('base64');
-}
-
-/**
- * The store's own test for raster image types with an unambiguous byte
- * signature, copied from context-manager's blob-manager.ts (it isn't
- * exported): the store relabels an image whose bytes match one of these.
- */
-function sniffRasterImageMediaType(bytes: Uint8Array): string | null {
-  if (bytes.length >= 8 &&
-      bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
-      bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
-    return 'image/png';
-  }
-  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
-    return 'image/jpeg';
-  }
-  if (bytes.length >= 6) {
-    const signature = Buffer.from(bytes.subarray(0, 6)).toString('ascii');
-    if (signature === 'GIF87a' || signature === 'GIF89a') return 'image/gif';
-  }
-  if (bytes.length >= 12 &&
-      Buffer.from(bytes.subarray(0, 4)).toString('ascii') === 'RIFF' &&
-      Buffer.from(bytes.subarray(8, 12)).toString('ascii') === 'WEBP') {
-    return 'image/webp';
+  try {
+    return blockAsStored(block as Parameters<typeof blockAsStored>[0]);
+  } catch (err) {
+    if (!(err instanceof MalformedContentError)) {
+      const { name, message } = (err ?? {}) as { name?: unknown; message?: unknown };
+      console.error(
+        `[stored-digest-as-given] error=${logValue(typeof name === 'string' ? name : typeof err)}: ` +
+        logDetail(typeof message === 'string' ? message : ''),
+      );
+    }
+    return block;
   }
-  return null;
 }
 
 /**
  * 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
- * each block as the store keeps it (storedBlock, canonicalJson). So a body
- * hashes alike as delivered, as handed to storage, and as read back from
- * the store. The one-element array keeps the framing an undecorated,
- * unsharded stored copy has always hashed to, so a stamped copy and an
- * older copy of the same body share a version.
+ * 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
+ * whose blocks the store changes together: when it mends a `tool_use` whose
+ * input isn't an object, it also releases a raw replay form (`rawXml`,
+ * `rawItem`) that the message's other blocks share, which no one block's
+ * stored form shows. A body an MCPL lane stamps is never one. A block the
+ * store refuses on write, a `blob_ref` among them, is digested as given. The
+ * one-element array keeps the framing an undecorated, unsharded stored copy
+ * has always hashed to, so a stamped copy and an older copy of the same body
+ * share a version where the store keeps the body as it did then.
+ *
+ * A digest is a digest under the context-manager release that computed it: a
+ * release that changes what the store keeps, such as its set of image
+ * signatures, changes the digest of a body it touches.
  *
  * Ingestion stamps it as `metadata.sourceBodyDigest`, and the same function
  * over exactly the blocks handed to storage (decorations included) as
  * `metadata.storedBodyDigest`, on both MCPL lanes. Both live outside the
  * frozen admission envelope: they describe the body actually delivered (a
  * materialization, a correction), not the admission. Neither proves later
- * presence or completeness; an unsharded stored copy that no longer hashes
+ * presence or completeness. An unsharded stored copy that no longer hashes
  * to its storedBodyDigest was changed after delivery (editMessage keeps
- * metadata). A body the store shards carries the whole body's two digests
- * on every shard, and no shard hashes to them. Check a copy read back with
- * its blobs resolved (getAllMessages, getMessage, or getMessageWindow
- * without `resolveBlobs: false`): a blob reference never matches.
+ * metadata), or holds blocks the store changes together, or its digest was
+ * taken under a release that kept some block of it differently: a
+ * context-manager release that changed a stored form, or an agent-framework
+ * release from 0.24.0 up to the one that brought in blockAsStored, which
+ * took stored forms from a copy of the store's transform. Digests already
+ * stamped are never recomputed. A body the store shards carries the whole
+ * body's two digests on every shard, and no shard hashes to them. Check a
+ * copy read back with its blobs resolved (getAllMessages, getMessage, or
+ * getMessageWindow without `resolveBlobs: false`): a blob reference never
+ * matches.
  *
  * Exported from the package root, so a consumer checks a copy against either
  * field with this same function rather than a copy of it.

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,
@@ -240,19 +241,29 @@ export function toolsetDeclarationsOf(advertised: unknown): Record<string, unkno
 /** What the RFC-014 read tap is handed as the connection reads a message
  *  that can carry hint changes (see McplServerConnection.setReadTap). */
 export type HintRead =
-  /** A response to a request that can carry hints (RFC-014 §6.1 carrier 1).
-   *  `awaited`: whoever sent it still waits for it; false for a result that
-   *  arrives after its timeout. A JSON-RPC error carries no state and isn't
-   *  tapped. */
-  | { kind: 'result'; method: string; params: Record<string, unknown>; result: unknown; awaited: boolean }
+  /** A response to a request that can carry hints (RFC-014 §6.1 carrier 1),
+   *  or a `tools/list`'s whole inventory (§4.1), its pages joined by
+   *  sendToolsList, `straddled` when its pages carry different revs.
+   *  `awaited`: whoever sent it still waits for it; false for a
+   *  result that arrives after its timeout. A JSON-RPC error carries no state
+   *  and isn't tapped. */
+  | { kind: 'result'; method: string; params: Record<string, unknown>; result: unknown; awaited: boolean; straddled?: boolean }
   /** A push/event (carrier 2), as read, before the plane gate or the grant
    *  admit or refuse it. */
   | { kind: 'push'; params: unknown }
   /** A standalone tools/hints (carrier 3). */
   | { kind: 'hints'; params: unknown };
 
-/** Requests whose results can carry hint state (RFC-014 §6.1, §4.1). */
-const HINTED_METHODS: ReadonlySet<string> = new Set(['tools/call', 'toolsets/open', 'toolsets/close', 'toolsets/list', 'tools/list']);
+/** Requests whose results can carry hint state, remembered for a late answer (RFC-014 §6.1). */
+const HINTED_METHODS: ReadonlySet<string> = new Set(['tools/call', 'toolsets/open', 'toolsets/close', 'toolsets/list']);
+
+function hintedParams(method: string, params: Record<string, unknown>): { toolset?: string; instance?: string } {
+  if (method !== 'toolsets/open' && method !== 'toolsets/close') return {};
+  return {
+    ...(typeof params.toolset === 'string' ? { toolset: params.toolset } : {}),
+    ...(typeof params.instance === 'string' ? { instance: params.instance } : {}),
+  };
+}
 
 /**
  * A handshake that failed, and whose cleanup couldn't confirm that the child
@@ -330,6 +341,7 @@ interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (error: Error) => void;
   method: string;
+  onRead?: (result: unknown) => void;
   /** Per-request timeout timer; cleared on response/close/timeout. */
   timer?: ReturnType<typeof setTimeout>;
 }
@@ -339,6 +351,9 @@ interface RequestOptions {
   timeoutMs?: number;
   /** Surface a late response even when it carries no checkpoint state. */
   surfaceOrphanedResponse?: boolean;
+  /** Called with a successful result as its response is read, before
+   *  anything read after it and before the request's promise settles. */
+  onRead?: (result: unknown) => void;
 }
 
 /** A server→host message held while its plane is closed. `kept`: it came on
@@ -452,15 +467,18 @@ export class McplServerConnection extends EventEmitter {
    * the message: a push the plane holds or the grant refuses, a result its
    * caller stopped waiting for. The tap sees every such message of the
    * current transport, synchronously, before anything routes it; a late
-   * answer's request is remembered past its timeout (hintedRequests) so its
-   * hints still apply. Null (the default) taps nothing, and the connection
+   * answer's request is remembered past its timeout (hintedRequests, while
+   * no more than 1,000 hinted requests await an answer) so its hints still
+   * apply. Null (the default) taps nothing, and the connection
    * behaves as it always has.
    */
   private readTap: ((read: HintRead, epoch: number) => void) | null = null;
   /** The hinted requests sent on this transport, by id, kept past a timeout
-   *  so a late result is still tapped; bounded. Cleared at each boundary,
+   *  so a late result is still tapped: each one's method, and an open's or
+   *  close's toolset and instance, which are all the read of its result
+   *  uses; never a call's arguments. Bounded. Cleared at each boundary,
    *  since the next transport numbers its requests afresh. */
-  private hintedRequests = new Map<string | number, { method: string; params: Record<string, unknown> }>();
+  private hintedRequests = new Map<string | number, { method: string; params: { toolset?: string; instance?: string } }>();
 
   /** Install (or, with null, remove) the RFC-014 read tap (see readTap). */
   setReadTap(tap: ((read: HintRead, epoch: number) => void) | null): void {
@@ -1313,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
@@ -1708,22 +1721,40 @@ export class McplServerConnection extends EventEmitter {
    * read it as a complete page). A page that isn't well formed (no `tools` array, a cursor
    * that isn't a string), or cursors that don't terminate (a repeat, or more
    * than {@link MAX_TOOL_LIST_PAGES} pages), are errors, never a partial or
-   * empty inventory published as complete.
+   * empty inventory published as complete. The read tap (RFC-014) is handed
+   * the complete inventory once, with the last page's `_meta`, as the last
+   * page's response is read, before anything read after it; a list that
+   * fails or times out hands it nothing. It's `straddled` when its pages
+   * carry different `mcpl/rev`s.
    */
   async sendToolsList(): Promise<{ tools: McpToolDefinition[] }> {
     const tools: McpToolDefinition[] = [];
     const seen = new Set<string>();
     let cursor: string | undefined;
     let first: Record<string, unknown> | undefined;
+    const read: McpToolDefinition[] = [];
+    const revs = new Set<unknown>();
+    const onRead = (result: unknown) => {
+      if (!result || typeof result !== 'object' || !Array.isArray((result as { tools?: unknown }).tools)) return;
+      const r = result as { tools: McpToolDefinition[]; nextCursor?: unknown; _meta?: unknown };
+      for (const t of r.tools) read.push(t);
+      const rev = (r._meta as Record<string, unknown> | undefined)?.['mcpl/rev'];
+      if (typeof rev === 'number') revs.add(rev);
+      if (r.nextCursor !== undefined && r.nextCursor !== null) return;
+      this.tap({
+        kind: 'result', method: 'tools/list', params: {}, ...(revs.size > 1 ? { straddled: true } : {}),
+        result: { tools: read, ...(r._meta !== undefined ? { _meta: r._meta } : {}) }, awaited: true,
+      });
+    };
     for (let page = 0; page < MAX_TOOL_LIST_PAGES; page++) {
-      const result = await this.sendRequest('tools/list', cursor === undefined ? {} : { cursor }) as Record<string, unknown> | null;
+      const result = await this.sendRequest('tools/list', cursor === undefined ? {} : { cursor }, { onRead }) as Record<string, unknown> | null;
       const malformed = (why: string) =>
         new Error(`MCPL server "${this.id}" sent a malformed tools/list page ${page + 1}: ${why}`);
       if (!result || typeof result !== 'object' || !Array.isArray(result.tools)) {
         throw malformed('no tools array');
       }
       first ??= result;
-      tools.push(...(result.tools as McpToolDefinition[]));
+      for (const t of result.tools as McpToolDefinition[]) tools.push(t);
       if (result.nextCursor === undefined || result.nextCursor === null) {
         // The first page's other fields are kept as they came, so a
         // single-page answer is returned exactly as before.
@@ -2176,7 +2207,7 @@ export class McplServerConnection extends EventEmitter {
     }
 
     return new Promise((resolve, reject) => {
-      const pending: PendingRequest = { resolve, reject, method };
+      const pending: PendingRequest = { resolve, reject, method, ...(options.onRead ? { onRead: options.onRead } : {}) };
       const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
       if (timeoutMs > 0) {
         pending.timer = setTimeout(() => {
@@ -2218,7 +2249,7 @@ export class McplServerConnection extends EventEmitter {
       // RFC-014: a request whose result can carry hints is remembered past
       // its timeout, so a late result's hints still apply (readTap).
       if (this.readTap && HINTED_METHODS.has(method)) {
-        this.hintedRequests.set(id, { method, params });
+        this.hintedRequests.set(id, { method, params: hintedParams(method, params) });
         if (this.hintedRequests.size > 1000) this.hintedRequests.delete(this.hintedRequests.keys().next().value!);
       }
       try {
@@ -2341,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) {
@@ -2654,6 +2676,11 @@ export class McplServerConnection extends EventEmitter {
         logValueRedacted(response.error.message, redact),
       );
     } else {
+      try {
+        pending.onRead?.(response.result);
+      } catch (error) {
+        console.error(`MCPL server "${this.id}": reading ${pending.method}'s result failed: ${logDetail(describeCause(error))}`);
+      }
       pending.resolve(response.result);
     }
   }
@@ -2789,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;
+}