@animalabs/agent-framework 0.22.2 → 0.23.0

package/dist/src/mcpl/transport.js

@@ -20,6 +20,9 @@ import { createInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
 import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
+import { describeCredentialError, noteDialSent, redactUrl, resolveServerBinding, urlAsDialed } from './protocol-family.js';
+import { assertBooleanSetting } from '../config-checks.js';
+import { logDetail } from './log-value.js';
 /**
  * A line-oriented duplex transport to an MCPL server.
  *
@@ -28,17 +31,25 @@ import WebSocket from 'ws';
  *  - `'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
  * lost across the handshake→routing handoff regardless of attach timing.
  */
 export class McplTransport extends EventEmitter {
+    serverId;
     _closed = false;
     lineBuffer = [];
     stderrBuffer = [];
-    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. */
+    constructor(serverId) {
         super();
+        this.serverId = serverId;
         // Flush buffered inbound lines the moment a consumer subscribes.
         this.on('newListener', (event) => {
             if (event === 'line' && this.lineBuffer.length > 0) {
@@ -67,6 +78,24 @@ export class McplTransport extends EventEmitter {
     get stderrTail() {
         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() {
+        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
+     * it hasn't. At once for a transport that has none.
+     */
+    stderrEnded(_ms) {
+        return Promise.resolve();
+    }
     /** Deliver an inbound line, buffering it if nobody is listening yet. */
     pushLine(line) {
         if (this.listenerCount('line') > 0)
@@ -81,6 +110,23 @@ export 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.
+     */
+    reportError(err) {
+        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. */
     markClosed(info) {
         if (this._closed)
@@ -113,15 +159,18 @@ 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
  *  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, hostEnv = process.env, platform = process.platform) {
     const win = platform === 'win32';
-    const env = config.inheritEnv ? { ...hostEnv } : {};
-    if (!config.inheritEnv) {
+    const inherit = config.inheritEnv === true;
+    const env = inherit ? { ...hostEnv } : {};
+    if (!inherit) {
         for (const [key, value] of Object.entries(hostEnv)) {
             if (value === undefined)
                 continue;
@@ -158,6 +207,19 @@ export function buildChildEnv(config, hostEnv = process.env, platform = process.
 }
 /** 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 {
     child;
     rl;
@@ -166,11 +228,38 @@ export class StdioTransport extends McplTransport {
     pipeError;
     stderrEnd = '';
     stderrCut = false;
+    /** True once the child's stderr has ended or closed. */
+    stderrDone = false;
     get stderrTail() {
         return (this.stderrCut ? '…' : '') + this.stderrEnd;
     }
-    constructor(child, rl) {
-        super();
+    get pipeFailure() {
+        return this.pipeError;
+    }
+    stderrEnded(ms) {
+        const stderr = this.child.stderr;
+        if (!stderr || this.stderrDone)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            let timer;
+            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);
+        });
+    }
+    constructor(child, rl, 
+    /** The server this child serves, named in its stderr lines and in what
+     *  its reaping reports. */
+    serverId) {
+        super(serverId);
         this.child = child;
         this.rl = rl;
         this.rl.on('line', (line) => this.pushLine(line));
@@ -199,21 +288,35 @@ export class StdioTransport extends McplTransport {
             received(decoder.end());
             if (carry.length > 0)
                 this.pushStderr(carry);
+            this.stderrDone = true;
         });
-        this.child.on('error', (err) => this.emit('error', err));
+        // 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).
+        // 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) => {
-            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) => {
+                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
@@ -222,14 +325,11 @@ export class StdioTransport extends McplTransport {
         // listener absorbs that copy.
         this.child.stdout?.on('error', endOnPipeError);
         this.rl.on('error', () => { });
-        // stderr carries diagnostics only: a read error on it is reported if
-        // anyone listens 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) => {
-            if (this.listenerCount('error') > 0)
-                this.emit('error', err);
-        });
+        // 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,
@@ -266,43 +366,109 @@ export class StdioTransport extends McplTransport {
             });
         });
         const rl = createInterface({ input: child.stdout });
-        return new StdioTransport(child, rl);
+        return new StdioTransport(child, rl, config.id);
     }
     writeLine(json) {
+        // 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() {
+    closing = 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() {
+        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) => {
+            if (this.exited())
+                return;
+            throw error;
+        });
+    }
+    async reap() {
         this.markClosed({ reason: 'closed by host' });
         this.rl.close();
-        if (this.child && !this.child.killed) {
-            this.child.kill();
-        }
-        await new Promise((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). */
+    exited() {
+        return this.child.pid === undefined || this.child.exitCode !== null || this.child.signalCode !== null;
+    }
+    terminating = 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.
+     */
+    terminate() {
+        this.terminating ??= this.escalate();
+        return this.terminating.catch((error) => {
+            if (this.exited())
+                return;
+            throw error;
         });
     }
+    async escalate() {
+        const child = this.child;
+        if (this.exited())
+            return;
+        const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+        const exitWithin = (ms) => new Promise((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
 // ---------------------------------------------------------------------------
 /** 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(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((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 {
     ws;
     kind = 'websocket';
-    constructor(ws) {
-        super();
+    constructor(ws, serverId) {
+        super(serverId);
         this.ws = ws;
         this.ws.on('message', (data, isBinary) => {
             // MCPL frames are UTF-8 JSON text. A frame MAY contain multiple
@@ -314,7 +480,7 @@ export class WebSocketTransport extends McplTransport {
                     this.pushLine(trimmed);
             }
         });
-        this.ws.on('error', (err) => this.emit('error', err));
+        this.ws.on('error', (err) => this.reportError(err));
         this.ws.on('close', (code, reason) => {
             const text = reason?.toString('utf8');
             this.markClosed(text ? { code, reason: text, reasonFromPeer: true } : { code, reason: 'websocket closed' });
@@ -323,27 +489,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) {
+    static async open(config, signal) {
         // 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 = config.token ?? null;
+        const abandoned = () => 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(() => { });
+                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.
-                console.error(`[mcpl] server "${config.id}": access provider failed (${err instanceof Error ? err.message : err}) — dialing with configured fallback`);
+                // The provider's own text may quote the credential, so it isn't logged.
+                console.error(`[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
         // live 2026-08-03: an HTTP 502 upgrade-reject emits the "Expected 101"
@@ -355,38 +537,41 @@ export class WebSocketTransport extends McplTransport {
         const swallowLateErrors = () => { };
         return new Promise((resolve, reject) => {
             let settled = false;
-            const timer = setTimeout(() => {
+            const abandon = (error) => {
                 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 = () => {
+                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));
+                resolve(new WebSocketTransport(ws, config.id));
             });
             ws.once('error', (err) => {
-                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})`));
             });
         });
     }
@@ -417,8 +602,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, tokenOverride) {
     if (!config.url) {
@@ -429,38 +615,82 @@ export function buildWebSocketUrl(config, tokenOverride) {
         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) {
-    if (config.transport === 'websocket')
-        return true;
-    if (config.transport === 'stdio')
+    try {
+        return resolveServerBinding(config).transport === 'websocket';
+    }
+    catch {
         return false;
-    return Boolean(config.url) && !config.command;
+    }
+}
+/** 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) {
+    try {
+        return resolveServerBinding(config).transport !== 'stdio';
+    }
+    catch {
+        return false;
+    }
+}
+/** 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 = {
+    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
+ * 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) {
+    for (const [setting, whatTrueDoes] of Object.entries(SERVER_CONFIG_BOOLEANS)) {
+        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) {
-    if (isWebSocketTransport(config)) {
-        return WebSocketTransport.open(config);
+export async function openTransport(config, signal) {
+    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);
 }
 //# sourceMappingURL=transport.js.map