diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock index 8104a3b710..f7f2f08624 100644 --- a/codex-rs/Cargo.lock +++ b/codex-rs/Cargo.lock @@ -3935,6 +3935,7 @@ dependencies = [ "schemars 0.8.22", "serde", "serde_json", + "serde_path_to_error", "sha2 0.10.9", "tempfile", "tokio", diff --git a/codex-rs/core/src/agent/api.rs b/codex-rs/core/src/agent/api.rs index 7664a864d4..054770df82 100644 --- a/codex-rs/core/src/agent/api.rs +++ b/codex-rs/core/src/agent/api.rs @@ -124,7 +124,11 @@ pub trait AgentControl: Send + Sync { /// Account for one inference response, including compaction. Each call records usage; /// callers report it once. `SessionBudgetExceeded` means the usage was recorded and /// the shared budget is now exhausted. - fn record_usage(&self, usage: TokenUsage) -> BoxFuture<'_, Result<()>>; + fn record_usage( + &self, + usage: Option, + hook_charge: codex_hooks::HookCharge, + ) -> BoxFuture<'_, Result<()>>; /// Report the terminal result to the parent and completion activity to the task /// initiator. Local delivery remains best effort and uses the reporting runtime's diff --git a/codex-rs/core/src/agent/control/api.rs b/codex-rs/core/src/agent/control/api.rs index bdb03f1b5c..ce3735f196 100644 --- a/codex-rs/core/src/agent/control/api.rs +++ b/codex-rs/core/src/agent/control/api.rs @@ -282,8 +282,12 @@ impl AgentControl for LocalAgentControl { self.execution_guard(version, source) } - fn record_usage(&self, usage: TokenUsage) -> BoxFuture<'_, Result<()>> { - Box::pin(async move { self.record_rollout_budget_usage(&usage) }) + fn record_usage( + &self, + usage: Option, + hook_charge: codex_hooks::HookCharge, + ) -> BoxFuture<'_, Result<()>> { + Box::pin(async move { self.record_rollout_budget_usage(usage.as_ref(), hook_charge) }) } fn turn_finished<'a>( diff --git a/codex-rs/core/src/agent/control/budget.rs b/codex-rs/core/src/agent/control/budget.rs index 3dc0b7f1d9..c637750139 100644 --- a/codex-rs/core/src/agent/control/budget.rs +++ b/codex-rs/core/src/agent/control/budget.rs @@ -9,8 +9,16 @@ use codex_protocol::error::Result as CodexResult; use codex_protocol::protocol::TokenUsage; impl LocalAgentControl { - pub(crate) fn record_rollout_budget_usage(&self, usage: &TokenUsage) -> CodexResult<()> { - if self.runtime.rollout_budget.record_usage(usage)? { + pub(crate) fn record_rollout_budget_usage( + &self, + usage: Option<&TokenUsage>, + hook_charge: codex_hooks::HookCharge, + ) -> CodexResult<()> { + if self + .runtime + .rollout_budget + .record_usage(usage, hook_charge)? + { return Err(CodexErr::SessionBudgetExceeded); } Ok(()) diff --git a/codex-rs/core/src/agent/host/usage.rs b/codex-rs/core/src/agent/host/usage.rs index 0ecf617948..65e7959c3f 100644 --- a/codex-rs/core/src/agent/host/usage.rs +++ b/codex-rs/core/src/agent/host/usage.rs @@ -5,14 +5,18 @@ use codex_protocol::error::Result; use codex_protocol::protocol::TokenUsage; use futures::future::BoxFuture; -/// Provider-reported spending for one response, including compaction. -#[derive(Clone, Debug, PartialEq, Eq)] +/// Spending reported for one model response, including compaction. +#[derive(Clone, Debug, PartialEq)] pub struct AgentUsageReport { pub thread_id: ThreadId, pub turn_id: String, /// Per-response usage, not cumulative totals. Remote adapters must explicitly /// carry `codex_rollout_budget_units`, which `TokenUsage` skips when serialized. - pub usage: TokenUsage, + pub usage: Option, + /// Synchronous post-hook contributions, independent of the provider's usage. + pub additional_budget_units: f64, + /// If f64 summation overflowed, this is the largest individual hook price, not the total. + pub additional_budget_units_overflowed: bool, } /// Both decisions mean the host recorded the reported spending. diff --git a/codex-rs/core/src/client/response_delivery.rs b/codex-rs/core/src/client/response_delivery.rs index 8daf97af09..888cdcfad5 100644 --- a/codex-rs/core/src/client/response_delivery.rs +++ b/codex-rs/core/src/client/response_delivery.rs @@ -87,18 +87,23 @@ impl ResponseDelivery { let owner = attempt.owner_cancellation.clone(); attempt.start_post_hooks(report).map(|hooks| (owner, hooks)) }); - if let Some((owner, hooks)) = hooks { + let hook_output = if let Some((owner, hooks)) = hooks { tokio::select! { biased; () = tx.closed() => return false, () = owner.cancelled() => return false, - () = hooks => {} + output = hooks => output, } - } + } else { + Default::default() + }; self.attempt = None; let terminal = SamplingEvent { event, - hook_output: Default::default(), + hook_output: crate::client_common::SamplingCharge { + hooks: hook_output, + ..Default::default() + }, }; let released = self.release(terminal, tx).await; match released { diff --git a/codex-rs/core/src/client_common.rs b/codex-rs/core/src/client_common.rs index 1940e54739..1a42418c81 100644 --- a/codex-rs/core/src/client_common.rs +++ b/codex-rs/core/src/client_common.rs @@ -121,13 +121,14 @@ fn normalize_image_detail(detail: &mut Option, model_info: &ModelIn } } -/// Records whether the response producer has posted the bill. +/// Carries the hook price and whether the response producer has posted the bill. #[derive(Debug, Default)] pub(crate) struct SamplingCharge { + pub(crate) hooks: codex_hooks::ModelRequestHookOutcome, pub(crate) posted: bool, } -/// Core consumes a terminal event together with its billing status. Other readers +/// Core consumes a terminal event and its hook output together. Other readers /// of the public response stream still see the provider's unmodified event. #[derive(Debug)] pub(crate) struct SamplingEvent { @@ -135,7 +136,8 @@ pub(crate) struct SamplingEvent { pub(crate) hook_output: SamplingCharge, } -/// Provider usage and billing status for one response. +/// The provider's usage and the hook's contribution describe the same +/// response. Keeping them separate preserves the provider's original numbers. #[derive(Debug)] pub(crate) struct SamplingUsage { pub(crate) provider: Option, @@ -161,7 +163,7 @@ impl From> for SamplingEvent { } } -/// A sampling consumer receives the billing status with the provider event. +/// A sampling consumer receives the hook outcome with the provider event it settles. pub(crate) struct SamplingStream { pub(crate) routing_affinity: Option, pub(crate) rx_event: mpsc::Receiver, diff --git a/codex-rs/core/src/compact_remote_v2.rs b/codex-rs/core/src/compact_remote_v2.rs index c9c66bac4c..0c68011664 100644 --- a/codex-rs/core/src/compact_remote_v2.rs +++ b/codex-rs/core/src/compact_remote_v2.rs @@ -1434,16 +1434,26 @@ mod tests { total_tokens: 120, ..Default::default() }; - let stream = response_stream(vec![Err(CodexErr::new( - CodexErrorDetails::ResponseIncomplete(Box::new( - codex_protocol::error::ResponseIncompleteError { + let stream = response_stream(vec![SamplingEvent { + event: Err(CodexErr::new(CodexErrorDetails::ResponseIncomplete( + Box::new(codex_protocol::error::ResponseIncompleteError { partial_output: vec![], reason: "max_output_tokens".to_string(), response_id: Some("resp-background".to_string()), token_usage: Some(usage.clone()), + }), + ))), + hook_output: crate::client_common::SamplingCharge { + hooks: codex_hooks::ModelRequestHookOutcome { + charge: codex_hooks::HookCharge { + units: 3.0, + overflowed: false, + }, + invalid_price: Some("negative sibling price".into()), }, - )), - ))]); + ..Default::default() + }, + }]); let (mut sess, turn_context, rx) = crate::session::tests::make_session_and_context_with_rx().await; let accounting = Arc::new(UsageRecorder { @@ -1484,65 +1494,90 @@ mod tests { vec![AgentUsageReport { thread_id: sess.thread_id(), turn_id: turn_context.sub_id.clone(), - usage, + usage: Some(usage), + additional_budget_units: 3.0, + additional_budget_units_overflowed: false, }] ); } - #[test_case::test_case(true, false; "background bills a complete response even without a summary")] - #[test_case::test_case(false, true; "turn interrupt discards a queued complete response")] - #[test_case::test_case(true, true; "session shutdown bills a queued complete response even without a summary")] + #[test_case::test_case(false, false, false; "foreground bills a complete response even without a summary")] + #[test_case::test_case(true, false, false; "background bills a complete response even without a summary")] + #[test_case::test_case(false, true, false; "turn interrupt discards a queued complete response")] + #[test_case::test_case(true, true, false; "session shutdown bills a queued complete response even without a summary")] + #[test_case::test_case(false, false, true; "a malformed sibling is still reported when valid spending exhausts the account")] #[tokio::test] - async fn collect_queued_complete_response(background: bool, interrupted: bool) { + async fn collect_queued_complete_response( + background: bool, + interrupted: bool, + bad_sibling: bool, + ) { let (mut sess, turn, _) = crate::session::tests::make_session_and_context_with_rx().await; let accounting = Arc::new(UsageRecorder { reports: Mutex::new(Vec::new()), - decision: UsageAccountingDecision::Continue, + decision: if bad_sibling { + UsageAccountingDecision::Exhausted + } else { + UsageAccountingDecision::Continue + }, }); accounting.install(&mut sess); - let usage = TokenUsage { + let provider_usage = interrupted.then(|| TokenUsage { output_tokens: 42, ..Default::default() - }; - let stream = response_stream(vec![Ok(ResponseEvent::Completed { - response_id: "resp-compact".into(), - token_usage: Some(usage.clone()), - usage_metadata: None, - reasoning_removals: None, - end_turn: Some(true), - })]); + }); + let stream = response_stream(vec![SamplingEvent { + event: Ok(ResponseEvent::Completed { + response_id: "resp-compact".into(), + token_usage: provider_usage.clone(), + usage_metadata: None, + reasoning_removals: None, + end_turn: Some(true), + }), + hook_output: crate::client_common::SamplingCharge { + hooks: codex_hooks::ModelRequestHookOutcome { + charge: codex_hooks::HookCharge { + units: 42.0, + overflowed: false, + }, + invalid_price: bad_sibling.then(|| "negative sibling price".into()), + }, + ..Default::default() + }, + }]); let cancellation = CancellationToken::new(); if interrupted { cancellation.cancel(); } - let result = collect_compaction_output( - &sess, - &turn, - stream, - if background { - CompactionRequestKind::Background(&cancellation) - } else { - CompactionRequestKind::Foreground(&cancellation) - }, - ) - .await; - - if !background { - assert!( - matches!(result, Err(error) if matches!(error.details(), CodexErrorDetails::TurnAborted)) - ); + let kind = if background { + CompactionRequestKind::Background(&cancellation) + } else { + CompactionRequestKind::Foreground(&cancellation) + }; + let result = collect_compaction_output(&sess, &turn, stream, kind).await; + let error = result.err().expect("no installable summary"); + if interrupted && !background { + assert!(matches!(error.details(), CodexErrorDetails::TurnAborted)); assert!(accounting.reports.lock().unwrap().is_empty()); return; } - assert!( - matches!(result, Err(error) if matches!(error.details(), CodexErrorDetails::Fatal(_))) - ); + if bad_sibling { + assert!( + matches!(error.details(), CodexErrorDetails::UsageAccountingFailed(message) if message.contains("negative sibling price")) + ); + } else { + assert!( + matches!(error.details(), CodexErrorDetails::Fatal(message) if message.contains("exactly one compaction output")) + ); + } assert_eq!( *accounting.reports.lock().unwrap(), [AgentUsageReport { thread_id: sess.thread_id(), turn_id: turn.sub_id.clone(), - usage, + usage: provider_usage, + additional_budget_units: 42.0, + additional_budget_units_overflowed: false, }] ); } diff --git a/codex-rs/core/src/hook_mcp_executor.rs b/codex-rs/core/src/hook_mcp_executor.rs index 3cc721803d..1ed54b8992 100644 --- a/codex-rs/core/src/hook_mcp_executor.rs +++ b/codex-rs/core/src/hook_mcp_executor.rs @@ -61,6 +61,7 @@ impl HookMcpExecutor for CoreHookMcpExecutor { } Ok(HookMcpOutput { + structured_content: result.structured_content, text, source_tool_namespace: call_result.source_tool_namespace, }) diff --git a/codex-rs/core/src/hook_runtime.rs b/codex-rs/core/src/hook_runtime.rs index 7da1b27e35..776952eade 100644 --- a/codex-rs/core/src/hook_runtime.rs +++ b/codex-rs/core/src/hook_runtime.rs @@ -1133,10 +1133,11 @@ async fn run_model_request_hooks( step: &StepContext, hooks: &codex_hooks::Hooks, request: codex_hooks::ModelRequestHookInput, -) { +) -> codex_hooks::ModelRequestHookOutcome { emit_hook_started_events(session, &step.turn, hooks.preview_model_request(&request)).await; - let events = hooks.run_model_request(request, |_| {}).await; + let (events, outcome) = hooks.run_model_request(request, |_| {}).await; emit_hook_completed_events(session, &step.turn, events).await; + outcome } #[cfg(test)] diff --git a/codex-rs/core/src/hook_runtime/sampling.rs b/codex-rs/core/src/hook_runtime/sampling.rs index fb7e675a27..9609532301 100644 --- a/codex-rs/core/src/hook_runtime/sampling.rs +++ b/codex-rs/core/src/hook_runtime/sampling.rs @@ -13,6 +13,7 @@ use crate::session::session::Session; use crate::session::step_context::StepContext; use codex_hooks::ModelRequestHookEvent; use codex_hooks::ModelRequestHookInput; +use codex_hooks::ModelRequestHookOutcome; use codex_hooks::SamplingKind; use codex_protocol::error::Result; use codex_protocol::protocol::HookCompletedEvent; @@ -118,12 +119,20 @@ struct PostHooks { } impl PostHooks { - async fn run(mut self, session: &Arc, event: ModelRequestHookEvent) { + async fn run( + mut self, + session: &Arc, + event: ModelRequestHookEvent, + ) -> ModelRequestHookOutcome { self.input.event = event; - run_model_request_hooks(session, &self.step, &self.hooks, self.input).await; + run_model_request_hooks(session, &self.step, &self.hooks, self.input).await } - async fn run_sync(mut self, session: Arc, event: ModelRequestHookEvent) { + async fn run_sync( + mut self, + session: Arc, + event: ModelRequestHookEvent, + ) -> ModelRequestHookOutcome { let (mut done, wait) = oneshot::channel(); self.input.event = event; // Dropping the waiter cancels execution while the task finishes publishing @@ -137,7 +146,7 @@ impl PostHooks { let started = Instant::now(); emit_hook_started_events(&session, turn, runs.clone()).await; let mut finished: Vec = Vec::new(); - let events = tokio::select! { + let (events, outcome) = tokio::select! { biased; () = done.closed() => { let completed_at = chrono::Utc::now().timestamp(); @@ -157,14 +166,17 @@ impl PostHooks { run, }); } - finished + (finished, ModelRequestHookOutcome::default()) } events = self.hooks.run_model_request(self.input, |event| finished.push(event.clone())) => events, }; emit_hook_completed_events(&session, turn, events).await; - let _ = done.send(()); + let _ = done.send(outcome); }); - let _ = wait.await; + wait.await.unwrap_or_else(|_| ModelRequestHookOutcome { + invalid_price: Some("synchronous hook task exited without reporting its charge".into()), + ..Default::default() + }) } fn schedule(self, session: Arc, event: ModelRequestHookEvent) { @@ -198,7 +210,7 @@ impl SamplingAttempt { pub(crate) fn start_post_hooks( &mut self, event: ModelRequestHookEvent, - ) -> Option + Send + 'static> { + ) -> Option + Send + 'static> { let post = self.post.take()?; let session = Arc::clone(&self.session); if post.mode == HookExecutionMode::Sync { diff --git a/codex-rs/core/src/lib.rs b/codex-rs/core/src/lib.rs index b6ece36a24..a33df95fc9 100644 --- a/codex-rs/core/src/lib.rs +++ b/codex-rs/core/src/lib.rs @@ -180,6 +180,7 @@ pub use agent::host::PreparedChildContext; pub use agent::host::RestrictRootCapabilities; pub use agent::host::ToolInvocationContext; pub use agent::host::UsageAccountingDecision; +pub use codex_hooks::HookCharge; pub use thread_spawn::ThreadCreateRequest; pub use thread_spawn::ThreadSpawnError; pub use thread_spawn::ThreadSpawnResult; diff --git a/codex-rs/core/src/responses_retry.rs b/codex-rs/core/src/responses_retry.rs index d33caa262d..79238cb0c7 100644 --- a/codex-rs/core/src/responses_retry.rs +++ b/codex-rs/core/src/responses_retry.rs @@ -36,6 +36,7 @@ pub(crate) fn is_terminal_sampling_outcome(error: &CodexErr) -> bool { matches!( error.details(), CodexErrorDetails::ResponseIncomplete(_) + | CodexErrorDetails::UsageAccountingFailed(_) | CodexErrorDetails::SessionBudgetExceeded | CodexErrorDetails::InferenceHookDenied { .. } ) diff --git a/codex-rs/core/src/rollout_budget.rs b/codex-rs/core/src/rollout_budget.rs index 5e2c992bbc..1b13b0fc7a 100644 --- a/codex-rs/core/src/rollout_budget.rs +++ b/codex-rs/core/src/rollout_budget.rs @@ -51,11 +51,28 @@ impl RolloutBudget { } /// Records usage and returns whether an enforced budget is exhausted. - pub(crate) fn record_usage(&self, usage: &TokenUsage) -> CodexResult { + pub(crate) fn record_usage( + &self, + usage: Option<&TokenUsage>, + hook_charge: codex_hooks::HookCharge, + ) -> CodexResult { let Some(mut state) = self.lock() else { return Ok(false); }; - let units = if let Some(units) = usage.codex_rollout_budget_units.as_ref() { + if !hook_charge.units.is_finite() || hook_charge.units < 0.0 { + return Err(CodexErr::Fatal("invalid rollout budget charge".into())); + } + if hook_charge.overflowed { + // All allowances are finite. No future nonnegative receipt can make + // this total representable; the remaining allowance is known to be zero. + state.posted.add(f64::INFINITY); + if state.config.enforce_limit { + self.stop_new_tools(); + } + } + let provider_units = if let Some(units) = + usage.and_then(|usage| usage.codex_rollout_budget_units.as_ref()) + { let units = units.as_f64().unwrap_or(f64::NAN); if !units.is_finite() || units < 0.0 { return Err(CodexErr::Fatal( @@ -64,15 +81,26 @@ impl RolloutBudget { )); } units - } else { + } else if let Some(usage) = usage { usage.output_tokens.max(0) as f64 * state.config.sampling_token_weight + usage.non_cached_input() as f64 * state.config.prefill_token_weight + } else { + 0.0 }; - state.posted.add(units); + if state.posted.total().is_infinite() { + return Ok(state.config.enforce_limit); + } + state.posted.add(provider_units); + state.posted.add(hook_charge.units); + if !state.posted.total().is_finite() { + if state.config.enforce_limit { + self.stop_new_tools(); + } + return Err(CodexErr::Fatal("invalid rollout budget charge".into())); + } // Equality is allowed, including one rounding step (0.1 + 0.2 versus 0.3). let exhausted = state.config.enforce_limit - && (state.posted.total().is_infinite() - || state.posted.total() > state.config.limit_budget.next_up()); + && state.posted.total() > state.config.limit_budget.next_up(); if exhausted { self.stop_new_tools(); } diff --git a/codex-rs/core/src/session/rollout_budget.rs b/codex-rs/core/src/session/rollout_budget.rs index e1d5722e4e..12bbc11bbb 100644 --- a/codex-rs/core/src/session/rollout_budget.rs +++ b/codex-rs/core/src/session/rollout_budget.rs @@ -3,11 +3,13 @@ use super::turn_context::TurnContext; use crate::agent::host::AgentRuntimeServices; use crate::agent::host::AgentUsageReport; use crate::agent::host::UsageAccountingDecision; +use crate::client_common::SamplingUsage; use crate::context::ContextualUserFragment; use crate::rollout_budget::RolloutBudget; use codex_protocol::error::CodexErr; use codex_protocol::error::CodexErrorDetails; use codex_protocol::error::Result as CodexResult; +use codex_protocol::protocol::TokenUsage; pub(super) async fn maybe_record_reminder( sess: &Session, @@ -55,28 +57,45 @@ impl Session { pub(crate) async fn record_rollout_budget_usage( &self, turn_id: &str, - bill: &crate::client_common::SamplingUsage, + usage: &SamplingUsage, ) -> CodexResult<()> { - if bill.charge.posted { + if !usage.charge.posted { + self.record_numeric_usage(turn_id, usage.provider.as_ref(), usage.charge.hooks.charge) + .await?; + } + if let Some(message) = &usage.charge.hooks.invalid_price { + // A bad price does not erase successful siblings' contributions. + return Err(CodexErr::UsageAccountingFailed(format!( + "Invalid post-hook budget units: {message}" + ))); + } + Ok(()) + } + + async fn record_numeric_usage( + &self, + turn_id: &str, + usage: Option<&TokenUsage>, + hook_charge: codex_hooks::HookCharge, + ) -> CodexResult<()> { + if usage.is_none() && hook_charge == codex_hooks::HookCharge::default() { return Ok(()); } - let Some(usage) = bill.provider.as_ref() else { - return Ok(()); - }; let stop_new_work = match &self.agent_runtime { AgentRuntimeServices::Controller => match self .services .agent_control - .record_usage(usage.clone()) + .record_usage(usage.cloned(), hook_charge) .await { Ok(()) => false, + // A legacy controller can report a posted bill and a stop through this error. Err(error) if matches!(error.details(), CodexErrorDetails::SessionBudgetExceeded) => { true } - Err(error) => return Err(error), + Err(error) => return Err(CodexErr::UsageAccountingFailed(error.to_string())), }, AgentRuntimeServices::Host(services) => { let Some(accounting) = &services.usage_accounting else { @@ -86,11 +105,15 @@ impl Session { .report_usage(AgentUsageReport { thread_id: self.thread_id(), turn_id: turn_id.to_owned(), - usage: usage.clone(), + usage: usage.cloned(), + additional_budget_units: hook_charge.units, + additional_budget_units_overflowed: hook_charge.overflowed, }) .await .map_err(|error| { - CodexErr::Fatal(format!("Host usage accounting failed: {error}")) + CodexErr::UsageAccountingFailed(format!( + "Host usage accounting failed: {error}" + )) })?; decision == UsageAccountingDecision::Exhausted } diff --git a/codex-rs/core/src/thread_manager_tests.rs b/codex-rs/core/src/thread_manager_tests.rs index 0e44d62f33..2d7090db02 100644 --- a/codex-rs/core/src/thread_manager_tests.rs +++ b/codex-rs/core/src/thread_manager_tests.rs @@ -1976,10 +1976,13 @@ async fn spawn_internal_session_preserves_parent_lineage_without_forking_history .session .services .agent_control - .record_usage(TokenUsage { - output_tokens: 25, - ..Default::default() - }) + .record_usage( + Some(TokenUsage { + output_tokens: 25, + ..Default::default() + }), + codex_hooks::HookCharge::default(), + ) .await .expect("record reviewer usage"); let reminder = parent diff --git a/codex-rs/core/tests/suite/agent_control_tests.rs b/codex-rs/core/tests/suite/agent_control_tests.rs index 102010f05d..078a13f9bc 100644 --- a/codex-rs/core/tests/suite/agent_control_tests.rs +++ b/codex-rs/core/tests/suite/agent_control_tests.rs @@ -258,7 +258,11 @@ impl AgentControl for TestAgentControl { None } - fn record_usage(&self, _usage: TokenUsage) -> BoxFuture<'_, CodexResult<()>> { + fn record_usage( + &self, + _usage: Option, + _hook_charge: codex_core::HookCharge, + ) -> BoxFuture<'_, CodexResult<()>> { Box::pin(async { Ok(()) }) } diff --git a/codex-rs/core/tests/suite/hooks.rs b/codex-rs/core/tests/suite/hooks.rs index 9c40c05a51..d686d958d5 100644 --- a/codex-rs/core/tests/suite/hooks.rs +++ b/codex-rs/core/tests/suite/hooks.rs @@ -6,6 +6,7 @@ use anyhow::Result; use codex_config::HookStateToml; use codex_config::McpServerConfig; use codex_config::test_support::CloudConfigBundleFixture; +use codex_core::AgentRuntimeOwnership; use codex_core::ForkSnapshot; use codex_core::StartThreadOptions; use codex_core::TurnInput; @@ -4593,19 +4594,12 @@ async fn local_bundled_cleanup_hook_runs_without_saved_trust( .features .disable(Feature::ExecutorCapabilityDiscovery) .expect("disable executor capability discovery"); - let repl: McpServerConfig = serde_json::from_value(serde_json::json!({ - "url": repl_url, - "environment_id": super::rmcp_client::remote_aware_environment_id(), - })) - .expect("valid MCP configuration"); - config - .mcp_servers - .set( - [(String::from(mcp_server_name), repl)] - .into_iter() - .collect(), - ) - .expect("configure MCP server"); + configure_hook_mcp( + config, + mcp_server_name, + &repl_url, + &super::rmcp_client::remote_aware_environment_id(), + ); }); let test = builder.build_with_auto_env(&server).await?; assert!(!test.config.bypass_hook_trust); @@ -6058,6 +6052,22 @@ async fn post_tool_use_records_apply_patch_context_with_edit_alias() -> Result<( Ok(()) } +fn configure_hook_mcp( + config: &mut codex_core::config::Config, + name: &str, + url: &str, + environment_id: &str, +) { + let server: McpServerConfig = serde_json::from_value(json!({ + "url": url, "environment_id": environment_id, + })) + .expect("valid MCP configuration"); + config + .mcp_servers + .set([(name.to_owned(), server)].into_iter().collect()) + .expect("configure MCP server"); +} + pub(super) fn write_lifecycle_hooks(home: &Path, events: &[&str]) -> Result<()> { let mut hooks = serde_json::Map::new(); for event in events { @@ -6190,6 +6200,7 @@ enum ToolDispatchCase { SyncHook, InterruptedHook, ExhaustedHook, + OverflowHook(AgentRuntimeOwnership), } #[test_case::test_case(ToolDispatchCase::Eager; "default runs the tool before the response ends")] @@ -6198,6 +6209,8 @@ enum ToolDispatchCase { #[test_case::test_case(ToolDispatchCase::SyncHook; "streaming output and tools precede a synchronous hook")] #[test_case::test_case(ToolDispatchCase::InterruptedHook; "interrupt discards the held response and its charge")] #[test_case::test_case(ToolDispatchCase::ExhaustedHook; "the response bill blocks its own tool")] +#[test_case::test_case(ToolDispatchCase::OverflowHook(AgentRuntimeOwnership::Host); "the host receives an overflow lower bound and keeps its policy")] +#[test_case::test_case(ToolDispatchCase::OverflowHook(AgentRuntimeOwnership::Controller); "a native overflow closes even the largest allowance")] #[tokio::test] async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> Result<()> { skip_if_no_network!(Ok(())); @@ -6206,20 +6219,68 @@ async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> use ToolDispatchCase::Eager; use ToolDispatchCase::ExhaustedHook; use ToolDispatchCase::InterruptedHook; + use ToolDispatchCase::OverflowHook; use ToolDispatchCase::SyncHook; const MARKER: &str = "tool-dispatched"; const STREAMED: &str = "Still streaming."; - let buffered = matches!(case, AfterComplete | InterruptedHook | ExhaustedHook); + let buffered = matches!( + case, + AfterComplete | InterruptedHook | ExhaustedHook | OverflowHook(_) + ); let hook_async = match case { Eager | AfterComplete => None, AsyncHook => Some(true), - SyncHook | InterruptedHook | ExhaustedHook => Some(false), + SyncHook | InterruptedHook | ExhaustedHook | OverflowHook(_) => Some(false), }; + // The native controls both spend 98 of 100. Only the successful +3 price + // crosses the limit; the failed sibling's reported 999 never counts. + let price_tools: &[&str] = match case { + SyncHook => &["failed"], + InterruptedHook | ExhaustedHook => &["price", "failed"], + OverflowHook(_) => &["price", "second_price"], + _ => &[], + }; + let pricing = if price_tools.is_empty() { + None + } else { + let server = start_mock_server().await; + mount_hook_mcp(&server, "billing", price_tools, move |params| { + if matches!(case, OverflowHook(_)) { + let output = if params["arguments"]["response_id"] == "first" { + json!({"extra_codex_rollout_budget_units":1e308}) + } else { + json!({}) + }; + json!({"content":[], "structuredContent":output}) + } else if params["name"] == "failed" { + json!({"isError":true, "content":[{"type":"text","text":"failed"}], + "structuredContent":{"extra_codex_rollout_budget_units":999}}) + } else { + // Turn B must report its own 3, not the interrupted first response's 31. + let units = + if case == InterruptedHook && params["arguments"]["response_id"] != "second" { + 31 + } else { + 3 + }; + json!({"content":[], "structuredContent":{"extra_codex_rollout_budget_units":units}}) + } + }) + .await; + Some(server) + }; + let pricing_url = pricing + .as_ref() + .map(|server| format!("{}/repl", server.uri())); let (finish_stream, gate) = oneshot::channel(); let mut completed = ev_completed_with_tokens("first", /*total_tokens*/ 42); completed["response"]["usage"]["codex_rollout_budget_units"] = - json!(if case == ExhaustedHook { 101 } else { 1 }); + json!(if matches!(case, SyncHook | ExhaustedHook) { + 98 + } else { + 1 + }); let first = vec![ StreamingSseChunk { gate: None, @@ -6243,9 +6304,16 @@ async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> body: sse_event(completed), }, ]; + let second_bill = if case == InterruptedHook { + let mut completed = ev_completed_with_tokens("second", /*total_tokens*/ 7); + completed["response"]["usage"]["codex_rollout_budget_units"] = json!(7); + completed + } else { + ev_completed("second") + }; let second = vec![StreamingSseChunk { gate: None, - body: sse(vec![ev_response_created("second"), ev_completed("second")]), + body: sse(vec![ev_response_created("second"), second_bill]), }]; let (server, _) = start_streaming_sse_server(vec![first, second]).await; let accounting = Arc::new(super::rollout_budget::HostAccounting::default()); @@ -6262,20 +6330,33 @@ async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> let post = format!( r#"python3 -c 'import json, socket, sys; json.load(sys.stdin).get("response_id") == "first" and socket.create_connection(("127.0.0.1", {port})).recv(1)'"# ); - let hooks = json!({"PostModelRequest": [{"hooks": [{ + let mut group = vec![json!({ "type": "command", "command": post, "async": hook_async, - }]}]}); + })]; + group.extend(price_tools.iter().map(|tool| json!({ + "type": "mcp_tool", "server": "billing", "tool": tool, + "input": {"response_id": "${response_id}"} + }))); + let hooks = json!({"PostModelRequest": [{"hooks": group}]}); fs::write(home.join("hooks.json"), json!({"hooks": hooks}).to_string()) .expect("write hook configuration"); } }) .with_config(move |config| { + if let Some(url) = &pricing_url { + configure_hook_mcp(config, "billing", url, codex_config::DEFAULT_MCP_SERVER_ENVIRONMENT_ID); + } if hook_async.is_some() { trust_discovered_hooks(config); } if matches!(case, Eager | SyncHook | ExhaustedHook) { config.rollout_budget = Some(super::rollout_budget::rollout_budget()); } + if case == OverflowHook(AgentRuntimeOwnership::Controller) { + let mut budget = super::rollout_budget::rollout_budget(); + budget.limit_budget = f64::MAX; + config.rollout_budget = Some(budget); + } // The builder changes cwd after loading config, so bind the write grant to that cwd. config.workspace_roots = vec![config.cwd.clone()]; config.permissions.set_workspace_roots(config.workspace_roots.clone()); @@ -6283,7 +6364,10 @@ async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> config.permissions.set_permission_profile(restrictive_workspace_write_profile()) .expect("allow the fixture's patch inside its temporary workspace"); }); - if case == InterruptedHook { + if matches!( + case, + InterruptedHook | OverflowHook(AgentRuntimeOwnership::Host) + ) { let mut extensions = codex_extension_api::ExtensionRegistryBuilder::new(); extensions.thread_lifecycle_contributor(accounting.clone()); builder = builder.with_extensions(Arc::new(extensions.build())); @@ -6368,39 +6452,105 @@ async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> stopped.run.status_message.as_deref(), Some("Hook cancelled because the turn was interrupted"), ); - drop(held_hook); - assert!(!marker.exists()); - let server = start_mock_server().await; - let requests = mount_sse_once(&server, responses::sse_completed("resumed")).await; - let resumed = test_codex().restart(&server, &test).await?; - resumed.submit_turn("continue after interrupt").await?; - assert!( - !requests - .single_request() - .input() - .iter() - .any(|item| item["call_id"] == "call") - ); - assert!(accounting.reports.lock().expect("usage reports").is_empty()); - return Ok(()); - } - drop(held_hook); - if case == ExhaustedHook { - let error = wait_for_event_match(&test.codex, |event| match event { - EventMsg::Error(error) => Some(error.clone()), + // Start and finish B before releasing A's hook gate. A's unread + // response must never publish its output or charge either turn. + let codex_core::TurnInputSubmission::Started { turn_id, .. } = test + .codex + .start_or_steer_turn(TurnInputRequest::user_input(vec![UserInput::Text { + text: "continue after interrupt".into(), + text_elements: vec![], + }])) + .await? + else { + anyhow::bail!("expected a new turn B"); + }; + let done = wait_for_event_match(&test.codex, |event| match event { + EventMsg::TurnComplete(done) if done.turn_id == turn_id => Some(done.clone()), _ => None, }) .await; + assert!(done.error.is_none(), "B failed: {:?}", done.error); + drop(held_hook); + assert!(!marker.exists()); + test.codex.ensure_rollout_materialized().await; + let history = test.codex.load_history(/*include_archived*/ false).await?; + assert!(!history.items.iter().any(|item| { + let RolloutItem::ResponseItem(envelope) = item else { return false; }; + match &envelope.item { + ResponseItem::CustomToolCall { call_id, .. } + | ResponseItem::CustomToolCallOutput { call_id, .. } => call_id == "call", + ResponseItem::Message { role, content, .. } => role == "assistant" + && content.iter().any(|part| matches!(part, ContentItem::OutputText { text, .. } if text == STREAMED)), + _ => false, + } + })); + let reports = accounting.reports.lock().expect("usage reports"); + let [bill] = reports.as_slice() else { + anyhow::bail!("expected only B's bill: {reports:?}"); + }; + assert_eq!(bill.turn_id, turn_id); assert_eq!( - error.codex_error_info, - Some(codex_protocol::protocol::CodexErrorInfo::SessionBudgetExceeded) + bill.usage + .as_ref() + .and_then(|usage| usage.codex_rollout_budget_units.as_ref()) + .and_then(serde_json::Number::as_f64), + Some(7.0) ); + assert_eq!(bill.additional_budget_units, 3.0); + return Ok(()); } - wait_for_event(&test.codex, |event| { - matches!(event, EventMsg::TurnComplete(_)) + drop(held_hook); + let done = wait_for_event_match(&test.codex, |event| match event { + EventMsg::TurnComplete(done) => Some(done.clone()), + _ => None, }) .await; + if let OverflowHook(owner) = case { + assert!( + done.error + .is_some_and(|error| error.message.contains("total hook cost exceeds f64 range")) + ); + assert!(!marker.exists()); + if owner == AgentRuntimeOwnership::Host { + let reports = accounting.reports.lock().expect("usage reports"); + let [bill] = reports.as_slice() else { + anyhow::bail!("expected one partial bill: {reports:?}"); + }; + assert_eq!(bill.additional_budget_units, 1e308); + assert!(bill.additional_budget_units_overflowed); + assert_eq!( + bill.usage + .as_ref() + .and_then(|usage| usage.codex_rollout_budget_units.as_ref()) + .and_then(serde_json::Number::as_f64), + Some(1.0) + ); + } + test.codex + .start_or_steer_turn(TurnInputRequest::user_input(vec![UserInput::Text { + text: "try the next turn".into(), + text_elements: vec![], + }])) + .await?; + let done = wait_for_event_match(&test.codex, |event| match event { + EventMsg::TurnComplete(done) => Some(done.clone()), + _ => None, + }) + .await; + match owner { + AgentRuntimeOwnership::Host => assert!(done.error.is_none()), + AgentRuntimeOwnership::Controller => assert_eq!( + done.error.and_then(|error| error.codex_error_info), + Some(codex_protocol::protocol::CodexErrorInfo::SessionBudgetExceeded), + ), + } + return Ok(()); + } if case == ExhaustedHook { + assert_eq!( + done.error.and_then(|error| error.codex_error_info), + Some(codex_protocol::protocol::CodexErrorInfo::SessionBudgetExceeded) + ); assert!(!marker.exists()); test.codex.ensure_rollout_materialized().await; let history = test.codex.load_history(/*include_archived*/ false).await?; @@ -6428,6 +6578,11 @@ async fn model_request_post_hook_orders_tool_dispatch(case: ToolDispatchCase) -> ["tool call", "assistant message", "aborted before dispatch"] ); } else { + assert!( + done.error.is_none(), + "unexpected turn error: {:?}", + done.error + ); assert_eq!(fs::read_to_string(marker)?, "ran\n"); } Ok(()) diff --git a/codex-rs/core/tests/suite/pending_input.rs b/codex-rs/core/tests/suite/pending_input.rs index 32af5dbd31..f0a82da3ff 100644 --- a/codex-rs/core/tests/suite/pending_input.rs +++ b/codex-rs/core/tests/suite/pending_input.rs @@ -1732,7 +1732,7 @@ async fn steer_interrupts_and_drains_websocket( .lock() .expect("usage reports") .iter() - .filter_map(|report| report.usage.codex_rollout_budget_units.as_ref()) + .filter_map(|report| report.usage.as_ref()?.codex_rollout_budget_units.as_ref()) .map(serde_json::Number::as_i64) .collect::>(); assert_eq!(billed_units, [Some(17)]); diff --git a/codex-rs/core/tests/suite/rollout_budget.rs b/codex-rs/core/tests/suite/rollout_budget.rs index fca9a03598..455fab0851 100644 --- a/codex-rs/core/tests/suite/rollout_budget.rs +++ b/codex-rs/core/tests/suite/rollout_budget.rs @@ -378,12 +378,15 @@ async fn subagent_usage_draws_from_the_shared_budget(host_accounting: bool) -> R .await; if host_accounting { let mut reports = accounting.reports.lock().expect("usage reports").clone(); - reports.sort_by_key(|report| report.usage.total_tokens); + reports.sort_by_key(|report| report.usage.as_ref().expect("provider usage").total_tokens); let root_thread_id = test.session_configured.thread_id; assert_eq!( reports .iter() - .map(|report| (report.thread_id, report.usage.total_tokens)) + .map(|report| ( + report.thread_id, + report.usage.as_ref().expect("provider usage").total_tokens + )) .collect::>(), [ (root_thread_id, 10), @@ -618,7 +621,14 @@ async fn compaction_accounting_errors_fail_without_retry( let reports = accounting.reports.lock().expect("usage reports"); assert_eq!(reports.len(), 1); assert_eq!(reports[0].thread_id, test.session_configured.thread_id); - assert_eq!(reports[0].usage.total_tokens, 10); + assert_eq!( + reports[0] + .usage + .as_ref() + .expect("provider usage") + .total_tokens, + 10 + ); } Ok(()) @@ -802,7 +812,7 @@ async fn host_accounting_reports_raw_usage_and_preserves_error_semantics( vec![AgentUsageReport { thread_id: test.session_configured.thread_id, turn_id: completed.turn_id, - usage: TokenUsage { + usage: Some(TokenUsage { input_tokens: 60, cached_input_tokens: 40, output_tokens: 15, @@ -812,7 +822,9 @@ async fn host_accounting_reports_raw_usage_and_preserves_error_semantics( serde_json::Number::from_f64(40.5).expect("finite budget units"), ), ..Default::default() - }, + }), + additional_budget_units: 0.0, + additional_budget_units_overflowed: false, }] ); Ok(()) diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rs index 7e0a2a8d2a..9fd8443652 100644 --- a/codex-rs/core/tests/suite/scenarios.rs +++ b/codex-rs/core/tests/suite/scenarios.rs @@ -4746,7 +4746,12 @@ async fn async_compaction_reuses_pending_work( .lock() .expect("usage reports") .iter() - .any(|report| report.usage.total_tokens == BACKGROUND_TOKENS); + .any(|report| { + report + .usage + .as_ref() + .is_some_and(|usage| usage.total_tokens == BACKGROUND_TOKENS) + }); release_post.send(()).expect("release the compaction hook"); assert!( !billed_while_held, @@ -4802,7 +4807,12 @@ async fn async_compaction_reuses_pending_work( let reports = accounting.reports.lock().expect("usage reports"); let charged_turns: Vec<_> = reports .iter() - .filter(|report| report.usage.total_tokens == BACKGROUND_TOKENS) + .filter(|report| { + report + .usage + .as_ref() + .is_some_and(|usage| usage.total_tokens == BACKGROUND_TOKENS) + }) .map(|report| &report.turn_id) .collect(); assert_eq!(charged_turns, [&usage("seed").turn_id]); diff --git a/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs b/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs index 4060f09d64..90dd1310cf 100644 --- a/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs +++ b/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs @@ -311,7 +311,7 @@ async fn same_manager_creation_preserves_live_bindings_and_attachments( accounting.reports.lock().expect("usage reports").as_slice(), [report] if report.thread_id == child_id && report.turn_id == turn_id - && report.usage.total_tokens == 42 + && report.usage.as_ref().is_some_and(|usage| usage.total_tokens == 42) )); let child_request = child_request.single_request(); assert_eq!(child_request.body_json()["service_tier"], "flex"); diff --git a/codex-rs/hooks/Cargo.toml b/codex-rs/hooks/Cargo.toml index d519e3b3d0..4ebb31b674 100644 --- a/codex-rs/hooks/Cargo.toml +++ b/codex-rs/hooks/Cargo.toml @@ -28,6 +28,7 @@ regex = { workspace = true } schemars = { workspace = true } serde = { workspace = true, features = ["derive"] } serde_json = { workspace = true } +serde_path_to_error = { workspace = true } sha2 = { workspace = true } tempfile = { workspace = true } tokio = { workspace = true, features = ["fs", "io-util", "process", "sync", "time"] } diff --git a/codex-rs/hooks/src/engine/command_runner.rs b/codex-rs/hooks/src/engine/command_runner.rs index 37c5d1a7cb..1c23a9e9b4 100644 --- a/codex-rs/hooks/src/engine/command_runner.rs +++ b/codex-rs/hooks/src/engine/command_runner.rs @@ -268,6 +268,7 @@ pub(crate) async fn run_command( Err(error) => (None, String::new(), String::new(), Some(error.to_string())), }; return HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::command_hook(), started_at, completed_at: chrono::Utc::now().timestamp(), @@ -432,6 +433,7 @@ fn finish_command_run( ) -> HandlerRunResult { Span::current().record("hook.command_outcome", completion.outcome); HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::command_hook(), started_at, completed_at: chrono::Utc::now().timestamp(), diff --git a/codex-rs/hooks/src/engine/mcp_runner.rs b/codex-rs/hooks/src/engine/mcp_runner.rs index 9d1285eb0c..dae2db346f 100644 --- a/codex-rs/hooks/src/engine/mcp_runner.rs +++ b/codex-rs/hooks/src/engine/mcp_runner.rs @@ -92,11 +92,18 @@ pub(crate) async fn run_mcp_tool( } .await; - let (exit_code, stdout, error, source_tool_namespace) = match result { - Ok(output) => (Some(0), output.text, None, output.source_tool_namespace), - Err(error) => (None, String::new(), Some(error.to_string()), None), + let (exit_code, stdout, error, source_tool_namespace, structured_content) = match result { + Ok(output) => ( + Some(0), + output.text, + None, + output.source_tool_namespace, + output.structured_content, + ), + Err(error) => (None, String::new(), Some(error.to_string()), None, None), }; HandlerRunResult { + structured_content, context_metadata: ContentItemMetadata::tool(source_tool_namespace.map(Into::into)), started_at, completed_at: chrono::Utc::now().timestamp(), diff --git a/codex-rs/hooks/src/engine/mcp_runner_tests.rs b/codex-rs/hooks/src/engine/mcp_runner_tests.rs index 3408b751b1..a1fe3ab723 100644 --- a/codex-rs/hooks/src/engine/mcp_runner_tests.rs +++ b/codex-rs/hooks/src/engine/mcp_runner_tests.rs @@ -31,6 +31,7 @@ impl HookMcpExecutor for RecordingExecutor { async move { self.calls.lock().expect("lock calls").push(call); Ok(HookMcpOutput { + structured_content: None, text: self.output.clone(), source_tool_namespace: Some("security".into()), }) diff --git a/codex-rs/hooks/src/engine/mod.rs b/codex-rs/hooks/src/engine/mod.rs index 5e3daf53b0..bfec9a847a 100644 --- a/codex-rs/hooks/src/engine/mod.rs +++ b/codex-rs/hooks/src/engine/mod.rs @@ -161,6 +161,7 @@ pub(crate) enum ConfiguredHandlerKind { #[derive(Debug)] pub(crate) struct HandlerRunResult { + pub structured_content: Option, pub context_metadata: codex_protocol::models::ContentItemMetadata, pub started_at: i64, pub completed_at: i64, diff --git a/codex-rs/hooks/src/engine/mod_tests.rs b/codex-rs/hooks/src/engine/mod_tests.rs index 93b065a169..cdc9f626f6 100644 --- a/codex-rs/hooks/src/engine/mod_tests.rs +++ b/codex-rs/hooks/src/engine/mod_tests.rs @@ -2305,6 +2305,7 @@ impl HookMcpExecutor for StaticMcpExecutor { self.calls.lock().expect("lock MCP calls").push(call); Ok(HookMcpOutput { text: output, + structured_content: None, source_tool_namespace: None, }) } @@ -2800,6 +2801,7 @@ async fn executor_stop_hooks_do_not_delay_stop_completion() { self.release.notified().await; Ok(HookMcpOutput { text: String::new(), + structured_content: None, source_tool_namespace: None, }) } diff --git a/codex-rs/hooks/src/events/compact.rs b/codex-rs/hooks/src/events/compact.rs index 720e097cd6..f07c4928e8 100644 --- a/codex-rs/hooks/src/events/compact.rs +++ b/codex-rs/hooks/src/events/compact.rs @@ -540,6 +540,7 @@ mod tests { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1_700_000_000, completed_at: 1_700_000_001, diff --git a/codex-rs/hooks/src/events/interrupt_tests.rs b/codex-rs/hooks/src/events/interrupt_tests.rs index 9c1b450fdd..7a54bf851f 100644 --- a/codex-rs/hooks/src/events/interrupt_tests.rs +++ b/codex-rs/hooks/src/events/interrupt_tests.rs @@ -118,6 +118,7 @@ fn handler() -> ConfiguredHandler { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1, completed_at: 2, diff --git a/codex-rs/hooks/src/events/model_request.rs b/codex-rs/hooks/src/events/model_request.rs index ed26d3cfca..783819c1f2 100644 --- a/codex-rs/hooks/src/events/model_request.rs +++ b/codex-rs/hooks/src/events/model_request.rs @@ -1,4 +1,6 @@ -//! Observation-only lifecycle hooks. Output is logged, never interpreted as control flow. +//! Sampling hooks observe attempts. Successful synchronous MCP post-hooks can +//! add a price to a completed response or to provider-reported incomplete usage. +use codex_protocol::BudgetUnitsSum; use codex_protocol::protocol::HookCompletedEvent; use codex_protocol::protocol::HookEventName; use codex_protocol::protocol::HookOutputEntry; @@ -8,6 +10,7 @@ use codex_protocol::protocol::HookRunSummary; use codex_protocol::protocol::TokenUsage; use codex_utils_absolute_path::AbsolutePathBuf; use schemars::JsonSchema; +use serde::Deserialize; use serde::Serialize; use super::common; @@ -157,19 +160,55 @@ pub(crate) fn preview( .collect() } +/// One response's successful hook prices. On overflow, units is a finite +/// subtotal of real contributions, not the price of the entire response. +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct HookCharge { + pub units: f64, + pub overflowed: bool, +} + +/// A failed observer does not erase prices reported by successful siblings. +#[derive(Debug, Default)] +pub struct ModelRequestHookOutcome { + pub charge: HookCharge, + pub invalid_price: Option, +} + +/// Structured MCP output from a synchronous post-hook. Omitted units add zero +/// to the provider's charge. +#[derive(Deserialize)] +struct PostHookOutput { + #[serde(default)] + extra_codex_rollout_budget_units: f64, +} + +type ReportedPrice = Result; + pub(crate) async fn run( engine: &ClaudeHooksEngine, request: ModelRequestHookInput, on_completed: impl FnMut(&HookCompletedEvent) + Send, -) -> Vec { +) -> (Vec, ModelRequestHookOutcome) { let matched = dispatcher::select_handlers( &engine.handlers, request.event.hook_event(), /*matcher_input*/ None, ); if matched.is_empty() { - return Vec::new(); + return Default::default(); } + let billable = matches!( + request.event, + ModelRequestHookEvent::PostModelRequest { + status: ModelRequestStatus::Completed, + .. + } | ModelRequestHookEvent::PostModelRequest { + status: ModelRequestStatus::Failed, + token_usage: Some(_), + .. + } + ); let input = match serde_json::to_value(&request) { Ok(input) => input, Err(error) => { @@ -181,10 +220,12 @@ pub(crate) async fn run( for event in &mut events { identify_run(&mut event.run, request.lifecycle_id); } - return events; + return (events, Default::default()); } }; - dispatcher::execute_handlers_with_progress( + // The dispatcher returns synchronous results in configuration order. Prices + // become visible together, only after the entire group finishes. + let results = dispatcher::execute_handlers_with_progress( engine, matched, &input, @@ -198,17 +239,40 @@ pub(crate) async fn run( }, on_completed, ) - .await - .into_iter() - .map(|result| result.completed) - .collect() + .await; + let mut outcome = ModelRequestHookOutcome::default(); + let mut reported_units = BudgetUnitsSum::default(); + let mut largest_price = 0.0_f64; + let mut events = Vec::with_capacity(results.len()); + for result in results { + if billable && let Some(price) = result.data { + match price { + Ok(units) => { + largest_price = largest_price.max(units); + reported_units.add(units); + } + Err(error) => outcome.invalid_price = Some(error), + } + } + events.push(result.completed); + } + outcome.charge.units = reported_units.total(); + if !outcome.charge.units.is_finite() { + // An individual price is a real lower bound, even if earlier f64 additions rounded up. + outcome.charge = HookCharge { + units: largest_price, + overflowed: true, + }; + outcome.invalid_price = Some("total hook cost exceeds f64 range".into()); + } + (events, outcome) } fn parse_completed( handler: &ConfiguredHandler, result: HandlerRunResult, turn_id: Option, -) -> dispatcher::ParsedHandler<()> { +) -> dispatcher::ParsedHandler> { let status = if result.error.is_none() && result.exit_code == Some(0) { HookRunStatus::Completed } else { @@ -231,12 +295,39 @@ fn parse_completed( text: error.clone(), }); } + let price = if status == HookRunStatus::Completed { + result + .structured_content + .as_ref() + .filter(|body| !body.is_null()) + .map(|body| { + if !body.is_object() { + return Err("post-hook structuredContent must be an object or null".into()); + } + let output: PostHookOutput = + serde_path_to_error::deserialize(body).map_err(|error| { + // Serde's underlying error can contain the raw hook value. + format!("invalid post-hook structuredContent.{}", error.path()) + })?; + let units = output.extra_codex_rollout_budget_units; + if units.is_finite() && units >= 0.0 { + Ok(units) + } else { + Err( + "hook extra_codex_rollout_budget_units must be finite and nonnegative" + .into(), + ) + } + }) + } else { + None + }; dispatcher::ParsedHandler { completed: HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &result, status, entries), }, - data: (), + data: price, completion_order: 0, } } diff --git a/codex-rs/hooks/src/events/post_tool_use.rs b/codex-rs/hooks/src/events/post_tool_use.rs index 58bff2fc75..32b501d71d 100644 --- a/codex-rs/hooks/src/events/post_tool_use.rs +++ b/codex-rs/hooks/src/events/post_tool_use.rs @@ -630,6 +630,7 @@ mod tests { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1_700_000_000, completed_at: 1_700_000_001, diff --git a/codex-rs/hooks/src/events/pre_tool_use.rs b/codex-rs/hooks/src/events/pre_tool_use.rs index d84b89c0d2..a07f0a60ff 100644 --- a/codex-rs/hooks/src/events/pre_tool_use.rs +++ b/codex-rs/hooks/src/events/pre_tool_use.rs @@ -814,6 +814,7 @@ mod tests { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1, completed_at: 2, diff --git a/codex-rs/hooks/src/events/session_end_tests.rs b/codex-rs/hooks/src/events/session_end_tests.rs index b0e8267c58..fd63ccf8bf 100644 --- a/codex-rs/hooks/src/events/session_end_tests.rs +++ b/codex-rs/hooks/src/events/session_end_tests.rs @@ -43,6 +43,7 @@ fn session_end_ignores_successful_output() { let completed = parse_completed( &handler(/*matcher*/ None), HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1, completed_at: 2, diff --git a/codex-rs/hooks/src/events/session_start.rs b/codex-rs/hooks/src/events/session_start.rs index 0da8b21706..1c5cab9ce9 100644 --- a/codex-rs/hooks/src/events/session_start.rs +++ b/codex-rs/hooks/src/events/session_start.rs @@ -564,6 +564,7 @@ mod tests { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1, completed_at: 2, diff --git a/codex-rs/hooks/src/events/stop.rs b/codex-rs/hooks/src/events/stop.rs index 83cc6f6585..78bdd3c76d 100644 --- a/codex-rs/hooks/src/events/stop.rs +++ b/codex-rs/hooks/src/events/stop.rs @@ -702,6 +702,7 @@ mod tests { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1, completed_at: 2, diff --git a/codex-rs/hooks/src/events/user_prompt_submit.rs b/codex-rs/hooks/src/events/user_prompt_submit.rs index 17342cad9d..476b5953ae 100644 --- a/codex-rs/hooks/src/events/user_prompt_submit.rs +++ b/codex-rs/hooks/src/events/user_prompt_submit.rs @@ -483,6 +483,7 @@ mod tests { fn run_result(exit_code: Option, stdout: &str, stderr: &str) -> HandlerRunResult { HandlerRunResult { + structured_content: None, context_metadata: codex_protocol::models::ContentItemMetadata::harness(), started_at: 1, completed_at: 2, diff --git a/codex-rs/hooks/src/lib.rs b/codex-rs/hooks/src/lib.rs index 79f2a8be14..54f1a15920 100644 --- a/codex-rs/hooks/src/lib.rs +++ b/codex-rs/hooks/src/lib.rs @@ -134,7 +134,9 @@ pub fn hook_key( ) } +pub use events::model_request::HookCharge; pub use events::model_request::ModelRequestHookEvent; pub use events::model_request::ModelRequestHookInput; +pub use events::model_request::ModelRequestHookOutcome; pub use events::model_request::ModelRequestStatus; pub use events::model_request::SamplingKind; diff --git a/codex-rs/hooks/src/mcp.rs b/codex-rs/hooks/src/mcp.rs index 249ccfb945..9ac93b172a 100644 --- a/codex-rs/hooks/src/mcp.rs +++ b/codex-rs/hooks/src/mcp.rs @@ -17,9 +17,10 @@ pub struct HookMcpCall { pub timeout: Duration, } -/// Text returned by an MCP hook and the callable namespace that supplied it. +/// The MCP hook's text, structured result, and originating callable namespace. pub struct HookMcpOutput { pub text: String, + pub structured_content: Option, pub source_tool_namespace: Option, } diff --git a/codex-rs/hooks/src/registry.rs b/codex-rs/hooks/src/registry.rs index 7e3954673e..278890f745 100644 --- a/codex-rs/hooks/src/registry.rs +++ b/codex-rs/hooks/src/registry.rs @@ -382,7 +382,10 @@ impl Hooks { &self, request: crate::ModelRequestHookInput, on_completed: impl FnMut(&HookCompletedEvent) + Send, - ) -> Vec { + ) -> ( + Vec, + crate::ModelRequestHookOutcome, + ) { crate::events::model_request::run(&self.engine, request, on_completed).await } } diff --git a/codex-rs/protocol/src/budget_units.rs b/codex-rs/protocol/src/budget_units.rs index 2a5bc7bef4..503fefd706 100644 --- a/codex-rs/protocol/src/budget_units.rs +++ b/codex-rs/protocol/src/budget_units.rs @@ -1,4 +1,5 @@ -//! Numerical accounting for nonnegative rollout-budget units. +//! Numerical accounting for nonnegative rollout-budget units. The same sum is +//! used for one response's hook contributions and for the rollout's posted bills. /// Accumulate validated, nonnegative `f64` charges without dropping every small /// contribution after a large one. An unrepresentable total stays infinite. diff --git a/codex-rs/protocol/src/error.rs b/codex-rs/protocol/src/error.rs index 9884549607..6e3e342a92 100644 --- a/codex-rs/protocol/src/error.rs +++ b/codex-rs/protocol/src/error.rs @@ -248,6 +248,9 @@ pub enum CodexErrorDetails { GatewayLoginRequired(String), #[error("Fatal error: {0}")] Fatal(String), + /// The provider attempt ended. Retrying inference cannot settle its bill. + #[error("{0}")] + UsageAccountingFailed(String), // ----------------------------------------------------------------- // Automatic conversions for common external error types // ----------------------------------------------------------------- @@ -420,6 +423,7 @@ impl CodexErr { UnsupportedOperation(message: String), RefreshTokenFailed(error: RefreshTokenFailedError), Fatal(message: String), + UsageAccountingFailed(message: String), Io(error: io::Error), Json(error: serde_json::Error), #[cfg(target_os = "linux")] @@ -484,6 +488,7 @@ impl CodexErr { | CodexErrorDetails::Interrupted | CodexErrorDetails::EnvVar(_) | CodexErrorDetails::Fatal(_) + | CodexErrorDetails::UsageAccountingFailed(_) | CodexErrorDetails::UsageNotIncluded | CodexErrorDetails::QuotaExceeded | CodexErrorDetails::InvalidImageRequest()