@dotsetlabs/bellwether 1.0.3 → 2.0.0

package/dist/transport/sse-transport.js

@@ -20,6 +20,75 @@ function validateSecureUrl(url) {
         throw new Error(`Invalid SSE URL: ${url}`);
     }
 }
+/**
+ * Minimal SSE parser for streaming responses.
+ */
+class SSEParser {
+    buffer = '';
+    eventName = 'message';
+    dataLines = [];
+    feed(chunk) {
+        const events = [];
+        this.buffer += chunk;
+        let newlineIndex = this.buffer.indexOf('\n');
+        while (newlineIndex !== -1) {
+            const rawLine = this.buffer.slice(0, newlineIndex);
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            const line = rawLine.replace(/\r$/, '');
+            // Empty line signals end of event
+            if (line === '') {
+                if (this.dataLines.length > 0) {
+                    events.push({
+                        event: this.eventName || 'message',
+                        data: this.dataLines.join('\n'),
+                    });
+                }
+                this.eventName = 'message';
+                this.dataLines = [];
+                newlineIndex = this.buffer.indexOf('\n');
+                continue;
+            }
+            // Comment/heartbeat
+            if (line.startsWith(':')) {
+                newlineIndex = this.buffer.indexOf('\n');
+                continue;
+            }
+            if (line.startsWith('event:')) {
+                this.eventName = line.slice('event:'.length).trim() || 'message';
+            }
+            else if (line.startsWith('data:')) {
+                this.dataLines.push(line.slice('data:'.length).trimStart());
+            }
+            newlineIndex = this.buffer.indexOf('\n');
+        }
+        return events;
+    }
+    flush() {
+        const events = [];
+        if (this.buffer.length > 0) {
+            const line = this.buffer.replace(/\r$/, '');
+            this.buffer = '';
+            if (line.startsWith(':')) {
+                // Ignore comments
+            }
+            else if (line.startsWith('event:')) {
+                this.eventName = line.slice('event:'.length).trim() || 'message';
+            }
+            else if (line.startsWith('data:')) {
+                this.dataLines.push(line.slice('data:'.length).trimStart());
+            }
+        }
+        if (this.dataLines.length > 0) {
+            events.push({
+                event: this.eventName || 'message',
+                data: this.dataLines.join('\n'),
+            });
+            this.eventName = 'message';
+            this.dataLines = [];
+        }
+        return events;
+    }
+}
 /**
  * SSETransport connects to MCP servers over HTTP using Server-Sent Events.
  *
@@ -32,7 +101,7 @@ function validateSecureUrl(url) {
  * - POST {baseUrl}/message - Endpoint for sending messages
  */
 export class SSETransport extends BaseTransport {
-    eventSource = null;
+    streamAbortController = null;
     abortController = null;
     connected = false;
     reconnectAttempts = 0;
@@ -74,61 +143,36 @@ export class SSETransport extends BaseTransport {
         validateSecureUrl(this.baseUrl);
         // Reset closing flag on fresh connection
         this.isClosing = false;
-        // EventSource is available in browsers natively and in Node.js 18+.
-        // We use globalThis to check availability at runtime, requiring `any` cast
-        // because TypeScript's lib.dom.d.ts doesn't type globalThis.EventSource.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const EventSourceImpl = globalThis.EventSource;
-        if (!EventSourceImpl) {
-            throw new Error('EventSource is not available. ' +
-                'SSE transport requires Node.js 18+ or a browser environment. ' +
-                'For older Node.js versions, consider using streamable-http transport instead.');
+        const sseUrl = `${this.baseUrl}/sse`;
+        this.log('Connecting to SSE endpoint', { url: sseUrl });
+        // Build URL with sessionId as query param for compatibility
+        let url = sseUrl;
+        if (this.sessionId) {
+            const separator = url.includes('?') ? '&' : '?';
+            url = `${url}${separator}sessionId=${encodeURIComponent(this.sessionId)}`;
         }
-        return new Promise((resolve, reject) => {
-            const sseUrl = `${this.baseUrl}/sse`;
-            this.log('Connecting to SSE endpoint', { url: sseUrl });
-            try {
-                // Create EventSource - headers need to be passed via URL params or custom implementation
-                // Note: Standard EventSource doesn't support custom headers
-                // For authenticated endpoints, session ID should be passed via URL param
-                let url = sseUrl;
-                if (this.sessionId) {
-                    const separator = url.includes('?') ? '&' : '?';
-                    url = `${url}${separator}sessionId=${encodeURIComponent(this.sessionId)}`;
-                }
-                this.eventSource = new EventSourceImpl(url);
-                this.eventSource.onopen = () => {
-                    this.log('SSE connection opened');
-                    this.connected = true;
-                    this.reconnectAttempts = 0;
-                    resolve();
-                };
-                this.eventSource.onmessage = (event) => {
-                    this.handleSSEMessage(event);
-                };
-                // Handle specific event types from MCP SSE protocol
-                this.eventSource.addEventListener('endpoint', (event) => {
-                    // Server tells us where to send messages
-                    const messageEvent = event;
-                    this.messageEndpoint = messageEvent.data;
-                    this.log('Received message endpoint', { endpoint: this.messageEndpoint ?? '' });
-                });
-                this.eventSource.addEventListener('message', (event) => {
-                    this.handleSSEMessage(event);
-                });
-                this.eventSource.onerror = (error) => {
-                    this.log('SSE error', { type: error.type });
-                    if (!this.connected) {
-                        // Connection failed on initial connect
-                        reject(new Error('Failed to connect to SSE endpoint'));
-                        return;
-                    }
-                    // Handle reconnection for established connections
-                    this.handleReconnect();
-                };
-            }
-            catch (error) {
-                reject(error);
+        this.streamAbortController = new AbortController();
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                Accept: 'text/event-stream',
+                ...this.headers,
+            },
+            signal: this.streamAbortController.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to connect to SSE endpoint: HTTP ${response.status}`);
+        }
+        if (!response.body) {
+            throw new Error('SSE response body is empty');
+        }
+        this.connected = true;
+        this.reconnectAttempts = 0;
+        // Start streaming in background
+        this.readSSEStream(response).catch((error) => {
+            this.log('SSE stream error', { error: String(error) });
+            if (!this.isClosing) {
+                this.handleReconnect();
             }
         });
     }
@@ -142,6 +186,11 @@ export class SSETransport extends BaseTransport {
             if (!data || data === ':') {
                 return;
             }
+            if (event.event === 'endpoint') {
+                this.messageEndpoint = data;
+                this.log('Received message endpoint', { endpoint: this.messageEndpoint ?? '' });
+                return;
+            }
             this.log('Received SSE message', { data });
             const message = JSON.parse(data);
             this.emit('message', message);
@@ -153,6 +202,47 @@ export class SSETransport extends BaseTransport {
             // Don't emit error for parse failures - just log
         }
     }
+    /**
+     * Stream and parse SSE events from a fetch response.
+     */
+    async readSSEStream(response) {
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error('SSE stream reader unavailable');
+        }
+        const decoder = new TextDecoder();
+        const parser = new SSEParser();
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (!value) {
+                continue;
+            }
+            const chunk = decoder.decode(value, { stream: true });
+            const events = parser.feed(chunk);
+            for (const event of events) {
+                this.handleSSEMessage(event);
+            }
+        }
+        const tail = decoder.decode();
+        if (tail) {
+            const tailEvents = parser.feed(tail);
+            for (const event of tailEvents) {
+                this.handleSSEMessage(event);
+            }
+        }
+        const flushed = parser.flush();
+        for (const event of flushed) {
+            this.handleSSEMessage(event);
+        }
+        // Stream ended
+        this.connected = false;
+        if (!this.isClosing) {
+            this.handleReconnect();
+        }
+    }
     /**
      * Handle reconnection after a connection error.
      *
@@ -161,7 +251,7 @@ export class SSETransport extends BaseTransport {
      * - Uses capped exponential backoff
      * - Clears reconnect timer on close
      * - Checks isClosing flag to prevent reconnection after close()
-     * - Explicitly closes EventSource on max attempts
+     * - Explicitly aborts SSE stream on max attempts
      */
     handleReconnect() {
         // Don't reconnect if we're closing
@@ -173,15 +263,15 @@ export class SSETransport extends BaseTransport {
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
             this.log('Max reconnect attempts reached', { attempts: this.reconnectAttempts });
             this.connected = false;
-            // Explicitly close the EventSource to clean up resources
-            if (this.eventSource) {
+            // Explicitly abort the SSE stream to clean up resources
+            if (this.streamAbortController) {
                 try {
-                    this.eventSource.close();
+                    this.streamAbortController.abort();
                 }
                 catch {
-                    // Ignore close errors
+                    // Ignore abort errors
                 }
-                this.eventSource = null;
+                this.streamAbortController = null;
             }
             this.emit('error', new Error(`Max reconnection attempts (${this.maxReconnectAttempts}) exceeded`));
             this.emit('close');
@@ -269,7 +359,7 @@ export class SSETransport extends BaseTransport {
      * Close the SSE connection.
      *
      * RELIABILITY: Properly cleans up all resources including:
-     * - EventSource connection
+     * - SSE stream connection
      * - Pending HTTP requests (via abort controller)
      * - Reconnection timer
      * - Sets isClosing flag to prevent reconnection attempts
@@ -284,15 +374,15 @@ export class SSETransport extends BaseTransport {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        // Close the EventSource connection
-        if (this.eventSource) {
+        // Abort SSE stream
+        if (this.streamAbortController) {
             try {
-                this.eventSource.close();
+                this.streamAbortController.abort();
             }
             catch {
-                // Ignore close errors
+                // Ignore abort errors
             }
-            this.eventSource = null;
+            this.streamAbortController = null;
         }
         // Abort any in-flight HTTP requests
         if (this.abortController) {

package/dist/version.js

@@ -30,7 +30,7 @@ function getPackageVersion() {
     }
     catch {
         // Fallback version - should match package.json
-        return '1.0.3';
+        return '2.0.0';
     }
 }
 /**

package/man/bellwether.1

@@ -1,4 +1,4 @@
-.TH "BELLWETHER" "1" "2026\-02\-02" "Bellwether 1.0.3" "User Commands"
+.TH "BELLWETHER" "1" "2026\-02\-04" "Bellwether 2.0.0" "User Commands"
 .SH NAME
 .PP
 bellwether \[em] MCP server testing and validation tool

package/man/bellwether.1.md

@@ -2,8 +2,8 @@
 title: BELLWETHER
 section: 1
 header: User Commands
-footer: Bellwether 1.0.3
-date: 2026-02-02
+footer: Bellwether 2.0.0
+date: 2026-02-04
 ---
 
 # NAME

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotsetlabs/bellwether",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "The open-source MCP testing tool. Structural drift detection and behavioral documentation for Model Context Protocol servers.",
   "type": "module",
   "main": "dist/index.js",

package/schemas/bellwether-check.schema.json

@@ -64,6 +64,30 @@
         "type": "string"
       }
     },
+    "semanticInferences": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/SemanticInference"
+        }
+      }
+    },
+    "schemaEvolution": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/ResponseSchemaEvolution"
+      }
+    },
+    "errorAnalysisSummaries": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/ErrorAnalysisSummary"
+      }
+    },
+    "documentationScore": {
+      "$ref": "#/$defs/DocumentationScore"
+    },
     "metadata": {
       "$ref": "#/$defs/InterviewMetadata"
     }
@@ -647,6 +671,167 @@
         "maxChainLength": { "type": "number" }
       },
       "additionalProperties": true
+    },
+    "SemanticInference": {
+      "type": "object",
+      "required": ["paramName", "inferredType", "confidence", "evidence"],
+      "properties": {
+        "paramName": { "type": "string" },
+        "inferredType": { "type": "string" },
+        "confidence": { "type": "number" },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "InferredSchema": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string" },
+        "properties": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/InferredSchema" }
+        },
+        "items": { "$ref": "#/$defs/InferredSchema" },
+        "required": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "nullable": { "type": "boolean" },
+        "enum": {
+          "type": "array",
+          "items": {}
+        }
+      },
+      "additionalProperties": true
+    },
+    "SchemaVersion": {
+      "type": "object",
+      "required": ["hash", "schema", "observedAt", "sampleCount"],
+      "properties": {
+        "hash": { "type": "string" },
+        "schema": { "$ref": "#/$defs/InferredSchema" },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "sampleCount": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "ResponseSchemaEvolution": {
+      "type": "object",
+      "required": ["currentHash", "history", "isStable", "stabilityConfidence", "inconsistentFields", "sampleCount"],
+      "properties": {
+        "currentHash": { "type": "string" },
+        "history": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SchemaVersion" }
+        },
+        "isStable": { "type": "boolean" },
+        "stabilityConfidence": { "type": "number" },
+        "inconsistentFields": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "sampleCount": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "ErrorPattern": {
+      "type": "object",
+      "required": ["category", "patternHash", "example", "count"],
+      "properties": {
+        "category": { "type": "string" },
+        "patternHash": { "type": "string" },
+        "example": { "type": "string" },
+        "count": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "EnhancedErrorAnalysis": {
+      "type": "object",
+      "required": ["pattern", "statusCategory", "rootCause", "remediation", "relatedParameters", "transient", "severity"],
+      "properties": {
+        "pattern": { "$ref": "#/$defs/ErrorPattern" },
+        "httpStatus": { "type": "number" },
+        "statusCategory": { "type": "string" },
+        "rootCause": { "type": "string" },
+        "remediation": { "type": "string" },
+        "relatedParameters": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "transient": { "type": "boolean" },
+        "severity": { "type": "string" },
+        "wasExpected": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "ErrorAnalysisSummary": {
+      "type": "object",
+      "required": ["tool", "totalErrors", "analyses", "dominantCategory", "transientErrors", "actionableCount"],
+      "properties": {
+        "tool": { "type": "string" },
+        "totalErrors": { "type": "number" },
+        "analyses": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/EnhancedErrorAnalysis" }
+        },
+        "dominantCategory": { "type": "string" },
+        "transientErrors": { "type": "number" },
+        "actionableCount": { "type": "number" },
+        "remediations": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "topRootCauses": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "topRemediations": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "relatedParameters": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "categoryCounts": {
+          "type": "object",
+          "additionalProperties": { "type": "number" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "DocumentationComponents": {
+      "type": "object",
+      "properties": {
+        "descriptionCoverage": { "type": "number" },
+        "descriptionQuality": { "type": "number" },
+        "parameterDocumentation": { "type": "number" },
+        "exampleCoverage": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "DocumentationScore": {
+      "type": "object",
+      "required": ["overallScore", "grade", "components", "issues", "suggestions", "toolCount"],
+      "properties": {
+        "overallScore": { "type": "number" },
+        "grade": { "type": "string" },
+        "components": { "$ref": "#/$defs/DocumentationComponents" },
+        "issues": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "suggestions": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "toolCount": { "type": "number" }
+      },
+      "additionalProperties": true
     }
   }
 }