@animalabs/agent-framework 0.23.1 → 0.24.0

package/src/mcpl/modern-connection.ts

@@ -68,10 +68,10 @@ import {
 
 import { StdioTransport, type McplTransport } from './transport.js';
 import { McplProtocolVersionError, McplRequestError, McplUnreapedLaunchError } from './server-connection.js';
-import { LEGACY_MCP_PROTOCOL_VERSION, MAX_TIMER_MS, MODERN_MCP_PROTOCOL_VERSION, checkServerConfig, describeCredentialError, noteDialSent, redactServerText, serverTextRedactor } from './protocol-family.js';
+import { LEGACY_MCP_PROTOCOL_VERSION, MAX_TIMER_MS, MODERN_MCP_PROTOCOL_VERSION, checkServerConfig, describeCredentialError, maskedError, noteDialSent, redactServerText, redactedData, serverTextRedactor, type ServerTextRedactor } from './protocol-family.js';
 import type { McplServerConfig, McpToolDefinition } from './types.js';
 import { boundedForLog } from './errors.js';
-import { logDetail, logValue, logValueRedacted } from './log-value.js';
+import { logDetail, logValue, logValueRedacted, loggedCode } from './log-value.js';
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 /** Bound on establishing the connection (`server/discover`), like the legacy
@@ -132,6 +132,12 @@ class NotWrittenError extends Error {
  *  transport inside the caller's async chain, so the scope reaches `send`. */
 const wireScope = new AsyncLocalStorage<WireRecord>();
 
+/** A send in flight, its transport, and what that transport reported
+ *  meanwhile, held until the send settles (ObservedTransport.send). A
+ *  scope that names no transport, a notification's or a settled send's,
+ *  holds nothing. */
+const sendScope = new AsyncLocalStorage<{ wire: ObservedTransport | null; held: Error[] }>();
+
 /**
  * The boundary between the SDK and the actual transport. It records, for the
  * logical request in scope, each request of the observed method that it
@@ -172,15 +178,35 @@ class ObservedTransport implements Transport {
       if (record) wireScope.run(record, () => this.onmessage?.(message, extra));
       else this.onmessage?.(message, extra);
     };
-    this.inner.onerror = (error) => this.onerror?.(error);
+    // An error this transport reports while one of its sends is in flight
+    // waits for that send to settle: the SDK's HTTP send reports a failure
+    // here and then throws it, and whoever sent it reports what it throws
+    // (#556). Anything else is reported at once, another transport's report
+    // made in a send's async context too.
+    this.inner.onerror = (error) => {
+      const sending = sendScope.getStore();
+      if (sending?.wire === this) sending.held.push(error);
+      else this.onerror?.(error);
+    };
     this.inner.onclose = () => this.onclose?.();
     await this.inner.start();
   }
 
   async send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void> {
+    if ('method' in message && !('id' in message)) {
+      // A notification's sender can swallow what its send throws (the SDK's
+      // listen teardown does), so what its transport reports is reported at
+      // once, whatever send it was made in.
+      await sendScope.run({ wire: null, held: [] }, () => this.inner.send(message, options));
+      return;
+    }
     const record = wireScope.getStore();
     let undo: (() => void) | undefined;
     if (record && 'method' in message && 'id' in message && message.method === record.method) {
+      // Every transport writes a message as JSON, so one JSON can't write (a
+      // BigInt, a cycle) never leaves this host: it's refused here, before
+      // it's marked handed off (#556).
+      JSON.stringify(message);
       const prior = { handedOff: record.handedOff, currentId: record.currentId, answer: record.answer, error: record.error };
       // Handed off from here on: past this point nothing proves it unsent,
       // unless the transport says it wrote nothing.
@@ -194,14 +220,29 @@ class ObservedTransport implements Transport {
         Object.assign(record, prior);
       };
     }
+    // A request's or a response's sender reports what its send throws: a
+    // call through its outcome, the connect through its failure, the SDK
+    // through its own report. So what the transport reports meanwhile is held
+    // here, and the failure the send threw isn't reported a second time (#556).
+    const sending: { wire: ObservedTransport | null; held: Error[] } = { wire: this, held: [] };
+    let thrown: unknown;
     try {
-      await this.inner.send(message, options);
+      await sendScope.run(sending, () => this.inner.send(message, options));
     } catch (error) {
+      thrown = error;
       // Refused before any write: this leg never reached the server, so the
       // record is as it was before it. Any other throw (an HTTP send can fail
       // after part of the request went out) leaves it handed off.
       if (error instanceof NotWrittenError) undo?.();
       throw error;
+    } finally {
+      // Settled: what was held goes on, but for the failure the send threw,
+      // and the scope lets go of this transport, which work the send started
+      // still carries.
+      const { held } = sending;
+      sending.wire = null;
+      sending.held = [];
+      for (const error of held) if (error !== thrown) this.onerror?.(error);
     }
   }
 
@@ -278,8 +319,8 @@ class SpawnerStdioTransport implements Transport {
     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. */
-    private readonly onUnreaped: (reason: string) => void,
+     *  pipe's error, and `failure` is the reap's. */
+    private readonly onUnreaped: (reason: string, failure: Error) => void,
   ) {
     this.recorded = serverTextRedactor(config);
   }
@@ -313,14 +354,20 @@ 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', () => this.onUnreaped(`its stdio pipe failed with ${line.pipeFailure?.message ?? 'an error'}`));
+    line.on('unreaped', (failure: Error) => this.onUnreaped(`its stdio pipe failed with ${line.pipeFailure?.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;
   }
 
   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.line.pipeFailure;
+    const failed = this.pipeFailure;
     if (failed) throw new NotWrittenError(`MCP server "${this.config.id}" stdio pipe failed with ${failed.message}`, true);
     this.line.writeLine(JSON.stringify(message));
   }
@@ -374,6 +421,8 @@ interface Session {
   readonly generation: number;
   readonly client: Client;
   readonly wire: ObservedTransport;
+  /** Its stdio transport, under `wire`; null over HTTP. */
+  readonly stdio: SpawnerStdioTransport | null;
   /** Its transport has closed, whether or not the session was adopted yet. */
   lost: boolean;
 }
@@ -411,6 +460,13 @@ export class ModernMcpConnection extends EventEmitter {
    *  connect() returns), delivered to the first listener. Bounded: the
    *  newest lines are kept. */
   private stderrBacklog: string[] = [];
+  private redactor?: ServerTextRedactor;
+
+  /** The server's text with its configuration's credentials replaced, for
+   *  the errors this connection hands its caller and its records. */
+  private get recorded(): ServerTextRedactor {
+    return (this.redactor ??= serverTextRedactor(this.config));
+  }
 
   private constructor(private readonly config: McplServerConfig) {
     super();
@@ -470,7 +526,8 @@ export class ModernMcpConnection extends EventEmitter {
    *  While it's true the connection owns that child, so whatever registered
    *  it keeps its id held; close() retries the reap. It's settled only once
    *  a reap has finished: while a lost session's reap or a close runs, it
-   *  reads false, so read it once lossReaped() or close() has settled. */
+   *  may not read true yet, so read it once lossReaped() or close() has
+   *  settled. */
   get holdsUnreapedChild(): boolean {
     return this.unreaped.length > 0;
   }
@@ -483,10 +540,15 @@ export class ModernMcpConnection extends EventEmitter {
   }
 
   /** A failed generation's cleanup couldn't reap its child: keep owning it,
-   *  and halt reconnecting until close() settles it. */
-  private holdUnreaped(session: Session, failure: Error): void {
+   *  and halt reconnecting until close() settles it. It's reported as an
+   *  'error' at once, unless the caller reports it later itself. */
+  private holdUnreaped(session: Session, failure: Error, report = true): void {
     if (this.unreaped.some((held) => held.session === session)) return;
     this.unreaped.push({ session, failure });
+    if (report) this.reportUnreaped(failure);
+  }
+
+  private reportUnreaped(failure: Error): void {
     this.emit('error', new Error(
       `MCP server "${this.id}": ${failure.message}. Not starting another launch while it may still be running; close the connection to retry the reap.`,
     ));
@@ -538,10 +600,16 @@ export class ModernMcpConnection extends EventEmitter {
         this.reconnectEnabled = false;
         throw error;
       }
+      // Any other failure is the SDK's or the transport's: it goes on as its
+      // words alone, redacted, since its message can quote the url and its
+      // other properties, such as Bun's fetch error's `path` or a wrapper's
+      // `cause`, can carry it whole (maskedError). The protocol refusal
+      // above was built from redacted words.
+      const masked = maskedError(error, this.recorded);
       // 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 error;
-      console.error(`MCP server "${this.id}" initial connect failed, will retry:`, redactServerText((error as Error).message, this.config));
+      if (!this.reconnectEnabled || this.holdsUnreapedChild) throw masked;
+      console.error(`MCP server "${this.id}" initial connect failed, will retry:`, masked.message);
       this.reconnectAttempts = 1;
       this.emit('connect-failed', { error: (error as Error).message, attempt: 0 });
       this.scheduleReconnect();
@@ -580,17 +648,19 @@ export class ModernMcpConnection extends EventEmitter {
     // reopen backs off from the base interval, not from the previous
     // generation's failures.
     this.relistenAttempts = 0;
-    const inner: Transport = this.transportKind === 'stdio'
+    const stdio = this.transportKind === 'stdio'
       ? new SpawnerStdioTransport(
         this.config,
         (line) => { if (this.isCurrent(generation)) this.deliverStderr(line); },
-        // A child whose pipe failed and that outlived SIGKILL: a loss, whose
-        // reap finds the child still running and holds the launch, as for any
-        // launch it can't reap. During a connect there is no session to lose
-        // yet: the connect's own cleanup holds it, once the connect fails.
-        (reason) => { if (this.isCurrent(generation)) this.handleLost(generation, reason); },
+        // 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); },
       )
-      : new StreamableHTTPClientTransport(new URL(this.config.url!), { authProvider: bearerAuth(this.config) });
+      : null;
+    const inner: Transport = stdio ?? new StreamableHTTPClientTransport(new URL(this.config.url!), { authProvider: bearerAuth(this.config) });
     const wire = new ObservedTransport(inner);
 
     const client = new Client(
@@ -609,7 +679,7 @@ export class ModernMcpConnection extends EventEmitter {
         },
       },
     );
-    const session: Session = { generation, client, wire, lost: false };
+    const session: Session = { generation, client, wire, stdio, lost: false };
     client.onerror = (error: Error) => {
       // The SDK reports late responses to deadline-abandoned calls here
       // ("unknown message ID"), and a list-change subscription it could not
@@ -654,16 +724,23 @@ export class ModernMcpConnection extends EventEmitter {
       if (failure) this.holdUnreaped(session, failure);
       return;
     }
-    if (session.lost) {
-      // The transport closed while the client connected, such as a child
-      // that exited at the connect-time list-change subscribe: the SDK
-      // reports that subscribe's failure only as an error, and resolves the
-      // connect anyway (R1-2). Adopted, the session would read as connected
-      // with nothing behind it, and no later close would come to reconnect
-      // it. So the connect failed.
+    // 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) {
       const failure = await ModernMcpConnection.closeSession(session);
       if (failure) this.holdUnreaped(session, failure);
-      throw new Error(`MCP server "${this.id}" closed its connection while connecting`);
+      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`);
     }
     this.session = session;
     this.protocolVersion = MODERN_MCP_PROTOCOL_VERSION;
@@ -679,7 +756,11 @@ export class ModernMcpConnection extends EventEmitter {
    */
   private versionVerdict(error: unknown): McplProtocolVersionError | null {
     if (!(error instanceof UnsupportedProtocolVersionError)) return null;
-    const data = (error as { data?: unknown }).data as { supported?: unknown } | undefined;
+    // The server's words and data, redacted before they're bounded or kept:
+    // the error goes to the host. One build for all of them, so a
+    // configuration that can't be read is read once.
+    const redact = this.recorded.now();
+    const data = redactedData((error as { data?: unknown }).data, redact) as { supported?: unknown } | undefined;
     const supported = Array.isArray(data?.supported) && data.supported.every((v) => typeof v === 'string')
       ? (data.supported as string[])
       : null;
@@ -693,13 +774,13 @@ export class ModernMcpConnection extends EventEmitter {
         : ` It speaks only legacy MCP, which this client reaches over stdio or WebSocket (ws://, wss://), not http(s).`;
     return new McplProtocolVersionError(
       `MCP server "${this.id}" does not support MCP ${MODERN_MCP_PROTOCOL_VERSION}` +
-        (supported ? ` (it supports: ${supported.join(', ') || 'none listed'}).` : ` (${error.message}).`) +
+        (supported ? ` (it supports: ${boundedForLog(supported.join(', ')) || 'none listed'}).` : ` (${boundedForLog(redact(error.message))}).`) +
         legacyHint,
       'rejected',
       null,
       supported,
       (error as { code?: unknown }).code === undefined ? undefined : Number((error as { code?: unknown }).code),
-      (error as { data?: unknown }).data,
+      data,
       MODERN_MCP_PROTOCOL_VERSION,
     );
   }
@@ -762,8 +843,10 @@ export class ModernMcpConnection extends EventEmitter {
     }
   }
 
-  /** The transport went away (child exit, or a closed HTTP client). */
-  private handleLost(generation: number, reason: string): void {
+  /** 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 {
     const session = this.session;
     if (session?.generation !== generation) return;
     this.session = null;
@@ -775,18 +858,34 @@ export class ModernMcpConnection extends EventEmitter {
     // reconnect's does, and is a permanent failure, as that one is: no
     // later attempt will come. The reap starts, and is recorded, before
     // 'close' is emitted, so a listener that throws can't skip it.
+    const permanent = () => this.emit('reconnect-failed', { error: `${reason}; ${this.unreapedFailure()}`, attempt: Math.max(1, this.reconnectAttempts), permanent: true });
     const done = ModernMcpConnection.closeSession(session).then((failure) => {
       if (this.losing?.session === session) this.losing = null;
+      // A close() the host made meanwhile reports the failure itself.
+      if (unreaped) {
+        // Held as the loss was handled, whatever the reap found now.
+        if (!this.closedByHost) permanent();
+        return;
+      }
       if (failure) {
         this.holdUnreaped(session, failure);
-        // A close() the host made meanwhile reports the failure itself.
-        if (!this.closedByHost) {
-          this.emit('reconnect-failed', { error: `${reason}; ${this.unreapedFailure()}`, attempt: Math.max(1, this.reconnectAttempts), permanent: true });
-        }
+        if (!this.closedByHost) permanent();
       } else if (this.willReconnect) this.scheduleReconnect();
     });
     this.losing = { session, done };
-    this.emit('close', { reason });
+    // A launch already known unreaped is held now, before 'close', so the
+    // calls the reap's close ends, which classify their failure only once
+    // this returns, and any made meanwhile, read that this host won't
+    // reconnect, as the legacy engine has it (#540's review, R1-1). It's
+    // reported after 'close', which is where the other route reports a hold
+    // too, whatever the 'close' listeners do, so a listener that throws can
+    // skip neither 'close' nor the report.
+    if (unreaped) this.holdUnreaped(session, unreaped, false);
+    try {
+      this.emit('close', { reason });
+    } finally {
+      if (unreaped) this.reportUnreaped(unreaped);
+    }
   }
 
   /** The legacy engine's backoff: doubling from the base interval, capped,
@@ -1013,9 +1112,9 @@ export class ModernMcpConnection extends EventEmitter {
    * The rules apply in this order. The call's answer is the server's final
    * one: an error or a `complete` result.
    * - nothing handed to the transport: `not-sent`, whatever was raised (a
-   *   pre-dispatch validation, a signal already aborted, no transport, a send
-   *   Connectome's stdio line refused before writing, an HTTP refusal before
-   *   any request went out);
+   *   pre-dispatch validation, a signal already aborted, no transport, a
+   *   message JSON can't write, a send Connectome's stdio line refused
+   *   before writing);
    * - the most recent leg answered with a JSON-RPC error: `error-response`
    *   with that error's data;
    * - the most recent leg answered with a complete result: the server
@@ -1051,7 +1150,10 @@ export class ModernMcpConnection extends EventEmitter {
   private requestFailure(what: string, record: WireRecord, error: unknown, timeoutMs?: number, lost = false): Error {
     const server = `the "${this.id}" server`;
     const Server = `The "${this.id}" server`;
-    const message = redactServerText(error instanceof Error ? error.message : String(error), this.config);
+    // One build of the redactor for all of this failure's texts, so a
+    // configuration that can't be read is read once.
+    const redact = this.recorded.now();
+    const message = redact(error instanceof Error ? error.message : String(error));
     const log = (line: string) => console.error(`MCP server "${this.id}" ${line}`);
     const listing = record.method === 'tools/list';
     // What a failure whose effect is in doubt says: for a tool call, that the
@@ -1075,18 +1177,21 @@ export class ModernMcpConnection extends EventEmitter {
     }
     if (record.answer === 'error' && record.error) {
       const { code, message: wireMessage, data } = record.error;
-      // A JSON-RPC answer reaches the caller unredacted (redactServerText's
-      // scope). The log is a record of the server's text, so the message is
-      // redacted there, whatever JSON value it is, as every other line this
-      // connection writes is.
-      log(`answered ${what} with error ${logValue(code)}: ${logValueRedacted(wireMessage, (text) => redactServerText(text, this.config))}`);
-      // The server's own words, bounded as errors.ts says. Only a string is
-      // words: a message of any other JSON value reads as none.
-      const said = typeof wireMessage === 'string' ? boundedForLog(wireMessage.trim()) : '';
+      // The log is a record of the server's text, so the code (loggedCode)
+      // and the message are redacted there, whatever JSON values they are,
+      // as every other line this connection writes is.
+      log(`answered ${what} with error ${loggedCode(code, redact)}: ${logValueRedacted(wireMessage, redact)}`);
+      // The server's own words, redacted and then bounded as errors.ts says,
+      // since they're in an error the caller gets (redactServerText's
+      // scope), and its data's strings redacted too. It's trimmed after it's
+      // redacted, so a credential that ends in a space is whole when it's
+      // matched. Only a string is words: a message of any other JSON value
+      // reads as none.
+      const said = typeof wireMessage === 'string' ? boundedForLog(redact(wireMessage).trim()) : '';
       return new McplRequestError(
         said ? `${Server} answered with an error: ${said}` : unknown(`${Server} answered with an error without saying what went wrong`),
         'error-response',
-        data,
+        redactedData(data, redact),
       );
     }
     if (record.answer === 'complete') {
@@ -1132,10 +1237,14 @@ export class ModernMcpConnection extends EventEmitter {
       // The response body (the SDK's `text`) is the server's text and can
       // echo the request's url, so it's left out of the data; the status stays.
       const { text: _body, ...data } = (error instanceof SdkHttpError && error.data && typeof error.data === 'object' ? error.data : {}) as Record<string, unknown>;
+      const redacted = redactedData(data, redact);
       return new McplRequestError(
         `${Server} refused this host access, so the request didn't run. If you need it, ask whoever runs this host.`,
         'error-response',
-        { ...data, httpStatus: refusedWith },
+        // The status is this host's own, so it's added after the server's
+        // data is redacted, and it stays when a configuration that can't be
+        // read withholds that data.
+        { ...(redacted !== null && typeof redacted === 'object' ? redacted : {}), httpStatus: refusedWith },
       );
     }
     if (deadline) {

package/src/mcpl/prose-grammar.ts

@@ -1,9 +1,8 @@
 /**
- * Explicit-prose routing grammar — the SINGLE definition shared by the
- * delivery path (framework.deliverProse*) and the outgoing-stream router
- * (prose-stream-router.ts). Extracted from framework.ts verbatim so the two
- * parsers cannot drift: a streamed chunk and its eventual delivery must agree
- * on what is a prefix, what is a modifier, and what is body.
+ * Explicit-prose routing grammar: the prefix parsers the delivery path uses
+ * (parseProsePrefix, parseHybridProsePrefix). The envelope splitters in
+ * framework.ts test a line's `>>` or `>>>` start on their own. The outgoing
+ * stream needs no parser of its own: it carries what delivery publishes.
  *
  * Grammar (docs/explicit-prose-routing.md):
  *   `>>target [!] [body…]`  — target = channel spec or `skip_reply`