feat(llm): X-OpenRouter-Categories attribution header + canonical X-OpenRouter-Title

Add OPENROUTER_APP_CATEGORIES as a third optional app-attribution env var,
mirroring OPENROUTER_APP_REFERER / OPENROUTER_APP_TITLE. When set, its value
is sent verbatim as the X-OpenRouter-Categories header (comma-separated
OpenRouter marketplace categories). OpenRouter silently ignores unrecognised
values, so the engine does no validation; an unparseable value is dropped
with a warning, like the other two headers.

Also switch the title header from the legacy X-Title to the current canonical
X-OpenRouter-Title (OpenRouter still accepts X-Title as an alias).

Docs (.env.example, README, README.zh, llm-audit, llm-audit.zh) and the three
attribution tests updated. OpenAPI snapshot unchanged.

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

Author: enriquephl

.env.example

@@ -13,6 +13,10 @@ OPENROUTER_API_KEY=sk-or-...
 # remain anonymous.
 # OPENROUTER_APP_REFERER=https://eros.example
 # OPENROUTER_APP_TITLE=Eros
+# Comma-separated OpenRouter marketplace categories (sent as
+# X-OpenRouter-Categories). Only takes effect alongside the referer;
+# OpenRouter silently ignores unrecognised values.
+# OPENROUTER_APP_CATEGORIES=roleplay,general-chat
 
 # OpenRouter response-side usage filter (optional). Comma-separated list of
 # top-level keys to strip from the `usage` object before it leaves the engine

README.md

@@ -234,7 +234,8 @@ for frame layout and error semantics.
 | `DATABASE_URL` | yes | Postgres with `pgvector`; tables are created under `engine.*`. |
 | `OPENROUTER_API_KEY` | yes | Chat completions, routed by `examples/model_config.toml` unless overridden. |
 | `OPENROUTER_APP_REFERER` | no | When set, sent as `HTTP-Referer` on every outbound OpenRouter call. Shows up on OpenRouter's app analytics dashboard. |
-| `OPENROUTER_APP_TITLE` | no | When set, sent as `X-Title`. Display name in OpenRouter app analytics. Pairs with `OPENROUTER_APP_REFERER`; both optional. |
+| `OPENROUTER_APP_TITLE` | no | When set, sent as `X-OpenRouter-Title`. Display name in OpenRouter app analytics. Pairs with `OPENROUTER_APP_REFERER`; both optional. |
+| `OPENROUTER_APP_CATEGORIES` | no | When set, sent as `X-OpenRouter-Categories` — comma-separated OpenRouter marketplace categories (e.g. `roleplay,general-chat`). Passed through verbatim; OpenRouter ignores unrecognised values and only honours it alongside `OPENROUTER_APP_REFERER`. |
 | `OPENROUTER_USAGE_HIDDEN_KEYS` | no | Comma-separated list of top-level keys to strip from the `usage` object on the SSE streaming `done` frame. Useful for hiding wholesale `cost` / `cost_details` from downstream customers. The full usage is still persisted and traced server-side. |
 | `VOYAGE_API_KEY` | yes | Embeddings. Empty keys fail server boot. |
 | `SUPABASE_URL` | no | Supabase project URL. When set, the server derives the JWKS endpoint (`<url>/auth/v1/.well-known/jwks.json`) for asymmetric (RS256/ES256) JWT validation — the post-2025 Supabase default. |

README.zh.md

@@ -178,7 +178,8 @@ Server 默認監聽 `0.0.0.0:8080`。Scalar API docs 在 `/docs`，OpenAPI JSON
 | `DATABASE_URL` | 是 | 帶 `pgvector` 的 Postgres；表建在 `engine.*`。 |
 | `OPENROUTER_API_KEY` | 是 | Chat completions；默認由 `examples/model_config.toml` 路由。 |
 | `OPENROUTER_APP_REFERER` | 否 | 設了之後每次出站 OpenRouter 調用都帶 `HTTP-Referer`。會出現在 OpenRouter 的 app 分析面板上。 |
-| `OPENROUTER_APP_TITLE` | 否 | 設了之後帶 `X-Title`。OpenRouter app analytics 顯示名稱。和 `OPENROUTER_APP_REFERER` 一對；兩個都可選。 |
+| `OPENROUTER_APP_TITLE` | 否 | 設了之後帶 `X-OpenRouter-Title`。OpenRouter app analytics 顯示名稱。和 `OPENROUTER_APP_REFERER` 一對；兩個都可選。 |
+| `OPENROUTER_APP_CATEGORIES` | 否 | 设了之后带 `X-OpenRouter-Categories` —— 逗号分隔的 OpenRouter marketplace 分类（如 `roleplay,general-chat`）。原样透传；OpenRouter 对无法识别的值静默忽略，且只有在同时设了 `OPENROUTER_APP_REFERER` 时才生效。 |
 | `OPENROUTER_USAGE_HIDDEN_KEYS` | 否 | 逗号分隔的顶层 key 列表，从 `usage` 对象里剔除 —— 在 SSE 流式 `done` 帧上生效。常用于把批发 `cost` / `cost_details` 隐藏起来不外泄给下游客户。完整 usage 仍会落库并写入服务器端 tracing。 |
 | `VOYAGE_API_KEY` | 是 | Embeddings。空 key 會拒絕啟動。 |
 | `SUPABASE_URL` | 否 | Supabase project URL。保留在 `.env.example` 裡方便 client / deploy 約定；目前 server 不讀取它。 |

crates/eros-engine-llm/src/openrouter.rs

@@ -17,7 +17,8 @@ const BASE_URL: &str = "https://openrouter.ai/api/v1/chat/completions";
 /// names become legacy and (if a transition window applies) get added as
 /// a parallel alias below.
 const HEADER_REFERER: &str = "HTTP-Referer";
-const HEADER_TITLE: &str = "X-Title";
+const HEADER_TITLE: &str = "X-OpenRouter-Title";
+const HEADER_CATEGORIES: &str = "X-OpenRouter-Categories";
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatMessage {
@@ -241,8 +242,15 @@ struct WireStreamFrame {
 pub struct AppAttribution {
     /// Sent as `HTTP-Referer`. Identifies the deploying app to OpenRouter.
     pub referer: Option<String>,
-    /// Sent as `X-Title`. Display name in OpenRouter's app analytics.
+    /// Sent as `X-OpenRouter-Title`. Display name in OpenRouter's app
+    /// analytics. (OpenRouter also accepts the legacy `X-Title` alias; we
+    /// send the current canonical name.)
     pub title: Option<String>,
+    /// Sent as `X-OpenRouter-Categories`. Comma-separated marketplace
+    /// categories for OpenRouter's app directory. Passed through verbatim;
+    /// OpenRouter silently ignores unrecognised values, so the engine does
+    /// no validation. Only takes effect when paired with `referer`.
+    pub categories: Option<String>,
 }
 
 #[derive(Clone)]
@@ -290,6 +298,18 @@ impl OpenRouterClient {
                 ),
             }
         }
+        if let Some(ref categories) = attribution.categories {
+            match reqwest::header::HeaderValue::from_str(categories) {
+                Ok(v) => {
+                    headers.insert(HEADER_CATEGORIES, v);
+                }
+                Err(e) => tracing::warn!(
+                    error = %e,
+                    header = HEADER_CATEGORIES,
+                    "openrouter: dropping invalid attribution value"
+                ),
+            }
+        }
         let http = reqwest::Client::builder()
             .default_headers(headers)
             .build()
@@ -615,7 +635,7 @@ mod tests {
         let server = MockServer::start().await;
         Mock::given(path("/api/v1/chat/completions"))
             .and(header("HTTP-Referer", "https://eros.example"))
-            .and(header("X-Title", "Eros"))
+            .and(header("X-OpenRouter-Title", "Eros"))
             .respond_with(ResponseTemplate::new(200).set_body_json(ok_response()))
             .expect(1)
             .mount(&server)
@@ -626,6 +646,7 @@ mod tests {
             AppAttribution {
                 referer: Some("https://eros.example".into()),
                 title: Some("Eros".into()),
+                categories: Some("roleplay,general-chat".into()),
             },
             format!("{}/api/v1/chat/completions", server.uri()),
         );
@@ -643,6 +664,20 @@ mod tests {
             })
             .await
             .expect("call succeeds");
+
+        // Categories is checked on the raw received value rather than via
+        // wiremock's `header` matcher: that matcher splits the received value
+        // on commas, so a comma-joined string would never compare equal. We
+        // want to prove the verbatim comma-separated string reaches the wire.
+        let reqs = server.received_requests().await.unwrap_or_default();
+        let categories = reqs
+            .iter()
+            .find_map(|r| r.headers.get("x-openrouter-categories"))
+            .expect("X-OpenRouter-Categories header present");
+        assert_eq!(
+            categories.to_str().expect("header is valid utf-8"),
+            "roleplay,general-chat"
+        );
     }
 
     #[tokio::test]
@@ -680,8 +715,12 @@ mod tests {
                 "HTTP-Referer must be absent when unset"
             );
             assert!(
-                req.headers.get("x-title").is_none(),
-                "X-Title must be absent when unset"
+                req.headers.get("x-openrouter-title").is_none(),
+                "X-OpenRouter-Title must be absent when unset"
+            );
+            assert!(
+                req.headers.get("x-openrouter-categories").is_none(),
+                "X-OpenRouter-Categories must be absent when unset"
             );
         }
     }
@@ -700,6 +739,7 @@ mod tests {
             AppAttribution {
                 referer: Some("bad\nvalue".into()),
                 title: Some("also\rbad".into()),
+                categories: Some("still\nbad".into()),
             },
             format!("{}/api/v1/chat/completions", server.uri()),
         );
@@ -724,8 +764,12 @@ mod tests {
                 "HTTP-Referer must be dropped"
             );
             assert!(
-                req.headers.get("x-title").is_none(),
-                "X-Title must be dropped"
+                req.headers.get("x-openrouter-title").is_none(),
+                "X-OpenRouter-Title must be dropped"
+            );
+            assert!(
+                req.headers.get("x-openrouter-categories").is_none(),
+                "X-OpenRouter-Categories must be dropped"
             );
         }
     }

crates/eros-engine-server/src/main.rs

@@ -208,6 +208,9 @@ async fn run_server() -> Result<()> {
         title: std::env::var("OPENROUTER_APP_TITLE")
             .ok()
             .filter(|s| !s.is_empty()),
+        categories: std::env::var("OPENROUTER_APP_CATEGORIES")
+            .ok()
+            .filter(|s| !s.is_empty()),
     };
     let openrouter = Arc::new(eros_engine_llm::openrouter::OpenRouterClient::new(
         openrouter_key,

docs/llm-audit.md

@@ -96,17 +96,22 @@ prompt_tokens=… completion_tokens=… total_tokens=… cost=…
 
 ## App-attribution headers
 
-Two optional env vars add headers to every outbound OpenRouter call:
+Three optional env vars add headers to every outbound OpenRouter call:
 
-| Env                       | Header         | Purpose                                          |
-|---------------------------|----------------|--------------------------------------------------|
-| `OPENROUTER_APP_REFERER`  | `HTTP-Referer` | App identifier on OpenRouter dashboards          |
-| `OPENROUTER_APP_TITLE`    | `X-Title`      | Display name in OpenRouter app analytics         |
+| Env                         | Header                    | Purpose                                          |
+|-----------------------------|---------------------------|--------------------------------------------------|
+| `OPENROUTER_APP_REFERER`    | `HTTP-Referer`            | App identifier on OpenRouter dashboards          |
+| `OPENROUTER_APP_TITLE`      | `X-OpenRouter-Title`      | Display name in OpenRouter app analytics         |
+| `OPENROUTER_APP_CATEGORIES` | `X-OpenRouter-Categories` | Comma-separated marketplace categories           |
 
-Both unset → today's behaviour (no attribution headers). They are set
+All unset → today's behaviour (no attribution headers). They are set
 per deployment, not per request — App-Attribution is intended for
 app-level aggregation. Per-user attribution belongs in `audit.user`.
 
+`OPENROUTER_APP_CATEGORIES` is passed through verbatim; OpenRouter
+silently ignores unrecognised values and only honours it when
+`OPENROUTER_APP_REFERER` is also set.
+
 Invalid values (control characters, non-ASCII outside header rules)
 are dropped at construction time with a `tracing::warn!`; the client
 still works.

docs/llm-audit.zh.md

@@ -90,17 +90,21 @@ prompt_tokens=… completion_tokens=… total_tokens=… cost=…
 
 ## App-attribution headers
 
-两个可选环境变量给每次出站 OpenRouter 调用加 header：
+三个可选环境变量给每次出站 OpenRouter 调用加 header：
 
-| Env                       | Header         | 用途                                          |
-|---------------------------|----------------|-----------------------------------------------|
-| `OPENROUTER_APP_REFERER`  | `HTTP-Referer` | OpenRouter 仪表盘上的 app 标识                |
-| `OPENROUTER_APP_TITLE`    | `X-Title`      | OpenRouter app analytics 里显示的名字         |
+| Env                         | Header                    | 用途                                          |
+|-----------------------------|---------------------------|-----------------------------------------------|
+| `OPENROUTER_APP_REFERER`    | `HTTP-Referer`            | OpenRouter 仪表盘上的 app 标识                |
+| `OPENROUTER_APP_TITLE`      | `X-OpenRouter-Title`      | OpenRouter app analytics 里显示的名字         |
+| `OPENROUTER_APP_CATEGORIES` | `X-OpenRouter-Categories` | 逗号分隔的 marketplace 分类                   |
 
-两个都不设 → 维持现状（不发任何 attribution header）。它们是
+都不设 → 维持现状（不发任何 attribution header）。它们是
 deployment 级别的设置，不是 per-request —— App-Attribution 的目的是
 app-level 聚合。Per-user 维度走 `audit.user`。
 
+`OPENROUTER_APP_CATEGORIES` 原样透传；OpenRouter 对无法识别的值静默
+忽略，且只有在同时设了 `OPENROUTER_APP_REFERER` 时才生效。
+
 非法值（控制字符、非 ASCII 之类）在构造时被丢弃并打一条
 `tracing::warn!`，client 仍然可用。