feat(web): add optional LLM user email header

Author: brendan-kellam

docs/docs/configuration/environment-variables.mdx

@@ -42,6 +42,7 @@ The following environment variables allow you to configure your Sourcebot deploy
 | `ALWAYS_INDEX_FILE_PATTERNS` | - | <p>A comma separated list of glob patterns matching file paths that should always be indexed, regardless of size or number of trigrams.</p> |
 | `SOURCEBOT_CHAT_ATTACHMENT_MAX_IMAGE_BYTES` | `10485760` (10 MiB) | <p>Maximum size in bytes of a single image attachment uploaded to Ask Sourcebot. Enforced server-side at upload time.</p> |
 | `SOURCEBOT_CHAT_ATTACHMENT_ORPHAN_TTL_HOURS` | `24` | <p>How long in hours an uploaded-but-unsent attachment is retained before being deleted by the orphan sweep. Set to `0` to disable the sweep.</p> |
+| `SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED` | `false` | <p>When enabled, Sourcebot sends the authenticated user's lower-cased email address to configured language model providers in the `X-Sourcebot-User-Email` request header. Anonymous and automated requests omit the header.</p> |
 | `NODE_USE_ENV_PROXY` | `0` | <p>Enables Node.js to automatically use `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for network requests. Set to `1` to enable or `0` to disable. See [this doc](https://nodejs.org/en/learn/http/enterprise-network-configuration) for more info.</p> |
 | `HTTP_PROXY` | - | <p>HTTP proxy URL for routing non-SSL requests through a proxy server (e.g., `http://proxy.company.com:8080`). Requires `NODE_USE_ENV_PROXY=1`.</p> |
 | `HTTPS_PROXY` | - | <p>HTTPS proxy URL for routing SSL requests through a proxy server (e.g., `http://proxy.company.com:8080`). Requires `NODE_USE_ENV_PROXY=1`.</p> |
@@ -71,4 +72,4 @@ The following environment variables allow you to configure your Sourcebot deploy
 
 ### Overriding environment variables from the config
 
-You can override environment variables from the config file by using the `environmentOverrides` property. See [this doc](/docs/configuration/config-file#overriding-environment-variables-from-the-config) for more info.
+You can override environment variables from the config file by using the `environmentOverrides` property. See [this doc](/docs/configuration/config-file#overriding-environment-variables-from-the-config) for more info.

packages/shared/src/env.server.test.ts

@@ -82,3 +82,25 @@ describe('SOURCEBOT_MCP_TOOL_CALL_TIMEOUT_MS', () => {
         await expect(import('./env.server.js')).rejects.toThrow();
     });
 });
+
+describe('SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        delete process.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED;
+    });
+
+    afterEach(() => {
+        delete process.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED;
+    });
+
+    test('defaults to false', async () => {
+        const { env } = await import('./env.server.js');
+        expect(env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED).toBe('false');
+    });
+
+    test.each(['true', 'false'])('accepts %s', async (enabled) => {
+        process.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED = enabled;
+        const { env } = await import('./env.server.js');
+        expect(env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED).toBe(enabled);
+    });
+});

packages/shared/src/env.server.ts

@@ -313,6 +313,7 @@ const options = {
 
         SOURCEBOT_CHAT_MAX_STEP_COUNT: numberSchema.default(100),
         SOURCEBOT_CHAT_PROMPT_CACHING_ENABLED: booleanSchema.default('true'),
+        SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED: booleanSchema.default('false'),
         /** TTL for the static block. The moving tail marker always uses the 5m default. */
         SOURCEBOT_CHAT_PROMPT_CACHE_STATIC_TTL: z.enum(['5m', '1h']).default('5m'),
         /**

packages/web/src/app/api/(server)/ee/chat/route.ts

@@ -135,7 +135,10 @@ export const POST = apiHandler(async (req: NextRequest) => {
                 return attachmentError;
             }
 
-            const { model, providerOptions, temperature } = await getAISDKLanguageModelAndOptions(languageModelConfig);
+            const { model, providerOptions, temperature } = await getAISDKLanguageModelAndOptions(
+                languageModelConfig,
+                user?.email,
+            );
 
             // Authoritative, server-side resolution of the model's input
             // modalities. The agent's multimodal content builder and degrade

packages/web/src/ee/features/chat/actions.ts

@@ -43,7 +43,11 @@ export const generateAndUpdateChatNameFromMessage = async ({ chatId, languageMod
             } satisfies ServiceError;
         }
 
-        const name = await generateChatNameFromMessage({ message, languageModelConfig });
+        const name = await generateChatNameFromMessage({
+            message,
+            languageModelConfig,
+            userEmail: user?.email,
+        });
 
         await prisma.chat.update({
             where: {

packages/web/src/ee/features/chat/llm.server.ts

@@ -4,8 +4,16 @@ import { LanguageModel } from '@sourcebot/schemas/v3/languageModel.type';
 import { generateText } from "ai";
 import { getAISDKLanguageModelAndOptions } from "@/features/chat/llm.server";
 
-export const generateChatNameFromMessage = async ({ message, languageModelConfig }: { message: string, languageModelConfig: LanguageModel }) => {
-    const { model } = await getAISDKLanguageModelAndOptions(languageModelConfig);
+export const generateChatNameFromMessage = async ({
+    message,
+    languageModelConfig,
+    userEmail,
+}: {
+    message: string,
+    languageModelConfig: LanguageModel,
+    userEmail?: string,
+}) => {
+    const { model } = await getAISDKLanguageModelAndOptions(languageModelConfig, userEmail);
 
     const prompt = `Convert this question into a short topic title (max 50 characters).
 

packages/web/src/ee/features/mcp/askCodebase.ts

@@ -84,7 +84,10 @@ export const askCodebase = (params: AskCodebaseParams): Promise<AskCodebaseResul
                 languageModelConfig = matchingModel;
             }
 
-            const { model, providerOptions, temperature } = await getAISDKLanguageModelAndOptions(languageModelConfig);
+            const { model, providerOptions, temperature } = await getAISDKLanguageModelAndOptions(
+                languageModelConfig,
+                user?.email,
+            );
             const modelName = languageModelConfig.displayName ?? languageModelConfig.model;
             const contextWindow = await resolveContextWindow(languageModelConfig);
             const { inputModalities, supportedDocumentTypes } = await resolveModelCapabilities(languageModelConfig);
@@ -211,6 +214,7 @@ export const askCodebase = (params: AskCodebaseParams): Promise<AskCodebaseResul
                 generateChatNameFromMessage({
                     message: query,
                     languageModelConfig,
+                    userEmail: user?.email,
                 })
             ]);
 

packages/web/src/features/chat/languageModelHeaders.server.test.ts

@@ -0,0 +1,63 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    env: {
+        SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED: 'false',
+    },
+    getTokenFromConfig: vi.fn(),
+}));
+
+vi.mock('@sourcebot/shared', () => mocks);
+vi.mock('server-only', () => ({}));
+
+import {
+    resolveLanguageModelHeaders,
+    SOURCEBOT_USER_EMAIL_HEADER,
+} from './languageModelHeaders.server';
+
+describe('resolveLanguageModelHeaders', () => {
+    beforeEach(() => {
+        mocks.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED = 'false';
+        mocks.getTokenFromConfig.mockReset();
+    });
+
+    test('does not add the user email header by default', async () => {
+        await expect(resolveLanguageModelHeaders(undefined, 'User@Example.com')).resolves.toBeUndefined();
+    });
+
+    test('adds a lower-cased user email when enabled', async () => {
+        mocks.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED = 'true';
+
+        await expect(resolveLanguageModelHeaders(undefined, 'User@Example.COM')).resolves.toEqual({
+            [SOURCEBOT_USER_EMAIL_HEADER]: 'user@example.com',
+        });
+    });
+
+    test('omits the user email header for anonymous requests', async () => {
+        mocks.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED = 'true';
+
+        await expect(resolveLanguageModelHeaders(undefined, undefined)).resolves.toBeUndefined();
+    });
+
+    test('preserves configured headers and overrides a case-insensitive email header', async () => {
+        mocks.env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED = 'true';
+
+        await expect(resolveLanguageModelHeaders({
+            'x-sourcebot-user-email': 'configured@example.com',
+            'X-Custom-Header': 'custom-value',
+        }, 'Authenticated@Example.com')).resolves.toEqual({
+            'X-Custom-Header': 'custom-value',
+            [SOURCEBOT_USER_EMAIL_HEADER]: 'authenticated@example.com',
+        });
+    });
+
+    test('resolves token-backed configured headers', async () => {
+        const token = { env: 'CUSTOM_HEADER' };
+        mocks.getTokenFromConfig.mockResolvedValue('resolved-value');
+
+        await expect(resolveLanguageModelHeaders({ Authorization: token }, undefined)).resolves.toEqual({
+            Authorization: 'resolved-value',
+        });
+        expect(mocks.getTokenFromConfig).toHaveBeenCalledWith(token);
+    });
+});

packages/web/src/features/chat/languageModelHeaders.server.ts

@@ -0,0 +1,33 @@
+import 'server-only';
+
+import { Token } from '@sourcebot/schemas/v3/shared.type';
+import { env, getTokenFromConfig } from '@sourcebot/shared';
+
+export const SOURCEBOT_USER_EMAIL_HEADER = 'X-Sourcebot-User-Email';
+
+export const resolveLanguageModelHeaders = async (
+    configuredHeaders: Record<string, string | Token> | undefined,
+    userEmail: string | undefined,
+): Promise<Record<string, string> | undefined> => {
+    const headers: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(configuredHeaders ?? {})) {
+        headers[key] = typeof value === 'string'
+            ? value
+            : await getTokenFromConfig(value);
+    }
+
+    if (env.SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED === 'true' && userEmail) {
+        // Header names are case-insensitive. Remove any configured variant so
+        // the authenticated user's email is always the authoritative value.
+        for (const key of Object.keys(headers)) {
+            if (key.toLowerCase() === SOURCEBOT_USER_EMAIL_HEADER.toLowerCase()) {
+                delete headers[key];
+            }
+        }
+
+        headers[SOURCEBOT_USER_EMAIL_HEADER] = userEmail.toLowerCase();
+    }
+
+    return Object.keys(headers).length > 0 ? headers : undefined;
+};

packages/web/src/features/chat/llm.server.ts

@@ -23,6 +23,7 @@ import { Token } from "@sourcebot/schemas/v3/shared.type";
 import { env, getTokenFromConfig } from '@sourcebot/shared';
 import { extractReasoningMiddleware, JSONValue, wrapLanguageModel } from "ai";
 import * as Sentry from "@sentry/nextjs";
+import { resolveLanguageModelHeaders } from './languageModelHeaders.server';
 
 // @note: This module resolves a configured language model into an AI SDK
 // provider object. It is intentionally FSL (open source) provider plumbing —
@@ -31,12 +32,13 @@ import * as Sentry from "@sentry/nextjs";
 // review agent). The re-licensed Ask logic (prompts, tools, threads, chat
 // name generation) lives in `@/ee/features/chat`.
 
-export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Promise<{
+export const getAISDKLanguageModelAndOptions = async (config: LanguageModel, userEmail?: string): Promise<{
     model: AISDKLanguageModelV3,
     providerOptions?: Record<string, Record<string, JSONValue>>,
     temperature?: number,
 }> => {
     const { provider, model: modelId } = config;
+    const headers = await resolveLanguageModelHeaders(config.headers, userEmail);
 
     const { model: _model, providerOptions } = await (async (): Promise<{
         model: AISDKLanguageModelV3,
@@ -56,9 +58,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     sessionToken: config.sessionToken
                         ? await getTokenFromConfig(config.sessionToken)
                         : env.AWS_SESSION_TOKEN,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                     // Fallback to the default Node.js credential provider chain if no credentials are provided.
                     // See: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain
                     credentialProvider: !config.accessKeyId && !config.accessKeySecret && !config.sessionToken
@@ -77,10 +77,6 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                 const authToken = config.authToken
                     ? await getTokenFromConfig(config.authToken)
                     : env.ANTHROPIC_AUTH_TOKEN;
-                const headers = config.headers
-                    ? await extractLanguageModelKeyValuePairs(config.headers)
-                    : undefined;
-
                 const anthropic = createAnthropic({
                     baseURL: config.baseUrl,
                     apiKey,
@@ -111,9 +107,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token ? (await getTokenFromConfig(config.token)) : env.AZURE_API_KEY,
                     apiVersion: config.apiVersion,
                     resourceName: config.resourceName ?? env.AZURE_RESOURCE_NAME,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 const reasoningSummary = config.reasoningSummary ?? 'auto';
@@ -131,9 +125,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                 const deepseek = createDeepSeek({
                     baseURL: config.baseUrl,
                     apiKey: config.token ? (await getTokenFromConfig(config.token)) : env.DEEPSEEK_API_KEY,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {
@@ -146,9 +138,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token
                         ? await getTokenFromConfig(config.token)
                         : env.GOOGLE_GENERATIVE_AI_API_KEY,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {
@@ -173,9 +163,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                             keyFilename: await getTokenFromConfig(config.credentials),
                         }
                     } : {}),
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {
@@ -202,9 +190,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                             keyFilename: await getTokenFromConfig(config.credentials),
                         }
                     } : {}),
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {
@@ -217,9 +203,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token
                         ? await getTokenFromConfig(config.token)
                         : env.MISTRAL_API_KEY,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {
@@ -232,9 +216,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token
                         ? await getTokenFromConfig(config.token)
                         : env.OPENAI_API_KEY,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 const reasoningSummary = config.reasoningSummary ?? 'auto';
@@ -255,9 +237,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token
                         ? await getTokenFromConfig(config.token)
                         : undefined,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                     queryParams: config.queryParams
                         ? await extractLanguageModelKeyValuePairs(config.queryParams)
                         : undefined,
@@ -282,9 +262,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token
                         ? await getTokenFromConfig(config.token)
                         : env.OPENROUTER_API_KEY,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {
@@ -297,9 +275,7 @@ export const getAISDKLanguageModelAndOptions = async (config: LanguageModel): Pr
                     apiKey: config.token
                         ? await getTokenFromConfig(config.token)
                         : env.XAI_API_KEY,
-                    headers: config.headers
-                        ? await extractLanguageModelKeyValuePairs(config.headers)
-                        : undefined,
+                    headers,
                 });
 
                 return {