diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json index 8745602931..7c49df6300 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json @@ -17556,6 +17556,20 @@ } ] }, + "headers_helper": { + "type": [ + "string", + "null" + ] + }, + "headers_helper_refresh_interval_ms": { + "format": "uint64", + "minimum": 1.0, + "type": [ + "integer", + "null" + ] + }, "log_agent_responses": { "type": [ "boolean", diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json index 5e986d8a81..e0e8a6f87f 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json @@ -13510,6 +13510,20 @@ } ] }, + "headers_helper": { + "type": [ + "string", + "null" + ] + }, + "headers_helper_refresh_interval_ms": { + "format": "uint64", + "minimum": 1.0, + "type": [ + "integer", + "null" + ] + }, "log_agent_responses": { "type": [ "boolean", diff --git a/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json b/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json index 5f9311e3d7..5a6cc34788 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json @@ -1266,6 +1266,20 @@ } ] }, + "headers_helper": { + "type": [ + "string", + "null" + ] + }, + "headers_helper_refresh_interval_ms": { + "format": "uint64", + "minimum": 1.0, + "type": [ + "integer", + "null" + ] + }, "log_agent_responses": { "type": [ "boolean", diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst index 7713616ae4..0b11d3dfc8 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differ diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst index 1c0ad89d3e..68366b8c4f 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differ diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/OtelRequirements.ts b/codex-rs/app-server-protocol/schema/typescript/v2/OtelRequirements.ts index 588d9993ee..a1a468d72d 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/OtelRequirements.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/OtelRequirements.ts @@ -4,4 +4,4 @@ import type { OtelExporter } from "./OtelExporter"; import type { OtelToolResultLogConfig } from "./OtelToolResultLogConfig"; -export type OtelRequirements = { tool_result: OtelToolResultLogConfig | null, log_sse_deltas: boolean | null, log_user_prompt: boolean | null, log_agent_responses: boolean | null, log_guardian_assessments: boolean | null, environment: string | null, exporter: OtelExporter | null, trace_exporter: OtelExporter | null, metrics_exporter: OtelExporter | null, span_attributes: { [key in string]?: string } | null, tracestate: { [key in string]?: { [key in string]?: string } } | null, }; +export type OtelRequirements = { headers_helper: string | null, headers_helper_refresh_interval_ms: bigint | null, tool_result: OtelToolResultLogConfig | null, log_sse_deltas: boolean | null, log_user_prompt: boolean | null, log_agent_responses: boolean | null, log_guardian_assessments: boolean | null, environment: string | null, exporter: OtelExporter | null, trace_exporter: OtelExporter | null, metrics_exporter: OtelExporter | null, span_attributes: { [key in string]?: string } | null, tracestate: { [key in string]?: { [key in string]?: string } } | null, }; diff --git a/codex-rs/app-server-protocol/src/protocol/v2/config.rs b/codex-rs/app-server-protocol/src/protocol/v2/config.rs index 2158fa23aa..949c1cc12c 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/config.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2/config.rs @@ -25,6 +25,7 @@ use serde::Serialize; use serde_json::Value as JsonValue; use std::collections::BTreeMap; use std::collections::HashMap; +use std::num::NonZeroU64; use std::path::PathBuf; #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)] @@ -507,6 +508,8 @@ pub struct FeedbackRequirements { #[serde(rename_all = "snake_case")] #[ts(export_to = "v2/")] pub struct OtelRequirements { + pub headers_helper: Option, + pub headers_helper_refresh_interval_ms: Option, pub tool_result: Option, pub log_sse_deltas: Option, pub log_user_prompt: Option, diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md index 7328265bc3..1e4291c6a9 100644 --- a/codex-rs/app-server/README.md +++ b/codex-rs/app-server/README.md @@ -965,6 +965,28 @@ managed fields. Configuration writes that overlap managed settings are rejected. Exporter header values are redacted in effective config, source layers, managed requirements, and write-override metadata. Runtime exporters retain the original values. +A system `requirements.toml` file or MDM requirements payload can set +`otel.headers_helper` and its optional `otel.headers_helper_refresh_interval_ms`. +Put the helper and each OTLP HTTP exporter that should receive its headers in +the same requirements layer. If another layer replaces an exporter, that +exporter uses its own configured headers. + +Set the managed helper to the absolute path of an executable, for example +`/opt/company/bin/otel-auth`. Install it in a directory controlled by the +administrator and grant Codex users permission to execute it. Codex launches +the executable directly with its parent as the working directory. A relative +path makes the managed requirements invalid. If the executable is missing or +cannot run, Codex warns and pauses exports that depend on its headers until a +refresh succeeds. + +**Rollout.** Install the helper and upgrade targeted clients to a release that +supports both keys in managed requirements before enabling either key in policy. +Older clients can reject the requirements at startup even if they support the +helper in ordinary config. For a mixed fleet, target only upgraded devices. + +**Rollback.** Remove both managed keys and confirm each device has received the +updated policy before downgrading its client or uninstalling the helper. + Managed span attributes and tracestate metadata are included in effective config and requirements reads. Unmanaged metadata remains writable. diff --git a/codex-rs/app-server/src/otel_config.rs b/codex-rs/app-server/src/otel_config.rs index f9a1915003..de887a0ada 100644 --- a/codex-rs/app-server/src/otel_config.rs +++ b/codex-rs/app-server/src/otel_config.rs @@ -15,6 +15,8 @@ use std::collections::HashMap; pub(crate) fn map_otel_requirements_to_api(otel: OtelRequirementsToml) -> OtelRequirements { OtelRequirements { + headers_helper: otel.headers_helper, + headers_helper_refresh_interval_ms: otel.headers_helper_refresh_interval_ms, tool_result: otel.tool_result.map(|value| OtelToolResultLogConfig { max_bytes: value.max_bytes, }), diff --git a/codex-rs/app-server/tests/common/json_logging.rs b/codex-rs/app-server/tests/common/json_logging.rs index 4ee8629049..dce9aac215 100644 --- a/codex-rs/app-server/tests/common/json_logging.rs +++ b/codex-rs/app-server/tests/common/json_logging.rs @@ -57,6 +57,26 @@ impl JsonLogCapture { } } + pub(crate) async fn wait_for_stderr_line(&self, text: &str, timeout: Duration) -> Result<()> { + tokio::time::timeout(timeout, async { + loop { + let updated = self.updated.notified(); + if self + .lines + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .iter() + .any(|line| line.contains(text)) + { + break; + } + updated.await; + } + }) + .await + .with_context(|| format!("timed out waiting for stderr containing {text:?}")) + } + pub(crate) fn events(&self) -> Result> { let lines = self .lines diff --git a/codex-rs/app-server/tests/common/test_app_server.rs b/codex-rs/app-server/tests/common/test_app_server.rs index 45616c0a2a..7f1465d1db 100644 --- a/codex-rs/app-server/tests/common/test_app_server.rs +++ b/codex-rs/app-server/tests/common/test_app_server.rs @@ -251,6 +251,11 @@ impl TestAppServer { }) } + /// Waits for a substring in the child's captured stderr, including plain-text warnings. + pub async fn wait_for_stderr_line(&self, text: &str, timeout: Duration) -> anyhow::Result<()> { + self.json_logs.wait_for_stderr_line(text, timeout).await + } + /// Waits up to `timeout` for a JSON stderr event whose structured `event.name` field matches. pub async fn wait_for_json_log_event( &self, diff --git a/codex-rs/app-server/tests/suite/logging.rs b/codex-rs/app-server/tests/suite/logging.rs index 348d6a8786..9312e54ccf 100644 --- a/codex-rs/app-server/tests/suite/logging.rs +++ b/codex-rs/app-server/tests/suite/logging.rs @@ -52,6 +52,7 @@ use tokio::time::timeout; use wiremock::Mock; use wiremock::MockServer; use wiremock::ResponseTemplate; +use wiremock::matchers::header; use wiremock::matchers::method; use wiremock::matchers::path; @@ -440,6 +441,131 @@ fn standalone_app_server_emits_json_info_events() -> Result<()> { Ok(()) } +async fn metrics_collector_expecting_helper_headers() -> (MockServer, wiremock::MockGuard) { + let collector = MockServer::start().await; + let export = Mock::given(method("POST")) + .and(path("/v1/metrics")) + .and(header("x-collector-auth", "from-helper")) + .respond_with(ResponseTemplate::new(200)) + .expect(1..) + .mount_as_scoped(&collector) + .await; + (collector, export) +} + +fn metrics_helper_config(command: &str, collector: &MockServer) -> String { + let endpoint = collector.uri(); + format!( + r#"[otel] +headers_helper = '{command}' +headers_helper_refresh_interval_ms = 100 +[otel.metrics_exporter.otlp-http] +endpoint = "{endpoint}/v1/metrics" +protocol = "json" +headers = {{ "x-collector-auth" = "static" }} +"# + ) +} + +fn install_otel_test_helper(dir: &std::path::Path) -> Result<&'static str> { + #[cfg(unix)] + let name = { + codex_utils_cargo_bin::write_executable( + &dir.join("otel-auth"), + "#!/bin/sh\ncat headers.json\n", + )?; + "otel-auth" + }; + #[cfg(windows)] + let name = { + std::fs::write(dir.join("otel-auth.cmd"), "@type headers.json\r\n")?; + "otel-auth.cmd" + }; + std::fs::write( + dir.join("headers.json"), + r#"{"x-collector-auth":"from-helper"}"#, + )?; + Ok(name) +} + +#[tokio::test] +async fn user_otel_helper_runs_from_codex_home_with_managed_environment() -> Result<()> { + let home = TempDir::new()?; + let name = install_otel_test_helper(home.path())?; + let (collector, export) = metrics_collector_expecting_helper_headers().await; + std::fs::write( + home.path().join("config.toml"), + metrics_helper_config(name, &collector), + )?; + std::fs::write( + home.path().join("requirements.toml"), + "[otel]\nenvironment = 'managed'", + )?; + let _server = TestAppServer::builder() + .with_codex_home(home.path()) + .without_auto_env() + .with_env_overrides(&[("OTEL_METRIC_EXPORT_INTERVAL", Some("100"))]) + .build_initialized_with_timeout(READ_TIMEOUT) + .await?; + timeout(READ_TIMEOUT, export.wait_until_satisfied()).await?; + Ok(()) +} + +#[tokio::test] +async fn managed_otel_helper_runs_from_its_install_directory() -> Result<()> { + let home = TempDir::new()?; + let install = tempfile::Builder::new() + .prefix("managed helpers ") + .tempdir()?; + let name = install_otel_test_helper(install.path())?; + let executable = install.path().join(name); + let decoy = home.path().join(name); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt as _; + codex_utils_cargo_bin::write_executable(&decoy, "#!/bin/sh\ntouch decoy-ran\n")?; + std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o644))?; + } + #[cfg(windows)] + std::fs::write(&decoy, "@echo decoy>decoy-ran")?; + let (collector, export) = metrics_collector_expecting_helper_headers().await; + let command = executable.to_str().context("UTF-8 helper path")?; + std::fs::write( + home.path().join("requirements.toml"), + metrics_helper_config(command, &collector), + )?; + let mut server = TestAppServer::builder() + .with_codex_home(home.path()) + .without_auto_env() + .with_env_overrides(&[("OTEL_METRIC_EXPORT_INTERVAL", Some("100"))]) + .build_initialized_with_timeout(READ_TIMEOUT) + .await?; + #[cfg(unix)] + { + let error = std::io::Error::from_raw_os_error(libc::EACCES); + server + .wait_for_stderr_line( + &format!("managed OTel helper {command}: headers helper failed to start: {error}"), + READ_TIMEOUT, + ) + .await?; + } + let request = server.send_config_requirements_read_request().await?; + let _: Value = timeout(READ_TIMEOUT, server.read_response(request)).await??; + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt as _; + std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o755))?; + } + timeout(READ_TIMEOUT, export.wait_until_satisfied()).await?; + assert!(!home.path().join("decoy-ran").exists()); + assert!(!install.path().join("decoy-ran").exists()); + for request in collector.received_requests().await.unwrap() { + assert_eq!(request.headers["x-collector-auth"], "from-helper"); + } + Ok(()) +} + #[tokio::test] async fn sqlite_log_metrics_exports_do_not_create_log_cycles() -> Result<()> { let quiet_period = codex_state::log_db::LogSinkQueueConfig::default().flush_interval diff --git a/codex-rs/app-server/tests/suite/strict_config.rs b/codex-rs/app-server/tests/suite/strict_config.rs index 153927ccc6..5f6b4aee4b 100644 --- a/codex-rs/app-server/tests/suite/strict_config.rs +++ b/codex-rs/app-server/tests/suite/strict_config.rs @@ -101,6 +101,31 @@ foo = "bar" Ok(()) } +#[test_case::test_case("otel-auth"; "bare_name")] +#[test_case::test_case("./otel-auth"; "relative_path")] +fn relative_managed_otel_helper_fails_startup(command: &str) -> Result<()> { + let home = TempDir::new()?; + std::fs::write( + home.path().join("requirements.toml"), + format!("[otel]\nheaders_helper = '{command}'"), + )?; + let output = Command::new(codex_utils_cargo_bin::cargo_bin("codex-app-server")?) + .env("CODEX_HOME", home.path()) + .env( + "CODEX_APP_SERVER_MANAGED_CONFIG_PATH", + home.path().join("managed_config.toml"), + ) + .args(["--listen", "off"]) + .output()?; + let stderr = String::from_utf8(output.stderr)?; + assert!(!output.status.success(), "{stderr}"); + assert!( + stderr.contains("otel.headers_helper must be an absolute executable path"), + "{stderr}" + ); + Ok(()) +} + #[test] fn managed_auth_requirements_fail_closed_for_standalone_app_server() -> Result<()> { for (requirements, config) in [ diff --git a/codex-rs/app-server/tests/suite/v2/config_rpc.rs b/codex-rs/app-server/tests/suite/v2/config_rpc.rs index 5e075f0a54..469ed3d682 100644 --- a/codex-rs/app-server/tests/suite/v2/config_rpc.rs +++ b/codex-rs/app-server/tests/suite/v2/config_rpc.rs @@ -711,10 +711,17 @@ async fn config_requirements_read_redacts_otel_exporter_headers( .without_auto_env() .build_initialized_with_timeout(DEFAULT_READ_TIMEOUT) .await?; + let helper = if cfg!(windows) { + "C:/company/otel-headers.exe" + } else { + "/opt/company/otel-headers" + }; // Read policy without starting exporters or opening the example TLS files. std::fs::write( codex_home.path().join("requirements.toml"), r#"[otel] +headers_helper = "$HELPER" +headers_helper_refresh_interval_ms = 60000 tool_result = { max_bytes = 1024 } log_user_prompt = false log_sse_deltas = false @@ -726,6 +733,7 @@ trace_exporter = { otlp-grpc = { endpoint = "http://127.0.0.1:4317", headers = { metrics_exporter = "$METRICS_EXPORTER" span_attributes = { "service.name" = "managed-service" } tracestate = { managed = { tenant = "enterprise" } }"# + .replace("$HELPER", helper) .replace("$PROTOCOL", protocol) .replace("$METRICS_EXPORTER", metrics_exporter), )?; @@ -735,6 +743,8 @@ tracestate = { managed = { tenant = "enterprise" } }"# assert_eq!( response["requirements"]["otel"], json!({ + "headers_helper": helper, + "headers_helper_refresh_interval_ms": 60000, "tool_result": { "max_bytes": 1024 }, "log_user_prompt": false, "log_sse_deltas": false, diff --git a/codex-rs/config/src/config_requirements.rs b/codex-rs/config/src/config_requirements.rs index ba158c883a..0b742f40e7 100644 --- a/codex-rs/config/src/config_requirements.rs +++ b/codex-rs/config/src/config_requirements.rs @@ -21,6 +21,7 @@ use std::collections::BTreeSet; use std::collections::HashMap; use std::convert::Infallible; use std::fmt; +use std::num::NonZeroU64; use std::path::PathBuf; use std::str::FromStr; use wildmatch::WildMatchPattern; @@ -1253,6 +1254,11 @@ pub struct ConfigRequirementsToml { #[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)] #[serde(deny_unknown_fields)] pub struct OtelRequirementsToml { + pub headers_helper: Option, + pub headers_helper_refresh_interval_ms: Option, + // Computed during composition. A policy cannot grant a helper access to another layer's collector. + #[serde(skip)] + managed_helper_targets: OtelHeadersHelperTargets, pub tool_result: Option, pub log_sse_deltas: Option, pub log_user_prompt: Option, @@ -1266,9 +1272,49 @@ pub struct OtelRequirementsToml { pub tracestate: Option>>, } +/// Signals whose collector may receive the configured helper's credentials. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct OtelHeadersHelperTargets { + pub logs: bool, + pub traces: bool, + pub metrics: bool, +} + +impl OtelHeadersHelperTargets { + fn merge_layer(&mut self, layer: &OtelRequirementsToml) { + let has_helper = layer.headers_helper.is_some(); + let update = |target: &mut bool, exporter: &Option| { + // Replacing either side of the binding revokes the previous grant. + // An empty HTTP endpoint falls back to the process environment in the OTLP SDK. + if has_helper || exporter.is_some() { + *target = has_helper + && matches!(exporter, Some(OtelExporterKind::OtlpHttp { endpoint, .. }) if !endpoint.is_empty()); + } + }; + update(&mut self.logs, &layer.exporter); + update(&mut self.traces, &layer.trace_exporter); + update(&mut self.metrics, &layer.metrics_exporter); + } +} + impl OtelRequirementsToml { + /// A managed helper serves its own layer's exporters. A user helper serves unmanaged exporters. + pub fn headers_helper_targets(&self) -> OtelHeadersHelperTargets { + if self.headers_helper.is_some() { + self.managed_helper_targets + } else { + OtelHeadersHelperTargets { + logs: self.exporter.is_none(), + traces: self.trace_exporter.is_none(), + metrics: self.metrics_exporter.is_none(), + } + } + } + pub(crate) fn is_empty(&self) -> bool { - self.tool_result.is_none() + self.headers_helper.is_none() + && self.headers_helper_refresh_interval_ms.is_none() + && self.tool_result.is_none() && self.log_sse_deltas.is_none() && self.log_user_prompt.is_none() && self.log_agent_responses.is_none() @@ -1951,7 +1997,7 @@ impl ConfigRequirementsToml { return Some("model_providers"); } let otel = self.otel.as_ref(); - let managed_fields: [(bool, &[&str], &'static str); 18] = [ + let managed_fields: [(bool, &[&str], &'static str); 20] = [ ( self.model_provider.is_some(), &["model_provider"], @@ -1997,6 +2043,16 @@ impl ConfigRequirementsToml { &["otel", "tool_result"], "otel.tool_result", ), + ( + otel.is_some_and(|otel| otel.headers_helper.is_some()), + &["otel", "headers_helper"], + "otel.headers_helper", + ), + ( + otel.is_some_and(|otel| otel.headers_helper_refresh_interval_ms.is_some()), + &["otel", "headers_helper_refresh_interval_ms"], + "otel.headers_helper_refresh_interval_ms", + ), ( otel.is_some_and(|otel| otel.log_user_prompt.is_some()), &["otel", "log_user_prompt"], @@ -2073,6 +2129,9 @@ macro_rules! otel_merge_functions { ); contributed = true; } + if let Some(merged) = requirements { + merged.managed_helper_targets.merge_layer(higher_priority); + } contributed } @@ -2097,6 +2156,8 @@ macro_rules! otel_merge_functions { } otel_merge_functions!( + headers_helper, + headers_helper_refresh_interval_ms, tool_result, log_sse_deltas, log_user_prompt, @@ -2753,6 +2814,8 @@ mod tests { #[test_case::test_case(&["otel"], Some("otel.tool_result"); "otel_parent")] #[test_case::test_case(&["otel", "tool_result"], Some("otel.tool_result"); "tool_result")] #[test_case::test_case(&["otel", "tool_result", "max_bytes"], Some("otel.tool_result"); "tool_result_max_bytes")] + #[test_case::test_case(&["otel", "headers_helper"], Some("otel.headers_helper"); "headers_helper")] + #[test_case::test_case(&["otel", "headers_helper_refresh_interval_ms"], Some("otel.headers_helper_refresh_interval_ms"); "headers_helper_refresh_interval_ms")] #[test_case::test_case(&["otel", "log_user_prompt"], Some("otel.log_user_prompt"); "log_user_prompt")] #[test_case::test_case(&["otel", "log_sse_deltas"], Some("otel.log_sse_deltas"); "log_sse_deltas")] #[test_case::test_case(&["otel", "environment"], Some("otel.environment"); "environment")] @@ -2776,6 +2839,8 @@ mod tests { r#" [otel] tool_result = { max_bytes = 1024 } +headers_helper = "/opt/company/otel-headers" +headers_helper_refresh_interval_ms = 60000 log_user_prompt = false environment = "managed" log_sse_deltas = false @@ -2790,6 +2855,8 @@ tracestate = { managed = { tenant = "enterprise" }, empty = {} } r#" [otel] tool_result = { max_bytes = 4096 } +headers_helper = "user-headers" +headers_helper_refresh_interval_ms = 90000 log_user_prompt = true environment = "user" log_sse_deltas = true @@ -2808,6 +2875,8 @@ tracestate = { managed = { tenant = "user", region = "us" }, other = { keep = "y r#" [otel] tool_result = { max_bytes = 1024 } +headers_helper = "/opt/company/otel-headers" +headers_helper_refresh_interval_ms = 60000 log_user_prompt = false environment = "managed" log_sse_deltas = false diff --git a/codex-rs/config/src/lib.rs b/codex-rs/config/src/lib.rs index 4a10ce6872..05ed1eb435 100644 --- a/codex-rs/config/src/lib.rs +++ b/codex-rs/config/src/lib.rs @@ -139,6 +139,7 @@ pub use config_requirements::NetworkRequirementsToml; pub use config_requirements::NetworkUnixSocketPermissionToml; pub use config_requirements::NetworkUnixSocketPermissionsToml; pub use config_requirements::NewThreadModelDefaultsToml; +pub use config_requirements::OtelHeadersHelperTargets; pub use config_requirements::OtelRequirementsToml; pub use config_requirements::RemoteSandboxConfigToml; pub use config_requirements::RequirementSource; diff --git a/codex-rs/config/src/requirements_layers/layer.rs b/codex-rs/config/src/requirements_layers/layer.rs index 2f24e53c2c..e02700aebd 100644 --- a/codex-rs/config/src/requirements_layers/layer.rs +++ b/codex-rs/config/src/requirements_layers/layer.rs @@ -112,6 +112,44 @@ impl ComposableRequirementsLayer { }); } + if let Some(otel) = regular_toml.get("otel") + && (otel.get("headers_helper").is_some() + || otel.get("headers_helper_refresh_interval_ms").is_some()) + && !matches!( + source, + RequirementSource::SystemRequirementsToml { .. } + | RequirementSource::MdmManagedPreferences { .. } + ) + { + return Err(RequirementsCompositionError::Parse { + layer_source: source, + message: + "OTel headers helpers may only be configured in local managed requirements" + .into(), + }); + } + + if let Some(command) = regular_toml + .get("otel") + .and_then(|otel| otel.get("headers_helper")) + .and_then(TomlValue::as_str) + { + let convention = path_context.as_ref().map_or_else( + crate::path_context::convention, + ConfigPathContext::convention, + ); + if codex_utils_path_uri::PathUri::resolve_config_path_uri( + command, convention, /*base*/ None, /*user_home_dir*/ None, + ) + .is_err() + { + return Err(RequirementsCompositionError::Parse { + layer_source: source, + message: "otel.headers_helper must be an absolute executable path in managed requirements".into(), + }); + } + } + // These fields can only be set locally; ignore them before validating cloud policy. strip_cloud_auth_requirements(&source, &mut regular_toml); diff --git a/codex-rs/config/src/requirements_layers/stack_tests.rs b/codex-rs/config/src/requirements_layers/stack_tests.rs index ee42c6a531..3997b238d8 100644 --- a/codex-rs/config/src/requirements_layers/stack_tests.rs +++ b/codex-rs/config/src/requirements_layers/stack_tests.rs @@ -6,6 +6,7 @@ use super::compose_requirements_for_hostname_and_hook_directory; use super::compose_requirements_with_hostname_resolver; use crate::ConfigRequirementsToml; use crate::ConfigRequirementsWithSources; +use crate::OtelHeadersHelperTargets; use crate::RequirementSource; use crate::Sourced; use codex_protocol::protocol::AskForApproval; @@ -452,6 +453,89 @@ tracestate = { shared = { tenant = "replacement", region = "us" }, lower = { ten } } +#[test] +fn otel_managed_headers_follow_each_exporters_owning_layer() -> anyhow::Result<()> { + let dir = tempdir()?; + let system_command = if cfg!(windows) { + "C:/company/headers.exe" + } else { + "/opt/company/headers" + }; + let mdm_command = if cfg!(windows) { + "C:/company/mdm-headers.exe" + } else { + "/opt/company/mdm-headers" + }; + let system = RequirementsLayerEntry::from_toml( + RequirementSource::SystemRequirementsToml { + file: AbsolutePathBuf::try_from(dir.path().join("requirements.toml"))?, + }, + r#"[otel] +headers_helper = "$HELPER" +exporter = { otlp-http = { endpoint = "https://collector.example/logs", protocol = "binary" } } +trace_exporter = { otlp-http = { endpoint = "https://collector.example/traces", protocol = "binary" } } +metrics_exporter = { otlp-http = { endpoint = "https://collector.example/metrics", protocol = "binary" } } +"#.replace("$HELPER", system_command), + ); + let cloud = layer( + "cloud", + "Cloud", + r#"[otel] +trace_exporter = { otlp-http = { endpoint = "https://other.example/traces", protocol = "binary" } } +"#, + ); + let mdm = RequirementsLayerEntry::from_toml( + RequirementSource::MdmManagedPreferences { + domain: "com.openai.codex".into(), + key: "requirements".into(), + }, + r#"[otel] +headers_helper = "$HELPER" +metrics_exporter = { otlp-http = { endpoint = "https://mdm.example/metrics", protocol = "binary" } } +exporter = { otlp-http = { endpoint = "", protocol = "binary" } } +"# + .replace("$HELPER", mdm_command), + ); + + for (layers, command, logs, traces, metrics) in [ + (vec![system.clone()], system_command, true, true, true), + ( + vec![system.clone(), cloud.clone()], + system_command, + true, + false, + true, + ), + (vec![system, cloud, mdm], mdm_command, false, false, true), + ] { + let otel = compose(layers)?.unwrap().otel.unwrap(); + assert_eq!(otel.headers_helper.as_deref(), Some(command)); + assert_eq!( + otel.headers_helper_targets(), + OtelHeadersHelperTargets { + logs, + traces, + metrics + } + ); + } + Ok(()) +} + +#[test] +fn otel_cloud_requirements_cannot_install_or_reschedule_a_helper() { + for setting in [ + "headers_helper = 'headers'", + "headers_helper_refresh_interval_ms = 1", + ] { + let err = + compose(vec![layer("cloud", "Cloud", &format!("[otel]\n{setting}"))]).unwrap_err(); + assert!( + matches!(err, RequirementsCompositionError::Parse { message, .. } if message.contains("local managed requirements")) + ); + } +} + #[test] fn provider_auth_missing_command_is_rejected_after_composition() { let err = compose(vec![ diff --git a/codex-rs/core/src/otel_init.rs b/codex-rs/core/src/otel_init.rs index b187bbd891..5d5496e485 100644 --- a/codex-rs/core/src/otel_init.rs +++ b/codex-rs/core/src/otel_init.rs @@ -87,20 +87,23 @@ pub fn build_provider( let service_name = service_name_override.unwrap_or(originator.value.as_str()); let runtime_metrics = config.features.enabled(Feature::RuntimeMetrics); - let managed = config + let managed_otel = config .config_layer_stack .requirements_toml() .otel .as_deref(); + let helper_targets = + managed_otel.map(codex_config::OtelRequirementsToml::headers_helper_targets); let headers_helper = config .otel .headers_helper .as_ref() .map(|command| OtelHeadersHelper { command: command.clone(), - apply_to_logs: managed.is_none_or(|otel| otel.exporter.is_none()), - apply_to_traces: managed.is_none_or(|otel| otel.trace_exporter.is_none()), - apply_to_metrics: managed.is_none_or(|otel| otel.metrics_exporter.is_none()), + managed: managed_otel.is_some_and(|otel| otel.headers_helper.is_some()), + apply_to_logs: helper_targets.is_none_or(|targets| targets.logs), + apply_to_traces: helper_targets.is_none_or(|targets| targets.traces), + apply_to_metrics: helper_targets.is_none_or(|targets| targets.metrics), refresh_interval: Duration::from_millis( config .otel diff --git a/codex-rs/otel/src/config.rs b/codex-rs/otel/src/config.rs index 0828b6085e..da7f2918d3 100644 --- a/codex-rs/otel/src/config.rs +++ b/codex-rs/otel/src/config.rs @@ -67,13 +67,15 @@ pub struct OtelSettings { } /// A shared command for explicit OTLP HTTP exporters; never used by built-in analytics. -/// The command runs from `OtelSettings::codex_home` and prints a JSON object of strings. +/// The command prints a JSON object of strings. /// Its headers override static headers. A failed run suspends exports until recovery. #[derive(Clone)] pub struct OtelHeadersHelper { pub command: String, + /// A managed executable runs directly from its parent directory. User commands run from Codex home. + pub managed: bool, pub refresh_interval: Duration, - /// Exporters set by admin requirements ignore the headers helper. + /// Signals whose exporter is authorized to receive this helper's headers. pub apply_to_logs: bool, pub apply_to_traces: bool, pub apply_to_metrics: bool, diff --git a/codex-rs/otel/src/headers_helper.rs b/codex-rs/otel/src/headers_helper.rs index a2036bc0e7..a68cd5edd9 100644 --- a/codex-rs/otel/src/headers_helper.rs +++ b/codex-rs/otel/src/headers_helper.rs @@ -106,7 +106,7 @@ async fn refresh_headers( // permit as an SDK that cannot enforce individual destinations. let result = match policy.acquire_for_unsupported_sdk() { Ok(permit) => permit - .run(run_helper(&config.command, cwd)) + .run(run_configured_helper(config, cwd)) .await .unwrap_or_else(|error| Err(error.to_string())), Err(error) => Err(error.to_string()), @@ -132,6 +132,22 @@ async fn refresh_headers( } } +async fn run_configured_helper(config: &OtelHeadersHelper, cwd: &Path) -> HeaderResult { + if !config.managed { + return run_helper(&config.command, cwd).await; + } + let executable = Path::new(&config.command); + let parent = executable + .parent() + .filter(|_| executable.is_absolute()) + .ok_or("managed OTel helper requires an absolute executable path")?; + let mut process = codex_utils_process::background_command(executable); + process.current_dir(parent); + codex_http_headers_helper::run(process) + .await + .map_err(|error| format!("managed OTel helper {}: {error}", executable.display())) +} + async fn run_helper(command: &str, cwd: &Path) -> HeaderResult { #[cfg(windows)] let mut process = codex_http_headers_helper::shell_command(command); diff --git a/codex-rs/otel/src/headers_helper_tests.rs b/codex-rs/otel/src/headers_helper_tests.rs index e2a6d59b11..cdd40452e0 100644 --- a/codex-rs/otel/src/headers_helper_tests.rs +++ b/codex-rs/otel/src/headers_helper_tests.rs @@ -31,6 +31,7 @@ async fn restricted_policy_skips_command_until_a_refresh_is_permitted() { ); let helper = HeadersHelper::start( &OtelHeadersHelper { + managed: false, command: format!("echo invocation >> calls && {}", read_command()), refresh_interval: Duration::from_millis(20), apply_to_logs: true, @@ -66,6 +67,7 @@ async fn concurrent_exports_share_one_helper_execution() { .unwrap(); let helper = HeadersHelper::start( &OtelHeadersHelper { + managed: false, command: format!("echo invocation >> calls && {}", read_command()), refresh_interval: Duration::from_secs(3600), apply_to_logs: true, @@ -101,6 +103,7 @@ async fn periodic_refresh_replaces_credentials_and_recovers_after_failure() { std::fs::write(&path, r#"{"Authorization":"first","X-Old":"old"}"#).unwrap(); let helper = HeadersHelper::start( &OtelHeadersHelper { + managed: false, command: read_command().to_string(), refresh_interval: Duration::from_millis(20), apply_to_logs: true, @@ -138,6 +141,27 @@ async fn periodic_refresh_replaces_credentials_and_recovers_after_failure() { helper.shutdown(); } +#[tokio::test] +async fn missing_managed_executable_reports_path_and_os_error() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("missing-helper.exe"); + let helper = OtelHeadersHelper { + command: path.to_str().unwrap().to_owned(), + managed: true, + refresh_interval: Duration::from_secs(60), + apply_to_logs: true, + apply_to_traces: true, + apply_to_metrics: true, + }; + let error = run_configured_helper(&helper, dir.path()) + .await + .unwrap_err(); + assert!(error.contains(path.to_str().unwrap()), "{error}"); + let os_error = std::fs::metadata(&path).unwrap_err(); + assert_eq!(os_error.kind(), std::io::ErrorKind::NotFound); + assert!(error.contains(&os_error.to_string()), "{error}"); +} + #[tokio::test] async fn helper_failure_is_an_export_error_and_output_is_bounded() { let dir = tempfile::tempdir().unwrap(); @@ -157,6 +181,7 @@ async fn failed_helper_prevents_http_export_even_with_static_credentials() { listener.set_nonblocking(true).unwrap(); let helper = HeadersHelper::start( &OtelHeadersHelper { + managed: false, command: "exit 1".to_string(), refresh_interval: Duration::from_secs(3600), apply_to_logs: true, @@ -193,6 +218,7 @@ async fn failed_helper_prevents_http_export_even_with_static_credentials() { async fn grpc_and_builtin_metrics_do_not_start_the_helper() { use crate::config::OtelExporter; let helper = OtelHeadersHelper { + managed: false, command: String::new(), refresh_interval: Duration::ZERO, apply_to_logs: true, diff --git a/codex-rs/otel/tests/suite/otel_headers_helper.rs b/codex-rs/otel/tests/suite/otel_headers_helper.rs index 625b0ff224..64426d5112 100644 --- a/codex-rs/otel/tests/suite/otel_headers_helper.rs +++ b/codex-rs/otel/tests/suite/otel_headers_helper.rs @@ -64,6 +64,7 @@ fn check_all_signals(protocol: OtelHttpProtocol, managed_logs: bool) { "cat headers.json" }; let helper = OtelHeadersHelper { + managed: false, command: format!("echo invocation >> calls && {command}"), refresh_interval: Duration::from_secs(3600), apply_to_logs: !managed_logs, diff --git a/sdk/python/src/openai_codex/generated/v2_all.py b/sdk/python/src/openai_codex/generated/v2_all.py index b2c5e0987e..75f9def358 100644 --- a/sdk/python/src/openai_codex/generated/v2_all.py +++ b/sdk/python/src/openai_codex/generated/v2_all.py @@ -9874,6 +9874,8 @@ class OtelRequirements(BaseModel): ) environment: str | None = None exporter: OtelExporter | None = None + headers_helper: str | None = None + headers_helper_refresh_interval_ms: Annotated[int | None, Field(ge=1)] = None log_agent_responses: bool | None = None log_guardian_assessments: bool | None = None log_sse_deltas: bool | None = None