From 0b34115d0b50728ad37d66c4bf29accc4d029723 Mon Sep 17 00:00:00 2001 From: Alexander Miroshnichenko Date: Thu, 19 Nov 2026 19:30:31 +0300 Subject: [PATCH] feat(config): add arbitrary HTTP headers for LLM and MCP Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 8bit Add `headers` at the top level, per specialist (`headers`, `validator_headers`) and per MCP server. Scopes merge per header name; `false` removes an inherited header. `x-opencode-session = true` generates one stable `ses_` per process. An explicit `Authorization` header suppresses `auth_token`. Transport-owned headers are rejected at config load; direct config construction warns and skips them. Signed-off-by: Alexander Miroshnichenko --- README.md | 26 +++- marmel.toml.example | 22 +++- src/agents/runner/fix_loop.rs | 67 ++++++++++ src/agents/runner/mod.rs | 55 +++++++- src/agents/validation.rs | 8 +- src/config.rs | 186 ++++++++++++++++++++++++++ src/llm/client.rs | 19 ++- src/llm/client_tests.rs | 59 +++++++++ src/mcp/client.rs | 9 ++ src/mcp/http.rs | 32 ++++- src/mcp/http_tests.rs | 48 +++++++ src/net/headers.rs | 242 ++++++++++++++++++++++++++++++++++ src/net/mod.rs | 1 + src/orchestrator/delegate.rs | 2 +- src/ui/session_tests.rs | 2 + src/ui/tui/tests_new_ui.rs | 2 + 16 files changed, 767 insertions(+), 13 deletions(-) create mode 100644 src/net/headers.rs diff --git a/README.md b/README.md index e87af3f0d6dc..2d895eb7f675 100644 --- a/README.md +++ b/README.md @@ -216,6 +216,7 @@ Marmel loads the first configuration file found from this list (files are not me | `backend_url` | `http://localhost:8000/v1` | Base URL for OpenAI-compatible chat completions (no trailing slash). | | `backend_urls` | `[]` | Optional list of backend URLs evaluated in priority order (primary -> spillover/fallback). | | `auth_token` | `""` | Optional Bearer token for authentication. | +| `headers` | `{}` | Extra HTTP headers for LLM requests. `x-opencode-session = true` generates one stable session id per process. | | `model` | `qwen-3.8-27b` | Model identifier requested from the backend. | | `temperature` | `0.7` | Sampling temperature. | | `top_p` | `0.9` | Nucleus sampling probability. | @@ -240,8 +241,8 @@ Marmel loads the first configuration file found from this list (files are not me | `[monitoring]` | — | Settings for repetition breakers and token ceilings (`repetition_threshold = 5`, `min_pattern_len = 5`). | | `[orchestration]` | — | Top-level concurrency and delegation settings (`max_recursion_depth = 3`). | | `[orchestration.concurrency]` | _unset_ | Concurrency caps per backend URL and model pair. | -| `[orchestration.specialists.]` | — | Per-role configuration overrides (`model`, `backend_url`, `backend_urls`, `tools`, `mcp_servers`, `reasoning_effort`, `max_validator_iterations`). | -| `[mcp_servers.]` | — | External MCP server registration (`command`, `args`, `env`, `url`, `prompt`, `idle_timeout_secs`, `request_timeout_secs`). | +| `[orchestration.specialists.]` | — | Per-role configuration overrides (`model`, `backend_url`, `backend_urls`, `auth_token`, `headers`, `validator_headers`, `tools`, `mcp_servers`, `reasoning_effort`, `max_validator_iterations`). | +| `[mcp_servers.]` | — | External MCP server registration (`command`, `args`, `env`, `url`, `headers`, `prompt`, `idle_timeout_secs`, `request_timeout_secs`). | ### Example `marmel.toml` @@ -306,6 +307,27 @@ reasoning_effort = "low" validator_reasoning_effort = "minimal" ``` +### Request Headers (`headers`) + +`headers` adds arbitrary HTTP headers to LLM requests. The top level applies to the Manager and every specialist. A specialist entry overrides the top level per header name, and `validator_headers` overrides both for that role's validator. A `false` value removes an inherited header. + +```toml +headers = { x-opencode-session = true, x-api-key = "top-key" } + +[orchestration.specialists.coder] +headers = { x-api-key = "coder-key" } +validator_headers = { x-audit = "1" } + +[mcp_servers.remote] +url = "https://example.com/mcp" +headers = { Authorization = "Bearer mcp-token" } +``` + +- `x-opencode-session = true` generates one `ses_` at process start and sends it on every request. Use a string to pin a fixed value. +- `auth_token` is not sent when an explicit `Authorization` header is set; Marmel logs a warning about the conflict. +- Transport-owned headers (`Content-Type`, `Accept`, `Content-Length`, `Host`, `Connection`, `Transfer-Encoding`, `Mcp-Session-Id`) are rejected at startup. +- MCP `headers` apply to every HTTP/SSE request. A stdio server (`command`) ignores them; use `env` instead. + ### Session Concurrency (`[orchestration.concurrency]`) When running against a local LLM server with limited GPU memory, running multiple subagents, validator loops, and JIT prompt architects in parallel can cause severe queuing and out-of-memory errors. The concurrency table caps simultaneous streams per backend URL and model: diff --git a/marmel.toml.example b/marmel.toml.example index 1da4c66165e7..115bd4f023af 100644 --- a/marmel.toml.example +++ b/marmel.toml.example @@ -14,6 +14,14 @@ backend_url = "http://localhost:8000/v1" # Optional bearer token sent as `Authorization: Bearer `. auth_token = "" +# Optional extra HTTP headers sent with every LLM request (Manager, specialists +# and validators). A per-specialist `headers` entry overrides this map per +# header name; `false` removes an inherited header. `x-opencode-session = true` +# generates one stable `ses_` at process start; use a string to pin a +# fixed value. Transport-owned headers (Content-Type, Accept, Content-Length, +# Host, Connection, Transfer-Encoding, Mcp-Session-Id) are rejected at startup. +# headers = { x-opencode-session = true, x-api-key = "..." } + # Model identifier to send in the chat request. model = "qwen-3.8-27b" @@ -214,6 +222,10 @@ model = "deepseek-v4-flash:cloud" # Optional unique backend and token for coder: # backend_url = "http://localhost:11434/v1" # auth_token = "" +# Optional extra request headers for this specialist and its validator. Both +# merge over the top-level `headers` per header name. +# headers = { x-api-key = "coder-key" } +# validator_headers = { x-audit = "1" } # Optional: set false to disable automated quality-assurance validation # enable_validator = false # Optional unique validator settings for coder's quality assurance: @@ -290,6 +302,10 @@ model = "deepseek-v4-flash:cloud" # `env` is optional and only applies to stdio servers: it sets environment # variables for the spawned process (e.g. API keys the server needs). # +# `headers` is optional and only applies to remote HTTP/SSE servers: it adds +# request headers to every request (`initialize`, `tools/list`, `tools/call`). +# A stdio server ignores `headers`; use `env` there instead. +# # Discovered MCP tools are exposed to agents with a `__` # prefix (e.g. a tool `read_file` from server `filesystem` appears as # `filesystem__read_file`). This prefix prevents name collisions when multiple @@ -298,8 +314,9 @@ model = "deepseek-v4-flash:cloud" # original unprefixed tool name. # # The legal keys of a server table are `command`, `args`, `env`, `url`, -# `prompt`, `idle_timeout_secs` and `request_timeout_secs`: exactly one transport -# per server — `command` wins when both `command` and `url` are set. `prompt` is +# `headers`, `prompt`, `idle_timeout_secs` and `request_timeout_secs`: exactly one +# transport per server — `command` wins when both `command` and `url` are set +# (`headers` are ignored on stdio). `prompt` is # optional free-form text injected into the system prompt of every agent allowed # to use that server (it also accepts the aliases `instructions` and `system_prompt`); # none of the three examples below set it. @@ -313,6 +330,7 @@ args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] # Example 2 — remote/external HTTP/SSE server (reached over the network). [mcp_servers.remote] url = "https://example.com/mcp" +# headers = { Authorization = "Bearer ...", x-opencode-session = true } # Example 3 — the offline reference library built in this workspace, registered # under the server name `kiwix` (a legal name: `[A-Za-z0-9_-]+`, no `__`, and it diff --git a/src/agents/runner/fix_loop.rs b/src/agents/runner/fix_loop.rs index 2d369bc2e8be..a1e072214e3f 100644 --- a/src/agents/runner/fix_loop.rs +++ b/src/agents/runner/fix_loop.rs @@ -715,6 +715,27 @@ pub fn resolve_validator_backend( (backend, token, model, reasoning_effort) } +/// Resolve a validator pass's request headers: top-level +/// [`crate::config::Config::headers`], then `[specialists.validator].headers`, +/// then the audited specialist's `validator_headers`. +pub fn resolve_validator_headers( + cfg: &crate::config::Config, + specialist: crate::agents::Agent, +) -> reqwest::header::HeaderMap { + let mut layers = vec![&cfg.headers]; + if let Some(validator_cfg) = cfg + .orchestration + .specialists + .get(crate::agents::Agent::Validator.as_str()) + { + layers.push(&validator_cfg.headers); + } + if let Some(specialist_cfg) = cfg.orchestration.specialists.get(specialist.as_str()) { + layers.push(&specialist_cfg.validator_headers); + } + crate::net::headers::resolve(&layers) +} + /// Shared tool-dispatch core: monitor intervention check → cancellation check /// → `dispatch_for_async_with_engine`. Returns `(content, execution_succeeded)` /// where `content` starts with `"ERROR: "` on failure. @@ -1436,6 +1457,7 @@ pub fn register_loop_worker( mod tests { use super::{ append_tool_result, inject_worker_notices_at_turn_start, inject_worker_notices_mid_turn, + resolve_validator_headers, }; use crate::manager::{ContextEngine, ContextEngineFactory}; use crate::orchestrator::notice::{TEST_NOTICE_MUTEX, has_worker_inbox, worker_inbox_len}; @@ -2786,4 +2808,49 @@ mod tests { ); } } + + /// Validator headers merge top level → `[specialists.validator]` → the + /// audited specialist's `validator_headers`, per header name. + #[test] + fn validator_headers_merge_in_scope_order() { + use crate::config::{Config, SpecialistConfig}; + use crate::net::headers::HeaderSpec; + + let mut cfg = Config::default(); + cfg.headers + .insert("x-scope".into(), HeaderSpec::Text("top".into())); + cfg.headers + .insert("x-top".into(), HeaderSpec::Text("kept".into())); + + let mut validator = SpecialistConfig::default(); + validator + .headers + .insert("x-scope".into(), HeaderSpec::Text("validator".into())); + cfg.orchestration + .specialists + .insert("validator".into(), validator); + + let mut coder = SpecialistConfig::default(); + coder + .validator_headers + .insert("x-scope".into(), HeaderSpec::Text("coder-validator".into())); + coder + .validator_headers + .insert("x-top".into(), HeaderSpec::Flag(false)); + cfg.orchestration.specialists.insert("coder".into(), coder); + + let headers = resolve_validator_headers(&cfg, crate::agents::Agent::Coder); + assert_eq!( + headers + .get("x-scope") + .expect("header present") + .to_str() + .expect("valid header value"), + "coder-validator" + ); + assert!( + headers.get("x-top").is_none(), + "the innermost scope removed the inherited header" + ); + } } diff --git a/src/agents/runner/mod.rs b/src/agents/runner/mod.rs index fafa56960738..301323e9889a 100644 --- a/src/agents/runner/mod.rs +++ b/src/agents/runner/mod.rs @@ -104,6 +104,19 @@ pub fn resolve_specialist_backend( (backend, auth_token, model) } +/// Resolve a specialist's request headers: top-level [`crate::config::Config::headers`] +/// overridden per header name by `[specialists.].headers`. +pub fn resolve_specialist_headers( + cfg: &crate::config::Config, + agent: Agent, +) -> reqwest::header::HeaderMap { + let mut layers = vec![&cfg.headers]; + if let Some(specialist_cfg) = cfg.orchestration.specialists.get(agent.as_str()) { + layers.push(&specialist_cfg.headers); + } + crate::net::headers::resolve(&layers) +} + pub(crate) async fn try_run_specialist_live( agent: Agent, ctx: &IsolatedContext, @@ -122,7 +135,8 @@ pub(crate) async fn try_run_specialist_live( if backend_url.is_empty() { return None; } - let client = crate::llm::ChatClient::new_with_token(&backend_url, &model, &auth_token); + let client = crate::llm::ChatClient::new_with_token(&backend_url, &model, &auth_token) + .with_headers(resolve_specialist_headers(&cfg, agent)); // Call class for this delegation, installed before the turn starts and // discharged when it returns. This is the point where the delegation's // `(backend_url, model)` pair is resolved, so the pool's gate in @@ -146,3 +160,42 @@ pub(crate) async fn try_run_specialist_live( }; Some(res) } + +#[cfg(test)] +mod tests { + use super::resolve_specialist_headers; + use crate::agents::Agent; + use crate::config::{Config, SpecialistConfig}; + use crate::net::headers::HeaderSpec; + + /// Specialist headers override the top-level map per header name, and + /// `false` removes an inherited header. + #[test] + fn specialist_headers_override_the_top_level_map() { + let mut cfg = Config::default(); + cfg.headers + .insert("x-scope".into(), HeaderSpec::Text("top".into())); + cfg.headers + .insert("x-remove".into(), HeaderSpec::Text("top".into())); + + let mut coder = SpecialistConfig::default(); + coder + .headers + .insert("x-scope".into(), HeaderSpec::Text("coder".into())); + coder + .headers + .insert("x-remove".into(), HeaderSpec::Flag(false)); + cfg.orchestration.specialists.insert("coder".into(), coder); + + let headers = resolve_specialist_headers(&cfg, Agent::Coder); + assert_eq!( + headers + .get("x-scope") + .expect("header present") + .to_str() + .expect("valid header value"), + "coder" + ); + assert!(headers.get("x-remove").is_none()); + } +} diff --git a/src/agents/validation.rs b/src/agents/validation.rs index d472fd1ffb22..47cc206e7167 100644 --- a/src/agents/validation.rs +++ b/src/agents/validation.rs @@ -12,7 +12,7 @@ use crate::agents::Agent; use crate::agents::runner::fix_loop::{ FixLoopBounds, FixLoopResult, LoopParams, assemble_tools, register_loop_worker, - resolve_validator_backend_with_lease, run_fix_loop, + resolve_validator_backend_with_lease, resolve_validator_headers, run_fix_loop, }; use crate::markers::{has_failure_verdict_cue, is_failure_verdict_word}; use crate::tool_names::is_leave_verdict_tool_name; @@ -408,7 +408,8 @@ async fn run_automated_validation_inner( // correct: a different model server has its own slots, so it gets its own pool. let (backend, auth, validator_model, validator_reasoning_effort, _val_lease) = resolve_validator_backend_with_lease(cfg, agent); - let val_client = crate::llm::ChatClient::new_with_token(&backend, &validator_model, &auth); + let val_client = crate::llm::ChatClient::new_with_token(&backend, &validator_model, &auth) + .with_headers(resolve_validator_headers(cfg, agent)); let brief = format!( "Task Brief:\n{}\n\nSpecialist Deliverable:\n{}\n\n\ @@ -619,7 +620,8 @@ async fn run_plan_validation_inner( // `[specialists.validator]` override points it at another endpoint/model. let (backend, auth, validator_model, validator_reasoning_effort, _val_lease) = resolve_validator_backend_with_lease(cfg, Agent::Planner); - let val_client = crate::llm::ChatClient::new_with_token(&backend, &validator_model, &auth); + let val_client = crate::llm::ChatClient::new_with_token(&backend, &validator_model, &auth) + .with_headers(resolve_validator_headers(cfg, Agent::Planner)); let brief = format!( "Proposed Execution Plan:\n```markdown\n{}\n```\n\n\ diff --git a/src/config.rs b/src/config.rs index ef6cf958cc28..ec6710598010 100644 --- a/src/config.rs +++ b/src/config.rs @@ -5,6 +5,8 @@ use serde::{Deserialize, Serialize}; use std::collections::{BTreeMap, HashMap}; use std::path::PathBuf; +use crate::net::headers::{HeaderSpecs, sets_header, validate as validate_headers}; + /// Default delegation depth bound. pub const DEFAULT_MAX_RECURSION_DEPTH: usize = 3; @@ -220,6 +222,10 @@ pub struct SpecialistConfig { pub backend_urls: Vec, /// Optional auth token override for this specialist. pub auth_token: Option, + /// Optional request-header overrides for this specialist's backend. Merged + /// over the top-level [`Config::headers`] per header name; `false` removes an + /// inherited header. + pub headers: HeaderSpecs, /// Optional model override for this specialist's validator. pub validator_model: Option, /// Optional backend URL override for this specialist's validator. @@ -229,6 +235,9 @@ pub struct SpecialistConfig { pub validator_backend_urls: Vec, /// Optional auth token override for this specialist's validator. pub validator_auth_token: Option, + /// Optional request-header overrides for this specialist's validator. Merged + /// over the top-level headers and `[specialists.validator].headers`. + pub validator_headers: HeaderSpecs, /// Optional reasoning-effort override for this specialist's validator /// (free-form pass-through; backends use different vocabularies). pub validator_reasoning_effort: Option, @@ -361,6 +370,9 @@ pub struct Config { #[serde(default)] pub backend_urls: Vec, pub auth_token: String, + /// Arbitrary request headers for the LLM backend. `x-opencode-session = true` + /// generates one stable session id for the whole process. + pub headers: HeaderSpecs, pub model: String, pub temperature: f32, pub top_p: f32, @@ -467,6 +479,7 @@ impl Default for Config { backend_url: "http://localhost:8000/v1".to_string(), backend_urls: Vec::new(), auth_token: String::new(), + headers: HeaderSpecs::new(), model: "qwen-3.8-27b".to_string(), temperature: 0.7, top_p: 0.9, @@ -936,10 +949,61 @@ pub fn load(explicit_path: Option<&str>) -> Result { std::env::var(SESSION_COMMIT_MIN_MS_ENV).ok(), ); + validate_headers_config(&cfg)?; cfg.expand_paths(); Ok(cfg) } +/// Reject transport-owned headers and flag misuse at startup, before any +/// request is built. Direct `Config` construction (tests) skips this; the +/// resolvers degrade invalid entries to a warning instead of panicking. +fn validate_headers_config(cfg: &Config) -> Result<()> { + validate_headers(&cfg.headers, "headers").map_err(anyhow::Error::msg)?; + warn_auth_conflict(&cfg.headers, &cfg.auth_token, "headers"); + + let validator_cfg = cfg.orchestration.specialists.get("validator"); + for (role, specialist) in &cfg.orchestration.specialists { + validate_headers(&specialist.headers, &format!("specialist '{role}' headers")) + .map_err(anyhow::Error::msg)?; + let effective_token = specialist.auth_token.as_deref().unwrap_or(&cfg.auth_token); + warn_auth_conflict( + &specialist.headers, + effective_token, + &format!("specialist '{role}' headers"), + ); + + validate_headers( + &specialist.validator_headers, + &format!("specialist '{role}' validator_headers"), + ) + .map_err(anyhow::Error::msg)?; + let effective_validator_token = specialist + .validator_auth_token + .as_deref() + .or_else(|| validator_cfg.and_then(|vc| vc.auth_token.as_deref())) + .unwrap_or(&cfg.auth_token); + warn_auth_conflict( + &specialist.validator_headers, + effective_validator_token, + &format!("specialist '{role}' validator_headers"), + ); + } + + for (name, server) in &cfg.mcp_servers { + validate_headers(&server.headers, &format!("mcp server '{name}' headers")) + .map_err(anyhow::Error::msg)?; + } + Ok(()) +} + +fn warn_auth_conflict(headers: &HeaderSpecs, token: &str, scope: &str) { + if !token.is_empty() && sets_header(headers, "authorization") { + tracing::warn!( + "{scope}: both `auth_token` and an explicit `Authorization` header are set; the header wins" + ); + } +} + /// Tri-state reading of a `MARMEL_*` boolean: `1`/`true`/`yes`/`on` ⇒ `Some(true)`, /// `0`/`false`/`no`/`off` ⇒ `Some(false)`, anything else (including unset and /// unparseable junk) ⇒ `None`, which means "leave the file/default value alone". @@ -1040,6 +1104,7 @@ struct PartialConfig { #[serde(default)] pub backend_urls: Vec, pub auth_token: Option, + pub headers: Option, pub model: Option, pub temperature: Option, pub top_p: Option, @@ -1136,6 +1201,9 @@ fn merge(mut base: Config, partial: PartialConfig) -> Config { { base.auth_token = v; } + if let Some(v) = partial.headers { + base.headers = v; + } if let Some(v) = partial.model && !v.is_empty() { @@ -1397,6 +1465,7 @@ pub(crate) fn sandbox_env_test_lock() -> std::sync::MutexGuard<'static, ()> { #[cfg(test)] mod tests { use super::*; + use crate::net::headers::HeaderSpec; #[test] fn test_orchestr_config_default_depth() { @@ -1447,6 +1516,123 @@ mod tests { assert!(validator.tools.iter().any(|t| t == "gedcom__*")); } + // ------------------------------------------------------------- headers + // + // `headers` is a map of header name to either a literal string or the bool + // flag `true` (generate the process session id) / `false` (remove an + // inherited header). Scopes are top level, per specialist, and per + // specialist validator; `validate_headers_config` is the startup gate that + // refuses transport-owned names and flag misuse. + + #[test] + fn headers_parse_at_every_scope() { + let cfg = merged( + r#" + headers = { x-api-key = "top", x-opencode-session = true } + [mcp_servers.auth] + url = "https://example.test/mcp" + headers = { Authorization = "Bearer mcp" } + [orchestration.specialists.coder] + headers = { x-api-key = "coder", x-remove = false } + validator_headers = { x-validator = "yes" } + "#, + ); + + assert_eq!( + cfg.headers.get("x-api-key"), + Some(&HeaderSpec::Text("top".to_string())) + ); + assert_eq!( + cfg.headers.get("x-opencode-session"), + Some(&HeaderSpec::Flag(true)) + ); + + let server = cfg.mcp_servers.get("auth").expect("mcp server"); + assert_eq!( + server.headers.get("Authorization"), + Some(&HeaderSpec::Text("Bearer mcp".to_string())) + ); + + let coder = cfg + .orchestration + .specialists + .get("coder") + .expect("coder present"); + assert_eq!( + coder.headers.get("x-api-key"), + Some(&HeaderSpec::Text("coder".to_string())) + ); + assert_eq!( + coder.headers.get("x-remove"), + Some(&HeaderSpec::Flag(false)) + ); + assert_eq!( + coder.validator_headers.get("x-validator"), + Some(&HeaderSpec::Text("yes".to_string())) + ); + } + + #[test] + fn headers_merge_replaces_the_whole_top_level_map() { + let mut base = Config::default(); + base.headers + .insert("x-keep".to_string(), HeaderSpec::Text("base".to_string())); + let partial: PartialConfig = + toml::from_str("headers = { x-new = \"project\" }\n").expect("parses"); + + let cfg = merge(base, partial); + assert_eq!( + cfg.headers.get("x-new"), + Some(&HeaderSpec::Text("project".to_string())) + ); + assert!( + cfg.headers.get("x-keep").is_none(), + "a re-declared top-level map replaces the whole map, like every other top-level key" + ); + } + + #[test] + fn headers_validation_accepts_valid_configuration() { + let cfg = merged( + r#" + headers = { x-api-key = "top", x-opencode-session = true } + [mcp_servers.auth] + url = "https://example.test/mcp" + headers = { Authorization = "Bearer mcp" } + [orchestration.specialists.coder] + headers = { x-remove = false } + validator_headers = { x-validator = "yes" } + "#, + ); + assert!(validate_headers_config(&cfg).is_ok()); + } + + #[test] + fn headers_validation_rejects_reserved_names_and_flag_misuse() { + let reserved = merged("headers = { Content-Type = \"text/plain\" }\n"); + assert!(validate_headers_config(&reserved).is_err()); + + let mcp_reserved = merged( + r#" + [mcp_servers.auth] + url = "https://example.test/mcp" + headers = { Mcp-Session-Id = "fixed" } + "#, + ); + assert!(validate_headers_config(&mcp_reserved).is_err()); + + let wrong_flag = merged("headers = { x-api-key = true }\n"); + assert!(validate_headers_config(&wrong_flag).is_err()); + + let specialist_reserved = merged( + r#" + [orchestration.specialists.coder] + validator_headers = { Host = "example.test" } + "#, + ); + assert!(validate_headers_config(&specialist_reserved).is_err()); + } + #[test] fn orchestration_absent_keeps_default() { let toml_str = "backend_url = \"http://localhost:9000/v1\"\n"; diff --git a/src/llm/client.rs b/src/llm/client.rs index 67e0c3e7bf13..a854960446fc 100644 --- a/src/llm/client.rs +++ b/src/llm/client.rs @@ -4,6 +4,7 @@ use crate::orchestrator::pool; use crate::types::{ChatChunk, ChatRequest}; use anyhow::Result; use eventsource_stream::Eventsource; +use reqwest::header::HeaderMap; // Only for the trait methods (`source()`) needed to walk a reqwest build // failure's cause chain; kept anonymous so it cannot shadow the `Error` derive // macro imported from `thiserror` below. @@ -247,6 +248,9 @@ impl StreamedReply { pub struct ChatClient { backend_url: String, auth_token: String, + /// Configured request headers. An explicit `Authorization` here suppresses + /// `auth_token`, so the header wins instead of producing two credentials. + headers: HeaderMap, model: String, initial_timeout_secs: u64, stall_timeout_secs: u64, @@ -689,6 +693,7 @@ impl ChatClient { Self { backend_url: cfg.backend_url.clone(), auth_token: cfg.auth_token.clone(), + headers: crate::net::headers::resolve(&[&cfg.headers]), model: cfg.model.clone(), initial_timeout_secs: INITIAL_RESPONSE_WATCHDOG_SECS, stall_timeout_secs: INTER_CHUNK_WATCHDOG_SECS, @@ -702,6 +707,7 @@ impl ChatClient { Self { backend_url: backend_url.into(), auth_token: String::new(), + headers: HeaderMap::new(), model: model.into(), initial_timeout_secs: INITIAL_RESPONSE_WATCHDOG_SECS, stall_timeout_secs: INTER_CHUNK_WATCHDOG_SECS, @@ -719,6 +725,7 @@ impl ChatClient { Self { backend_url: backend_url.into(), auth_token: auth_token.into(), + headers: HeaderMap::new(), model: model.into(), initial_timeout_secs: INITIAL_RESPONSE_WATCHDOG_SECS, stall_timeout_secs: INTER_CHUNK_WATCHDOG_SECS, @@ -734,6 +741,12 @@ impl ChatClient { self } + /// Attach request headers resolved from configuration. + pub fn with_headers(mut self, headers: HeaderMap) -> Self { + self.headers = headers; + self + } + pub fn with_initial_timeout_secs(mut self, secs: u64) -> Self { self.initial_timeout_secs = secs; self @@ -1183,7 +1196,11 @@ impl ChatClient { let req_start = std::time::Instant::now(); let mut builder = client.post(&url).json(&req_body); - if !self.auth_token.is_empty() { + for (name, value) in &self.headers { + builder = builder.header(name, value); + } + if !self.auth_token.is_empty() && !self.headers.contains_key(reqwest::header::AUTHORIZATION) + { builder = builder.bearer_auth(&self.auth_token); } diff --git a/src/llm/client_tests.rs b/src/llm/client_tests.rs index 7b92e156e882..bed827d91f35 100644 --- a/src/llm/client_tests.rs +++ b/src/llm/client_tests.rs @@ -1788,3 +1788,62 @@ fn test_construction_verdict_matches_the_startup_probe() { } } } + +/// Configured headers reach the wire through [`ChatClient::from_config`], and an +/// explicit `Authorization` header suppresses `auth_token`. +#[tokio::test] +async fn test_configured_headers_reach_the_wire_and_explicit_authorization_wins() { + use crate::net::headers::{HeaderSpec, HeaderSpecs, generated_session_id}; + use wiremock::matchers::{method, path}; + use wiremock::{Mock, MockServer, Request, ResponseTemplate}; + + let server = MockServer::start().await; + let seen: Arc, Option)>>> = Arc::new(Mutex::new(None)); + let recorder = seen.clone(); + Mock::given(method("POST")) + .and(path("/chat/completions")) + .respond_with(move |req: &Request| { + let header = |name: &str| { + req.headers + .get(name) + .and_then(|value| value.to_str().ok()) + .map(str::to_string) + }; + *recorder.lock().expect("recorder lock") = + Some((header("x-opencode-session"), header("authorization"))); + ResponseTemplate::new(200).set_body_string(sse_body("ok")) + }) + .mount(&server) + .await; + + let headers: HeaderSpecs = [ + ("x-opencode-session".to_string(), HeaderSpec::Flag(true)), + ( + "Authorization".to_string(), + HeaderSpec::Text("Bearer explicit".to_string()), + ), + ] + .into_iter() + .collect(); + let cfg = crate::config::Config { + backend_url: server.uri(), + auth_token: "configured-token".to_string(), + headers, + model: "test-model".to_string(), + ..Default::default() + }; + + let reply = ChatClient::from_config(&cfg) + .chat(&request()) + .await + .unwrap(); + assert_eq!(reply.content, "ok"); + + let (session, authorization) = seen + .lock() + .expect("recorder lock") + .clone() + .expect("the request must have reached the mock"); + assert_eq!(session.as_deref(), Some(generated_session_id())); + assert_eq!(authorization.as_deref(), Some("Bearer explicit")); +} diff --git a/src/mcp/client.rs b/src/mcp/client.rs index 71d66876007e..472b2657316d 100644 --- a/src/mcp/client.rs +++ b/src/mcp/client.rs @@ -20,6 +20,7 @@ use super::http::{DEFAULT_MCP_REQUEST_TIMEOUT, HttpSseConnection}; use super::protocol::{ self, JsonRpcNotification, JsonRpcRequest, JsonRpcTransport, RequestIds, decode_reply, }; +use crate::net::headers::HeaderSpecs; /// Default idle duration before closing an inactive MCP connection (5 minutes). pub const DEFAULT_MCP_IDLE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(300); @@ -36,6 +37,9 @@ pub struct McpServerConfig { pub env: HashMap, /// Remote URL endpoint (for HTTP/SSE transport). pub url: Option, + /// Request headers for the HTTP/SSE transport. Ignored for stdio servers, + /// which use `env` instead. + pub headers: HeaderSpecs, /// Optional prompt or usage instructions injected into the system prompt of /// every agent allowed to use this MCP server. #[serde(alias = "instructions", alias = "system_prompt")] @@ -871,6 +875,11 @@ impl McpManager { if cfg.command.is_none() && cfg.url.is_none() { return Ok(false); } + if cfg.command.is_some() && !cfg.headers.is_empty() { + tracing::warn!( + "MCP server '{name}' uses stdio (`command`); `headers` are ignored — use `env`" + ); + } let (client, instructions) = connect_client(name, cfg).await?; diff --git a/src/mcp/http.rs b/src/mcp/http.rs index 9af874b628e5..1c3a32bb268e 100644 --- a/src/mcp/http.rs +++ b/src/mcp/http.rs @@ -23,9 +23,12 @@ use anyhow::{Context, Result, anyhow}; use eventsource_stream::Eventsource; +use reqwest::header::HeaderMap; use serde_json::Value; use std::time::{Duration, Instant}; +use crate::net::headers::HeaderSpecs; + use super::client::{McpServerConfig, McpTool}; use super::protocol::{ self, JsonRpcNotification, JsonRpcRequest, JsonRpcTransport, RequestIds, decode_reply, @@ -235,6 +238,8 @@ pub struct HttpSseConnection { server_name: String, endpoint: String, client: reqwest::Client, + /// Configured request headers, resolved once at connect time. + headers: HeaderMap, session_id: Option, /// The protocol layer's monotonic JSON-RPC id allocator /// ([`super::protocol::RequestIds`]); the transport only carries it. @@ -358,7 +363,7 @@ impl HttpSseConnection { .as_ref() .ok_or_else(|| anyhow!("missing `url` for HTTP MCP server '{server_name}'"))?; - Self::establish(server_name, url, cfg.request_timeout()).await + Self::establish(server_name, url, &cfg.headers, cfg.request_timeout()).await } /// Test seam: same handshake with an explicit request deadline, so the @@ -370,7 +375,19 @@ impl HttpSseConnection { url: &str, request_timeout: Duration, ) -> Result { - Self::establish(server_name, url, request_timeout).await + let headers = HeaderSpecs::new(); + Self::establish(server_name, url, &headers, request_timeout).await + } + + /// Test seam with configured headers. + #[cfg(test)] + pub(crate) async fn connect_with_timeout_and_headers( + server_name: &str, + url: &str, + headers: &HeaderSpecs, + request_timeout: Duration, + ) -> Result { + Self::establish(server_name, url, headers, request_timeout).await } #[cfg(test)] @@ -380,7 +397,12 @@ impl HttpSseConnection { /// Build the reqwest client through the shared builder and run the /// `initialize` handshake through the shared protocol layer. - async fn establish(server_name: &str, url: &str, request_timeout: Duration) -> Result { + async fn establish( + server_name: &str, + url: &str, + headers: &HeaderSpecs, + request_timeout: Duration, + ) -> Result { let client = build_http_client_with(http_client_options(request_timeout)) .with_context(|| format!("failed to build HTTP client for '{server_name}'"))?; @@ -388,6 +410,7 @@ impl HttpSseConnection { server_name: server_name.to_string(), endpoint: url.to_string(), client, + headers: crate::net::headers::resolve(&[headers]), session_id: None, request_ids: RequestIds::new(), request_timeout, @@ -466,6 +489,9 @@ impl HttpSseConnection { if let Some(sid) = &self.session_id { builder = builder.header("Mcp-Session-Id", sid); } + for (name, value) in &self.headers { + builder = builder.header(name, value); + } builder } diff --git a/src/mcp/http_tests.rs b/src/mcp/http_tests.rs index eb123c5d8732..cb3e0eede761 100644 --- a/src/mcp/http_tests.rs +++ b/src/mcp/http_tests.rs @@ -373,6 +373,54 @@ mod tests { assert_eq!(sent[2], JsonRpcRequest::tools_list(1).body().expect("body")); } + /// Configured headers travel on every HTTP request of the transport — the + /// `initialize` handshake, the notification and `tools/list` alike. + #[tokio::test] + async fn configured_headers_travel_on_every_http_request() { + use crate::net::headers::{HeaderSpec, HeaderSpecs}; + + let server = MockServer::start().await; + let (router, _all, _calls) = endpoint_router(EndpointBehaviour::JsonToolsList); + let seen: Arc>>> = Arc::new(Mutex::new(Vec::new())); + let recorder = seen.clone(); + Mock::given(method("POST")) + .and(path("/mcp")) + .respond_with(move |req: &Request| { + recorder.lock().expect("recorder lock").push( + req.headers + .get("x-api-key") + .and_then(|value| value.to_str().ok()) + .map(str::to_string), + ); + router(req) + }) + .mount(&server) + .await; + + let headers: HeaderSpecs = [( + "x-api-key".to_string(), + HeaderSpec::Text("secret".to_string()), + )] + .into_iter() + .collect(); + let mut conn = HttpSseConnection::connect_with_timeout_and_headers( + "mock-server", + &format!("{}/mcp", server.uri()), + &headers, + Duration::from_secs(5), + ) + .await + .expect("initialize handshake should succeed"); + conn.list_tools().await.expect("tools/list"); + + let seen = seen.lock().expect("recorder lock").clone(); + assert_eq!(seen.len(), 3, "initialize + notification + tools/list"); + assert!( + seen.iter().all(|value| value.as_deref() == Some("secret")), + "every request must carry the configured header, got {seen:?}" + ); + } + /// A `tools/call` envelope carries the protocol layer's param shape. #[tokio::test] async fn http_call_tool_envelope_carries_the_protocol_params() { diff --git a/src/net/headers.rs b/src/net/headers.rs new file mode 100644 index 000000000000..1f73b723ae74 --- /dev/null +++ b/src/net/headers.rs @@ -0,0 +1,242 @@ +//! Arbitrary request headers from configuration, shared by the LLM chat client +//! and the MCP HTTP/SSE transport. +//! +//! A configured value is either a literal string or a flag: +//! * `true` on [`SESSION_HEADER`] asks the process to mint one stable +//! `ses_` for the whole run and send it on every request; +//! * `false` removes a header inherited from a broader scope. +//! +//! Reserved transport headers are refused at config load, never silently +//! overridden. + +use std::collections::BTreeMap; +use std::sync::OnceLock; + +use reqwest::header::{HeaderMap, HeaderName, HeaderValue as HttpHeaderValue}; +use serde::{Deserialize, Serialize}; + +/// Stable per-run session header understood by the OpenCode Console gateway. +pub const SESSION_HEADER: &str = "x-opencode-session"; + +/// Header values accepted from TOML. +pub type HeaderSpecs = BTreeMap; + +/// One configured header value. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(untagged)] +pub enum HeaderSpec { + /// A literal header value. + Text(String), + /// `true` generates the process session id; `false` removes the header. + Flag(bool), +} + +/// Headers the transports own and a user must not override. +const RESERVED_HEADERS: &[&str] = &[ + "accept", + "connection", + "content-length", + "content-type", + "host", + "mcp-session-id", + "transfer-encoding", +]; + +/// The process-wide generated session id. +/// +/// Minted on first use, so every configured `true` value and every request +/// shares one stable id for the life of the process. +pub fn generated_session_id() -> &'static str { + static ID: OnceLock = OnceLock::new(); + ID.get_or_init(|| format!("ses_{}", uuid::Uuid::new_v4().simple())) +} + +/// `true` when `name` is a transport-owned header. +pub fn is_reserved(name: &str) -> bool { + RESERVED_HEADERS + .iter() + .any(|reserved| reserved.eq_ignore_ascii_case(name)) +} + +/// `true` when `specs` sets `name` to anything other than an explicit removal. +pub fn sets_header(specs: &HeaderSpecs, name: &str) -> bool { + specs.iter().any(|(key, spec)| { + key.eq_ignore_ascii_case(name) && !matches!(spec, HeaderSpec::Flag(false)) + }) +} + +/// Validate one configuration scope, naming it in every error. +pub fn validate(specs: &HeaderSpecs, context: &str) -> Result<(), String> { + for (name, spec) in specs { + let header_name = HeaderName::from_bytes(name.as_bytes()) + .map_err(|err| format!("{context}: invalid header name {name:?}: {err}"))?; + if is_reserved(header_name.as_str()) { + return Err(format!( + "{context}: header {name:?} is managed by the transport and cannot be overridden" + )); + } + match spec { + HeaderSpec::Text(value) => { + value.parse::().map_err(|err| { + format!("{context}: invalid value for header {name:?}: {err}") + })?; + } + HeaderSpec::Flag(true) if header_name.as_str() != SESSION_HEADER => { + return Err(format!( + "{context}: `true` is only supported for `{SESSION_HEADER}`; use a string for {name:?}" + )); + } + HeaderSpec::Flag(_) => {} + } + } + Ok(()) +} + +/// Merge scopes left-to-right and resolve each value into a concrete header. +/// +/// Later scopes win per header name; `false` removes a header inherited from an +/// earlier scope. Invalid entries are skipped with a warning: normal startup +/// rejects them through [`validate`], and direct `Config` construction (tests) +/// must not panic. +pub fn resolve(layers: &[&HeaderSpecs]) -> HeaderMap { + let mut map = HeaderMap::new(); + for layer in layers { + for (name, spec) in *layer { + let Ok(header_name) = HeaderName::from_bytes(name.as_bytes()) else { + tracing::warn!("ignoring invalid configured header name {name:?}"); + continue; + }; + if is_reserved(header_name.as_str()) { + tracing::warn!( + "ignoring configured header {name:?}: it is managed by the transport" + ); + continue; + } + match spec { + HeaderSpec::Text(value) => match value.parse::() { + Ok(value) => { + map.insert(header_name, value); + } + Err(err) => { + tracing::warn!( + "ignoring invalid value for configured header {name:?}: {err}" + ); + } + }, + HeaderSpec::Flag(true) if header_name.as_str() == SESSION_HEADER => { + if let Ok(value) = generated_session_id().parse::() { + map.insert(header_name, value); + } + } + HeaderSpec::Flag(true) => { + tracing::warn!( + "ignoring `true` for configured header {name:?}: only `{SESSION_HEADER}` supports it" + ); + } + HeaderSpec::Flag(false) => { + map.remove(&header_name); + } + } + } + } + map +} + +#[cfg(test)] +mod tests { + use super::*; + + fn specs(pairs: &[(&str, HeaderSpec)]) -> HeaderSpecs { + pairs + .iter() + .map(|(name, spec)| ((*name).to_string(), spec.clone())) + .collect() + } + + fn value<'a>(headers: &'a HeaderMap, name: &str) -> &'a str { + headers.get(name).expect("header present").to_str().unwrap() + } + + #[test] + fn later_scopes_override_and_false_removes() { + let base = specs(&[ + ("x-keep", HeaderSpec::Text("one".into())), + ("x-replace", HeaderSpec::Text("old".into())), + ("x-remove", HeaderSpec::Text("gone".into())), + ]); + let over = specs(&[ + ("x-replace", HeaderSpec::Text("new".into())), + ("x-remove", HeaderSpec::Flag(false)), + ]); + + let headers = resolve(&[&base, &over]); + assert_eq!(value(&headers, "x-keep"), "one"); + assert_eq!(value(&headers, "x-replace"), "new"); + assert!(headers.get("x-remove").is_none()); + } + + #[test] + fn session_flag_resolves_to_the_process_id() { + let headers = resolve(&[&specs(&[(SESSION_HEADER, HeaderSpec::Flag(true))])]); + assert_eq!(value(&headers, SESSION_HEADER), generated_session_id()); + assert!(generated_session_id().starts_with("ses_")); + assert_eq!(generated_session_id(), generated_session_id()); + } + + #[test] + fn validate_accepts_text_flags_removals_and_empty_values() { + let valid = specs(&[ + (SESSION_HEADER, HeaderSpec::Flag(true)), + ("x-api-key", HeaderSpec::Text("secret".into())), + ("x-empty", HeaderSpec::Text(String::new())), + ("x-remove", HeaderSpec::Flag(false)), + ]); + assert!(validate(&valid, "test headers").is_ok()); + } + + #[test] + fn validate_rejects_reserved_names_and_bool_misuse() { + let reserved = specs(&[("Content-Type", HeaderSpec::Text("text/plain".into()))]); + assert!(validate(&reserved, "test headers").is_err()); + + let wrong_flag = specs(&[("x-api-key", HeaderSpec::Flag(true))]); + assert!(validate(&wrong_flag, "test headers").is_err()); + + let bad_name = specs(&[("bad header", HeaderSpec::Text("x".into()))]); + assert!(validate(&bad_name, "test headers").is_err()); + } + + #[test] + fn empty_literal_is_a_value_not_a_removal() { + let base = specs(&[("x-empty", HeaderSpec::Text("inherited".into()))]); + let over = specs(&[("x-empty", HeaderSpec::Text(String::new()))]); + + let headers = resolve(&[&base, &over]); + assert_eq!(value(&headers, "x-empty"), ""); + } + + /// The startup gate rejects reserved names; a directly constructed `Config` + /// skips that gate, so resolution must warn and skip them instead of + /// emitting a transport-owned header. + #[test] + fn reserved_headers_are_skipped_during_resolution() { + let headers = resolve(&[&specs(&[ + ("Content-Type", HeaderSpec::Text("text/plain".into())), + ("Mcp-Session-Id", HeaderSpec::Text("fixed".into())), + ("x-ok", HeaderSpec::Text("yes".into())), + ])]); + + assert!(headers.get("content-type").is_none()); + assert!(headers.get("mcp-session-id").is_none()); + assert_eq!(value(&headers, "x-ok"), "yes"); + } + + #[test] + fn sets_header_ignores_explicit_removal() { + let removal = specs(&[("Authorization", HeaderSpec::Flag(false))]); + assert!(!sets_header(&removal, "authorization")); + + let set = specs(&[("Authorization", HeaderSpec::Text("Bearer x".into()))]); + assert!(sets_header(&set, "authorization")); + } +} diff --git a/src/net/mod.rs b/src/net/mod.rs index 2b9d66001235..74e895dda87b 100644 --- a/src/net/mod.rs +++ b/src/net/mod.rs @@ -4,6 +4,7 @@ //! hook), the generic retry-with-backoff policy, and the reqwest client //! builder. +pub mod headers; pub mod http; pub mod retry; pub mod sse; diff --git a/src/orchestrator/delegate.rs b/src/orchestrator/delegate.rs index 97746036c4eb..e5950813a8d8 100644 --- a/src/orchestrator/delegate.rs +++ b/src/orchestrator/delegate.rs @@ -106,7 +106,7 @@ pub fn handle_delegate_task(args: &serde_json::Value) -> Result std::sync::Arc std::sync::Arc { args: Vec::new(), env: std::collections::HashMap::new(), url: None, + headers: Default::default(), prompt: None, ..Default::default() }, @@ -5307,6 +5308,7 @@ fn the_configured_server_count_is_seeded_from_the_config_once() { args: Vec::new(), env: std::collections::HashMap::new(), url: None, + headers: Default::default(), prompt: None, ..Default::default() }, -- 2.54.0