@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/mcpl/server-registry.ts

@@ -42,14 +42,16 @@ export class McplServerRegistry {
       throw new Error(`MCPL server "${config.id}" is already registered`);
     }
 
-    const connection = config.reconnect
+    const connection = config.reconnect === true
       ? await McplServerConnection.connectWithReconnect(config, hostCapabilities)
       : await McplServerConnection.connect(config, hostCapabilities);
     this.servers.set(config.id, connection);
 
-    // Auto-remove on unexpected close (unless reconnect will re-add)
+    // Auto-remove on close unless the connection will reconnect. That was
+    // decided once, from `reconnect === true` at connect, and a close() the
+    // host asks for disarms it first, so a server closed for good goes too.
     connection.on('close', () => {
-      if (!config.reconnect) {
+      if (!connection.willReconnect) {
         this.servers.delete(config.id);
       }
     });
@@ -146,7 +148,16 @@ export class McplServerRegistry {
     })), timeoutMs);
   }
 
-  private closeServer(id: string, connection: McplServerConnection): Promise<void> {
+  /**
+   * Close a server for good and drop its entry, if this connection is still
+   * the one registered under `id`. The entry goes when close() resolves,
+   * whatever the connection reports: close() emits no 'close' for a
+   * connection that's down between retries, such as a reconnect stub waiting
+   * for its next retry, so the 'close' listener alone would leave it
+   * registered. A close that fails keeps the entry and rejects; a close
+   * already under way is shared.
+   */
+  closeServer(id: string, connection: McplServerConnection): Promise<void> {
     const existing = this.closing.get(connection);
     if (existing) return existing;
     const attempt = Promise.resolve().then(() => connection.close()).then(() => {

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

@@ -0,0 +1,73 @@
+/**
+ * How `skip_reply` reads its `wake_in_seconds`, for every site that acts on
+ * it: the framework arms the EventGate's timer or refuses the call, the turn's
+ * bookkeeping of a refused round asks whether it was refused, and the channel
+ * registry words the confirmation. One reading, so a value can't arm a timer
+ * at one site and read as no wake at another, and the confirmation names the
+ * seconds the timer is set for.
+ */
+import { safeSlice } from '../safe-slice.js';
+
+/** The range the tool's schema offers, in seconds: a larger number waits the most. */
+export const SKIP_REPLY_WAKE_MIN_SECONDS = 1;
+export const SKIP_REPLY_WAKE_MAX_SECONDS = 3600;
+
+/**
+ * What a `skip_reply` call's `wake_in_seconds` asks for:
+ * - `none`: absent or `null`, an ordinary skip;
+ * - `wake`: a number of at least 1, or a string that `Number()` reads as one,
+ *   in whole seconds and at most 3600, so 90.7 waits 90 s and anything over
+ *   3600, Infinity included, waits 3600 s;
+ * - `invalid`: anything else, which asks for no number of seconds the host can
+ *   set: a number below 1, such as 0, a negative or 0.5, and "soon", "",
+ *   `true`, an array or an object. Below 1 is refused rather than raised to 1:
+ *   0 is a value a model may write when it fills an optional number with a
+ *   default, and as a 1 s wake it would wake the agent again a second after
+ *   each turn, for as long as it kept skipping with 0.
+ */
+export type SkipReplyWake =
+  | { kind: 'none' }
+  | { kind: 'wake'; seconds: number }
+  | { kind: 'invalid'; value: unknown };
+
+export function readSkipReplyWake(input: unknown): SkipReplyWake {
+  const value = input !== null && typeof input === 'object'
+    ? (input as Record<string, unknown>).wake_in_seconds
+    : undefined;
+  if (value === undefined || value === null) return { kind: 'none' };
+  // A blank string reads as 0, so it's refused as a number below 1.
+  const seconds = typeof value === 'number' ? value
+    : typeof value === 'string' ? Number(value)
+    : Number.NaN;
+  if (Number.isNaN(seconds) || seconds < SKIP_REPLY_WAKE_MIN_SECONDS) return { kind: 'invalid', value };
+  return { kind: 'wake', seconds: Math.floor(Math.min(SKIP_REPLY_WAKE_MAX_SECONDS, seconds)) };
+}
+
+/** 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.";
+
+/**
+ * Why a `skip_reply` call is refused, as the model will read it, or undefined
+ * when it isn't: without an EventGate, any `wake_in_seconds` but absent or
+ * `null`, since the host offers none; with one, a value that isn't a number of
+ * seconds. A refused call arms nothing and doesn't end the turn.
+ */
+export function skipReplyWakeRefusal(wake: SkipReplyWake, gatePresent: boolean): string | undefined {
+  if (wake.kind === 'none') return undefined;
+  if (!gatePresent) return SKIP_REPLY_WAKE_NO_GATE_REFUSAL;
+  if (wake.kind === 'wake') return undefined;
+  return `Your turn didn't end, and no wake was set: wake_in_seconds takes a number of seconds from ${SKIP_REPLY_WAKE_MIN_SECONDS} to ${SKIP_REPLY_WAKE_MAX_SECONDS}, and ${describeValue(wake.value)} isn't one. Call skip_reply with a number of seconds to come back on your own, or without wake_in_seconds to end the turn and wait for the next message.`;
+}
+
+/**
+ * A value as the model wrote it, as JSON, cut to keep the refusal short,
+ * never between the halves of a surrogate pair. A tool call's input is parsed
+ * JSON, so it always has a JSON text, but JSON writes a number that isn't
+ * finite as `null`, and `-1e400` parses as -Infinity, so a number prints as
+ * `String()` of it.
+ */
+function describeValue(value: unknown): string {
+  const text = typeof value === 'number' ? String(value) : JSON.stringify(value);
+  return text.length > 80 ? `${safeSlice(text, 0, 80)}…` : text;
+}

package/src/mcpl/tool-classes.ts

@@ -21,6 +21,7 @@
  */
 
 import { globMatch } from './tool-glob.js';
+import { logValue } from './log-value.js';
 
 export const TOOL_CLASSES = [
   'comms',
@@ -116,7 +117,7 @@ export function parseDeclaredClasses(meta: unknown, toolName = '(unnamed)'): Too
   const raw = (meta as Record<string, unknown>)[TOOL_CLASS_META_KEY];
   if (raw === undefined) return undefined;
   if (!Array.isArray(raw)) {
-    console.error(`[mcpl] ${toolName}: _meta["${TOOL_CLASS_META_KEY}"] is not an array — treated as unclassed`);
+    console.error(`[mcpl] ${logValue(toolName)}: _meta["${TOOL_CLASS_META_KEY}"] is not an array — treated as unclassed`);
     return undefined;
   }
   const out: ToolClass[] = [];
@@ -124,7 +125,7 @@ export function parseDeclaredClasses(meta: unknown, toolName = '(unnamed)'): Too
     if (isToolClass(value)) {
       if (!out.includes(value)) out.push(value);
     } else {
-      console.error(`[mcpl] ${toolName}: unknown tool class ${JSON.stringify(value)} ignored (RFC-008 §3)`);
+      console.error(`[mcpl] ${logValue(toolName)}: unknown tool class ${logValue(value)} ignored (RFC-008 §3)`);
     }
   }
   return out.length > 0 ? out : undefined;

package/src/mcpl/transport.ts

@@ -19,9 +19,12 @@
 import { spawn, type ChildProcess } from 'node:child_process';
 import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
+import { assertBooleanSetting } from '../config-checks.js';
+import { logDetail } from './log-value.js';
 
 /** Why/how a transport closed. `code`/`signal` are populated for stdio child
  *  exits; `reason` carries a WebSocket close reason or an error message. */
@@ -29,6 +32,9 @@ export interface TransportCloseInfo {
   code?: number | null;
   signal?: NodeJS.Signals | null;
   reason?: string;
+  /** True when `reason` is the peer's own text, a WebSocket server's close
+   *  reason, rather than the transport's words. */
+  reasonFromPeer?: boolean;
 }
 
 /**
@@ -51,7 +57,10 @@ export abstract class McplTransport extends EventEmitter {
   private lineBuffer: string[] = [];
   private stderrBuffer: string[] = [];
 
-  protected constructor() {
+  /** The server's id from its config, so a line the transport logs names it.
+   *  The stdio and WebSocket transports always give it; a test's stand-in
+   *  transport may leave it out. */
+  protected constructor(protected readonly serverId?: string) {
     super();
     // Flush buffered inbound lines the moment a consumer subscribes.
     this.on('newListener', (event) => {
@@ -71,6 +80,25 @@ export abstract class McplTransport extends EventEmitter {
     return this._closed;
   }
 
+  /**
+   * The last of what the server wrote to its diagnostic stream: at most its
+   * last {@link STDERR_TAIL_CHARS} UTF-16 code units, never opening inside a
+   * surrogate pair, after a '…' when earlier ones were dropped. A stdio
+   * child's stderr, and '' for a transport that has none.
+   */
+  get stderrTail(): string {
+    return '';
+  }
+
+  /**
+   * 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
+   * it hasn't. At once for a transport that has none.
+   */
+  stderrEnded(_ms: number): Promise<void> {
+    return Promise.resolve();
+  }
+
   /** Deliver an inbound line, buffering it if nobody is listening yet. */
   protected pushLine(line: string): void {
     if (this.listenerCount('line') > 0) this.emit('line', line);
@@ -83,6 +111,23 @@ export abstract class McplTransport extends EventEmitter {
     else this.stderrBuffer.push(line);
   }
 
+  /**
+   * Report a transport error: to the 'error' listeners if there are any, else
+   * as a log line. EventEmitter throws an 'error' that nothing listens for,
+   * and a transport reports its errors from I/O callbacks, where nothing
+   * catches that throw, so it would end the process. A transport has no
+   * listener from its creation until the handshake attaches one, and a
+   * WebSocket server that sends a malformed frame with its upgrade response
+   * makes ws raise an 'error' in that window.
+   */
+  protected reportError(err: Error): void {
+    if (this.listenerCount('error') > 0) this.emit('error', err);
+    else {
+      const server = this.serverId === undefined ? '' : `${this.serverId}: `;
+      console.error(`[mcpl] ${server}a ${this.kind} transport error, with nothing listening for it: ${logDetail(err.message)}`);
+    }
+  }
+
   /** Emit 'close' exactly once. */
   protected markClosed(info: TransportCloseInfo): void {
     if (this._closed) return;
@@ -127,15 +172,17 @@ export const CHILD_ENV_ALLOWLIST = [
 
 /** Environment for a stdio child: allowlisted host vars (+ LC_*), then the
  *  server's declared `env` on top. Windows names merge case-insensitively;
- *  POSIX names remain case-sensitive. `inheritEnv: true` restores full inheritance. */
+ *  POSIX names remain case-sensitive. `inheritEnv: true` restores full inheritance,
+ *  and only `true` does: a direct caller can pass any value, unchecked. */
 export function buildChildEnv(
   config: Pick<McplServerConfig, 'env' | 'inheritEnv'>,
   hostEnv: NodeJS.ProcessEnv = process.env,
   platform: NodeJS.Platform = process.platform,
 ): NodeJS.ProcessEnv {
   const win = platform === 'win32';
-  const env: NodeJS.ProcessEnv = config.inheritEnv ? { ...hostEnv } : {};
-  if (!config.inheritEnv) {
+  const inherit = config.inheritEnv === true;
+  const env: NodeJS.ProcessEnv = inherit ? { ...hostEnv } : {};
+  if (!inherit) {
     for (const [key, value] of Object.entries(hostEnv)) {
       if (value === undefined) continue;
       // Windows commonly enumerates Path/SystemRoot rather than PATH/SYSTEMROOT.
@@ -167,37 +214,129 @@ export function buildChildEnv(
   return merged;
 }
 
+/** The most of a stdio child's stderr a transport keeps for {@link McplTransport.stderrTail}. */
+export const STDERR_TAIL_CHARS = 2_048;
+
+/**
+ * How long a refusal at a stdio child's exit waits for the child's stderr to
+ * end, so that its `stderrTail` holds what the child wrote. Node can emit a
+ * child's `exit` before it has read the last of the child's stderr. When the
+ * child held the stream alone, the stream ends with it, and the wait is short.
+ * The bound binds when another process still holds the stream, such as one the
+ * server started that inherited it, or when the host's loop stalls past it
+ * before reading an end that is waiting. The tail then holds what had arrived.
+ * A process that keeps the stream open, such as one the server started and
+ * left running, holds the refusal up by the bound, a fifth of the reconnect's
+ * default first interval.
+ */
+export const STDERR_END_WAIT_MS = 1_000;
+
 export class StdioTransport extends McplTransport {
   readonly kind = 'stdio' as const;
+  /** The first error on the child's stdin or stdout, named in the close reason. */
+  private pipeError: Error | undefined;
+  private stderrEnd = '';
+  private stderrCut = false;
+  /** True once the child's stderr has ended or closed. */
+  private stderrDone = false;
+
+  override get stderrTail(): string {
+    return (this.stderrCut ? '…' : '') + this.stderrEnd;
+  }
+
+  override stderrEnded(ms: number): Promise<void> {
+    const stderr = this.child.stderr;
+    if (!stderr || this.stderrDone) return Promise.resolve();
+    return new Promise((resolve) => {
+      let timer: NodeJS.Timeout | undefined;
+      const done = () => {
+        clearTimeout(timer);
+        stderr.off('end', done);
+        stderr.off('close', done);
+        resolve();
+      };
+      // Added after the constructor's listeners, so the tail already holds the
+      // stream's last characters when these run.
+      stderr.once('end', done);
+      stderr.once('close', done);
+      timer = setTimeout(done, ms);
+    });
+  }
 
   private constructor(
     private readonly child: ChildProcess,
     private readonly rl: ReadlineInterface,
+    serverId: string,
   ) {
-    super();
+    super(serverId);
 
     this.rl.on('line', (line: string) => this.pushLine(line));
 
-    // Stitch stderr chunks into whole lines (a chunk can split a line).
+    // Stitch stderr chunks into whole lines (a chunk can split a line, and a
+    // character's bytes), and keep the stream's last characters for
+    // stderrTail.
     let carry = '';
-    this.child.stderr?.on('data', (chunk: Buffer) => {
-      const text = carry + chunk.toString('utf8');
-      const lines = text.split('\n');
+    const decoder = new StringDecoder('utf8');
+    const received = (text: string) => {
+      const end = this.stderrEnd + text;
+      this.stderrCut ||= end.length > STDERR_TAIL_CHARS;
+      let kept = end.slice(-STDERR_TAIL_CHARS);
+      // A cut between a surrogate pair's halves drops the low half too.
+      if (/^[\uDC00-\uDFFF]/.test(kept) && end.length > STDERR_TAIL_CHARS) kept = kept.slice(1);
+      this.stderrEnd = kept;
+      const lines = (carry + text).split('\n');
       carry = lines.pop() ?? '';
       for (const l of lines) if (l.length > 0) this.pushStderr(l);
+    };
+    this.child.stderr?.on('data', (chunk: Buffer) => received(decoder.write(chunk)));
+    // A last line with no newline is complete once the stream ends.
+    this.child.stderr?.on('end', () => {
+      received(decoder.end());
+      if (carry.length > 0) this.pushStderr(carry);
+      this.stderrDone = true;
     });
-
-    this.child.on('error', (err) => this.emit('error', err));
-    this.child.on('exit', (code, signal) =>
-      this.markClosed({ code, signal, reason: 'child process exited' }),
-    );
+    // A stream destroyed by an error closes without ending: nothing more comes.
+    this.child.stderr?.on('close', () => { this.stderrDone = true; });
+
+    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).
+    const endOnPipeError = (err: Error) => {
+      this.pipeError ??= err;
+      if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+    };
+    this.child.stdin?.on('error', endOnPipeError);
+    // On the stream itself, since close() closes readline, which takes its own
+    // listener off the stream. While readline is open, its listener, which
+    // came first, re-emits the error on the interface, where an empty
+    // listener absorbs that copy.
+    this.child.stdout?.on('error', endOnPipeError);
+    this.rl.on('error', () => { /* readline's copy of a stdout error, handled above */ });
+    // stderr carries diagnostics only: a read error on it is reported, to the
+    // listeners or else in the log, and never thrown. It ends nothing once
+    // the connection is wired; during a handshake the listener is the
+    // handshake's, which fails it.
+    this.child.stderr?.on('error', (err) => this.reportError(err));
+    this.child.on('exit', (code, signal) => this.markClosed({
+      code,
+      signal,
+      reason: this.pipeError ? `child process exited, and its pipe failed with ${this.pipeError.message}` : 'child process exited',
+    }));
   }
 
   /**
-   * Spawn `config.command` and return a ready stdio transport. Rejects if the
-   * command is missing (a config bug) or the process fails to spawn.
+   * Spawn `config.command` and resolve with a ready stdio transport once the
+   * child has spawned. Rejects if the command is missing (a config bug) or the
+   * process fails to spawn.
    */
-  static spawn(config: McplServerConfig): StdioTransport {
+  static async spawn(config: McplServerConfig): Promise<StdioTransport> {
     if (!config.command) {
       throw new Error(
         `MCPL server "${config.id}": stdio transport requires "command" (none provided)`,
@@ -207,8 +346,24 @@ export class StdioTransport extends McplTransport {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: buildChildEnv(config),
     });
+    // Node reports a failed spawn (a command that doesn't exist, say) as an
+    // 'error' on a tick after spawn() returns, and no 'exit' follows. It is
+    // settled here, where it is listened for. A caller that listens only once
+    // this resolves, as the handshake does, would be too late when reached
+    // from a timer callback, as a reconnect is: Node runs that tick before the
+    // caller's promise continuation, and throws an 'error' nothing listens for.
+    await new Promise<void>((resolve, reject) => {
+      const failed = (err: Error) => {
+        reject(new Error(`MCPL server "${config.id}" could not be started: ${err.message}`, { cause: err }));
+      };
+      child.once('error', failed);
+      child.once('spawn', () => {
+        child.off('error', failed);
+        resolve();
+      });
+    });
     const rl = createInterface({ input: child.stdout! });
-    return new StdioTransport(child, rl);
+    return new StdioTransport(child, rl, config.id);
   }
 
   writeLine(json: string): void {
@@ -223,7 +378,12 @@ export class StdioTransport extends McplTransport {
       this.child.kill();
     }
     await new Promise<void>((resolve) => {
-      if (!this.child || this.child.exitCode !== null || this.child.killed) {
+      // 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());
@@ -242,8 +402,8 @@ const WS_OPEN_TIMEOUT_MS = 15_000;
 export class WebSocketTransport extends McplTransport {
   readonly kind = 'websocket' as const;
 
-  private constructor(private readonly ws: WebSocket) {
-    super();
+  private constructor(private readonly ws: WebSocket, serverId: string) {
+    super(serverId);
 
     this.ws.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
       // MCPL frames are UTF-8 JSON text. A frame MAY contain multiple
@@ -255,10 +415,11 @@ export class WebSocketTransport extends McplTransport {
       }
     });
 
-    this.ws.on('error', (err: Error) => this.emit('error', err));
-    this.ws.on('close', (code: number, reason: Buffer) =>
-      this.markClosed({ code, reason: reason?.toString('utf8') || 'websocket closed' }),
-    );
+    this.ws.on('error', (err: Error) => this.reportError(err));
+    this.ws.on('close', (code: number, reason: Buffer) => {
+      const text = reason?.toString('utf8');
+      this.markClosed(text ? { code, reason: text, reasonFromPeer: true } : { code, reason: 'websocket closed' });
+    });
   }
 
   /**
@@ -313,7 +474,7 @@ export class WebSocketTransport extends McplTransport {
         settled = true;
         clearTimeout(timer);
         ws.removeAllListeners('error'); // the instance re-attaches its own handlers
-        resolve(new WebSocketTransport(ws));
+        resolve(new WebSocketTransport(ws, config.id));
       });
 
       ws.once('error', (err: Error) => {
@@ -390,6 +551,38 @@ export function isWebSocketTransport(config: McplServerConfig): boolean {
   return Boolean(config.url) && !config.command;
 }
 
+/** The settings of McplServerConfig whose type is boolean. */
+type BooleanSetting = {
+  [K in keyof McplServerConfig]-?: NonNullable<McplServerConfig[K]> extends boolean ? K : never;
+}[keyof McplServerConfig];
+
+/** What `true` does for each boolean setting, as its refusal says it. A
+ *  boolean setting added to McplServerConfig doesn't compile until it has
+ *  an entry here, so the check below covers it too. */
+const SERVER_CONFIG_BOOLEANS: Record<BooleanSetting, string> = {
+  inheritEnv: 'true passes the server the host\'s whole environment, and false or leaving it out passes only the allowlisted and LC_* host variables',
+  reconnect: 'true retries in the background when the server can\'t be reached or its connection drops, and false or leaving it out doesn\'t',
+  allowHostCommands: 'true lets the server run the host\'s admin commands, such as undo, hide, unstick and quiesce, and false or leaving it out refuses them',
+};
+
+/**
+ * Refuse a server config whose `inheritEnv`, `reconnect` or `allowHostCommands`
+ * holds anything but true or false. A config read from JSON can carry a quoted
+ * "false" where the type says boolean, and every reader of these settings takes
+ * 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.
+ */
+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;
+    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

package/src/mcpl/types.ts

@@ -238,7 +238,10 @@ export interface McplServerConfig {
   /**
    * Escape hatch: pass the host's entire environment (including secrets) to
    * the stdio child, as older versions did. Only for servers that genuinely
-   * need it. Default false.
+   * need it. Default false. Only `true` turns it on, and null counts as not
+   * set. For a stdio server, `create()`, `connectMcplServer` and
+   * `restartMcplServer` refuse any other value, such as a quoted "false". A
+   * WebSocket server never reads it.
    */
   inheritEnv?: boolean;
 
@@ -278,7 +281,9 @@ export interface McplServerConfig {
    * unstick). DEFAULT FALSE: no §6.2 capability path exists for it, and the
    * grant cannot confer it — only this config, decided by the operator, can
    * (PR #79 review blocker 9). The one legitimate fleet user is
-   * discord-mcpl's slash-command relay.
+   * discord-mcpl's slash-command relay. Only `true` turns it on, and null
+   * counts as not set. `create()`, `connectMcplServer` and
+   * `restartMcplServer` refuse any other value, such as a quoted "true".
    */
   allowHostCommands?: boolean;
 
@@ -351,6 +356,9 @@ export interface McplServerConfig {
    * When true, connect() resolves immediately (with null capabilities) if the
    * server is unavailable, and retries in the background.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+   * Only `true` turns it on, and null counts as not set. `create()`,
+   * `connectMcplServer` and `restartMcplServer` refuse any other value, such
+   * as a quoted "false".
    */
   reconnect?: boolean;
 
@@ -374,7 +382,14 @@ export interface McplServerConfig {
    * accepts a request and never responds would otherwise freeze the awaiting
    * agent turn forever; with the timeout the pending request rejects with a
    * descriptive error, which the framework surfaces as a normal isError
-   * tool_result. Set 0 to disable. Default: 60000 (60 seconds).
+   * 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).
    */
   requestTimeoutMs?: number;
 

package/src/mcpl/visible-content.ts

@@ -31,6 +31,33 @@ export function isVisiblyEmptyContent(content: readonly unknown[] | null | undef
   return true;
 }
 
+/**
+ * What the converter (convertBlock, on every lane) shows for a text
+ * 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).
+ */
+export const NON_STRING_TEXT_PLACEHOLDER = "[Text not shown: the server's text block had no string text.]";
+
+/** A wire text block whose text isn't a string, which the converter shows as
+ *  NON_STRING_TEXT_PLACEHOLDER. */
+function isNonStringTextBlock(block: unknown): boolean {
+  if (!block || typeof block !== 'object') return false;
+  const b = block as { type?: unknown; text?: unknown };
+  return b.type === 'text' && typeof b.text !== 'string';
+}
+
+/**
+ * isVisiblyEmptyContent for content as a converter showed it, `wire` being
+ * the content as it arrived, block for block: a block shown as
+ * NON_STRING_TEXT_PLACEHOLDER counts as the nothing it held. So content that
+ * is only such blocks (or blank text) is still empty, and anything else is
+ * judged as the converted blocks show it, placeholders included.
+ */
+export function isVisiblyEmptyConversion(wire: readonly unknown[], converted: readonly unknown[]): boolean {
+  return isVisiblyEmptyContent(converted.filter((_, i) => !isNonStringTextBlock(wire[i])));
+}
+
 /** The server id and feature set the marker must carry. */
 export const SILENT_HEARTBEAT_SERVER_ID = 'heartbeat';
 export const SILENT_HEARTBEAT_FEATURE_SET = 'heartbeat';