@animalabs/agent-framework 0.30.0 → 0.31.0

package/dist/src/mcpl/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/mcpl/transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/mcpl/transport.ts"],"names":[],"mappings":"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"}

package/dist/src/mcpl/transport.js

@@ -20,9 +20,9 @@
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { StringDecoder } from 'node:string_decoder';
-import { escapeLineSeparators, readLines } from '../line-reader.js';
+import { MAX_LINE_CHARS, escapeLineSeparators, readLines } from '../line-reader.js';
 import WebSocket from 'ws';
-import { WITHHELD_TEXT, describeCredentialError, headerCarries, maskedError, noteDialSent, redactServerText, redactUrl, resolveServerBinding, serverTextRedactor, tokenTransportProblem, urlAsDialed } from './protocol-family.js';
+import { WITHHELD_TEXT, describeCredentialError, headerCarries, maskedError, noteDialSent, redactServerText, redactUrl, resolveServerBinding, serverConfigProblems, serverTextRedactor, tokenTransportProblem, urlAsDialed } from './protocol-family.js';
 import { assertBooleanSetting } from '../config-checks.js';
 import { logDetail } from './log-value.js';
 /**
@@ -33,19 +33,15 @@ import { logDetail } from './log-value.js';
  *  - `'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.
+ *  - `'unreaped'` `(failure: Error)`        a stdio child this transport was
+ *    ending outlived SIGKILL too: the transport stays open, owning the
+ *    child, and close() retries the reap (never WS)
  */
 export class McplTransport extends EventEmitter {
     serverId;
     _closed = false;
     lineBuffer = [];
-    stderrBuffer = [];
+    heldStderr = new HeldStderr();
     /** 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. */
@@ -60,9 +56,8 @@ export class McplTransport extends EventEmitter {
                 queueMicrotask(() => { for (const l of pending)
                     this.emit('line', l); });
             }
-            else if (event === 'stderr' && this.stderrBuffer.length > 0) {
-                const pending = this.stderrBuffer;
-                this.stderrBuffer = [];
+            else if (event === 'stderr' && !this.heldStderr.empty) {
+                const pending = this.heldStderr.take();
                 queueMicrotask(() => { for (const l of pending)
                     this.emit('stderr', l); });
             }
@@ -94,14 +89,7 @@ export class McplTransport extends EventEmitter {
     stderrTailRedacted(_redact) {
         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() {
+    get stdioStopCause() {
         return undefined;
     }
     /**
@@ -124,7 +112,7 @@ export class McplTransport extends EventEmitter {
         if (this.listenerCount('stderr') > 0)
             this.emit('stderr', line);
         else
-            this.stderrBuffer.push(line);
+            this.heldStderr.hold(line);
     }
     /**
      * Report a transport error: to the 'error' listeners if there are any, else
@@ -247,8 +235,8 @@ export const STDERR_END_WAIT_MS = 1_000;
 export class StdioTransport extends McplTransport {
     child;
     kind = 'stdio';
-    /** The first error on the child's stdin or stdout, named in the close reason. */
-    pipeError;
+    stopCause;
+    endedChild = false;
     /** The stream's last STDERR_WINDOW_CHARS, raw. */
     stderrWindow = '';
     /** True once the child's stderr has ended or closed. */
@@ -272,8 +260,8 @@ export class StdioTransport extends McplTransport {
             kept = kept.slice(1);
         return (cut ? '…' : '') + kept;
     }
-    get pipeFailure() {
-        return this.pipeError;
+    get stdioStopCause() {
+        return this.stopCause;
     }
     stderrEnded(ms) {
         const stderr = this.child.stderr;
@@ -301,20 +289,44 @@ export class StdioTransport extends McplTransport {
     serverId) {
         super(serverId);
         this.child = child;
-        this.stopLines = readLines(stdout, (line) => this.pushLine(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.
+        const lineBound = testLineBound ?? MAX_LINE_CHARS;
+        this.stopLines = readLines(stdout, {
+            line: (line) => this.pushLine(line),
+            tooLong: (maxChars) => this.stopStdio(new Error(`the server wrote a line on stdout longer than ${maxChars.toLocaleString('en-US')} UTF-16 code units`), false),
+        }, lineBound);
         let carry = '';
+        let dropping = false;
+        const dropped = `[a stderr line longer than ${lineBound.toLocaleString('en-US')} UTF-16 code units was dropped]`;
         const decoder = new StringDecoder('utf8');
         const received = (text) => {
             const window = this.stderrWindow + text;
             this.stderrWindow = window.slice(-STDERR_WINDOW_CHARS);
-            const lines = (carry + text).split('\n');
-            carry = lines.pop() ?? '';
-            for (const l of lines)
-                if (l.length > 0)
-                    this.pushStderr(l);
+            let rest = text;
+            if (dropping) {
+                const end = rest.indexOf('\n');
+                if (end === -1)
+                    return;
+                dropping = false;
+                rest = rest.slice(end + 1);
+            }
+            if (rest.includes('\n')) {
+                const lines = (carry + rest).split('\n');
+                carry = lines.pop() ?? '';
+                for (const l of lines) {
+                    if (l.length > lineBound)
+                        this.pushStderr(dropped);
+                    else if (l.length > 0)
+                        this.pushStderr(l);
+                }
+            }
+            else {
+                carry += rest;
+            }
+            if (carry.length > lineBound) {
+                carry = '';
+                dropping = true;
+                this.pushStderr(dropped);
+            }
         };
         this.child.stderr?.on('data', (chunk) => received(decoder.write(chunk)));
         // A last line with no newline is complete once the stream ends.
@@ -322,6 +334,7 @@ export class StdioTransport extends McplTransport {
             received(decoder.end());
             if (carry.length > 0)
                 this.pushStderr(carry);
+            carry = '';
             this.stderrDone = true;
         });
         // A stream destroyed by an error closes without ending: nothing more comes.
@@ -329,13 +342,17 @@ export class StdioTransport extends McplTransport {
         this.child.on('error', (err) => this.reportError(err));
         // The child's stdin and stdout carry the protocol, so after an error on
         // either, a write's EPIPE or a read error, this transport can't reach the
-        // child even if it's still running. The handler 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
+        // child even if it's still running. Nothing more is written (stdioStopCause),
+        // and the handler first gives the child its exit grace to exit on its
+        // own: a child already dead when the write failed, as one a stop's signal
+        // reached first, exits within it, and its close carries its own code and
+        // signal. One still running then is ended as close() ends it, SIGTERM and
+        // then SIGKILL, in the one attempt close() shares, and only that close is
+        // pipeFailed, since its signal is this transport's. Either way 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 and nothing is thrown.
+        // The first error starts the wait, 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
@@ -343,17 +360,8 @@ export class StdioTransport extends McplTransport {
         // 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) => {
-            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);
-        this.child.stdout?.on('error', endOnPipeError);
+        this.child.stdin?.on('error', (err) => this.stopStdio(err, true));
+        this.child.stdout?.on('error', (err) => this.stopStdio(err, true));
         // 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
@@ -362,9 +370,25 @@ export class StdioTransport extends McplTransport {
         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',
+            reason: this.stopCause ? `child process exited, and this host had stopped using the server's stdio (${this.stopCause.message})` : 'child process exited',
+            ...(this.endedChild ? { pipeFailed: true } : {}),
         }));
     }
+    stopStdio(cause, exitGraceFirst) {
+        if (this.stopCause)
+            return;
+        this.stopCause = cause;
+        const exitedFirst = exitGraceFirst ? this.exitWithin(this.exitGrace()) : Promise.resolve(this.exited());
+        void exitedFirst.then((gone) => {
+            if (gone || this.terminating)
+                return;
+            this.endedChild = true;
+            return this.terminate();
+        }).catch((failure) => {
+            if (!this.closed)
+                this.emit('unreaped', failure instanceof Error ? failure : new Error(String(failure)));
+        });
+    }
     /**
      * 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
@@ -419,9 +443,7 @@ export class StdioTransport extends McplTransport {
         return new StdioTransport(child, child.stdout, config.id);
     }
     writeLine(json) {
-        // Nothing more goes to a child whose stdin or stdout has failed: this
-        // transport is ending it.
-        if (this.pipeError)
+        if (this.stopCause)
             return;
         // stdin may be gone if the child died between the closed-check and here.
         this.child.stdin?.write(escapeLineSeparators(json) + '\n');
@@ -455,6 +477,21 @@ export class StdioTransport extends McplTransport {
         this.stopLines();
         await this.terminate();
     }
+    /** How long the child gets to exit after a pipe error, after SIGTERM and
+     *  after SIGKILL: {@link STDIO_EXIT_GRACE_MS}, or a test's grace for it. */
+    exitGrace() {
+        return testExitGraces.get(this.child) ?? STDIO_EXIT_GRACE_MS;
+    }
+    /** Whether the child exits within `ms`: true at once if it has. */
+    exitWithin(ms) {
+        if (this.exited())
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const onExit = () => { clearTimeout(timer); resolve(true); };
+            const timer = setTimeout(() => { this.child.off('exit', onExit); resolve(false); }, ms);
+            this.child.once('exit', onExit);
+        });
+    }
     /** 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;
@@ -479,24 +516,71 @@ export class StdioTransport extends McplTransport {
         const child = this.child;
         if (this.exited())
             return;
+        const grace = this.exitGrace();
         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))
+        if (await exitWithin(grace))
             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`);
+        console.error(`[mcpl] ${named} ignored SIGTERM for ${grace}ms — sending SIGKILL`);
         child.kill('SIGKILL');
-        if (await exitWithin(STDIO_EXIT_GRACE_MS))
+        if (await exitWithin(grace))
             return;
-        throw new Error(`${named} did not exit within ${STDIO_EXIT_GRACE_MS}ms of SIGKILL; it could not be reaped`);
+        throw new Error(`${named} did not exit within ${grace}ms of SIGKILL; it could not be reaped`);
     }
 }
-/** How long a stdio child gets to exit after SIGTERM, and again after SIGKILL. */
+/** How long a stdio child gets to exit on its own after a pipe error, after
+ *  SIGTERM, and again after SIGKILL. */
 const STDIO_EXIT_GRACE_MS = 2_000;
+const testExitGraces = new WeakMap();
+/**
+ * For tests only: `child` gets `ms` in place of {@link STDIO_EXIT_GRACE_MS}.
+ * Set it only on a child that can exit by no means, such as one whose
+ * `kill()` is a no-op and that nothing else ends while it's closed: a short
+ * grace there races no exit, and only brings "could not be reaped" sooner.
+ */
+export function setStdioExitGraceForTests(child, ms) {
+    testExitGraces.set(child, ms);
+}
+let testLineBound;
+const MAX_HELD_STDERR_LINES = 200;
+export class HeldStderr {
+    lines = [];
+    chars = 0;
+    dropped = 0;
+    get empty() {
+        return this.lines.length === 0 && this.dropped === 0;
+    }
+    hold(line) {
+        // V8 can make a line split from a longer string a slice that keeps the
+        // whole string alive, so a held line is copied to own only its characters.
+        this.lines.push(Buffer.from(line, 'utf16le').toString('utf16le'));
+        this.chars += line.length;
+        const ceiling = testLineBound ?? MAX_LINE_CHARS;
+        while (this.lines.length > MAX_HELD_STDERR_LINES || this.chars > ceiling) {
+            this.chars -= this.lines.shift().length;
+            this.dropped++;
+        }
+    }
+    take() {
+        const held = this.lines;
+        const taken = this.dropped > 0
+            ? [`[${this.dropped.toLocaleString('en-US')} earlier stderr line${this.dropped === 1 ? ' was' : 's were'} dropped: unread stderr is held to ${MAX_HELD_STDERR_LINES} lines and ${(testLineBound ?? MAX_LINE_CHARS).toLocaleString('en-US')} UTF-16 code units]`, ...held]
+            : held;
+        this.lines = [];
+        this.chars = 0;
+        this.dropped = 0;
+        return taken;
+    }
+}
+/** @internal */
+export function setStdioLineBoundForTests(maxChars) {
+    testLineBound = maxChars;
+}
 // ---------------------------------------------------------------------------
 // WebSocket
 // ---------------------------------------------------------------------------
@@ -550,6 +634,9 @@ export class WebSocketTransport extends McplTransport {
      * at the open timeout.
      */
     static async open(config, signal) {
+        const credentialRequired = checkedCredentialRequired(config);
+        if (credentialRequired === true)
+            return WebSocketTransport.openStrict(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.
@@ -650,6 +737,127 @@ export class WebSocketTransport extends McplTransport {
             });
         });
     }
+    /** Separate opt-in path: the legacy dial above keeps its objects, reads,
+     * receivers and error behavior. Capture policy before calling host code;
+     * only noteDialSent uses the original config after awaiting (as a WeakMap
+     * key, without reading it). No provider result is stored on either config. */
+    static async openStrict(config, signal) {
+        const captured = {
+            id: config.id, url: config.url, tokenTransport: config.tokenTransport,
+            credentialRequired: true, token: config.token, accessProvider: config.accessProvider,
+            command: config.command, transport: config.transport, protocol: config.protocol,
+        };
+        const id = captured.id;
+        const fail = (reason) => new Error(`MCPL server "${id}": ${reason}`);
+        let problems;
+        try {
+            problems = serverConfigProblems(captured);
+        }
+        catch {
+            throw fail('connection-failed');
+        }
+        if (problems.length)
+            throw fail('connection-failed');
+        const provider = captured.accessProvider;
+        if (typeof provider !== 'function')
+            throw fail('provider-failed');
+        const followRedirects = false;
+        let url;
+        try {
+            url = buildWebSocketUrl(captured, null);
+        }
+        catch {
+            throw fail('connection-failed');
+        }
+        if (signal?.aborted)
+            throw fail('connection-failed');
+        let token;
+        try {
+            // Preserve the provider's receiver, without re-reading any config input.
+            const provided = Promise.resolve(provider.call(config));
+            provided.catch(() => { });
+            token = signal ? await raceAbort(provided, signal) : await provided;
+        }
+        catch {
+            if (signal?.aborted)
+                throw fail('connection-failed');
+            throw fail('provider-failed');
+        }
+        if (signal?.aborted)
+            throw fail('connection-failed');
+        if (typeof token !== 'string' || !headerCarries(token))
+            throw fail('provider-failed');
+        noteDialSent(config, { url, token });
+        let ws;
+        try {
+            ws = new WebSocket(url, { headers: { Authorization: `Bearer ${token}` }, followRedirects });
+        }
+        catch {
+            throw fail('connection-failed');
+        }
+        const swallowLateErrors = () => { };
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const abandon = (reason = 'connection-failed', request, response) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                ws.removeAllListeners();
+                ws.on('error', swallowLateErrors);
+                // The status listener suppresses ws's default abort. Discard the body
+                // without inspecting it, and use the request API this engine offers.
+                try {
+                    response?.destroy();
+                }
+                catch { /* already gone */ }
+                try {
+                    if (typeof request?.destroy === 'function')
+                        request.destroy();
+                    else
+                        request?.abort?.(); // Some clients expose abort(), not destroy().
+                }
+                catch { /* already gone */ }
+                try {
+                    ws.terminate();
+                }
+                catch { /* already gone */ }
+                reject(fail(reason));
+            };
+            const timer = setTimeout(() => abandon(), WS_OPEN_TIMEOUT_MS);
+            const onAbort = () => abandon();
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            else
+                signal?.addEventListener('abort', onAbort, { once: true });
+            // Installed only on this explicit strict path. No peer text is a status.
+            ws.once('unexpected-response', (request, response) => {
+                const status = response?.statusCode;
+                // A refused upgrade without structured status cannot classify auth.
+                // Generic socket errors still mean connection-failed, never parsed text.
+                abandon(typeof status !== 'number' || !Number.isFinite(status) ? 'engine-unsupported'
+                    : status === 401 || status === 403 ? 'credential-rejected' : 'connection-failed', request, response);
+            });
+            ws.once('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                ws.removeAllListeners('unexpected-response');
+                const transport = new WebSocketTransport(ws, captured, url);
+                // Strict transport-created errors carry only id and a fixed code;
+                // don't project a native error or its cause into them.
+                ws.removeAllListeners('error');
+                ws.on('error', () => transport.reportError(fail('connection-failed')));
+                resolve(transport);
+            });
+            ws.once('error', () => abandon());
+        });
+    }
     writeLine(json) {
         if (this.ws.readyState === WebSocket.OPEN) {
             this.ws.send(escapeLineSeparators(json));
@@ -778,14 +986,23 @@ function dialsNetwork(config) {
  *  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 = {
+    credentialRequired: 'true requires a provider credential on every WebSocket dial without fallback; false or leaving it out keeps legacy behavior',
     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',
     toolHints: 'true advertises MCPL tool hints (RFC-014) to an MCPL server, so its dynamic tools are announced in the conversation and called through toolsets--act; leaving it out does the same wherever the name toolsets is free; false lists every tool as before and advertises none',
 };
+/** Direct transport callers bypass config validation, but not this check. */
+function checkedCredentialRequired(config) {
+    const value = config.credentialRequired;
+    if (value !== undefined && value !== null && typeof value !== 'boolean') {
+        assertBooleanSetting(`MCPL server "${config.id}" credentialRequired`, value, SERVER_CONFIG_BOOLEANS.credentialRequired);
+    }
+    return value;
+}
 /**
- * Refuse a server config whose `inheritEnv`, `reconnect`, `allowHostCommands`
- * or `toolHints` holds anything but true or false. A config read from JSON can carry a quoted
+ * Refuse a server config whose `inheritEnv`, `reconnect`, `allowHostCommands`,
+ * `credentialRequired` or `toolHints` 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
@@ -817,6 +1034,8 @@ export function assertServerConfigBooleans(config) {
  * performed the MCPL handshake.
  */
 export async function openTransport(config, signal) {
+    if (checkedCredentialRequired(config) === true)
+        return WebSocketTransport.open(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`);