@animalabs/agent-framework 0.22.4 → 0.23.1

package/src/mcpl/transport.ts

@@ -23,6 +23,7 @@ import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
+import { describeCredentialError, noteDialSent, redactUrl, resolveServerBinding, urlAsDialed } from './protocol-family.js';
 import { assertBooleanSetting } from '../config-checks.js';
 import { logDetail } from './log-value.js';
 
@@ -45,6 +46,9 @@ export interface TransportCloseInfo {
  *  - `'stderr'` `(line: string)`            diagnostic line (stdio child stderr; never WS)
  *  - `'error'`  `(err: Error)`              transport-level error
  *  - `'close'`  `(info: TransportCloseInfo)` transport closed (once)
+ *  - `'unreaped'` `(failure: Error)`        a stdio child whose pipe failed
+ *    outlived SIGKILL too: the transport stays open, owning the child, and
+ *    close() retries the reap (never WS)
  *
  * Inbound `'line'`/`'stderr'` events are buffered until the first matching
  * listener attaches (and re-buffered whenever there are none), so no message is
@@ -90,6 +94,17 @@ export abstract class McplTransport extends EventEmitter {
     return '';
   }
 
+  /**
+   * The error a stdio child's stdin or stdout failed with, once one has. The
+   * transport is ending the child then, and stays open until it exits, but
+   * writes nothing more to it: writeLine drops each line, and both engines
+   * refuse a request as not sent. Undefined while writes go out, and always
+   * for a transport that has no pipes.
+   */
+  get pipeFailure(): Error | undefined {
+    return undefined;
+  }
+
   /**
    * Resolves once the server's diagnostic stream has ended or closed, so that
    * {@link stderrTail} holds what arrived on it, or once `ms` have passed while
@@ -167,7 +182,8 @@ export const CHILD_ENV_ALLOWLIST = [
   'http_proxy', 'https_proxy', 'no_proxy',
   '__CF_USER_TEXT_ENCODING',
   // Windows equivalents, harmless elsewhere.
-  'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT', 'APPDATA', 'LOCALAPPDATA', 'USERPROFILE',
+  // USERNAME is Windows' USER, which Python's getpass.getuser() reads there.
+  'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT', 'APPDATA', 'LOCALAPPDATA', 'USERPROFILE', 'USERNAME',
 ];
 
 /** Environment for a stdio child: allowlisted host vars (+ LC_*), then the
@@ -244,6 +260,10 @@ export class StdioTransport extends McplTransport {
     return (this.stderrCut ? '…' : '') + this.stderrEnd;
   }
 
+  override get pipeFailure(): Error | undefined {
+    return this.pipeError;
+  }
+
   override stderrEnded(ms: number): Promise<void> {
     const stderr = this.child.stderr;
     if (!stderr || this.stderrDone) return Promise.resolve();
@@ -266,6 +286,8 @@ export class StdioTransport extends McplTransport {
   private constructor(
     private readonly child: ChildProcess,
     private readonly rl: ReadlineInterface,
+    /** The server this child serves, named in its stderr lines and in what
+     *  its reaping reports. */
     serverId: string,
   ) {
     super(serverId);
@@ -301,16 +323,26 @@ export class StdioTransport extends McplTransport {
     this.child.on('error', (err) => this.reportError(err));
     // The child's stdin and stdout carry the protocol, so after an error on
     // either, a write's EPIPE or a read error, this transport can't reach the
-    // child even if it's still running. The handler sends a running child
-    // SIGTERM, and the exit's close names the error, so the connection handles
-    // it as any other exit. The close is the report: no 'error' is emitted,
-    // nothing is thrown. Nothing here escalates to SIGKILL, so a child that
-    // ignores SIGTERM keeps running, unreported. A child that stops reading
-    // without closing its stdin raises no error: the writes are buffered, and
-    // only request timeouts bound it (McplServerConfig.requestTimeoutMs).
+    // child even if it's still running. The handler ends the child as close()
+    // does, SIGTERM and then SIGKILL, in the one attempt close() shares, and
+    // the exit's close names the error, so the connection handles it as any
+    // other exit. The close is the report: no 'error' is emitted, nothing is
+    // thrown, and nothing more is written meanwhile (pipeFailure). The first
+    // error starts that one attempt, and a later one, from either pipe, adds
+    // nothing to it. A child that outlives SIGKILL too stays this
+    // transport's: 'unreaped' says so, unless the host is closing it, whose
+    // close() reports the failure itself. A child that stops reading without
+    // closing its stdin raises no error: the writes are buffered, and only
+    // request timeouts bound it (McplServerConfig.requestTimeoutMs). Under
+    // Bun a child that closes its stdin isn't reported either: Bun emits no
+    // 'error' for the writes to it (checked on 1.3.10, 1.4.3 and 1.4.4's
+    // canary), so request timeouts are its only bound too.
     const endOnPipeError = (err: Error) => {
-      this.pipeError ??= err;
-      if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+      if (this.pipeError) return;
+      this.pipeError = err;
+      void this.terminate().catch((failure: unknown) => {
+        if (!this.closed) this.emit('unreaped', failure instanceof Error ? failure : new Error(String(failure)));
+      });
     };
     this.child.stdin?.on('error', endOnPipeError);
     // On the stream itself, since close() closes readline, which takes its own
@@ -367,31 +399,89 @@ export class StdioTransport extends McplTransport {
   }
 
   writeLine(json: string): void {
+    // Nothing more goes to a child whose stdin or stdout has failed: this
+    // transport is ending it.
+    if (this.pipeError) return;
     // stdin may be gone if the child died between the closed-check and here.
     this.child.stdin?.write(json + '\n');
   }
 
-  async close(): Promise<void> {
+  private closing: Promise<void> | null = null;
+
+  /**
+   * Close and reap: resolves once the child has actually exited, not merely
+   * been signalled (`child.killed` is true as soon as a signal is sent). A
+   * child that outlives SIGTERM by {@link STDIO_EXIT_GRACE_MS} gets SIGKILL.
+   * If it still hasn't exited after that bound again, close rejects: an
+   * explicit cleanup failure, rather than waiting forever or claiming an
+   * exit that wasn't seen. Calls share one attempt, and so does a pipe
+   * failure that is already ending the child; a later call succeeds if the
+   * child has exited since.
+   */
+  close(): Promise<void> {
+    if (!this.closing) {
+      this.closing = this.reap();
+      return this.closing;
+    }
+    // A later call re-checks a failed verdict: a child that has exited since
+    // is reaped now. No new signals are sent.
+    return this.closing.catch((error: unknown) => {
+      if (this.exited()) return;
+      throw error;
+    });
+  }
+
+  private async reap(): Promise<void> {
     this.markClosed({ reason: 'closed by host' });
     this.rl.close();
-    if (this.child && !this.child.killed) {
-      this.child.kill();
-    }
-    await new Promise<void>((resolve) => {
-      // Once Node has seen a child exit, it has its exitCode set, or its
-      // signalCode when a signal ended it, and its 'exit' event has fired. A
-      // signal that didn't come through kill() (an OOM kill, a crash) leaves
-      // `killed` false. A child that has exited but isn't reaped yet still
-      // takes the kill() above, which sets `killed`.
-      if (!this.child || this.child.exitCode !== null || this.child.signalCode !== null || this.child.killed) {
-        resolve();
-      } else {
-        this.child.once('exit', () => resolve());
-      }
+    await this.terminate();
+  }
+
+  /** Whether the child has exited, or never started (a spawn error). */
+  private exited(): boolean {
+    return this.child.pid === undefined || this.child.exitCode !== null || this.child.signalCode !== null;
+  }
+
+  private terminating: Promise<void> | null = null;
+
+  /**
+   * End the child: SIGTERM, then SIGKILL once it has outlived SIGTERM by
+   * {@link STDIO_EXIT_GRACE_MS}. Resolves once it has exited; rejects if it
+   * still hasn't that long after SIGKILL. close() and a pipe failure share
+   * one attempt, so no second signal or timer goes out. A failed attempt is
+   * re-checked, not repeated: a child that has exited since resolves it.
+   */
+  private terminate(): Promise<void> {
+    this.terminating ??= this.escalate();
+    return this.terminating.catch((error: unknown) => {
+      if (this.exited()) return;
+      throw error;
     });
   }
+
+  private async escalate(): Promise<void> {
+    const child = this.child;
+    if (this.exited()) return;
+    const exited = new Promise<void>((resolve) => child.once('exit', () => resolve()));
+    const exitWithin = (ms: number) => new Promise<boolean>((resolve) => {
+      const timer = setTimeout(() => resolve(false), ms);
+      void exited.then(() => { clearTimeout(timer); resolve(true); });
+    });
+    child.kill('SIGTERM');
+    if (await exitWithin(STDIO_EXIT_GRACE_MS)) return;
+    const named = `stdio child ${child.pid} of MCP server "${this.serverId}"`;
+    console.error(`[mcpl] ${named} ignored SIGTERM for ${STDIO_EXIT_GRACE_MS}ms — sending SIGKILL`);
+    child.kill('SIGKILL');
+    if (await exitWithin(STDIO_EXIT_GRACE_MS)) return;
+    throw new Error(
+      `${named} did not exit within ${STDIO_EXIT_GRACE_MS}ms of SIGKILL; it could not be reaped`,
+    );
+  }
 }
 
+/** How long a stdio child gets to exit after SIGTERM, and again after SIGKILL. */
+const STDIO_EXIT_GRACE_MS = 2_000;
+
 // ---------------------------------------------------------------------------
 // WebSocket
 // ---------------------------------------------------------------------------
@@ -399,6 +489,18 @@ export class StdioTransport extends McplTransport {
 /** Timeout for the WebSocket to reach OPEN before we give up (ms). */
 const WS_OPEN_TIMEOUT_MS = 15_000;
 
+/** `work`, or `signal`'s reason once it aborts, whichever comes first. The
+ *  listener comes off the signal when `work` settles, so a long-lived signal,
+ *  such as a reconnect loop's, doesn't gather one per dial. */
+function raceAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
+    work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+  });
+}
+
 export class WebSocketTransport extends McplTransport {
   readonly kind = 'websocket' as const;
 
@@ -425,28 +527,43 @@ export class WebSocketTransport extends McplTransport {
   /**
    * Dial `config.url` and resolve once the socket is OPEN. Appends `?token=`
    * when `config.token` is set. Rejects on connect error / timeout (and tears
-   * the socket down) so a failed dial never leaks an open handle.
+   * the socket down) so a failed dial never leaks an open handle. `signal`
+   * ends a dial whose connection is closed meanwhile, at once, rather than
+   * at the open timeout.
    */
-  static async open(config: McplServerConfig): Promise<WebSocketTransport> {
+  static async open(config: McplServerConfig, signal?: AbortSignal): Promise<WebSocketTransport> {
     // Resolve the per-dial credential first: the provider runs on every
     // connect AND reconnect, so rotation happens at the transport layer and
     // nothing above it ever holds a credential.
     let token: string | null = config.token ?? null;
+    const abandoned = (): Error =>
+      new Error(`MCPL server "${config.id}" WebSocket connect abandoned: the connection was closed (${redactUrl(config.url)})`);
     if (config.accessProvider) {
+      if (signal?.aborted) throw abandoned();
       try {
-        token = (await config.accessProvider()) ?? token;
+        // A dial whose connection is closed meanwhile stops waiting for the
+        // provider; whatever the provider does later is ignored.
+        const provided = Promise.resolve(config.accessProvider());
+        provided.catch(() => { /* a late failure after the dial was abandoned */ });
+        token = (signal ? await raceAbort(provided, signal) : await provided) ?? token;
       } catch (err) {
+        if (signal?.aborted) throw abandoned();
         // Fall back to the static token (if any) rather than failing the dial
         // outright — the server will refuse a stale credential loudly anyway.
+        // The provider's own text may quote the credential, so it isn't logged.
         console.error(
-          `[mcpl] server "${config.id}": access provider failed (${err instanceof Error ? err.message : err}) — dialing with configured fallback`,
+          `[mcpl] server "${config.id}": access provider failed (${describeCredentialError(err)}) — dialing with configured fallback`,
         );
       }
     }
     const url = buildWebSocketUrl(config, token);
+    // A provider's token is in this url, and the query may be re-encoded:
+    // the server's text is recorded with what the dial sent, the token in
+    // each form a token is replaced in.
+    noteDialSent(config, { url, token: token ?? undefined });
     // Error strings travel: traces, logs, tool results the model reads. They
     // get the endpoint, never the credential.
-    const redacted = buildWebSocketUrl({ ...config, token: undefined }, null);
+    const redacted = redactUrl(config.url);
     const ws = new WebSocket(url);
 
     // A failed dial can emit 'error' MORE THAN ONCE on the raw socket (seen
@@ -460,31 +577,36 @@ export class WebSocketTransport extends McplTransport {
 
     return new Promise<WebSocketTransport>((resolve, reject) => {
       let settled = false;
-      const timer = setTimeout(() => {
+      const abandon = (error: Error): void => {
         if (settled) return;
         settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
         ws.removeAllListeners();
         ws.on('error', swallowLateErrors);
         try { ws.terminate(); } catch { /* already gone */ }
-        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${redacted})`));
+        reject(error);
+      };
+      const timer = setTimeout(() => {
+        abandon(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${redacted})`));
       }, WS_OPEN_TIMEOUT_MS);
+      const onAbort = (): void => {
+        abandon(new Error(`MCPL server "${config.id}" WebSocket connect abandoned: the connection was closed (${redacted})`));
+      };
+      if (signal?.aborted) onAbort();
+      else signal?.addEventListener('abort', onAbort, { once: true });
 
       ws.once('open', () => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
         ws.removeAllListeners('error'); // the instance re-attaches its own handlers
         resolve(new WebSocketTransport(ws, config.id));
       });
 
       ws.once('error', (err: Error) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        ws.removeAllListeners();
-        ws.on('error', swallowLateErrors);
-        try { ws.terminate(); } catch { /* already gone */ }
-        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${redacted})`));
+        abandon(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${redacted})`));
       });
     });
   }
@@ -514,8 +636,9 @@ export class WebSocketTransport extends McplTransport {
 }
 
 /**
- * Build the dial URL: validate it's a ws(s):// URL and append the auth token as
- * a `token` query param when provided (preserving any existing query).
+ * Build the dial URL: validate it's a ws(s):// URL the ws library will dial,
+ * which refuses one with a fragment, and append the auth token as a `token`
+ * query param when provided (preserving any existing query).
  */
 export function buildWebSocketUrl(config: McplServerConfig, tokenOverride?: string | null): string {
   if (!config.url) {
@@ -525,30 +648,45 @@ export function buildWebSocketUrl(config: McplServerConfig, tokenOverride?: stri
   try {
     parsed = new URL(config.url);
   } catch {
-    throw new Error(`MCPL server "${config.id}": invalid WebSocket url "${config.url}"`);
+    // Not echoed: a url that doesn't parse can't be redacted.
+    throw new Error(`MCPL server "${config.id}": invalid WebSocket url (it isn't shown, since it may carry a credential)`);
   }
   if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
     throw new Error(
       `MCPL server "${config.id}": websocket url must be ws:// or wss://, got "${parsed.protocol}"`,
     );
   }
-  const token = tokenOverride !== undefined ? tokenOverride : config.token;
-  if (token) {
-    parsed.searchParams.set('token', token);
+  if (parsed.hash) {
+    throw new Error(`MCPL server "${config.id}": websocket url must not have a fragment, got "${parsed.hash}"`);
   }
-  return parsed.toString();
+  const token = tokenOverride !== undefined ? tokenOverride : config.token;
+  return urlAsDialed(parsed, token).toString();
 }
 
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
 
-/** True when the config selects the WebSocket transport (explicit `transport`,
- *  or a `url` with no `command`). */
+/** True when the config selects the WebSocket transport, as
+ *  {@link resolveServerBinding} decides it; false for any other transport and
+ *  for a configuration it refuses. */
 export function isWebSocketTransport(config: McplServerConfig): boolean {
-  if (config.transport === 'websocket') return true;
-  if (config.transport === 'stdio') return false;
-  return Boolean(config.url) && !config.command;
+  try {
+    return resolveServerBinding(config).transport === 'websocket';
+  } catch {
+    return false;
+  }
+}
+
+/** Whether a server's binding dials it, over WebSocket or HTTP. False for a
+ *  stdio launch, and for a configuration whose binding can't be resolved,
+ *  which the family check refuses. */
+function dialsNetwork(config: McplServerConfig): boolean {
+  try {
+    return resolveServerBinding(config).transport !== 'stdio';
+  } catch {
+    return false;
+  }
 }
 
 /** The settings of McplServerConfig whose type is boolean. */
@@ -572,25 +710,29 @@ const SERVER_CONFIG_BOOLEANS: Record<BooleanSetting, string> = {
  * only `true` as on, so the quotes would hide what the value does. null counts
  * as not set, so a generated config that writes an unset setting as null
  * keeps working. `inheritEnv` is checked only for a stdio server, since a
- * WebSocket server never reads it. The error names the server, the setting
- * and the value's kind, not the value, which could be a secret pasted into
- * the wrong field.
+ * network server, WebSocket or HTTP, never reads it. The error names the
+ * server, the setting and the value's kind, not the value, which could be a
+ * secret pasted into the wrong field.
  */
 export function assertServerConfigBooleans(config: McplServerConfig): void {
   for (const [setting, whatTrueDoes] of Object.entries(SERVER_CONFIG_BOOLEANS) as Array<[BooleanSetting, string]>) {
-    if (setting === 'inheritEnv' && isWebSocketTransport(config)) continue;
+    if (setting === 'inheritEnv' && dialsNetwork(config)) continue;
     assertBooleanSetting(`MCPL server "${config.id}" ${setting}`, config[setting], whatTrueDoes);
   }
 }
 
 /**
- * Open the transport selected by `config` (WebSocket when `transport` is
- * 'websocket' or a bare `url` is given; stdio otherwise). The returned transport
- * is connected at the byte level but has NOT performed the MCPL handshake.
+ * Open the legacy transport `config` selects, as {@link resolveServerBinding}
+ * decides it: stdio for a `command`, MCPL's WebSocket binding for a ws(s)://
+ * url. A configuration it refuses, or one for the modern family (an http(s)
+ * url, or `protocol: 'modern'`), throws before anything is spawned or dialed.
+ * The returned transport is connected at the byte level but has NOT
+ * performed the MCPL handshake.
  */
-export async function openTransport(config: McplServerConfig): Promise<McplTransport> {
-  if (isWebSocketTransport(config)) {
-    return WebSocketTransport.open(config);
+export async function openTransport(config: McplServerConfig, signal?: AbortSignal): Promise<McplTransport> {
+  const binding = resolveServerBinding(config);
+  if (binding.family !== 'legacy') {
+    throw new Error(`MCP server "${config.id}" is configured for modern MCP; the legacy transports can't open it`);
   }
-  return StdioTransport.spawn(config);
+  return binding.transport === 'websocket' ? WebSocketTransport.open(config, signal) : StdioTransport.spawn(config);
 }

package/src/mcpl/types.ts

@@ -211,15 +211,22 @@ export interface McplChannelCapabilities {
 /**
  * Configuration for connecting to a single MCPL server.
  * Provided in FrameworkConfig.mcplServers[].
+ *
+ * Treat a submitted configuration and its nested values as immutable for as
+ * long as the server uses them. Apply changed settings with
+ * `restartMcplServer(id, newConfig)`; use `accessProvider` for a network
+ * server's rotating credentials (a stdio server's changed `env` goes through
+ * a restart with the new configuration).
  */
 export interface McplServerConfig {
   /** Unique server identifier */
   id: string;
 
   /**
-   * Command to spawn the server process (stdio transport). Mutually exclusive
-   * with `url`. Required for the stdio transport; omit it (and set `url`) for
-   * the WebSocket transport.
+   * Command to spawn the server process (stdio transport). Required for the
+   * stdio transport; omit it (and set `url`) for a network server, over
+   * WebSocket or HTTP. A configuration with both needs `transport` to say
+   * which one is used, and is refused without it.
    */
   command?: string;
 
@@ -246,22 +253,41 @@ export interface McplServerConfig {
   inheritEnv?: boolean;
 
   /**
-   * WebSocket URL for the network transport (`ws://` or `wss://`). Mutually
-   * exclusive with `command`. When set (or `transport: 'websocket'`), the host
-   * dials this endpoint instead of spawning a process — newline-delimited
-   * JSON-RPC MCPL runs over the socket identically to stdio.
+   * URL for a network server, used instead of `command`. A configuration
+   * with both needs `transport` to say which one is used, and is refused
+   * without it. Its scheme decides the protocol family:
+   * - `ws://` or `wss://` is a legacy MCPL server over MCPL's WebSocket
+   *   binding. The host dials it and runs the same newline-delimited JSON-RPC
+   *   as over stdio.
+   * - `http://` or `https://` is a modern MCP (2026-07-28) server over
+   *   Streamable HTTP.
    */
   url?: string;
 
   /**
-   * Transport selector. Defaults to `'websocket'` when a bare `url` is given
-   * (no `command`), `'stdio'` otherwise. Set explicitly to disambiguate.
+   * Transport selector. When it is absent, a `command` means stdio and a
+   * `url` means the transport its scheme names; with both, it is required.
+   * When it is set, it decides which of the two is used and must agree with
+   * it: `'stdio'` needs a `command`, `'websocket'` a ws(s):// url and
+   * `'http'` an http(s):// url.
+   */
+  transport?: 'stdio' | 'websocket' | 'http';
+
+  /**
+   * Protocol family for a stdio (`command`) server. Defaults to `'legacy'`,
+   * which is MCP 2024-11-05 + MCPL and today's behavior. `'modern'` speaks
+   * MCP 2026-07-28 through the SDK-backed modern engine. A network server's
+   * family comes from its url's scheme, so setting this on one is a
+   * configuration error. There is no probing between families.
    */
-  transport?: 'stdio' | 'websocket';
+  protocol?: 'legacy' | 'modern';
 
   /**
-   * Bearer token for WebSocket auth. Appended to `url` as a `token` query
-   * parameter (`?token=…`) on connect. Ignored by the stdio transport.
+   * Bearer token for a network server. Where it travels depends on the
+   * transport: on a ws(s):// url it is appended as a `token` query parameter
+   * (`?token=…`) on connect; to an http(s):// server it is sent as an
+   * `Authorization: Bearer` header and never put in the url. A legacy stdio
+   * server ignores it, and a modern stdio server refuses it.
    */
   token?: string;
 
@@ -384,12 +410,20 @@ export interface McplServerConfig {
    * descriptive error, which the framework surfaces as a normal isError
    * tool_result. Request timeouts are the only bound for a stdio server that
    * stops reading its stdin without closing it: the host's writes are
-   * buffered, no error is raised, and the connection stays up. This is the
-   * timeout of every request that names none; the handshake's initialize has
-   * its own. Set 0 to disable, except for channels/publish and the
-   * channels/open a delivery may send first, which keep the 60 s default: a
-   * publish's outcome is reported to the resident and recorded for its
-   * draft, so it must end. Default: 60000 (60 seconds).
+   * buffered, no error is raised, and the connection stays up. Under Bun they
+   * are also the only bound for one that closes its stdin, since Bun emits no
+   * 'error' event for the writes to it. requestTimeoutMs is the timeout of
+   * every request that names none; the handshake's initialize has its own.
+   * Set 0 to disable, except for channels/publish and the channels/open a
+   * delivery may send first, which keep the 60 s default: a publish's outcome
+   * is reported to the resident and recorded for its draft, so it must end.
+   * Default: 60000 (60 seconds). A value above 2^31−1 is refused: Node runs a
+   * longer timer after about 1 ms, so every request would time out at once.
+   *
+   * For a modern server it is one deadline per tool call, across every leg
+   * of the call, and must be an integer from 1 to 2^31−1. It can't be
+   * disabled: the SDK reads 0 as "time out now". At the deadline
+   * cancellation is requested and the outcome is unknown.
    */
   requestTimeoutMs?: number;
 
@@ -419,7 +453,10 @@ export interface McplServerConfig {
    * `toolLifecycle.*.tools`) match these full names; `enabledTools` /
    * `disabledTools` use the bare server-side names.
    *
-   * Must not collide with any module name or another server's prefix.
+   * Must not equal any module name or another server's prefix, nor meet
+   * another server's prefix: two prefixes meet when one is the other
+   * followed by `-`, or begins with the other followed by `--`, as `foo-`
+   * and `foo--bar` each meet `foo` (prefixesMeet, #265).
    */
   toolPrefix?: string;
 
@@ -1075,7 +1112,15 @@ export interface ChannelsListResult {
  * Spec Section 14.3.
  */
 export interface ChannelsOpenParams {
-  /** Exact registered id. Preferred over type/address matching. */
+  /**
+   * The exact registered id to open. Without it, a server matches by `type`
+   * and `address`, as before. A server that doesn't know the id should
+   * refuse rather than open another channel: the host fails an open whose
+   * answer names a different channel id, by its `channel.id` or a history
+   * item's `channelId`, compared exactly, as the server's traffic is. When
+   * that other channel is registered and decided closed, the host closes it
+   * again.
+   */
   channelId?: string;
   type: string;
   address?: Record<string, unknown>;
@@ -1330,6 +1375,8 @@ export interface McpToolDefinition {
   name: string;
   description?: string;
   inputSchema: Record<string, unknown>;
+  /** Server metadata for the tool (e.g. RFC-008 `mcpl/class` hints). */
+  _meta?: Record<string, unknown>;
 }
 
 /**

package/src/mcpl/visible-content.ts

@@ -36,8 +36,9 @@ export function isVisiblyEmptyContent(content: readonly unknown[] | null | undef
  * block whose text isn't a string, which only a nonconformant sender writes,
  * so the agent learns that a block was there. It is the host's word, not the
  * sender's, so it never makes content visible (isVisiblyEmptyConversion).
+ * The other blocks the converters can't show have theirs in references.ts.
  */
-export const NON_STRING_TEXT_PLACEHOLDER = "[Text not shown: the server's text block had no string text.]";
+export const NON_STRING_TEXT_PLACEHOLDER = '[Text not shown: a text part arrived without readable text.]';
 
 /** A wire text block whose text isn't a string, which the converter shows as
  *  NON_STRING_TEXT_PLACEHOLDER. */