refactor: remove SEP-1699 references and improve test quality

- Remove SEP-1699 references from all code comments
- Improve tests to validate priming events instead of skipping them
- Update readSSEEvent helper with documentation
- Fix notification tests to properly sequence reads after priming

Author: felixweinberger

src/client/streamableHttp.test.ts

@@ -1010,7 +1010,7 @@ describe('StreamableHTTPClientTransport', () => {
         });
     });
 
-    describe('SSE retry field handling (SEP-1699)', () => {
+    describe('SSE retry field handling', () => {
         beforeEach(() => {
             vi.useFakeTimers();
             (global.fetch as Mock).mockReset();

src/client/streamableHttp.ts

@@ -133,7 +133,7 @@ export class StreamableHTTPClientTransport implements Transport {
     private _reconnectionOptions: StreamableHTTPReconnectionOptions;
     private _protocolVersion?: string;
     private _hasCompletedAuthFlow = false; // Circuit breaker: detect auth success followed by immediate 401
-    private _serverRetryMs?: number; // Server-provided retry delay from SSE retry field (SEP-1699)
+    private _serverRetryMs?: number; // Server-provided retry delay from SSE retry field
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
@@ -248,7 +248,7 @@ export class StreamableHTTPClientTransport implements Transport {
      * @returns Time to wait in milliseconds before next reconnection attempt
      */
     private _getNextReconnectionDelay(attempt: number): number {
-        // SEP-1699: Use server-provided retry value if available
+        // Use server-provided retry value if available
         if (this._serverRetryMs !== undefined) {
             return this._serverRetryMs;
         }
@@ -323,7 +323,7 @@ export class StreamableHTTPClientTransport implements Transport {
                     .pipeThrough(
                         new EventSourceParserStream({
                             onRetry: (retryMs: number) => {
-                                // SEP-1699: Capture server-provided retry value for reconnection timing
+                                // Capture server-provided retry value for reconnection timing
                                 this._serverRetryMs = retryMs;
                             }
                         })
@@ -355,7 +355,7 @@ export class StreamableHTTPClientTransport implements Transport {
                     }
                 }
 
-                // SEP-1699: Handle graceful server-side disconnect
+                // Handle graceful server-side disconnect
                 // Server may close connection after sending event ID and retry field
                 if (isReconnectable && this._abortController && !this._abortController.signal.aborted) {
                     this._scheduleReconnection(

src/server/streamableHttp.test.ts

@@ -178,13 +178,16 @@ const TEST_MESSAGES = {
 };
 
 /**
- * Helper to extract text from SSE response
+ * Helper to extract text from SSE response, skipping priming events.
+ *
+ * Priming events have empty data fields and are sent to establish resumability.
+ * This helper keeps reading until it finds an event with actual content.
+ *
  * Note: Can only be called once per response stream. For multiple reads,
  * get the reader manually and read multiple times.
  */
 async function readSSEEvent(response: Response): Promise<string> {
     const reader = response.body?.getReader();
-    // Keep reading until we get an event with actual data (skip priming events)
     while (true) {
         const { value, done } = await reader!.read();
         if (done) break;
@@ -531,17 +534,22 @@ describe('StreamableHTTPServerTransport', () => {
         expect(sseResponse.status).toBe(200);
         const reader = sseResponse.body?.getReader();
 
-        // Skip the priming event
-        await reader!.read();
+        // Read and validate the priming event
+        const { value: primingValue } = await reader!.read();
+        const primingText = new TextDecoder().decode(primingValue);
+        expect(primingText).toContain('id: ');
+        const primingIdMatch = primingText.match(/id: ([^\n]+)/);
+        expect(primingIdMatch).toBeTruthy();
+        const primingEventId = primingIdMatch![1];
 
-        // Send multiple notifications
+        // Send a notification
         const notification1: JSONRPCMessage = {
             jsonrpc: '2.0',
             method: 'notifications/message',
             params: { level: 'info', data: 'First notification' }
         };
 
-        // Just send one and verify it comes through - then the stream should stay open
+        // Send and verify it comes through - then the stream should stay open
         await transport.send(notification1);
 
         const { value, done } = await reader!.read();
@@ -1358,6 +1366,14 @@ describe('StreamableHTTPServerTransport with resumability', () => {
         expect(sseResponse.status).toBe(200);
         expect(sseResponse.headers.get('content-type')).toBe('text/event-stream');
 
+        // Read from the stream
+        const reader = sseResponse.body?.getReader();
+
+        // Read and validate the priming event
+        const { value: primingValue } = await reader!.read();
+        const primingText = new TextDecoder().decode(primingValue);
+        expect(primingText).toContain('id: ');
+
         // Send a notification that should be stored with an event ID
         const notification: JSONRPCMessage = {
             jsonrpc: '2.0',
@@ -1368,12 +1384,7 @@ describe('StreamableHTTPServerTransport with resumability', () => {
         // Send the notification via transport
         await transport.send(notification);
 
-        // Read from the stream and verify we got the notification with an event ID
-        const reader = sseResponse.body?.getReader();
-
-        // Skip the priming event
-        await reader!.read();
-
+        // Read the notification
         const { value } = await reader!.read();
         const text = new TextDecoder().decode(value);
 
@@ -1544,8 +1555,8 @@ describe('StreamableHTTPServerTransport in stateless mode', () => {
     });
 });
 
-// Test SSE priming events (SEP-1699)
-describe('StreamableHTTPServerTransport SSE priming events (SEP-1699)', () => {
+// Test SSE priming events
+describe('StreamableHTTPServerTransport SSE priming events', () => {
     let server: Server;
     let transport: StreamableHTTPServerTransport;
     let baseUrl: URL;
@@ -1623,13 +1634,34 @@ describe('StreamableHTTPServerTransport SSE priming events (SEP-1699)', () => {
 
         // Read the priming event
         const reader = sseResponse.body?.getReader();
-        const { value } = await reader!.read();
-        const text = new TextDecoder().decode(value);
+        const { value: primingValue } = await reader!.read();
+        const primingText = new TextDecoder().decode(primingValue);
 
-        // Should have id field for resumability but NOT retry field
-        expect(text).toContain('id: ');
-        expect(text).toContain('data: ');
-        expect(text).not.toContain('retry:');
+        // Priming event should have id field for resumability but NOT retry field
+        expect(primingText).toContain('id: ');
+        expect(primingText).toContain('data: ');
+        expect(primingText).not.toContain('retry:');
+
+        // Extract priming event ID
+        const primingIdMatch = primingText.match(/id: ([^\n]+)/);
+        expect(primingIdMatch).toBeTruthy();
+        const primingEventId = primingIdMatch![1];
+
+        // Send a notification
+        const notification: JSONRPCMessage = {
+            jsonrpc: '2.0',
+            method: 'notifications/message',
+            params: { level: 'info', data: 'Test notification' }
+        };
+        await transport.send(notification);
+
+        // Read the notification
+        const { value: notifValue } = await reader!.read();
+        const notifText = new TextDecoder().decode(notifValue);
+
+        // Notification should have content and no retry field
+        expect(notifText).toContain('Test notification');
+        expect(notifText).not.toContain('retry:');
     });
 
     it('should include event ID in priming event for resumability', async () => {

src/server/streamableHttp.ts

@@ -111,8 +111,8 @@ export interface StreamableHTTPServerTransportOptions {
 
     /**
      * Retry interval in milliseconds to suggest to clients in SSE retry field.
-     * When set, the server will send a retry field in SSE events to control
-     * client reconnection timing (SEP-1699).
+     * When set, the server will send a retry field in SSE priming events to control
+     * client reconnection timing for polling behavior.
      */
     retryInterval?: number;
 }
@@ -329,7 +329,7 @@ export class StreamableHTTPServerTransport implements Transport {
         // otherwise the client will just wait for the first message
         res.writeHead(200, headers).flushHeaders();
 
-        // SEP-1699: Send priming event with id and empty data to establish resumption capability
+        // Send priming event to establish resumption capability
         // This primes the client's Last-Event-ID for reconnection
         const primingEventId = this._eventStore
             ? await this._eventStore.storeEvent(this._standaloneSseStreamId, {} as JSONRPCMessage)
@@ -570,7 +570,7 @@ export class StreamableHTTPServerTransport implements Transport {
 
                     res.writeHead(200, headers);
 
-                    // SEP-1699: Send priming event with id and empty data to establish resumption capability
+                    // Send priming event to establish resumption capability
                     // This primes the client's Last-Event-ID for reconnection
                     const primingEventId = this._eventStore
                         ? await this._eventStore.storeEvent(streamId, {} as JSONRPCMessage)