feat(openai): expose AsyncAPI server variable + subprotocol-auth

Wire tryAGI/AutoSDK #277 and #278 through asyncapi.json so the
generated OpenAiRealtimeClient surfaces:

- `ConnectAsync(string model, …)` — new typed overload that appends
  `?model=<model>` to the WebSocket URL via the AsyncAPI
  `servers[*].variables.model` declaration.
- `AuthorizeUsingSubprotocol(string apiKey)` + `useSubprotocolAuth`
  parameter on ConnectAsync — browser-compatible auth that sends the
  API key as a WebSocket subprotocol instead of an Authorization
  header (which the JS WebSocket constructor can't set).

Kept to a single subprotocol template to avoid the codegen bug I
filed as tryAGI/AutoSDK#282 (duplicate `__subProtocol` locals when
>1 template). The literal `realtime` subprotocol that OpenAI also
requires can be passed via `additionalSubProtocols` on ConnectAsync
until #282 lands, after which we can move it back into the scheme.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: HavenDV

src/libs/tryAGI.OpenAI/Generated/tryAGI.OpenAI.Realtime.OpenAiRealtimeClient.g.cs

@@ -45,6 +45,9 @@ public OpenAiRealtimeClient(
         private string? _storedAuthorizationHeaderScheme;
         private string? _storedAuthorizationApiKey;
 
+        private readonly global::System.Collections.Generic.Dictionary<string, string> _subprotocolAuthorizationValues = new global::System.Collections.Generic.Dictionary<string, string>(global::System.StringComparer.Ordinal);
+        private bool _preferSubprotocolAuth;
+
         /// <summary>
         /// Authorize using bearer authentication.
         /// </summary>
@@ -57,6 +60,8 @@ public void AuthorizeUsingBearer(
             _storedAuthorizationApiKey = apiKey;
             _storedAuthorizationHeaderName = "Authorization";
             _storedAuthorizationHeaderScheme = "bearer";
+            _preferSubprotocolAuth = false;
+            _subprotocolAuthorizationValues["apiKey"] = apiKey;
         }
 
         /// <summary>
@@ -75,13 +80,34 @@ public OpenAiRealtimeClient(
             Authorized(_clientWebSocket);
         }
 
+        /// <summary>
+        /// Authorize using WebSocket subprotocol authentication.
+        /// </summary>
+        /// <param name="apiKey"></param>
+        public void AuthorizeUsingSubprotocol(
+            string apiKey
+        )
+        {
+            var apiKeyValue = apiKey ?? throw new global::System.ArgumentNullException(nameof(apiKey));
+            _subprotocolAuthorizationValues["apiKey"] = apiKeyValue;
+            _preferSubprotocolAuth = true;
+        }
+
 
 
 
 
         private void ApplyStoredAuthorization(
             bool useSubprotocolAuth)
         {
+            if (useSubprotocolAuth || _preferSubprotocolAuth)
+            {
+                if (_subprotocolAuthorizationValues.ContainsKey("apiKey"))
+                {
+                    var __apiKey = _subprotocolAuthorizationValues["apiKey"];                    var __subProtocol = "openai-insecure-api-key.{apiKey}";
+                    __subProtocol = __subProtocol.Replace("{apiKey}", __apiKey);                    _clientWebSocket.Options.AddSubProtocol(__subProtocol);                    return;
+                }                return;
+            }
 
             if (_storedAuthorizationApiKey is not null &&
                 _storedAuthorizationHeaderName is not null)
@@ -95,14 +121,15 @@ private void ApplyStoredAuthorization(
         private void ApplyConnectionOptions(
             global::System.Collections.Generic.IDictionary<string, string>? additionalHeaders,
             global::System.Collections.Generic.IEnumerable<string>? additionalSubProtocols,
-            global::System.TimeSpan? keepAliveInterval)
+            global::System.TimeSpan? keepAliveInterval,
+            bool useSubprotocolAuth)
         {
             if (keepAliveInterval is not null)
             {
                 _clientWebSocket.Options.KeepAliveInterval = keepAliveInterval.Value;
             }
 
-            ApplyStoredAuthorization(false);
+            ApplyStoredAuthorization(useSubprotocolAuth);
 
             if (additionalHeaders is not null)
             {
@@ -146,13 +173,17 @@ private void ApplyConnectionOptions(
             }
         }
 
+        private const string DefaultBaseUrlTemplate = "wss://api.openai.com/v1/realtime";
+
+
         /// <inheritdoc cref="global::System.Net.WebSockets.ClientWebSocket.ConnectAsync(global::System.Uri, global::System.Threading.CancellationToken)"/>
         public async global::System.Threading.Tasks.Task ConnectAsync(
             global::System.Uri? uri = null,
             global::System.Collections.Generic.IDictionary<string, string>? additionalHeaders = null,
             global::System.Collections.Generic.IEnumerable<string>? additionalSubProtocols = null,
             global::System.TimeSpan? keepAliveInterval = null,
             global::System.TimeSpan? connectTimeout = null,
+            bool useSubprotocolAuth = false,
             global::System.Threading.CancellationToken cancellationToken = default)
         {
             global::System.Uri __uri;
@@ -168,7 +199,49 @@ private void ApplyConnectionOptions(
                 __uri = new global::System.Uri(__pathBuilder.ToString());
             }
 
-            ApplyConnectionOptions(additionalHeaders, additionalSubProtocols, keepAliveInterval);
+            ApplyConnectionOptions(additionalHeaders, additionalSubProtocols, keepAliveInterval, useSubprotocolAuth);
+            await ConnectAsyncCore(__uri, connectTimeout, cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Connects to the WebSocket server with typed connection parameters.
+        /// </summary>
+        /// <param name="model">Realtime model ID. The generator emits this as a required parameter on ConnectAsync and appends it to the URL as ?model=&lt;id&gt;.</param>
+        /// <param name="uri">Optional WebSocket endpoint override.</param>
+        /// <param name="additionalHeaders">Additional headers applied before connecting.</param>
+        /// <param name="additionalSubProtocols">Additional WebSocket subprotocols applied before connecting.</param>
+        /// <param name="keepAliveInterval">Optional keep-alive interval.</param>
+        /// <param name="connectTimeout">Optional connect timeout.</param>
+        /// <param name="useSubprotocolAuth">When true, applies stored subprotocol authentication instead of header authentication.</param>
+        /// <param name="cancellationToken">A cancellation token.</param>
+        public async global::System.Threading.Tasks.Task ConnectAsync(
+            string model,
+            global::System.Uri? uri = null,
+            global::System.Collections.Generic.IDictionary<string, string>? additionalHeaders = null,
+            global::System.Collections.Generic.IEnumerable<string>? additionalSubProtocols = null,
+            global::System.TimeSpan? keepAliveInterval = null,
+            global::System.TimeSpan? connectTimeout = null,
+            bool useSubprotocolAuth = false,
+            global::System.Threading.CancellationToken cancellationToken = default)
+        {
+            global::System.Uri __uri;
+            if (uri is not null)
+            {
+                __uri = uri;
+            }
+            else
+            {
+                var __baseUrl = DefaultBaseUrlTemplate;
+                var __pathBuilder = new global::tryAGI.OpenAI.Realtime.PathBuilder(
+                    path: __baseUrl);
+                __pathBuilder
+                .AddRequiredParameter("model", model)
+                ;
+
+                __uri = new global::System.Uri(__pathBuilder.ToString());
+            }
+
+            ApplyConnectionOptions(additionalHeaders, additionalSubProtocols, keepAliveInterval, useSubprotocolAuth);
             await ConnectAsyncCore(__uri, connectTimeout, cancellationToken).ConfigureAwait(false);
         }
 

src/libs/tryAGI.OpenAI/asyncapi.json

@@ -11,9 +11,20 @@
       "pathname": "/v1/realtime",
       "protocol": "wss",
       "description": "OpenAI Realtime WebSocket server",
+      "variables": {
+        "model": {
+          "description": "Realtime model ID. The generator emits this as a required parameter on ConnectAsync and appends it to the URL as ?model=<id>.",
+          "examples": [
+            "gpt-4o-realtime-preview"
+          ]
+        }
+      },
       "security": [
         {
           "$ref": "#/components/securitySchemes/bearer"
+        },
+        {
+          "$ref": "#/components/securitySchemes/subprotocol"
         }
       ]
     }
@@ -356,6 +367,13 @@
         "type": "http",
         "scheme": "bearer",
         "description": "OpenAI API key as a Bearer token."
+      },
+      "subprotocol": {
+        "type": "apiKey",
+        "description": "Browser-compatible auth via WebSocket subprotocols. When ConnectAsync is called with useSubprotocolAuth: true, the client advertises `openai-insecure-api-key.<apiKey>`, avoiding the need to set an Authorization header (which browsers disallow on the JS WebSocket constructor).\n\nOpenAI also expects the `realtime` subprotocol on the connection; include it via the `additionalSubProtocols` parameter on ConnectAsync.\n\nNOTE: single template until tryAGI/AutoSDK codegen bug (duplicate __subProtocol locals with >1 template) is fixed.",
+        "x-subprotocol-auth": [
+          "openai-insecure-api-key.{apiKey}"
+        ]
       }
     },
     "messages": {

src/libs/tryAGI.OpenAI/build-asyncapi.py

@@ -155,7 +155,20 @@ def main() -> int:
                 "pathname": "/v1/realtime",
                 "protocol": "wss",
                 "description": "OpenAI Realtime WebSocket server",
-                "security": [{"$ref": "#/components/securitySchemes/bearer"}],
+                "variables": {
+                    "model": {
+                        "description": (
+                            "Realtime model ID. The generator emits this as a "
+                            "required parameter on ConnectAsync and appends it "
+                            "to the URL as ?model=<id>."
+                        ),
+                        "examples": ["gpt-4o-realtime-preview"],
+                    }
+                },
+                "security": [
+                    {"$ref": "#/components/securitySchemes/bearer"},
+                    {"$ref": "#/components/securitySchemes/subprotocol"},
+                ],
             }
         },
         "channels": {
@@ -168,7 +181,26 @@ def main() -> int:
                     "type": "http",
                     "scheme": "bearer",
                     "description": "OpenAI API key as a Bearer token.",
-                }
+                },
+                "subprotocol": {
+                    "type": "apiKey",
+                    "description": (
+                        "Browser-compatible auth via WebSocket subprotocols. "
+                        "When ConnectAsync is called with useSubprotocolAuth: true, "
+                        "the client advertises `openai-insecure-api-key.<apiKey>`, "
+                        "avoiding the need to set an Authorization header (which "
+                        "browsers disallow on the JS WebSocket constructor).\n\n"
+                        "OpenAI also expects the `realtime` subprotocol on the "
+                        "connection; include it via the `additionalSubProtocols` "
+                        "parameter on ConnectAsync.\n\n"
+                        "NOTE: single template until tryAGI/AutoSDK codegen bug "
+                        "(duplicate __subProtocol locals with >1 template) is "
+                        "fixed."
+                    ),
+                    "x-subprotocol-auth": [
+                        "openai-insecure-api-key.{apiKey}",
+                    ],
+                },
             },
             "messages": component_messages,
             "schemas": inline_schemas,