docs: Anthropic base URL must not end in /v1

feat(llm): optional custom User-Agent for LLM requests

.dockerignore

@@ -6,6 +6,10 @@ server/webui/dist
 /artex
 data
 keys
+backups
+.env
+config.json
+jwt.key
 *.db
 transcripts
 bench/kv

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Added
+
+- **Optional custom User-Agent for LLM requests**: an LLM profile can set a `User-Agent` value that overrides the header on every outbound LLM request; left empty, the default User-Agent is unchanged. The value is trimmed and rejected if it contains control characters or exceeds 256 bytes. Part of #154 (the fixed-full-URL mode is not included).
+
+### Docs
+
+- **LLM base URL note in the README**: for the Anthropic format, enter the host without a `/v1` suffix (the provider appends `/v1/messages`, so a `/v1` base becomes `/v1/v1/messages`); OpenAI-format providers append `/chat/completions`, so their base does end in `/v1`. Follow-up to #154.
+
 ## [0.5.1] - 2026-11-05
 
 Login rate limiting per client IP with trusted-proxy support, a 12-character minimum for new passwords, a loopback-only default for the binary, and the JWT signing key in its own Docker volume.

README.md

@@ -100,7 +100,6 @@ The web UI is published on `127.0.0.1` by default. To reach it from another mach
 git clone https://github.com/BaaRai/ARTEX.git
 cd ARTEX
 cp .env.example .env          # set POSTGRES_PASSWORD, optionally ANTHROPIC_API_KEY
-# build the single binary first (frontend, then go build -tags embedui), see the Dockerfile header
 docker compose up -d --build  # builds artex from this checkout + starts postgres
 # → http://localhost:8787
 ```
@@ -257,6 +256,8 @@ CGO_ENABLED=0 go build -tags embedui -o artex ./cmd/artex
 **LLM**: `export ANTHROPIC_API_KEY=sk-...` (or `OPENAI_API_KEY`); you can also fill it in on the UI's "LLM Configuration" page — which can add a local Ollama server as a keyless provider (format "Ollama", base URL default `http://127.0.0.1:11434/v1`, models loaded from the server).
 Optional: `ARTEX_LLM_PROVIDER` (anthropic | openai | openai-responses | ollama) / `ARTEX_LLM_MODEL` / `ARTEX_LLM_BASE_URL` / `ARTEX_LLM_PROXY`.
 
+**Base URL**: for the Anthropic format, enter the host **without** a `/v1` suffix (e.g. `https://api.anthropic.com`) — the provider appends `/v1/messages` itself, so a base ending in `/v1` becomes `https://api.anthropic.com/v1/v1/messages`. OpenAI-format providers append `/chat/completions`, so their base **does** end in `/v1` (e.g. `https://api.openai.com/v1`).
+
 **Concurrency**: the number of work agents per task is configured in "System Settings" (default 3).
 
 **Common flags**: `./start.sh -addr :8787 -proxy :8788` (`-addr` frontend+API, `-proxy` traffic recording proxy). The startup script passes arguments through to `artex` verbatim.

agent/provider.go

@@ -86,6 +86,10 @@ type Config struct {
 	// context via transcript.WithSessionID and read by the RoundTripper, so even a
 	// shared provider emits different header values per session.
 	SessionHeaderKey string
+	// UserAgent, when non-empty, overrides the User-Agent header on every outbound
+	// LLM request built from this config. Empty = don't set it, leaving the Go/Norma
+	// default UA untouched (the historical behavior). Validated by ValidateUserAgent.
+	UserAgent string
 	// Retry holds the retry parameters resolved for this config (profile override →
 	// global policy → built-in default, resolved server-side). See RetryConfig for
 	// the per-layer semantics; zero values = fully inherit the built-in defaults.
@@ -341,7 +345,7 @@ func (c Config) Provider() string {
 // limiter lives on the single provider instance — so planner + all workers +
 // main agent (which share this provider) are bounded by one shared rate limit.
 func (c Config) NewProvider() (llm.Provider, error) {
-	client, err := quotaAwareHTTPClient(c.Proxy, c.SessionHeaderKey)
+	client, err := quotaAwareHTTPClient(c.Proxy, c.SessionHeaderKey, c.UserAgent)
 	if err != nil {
 		return nil, err
 	}
@@ -440,6 +444,9 @@ type quotaAwareTransport struct {
 	// carries; its value is the session id read from the request context. Empty
 	// disables it. See Config.SessionHeaderKey.
 	sessionHeaderKey string
+	// userAgent, when non-empty, is set as the User-Agent header on every request.
+	// Empty leaves the default UA untouched. See Config.UserAgent.
+	userAgent string
 }
 
 func (t quotaAwareTransport) RoundTrip(req *http.Request) (*http.Response, error) {
@@ -452,6 +459,11 @@ func (t quotaAwareTransport) RoundTrip(req *http.Request) (*http.Response, error
 			req.Header.Set(t.sessionHeaderKey, sid)
 		}
 	}
+	// Custom User-Agent: override only when configured, so an empty value keeps the
+	// underlying transport's default UA exactly as before.
+	if t.userAgent != "" {
+		req.Header.Set("User-Agent", t.userAgent)
+	}
 	// When LLM recording is on, the Recorder puts a Capture on the context so the
 	// raw wire bodies can be persisted. This is the only layer that still sees
 	// them: norma builds the request body internally and decodes the SSE response
@@ -504,7 +516,7 @@ func requestBodySnapshot(req *http.Request) string {
 	return string(b)
 }
 
-func quotaAwareHTTPClient(proxy, sessionHeaderKey string) (*http.Client, error) {
+func quotaAwareHTTPClient(proxy, sessionHeaderKey, userAgent string) (*http.Client, error) {
 	transport := http.DefaultTransport.(*http.Transport).Clone()
 	proxy = strings.TrimSpace(proxy)
 	if proxy == "" {
@@ -523,7 +535,31 @@ func quotaAwareHTTPClient(proxy, sessionHeaderKey string) (*http.Client, error)
 		}
 		transport.Proxy = http.ProxyURL(proxyURL)
 	}
-	return &http.Client{Transport: quotaAwareTransport{base: transport, sessionHeaderKey: strings.TrimSpace(sessionHeaderKey)}}, nil
+	return &http.Client{Transport: quotaAwareTransport{base: transport, sessionHeaderKey: strings.TrimSpace(sessionHeaderKey), userAgent: strings.TrimSpace(userAgent)}}, nil
+}
+
+// MaxUserAgentLen bounds a custom User-Agent value. Generous for real UA strings
+// while keeping a pathological value out of every outbound request.
+const MaxUserAgentLen = 256
+
+// ValidateUserAgent trims a custom User-Agent and returns the cleaned value. An
+// empty/blank input is valid and means "no override" (keep the default UA). A
+// non-empty value is rejected when it exceeds MaxUserAgentLen or contains any
+// control character (including CR/LF, which would allow header injection).
+func ValidateUserAgent(raw string) (string, error) {
+	ua := strings.TrimSpace(raw)
+	if ua == "" {
+		return "", nil
+	}
+	if len(ua) > MaxUserAgentLen {
+		return "", fmt.Errorf("user agent too long: %d bytes (max %d)", len(ua), MaxUserAgentLen)
+	}
+	for _, r := range ua {
+		if r < 0x20 || r == 0x7f {
+			return "", fmt.Errorf("user agent contains a control character")
+		}
+	}
+	return ua, nil
 }
 
 // logTestConnection prints the raw HTTP status code(s) and response body of a

agent/provider_capture_test.go

@@ -21,7 +21,7 @@ func TestRoundTripCapturesRawBodies(t *testing.T) {
 	}))
 	defer srv.Close()
 
-	client, err := quotaAwareHTTPClient("", "")
+	client, err := quotaAwareHTTPClient("", "", "")
 	if err != nil {
 		t.Fatalf("client: %v", err)
 	}
@@ -65,7 +65,7 @@ func TestRoundTripCaptures429BodyAlongsideQuotaRewrite(t *testing.T) {
 	}))
 	defer srv.Close()
 
-	client, err := quotaAwareHTTPClient("", "")
+	client, err := quotaAwareHTTPClient("", "", "")
 	if err != nil {
 		t.Fatalf("client: %v", err)
 	}
@@ -106,7 +106,7 @@ func TestRoundTripWithoutCaptureIsUnchanged(t *testing.T) {
 	}))
 	defer srv.Close()
 
-	client, err := quotaAwareHTTPClient("", "")
+	client, err := quotaAwareHTTPClient("", "", "")
 	if err != nil {
 		t.Fatalf("client: %v", err)
 	}

agent/user_agent_test.go

@@ -0,0 +1,91 @@
+package agent
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// serveUA spins up an httptest server that records the User-Agent of the request
+// it receives, drives one request through a quotaAwareHTTPClient built with the
+// given userAgent, and returns what actually reached the wire.
+func serveUA(t *testing.T, userAgent string) string {
+	t.Helper()
+	got := make(chan string, 1)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got <- r.Header.Get("User-Agent")
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	client, err := quotaAwareHTTPClient("", "", userAgent)
+	if err != nil {
+		t.Fatalf("quotaAwareHTTPClient: %v", err)
+	}
+	resp, err := client.Get(srv.URL)
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	resp.Body.Close()
+	return <-got
+}
+
+func TestUserAgentHeaderSetWhenConfigured(t *testing.T) {
+	const want = "artex-test-agent/1.2.3"
+	if got := serveUA(t, want); got != want {
+		t.Fatalf("User-Agent = %q, want %q", got, want)
+	}
+}
+
+func TestUserAgentHeaderDefaultWhenEmpty(t *testing.T) {
+	// Empty = no override: the Go client's default UA must reach the server unchanged.
+	got := serveUA(t, "")
+	if !strings.HasPrefix(got, "Go-http-client/") {
+		t.Fatalf("User-Agent = %q, want the default Go-http-client UA when unset", got)
+	}
+}
+
+func TestValidateUserAgentRejectsNewline(t *testing.T) {
+	if _, err := ValidateUserAgent("good/1.0\r\nX-Injected: 1"); err == nil {
+		t.Fatalf("expected a newline-containing user agent to be rejected")
+	}
+}
+
+// The rule is "no control character at all" (r < 0x20 or r == 0x7f), so the
+// non-newline controls are rejected too, TAB included: a header value is one
+// printable token, not something to lay out with tabs.
+func TestValidateUserAgentRejectsControlCharacters(t *testing.T) {
+	for name, in := range map[string]string{
+		"NUL": "good/1.0\x00",
+		"US":  "good/1.0\x1f",
+		"DEL": "good/1.0\x7f",
+		"TAB": "good/1.0\tX",
+	} {
+		if _, err := ValidateUserAgent(in); err == nil {
+			t.Errorf("%s: expected a user agent containing %q to be rejected", name, in)
+		}
+	}
+}
+
+func TestValidateUserAgentAcceptsPrintableToken(t *testing.T) {
+	const want = "MyTool/1.0 (contact-free)"
+	if ua, err := ValidateUserAgent("  " + want + "  "); err != nil || ua != want {
+		t.Fatalf("printable value: got (%q, %v), want (%q, nil)", ua, err, want)
+	}
+}
+
+func TestValidateUserAgentRejectsTooLong(t *testing.T) {
+	if _, err := ValidateUserAgent(strings.Repeat("a", MaxUserAgentLen+1)); err == nil {
+		t.Fatalf("expected a user agent longer than %d to be rejected", MaxUserAgentLen)
+	}
+}
+
+func TestValidateUserAgentTrimsAndAllowsEmpty(t *testing.T) {
+	if ua, err := ValidateUserAgent("   "); err != nil || ua != "" {
+		t.Fatalf("blank user agent: got (%q, %v), want (\"\", nil)", ua, err)
+	}
+	if ua, err := ValidateUserAgent("  my-app/1.0  "); err != nil || ua != "my-app/1.0" {
+		t.Fatalf("trim: got (%q, %v), want (\"my-app/1.0\", nil)", ua, err)
+	}
+}

db/config.go

@@ -64,6 +64,10 @@ type LLMProfile struct {
 	// or sticky routing off a session-id header. "" = not sent. Maps to
 	// agent.Config.SessionHeaderKey.
 	SessionHeaderKey string `json:"session_header_key"`
+	// UserAgent, when non-empty, overrides the User-Agent header on every outbound
+	// request built from this profile. "" = don't override (keep the default UA);
+	// old profiles behave exactly as before. Maps to agent.Config.UserAgent.
+	UserAgent string `json:"user_agent"`
 	// Cost ledger: EUR per 1M tokens (0 = unset; cost is computed only when a
 	// price is set). Set through the same profile API/SaveProfile path.
 	PriceInputPerM      float64 `json:"price_input_per_m,omitempty"`
@@ -89,8 +93,8 @@ type RetryOverride struct {
 // profileCols is the read column list (hint variant, no api key) shared by the
 // list query; profileColsKey is the same with api_key for the single-row loads.
 const profileRetryCols = `COALESCE(retry_connect_attempts,0),COALESCE(retry_connect_interval_ms,0),COALESCE(retry_empty_attempts,0),COALESCE(retry_empty_interval_ms,0),COALESCE(retry_stream_attempts,0),COALESCE(retry_stream_interval_ms,0)`
-const profileCols = `id,name,format,COALESCE(base_url,''),COALESCE(proxy,''),model,COALESCE(api_key_hint,''),rate_per_second,rate_per_minute,context_window_k,COALESCE(reasoning_effort,''),is_default,priority,pool_exclude,COALESCE(thinking_type,''),COALESCE(streaming,true),COALESCE(max_tokens,0),COALESCE(max_tokens_field,''),COALESCE(session_header_key,''),` + profileRetryCols + `,COALESCE(price_input_per_m,0),COALESCE(price_output_per_m,0),COALESCE(price_cache_read_per_m,0),COALESCE(price_cache_write_per_m,0)`
-const profileColsKey = `id,name,format,COALESCE(base_url,''),COALESCE(proxy,''),model,COALESCE(api_key,''),rate_per_second,rate_per_minute,context_window_k,COALESCE(reasoning_effort,''),is_default,priority,pool_exclude,COALESCE(thinking_type,''),COALESCE(streaming,true),COALESCE(max_tokens,0),COALESCE(max_tokens_field,''),COALESCE(session_header_key,''),` + profileRetryCols + `,COALESCE(price_input_per_m,0),COALESCE(price_output_per_m,0),COALESCE(price_cache_read_per_m,0),COALESCE(price_cache_write_per_m,0)`
+const profileCols = `id,name,format,COALESCE(base_url,''),COALESCE(proxy,''),model,COALESCE(api_key_hint,''),rate_per_second,rate_per_minute,context_window_k,COALESCE(reasoning_effort,''),is_default,priority,pool_exclude,COALESCE(thinking_type,''),COALESCE(streaming,true),COALESCE(max_tokens,0),COALESCE(max_tokens_field,''),COALESCE(session_header_key,''),` + profileRetryCols + `,COALESCE(price_input_per_m,0),COALESCE(price_output_per_m,0),COALESCE(price_cache_read_per_m,0),COALESCE(price_cache_write_per_m,0),COALESCE(user_agent,'')`
+const profileColsKey = `id,name,format,COALESCE(base_url,''),COALESCE(proxy,''),model,COALESCE(api_key,''),rate_per_second,rate_per_minute,context_window_k,COALESCE(reasoning_effort,''),is_default,priority,pool_exclude,COALESCE(thinking_type,''),COALESCE(streaming,true),COALESCE(max_tokens,0),COALESCE(max_tokens_field,''),COALESCE(session_header_key,''),` + profileRetryCols + `,COALESCE(price_input_per_m,0),COALESCE(price_output_per_m,0),COALESCE(price_cache_read_per_m,0),COALESCE(price_cache_write_per_m,0),COALESCE(user_agent,'')`
 
 // scanProfile reads one row in the profileCols / profileColsKey column order. The
 // 7th column lands in APIKeyHint or APIKey depending on which list the caller used.
@@ -101,7 +105,8 @@ func scanProfile(sc interface{ Scan(...any) error }, into *string, p *LLMProfile
 		&p.Retry.Connect.Attempts, &p.Retry.Connect.IntervalMS,
 		&p.Retry.Empty.Attempts, &p.Retry.Empty.IntervalMS,
 		&p.Retry.Stream.Attempts, &p.Retry.Stream.IntervalMS,
-		&p.PriceInputPerM, &p.PriceOutputPerM, &p.PriceCacheReadPerM, &p.PriceCacheWritePerM)
+		&p.PriceInputPerM, &p.PriceOutputPerM, &p.PriceCacheReadPerM, &p.PriceCacheWritePerM,
+		&p.UserAgent)
 }
 
 func (d *DB) ListProfiles() ([]*LLMProfile, error) {
@@ -180,27 +185,27 @@ func (d *DB) SaveProfile(p *LLMProfile) (int64, error) {
 	r := p.Retry.Clamped()
 	if p.ID == 0 {
 		var id int64
-		err := d.QueryRow(`INSERT INTO llm_profiles(name,format,base_url,proxy,model,api_key,api_key_hint,rate_per_second,rate_per_minute,context_window_k,reasoning_effort,priority,pool_exclude,thinking_type,streaming,max_tokens,max_tokens_field,session_header_key,retry_connect_attempts,retry_connect_interval_ms,retry_empty_attempts,retry_empty_interval_ms,retry_stream_attempts,retry_stream_interval_ms)
-VALUES ($1,$2,NULLIF($3,''),NULLIF($4,''),$5,NULLIF($6,''),NULLIF($7,''),$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24) RETURNING id`,
+		err := d.QueryRow(`INSERT INTO llm_profiles(name,format,base_url,proxy,model,api_key,api_key_hint,rate_per_second,rate_per_minute,context_window_k,reasoning_effort,priority,pool_exclude,thinking_type,streaming,max_tokens,max_tokens_field,session_header_key,retry_connect_attempts,retry_connect_interval_ms,retry_empty_attempts,retry_empty_interval_ms,retry_stream_attempts,retry_stream_interval_ms,user_agent)
+VALUES ($1,$2,NULLIF($3,''),NULLIF($4,''),$5,NULLIF($6,''),NULLIF($7,''),$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25) RETURNING id`,
 			p.Name, p.Format, p.BaseURL, p.Proxy, p.Model, p.APIKey, hint, p.RatePerSecond, p.RatePerMinute, p.ContextWindowK, p.ReasoningEffort, p.Priority, p.PoolExclude, p.ThinkingType, p.Streaming, p.MaxTokens, p.MaxTokensField, p.SessionHeaderKey,
-			r.Connect.Attempts, r.Connect.IntervalMS, r.Empty.Attempts, r.Empty.IntervalMS, r.Stream.Attempts, r.Stream.IntervalMS).Scan(&id)
+			r.Connect.Attempts, r.Connect.IntervalMS, r.Empty.Attempts, r.Empty.IntervalMS, r.Stream.Attempts, r.Stream.IntervalMS, p.UserAgent).Scan(&id)
 		if err == nil {
 			_, err = d.saveProfilePrices(id, p)
 		}
 		return id, err
 	}
 	if p.APIKey == "" {
-		_, err := d.Exec(`UPDATE llm_profiles SET name=$1,format=$2,base_url=NULLIF($3,''),proxy=NULLIF($4,''),model=$5,rate_per_second=$6,rate_per_minute=$7,context_window_k=$8,reasoning_effort=$9,priority=$10,pool_exclude=$11,thinking_type=$12,streaming=$13,max_tokens=$14,max_tokens_field=$15,session_header_key=$16,retry_connect_attempts=$17,retry_connect_interval_ms=$18,retry_empty_attempts=$19,retry_empty_interval_ms=$20,retry_stream_attempts=$21,retry_stream_interval_ms=$22 WHERE id=$23`,
+		_, err := d.Exec(`UPDATE llm_profiles SET name=$1,format=$2,base_url=NULLIF($3,''),proxy=NULLIF($4,''),model=$5,rate_per_second=$6,rate_per_minute=$7,context_window_k=$8,reasoning_effort=$9,priority=$10,pool_exclude=$11,thinking_type=$12,streaming=$13,max_tokens=$14,max_tokens_field=$15,session_header_key=$16,retry_connect_attempts=$17,retry_connect_interval_ms=$18,retry_empty_attempts=$19,retry_empty_interval_ms=$20,retry_stream_attempts=$21,retry_stream_interval_ms=$22,user_agent=$23 WHERE id=$24`,
 			p.Name, p.Format, p.BaseURL, p.Proxy, p.Model, p.RatePerSecond, p.RatePerMinute, p.ContextWindowK, p.ReasoningEffort, p.Priority, p.PoolExclude, p.ThinkingType, p.Streaming, p.MaxTokens, p.MaxTokensField, p.SessionHeaderKey,
-			r.Connect.Attempts, r.Connect.IntervalMS, r.Empty.Attempts, r.Empty.IntervalMS, r.Stream.Attempts, r.Stream.IntervalMS, p.ID)
+			r.Connect.Attempts, r.Connect.IntervalMS, r.Empty.Attempts, r.Empty.IntervalMS, r.Stream.Attempts, r.Stream.IntervalMS, p.UserAgent, p.ID)
 		if err == nil {
 			_, err = d.saveProfilePrices(p.ID, p)
 		}
 		return p.ID, err
 	}
-	_, err := d.Exec(`UPDATE llm_profiles SET name=$1,format=$2,base_url=NULLIF($3,''),proxy=NULLIF($4,''),model=$5,api_key=$6,api_key_hint=$7,rate_per_second=$8,rate_per_minute=$9,context_window_k=$10,reasoning_effort=$11,priority=$12,pool_exclude=$13,thinking_type=$14,streaming=$15,max_tokens=$16,max_tokens_field=$17,session_header_key=$18,retry_connect_attempts=$19,retry_connect_interval_ms=$20,retry_empty_attempts=$21,retry_empty_interval_ms=$22,retry_stream_attempts=$23,retry_stream_interval_ms=$24 WHERE id=$25`,
+	_, err := d.Exec(`UPDATE llm_profiles SET name=$1,format=$2,base_url=NULLIF($3,''),proxy=NULLIF($4,''),model=$5,api_key=$6,api_key_hint=$7,rate_per_second=$8,rate_per_minute=$9,context_window_k=$10,reasoning_effort=$11,priority=$12,pool_exclude=$13,thinking_type=$14,streaming=$15,max_tokens=$16,max_tokens_field=$17,session_header_key=$18,retry_connect_attempts=$19,retry_connect_interval_ms=$20,retry_empty_attempts=$21,retry_empty_interval_ms=$22,retry_stream_attempts=$23,retry_stream_interval_ms=$24,user_agent=$25 WHERE id=$26`,
 		p.Name, p.Format, p.BaseURL, p.Proxy, p.Model, p.APIKey, hint, p.RatePerSecond, p.RatePerMinute, p.ContextWindowK, p.ReasoningEffort, p.Priority, p.PoolExclude, p.ThinkingType, p.Streaming, p.MaxTokens, p.MaxTokensField, p.SessionHeaderKey,
-		r.Connect.Attempts, r.Connect.IntervalMS, r.Empty.Attempts, r.Empty.IntervalMS, r.Stream.Attempts, r.Stream.IntervalMS, p.ID)
+		r.Connect.Attempts, r.Connect.IntervalMS, r.Empty.Attempts, r.Empty.IntervalMS, r.Stream.Attempts, r.Stream.IntervalMS, p.UserAgent, p.ID)
 	if err == nil {
 		_, err = d.saveProfilePrices(p.ID, p)
 	}

db/schema.sql

@@ -396,6 +396,8 @@ CREATE TABLE IF NOT EXISTS llm_profiles (
     -- Custom session header: when non-empty, every request carries an HTTP header of this name whose value is the current session id
     -- (chat session/worker intent). For gateways that do prompt caching/sticky routing by a session-id header. ''=do not send.
     session_header_key TEXT NOT NULL DEFAULT '',
+    -- Custom User-Agent: when non-empty, every outbound LLM request overrides the User-Agent header with this value. ''=do not override (keep the default UA).
+    user_agent       TEXT NOT NULL DEFAULT '',
     -- Retry overrides: attempts 0=use global default / -1=disable / >0=use this value; interval 0=use default exponential backoff / >0=fixed milliseconds.
     -- The three groups correspond to connect retry, empty-response retry, and same-provider safe-window retry; see the ALTER comment below.
     retry_connect_attempts    INTEGER NOT NULL DEFAULT 0,
@@ -436,6 +438,8 @@ ALTER TABLE llm_profiles ADD  CONSTRAINT llm_profiles_max_tokens_check
     CHECK (max_tokens >= 0);
 -- Custom session header name; backfills old databases. Default '' = do not send; old configs behave unchanged.
 ALTER TABLE llm_profiles ADD COLUMN IF NOT EXISTS session_header_key TEXT NOT NULL DEFAULT '';
+-- Custom User-Agent; backfills old databases. Default '' = do not override (keep the default UA); old configs behave unchanged.
+ALTER TABLE llm_profiles ADD COLUMN IF NOT EXISTS user_agent TEXT NOT NULL DEFAULT '';
 
 -- Per-profile retry overrides (see the LLM retry design doc). Each of the three groups is a pair of
 -- "attempts + fixed interval" with unified semantics: attempts 0=use the global default, -1=disable this layer's

mcphttp/client.go

@@ -28,7 +28,7 @@ import (
 	actool "github.com/Autumn-27/norma/tool"
 )
 
-const protocolVersion = "2025-06-18"
+const protocolVersion = "2025-11-25"
 const legacySSEProtocolVersion = "2024-11-05"
 
 // ToolName mirrors mcp.ToolName so remote tools share the mcp__server__tool scheme.
@@ -66,6 +66,11 @@ type Client struct {
 	mu        sync.Mutex
 	nextID    int
 	sessionID string
+	// initialized is set once initialize succeeds. Until then the
+	// MCP-Protocol-Version header is omitted: the spec requires it on requests
+	// after initialization, and the offered version already travels in the
+	// initialize body.
+	initialized bool
 
 	// legacySSE is the pre-2025 MCP SSE transport used by servers such as GSL5.
 	legacySSE    bool
@@ -247,18 +252,47 @@ func (c *Client) readLegacySSE(r *bufio.Reader) {
 }
 
 func (c *Client) initialize(ctx context.Context) error {
-	version := c.protocol
-	if version == "" {
-		version = protocolVersion
+	versions := []string{protocolVersion, "2025-06-18"}
+	if c.legacySSE {
+		versions = []string{legacySSEProtocolVersion}
 	}
-	if _, err := c.call(ctx, "initialize", map[string]any{
-		"protocolVersion": version,
-		"capabilities":    map[string]any{},
-		"clientInfo":      map[string]any{"name": "artex", "version": "0.2"},
-	}); err != nil {
-		return err
+	for i, version := range versions {
+		c.mu.Lock()
+		c.protocol = version
+		c.mu.Unlock()
+		result, err := c.call(ctx, "initialize", map[string]any{
+			"protocolVersion": version,
+			"capabilities":    map[string]any{},
+			"clientInfo":      map[string]any{"name": "artex", "version": "0.2"},
+		})
+		if err != nil {
+			if i+1 < len(versions) && isUnsupportedVersion(err) {
+				continue
+			}
+			return err
+		}
+		var negotiated struct {
+			ProtocolVersion string `json:"protocolVersion"`
+		}
+		c.mu.Lock()
+		if json.Unmarshal(result, &negotiated) == nil && negotiated.ProtocolVersion != "" {
+			c.protocol = negotiated.ProtocolVersion
+		}
+		c.initialized = true
+		c.mu.Unlock()
+		return c.notify(ctx, "notifications/initialized", map[string]any{})
 	}
-	return c.notify(ctx, "notifications/initialized", map[string]any{})
+	return fmt.Errorf("mcp: no supported protocol version")
+}
+
+// isUnsupportedVersion reports whether err is a server rejecting the offered
+// protocol version: the spec's "Unsupported protocol version" (JSON-RPC -32602,
+// or an HTTP 400 on the MCP-Protocol-Version header) or the
+// UNSUPPORTED_PROTOCOL_VERSION code some servers return instead.
+func isUnsupportedVersion(err error) bool {
+	msg := strings.ToLower(err.Error())
+	return strings.Contains(msg, "unsupported protocol version") ||
+		strings.Contains(msg, "unsupported_protocol_version")
 }
 
 // Tools lists the server's tools and adapts them to CoreTools.
@@ -438,17 +472,16 @@ func (c *Client) roundTrip(ctx context.Context, body rpcRequest, expectResp bool
 	}
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Accept", "application/json, text/event-stream")
-	version := c.protocol
-	if version == "" {
-		version = protocolVersion
+	c.mu.Lock()
+	sid := c.sessionID
+	initialized, version := c.initialized, c.protocol
+	c.mu.Unlock()
+	if initialized && version != "" {
+		req.Header.Set("MCP-Protocol-Version", version)
 	}
-	req.Header.Set("MCP-Protocol-Version", version)
 	for k, v := range c.headers {
 		req.Header.Set(k, v)
 	}
-	c.mu.Lock()
-	sid := c.sessionID
-	c.mu.Unlock()
 	if sid != "" {
 		req.Header.Set("Mcp-Session-Id", sid)
 	}

mcphttp/client_test.go

@@ -73,3 +73,163 @@ func TestStreamableClientRequestTimeout(t *testing.T) {
 	}
 	_ = c3.Close()
 }
+
+// initRequest captures what the client sent for one MCP request.
+type initRequest struct {
+	method, header, bodyVersion string
+}
+
+func recordRequest(r *http.Request) (rpcRequest, initRequest) {
+	var req rpcRequest
+	_ = json.NewDecoder(r.Body).Decode(&req)
+	rec := initRequest{method: req.Method, header: r.Header.Get("MCP-Protocol-Version")}
+	if p, ok := req.Params.(map[string]any); ok {
+		rec.bodyVersion, _ = p["protocolVersion"].(string)
+	}
+	return req, rec
+}
+
+// TestStreamableClientProtocolVersions uses spec-shaped servers that each support
+// one version: they answer initialize with their own version, accept a request
+// without MCP-Protocol-Version, and reject any other header value. The client
+// must send no version header on initialize and the negotiated one afterwards.
+func TestStreamableClientProtocolVersions(t *testing.T) {
+	for _, supported := range []string{"2025-11-25", "2025-06-18", "2025-03-26"} {
+		t.Run(supported, func(t *testing.T) {
+			var seen []initRequest
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				req, rec := recordRequest(r)
+				seen = append(seen, rec)
+				if rec.header != "" && rec.header != supported {
+					w.WriteHeader(http.StatusBadRequest)
+					fmt.Fprint(w, `{"code":"UNSUPPORTED_PROTOCOL_VERSION"}`)
+					return
+				}
+				w.Header().Set("Content-Type", "application/json")
+				switch req.Method {
+				case "initialize":
+					fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%d,"result":{"protocolVersion":%q,"capabilities":{},"serverInfo":{"name":"t","version":"0"}}}`, req.ID, supported)
+				case "notifications/initialized":
+					w.WriteHeader(http.StatusAccepted)
+				case "tools/list":
+					fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%d,"result":{"tools":[]}}`, req.ID)
+				default:
+					http.NotFound(w, r)
+				}
+			}))
+			defer srv.Close()
+
+			c, err := New(context.Background(), "t", srv.URL, nil, false, 0)
+			if err != nil {
+				t.Fatalf("connect: %v", err)
+			}
+			defer c.Close()
+			if _, err := c.Tools(context.Background()); err != nil {
+				t.Fatalf("tools/list: %v", err)
+			}
+			if c.protocol != supported {
+				t.Fatalf("negotiated protocol = %q", c.protocol)
+			}
+			var inits int
+			for _, rec := range seen {
+				if rec.method == "initialize" {
+					inits++
+					if rec.header != "" {
+						t.Fatalf("initialize carried MCP-Protocol-Version %q", rec.header)
+					}
+					if rec.bodyVersion != protocolVersion {
+						t.Fatalf("initialize offered %q, want %q", rec.bodyVersion, protocolVersion)
+					}
+					continue
+				}
+				if rec.header != supported {
+					t.Fatalf("%s carried MCP-Protocol-Version %q, want %q", rec.method, rec.header, supported)
+				}
+			}
+			if inits != 1 {
+				t.Fatalf("initialize attempts = %d, want 1", inits)
+			}
+		})
+	}
+}
+
+// TestStreamableClientVersionRejectionForms keeps the fallback loop honest for
+// servers that reject the initialize body version instead of negotiating: an
+// HTTP 400 "Unsupported protocol version", the JSON-RPC -32602 error from the
+// spec's example, and an unrelated failure that must not trigger a retry.
+func TestStreamableClientVersionRejectionForms(t *testing.T) {
+	cases := []struct {
+		name     string
+		reject   func(w http.ResponseWriter, id int)
+		fallback bool
+	}{
+		{"http 400", func(w http.ResponseWriter, _ int) {
+			http.Error(w, "Bad Request: Unsupported protocol version", http.StatusBadRequest)
+		}, true},
+		{"json-rpc -32602", func(w http.ResponseWriter, id int) {
+			w.Header().Set("Content-Type", "application/json")
+			fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%d,"error":{"code":-32602,"message":"Unsupported protocol version","data":{"supported":["2025-06-18"],"requested":"2025-11-25"}}}`, id)
+		}, true},
+		{"unrelated 401", func(w http.ResponseWriter, _ int) {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+		}, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var inits []initRequest
+			var after []initRequest
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				req, rec := recordRequest(r)
+				if req.Method == "initialize" {
+					inits = append(inits, rec)
+					if rec.bodyVersion != "2025-06-18" {
+						tc.reject(w, req.ID)
+						return
+					}
+				} else {
+					after = append(after, rec)
+				}
+				w.Header().Set("Content-Type", "application/json")
+				switch req.Method {
+				case "initialize":
+					fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%d,"result":{"protocolVersion":"2025-06-18","capabilities":{},"serverInfo":{"name":"t","version":"0"}}}`, req.ID)
+				case "notifications/initialized":
+					w.WriteHeader(http.StatusAccepted)
+				default:
+					http.NotFound(w, r)
+				}
+			}))
+			defer srv.Close()
+
+			c, err := New(context.Background(), "t", srv.URL, nil, false, 0)
+			for _, rec := range inits {
+				if rec.header != "" {
+					t.Fatalf("initialize carried MCP-Protocol-Version %q", rec.header)
+				}
+			}
+			if !tc.fallback {
+				if err == nil {
+					_ = c.Close()
+					t.Fatal("expected connect error")
+				}
+				if len(inits) != 1 {
+					t.Fatalf("unrelated error retried: %d initialize attempts", len(inits))
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("connect: %v", err)
+			}
+			defer c.Close()
+			if len(inits) != 2 || inits[0].bodyVersion != protocolVersion || inits[1].bodyVersion != "2025-06-18" {
+				t.Fatalf("fallback attempts = %+v", inits)
+			}
+			if c.protocol != "2025-06-18" {
+				t.Fatalf("negotiated protocol = %q", c.protocol)
+			}
+			if len(after) == 0 || after[0].method != "notifications/initialized" || after[0].header != "2025-06-18" {
+				t.Fatalf("requests after initialize = %+v", after)
+			}
+		})
+	}
+}

server/dto.go

@@ -617,6 +617,9 @@ type LLMProfileDTO struct {
 	// Custom session header name: when non-empty, every request carries this HTTP header,
 	// its value = the current session/intent's session id. '' = do not send. For gateways that key prompt caching/sticky routing off a session-id header.
 	SessionHeaderKey string `json:"session_header_key"`
+	// Custom User-Agent: when non-empty, every outbound LLM request overrides its
+	// User-Agent header with this value. '' = do not override (keep the default UA).
+	UserAgent string `json:"user_agent"`
 	// This profile's retry overrides (connect / empty response / same-provider safe
 	// window). Per item attempts: 0=inherit the global policy | -1=disable that retry
 	// layer | >0=count; interval_ms: 0=default exponential backoff | >0=use that fixed millisecond interval. All zero = fully follow the global policy, i.e. the historical behavior.
@@ -644,6 +647,7 @@ func llmProfileDTO(p *db.LLMProfile) LLMProfileDTO {
 		MaxTokens:        p.MaxTokens,
 		MaxTokensField:   p.MaxTokensField,
 		SessionHeaderKey: p.SessionHeaderKey,
+		UserAgent:        p.UserAgent,
 		Retry:            p.Retry,
 	}
 }

server/llm_key_endpoint_test.go

@@ -81,6 +81,44 @@ func TestLLMTestGlobalKeyOnlyForGlobalEndpoint(t *testing.T) {
 	}
 }
 
+// The connection test applies the same User-Agent rule as saving a profile: a
+// value with a control character is a 400 before any request leaves, and a
+// printable value reaches the wire exactly as given.
+func TestLLMTestValidatesUserAgent(t *testing.T) {
+	var hits atomic.Int32
+	var gotUA atomic.Value
+	fake := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hits.Add(1)
+		gotUA.Store(r.Header.Get("User-Agent"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"id":"m","type":"message","role":"assistant","model":"m","content":[{"type":"text","text":"OK"}],"stop_reason":"end_turn","usage":{"input_tokens":1,"output_tokens":1}}`))
+	}))
+	t.Cleanup(fake.Close)
+	s := &Server{}
+	post := func(ua string) *httptest.ResponseRecorder {
+		b, _ := json.Marshal(map[string]any{
+			"provider": "anthropic", "model": "m", "base_url": fake.URL, "api_key": "k", "streaming": false, "user_agent": ua,
+		})
+		req := httptest.NewRequest(http.MethodPost, "/api/llm/test", bytes.NewReader(b))
+		req.Header.Set("Content-Type", "application/json")
+		rec := httptest.NewRecorder()
+		s.testLLM(rec, req)
+		return rec
+	}
+
+	if rec := post("good/1.0\r\nX-Injected: 1"); rec.Code != http.StatusBadRequest || hits.Load() != 0 {
+		t.Fatalf("control character in user_agent: status %d hits=%d body=%s", rec.Code, hits.Load(), rec.Body.String())
+	}
+
+	const want = "MyTool/1.0 (contact-free)"
+	if rec := post("  " + want + "  "); rec.Code != http.StatusOK {
+		t.Fatalf("printable user_agent: status %d body=%s", rec.Code, rec.Body.String())
+	}
+	if ua, _ := gotUA.Load().(string); hits.Load() != 1 || ua != want {
+		t.Fatalf("test request User-Agent = %q (hits=%d), want %q", ua, hits.Load(), want)
+	}
+}
+
 // A stored profile's key goes only to that profile's base URL, for both the
 // connection test and the model listing.
 func TestStoredProfileKeyOnlyForStoredEndpoint(t *testing.T) {

server/server.go

@@ -355,6 +355,7 @@ func (s *Server) loadLLMConfig() (agent.Config, bool) {
 	cfg.Stream = p.Streaming
 	cfg.MaxTokens, cfg.MaxTokensField = p.MaxTokens, p.MaxTokensField
 	cfg.SessionHeaderKey = p.SessionHeaderKey
+	cfg.UserAgent = p.UserAgent
 	s.applyProfileRetry(&cfg, p)
 	// Ollama profiles run keyless (local server); the other formats need a key.
 	if cfg.APIKey == "" && cfg.NeedsAPIKey() {
@@ -381,6 +382,7 @@ func (s *Server) saveLLMConfig(cfg agent.Config) error {
 	var maxTokens int
 	var maxTokensField string
 	var sessionHeaderKey string
+	var userAgent string
 	var retry db.RetryOverride
 	if profs, _ := s.m.pg.ListProfiles(); profs != nil {
 		for _, p := range profs {
@@ -388,6 +390,7 @@ func (s *Server) saveLLMConfig(cfg agent.Config) error {
 				id, priority, poolExclude, streaming = p.ID, p.Priority, p.PoolExclude, p.Streaming
 				maxTokens, maxTokensField = p.MaxTokens, p.MaxTokensField
 				sessionHeaderKey = p.SessionHeaderKey
+				userAgent = p.UserAgent
 				retry = p.Retry
 				break
 			}
@@ -398,7 +401,7 @@ func (s *Server) saveLLMConfig(cfg agent.Config) error {
 		APIKey: cfg.APIKey, RatePerSecond: cfg.RatePerSecond, RatePerMinute: cfg.RatePerMinute,
 		ContextWindowK: cfg.ContextWindowK, ThinkingType: cfg.ThinkingType, ReasoningEffort: cfg.ReasoningEffort, IsDefault: true,
 		Priority: priority, PoolExclude: poolExclude, Streaming: streaming,
-		MaxTokens: maxTokens, MaxTokensField: maxTokensField, SessionHeaderKey: sessionHeaderKey,
+		MaxTokens: maxTokens, MaxTokensField: maxTokensField, SessionHeaderKey: sessionHeaderKey, UserAgent: userAgent,
 		Retry: retry,
 	})
 	if err != nil {
@@ -528,6 +531,7 @@ func (s *Server) loadProfileConfig(id int64) (agent.Config, bool) {
 	cfg.Stream = p.Streaming
 	cfg.MaxTokens, cfg.MaxTokensField = p.MaxTokens, p.MaxTokensField
 	cfg.SessionHeaderKey = p.SessionHeaderKey
+	cfg.UserAgent = p.UserAgent
 	s.applyProfileRetry(&cfg, p)
 	if cfg.APIKey == "" && cfg.NeedsAPIKey() {
 		return cfg, false
@@ -1418,6 +1422,7 @@ func (s *Server) testLLM(w http.ResponseWriter, r *http.Request) {
 		ProfileID        *int64 `json:"profile_id"`         // passed when testing a stored profile: if api_key is empty, its stored key is used
 		Streaming        *bool  `json:"streaming"`          // omitted = streaming, the same defaults as when saving a profile
 		SessionHeaderKey string `json:"session_header_key"` // non-empty = the test also sends this custom session header, with a one-off random session id as the value
+		UserAgent        string `json:"user_agent"`         // non-empty = the test overrides the User-Agent header with this value (mirrors production)
 	}
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		writeErr(w, 400, err.Error())
@@ -1477,6 +1482,20 @@ func (s *Server) testLLM(w http.ResponseWriter, r *http.Request) {
 	if stored != nil && cfg.SessionHeaderKey == "" {
 		cfg.SessionHeaderKey = strings.TrimSpace(stored.SessionHeaderKey)
 	}
+	// The custom User-Agent follows the profile too, so the test request uses the
+	// exact UA a real conversation would; the form value wins, else the stored one.
+	cfg.UserAgent = strings.TrimSpace(req.UserAgent)
+	if stored != nil && cfg.UserAgent == "" {
+		cfg.UserAgent = strings.TrimSpace(stored.UserAgent)
+	}
+	// Same rule as saving a profile: a value with control characters or over the
+	// length cap never reaches the wire, not even from the test button.
+	ua, err := agent.ValidateUserAgent(cfg.UserAgent)
+	if err != nil {
+		writeErr(w, 400, err.Error())
+		return
+	}
+	cfg.UserAgent = ua
 	// Keyless formats (Ollama) skip the key resolution entirely.
 	if cfg.NeedsAPIKey() {
 		// API key resolution precedence: form input > the named profile's stored key > the global config's key.

server/server_mgmt.go

@@ -1882,6 +1882,14 @@ func (s *Server) pgSaveProfile(w http.ResponseWriter, r *http.Request) {
 	if p.Format != "openai" || p.MaxTokensField != llm.MaxTokensFieldCompletion {
 		p.MaxTokensField = ""
 	}
+	// Custom User-Agent: trim and reject control characters / over-long values so a
+	// bad value can never inject a header or bloat every request. "" = no override.
+	ua, err := agent.ValidateUserAgent(p.UserAgent)
+	if err != nil {
+		writeErr(w, 400, err.Error())
+		return
+	}
+	p.UserAgent = ua
 	id, err := pg.SaveProfile(&p)
 	if err != nil {
 		writeErr(w, 500, err.Error())

server/side_questions.go

@@ -41,7 +41,7 @@ type sideQuestionState struct {
 }
 
 func sideModel(cfg agent.Config, id int64, name string) sidequestion.Model {
-	b, _ := json.Marshal([]any{cfg.Format, cfg.BaseURL, cfg.Model, cfg.ThinkingType, cfg.ReasoningEffort, cfg.Stream, cfg.MaxTokensField, cfg.SessionHeaderKey})
+	b, _ := json.Marshal([]any{cfg.Format, cfg.BaseURL, cfg.Model, cfg.ThinkingType, cfg.ReasoningEffort, cfg.Stream, cfg.MaxTokensField, cfg.SessionHeaderKey, cfg.UserAgent})
 	h := sha256.Sum256(b)
 	return sidequestion.Model{ProfileID: id, Name: name, Format: string(cfg.Format), Model: cfg.Model, Identity: hex.EncodeToString(h[:]), Streaming: cfg.Stream, WindowTokens: cfg.CompactionWindow()}
 }

web/src/app/(main)/system/llm/page.tsx

@@ -335,6 +335,7 @@ function ProfileSheet({
   const [maxTokens, setMaxTokens] = React.useState("0"); // per-reply output cap; 0 = not sent
   const [maxTokensField, setMaxTokensField] = React.useState(NONE); // which field name carries the cap; NONE = max_tokens
   const [sessionHeaderKey, setSessionHeaderKey] = React.useState(""); // custom session header name; empty = not sent
+  const [userAgent, setUserAgent] = React.useState(""); // custom User-Agent; empty = keep the default UA
   const [retry, setRetry] = React.useState<LLMRetryOverride>(ZERO_OVERRIDE); // retry override for this profile; all 0 = follow the global
   const [testing, setTesting] = React.useState(false);
   const [saving, setSaving] = React.useState(false);
@@ -366,6 +367,7 @@ function ProfileSheet({
     setMaxTokens(String(profile?.max_tokens ?? 0));
     setMaxTokensField(fromStore(profile?.max_tokens_field));
     setSessionHeaderKey(profile?.session_header_key ?? "");
+    setUserAgent(profile?.user_agent ?? "");
     setRetry(profile?.retry ?? ZERO_OVERRIDE);
     setApiKey("");
     setKeyHint(profile?.api_key_hint ?? "");
@@ -412,6 +414,7 @@ function ProfileSheet({
         profileId,
         streaming,
         sessionHeaderKey.trim(),
+        userAgent.trim(),
       );
       // Show the reply too: only when the model demonstrably spoke is this the same as working inside a session.
       if (r.ok)
@@ -455,6 +458,7 @@ function ProfileSheet({
         // and the backend re-applies the same normalization; this just keeps the UI from sending contradictory values.
         max_tokens_field: format === "openai" ? toStore(maxTokensField) : "",
         session_header_key: sessionHeaderKey.trim(),
+        user_agent: userAgent.trim(),
         retry,
       });
       if (isNew) toast.success(`Created: ${name.trim()} (use "Set as active" on its card to enable it)`);
@@ -613,6 +617,21 @@ function ProfileSheet({
             </p>
           </div>
 
+          <div className="grid gap-2">
+            <Label htmlFor="p-user-agent">Custom User-Agent (optional)</Label>
+            <Input
+              id="p-user-agent"
+              className="font-mono"
+              placeholder="e.g. my-app/1.0 (empty = default UA)"
+              value={userAgent}
+              onChange={(e) => setUserAgent(e.target.value)}
+            />
+            <p className="text-muted-foreground text-xs">
+              Overrides the <b>User-Agent</b> header on every outbound LLM request. Useful for gateways that route or allow-list by
+              User-Agent. Leave empty to keep the default User-Agent unchanged.
+            </p>
+          </div>
+
           <div className="grid gap-2">
             <Label htmlFor="p-api-key">
               {format === "ollama" ? "API Key (optional for Ollama)" : "API Key"}

web/src/lib/api.ts

@@ -949,6 +949,7 @@ export const api = {
     profile_id?: number,
     streaming = true, // test with the profile's real streaming mode so "streaming works, non-streaming does not" never leaks into conversations
     session_header_key = "", // non-empty = the test request also carries this custom session header (value is a one-off session id)
+    user_agent = "", // non-empty = the test overrides the User-Agent header with this value
   ) =>
     // reply = the model's actual reply (truncated); the backend marks a profile that replies with nothing as failed
     post<{ ok: boolean; error?: string; latency_ms?: number; model?: string; reply?: string }>("/llm/test", {
@@ -962,6 +963,7 @@ export const api = {
       profile_id,
       streaming,
       session_header_key,
+      user_agent,
     }),
   llmProfiles: () => get<{ profiles: LLMProfile[] }>("/llm/profiles").then((r) => arr(r.profiles)),
   saveLLMProfile: (p: {
@@ -983,6 +985,7 @@ export const api = {
     max_tokens?: number; // output cap per reply; 0 = not sent, the server default decides
     max_tokens_field?: string; // ""=max_tokens (default) | "max_completion_tokens" (openai format only)
     session_header_key?: string; // non-empty = send this HTTP header on every request, value = the current session id; "" = not sent
+    user_agent?: string; // non-empty = override the User-Agent header on every request; "" = keep the default UA
     retry?: LLMRetryOverride; // this profile's retry override; all zeros = follow the global retry policy
   }) => post<{ id: number }>("/llm/profiles", p),
   deleteLLMProfile: (id: string) => del<{ deleted: number }>(`/llm/profiles/${id}`),

web/src/lib/types.ts

@@ -1061,6 +1061,8 @@ export interface LLMProfile {
   // Custom session header name: when non-empty every request carries this HTTP header, value = the current session/intent session id.
   // "" = not sent. For gateways that do prompt caching/sticky routing on a session-id header.
   session_header_key?: string;
+  // Custom User-Agent: when non-empty, every outbound LLM request overrides its User-Agent header with this value. "" = do not override (keep the default UA).
+  user_agent?: string;
   // This profile's retry overrides (connect / empty response / same-provider safety window). Empty / all zeros = follow the global policy.
   retry?: LLMRetryOverride;
 }