@animalabs/agent-framework 0.29.0 → 0.31.0

package/src/mcpl/modern-connection.ts

@@ -66,8 +66,8 @@ import {
   type TransportSendOptions,
 } from '@modelcontextprotocol/client';
 
-import { StdioTransport, type McplTransport } from './transport.js';
-import { McplProtocolVersionError, McplRequestError, McplUnreapedLaunchError } from './server-connection.js';
+import { HeldStderr, STDERR_END_WAIT_MS, StdioTransport, type McplTransport, type TransportCloseInfo } from './transport.js';
+import { McplProtocolVersionError, McplRequestError, McplUnreapedLaunchError, stderrTailOf, withStderr } from './server-connection.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';
@@ -79,8 +79,6 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 const CONNECT_TIMEOUT_MS = 30_000;
 /** Inventory listing has its own bound: it is host work, not a resident's call. */
 const LIST_TIMEOUT_MS = 30_000;
-/** Startup stderr kept for the first listener. */
-const STDERR_BACKLOG_LINES = 200;
 
 /** A modern tool result as the framework consumes it. `structuredContent` is
  *  kept by presence: `false`, `0` and `null` are values, not absence. */
@@ -113,18 +111,12 @@ interface WireRecord {
   continued: boolean;
 }
 
-/**
- * A send that Connectome's own transport refused before writing anything (its
- * stdio line is closed): nothing of that request reached the server. `pipe`:
- * the child's stdin or stdout had failed, so this host can no longer write to
- * that server at all.
- */
 class NotWrittenError extends Error {
-  readonly pipe: boolean;
-  constructor(message: string, pipe = false) {
+  readonly stdioStopped: boolean;
+  constructor(message: string, stdioStopped = false) {
     super(message);
     this.name = 'NotWrittenError';
-    this.pipe = pipe;
+    this.stdioStopped = stdioStopped;
   }
 }
 
@@ -309,6 +301,9 @@ class SpawnerStdioTransport implements Transport {
   onerror?: (error: Error) => void;
   onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
   private line: McplTransport | null = null;
+  /** How the child ended, once its line has closed: the line's reason, and
+   *  the child's exit code or signal. */
+  closeInfo: TransportCloseInfo | undefined;
   /** The spawn start() awaits, so a close() made meanwhile closes its child. */
   private spawning: Promise<McplTransport> | null = null;
 
@@ -318,9 +313,6 @@ class SpawnerStdioTransport implements Transport {
   constructor(
     private readonly config: McplServerConfig,
     private readonly onStderr: (line: string) => void,
-    /** The child's pipe failed and it outlived SIGKILL too, so the line
-     *  stays open, owning it (the line's 'unreaped'): `reason` names the
-     *  pipe's error, and `failure` is the reap's. */
     private readonly onUnreaped: (reason: string, failure: Error) => void,
   ) {
     this.recorded = serverTextRedactor(config);
@@ -357,22 +349,31 @@ class SpawnerStdioTransport implements Transport {
     });
     line.on('stderr', (text: string) => this.onStderr(text));
     line.on('error', (error: Error) => this.onerror?.(error));
-    line.on('close', () => this.onclose?.());
-    line.on('unreaped', (failure: Error) => this.onUnreaped(`its stdio pipe failed with ${line.pipeFailure?.message ?? 'an error'}`, failure));
+    line.on('close', (info: TransportCloseInfo) => {
+      this.closeInfo = info;
+      this.onclose?.();
+    });
+    line.on('unreaped', (failure: Error) => this.onUnreaped(`this host stopped using the server's stdio (${line.stdioStopCause?.message ?? 'an error'})`, failure));
   }
 
-  /** The first error on the child's stdin or stdout, once there is one: the
-   *  line is ending the child then, and writes nothing more to it. */
-  get pipeFailure(): Error | undefined {
-    return this.line?.pipeFailure;
+  get stdioStopCause(): Error | undefined {
+    return this.line?.stdioStopCause;
+  }
+
+  /** The last of the child's stderr, redacted, once the stream has ended or
+   *  STDERR_END_WAIT_MS has passed, as the legacy handshake waits before it
+   *  refuses; '' when there's no child or it wrote nothing. */
+  async stderrTail(): Promise<string> {
+    const line = this.line;
+    if (!line) return '';
+    await line.stderrEnded(STDERR_END_WAIT_MS);
+    return line.stderrTailRedacted(serverTextRedactor(this.config)).trimEnd();
   }
 
   async send(message: JSONRPCMessage): Promise<void> {
     if (!this.line || this.line.closed) throw new NotWrittenError(`MCP server "${this.config.id}" stdio transport is closed`);
-    // Once the child's stdin or stdout has failed, the line is ending it and
-    // writes nothing more to it, so a message is refused here as not sent.
-    const failed = this.pipeFailure;
-    if (failed) throw new NotWrittenError(`MCP server "${this.config.id}" stdio pipe failed with ${failed.message}`, true);
+    const stopped = this.stdioStopCause;
+    if (stopped) throw new NotWrittenError(`MCP server "${this.config.id}": this host stopped using the server's stdio (${stopped.message})`, true);
     this.line.writeLine(JSON.stringify(message));
   }
 
@@ -460,10 +461,7 @@ export class ModernMcpConnection extends EventEmitter {
   /** A lost session's reap in flight: the reconnect follows it, and
    *  close() waits for it. */
   private losing: { session: Session; done: Promise<void> } | null = null;
-  /** Child stderr from before anyone listens (the caller attaches only once
-   *  connect() returns), delivered to the first listener. Bounded: the
-   *  newest lines are kept. */
-  private stderrBacklog: string[] = [];
+  private readonly heldStderr = new HeldStderr();
   private redactor?: ServerTextRedactor;
 
   /** The server's text with its configuration's credentials replaced, for
@@ -489,9 +487,8 @@ export class ModernMcpConnection extends EventEmitter {
       if (this.listenerCount('error') === 1) console.error(`[mcp] ${this.id}: ${redactServerText(error.message, this.config)}`);
     });
     this.on('newListener', (event: string | symbol) => {
-      if (event !== 'stderr' || this.stderrBacklog.length === 0) return;
-      const pending = this.stderrBacklog;
-      this.stderrBacklog = [];
+      if (event !== 'stderr' || this.heldStderr.empty) return;
+      const pending = this.heldStderr.take();
       // After the listener is added (newListener fires just before).
       queueMicrotask(() => { for (const line of pending) this.emit('stderr', { line }); });
     });
@@ -502,8 +499,7 @@ export class ModernMcpConnection extends EventEmitter {
       this.emit('stderr', { line });
       return;
     }
-    this.stderrBacklog.push(line);
-    if (this.stderrBacklog.length > STDERR_BACKLOG_LINES) this.stderrBacklog.shift();
+    this.heldStderr.hold(line);
   }
 
   /** The per-call deadline: `requestTimeoutMs`, validated positive. */
@@ -520,6 +516,14 @@ export class ModernMcpConnection extends EventEmitter {
     return this.reconnectEnabled && !this.closedByHost && this.unreaped.length === 0;
   }
 
+  /**
+   * Stop reconnecting, closing nothing, as the legacy engine's does.
+   * @internal For the framework's stop(); not a host API.
+   */
+  stopReconnecting(): void {
+    this.reconnectEnabled = false;
+  }
+
   /** Whether close() has been called: closed for good, or closing. A
    *  connection lost on its own is not closed in this sense. */
   get isClosed(): boolean {
@@ -610,12 +614,14 @@ export class ModernMcpConnection extends EventEmitter {
       // `cause`, can carry it whole (maskedError). The protocol refusal
       // above was built from redacted words.
       const masked = maskedError(error, this.recorded);
+      const stderrTail = stderrTailOf(error);
+      if (stderrTail !== undefined) Object.assign(masked, { stderrTail });
       // A launch that couldn't be reaped halts reconnecting, so no retry
       // will come: the first connect fails, as one without reconnect does.
       if (!this.reconnectEnabled || this.holdsUnreapedChild) throw masked;
-      console.error(`MCP server "${this.id}" initial connect failed, will retry:`, masked.message);
+      console.error(`MCP server "${this.id}" initial connect failed, will retry: ${masked.message}${withStderr(masked, this.recorded)}`);
       this.reconnectAttempts = 1;
-      this.emit('connect-failed', { error: (error as Error).message, attempt: 0 });
+      this.emit('connect-failed', { error: (error as Error).message, ...(stderrTail === undefined ? {} : { stderrTail }), attempt: 0 });
       this.scheduleReconnect();
     }
   }
@@ -656,11 +662,6 @@ export class ModernMcpConnection extends EventEmitter {
       ? new SpawnerStdioTransport(
         this.config,
         (line) => { if (this.isCurrent(generation)) this.deliverStderr(line); },
-        // A child whose pipe failed and that outlived SIGKILL: a loss whose
-        // launch is already known unreaped, so it's held as the loss is
-        // handled (handleLost). During a connect there is no session to lose
-        // yet: a connect whose pipe has failed fails, whether or not the SDK
-        // resolves it (establish), and its cleanup holds the launch.
         (reason, failure) => { if (this.isCurrent(generation)) this.handleLost(generation, reason, failure); },
       )
       : null;
@@ -697,7 +698,9 @@ export class ModernMcpConnection extends EventEmitter {
       // Marked before the session is adopted too: a close during the connect
       // makes it a failed connect (see establish).
       session.lost = true;
-      if (this.isCurrent(generation)) this.handleLost(generation, 'transport closed');
+      // Over stdio, how its child ended, as legacy's loss carries it.
+      const ended = session.stdio?.closeInfo;
+      if (this.isCurrent(generation)) this.handleLost(generation, ended?.reason ?? 'transport closed', undefined, ended);
     };
 
     // `done` settles only once this connect's own cleanup has finished, on
@@ -713,6 +716,13 @@ export class ModernMcpConnection extends EventEmitter {
     }
   }
 
+  /** `error` carrying the session's stderr tail as `stderrTail`, as a
+   *  legacy connect's failure does, when the child wrote any. */
+  private static async withStderrTail(session: Session, error: unknown): Promise<unknown> {
+    const tail = await session.stdio?.stderrTail();
+    return tail && error instanceof Error ? Object.assign(error, { stderrTail: tail }) : error;
+  }
+
   /** Connect one generation's client, and adopt it if it's still current. */
   private async establish(session: Session): Promise<void> {
     try {
@@ -720,7 +730,7 @@ export class ModernMcpConnection extends EventEmitter {
     } catch (error) {
       const failure = await ModernMcpConnection.closeSession(session);
       if (failure) this.holdUnreaped(session, failure);
-      throw this.versionVerdict(error) ?? error;
+      throw await ModernMcpConnection.withStderrTail(session, this.versionVerdict(error) ?? error);
     }
     if (!this.isCurrent(session.generation)) {
       // Superseded or closed while connecting: this generation never serves.
@@ -729,22 +739,22 @@ export class ModernMcpConnection extends EventEmitter {
       return;
     }
     // The transport closed while the client connected, such as a child that
-    // exited at the connect-time list-change subscribe, or the child's stdio
-    // pipe failed, such as that subscribe's write meeting EPIPE: the SDK
-    // reports the subscribe's failure only as an error, and resolves the
-    // connect anyway (R1-2). Adopted, the session would read as connected
-    // with nothing it can write to behind it, and from a child that outlived
-    // SIGKILL, whose 'unreaped' came while there was no session to lose, no
-    // later close would come to reconnect it. So the connect failed: its
-    // close reaps the child, and a child it can't reap is held. A failed
-    // pipe is named whether or not the child has exited by now.
-    const pipe = session.stdio?.pipeFailure;
-    if (session.lost || pipe) {
+    // exited at the connect-time list-change subscribe, or this host stopped
+    // using the child's stdio, such as after that subscribe's write met
+    // EPIPE: the SDK reports the subscribe's failure only as an error, and
+    // resolves the connect anyway (R1-2). Adopted, the session would read as
+    // connected with nothing it can write to behind it, and from a child that
+    // outlived SIGKILL, whose 'unreaped' came while there was no session to
+    // lose, no later close would come to reconnect it. So the connect failed:
+    // its close reaps the child, and a child it can't reap is held. The
+    // stop's cause is named whether or not the child has exited by now.
+    const stopped = session.stdio?.stdioStopCause;
+    if (session.lost || stopped) {
       const failure = await ModernMcpConnection.closeSession(session);
       if (failure) this.holdUnreaped(session, failure);
-      throw new Error(pipe
-        ? `MCP server "${this.id}" stdio pipe failed with ${pipe.message} while connecting`
-        : `MCP server "${this.id}" closed its connection while connecting`);
+      throw await ModernMcpConnection.withStderrTail(session, new Error(stopped
+        ? `MCP server "${this.id}": this host stopped using the server's stdio while connecting (${stopped.message})`
+        : `MCP server "${this.id}" closed its connection while connecting`));
     }
     this.session = session;
     this.protocolVersion = MODERN_MCP_PROTOCOL_VERSION;
@@ -847,10 +857,8 @@ export class ModernMcpConnection extends EventEmitter {
     }
   }
 
-  /** The transport went away (child exit, or a closed HTTP client).
-   *  `unreaped`: the child's pipe failed and it outlived SIGKILL, so its
-   *  launch is already known unreaped. */
-  private handleLost(generation: number, reason: string, unreaped?: Error): void {
+  /** The transport went away (child exit, or a closed HTTP client). */
+  private handleLost(generation: number, reason: string, unreaped?: Error, ended?: TransportCloseInfo): void {
     const session = this.session;
     if (session?.generation !== generation) return;
     this.session = null;
@@ -886,7 +894,7 @@ export class ModernMcpConnection extends EventEmitter {
     // skip neither 'close' nor the report.
     if (unreaped) this.holdUnreaped(session, unreaped, false);
     try {
-      this.emit('close', { reason });
+      this.emit('close', { reason, code: ended?.code ?? null, signal: ended?.signal ?? null, pipeFailed: ended?.pipeFailed === true });
     } finally {
       if (unreaped) this.reportUnreaped(unreaped);
     }
@@ -920,19 +928,26 @@ export class ModernMcpConnection extends EventEmitter {
     } catch (error) {
       if (this.closedByHost) return;
       this.reconnectAttempts = attempt + 1;
+      const stderrTail = stderrTailOf(error);
+      const failed = (message: string, permanent?: true) => this.emit('reconnect-failed', {
+        error: message,
+        ...(stderrTail === undefined ? {} : { stderrTail }),
+        attempt,
+        ...(permanent ? { permanent } : {}),
+      });
       const halted = this.unreapedFailure();
       if (halted) {
-        this.emit('reconnect-failed', { error: `${(error as Error).message}; ${halted}`, attempt, permanent: true });
+        failed(`${(error as Error).message}; ${halted}`, true);
         return;
       }
       // No common revision: every further attempt would hear the same
       // answer. Stop; only the configuration can fix it.
       if (error instanceof McplProtocolVersionError) {
         this.reconnectEnabled = false;
-        this.emit('reconnect-failed', { error: error.message, attempt, permanent: true });
+        failed(error.message, true);
         return;
       }
-      this.emit('reconnect-failed', { error: (error as Error).message, attempt });
+      failed((error as Error).message);
       this.scheduleReconnect();
     }
   }
@@ -1168,9 +1183,9 @@ export class ModernMcpConnection extends EventEmitter {
       : `${said}, so whether the request took effect is unknown. Check its effect before trying again.`;
     if (!record.handedOff) {
       log(`${what} not sent: ${logDetail(message)}`);
-      const pipe = error instanceof NotWrittenError && error.pipe;
+      const stdioStopped = error instanceof NotWrittenError && error.stdioStopped;
       return new McplRequestError(
-        pipe
+        stdioStopped
           ? `The request wasn't sent: this host can no longer write to ${server}, so nothing ran. ${this.retryText()}`
           // Before the wire, the cause can pass (the stdio line closing as
           // the connection is lost) or stay (a tool's outputSchema the SDK

package/src/mcpl/protocol-family.ts

@@ -695,7 +695,7 @@ export function serverConfigProblems(config: McplServerConfig): string[] {
   } catch (error) {
     return [(error as Error).message];
   }
-  const problems: string[] = [];
+  const problems: string[] = credentialRequiredProblems(config);
   if (binding.transport === 'http') {
     // fetch refuses a url with userinfo, and its error quotes the whole url,
     // password included, into the connect failure's log line, trace and
@@ -760,6 +760,38 @@ export function serverConfigProblems(config: McplServerConfig): string[] {
   return problems;
 }
 
+/** Strict-only admission, also applied to a captured policy at dial time.
+ * Nothing supplied in an invalid setting is quoted. Runtime providers are
+ * host-attached, so their presence is checked by the dial, not here. */
+function credentialRequiredProblems(config: McplServerConfig): string[] {
+  const flag: unknown = config.credentialRequired;
+  if (flag === undefined || flag === null || flag === false) return [];
+  const problem = (why: string) => [`MCP server "${config.id}": credentialRequired ${why}`];
+  if (flag !== true) return problem('must be a boolean');
+  let binding: ServerBinding;
+  try { binding = resolveServerBinding(config); }
+  catch { return problem('requires a valid WebSocket binding'); }
+  if (binding.transport !== 'websocket' || binding.family !== 'legacy') {
+    return problem('applies only to a legacy ws(s):// server, not HTTP, stdio or modern servers');
+  }
+  if (config.token !== undefined && config.token !== null) return problem('forbids a static token, including an empty token');
+  if (config.tokenTransport !== 'header') return problem("requires tokenTransport 'header'");
+  const url = new URL(config.url!);
+  if (url.hash) return problem('forbids a URL fragment');
+  if (url.protocol === 'ws:') {
+    if (!isLoopbackHost(url.hostname)) return problem('requires TLS outside loopback');
+    const name = url.hostname.toLowerCase();
+    const host = name.replace(/\.$/, '');
+    if (host.endsWith('.localhost') || name === 'localhost.') {
+      return problem('requires TLS for a localhost name other than localhost itself, which a resolver can send off this host; use localhost or a loopback address');
+    }
+    if (host === '0.0.0.0' || host === '[::]') {
+      return problem('requires TLS for the unspecified address, which is not a loopback address; use 127.0.0.1 or [::1]');
+    }
+  }
+  return [];
+}
+
 /**
  * What's wrong with a WebSocket server's `tokenTransport`, as a message, or
  * undefined: a value that is neither mode, or `'header'` with a url that
@@ -770,18 +802,19 @@ export function serverConfigProblems(config: McplServerConfig): string[] {
  * The refusal names the value's kind, never the value, which could be a
  * credential pasted into the wrong field, and quotes nothing of the url.
  */
-export function tokenTransportProblem(config: Pick<McplServerConfig, 'id' | 'tokenTransport'>, url: URL): string | undefined {
+export function tokenTransportProblem(config: Pick<McplServerConfig, 'id' | 'tokenTransport' | 'credentialRequired'>, url: URL): string | undefined {
   // A configuration read from JSON can hold anything here.
   const mode: unknown = config.tokenTransport;
   if (mode === undefined || mode === null || mode === 'query') return undefined;
   if (mode !== 'header') {
     return `MCP server "${config.id}": tokenTransport must be 'query' or 'header', not ${typeof mode === 'string' ? 'another string' : kindOf(mode)}`;
   }
+  const strict = config.credentialRequired === true;
   if (url.searchParams.has('token')) {
-    return `MCP server "${config.id}": with tokenTransport 'header' the url must not carry a "token" query parameter, which would still put a credential in it; give it as "token" or "accessProvider"`;
+    return `MCP server "${config.id}": with tokenTransport 'header' the url must not carry a "token" query parameter, which would still put a credential in it; give it as ${strict ? '"accessProvider"' : '"token" or "accessProvider"'}`;
   }
   if (url.username || url.password) {
-    return `MCP server "${config.id}": with tokenTransport 'header' the url must not carry userinfo (user:password@), since the Bearer header replaces the userinfo's Basic credential whenever it carries a credential; leave out "tokenTransport" to send the userinfo as before, or give the credential as "token" or "accessProvider"`;
+    return `MCP server "${config.id}": with tokenTransport 'header' the url must not carry userinfo (user:password@), since the Bearer header replaces the userinfo's Basic credential whenever it carries a credential; ${strict ? 'give the credential as "accessProvider"' : 'leave out "tokenTransport" to send the userinfo as before, or give the credential as "token" or "accessProvider"'}`;
   }
   return undefined;
 }

package/src/mcpl/push-coalescer.ts

@@ -295,18 +295,13 @@ export interface CoalescingReceiptRecord {
 
 export interface CoalescerHost<E> {
   /** True iff the placement still exists and, as far as the host can tell,
-   *  no model request has included it. The host can't always tell: a
-   *  message injected into a stream that didn't say whether it carries
-   *  injections, as no membrane 0.5.x stream does, counts as unread though
-   *  a request may have included it. */
+   *  no model request has included it. */
   isUnread(placement: CoalescingPlacement): boolean;
   /** True iff nothing may have shown the placement to the agent: it is still
    *  in the deferred queue and known not to be stored already, or it is
    *  stored where no committing compile has begun to assemble it and no tool
    *  boundary has injected past it. Unlike
-   *  isUnread, a compile counts from its start, and a boundary counts
-   *  whether or not its stream says it carries injected messages: a doubt
-   *  counts as shown. */
+   *  isUnread, a compile counts from its start: a doubt counts as shown. */
   isUnshown(placement: CoalescingPlacement): boolean;
   /** False when the unread occurrence could not be removed (it may still be read). */
   remove(placement: CoalescingPlacement): boolean;
@@ -1000,6 +995,25 @@ export class PushCoalescer<E = unknown> {
     return result;
   }
 
+  /**
+   * Render and materialize one subject's pending batch for `agentName` now,
+   * outside a turn's assembly: a batch whose wake a hold keeps back, stored
+   * as it renders (held, as a plain push under the hold is), so whoever reads
+   * held traffic sees it and the turn after the hold doesn't take it again.
+   * A batch that opened while another render ran is rendered once that
+   * render settles. Resolves whether it materialized.
+   */
+  async materializeNow(agentName: string, subject: string): Promise<boolean> {
+    for (;;) {
+      if (this.suspended) return false;
+      const started = await this.locked(() => this.freeze(subject, agentName));
+      if (!started || started === 'declined') return false;
+      await started.done;
+      this.persist();
+      if (!started.joined) return started.rendering.materialized === true;
+    }
+  }
+
   /**
    * Under the lock: decide whether `subject`'s batch renders for `agentName`,
    * freeze it, make the render-start durable, re-check authority, and start

package/src/mcpl/references.ts

@@ -50,7 +50,6 @@ export interface ReferenceTestimony {
   name?: string;
   disposition?: ReferenceDisposition;
   rejectedFields: string[];
-  truncatedFields: string[];
   /** Set when the testimony is an MCP resource_link's, which claims no
    *  digest, expiry or disposition. A link is registered but never fetched
    *  on the side, and its testimony never replaces a record's (register). */
@@ -182,8 +181,8 @@ function parseReferenceFields(block: Record<string, unknown>): BlockClassificati
   if (block.uri.length > REFERENCE_LIMITS.uri) {
     return { kind: 'invalid', shown: REFERENCE_LINK_TOO_LONG_TEXT };
   }
-  const out = { rejected: [] as string[], truncated: [] as string[] };
-  const t: ReferenceTestimony = { uri: block.uri, rejectedFields: out.rejected, truncatedFields: out.truncated };
+  const out = { rejected: [] as string[] };
+  const t: ReferenceTestimony = { uri: block.uri, rejectedFields: out.rejected };
   t.mimeType = takeString(block.mimeType, 'mimeType', out);
   t.name = takeString(block.name, 'name', out);
   t.expiresAt = takeString(block.expiresAt, 'expiresAt', out);
@@ -835,7 +834,7 @@ export class ReferenceRegistry {
    *  entry for the id, if any, is in force again; with none, a stub reads the
    *  id's references as an unknown server's. After a removal, that framework's
    *  fetch refuses them too. A stopped framework keeps its configs, so its
-   *  fetcher, called before it starts again, can still dial them. */
+   *  fetcher can still dial them. */
   forgetServerAddress(serverId: string, owner: object): void {
     const entries = (this.addresses.get(serverId) ?? []).filter((e) => e.owner !== owner);
     if (entries.length > 0) this.addresses.set(serverId, entries);

package/src/mcpl/server-connection.ts

@@ -79,6 +79,9 @@ export interface McplConnectionCloseInfo {
   /** True when `reason` is the peer's own text, a WebSocket server's close
    *  reason, rather than the transport's or the host's words. */
   reasonFromPeer?: boolean;
+  /** True when the stdio transport ended the child itself, after a pipe
+   *  error or a line on its stdout longer than the bound. */
+  pipeFailed?: boolean;
   /** True when the host closed the link (`close()` / `reconnectAfterFailure()`),
    *  false when the transport dropped unexpectedly. */
   byHost: boolean;
@@ -454,6 +457,8 @@ export class McplServerConnection extends EventEmitter {
    *  the epoch their opening went to, never across a reconnect. */
   transportEpoch = 0;
 
+  private transportEnded = new AbortController();
+
   /**
    * RFC-014: the server's `toolHints`, `toolsets` and `surface` members as it
    * advertised them at the last handshake (toolsetDeclarationsOf), or null.
@@ -531,6 +536,8 @@ export class McplServerConnection extends EventEmitter {
     this.grant = CapabilityGrant.empty();
     this.policyEstablished = false;
     this.transportEpoch++;
+    this.transportEnded.abort();
+    this.transportEnded = new AbortController();
     // What the server sent that is still held came on the transport that is
     // now gone. What it said about its own process is dropped: its requests
     // wait on answers that can no longer reach whoever asked (an inference
@@ -726,6 +733,20 @@ export class McplServerConnection extends EventEmitter {
     return this.reconnectEnabled;
   }
 
+  /**
+   * Stop reconnecting, closing nothing: a retry already scheduled starts
+   * nothing when its timer fires, none is scheduled after, and an attempt
+   * under way is aborted, as close() aborts it, so one still waiting on its
+   * access provider never dials and a child it spawned is reaped. The host's
+   * stop() does this first, so nothing is launched or dialed while it shuts
+   * down; close() clears the timer.
+   * @internal For the framework's stop(); not a host API.
+   */
+  stopReconnecting(): void {
+    this.reconnectEnabled = false;
+    this.reconnecting?.abort.abort();
+  }
+
   /** Whether a child this connection launched couldn't be confirmed exited.
    *  While it's true the connection owns that child, so whatever registered
    *  it keeps its id held; close() retries the reap. */
@@ -1417,7 +1438,7 @@ export class McplServerConnection extends EventEmitter {
         transport.writeLine(JSON.stringify(initRequest));
       });
 
-      // The transport has found the child's stdin or stdout failed before the
+      // The transport has stopped using the child's stdio before the
       // handshake could hand it on, such as when this host's answer to a ping
       // the server sent met EPIPE. Nothing more is written to the child then,
       // so the connection couldn't serve. It's read here, once the answer has
@@ -1430,8 +1451,8 @@ export class McplServerConnection extends EventEmitter {
       // the launch if it can't reap the child. A failure of the write below
       // is reported only once the caller has wired the transport, so it
       // reaches the connection as a loss, like any later one.
-      const pipeFailure = transport.pipeFailure;
-      if (pipeFailure) throw failed(`MCPL server "${config.id}" stdio pipe failed with ${pipeFailure.message} during the handshake`);
+      const stopCause = transport.stdioStopCause;
+      if (stopCause) throw failed(`MCPL server "${config.id}": this host stopped using the server's stdio during the handshake (${stopCause.message})`);
 
       // Send `initialized` notification (no id)
       transport.writeLine(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }));
@@ -2163,12 +2184,8 @@ export class McplServerConnection extends EventEmitter {
         'not-sent',
       ));
     }
-    // Once the child's stdin or stdout has failed, the transport is ending
-    // it and writes nothing more to it, so a request is refused here as not
-    // sent rather than left to wait out its timeout. The method and the
-    // pipe's error are the operator's, so they go to the log.
-    const pipeFailure = this.transport?.pipeFailure;
-    if (pipeFailure) {
+    const stopCause = this.transport?.stdioStopCause;
+    if (stopCause) {
       return McplServerConnection.refused(
         new McplRequestError(
           `The request wasn't sent: this host can no longer write to the "${this.id}" server, so nothing ran. ` +
@@ -2177,7 +2194,7 @@ export class McplServerConnection extends EventEmitter {
               : "This host won't reconnect to it on its own. If you need it, ask whoever runs this host."),
           'not-sent',
         ),
-        `MCPL server "${this.id}": ${method} not sent, since its stdio pipe failed: ${logDetail(pipeFailure.message)}`,
+        `MCPL server "${this.id}": ${method} not sent, since this host stopped using the server's stdio (${logDetail(stopCause.message)})`,
       );
     }
 
@@ -2492,6 +2509,7 @@ export class McplServerConnection extends EventEmitter {
   private responderFor(id: string | number, epoch: number) {
     return {
       id,
+      signal: epoch === this.transportEpoch ? this.transportEnded.signal : AbortSignal.abort(),
       respond: (result: unknown) => this.sendResponse(id, result, epoch),
       respondError: (code: number, message: string, data?: unknown) =>
         this.sendErrorResponse(id, code, message, data, epoch),
@@ -2787,6 +2805,7 @@ export class McplServerConnection extends EventEmitter {
           signal: info.signal ?? null,
           reason: info.reason ?? (byHost ? 'closed by host' : undefined),
           ...(info.reasonFromPeer ? { reasonFromPeer: true } : {}),
+          ...(info.pipeFailed ? { pipeFailed: true } : {}),
           byHost,
         };
         this.emit('close', closeInfo.code, closeInfo.signal, closeInfo);
@@ -2798,20 +2817,10 @@ export class McplServerConnection extends EventEmitter {
       }
     };
     transport.on('close', lost);
-    // A stdio child whose stdin or stdout failed, and that outlived SIGKILL
-    // too: the transport stays open, owning the child. The connection holds
-    // it as a launch it can't reap, as a reconnect does, which halts
-    // reconnecting, and is lost as on a close, with the permanent failure
-    // that raises the alert and takes its tools off the list. Its id stays
-    // held until close() confirms the exit. A close the host has begun
-    // reports the failure itself. During a handshake nothing listens yet: a
-    // handshake whose pipe has failed fails, when its answer comes (it's
-    // refused then), when the child's exit closes the transport, or at its
-    // timeout, and its own cleanup holds the launch.
     transport.on('unreaped', (failure: Error) => {
       if (this.closed || this.transport !== transport) return;
       this.holdUnreaped(transport, failure);
-      lost({ reason: `its stdio pipe failed with ${transport.pipeFailure?.message ?? 'an error'}, and its child outlived SIGKILL` });
+      lost({ reason: `this host stopped using the server's stdio (${transport.stdioStopCause?.message ?? 'an error'}), and the server's process outlived SIGKILL` });
       this.emit('reconnect-failed', { error: this.unreapedFailure(), attempt: Math.max(1, this.reconnectAttempts), permanent: true });
     });
   }

package/src/mcpl/tool-signature.ts

@@ -94,22 +94,25 @@ const schemaOf = (tool: HintedTool): JsonSchema => (isObj(tool.inputSchema) ? to
 
 /** `play(point: string)`, `move(forward?: int -10..10 =0, turn?: int)` */
 export function signature(tool: HintedTool): string {
-  const s = schemaOf(tool);
-  const props = (isObj(s.properties) ? s.properties : {}) as Record<string, JsonSchema>;
-  const req = new Set(Array.isArray(s.required) ? (s.required as string[]) : []);
-  const params = Object.entries(props).map(([k, v]) => {
-    const def = isObj(v) && v.default !== undefined ? ` =${literal(v.default)}` : '';
-    return `${nameToTypeBack(k)}${req.has(k) ? '' : '?'}: ${typeSig(v, 1)}${def}`;
-  });
-  return `${nameToTypeBack(String(tool.name))}(${params.join(', ')})`;
+  return `${nameToTypeBack(String(tool.name))}(${paramsOf(schemaOf(tool))})`;
 }
 
 /** An options schema as `{size?: 9|13|19 =9, …}` (a toolset's options). */
 export function objectSignature(schema: unknown): string {
-  const inner = signature({ name: '', inputSchema: schema }).slice(1, -1);
+  const inner = paramsOf(isObj(schema) ? schema : {});
   return inner ? `{${inner}}` : '{}';
 }
 
+/** A schema's properties as `name?: type =default`, joined with commas. */
+function paramsOf(s: JsonSchema): string {
+  const props = (isObj(s.properties) ? s.properties : {}) as Record<string, JsonSchema>;
+  const req = new Set(Array.isArray(s.required) ? (s.required as string[]) : []);
+  return Object.entries(props).map(([k, v]) => {
+    const def = isObj(v) && v.default !== undefined ? ` =${literal(v.default)}` : '';
+    return `${nameToTypeBack(k)}${req.has(k) ? '' : '?'}: ${typeSig(v, 1)}${def}`;
+  }).join(', ');
+}
+
 /** First sentence of a description, bounded. */
 export function firstSentence(text: unknown, max = 140): string {
   const t = (typeof text === 'string' ? text : '').trim().replace(/\s+/g, ' ');
@@ -153,11 +156,15 @@ export function renderToolLines(tools: HintedTool[], shown: Shown, opts: { descr
     const d = toolDigest(t);
     const describe = opts.describeAll || !shown.has(d);
     shown.add(d);
-    const sentence = describe ? firstSentence(t.description) : '';
-    return `${indent}${signature(t)}${sentence ? ` — ${suppliedValue(sentence)}` : ''}`;
+    return toolLine(t, describe, indent);
   });
 }
 
+export function toolLine(tool: HintedTool, describe = true, indent = '  '): string {
+  const sentence = describe ? firstSentence(tool.description) : '';
+  return `${indent}${signature(tool)}${sentence ? ` — ${suppliedValue(sentence)}` : ''}`;
+}
+
 /** A server's value as JSON, or a note where it's nested too deeply, or too long, to show. */
 export function jsonText(value: unknown, space?: number): string {
   if (!nestsWithin(value)) return '(nested too deeply to show)';