diff --git a/codex-rs/analytics/src/client.rs b/codex-rs/analytics/src/client.rs index feb7728f19..32d66da972 100644 --- a/codex-rs/analytics/src/client.rs +++ b/codex-rs/analytics/src/client.rs @@ -1,3 +1,5 @@ +use crate::event_transport::AnalyticsEventTransport; +use crate::event_transport::retain_http_events; use crate::events::AppServerRpcTransport; use crate::events::GuardianReviewAnalyticsResult; use crate::events::GuardianReviewTrackContext; @@ -207,6 +209,7 @@ impl AnalyticsEventsQueue { auth_manager: Arc, destination: AnalyticsEventsDestination, runtime_auth: Option<(RuntimeAuthSlot, RuntimeAuthMode)>, + event_transport: Option>, ) -> Self { let (sender, mut receiver) = mpsc::channel(ANALYTICS_EVENTS_QUEUE_SIZE); let product_generation = Arc::new(AtomicU64::new(0)); @@ -250,6 +253,7 @@ impl AnalyticsEventsQueue { events, &thread_products, runtime_auth.as_ref(), + event_transport.as_ref(), ) .await; thread_products.register(thread_id, product_sku); @@ -264,6 +268,7 @@ impl AnalyticsEventsQueue { events, &thread_products, runtime_auth.as_ref(), + event_transport.as_ref(), ) .await; let _ = done_tx.send(()); @@ -278,6 +283,7 @@ impl AnalyticsEventsQueue { events, &thread_products, runtime_auth.as_ref(), + event_transport.as_ref(), ) .await; } @@ -382,6 +388,31 @@ impl AnalyticsEventsClient { ) } + /// Installs a host-owned transport for events selected by the host. + /// + /// The host owns envelope construction, policy, identity refresh, and bounded delivery. + /// Disabled analytics and local capture never invoke the transport. Rebinding through + /// `for_auth_context` resets it to HTTP so an old actor's transport cannot follow a new actor. + pub fn new_with_event_transport( + auth_manager: Arc, + base_url: impl Into, + analytics_enabled: Option, + event_transport: Arc, + ) -> Self { + let destination = + AnalyticsEventsDestination::from_base_url(base_url.into(), HeaderMap::new()); + Self { + queue: (analytics_enabled != Some(false)).then(|| { + AnalyticsEventsQueue::new( + auth_manager, + destination, + /*runtime_auth*/ None, + Some(event_transport), + ) + }), + } + } + /// Share runtime identity for OpenAI delivery; file capture never authenticates. pub fn new_with_runtime( auth_manager: Arc, @@ -401,7 +432,12 @@ impl AnalyticsEventsClient { let destination = AnalyticsEventsDestination::from_base_url(base_url, api_key_headers); Self { queue: (analytics_enabled != Some(false)).then(|| { - AnalyticsEventsQueue::new(Arc::clone(&auth_manager), destination, runtime_auth) + AnalyticsEventsQueue::new( + Arc::clone(&auth_manager), + destination, + runtime_auth, + /*event_transport*/ None, + ) }), } } @@ -1079,6 +1115,7 @@ async fn send_track_events( mut events: Vec, thread_products: &ThreadProducts, runtime_auth: Option<&(RuntimeAuthSlot, RuntimeAuthMode)>, + event_transport: Option<&Arc>, ) { if events.is_empty() { return; @@ -1108,8 +1145,15 @@ async fn send_track_events( ); let product_sku = product_sku.map(str::to_string); let runtime_auth = runtime_auth.cloned(); + let event_transport = event_transport.cloned(); requests.spawn(async move { for events in track_event_request_batches(events) { + let events = match (&destination, event_transport.as_deref()) { + (AnalyticsEventsDestination::Http { .. }, Some(transport)) => { + retain_http_events(events, product_sku.as_deref(), transport).await + } + _ => events, + }; send_track_events_request( &auth, &destination, diff --git a/codex-rs/analytics/src/client_product_tests.rs b/codex-rs/analytics/src/client_product_tests.rs index 97b3ac6ae0..145e42c748 100644 --- a/codex-rs/analytics/src/client_product_tests.rs +++ b/codex-rs/analytics/src/client_product_tests.rs @@ -175,6 +175,7 @@ async fn product_streams_send_concurrently_and_preserve_event_order() { events, &products, /*runtime_auth*/ None, + /*event_transport*/ None, ), ) .await @@ -218,6 +219,7 @@ async fn buffered_tool_events_preserve_attribution_or_drop_it_on_queue_overflow( manager, destination, /*runtime_auth*/ None, + /*event_transport*/ None, )), }; let thread_id = ThreadId::new(); diff --git a/codex-rs/analytics/src/client_runtime_auth_tests.rs b/codex-rs/analytics/src/client_runtime_auth_tests.rs index cf2f25f869..4974dcfbda 100644 --- a/codex-rs/analytics/src/client_runtime_auth_tests.rs +++ b/codex-rs/analytics/src/client_runtime_auth_tests.rs @@ -81,6 +81,7 @@ async fn runtime_delivery_signs_each_batch_and_strips_cross_origin_auth() { api_key_headers: Default::default(), }, Some((Arc::new(std::sync::OnceLock::from(runtime.0)), runtime.1)), + /*event_transport*/ None, )), }; emit(&client, "first").await; @@ -209,6 +210,7 @@ async fn analytics_between_model_calls_keeps_the_selected_api_resources() { Arc::new(std::sync::OnceLock::from(Arc::clone(&owner))), mode, )), + /*event_transport*/ None, )), }; let provider = codex_model_provider::test_support::runtime_model_provider( diff --git a/codex-rs/analytics/src/client_tests.rs b/codex-rs/analytics/src/client_tests.rs index 958269ae3c..7eb27fa6ec 100644 --- a/codex-rs/analytics/src/client_tests.rs +++ b/codex-rs/analytics/src/client_tests.rs @@ -115,6 +115,8 @@ use tokio::sync::mpsc::error::TryRecvError; #[path = "client_product_tests.rs"] mod product_tests; +#[path = "client_transport_tests.rs"] +mod transport_tests; #[cfg(debug_assertions)] impl AnalyticsEventsClient { @@ -124,6 +126,7 @@ impl AnalyticsEventsClient { auth_manager, AnalyticsEventsDestination::CaptureFile { path }, /*runtime_auth*/ None, + /*event_transport*/ None, )), } } @@ -536,6 +539,7 @@ async fn api_key_auth_sends_only_plugin_events_to_codex_backend() { ], &ThreadProducts::default(), /*runtime_auth*/ None, + /*event_transport*/ None, ) .await; @@ -1267,6 +1271,7 @@ async fn account_switch_between_batches_does_not_send_old_credentials() { events, &ThreadProducts::default(), /*runtime_auth*/ None, + /*event_transport*/ None, ) .await; server.abort(); diff --git a/codex-rs/analytics/src/client_transport_tests.rs b/codex-rs/analytics/src/client_transport_tests.rs new file mode 100644 index 0000000000..029beb557d --- /dev/null +++ b/codex-rs/analytics/src/client_transport_tests.rs @@ -0,0 +1,354 @@ +#![cfg(test)] + +//! Protect mixed-batch HTTP compatibility and the boundaries of host transport opt-in. + +use super::AnalyticsEventsClient; +use super::AnalyticsEventsDestination; +use super::sample_regular_track_event; +use super::sample_thread_start_response; +use super::send_track_events; +use crate::AnalyticsEventDelivery; +use crate::AnalyticsEventTransport; +use crate::AnalyticsTransportEvent; +use crate::events::AppServerRpcTransport; +use crate::events::CodexAppServerClientMetadata; +use crate::events::CodexCompactionEventRequest; +use crate::events::CodexRuntimeMetadata; +use crate::events::TrackEventRequest; +use crate::events::codex_compaction_event_params; +use crate::facts::CodexCompactionEvent; +use crate::facts::CompactionImplementation; +use crate::facts::CompactionPhase; +use crate::facts::CompactionReason; +use crate::facts::CompactionStatus; +use crate::facts::CompactionStrategy; +use crate::facts::CompactionTrigger; +use crate::product_attribution::ThreadProducts; +use codex_app_server_protocol::ClientInfo; +use codex_app_server_protocol::ClientResponsePayload; +use codex_app_server_protocol::InitializeParams; +use codex_app_server_protocol::RequestId; +use codex_login::AuthManager; +use codex_login::CodexAuth; +use pretty_assertions::assert_eq; +use std::future::Future; +use std::pin::Pin; +use std::sync::Arc; +use std::sync::Mutex; +use wiremock::Mock; +use wiremock::MockServer; +use wiremock::ResponseTemplate; +use wiremock::matchers::path; + +struct RecordingTransport { + selected_type: &'static str, + delivery: AnalyticsEventDelivery, + events: Arc>>, +} + +impl AnalyticsEventTransport for RecordingTransport { + fn selects(&self, event_type: &str) -> bool { + self.selected_type == event_type + } + + fn publish( + &self, + event: AnalyticsTransportEvent, + ) -> Pin + Send + '_>> { + Box::pin(async move { + self.events.lock().unwrap().push(event); + self.delivery + }) + } +} + +fn compaction_fact() -> CodexCompactionEvent { + CodexCompactionEvent { + thread_id: "thread-1".to_string(), + turn_id: "turn-1".to_string(), + trigger: CompactionTrigger::Auto, + reason: CompactionReason::ContextLimit, + implementation: CompactionImplementation::ResponsesCompactionV2, + phase: CompactionPhase::MidTurn, + strategy: CompactionStrategy::Memento, + status: CompactionStatus::Completed, + codex_error_kind: None, + codex_error_http_status_code: None, + usage_limit_window_minutes: None, + active_context_tokens_before: 120_000, + active_context_tokens_after: 18_000, + retained_image_count: None, + compaction_summary_tokens: None, + cached_input_tokens: None, + cache_write_input_tokens: None, + started_at: 100, + completed_at: 106, + duration_ms: Some(6543), + } +} + +fn compaction() -> TrackEventRequest { + TrackEventRequest::Compaction(Box::new(CodexCompactionEventRequest { + event_type: "codex_compaction_event", + event_params: codex_compaction_event_params( + compaction_fact(), + "session-1".to_string(), + CodexAppServerClientMetadata { + product_client_id: "codex-cloud-agent".to_string(), + client_name: Some("codex-cloud-agent".to_string()), + client_version: Some("1.0.0".to_string()), + rpc_transport: AppServerRpcTransport::InProcess, + experimental_api_enabled: Some(true), + }, + CodexRuntimeMetadata { + codex_rs_version: "0.1.0".to_string(), + runtime_os: "linux".to_string(), + runtime_os_version: "6".to_string(), + runtime_arch: "x86_64".to_string(), + }, + /*thread_source*/ None, + /*subagent_source*/ None, + /*parent_thread_id*/ None, + ), + })) +} + +/// The host can select either wire type without changing the HTTP payload of its neighbor. +#[tokio::test] +async fn host_delivery_preserves_http_payload_and_product_for_unhandled_events() { + for (selected_type, delivery) in [ + ("codex_compaction_event", None), + ("codex_compaction_event", Some(AnalyticsEventDelivery::Http)), + ( + "codex_compaction_event", + Some(AnalyticsEventDelivery::Handled), + ), + ("skill_invocation", Some(AnalyticsEventDelivery::Http)), + ("skill_invocation", Some(AnalyticsEventDelivery::Handled)), + ] { + let server = MockServer::start().await; + Mock::given(path("/codex/analytics-events/events")) + .respond_with(ResponseTemplate::new(200)) + .expect(1) + .mount(&server) + .await; + let recorded = Arc::new(Mutex::new(Vec::new())); + let transport: Option> = delivery.map(|delivery| { + Arc::new(RecordingTransport { + selected_type, + delivery, + events: Arc::clone(&recorded), + }) as Arc + }); + let events = vec![compaction(), sample_regular_track_event("thread-1")]; + let payloads = serde_json::to_value(&events).unwrap(); + let payloads = payloads.as_array().unwrap(); + let selected = payloads + .iter() + .find(|event| event["event_type"] == selected_type) + .unwrap(); + let expected_http: Vec<_> = payloads + .iter() + .filter(|event| { + delivery != Some(AnalyticsEventDelivery::Handled) + || event["event_type"] != selected_type + }) + .collect(); + let mut products = ThreadProducts::default(); + products.register("thread-1".to_string(), Some("tpp".to_string())); + send_track_events( + &AuthManager::from_auth_for_testing(CodexAuth::create_dummy_chatgpt_auth_for_testing()), + &AnalyticsEventsDestination::Http { + base_url: server.uri().into(), + api_key_headers: Default::default(), + }, + events, + &products, + /*runtime_auth*/ None, + transport.as_ref(), + ) + .await; + let requests = server.received_requests().await.unwrap(); + assert_eq!(requests.len(), 1); + assert_eq!( + requests[0].body_json::().unwrap(), + serde_json::json!({ "events": expected_http }) + ); + assert_eq!(requests[0].headers["x-openai-product-sku"], "tpp"); + assert_eq!( + *recorded.lock().unwrap(), + if delivery.is_some() { + vec![AnalyticsTransportEvent { + event_type: selected_type, + payload: selected.clone(), + product_sku: Some("tpp".to_string()), + }] + } else { + vec![] + } + ); + } +} + +/// Installing a host transport must not bypass the existing event eligibility filter. +#[tokio::test] +async fn api_key_auth_does_not_send_ineligible_compaction_to_host() { + let server = MockServer::start().await; + let recorded = Arc::new(Mutex::new(Vec::new())); + let transport: Arc = Arc::new(RecordingTransport { + selected_type: "codex_compaction_event", + delivery: AnalyticsEventDelivery::Handled, + events: Arc::clone(&recorded), + }); + send_track_events( + &AuthManager::from_auth_for_testing(CodexAuth::from_api_key("test-key")), + &AnalyticsEventsDestination::Http { + base_url: server.uri().into(), + api_key_headers: Default::default(), + }, + vec![compaction()], + &ThreadProducts::default(), + /*runtime_auth*/ None, + Some(&transport), + ) + .await; + assert!(recorded.lock().unwrap().is_empty()); + assert!(server.received_requests().await.unwrap().is_empty()); +} + +/// Local capture keeps source payloads and must not trigger an external host publisher. +#[cfg(debug_assertions)] +#[tokio::test] +async fn capture_file_never_invokes_host_transport() { + let capture = std::env::temp_dir().join(format!( + "analytics-host-capture-{}-{}.jsonl", + std::process::id(), + crate::now_unix_millis() + )); + let recorded = Arc::new(Mutex::new(Vec::new())); + let transport: Arc = Arc::new(RecordingTransport { + selected_type: "codex_compaction_event", + delivery: AnalyticsEventDelivery::Handled, + events: Arc::clone(&recorded), + }); + send_track_events( + &AuthManager::from_auth_for_testing(CodexAuth::create_dummy_chatgpt_auth_for_testing()), + &AnalyticsEventsDestination::CaptureFile { + path: capture.clone(), + }, + vec![compaction()], + &ThreadProducts::default(), + /*runtime_auth*/ None, + Some(&transport), + ) + .await; + let payload: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(&capture).unwrap()).unwrap(); + std::fs::remove_file(capture).unwrap(); + assert_eq!(payload, serde_json::json!({"events": [compaction()]})); + assert!(recorded.lock().unwrap().is_empty()); +} + +/// The worker routes reduced compaction only for an enabled, explicitly opted-in actor. +/// Flushing waits for delivery; rebinding must not reuse the previous actor's transport. +#[tokio::test] +async fn worker_preserves_opt_out_and_actor_rebinding() { + enum Mode { + Host, + Disabled, + Rebound, + } + for mode in [Mode::Host, Mode::Disabled, Mode::Rebound] { + let server = MockServer::start().await; + Mock::given(path("/codex/analytics-events/events")) + .respond_with(ResponseTemplate::new(200)) + .mount(&server) + .await; + let recorded = Arc::new(Mutex::new(Vec::new())); + let transport = Arc::new(RecordingTransport { + selected_type: "codex_compaction_event", + delivery: AnalyticsEventDelivery::Handled, + events: Arc::clone(&recorded), + }); + let client = AnalyticsEventsClient::new_with_event_transport( + AuthManager::from_auth_for_testing(CodexAuth::create_dummy_chatgpt_auth_for_testing()), + server.uri(), + Some(!matches!(mode, Mode::Disabled)), + transport, + ); + let client = if matches!(mode, Mode::Rebound) { + client.for_auth_context( + AuthManager::from_auth_for_testing( + CodexAuth::create_dummy_chatgpt_auth_for_testing(), + ), + server.uri(), + /*runtime_auth*/ None, + /*api_key_headers*/ Default::default(), + ) + } else { + client + }; + client.track_initialize( + /*connection_id*/ 1, + InitializeParams { + client_info: ClientInfo { + name: "test".to_string(), + title: None, + version: "1".to_string(), + }, + capabilities: None, + }, + "test_client".to_string(), + AppServerRpcTransport::InProcess, + ); + let response = sample_thread_start_response(); + let ClientResponsePayload::ThreadStart(started) = &response else { + unreachable!() + }; + let mut fact = compaction_fact(); + fact.thread_id = started.thread.id.clone(); + client.track_response(/*connection_id*/ 1, RequestId::Integer(1), &response); + client.track_compaction(fact); + client.flush().await; + + let http_events = server + .received_requests() + .await + .unwrap() + .iter() + .flat_map(|request| { + request.body_json::().unwrap()["events"] + .as_array() + .unwrap() + .clone() + }) + .collect::>(); + let http_compactions = http_events + .iter() + .filter(|event| event["event_type"] == "codex_compaction_event") + .count(); + let delivered = recorded.lock().unwrap(); + match mode { + Mode::Host => { + assert_eq!(delivered.len(), 1); + assert_eq!( + delivered[0].payload["event_params"]["thread_id"], + started.thread.id + ); + assert_eq!(http_compactions, 0); + assert!( + !http_events.is_empty(), + "unmigrated thread events retain HTTP delivery" + ); + } + Mode::Disabled => { + assert!(delivered.is_empty()); + assert!(http_events.is_empty()); + } + Mode::Rebound => { + assert!(delivered.is_empty()); + assert_eq!(http_compactions, 1); + } + } + } +} diff --git a/codex-rs/analytics/src/event_transport.rs b/codex-rs/analytics/src/event_transport.rs new file mode 100644 index 0000000000..6e12e76f47 --- /dev/null +++ b/codex-rs/analytics/src/event_transport.rs @@ -0,0 +1,84 @@ +//! Let a host select analytics events by wire type after the existing eligibility checks. + +use crate::events::TrackEventRequest; +use std::future::Future; +use std::pin::Pin; + +/// One source event in its HTTP wire format, before backend normalization. +/// The transport must preserve the product attribution and supply its own fresh actor context. +/// Canonical delivery must also preserve any backend side effects for the selected type. +#[derive(Debug, PartialEq)] +pub struct AnalyticsTransportEvent { + pub event_type: &'static str, + /// The complete event, including any type-specific top-level fields. + pub payload: serde_json::Value, + pub product_sku: Option, +} + +/// Whether the original event still needs the existing HTTP delivery path. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum AnalyticsEventDelivery { + /// Preserve HTTP delivery, including after publishing a shadow copy. + Http, + /// The host took responsibility for canonical delivery; do not also send HTTP. + /// This does not imply durable persistence or successful delivery. + Handled, +} + +/// Host-owned transport for explicitly selected event types. +/// +/// Implementations own policy checks, actor refresh, schema/envelope normalization, +/// and bounded delivery. Return `Http` for legacy or shadow mode, or when declining +/// before a canonical publish. After attempting canonical delivery, return `Handled` +/// even if its outcome is uncertain, to avoid an automatic duplicate through HTTP. +/// The queue awaits this method, so implementations must enforce their own deadline +/// or enqueue into a bounded host queue; stalled delivery also delays unrelated facts. +/// +/// The boxed future permits different host implementations behind a shared client. +pub trait AnalyticsEventTransport: Send + Sync { + /// Select the wire types this host supports before preparing a payload. + /// Return false for unknown types and for events using ordinary HTTP delivery. + fn selects(&self, event_type: &str) -> bool; + + fn publish( + &self, + event: AnalyticsTransportEvent, + ) -> Pin + Send + '_>>; +} + +pub(crate) async fn retain_http_events( + events: Vec, + product_sku: Option<&str>, + transport: &dyn AnalyticsEventTransport, +) -> Vec { + let mut http_events = Vec::with_capacity(events.len()); + for event in events { + let event_type = event.event_type(); + if !transport.selects(event_type) { + http_events.push(event); + continue; + } + let payload = match serde_json::to_value(&event) { + Ok(payload) => payload, + Err(_) => { + tracing::warn!( + event_type, + "failed to prepare event for host analytics transport" + ); + http_events.push(event); + continue; + } + }; + let delivery = transport + .publish(AnalyticsTransportEvent { + event_type, + payload, + product_sku: product_sku.map(str::to_owned), + }) + .await; + if delivery == AnalyticsEventDelivery::Http { + http_events.push(event); + } + } + http_events +} diff --git a/codex-rs/analytics/src/events.rs b/codex-rs/analytics/src/events.rs index 32fa452b8d..be169547b3 100644 --- a/codex-rs/analytics/src/events.rs +++ b/codex-rs/analytics/src/events.rs @@ -165,6 +165,46 @@ pub(crate) fn codex_artifact_operation_event_request( } impl TrackEventRequest { + pub(crate) fn event_type(&self) -> &'static str { + match self { + Self::SkillInvocation(event) => event.event_type, + Self::ThreadInitialized(event) => event.event_type, + Self::ThreadArchive(event) => event.event_type, + Self::GuardianReview(event) => event.event_type, + Self::GuardianV2(event) => event.event_type, + Self::AppMentioned(event) => event.event_type, + Self::AppUsed(event) => event.event_type, + Self::HookRun(event) => event.event_type, + Self::Compaction(event) => event.event_type, + Self::Goal(event) => event.event_type, + Self::ThreadHintStatus(event) => event.event_type, + Self::TurnEvent(event) => event.event_type, + Self::TurnSteer(event) => event.event_type, + Self::ArtifactOperation(event) => event.event_type, + Self::CommandExecution(event) => event.event_type, + Self::PluginMeasurement(event) => event.event_type, + Self::FileChange(event) => event.event_type, + Self::CuaToolCallStarted(event) => event.event_type, + Self::McpToolCall(event) => event.event_type, + Self::DynamicToolCall(event) => event.event_type, + Self::ControlToolCall(event) => event.event_type, + Self::CollabAgentToolCall(event) => event.event_type, + Self::WebSearch(event) => event.event_type, + Self::ImageGeneration(event) => event.event_type, + Self::AcceptedLineFingerprints(event) => event.event_type, + Self::ReviewEvent(event) => event.event_type, + Self::PluginUsed(event) => event.event_type, + Self::PluginInstallRequested(event) => event.event_type, + Self::PluginInstalled(event) + | Self::PluginUninstalled(event) + | Self::PluginEnabled(event) + | Self::PluginDisabled(event) => event.event_type, + Self::PluginInstallFailed(event) => event.event_type, + Self::ExternalAgentConfigImportCompleted(event) => event.event_type, + Self::ExternalAgentConfigImportFailure(event) => event.event_type, + } + } + pub(crate) fn should_send_in_isolated_request(&self) -> bool { matches!(self, Self::AcceptedLineFingerprints(_)) } diff --git a/codex-rs/analytics/src/lib.rs b/codex-rs/analytics/src/lib.rs index 68e1103a31..768903d898 100644 --- a/codex-rs/analytics/src/lib.rs +++ b/codex-rs/analytics/src/lib.rs @@ -2,6 +2,7 @@ mod accepted_lines; #[cfg(debug_assertions)] mod analytics_capture; mod client; +mod event_transport; mod events; mod facts; mod guardian_v2; @@ -15,6 +16,9 @@ use std::time::UNIX_EPOCH; pub use accepted_lines::fingerprint_hash; pub use client::AnalyticsEventsClient; +pub use event_transport::AnalyticsEventDelivery; +pub use event_transport::AnalyticsEventTransport; +pub use event_transport::AnalyticsTransportEvent; pub use events::AppServerRpcTransport; pub use events::GuardianAdditionalPermissions; pub use events::GuardianApprovalRequestSource;