feat(realtime): add xAI Grok Voice Agent realtime support

xAI's Voice Agent API (wss://api.x.ai/v1/realtime) is OpenAI Realtime API
compatible and derives from the base URL exactly like OpenAI's, so factor the
shared derivation into providers.OpenAIRealtimeURL and have both OpenAI and xAI
use it; Bailian keeps its own (/api-ws/v1/realtime) target.

- xai.Provider implements core.RealtimeProvider (+ retains baseURL, kept in sync
  by SetBaseURL).
- providers.OpenAIRealtimeURL: shared https->wss + /realtime?model= derivation,
  with its table test moved to the providers package.
- Compile-time core.RealtimeProvider assertions on OpenAI and xAI.

Verified live over the gateway: grok-voice-latest relays session.created ->
events -> response.done on both /v1/realtime and /p/xai/v1/realtime (the latter
once xai is added to ENABLED_PASSTHROUGH_PROVIDERS, confirming the allowlist
gate). Notes: xAI voice models are not in upstream /models discovery (configure
via XAI_MODELS) and xAI bills realtime per-minute, so it reports no token usage.

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

Author: SantiagoDePolonia

CLAUDE.md

@@ -114,7 +114,7 @@ Full reference: `.env.template` and `config/config.yaml`
   - `ENABLE_PASSTHROUGH_ROUTES` (true: Enable provider-native passthrough routes under /p/{provider}/...)
   - `ALLOW_PASSTHROUGH_V1_ALIAS` (true: Allow /p/{provider}/v1/... aliases while keeping /p/{provider}/... canonical)
   - `ENABLED_PASSTHROUGH_PROVIDERS` (openai,anthropic,openrouter,zai,vllm: Comma-separated list of enabled passthrough providers)
-  - `REALTIME_ENABLED` (true: Expose the realtime speech-to-speech websocket at `/v1/realtime` and the `/p/{provider}/v1/realtime` upgrade. The gateway is a transparent websocket reverse proxy — it injects provider credentials and relays the provider's realtime event schema verbatim (no translation), so clients connect without provider API keys. Only providers implementing realtime accept sessions; currently OpenAI (`wss://…/v1/realtime`) and Bailian/Qwen-Omni (`wss://dashscope…/api-ws/v1/realtime`). Sessions are gated by the same model-access and budget rules as other model endpoints; usage is tracked per `response.done` event, accepting both the OpenAI singular and Alibaba plural token-detail spellings.)
+  - `REALTIME_ENABLED` (true: Expose the realtime speech-to-speech websocket at `/v1/realtime` and the `/p/{provider}/v1/realtime` upgrade. The gateway is a transparent websocket reverse proxy — it injects provider credentials and relays the provider's realtime event schema verbatim (no translation), so clients connect without provider API keys. Only providers implementing realtime accept sessions; currently OpenAI and xAI/Grok Voice Agent (both `wss://…/v1/realtime`, OpenAI-realtime-compatible) and Bailian/Qwen-Omni (`wss://dashscope…/api-ws/v1/realtime`). xAI's voice models (e.g. `grok-voice-latest`) are not returned by upstream `/models` discovery, so configure them via `XAI_MODELS`; xAI bills realtime per-minute and reports no token usage. Sessions are gated by the same model-access and budget rules as other model endpoints; usage is tracked per `response.done` event, accepting both the OpenAI singular and Alibaba plural token-detail spellings.)
 - **Storage:** `STORAGE_TYPE` (sqlite), `SQLITE_PATH` (data/gomodel.db), `POSTGRES_URL`, `MONGODB_URL`
 - **Models:** `MODELS_ENABLED_BY_DEFAULT` (true), `MODEL_OVERRIDES_ENABLED` (true), `KEEP_ONLY_ALIASES_AT_MODELS_ENDPOINT` (false), `CONFIGURED_PROVIDER_MODELS_MODE` (`fallback` or `allowlist`, default `fallback`; `allowlist` skips upstream `/models` for providers with configured lists); persisted overrides restrict/allow selectors with `user_paths`. When alias-only models listing is enabled, `GET /v1/models` returns only model aliases, not full concrete model specs, to operators.
 - **Audit logging:** `LOGGING_ENABLED` (false), `LOGGING_LOG_BODIES` (false), `LOGGING_LOG_AUDIO_BODIES` (false: refines `LOGGING_LOG_BODIES` for audio endpoints — base64 audio for both `/v1/audio/speech` output and `/v1/audio/transcriptions` upload (≤8 MB each, else `too_large`) + dashboard playback, plus transcription upload metadata; no effect unless `LOGGING_LOG_BODIES` is on, in which case audio-off records a placeholder), `LOGGING_LOG_HEADERS` (false), `LOGGING_RETENTION_DAYS` (30)

internal/providers/openai/realtime.go

@@ -3,10 +3,10 @@ package openai
 import (
 	"context"
 	"net/http"
-	"net/url"
 	"strings"
 
 	"gomodel/internal/core"
+	"gomodel/internal/providers"
 )
 
 // RealtimeTarget implements core.RealtimeProvider for OpenAI's realtime websocket
@@ -18,7 +18,7 @@ func (p *Provider) RealtimeTarget(_ context.Context, req *core.RealtimeRequest)
 		return nil, core.NewInvalidRequestError("model is required for realtime sessions", nil)
 	}
 
-	endpoint, err := realtimeURL(p.baseURL, req.Model)
+	endpoint, err := providers.OpenAIRealtimeURL(p.baseURL, req.Model)
 	if err != nil {
 		return nil, err
 	}
@@ -33,32 +33,5 @@ func (p *Provider) RealtimeTarget(_ context.Context, req *core.RealtimeRequest)
 	return &core.RealtimeTarget{URL: endpoint, Headers: headers}, nil
 }
 
-// realtimeURL turns an HTTP(S) base URL such as https://api.openai.com/v1 into
-// the realtime websocket URL wss://api.openai.com/v1/realtime?model=... It maps
-// the scheme to ws/wss and appends the realtime path and model query parameter.
-func realtimeURL(baseURL, model string) (string, error) {
-	base := strings.TrimSpace(baseURL)
-	if base == "" {
-		base = defaultBaseURL
-	}
-	u, err := url.Parse(base)
-	if err != nil {
-		return "", core.NewInvalidRequestError("invalid realtime base url: "+err.Error(), err)
-	}
-	switch strings.ToLower(u.Scheme) {
-	case "https", "wss":
-		u.Scheme = "wss"
-	case "http", "ws":
-		u.Scheme = "ws"
-	default:
-		return "", core.NewInvalidRequestError("unsupported realtime base url scheme: "+u.Scheme, nil)
-	}
-	u.Path = strings.TrimRight(u.Path, "/") + "/realtime"
-	q := u.Query()
-	q.Set("model", model)
-	u.RawQuery = q.Encode()
-	return u.String(), nil
-}
-
 // Compile-time assertion that OpenAI implements the realtime capability.
 var _ core.RealtimeProvider = (*Provider)(nil)

internal/providers/openai/realtime_test.go

@@ -2,56 +2,13 @@ package openai
 
 import (
 	"context"
-	"net/url"
 	"strings"
 	"testing"
 
 	"gomodel/internal/core"
 	"gomodel/internal/providers"
 )
 
-func TestRealtimeURL(t *testing.T) {
-	tests := []struct {
-		name     string
-		baseURL  string
-		model    string
-		wantBase string // scheme://host/path before query
-		wantErr  bool
-	}{
-		{name: "default https to wss", baseURL: "https://api.openai.com/v1", model: "gpt-realtime", wantBase: "wss://api.openai.com/v1/realtime"},
-		{name: "empty base falls back to default", baseURL: "", model: "gpt-realtime", wantBase: "wss://api.openai.com/v1/realtime"},
-		{name: "trailing slash normalized", baseURL: "https://api.openai.com/v1/", model: "gpt-realtime", wantBase: "wss://api.openai.com/v1/realtime"},
-		{name: "http maps to ws", baseURL: "http://localhost:9000/v1", model: "m", wantBase: "ws://localhost:9000/v1/realtime"},
-		{name: "wss preserved", baseURL: "wss://example.com/v1", model: "m", wantBase: "wss://example.com/v1/realtime"},
-		{name: "unsupported scheme", baseURL: "ftp://example.com/v1", model: "m", wantErr: true},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, err := realtimeURL(tt.baseURL, tt.model)
-			if tt.wantErr {
-				if err == nil {
-					t.Fatalf("expected error, got %q", got)
-				}
-				return
-			}
-			if err != nil {
-				t.Fatalf("unexpected error: %v", err)
-			}
-			u, parseErr := url.Parse(got)
-			if parseErr != nil {
-				t.Fatalf("result is not a valid URL: %v", parseErr)
-			}
-			base := u.Scheme + "://" + u.Host + u.Path
-			if base != tt.wantBase {
-				t.Errorf("base = %q, want %q", base, tt.wantBase)
-			}
-			if u.Query().Get("model") != tt.model {
-				t.Errorf("model query = %q, want %q", u.Query().Get("model"), tt.model)
-			}
-		})
-	}
-}
-
 func TestRealtimeTarget(t *testing.T) {
 	const apiKey = "sk-secret-key"
 	p, ok := New(providers.ProviderConfig{APIKey: apiKey}, providers.ProviderOptions{}).(*Provider)

internal/providers/realtime_url.go

@@ -0,0 +1,39 @@
+package providers
+
+import (
+	"net/url"
+	"strings"
+
+	"gomodel/internal/core"
+)
+
+// OpenAIRealtimeURL derives an OpenAI-style realtime websocket URL from an
+// HTTP(S) base URL: https://host/v1 -> wss://host/v1/realtime?model=... It maps
+// the scheme to ws/wss and appends the realtime path and model query parameter.
+//
+// It is shared by providers whose realtime endpoint mirrors OpenAI's exact shape
+// (OpenAI, xAI). Providers whose realtime endpoint differs (e.g. Bailian's
+// /api-ws/v1/realtime) build their own target instead.
+func OpenAIRealtimeURL(baseURL, model string) (string, error) {
+	base := strings.TrimSpace(baseURL)
+	if base == "" {
+		return "", core.NewInvalidRequestError("realtime base url is required", nil)
+	}
+	u, err := url.Parse(base)
+	if err != nil {
+		return "", core.NewInvalidRequestError("invalid realtime base url: "+err.Error(), err)
+	}
+	switch strings.ToLower(u.Scheme) {
+	case "https", "wss":
+		u.Scheme = "wss"
+	case "http", "ws":
+		u.Scheme = "ws"
+	default:
+		return "", core.NewInvalidRequestError("unsupported realtime base url scheme: "+u.Scheme, nil)
+	}
+	u.Path = strings.TrimRight(u.Path, "/") + "/realtime"
+	q := u.Query()
+	q.Set("model", model)
+	u.RawQuery = q.Encode()
+	return u.String(), nil
+}

internal/providers/realtime_url_test.go

@@ -0,0 +1,48 @@
+package providers
+
+import (
+	"net/url"
+	"testing"
+)
+
+func TestOpenAIRealtimeURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		baseURL  string
+		model    string
+		wantBase string // scheme://host/path before query
+		wantErr  bool
+	}{
+		{name: "openai https to wss", baseURL: "https://api.openai.com/v1", model: "gpt-realtime", wantBase: "wss://api.openai.com/v1/realtime"},
+		{name: "xai https to wss", baseURL: "https://api.x.ai/v1", model: "grok-voice-latest", wantBase: "wss://api.x.ai/v1/realtime"},
+		{name: "trailing slash normalized", baseURL: "https://api.openai.com/v1/", model: "m", wantBase: "wss://api.openai.com/v1/realtime"},
+		{name: "http maps to ws", baseURL: "http://localhost:9000/v1", model: "m", wantBase: "ws://localhost:9000/v1/realtime"},
+		{name: "wss preserved", baseURL: "wss://example.com/v1", model: "m", wantBase: "wss://example.com/v1/realtime"},
+		{name: "empty base", baseURL: "", model: "m", wantErr: true},
+		{name: "unsupported scheme", baseURL: "ftp://example.com/v1", model: "m", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := OpenAIRealtimeURL(tt.baseURL, tt.model)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got %q", got)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			u, parseErr := url.Parse(got)
+			if parseErr != nil {
+				t.Fatalf("result is not a valid URL: %v", parseErr)
+			}
+			if base := u.Scheme + "://" + u.Host + u.Path; base != tt.wantBase {
+				t.Errorf("base = %q, want %q", base, tt.wantBase)
+			}
+			if u.Query().Get("model") != tt.model {
+				t.Errorf("model query = %q, want %q", u.Query().Get("model"), tt.model)
+			}
+		})
+	}
+}

internal/providers/xai/realtime.go

@@ -0,0 +1,35 @@
+package xai
+
+import (
+	"context"
+	"net/http"
+	"strings"
+
+	"gomodel/internal/core"
+	"gomodel/internal/providers"
+)
+
+// RealtimeTarget implements core.RealtimeProvider for xAI's Voice Agent API
+// (wss://api.x.ai/v1/realtime), which is largely OpenAI Realtime API compatible.
+// The endpoint shares OpenAI's shape, so the dial URL is derived from the base
+// URL the same way. Bearer auth is injected here and must never be logged.
+func (p *Provider) RealtimeTarget(_ context.Context, req *core.RealtimeRequest) (*core.RealtimeTarget, error) {
+	if req == nil || strings.TrimSpace(req.Model) == "" {
+		return nil, core.NewInvalidRequestError("model is required for realtime sessions", nil)
+	}
+
+	endpoint, err := providers.OpenAIRealtimeURL(p.baseURL, req.Model)
+	if err != nil {
+		return nil, err
+	}
+
+	headers := http.Header{}
+	if p.apiKey != "" {
+		headers.Set("Authorization", "Bearer "+p.apiKey)
+	}
+
+	return &core.RealtimeTarget{URL: endpoint, Headers: headers}, nil
+}
+
+// Compile-time assertion that xAI implements the realtime capability.
+var _ core.RealtimeProvider = (*Provider)(nil)

internal/providers/xai/realtime_test.go

@@ -0,0 +1,30 @@
+package xai
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gomodel/internal/core"
+	"gomodel/internal/providers"
+)
+
+func TestRealtimeTarget(t *testing.T) {
+	const apiKey = "xai-secret-key"
+	p := New(providers.ProviderConfig{APIKey: apiKey}, providers.ProviderOptions{}).(*Provider)
+
+	target, err := p.RealtimeTarget(context.Background(), &core.RealtimeRequest{Model: "grok-voice-latest"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.HasPrefix(target.URL, "wss://api.x.ai/v1/realtime?") {
+		t.Errorf("url = %q, want xAI realtime endpoint", target.URL)
+	}
+	if got := target.Headers.Get("Authorization"); got != "Bearer "+apiKey {
+		t.Errorf("Authorization = %q, want bearer with key", got)
+	}
+
+	if _, err := p.RealtimeTarget(context.Background(), &core.RealtimeRequest{Model: " "}); err == nil {
+		t.Fatal("expected error for missing model")
+	}
+}

internal/providers/xai/xai.go

@@ -32,16 +32,18 @@ const (
 
 // Provider implements the core.Provider interface for xAI
 type Provider struct {
-	client *llmclient.Client
-	apiKey string
+	client  *llmclient.Client
+	apiKey  string
+	baseURL string // retained to build the realtime websocket dial target
 }
 
 // New creates a new xAI provider.
 func New(providerCfg providers.ProviderConfig, opts providers.ProviderOptions) core.Provider {
-	p := &Provider{apiKey: providerCfg.APIKey}
+	baseURL := providers.ResolveBaseURL(providerCfg.BaseURL, defaultBaseURL)
+	p := &Provider{apiKey: providerCfg.APIKey, baseURL: baseURL}
 	clientCfg := llmclient.Config{
 		ProviderName:   "xai",
-		BaseURL:        providers.ResolveBaseURL(providerCfg.BaseURL, defaultBaseURL),
+		BaseURL:        baseURL,
 		Retry:          opts.Resilience.Retry,
 		Hooks:          opts.Hooks,
 		CircuitBreaker: opts.Resilience.CircuitBreaker,
@@ -56,7 +58,7 @@ func NewWithHTTPClient(apiKey string, httpClient *http.Client, hooks llmclient.H
 	if httpClient == nil {
 		httpClient = http.DefaultClient
 	}
-	p := &Provider{apiKey: apiKey}
+	p := &Provider{apiKey: apiKey, baseURL: defaultBaseURL}
 	cfg := llmclient.DefaultConfig("xai", defaultBaseURL)
 	cfg.Hooks = hooks
 	p.client = llmclient.NewWithHTTPClient(httpClient, cfg, p.setHeaders)
@@ -66,6 +68,7 @@ func NewWithHTTPClient(apiKey string, httpClient *http.Client, hooks llmclient.H
 // SetBaseURL allows configuring a custom base URL for the provider
 func (p *Provider) SetBaseURL(url string) {
 	p.client.SetBaseURL(url)
+	p.baseURL = url
 }
 
 // setHeaders sets the required headers for xAI API requests