Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add lifecycle hooks for inter-agent messages (#55657)

Ruslan Nigmatullin66d0de9983e8
diff --git a/codex-rs/core/src/agent/api.rs b/codex-rs/core/src/agent/api.rs
index 622c451343..e23f1ead6b 100644
--- a/codex-rs/core/src/agent/api.rs
+++ b/codex-rs/core/src/agent/api.rs
@@ -70,10 +70,7 @@ pub trait AgentControl: Send + Sync {
/// Take queued, non-turn-starting mail in order, without loading the recipient.
/// This in-memory operation performs no I/O; returning transfers ownership to the caller.
- fn take_mailbox(
- &self,
- agent: ThreadId,
- ) -> Vec<codex_protocol::protocol::InterAgentCommunication>;
+ fn take_mailbox(&self, agent: ThreadId) -> Vec<crate::PendingAgentMessage>;
/// Observe whether unread mail is available. Subscribe before the first read so
/// arrivals cannot be missed; notifications do not consume mail or start a turn.
diff --git a/codex-rs/core/src/agent/control.rs b/codex-rs/core/src/agent/control.rs
index a1a3a9b867..765725df7b 100644
--- a/codex-rs/core/src/agent/control.rs
+++ b/codex-rs/core/src/agent/control.rs
@@ -9,6 +9,7 @@ use crate::agent::types::AgentMetadata;
use crate::agent::types::LiveAgent;
use crate::agent_communication::AgentCommunicationContext;
use crate::agent_communication::AgentCommunicationKind;
+use crate::agent_communication::MessageDelivery;
use crate::config::Config;
use crate::config::RolloutBudgetConfig;
use crate::context::ContextualUserFragment;
@@ -25,6 +26,7 @@ use codex_history::InitialHistory;
use codex_history::ResumedHistory;
use codex_history::RolloutItem;
use codex_protocol::AgentPath;
+use codex_protocol::ResponseItemId;
use codex_protocol::SessionId;
use codex_protocol::ThreadId;
use codex_protocol::error::CodexErr;
@@ -258,10 +260,20 @@ impl LocalAgentControl {
&self,
agent_id: ThreadId,
state: &Arc<ThreadManagerState>,
- communication: InterAgentCommunication,
+ mut communication: InterAgentCommunication,
context: AgentCommunicationContext,
start_options: TurnStartOptions,
) -> CodexResult<String> {
+ let observers = state.extensions.message_lifecycle_contributors();
+ let delivery = (!observers.is_empty()).then(|| {
+ let message_id = communication
+ .id
+ .take()
+ .filter(|id| !id.is_empty())
+ .unwrap_or_else(|| ResponseItemId::new("amsg"));
+ communication.id = Some(message_id.clone());
+ MessageDelivery::publish(context.sender_thread_id, message_id, observers)
+ });
let communication_for_log =
crate::agent_communication::logging_enabled().then(|| communication.clone());
{
@@ -274,7 +286,7 @@ impl LocalAgentControl {
self.runtime.mailboxes.enqueue(
agent_id,
Some(submission_id.clone()),
- vec![communication],
+ vec![crate::PendingAgentMessage::new(communication, delivery)],
)?;
if let Some(communication) = communication_for_log {
crate::agent_communication::emit_agent_communication_send(
@@ -309,6 +321,7 @@ impl LocalAgentControl {
},
parent_turn_id,
root_turn_id,
+ delivery,
)
.await,
)
@@ -338,6 +351,7 @@ impl LocalAgentControl {
Op::Interrupt,
/*parent_turn_id*/ None,
/*root_turn_id*/ None,
+ /*message_delivery*/ None,
)
.await,
)
diff --git a/codex-rs/core/src/agent/control/api.rs b/codex-rs/core/src/agent/control/api.rs
index 4087cde92b..0426ca39d8 100644
--- a/codex-rs/core/src/agent/control/api.rs
+++ b/codex-rs/core/src/agent/control/api.rs
@@ -178,10 +178,7 @@ impl AgentControl for LocalAgentControl {
})
}
- fn take_mailbox(
- &self,
- agent: ThreadId,
- ) -> Vec<codex_protocol::protocol::InterAgentCommunication> {
+ fn take_mailbox(&self, agent: ThreadId) -> Vec<crate::PendingAgentMessage> {
self.runtime.mailboxes.take(agent)
}
diff --git a/codex-rs/core/src/agent/control/legacy.rs b/codex-rs/core/src/agent/control/legacy.rs
index 1c0b6e2fd7..743bb752b0 100644
--- a/codex-rs/core/src/agent/control/legacy.rs
+++ b/codex-rs/core/src/agent/control/legacy.rs
@@ -23,6 +23,7 @@ impl LocalAgentControl {
Op::Shutdown {},
/*parent_turn_id*/ None,
/*root_turn_id*/ None,
+ /*message_delivery*/ None,
)
.await
};
@@ -35,6 +36,7 @@ impl LocalAgentControl {
Op::Shutdown {},
/*parent_turn_id*/ None,
/*root_turn_id*/ None,
+ /*message_delivery*/ None,
)
.await
};
diff --git a/codex-rs/core/src/agent/control/mailbox.rs b/codex-rs/core/src/agent/control/mailbox.rs
index 6b5f4d88de..c5e7e06ee8 100644
--- a/codex-rs/core/src/agent/control/mailbox.rs
+++ b/codex-rs/core/src/agent/control/mailbox.rs
@@ -1,12 +1,12 @@
//! Retains queue-only mail while local sessions are unloaded.
//! Eviction transfers mail before releasing the recipient's residency guard.
+use crate::PendingAgentMessage;
use crate::agent_communication::PENDING_MAILBOX_MESSAGES;
use codex_diagnostics::GaugeGuard;
use codex_protocol::ThreadId;
use codex_protocol::error::CodexErr;
use codex_protocol::error::Result;
-use codex_protocol::protocol::InterAgentCommunication;
use std::collections::HashMap;
use std::sync::Mutex;
use std::sync::PoisonError;
@@ -28,7 +28,7 @@ struct Mailbox {
struct StoredMail {
id: Option<String>,
- communication: InterAgentCommunication,
+ communication: PendingAgentMessage,
_diagnostics_guard: GaugeGuard,
}
@@ -37,7 +37,7 @@ impl Mailboxes {
&self,
agent: ThreadId,
id: Option<String>,
- messages: Vec<InterAgentCommunication>,
+ messages: Vec<PendingAgentMessage>,
) -> Result<()> {
let mut mailboxes = self.0.lock().unwrap_or_else(PoisonError::into_inner);
let mailbox = mailboxes
@@ -56,7 +56,7 @@ impl Mailboxes {
Ok(())
}
- pub(super) fn take(&self, agent: ThreadId) -> Vec<InterAgentCommunication> {
+ pub(super) fn take(&self, agent: ThreadId) -> Vec<PendingAgentMessage> {
let mut mailboxes = self.0.lock().unwrap_or_else(PoisonError::into_inner);
let Some(mailbox) = mailboxes
.as_mut()
@@ -94,18 +94,20 @@ impl Mailboxes {
}
pub(super) fn remove(&self, agent: ThreadId) {
- if let Some(mailboxes) = self
+ // Dropping pending mail can run extension destructors. Release the lock first.
+ let mailbox = self
.0
.lock()
.unwrap_or_else(PoisonError::into_inner)
.as_mut()
- {
- mailboxes.remove(&agent);
- }
+ .and_then(|mailboxes| mailboxes.remove(&agent));
+ drop(mailbox);
}
pub(super) fn close(&self) {
- if let Some(mailboxes) = self.0.lock().unwrap_or_else(PoisonError::into_inner).take() {
+ // Detach under the lock, then notify readers and drop pending mail outside it.
+ let mailboxes = self.0.lock().unwrap_or_else(PoisonError::into_inner).take();
+ if let Some(mailboxes) = mailboxes {
for mailbox in mailboxes.values() {
mailbox.state.send_replace(false);
}
diff --git a/codex-rs/core/src/agent_communication.rs b/codex-rs/core/src/agent_communication.rs
index 9925d61f9f..880085285a 100644
--- a/codex-rs/core/src/agent_communication.rs
+++ b/codex-rs/core/src/agent_communication.rs
@@ -1,5 +1,19 @@
+//! Direct-message diagnostics and delivery ownership across queues and eviction.
+//! Only history commitment consumes mail; dropping its last owner releases its attachments.
+
+use codex_extension_api::ExtensionData;
+use codex_extension_api::MessageLifecycleContributor;
+use codex_extension_api::MessageLifecycleInput;
+use codex_protocol::ResponseItemId;
use codex_protocol::ThreadId;
use codex_protocol::protocol::InterAgentCommunication;
+use serde::Deserialize;
+use serde::Serialize;
+use std::fmt;
+use std::ops::Deref;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::PoisonError;
pub(crate) static PENDING_MAILBOX_MESSAGES: codex_diagnostics::Gauge =
codex_diagnostics::Gauge::new("core.mailbox.pending");
@@ -28,7 +42,7 @@ impl AgentCommunicationKind {
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct AgentCommunicationContext {
kind: AgentCommunicationKind,
- sender_thread_id: ThreadId,
+ pub(crate) sender_thread_id: ThreadId,
}
impl AgentCommunicationContext {
@@ -79,3 +93,92 @@ pub(crate) fn emit_agent_communication_receive(communication_id: &str) {
"agent communication"
);
}
+
+/// Pending mail with shared ownership of its captured publication state.
+/// Serialization preserves the protocol shape; restored historical mail is not republished.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct PendingAgentMessage {
+ communication: InterAgentCommunication,
+ #[serde(skip)]
+ pub(crate) delivery: Option<MessageDelivery>,
+}
+
+impl From<InterAgentCommunication> for PendingAgentMessage {
+ fn from(communication: InterAgentCommunication) -> Self {
+ Self::new(communication, /*delivery*/ None)
+ }
+}
+
+impl Deref for PendingAgentMessage {
+ type Target = InterAgentCommunication;
+ fn deref(&self) -> &Self::Target {
+ &self.communication
+ }
+}
+
+impl PartialEq for PendingAgentMessage {
+ fn eq(&self, other: &Self) -> bool {
+ self.communication == other.communication
+ }
+}
+
+impl PendingAgentMessage {
+ pub(crate) fn new(
+ communication: InterAgentCommunication,
+ delivery: Option<MessageDelivery>,
+ ) -> Self {
+ Self {
+ communication,
+ delivery,
+ }
+ }
+}
+
+/// The publication state retained until this delivery is consumed or abandoned.
+struct MessagePublication {
+ input: MessageLifecycleInput,
+ observers: Box<[Arc<dyn MessageLifecycleContributor>]>,
+}
+
+/// Clones follow one logical delivery through queues and share its consumption state.
+#[derive(Clone)]
+pub(crate) struct MessageDelivery(Arc<Mutex<Option<MessagePublication>>>);
+
+impl MessageDelivery {
+ pub(crate) fn publish(
+ sender: ThreadId,
+ message_id: ResponseItemId,
+ observers: &[Arc<dyn MessageLifecycleContributor>],
+ ) -> Self {
+ let input = MessageLifecycleInput {
+ sender,
+ data: ExtensionData::new(message_id.to_string()),
+ message_id,
+ };
+ for observer in observers {
+ observer.on_publish(&input);
+ }
+ let publication = MessagePublication {
+ input,
+ observers: observers.into(),
+ };
+ Self(Arc::new(Mutex::new(Some(publication))))
+ }
+
+ /// Commit this delivery and release its publication state, even if clones remain.
+ pub(crate) fn consumed(&self, recipient: ThreadId) {
+ let publication = self.0.lock().unwrap_or_else(PoisonError::into_inner).take();
+ if let Some(publication) = publication {
+ for observer in &publication.observers {
+ observer.on_consumed(&publication.input, recipient);
+ }
+ }
+ }
+}
+
+impl fmt::Debug for MessageDelivery {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("MessageDelivery").finish_non_exhaustive()
+ }
+}
diff --git a/codex-rs/core/src/codex_delegate.rs b/codex-rs/core/src/codex_delegate.rs
index 54d0d201d9..d6742fc218 100644
--- a/codex-rs/core/src/codex_delegate.rs
+++ b/codex-rs/core/src/codex_delegate.rs
@@ -311,6 +311,7 @@ pub(crate) async fn run_codex_thread_one_shot(
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
})
.await;
child_cancel.cancel();
diff --git a/codex-rs/core/src/codex_delegate_tests.rs b/codex-rs/core/src/codex_delegate_tests.rs
index 9288d30001..9b6c0aeca4 100644
--- a/codex-rs/core/src/codex_delegate_tests.rs
+++ b/codex-rs/core/src/codex_delegate_tests.rs
@@ -163,6 +163,7 @@ async fn forward_ops_preserves_submission_trace_context() {
parent_turn_id: Some("parent-turn".to_string()),
root_turn_id: Some("root-turn".to_string()),
residency_guard: None,
+ message_delivery: None,
};
tx_ops.send(submission).await.unwrap();
drop(tx_ops);
diff --git a/codex-rs/core/src/codex_thread.rs b/codex-rs/core/src/codex_thread.rs
index f174a728dd..8652ebde0c 100644
--- a/codex-rs/core/src/codex_thread.rs
+++ b/codex-rs/core/src/codex_thread.rs
@@ -404,7 +404,7 @@ impl CodexThread {
self.io
.submit_with_trace(
op, trace, /*parent_turn_id*/ None, /*root_turn_id*/ None,
- /*residency_guard*/ None,
+ /*residency_guard*/ None, /*message_delivery*/ None,
)
.await
}
@@ -550,6 +550,7 @@ impl CodexThread {
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
})
.await
.map_err(|_| CodexErr::Fatal("thread session has stopped".to_string()))?;
diff --git a/codex-rs/core/src/lib.rs b/codex-rs/core/src/lib.rs
index 97600eb9e6..390b658b60 100644
--- a/codex-rs/core/src/lib.rs
+++ b/codex-rs/core/src/lib.rs
@@ -77,6 +77,7 @@ pub use agent::types::SpawnAgentForkMode;
pub use agent::types::SpawnAgentOptions;
pub use rollout_budget::RolloutBudgetReminder;
mod agent_communication;
+pub use agent_communication::PendingAgentMessage;
mod agent_message_board;
pub use agent_message_board::install_agent_message_board;
mod attestation;
diff --git a/codex-rs/core/src/session/handlers.rs b/codex-rs/core/src/session/handlers.rs
index 4b299407c6..5ded792689 100644
--- a/codex-rs/core/src/session/handlers.rs
+++ b/codex-rs/core/src/session/handlers.rs
@@ -34,7 +34,6 @@ use codex_protocol::protocol::Event;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::GuardianAssessmentEvent;
use codex_protocol::protocol::GuardianAssessmentStatus;
-use codex_protocol::protocol::InterAgentCommunication;
use codex_protocol::protocol::Op;
use codex_protocol::protocol::RealtimeConversationListVoicesResponseEvent;
use codex_protocol::protocol::RealtimeVoicesList;
@@ -83,7 +82,7 @@ pub async fn realtime_conversation_list_voices(sess: &Session, sub_id: String) {
pub async fn inter_agent_communication(
sess: &Arc<Session>,
sub_id: String,
- communication: InterAgentCommunication,
+ communication: crate::PendingAgentMessage,
start_options: codex_protocol::turn_input::TurnStartOptions,
) {
let trigger_turn = communication.trigger_turn;
@@ -657,6 +656,8 @@ pub(super) async fn submission_loop(
communication,
start_options,
} => {
+ let communication =
+ crate::PendingAgentMessage::new(communication, sub.message_delivery);
inter_agent_communication(&sess, sub.id.clone(), communication, start_options)
.await;
false
diff --git a/codex-rs/core/src/session/input_queue.rs b/codex-rs/core/src/session/input_queue.rs
index 3f15119a28..21d31dd791 100644
--- a/codex-rs/core/src/session/input_queue.rs
+++ b/codex-rs/core/src/session/input_queue.rs
@@ -44,7 +44,7 @@ pub enum TurnInput {
// Preserve the existing serialized format while carrying injection API metadata
// through the in-memory queue.
ResponseItem(#[serde(with = "turn_input_response_item")] ResponseItemEnvelope),
- InterAgentCommunication(InterAgentCommunication),
+ InterAgentCommunication(crate::PendingAgentMessage),
}
mod turn_input_response_item {
@@ -101,7 +101,7 @@ pub(crate) struct InputQueue {
}
pub(crate) struct PendingMailboxCommunication {
- pub(crate) communication: InterAgentCommunication,
+ pub(crate) communication: crate::PendingAgentMessage,
start_options: TurnStartOptions,
_diagnostics_guard: GaugeGuard,
}
@@ -199,14 +199,14 @@ impl InputQueue {
turn_state
.pending_input
.items
- .push(TurnInput::InterAgentCommunication(communication));
+ .push(TurnInput::InterAgentCommunication(communication.into()));
self.activity_tx.send_replace(InputQueueActivity::Mailbox);
true
}
pub(crate) async fn enqueue_mailbox_communication(
&self,
- communication: InterAgentCommunication,
+ communication: crate::PendingAgentMessage,
start_options: TurnStartOptions,
) {
let mut pending = self.mailbox_pending_mails.lock().await;
@@ -318,7 +318,10 @@ impl InputQueue {
pub(crate) async fn clear_pending(&self, active_turn: &ActiveTurn) {
let mut turn_state = active_turn.turn_state.lock().await;
turn_state.clear_pending_waiters();
- turn_state.pending_input = TurnInputQueue::default();
+ // Pending mail can own extension attachments whose destructors need the lock released.
+ let pending_input = std::mem::take(&mut turn_state.pending_input);
+ drop(turn_state);
+ drop(pending_input);
}
pub(crate) async fn defer_mailbox_delivery_to_next_turn(
@@ -586,7 +589,7 @@ mod tests {
/*trigger_turn*/ false,
);
input_queue
- .enqueue_mailbox_communication(mail_one, Default::default())
+ .enqueue_mailbox_communication(mail_one.into(), Default::default())
.await;
let mail_two = make_mail(
AgentPath::root(),
@@ -595,7 +598,7 @@ mod tests {
/*trigger_turn*/ false,
);
input_queue
- .enqueue_mailbox_communication(mail_two, Default::default())
+ .enqueue_mailbox_communication(mail_two.into(), Default::default())
.await;
activity_rx.changed().await.expect("mailbox update");
@@ -676,7 +679,7 @@ mod tests {
input_queue
.extend_pending_input_for_turn_state(
&turn_state,
- vec![TurnInput::InterAgentCommunication(communication)],
+ vec![TurnInput::InterAgentCommunication(communication.into())],
)
.await;
assert_eq!(
@@ -720,17 +723,17 @@ mod tests {
);
input_queue
- .enqueue_mailbox_communication(mail_one.clone(), Default::default())
+ .enqueue_mailbox_communication(mail_one.clone().into(), Default::default())
.await;
input_queue
- .enqueue_mailbox_communication(mail_two.clone(), Default::default())
+ .enqueue_mailbox_communication(mail_two.clone().into(), Default::default())
.await;
assert_eq!(
input_queue.drain_mailbox_input_items().await.0,
vec![
- TurnInput::InterAgentCommunication(mail_one),
- TurnInput::InterAgentCommunication(mail_two)
+ TurnInput::InterAgentCommunication(mail_one.into()),
+ TurnInput::InterAgentCommunication(mail_two.into())
]
);
assert!(!input_queue.has_pending_mailbox_items().await);
@@ -765,7 +768,8 @@ mod tests {
for (trigger_turn, parent_turn_id, root_turn_id) in pending_mails {
input_queue
.enqueue_mailbox_communication(
- make_mail(AgentPath::root(), AgentPath::root(), "task", trigger_turn),
+ make_mail(AgentPath::root(), AgentPath::root(), "task", trigger_turn)
+ .into(),
TurnStartOptions {
parent_turn_id: parent_turn_id.map(str::to_string),
root_turn_id: root_turn_id.map(str::to_string),
@@ -796,7 +800,8 @@ mod tests {
] {
input_queue
.enqueue_mailbox_communication(
- make_mail(AgentPath::root(), AgentPath::root(), "task", trigger_turn),
+ make_mail(AgentPath::root(), AgentPath::root(), "task", trigger_turn)
+ .into(),
TurnStartOptions {
cyber_access_program: program,
..Default::default()
@@ -820,7 +825,7 @@ mod tests {
/*trigger_turn*/ false,
);
input_queue
- .enqueue_mailbox_communication(queued_mail, Default::default())
+ .enqueue_mailbox_communication(queued_mail.into(), Default::default())
.await;
assert!(!input_queue.has_trigger_turn_mailbox_items().await);
@@ -831,7 +836,7 @@ mod tests {
/*trigger_turn*/ true,
);
input_queue
- .enqueue_mailbox_communication(trigger_mail, Default::default())
+ .enqueue_mailbox_communication(trigger_mail.into(), Default::default())
.await;
assert!(input_queue.has_trigger_turn_mailbox_items().await);
}
diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rs
index a35f324712..c69af94ee0 100644
--- a/codex-rs/core/src/session/mod.rs
+++ b/codex-rs/core/src/session/mod.rs
@@ -145,7 +145,6 @@ use codex_protocol::permissions::NetworkSandboxPolicy;
use codex_protocol::protocol::FileChange;
use codex_protocol::protocol::HasLegacyEvent;
use codex_protocol::protocol::HistoryPosition;
-use codex_protocol::protocol::InterAgentCommunication;
use codex_protocol::protocol::ItemCompletedEvent;
use codex_protocol::protocol::ItemStartedEvent;
use codex_protocol::protocol::MULTI_AGENT_MODE_OPEN_TAG;
@@ -1060,7 +1059,7 @@ impl SessionIo {
) -> CodexResult<String> {
self.submit_with_trace(
op, /*trace*/ None, /*parent_turn_id*/ None, /*root_turn_id*/ None,
- /*residency_guard*/ None,
+ /*residency_guard*/ None, /*message_delivery*/ None,
)
.await
}
@@ -1072,6 +1071,7 @@ impl SessionIo {
parent_turn_id: Option<String>,
root_turn_id: Option<String>,
residency_guard: Option<tokio::sync::OwnedRwLockReadGuard<()>>,
+ message_delivery: Option<crate::agent_communication::MessageDelivery>,
) -> CodexResult<String> {
let id = new_submission_id();
let WithTurnExtensionData {
@@ -1086,6 +1086,7 @@ impl SessionIo {
parent_turn_id,
root_turn_id,
residency_guard,
+ message_delivery,
};
self.submit_with_id(sub).await?;
Ok(id)
@@ -1131,6 +1132,7 @@ impl SessionIo {
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
})
.await?;
reply_rx.await.unwrap_or(Err(CodexErr::InternalAgentDied))
@@ -1157,6 +1159,7 @@ impl SessionIo {
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
})
.await?;
reply_rx.await.unwrap_or(Err(CodexErr::InternalAgentDied))
@@ -4093,8 +4096,9 @@ impl Session {
&self,
turn_context: &TurnContext,
model_info: &ModelInfo,
- communication: InterAgentCommunication,
+ communication: impl Into<crate::PendingAgentMessage>,
) {
+ let communication = communication.into();
let mut response_item = communication.to_model_input_item();
if let ResponseItem::AgentMessage {
content,
@@ -4161,6 +4165,9 @@ impl Session {
model_info.truncation_policy.into(),
);
}
+ if let Some(delivery) = &communication.delivery {
+ delivery.consumed(self.thread_id);
+ }
self.persist_rollout_items(&[
RolloutItem::InterAgentCommunicationMetadata {
trigger_turn: communication.trigger_turn,
diff --git a/codex-rs/core/src/session/step_activation_tests.rs b/codex-rs/core/src/session/step_activation_tests.rs
index d05b1e1c93..a61493af76 100644
--- a/codex-rs/core/src/session/step_activation_tests.rs
+++ b/codex-rs/core/src/session/step_activation_tests.rs
@@ -513,6 +513,7 @@ fn settings_submission(
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
},
receiver,
)
diff --git a/codex-rs/core/src/session/submission.rs b/codex-rs/core/src/session/submission.rs
index b5649cf9de..01f52556ff 100644
--- a/codex-rs/core/src/session/submission.rs
+++ b/codex-rs/core/src/session/submission.rs
@@ -17,4 +17,6 @@ pub(crate) struct Submission {
pub root_turn_id: Option<String>,
/// Keeps a V2 recipient resident until this submission is handled or dropped.
pub residency_guard: Option<OwnedRwLockReadGuard<()>>,
+ /// Owns delivery until dispatch; failed or abandoned submissions discard it.
+ pub message_delivery: Option<crate::agent_communication::MessageDelivery>,
}
diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rs
index c978a7dc11..30a7216428 100644
--- a/codex-rs/core/src/session/tests.rs
+++ b/codex-rs/core/src/session/tests.rs
@@ -6176,6 +6176,7 @@ async fn standalone_settings_invalidate_continuation_before_delivering_acceptanc
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
})
.await
.expect("submit settings");
@@ -8134,6 +8135,7 @@ async fn submit_with_trace_captures_current_span_trace_context() {
/*parent_turn_id*/ None,
/*root_turn_id*/ None,
/*residency_guard*/ None,
+ /*message_delivery*/ None,
)
.await
.expect("submit should succeed");
@@ -8208,6 +8210,7 @@ fn submission_dispatch_span_prefers_submission_trace_context() {
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
trace: Some(submission_trace),
})
});
@@ -8238,6 +8241,7 @@ fn submission_dispatch_span_uses_debug_for_realtime_audio() {
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
trace: None,
});
@@ -8598,6 +8602,7 @@ async fn spawn_task_turn_span_inherits_dispatch_trace_context() {
parent_turn_id: None,
root_turn_id: None,
residency_guard: None,
+ message_delivery: None,
trace: Some(submission_trace.clone()),
});
let dispatch_span_id = dispatch_span.context().span().span_context().span_id();
@@ -12716,7 +12721,8 @@ async fn thread_idle_lifecycle_waits_for_trigger_turn_mailbox_work() {
Vec::new(),
"pending trigger".to_string(),
/*trigger_turn*/ true,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -12798,7 +12804,7 @@ async fn queue_only_mailbox_mail_waits_for_next_turn_after_answer_boundary() {
.defer_mailbox_delivery_to_next_turn(&sess.active_turn, &tc.sub_id)
.await;
sess.input_queue
- .enqueue_mailbox_communication(communication.clone(), Default::default())
+ .enqueue_mailbox_communication(communication.clone().into(), Default::default())
.await;
assert!(
@@ -12817,7 +12823,7 @@ async fn queue_only_mailbox_mail_waits_for_next_turn_after_answer_boundary() {
assert_eq!(
(sess.input_queue.get_pending_input(&sess.active_turn).await).0,
- vec![TurnInput::InterAgentCommunication(communication)],
+ vec![TurnInput::InterAgentCommunication(communication.into())],
);
}
@@ -12845,7 +12851,8 @@ async fn trigger_turn_mailbox_mail_waits_for_next_turn_after_answer_boundary() {
Vec::new(),
"late trigger update".to_string(),
/*trigger_turn*/ true,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -12891,7 +12898,7 @@ async fn active_turn_keeps_first_root_when_mail_coalesces(inherited_root: Option
{
sess.input_queue
.enqueue_mailbox_communication(
- communication,
+ communication.into(),
codex_protocol::turn_input::TurnStartOptions {
parent_turn_id: Some(parent_turn_id.to_string()),
root_turn_id: Some(root_turn_id.to_string()),
@@ -12917,8 +12924,8 @@ async fn active_turn_keeps_first_root_when_mail_coalesces(inherited_root: Option
assert_eq!(
(sess.input_queue.get_pending_input(&sess.active_turn).await).0,
vec![
- TurnInput::InterAgentCommunication(first),
- TurnInput::InterAgentCommunication(second),
+ TurnInput::InterAgentCommunication(first.into()),
+ TurnInput::InterAgentCommunication(second.into()),
]
);
assert_eq!(
@@ -12954,7 +12961,7 @@ async fn steered_input_reopens_mailbox_delivery_for_current_turn() {
.defer_mailbox_delivery_to_next_turn(&sess.active_turn, &tc.sub_id)
.await;
sess.input_queue
- .enqueue_mailbox_communication(communication.clone(), Default::default())
+ .enqueue_mailbox_communication(communication.clone().into(), Default::default())
.await;
let submission = submit_steer_only(
&sess,
@@ -12981,7 +12988,7 @@ async fn steered_input_reopens_mailbox_delivery_for_current_turn() {
}],
client_id: None,
},
- TurnInput::InterAgentCommunication(communication),
+ TurnInput::InterAgentCommunication(communication.into()),
],
);
}
@@ -13010,7 +13017,7 @@ async fn stale_defer_mailbox_delivery_does_not_override_steered_input() {
.defer_mailbox_delivery_to_next_turn(&sess.active_turn, &tc.sub_id)
.await;
sess.input_queue
- .enqueue_mailbox_communication(communication.clone(), Default::default())
+ .enqueue_mailbox_communication(communication.clone().into(), Default::default())
.await;
let submission = submit_steer_only(
&sess,
@@ -13041,7 +13048,7 @@ async fn stale_defer_mailbox_delivery_does_not_override_steered_input() {
}],
client_id: None,
},
- TurnInput::InterAgentCommunication(communication),
+ TurnInput::InterAgentCommunication(communication.into()),
],
);
}
@@ -13070,7 +13077,7 @@ async fn tool_calls_reopen_mailbox_delivery_for_current_turn() {
.defer_mailbox_delivery_to_next_turn(&sess.active_turn, &tc.sub_id)
.await;
sess.input_queue
- .enqueue_mailbox_communication(communication.clone(), Default::default())
+ .enqueue_mailbox_communication(communication.clone().into(), Default::default())
.await;
let item = ResponseItem::FunctionCall {
@@ -13101,7 +13108,7 @@ async fn tool_calls_reopen_mailbox_delivery_for_current_turn() {
assert!(output.tool_future.is_some());
assert_eq!(
(sess.input_queue.get_pending_input(&sess.active_turn).await).0,
- vec![TurnInput::InterAgentCommunication(communication)],
+ vec![TurnInput::InterAgentCommunication(communication.into())],
);
}
diff --git a/codex-rs/core/src/session/turn_input.rs b/codex-rs/core/src/session/turn_input.rs
index 4c1c6ba66c..4d2f83bbe0 100644
--- a/codex-rs/core/src/session/turn_input.rs
+++ b/codex-rs/core/src/session/turn_input.rs
@@ -993,7 +993,7 @@ async fn pending_turn_input(
TurnInput::ResponseItem(item.into())
}
SubmittedTurnInput::InterAgentCommunication(communication) => {
- TurnInput::InterAgentCommunication(communication)
+ TurnInput::InterAgentCommunication(communication.into())
}
};
if retain
diff --git a/codex-rs/core/src/session/turn_input_tests.rs b/codex-rs/core/src/session/turn_input_tests.rs
index 2167aa2ad2..2dca090537 100644
--- a/codex-rs/core/src/session/turn_input_tests.rs
+++ b/codex-rs/core/src/session/turn_input_tests.rs
@@ -831,7 +831,8 @@ async fn start_only_rejects_pending_trigger_turn_without_injecting() {
Vec::new(),
"pending trigger".to_string(),
/*trigger_turn*/ true,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -887,14 +888,14 @@ async fn agent_message_wake_reservation_preserves_existing_boundaries(
);
session
.input_queue
- .enqueue_mailbox_communication(communication.clone(), Default::default())
+ .enqueue_mailbox_communication(communication.clone().into(), Default::default())
.await;
assert!(session.reserve_pending_work_turn().await.is_none());
assert!(session.active_turn.lock().await.is_none());
assert_eq!(
session.input_queue.drain_mailbox_input_items().await.0,
- vec![TurnInput::InterAgentCommunication(communication)]
+ vec![TurnInput::InterAgentCommunication(communication.into())]
);
}
diff --git a/codex-rs/core/src/thread_manager.rs b/codex-rs/core/src/thread_manager.rs
index 7c27b9d1e3..1ac38d20fd 100644
--- a/codex-rs/core/src/thread_manager.rs
+++ b/codex-rs/core/src/thread_manager.rs
@@ -452,7 +452,7 @@ pub(crate) struct ThreadManagerState {
plugins_manager: Arc<PluginsManager>,
mcp_manager: Arc<McpManager>,
code_mode_session_provider: Arc<dyn CodeModeSessionProvider>,
- extensions: Arc<ExtensionRegistry<Config>>,
+ pub(crate) extensions: Arc<ExtensionRegistry<Config>>,
user_instructions_provider: Arc<dyn UserInstructionsProvider>,
image_store: Arc<dyn AttachmentStore>,
thread_store: Arc<dyn ThreadStore>,
@@ -1816,6 +1816,7 @@ impl ThreadManagerState {
op: Op,
parent_turn_id: Option<String>,
root_turn_id: Option<String>,
+ message_delivery: Option<crate::agent_communication::MessageDelivery>,
) -> CodexResult<String> {
let thread = self.get_thread(thread_id).await?;
let residency_guard = if matches!(op, Op::InterAgentCommunication { .. }) {
@@ -1842,6 +1843,7 @@ impl ThreadManagerState {
parent_turn_id,
root_turn_id,
residency_guard,
+ message_delivery,
)
.await
}
diff --git a/codex-rs/core/src/tools/handlers/multi_agents_tests.rs b/codex-rs/core/src/tools/handlers/multi_agents_tests.rs
index f6ffb7a8bb..27bee5dfa2 100644
--- a/codex-rs/core/src/tools/handlers/multi_agents_tests.rs
+++ b/codex-rs/core/src/tools/handlers/multi_agents_tests.rs
@@ -3037,7 +3037,8 @@ async fn multi_agent_v2_wait_agent_accepts_timeout_only_argument() {
Vec::new(),
"hello from worker".to_string(),
/*trigger_turn*/ false,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -3537,7 +3538,8 @@ async fn multi_agent_v2_wait_agent_returns_summary_for_mailbox_activity() {
Vec::new(),
"completed".to_string(),
/*trigger_turn*/ false,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -3613,7 +3615,8 @@ async fn multi_agent_v2_wait_agent_returns_for_already_queued_mail() {
Vec::new(),
"already queued".to_string(),
/*trigger_turn*/ false,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -3715,7 +3718,8 @@ async fn multi_agent_v2_wait_agent_wakes_on_any_mailbox_notification() {
Vec::new(),
"from worker b".to_string(),
/*trigger_turn*/ false,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
@@ -3806,7 +3810,8 @@ async fn multi_agent_v2_wait_agent_does_not_return_completed_content() {
Vec::new(),
"sensitive child output".to_string(),
/*trigger_turn*/ false,
- ),
+ )
+ .into(),
Default::default(),
)
.await;
diff --git a/codex-rs/core/tests/suite/agent_control_tests.rs b/codex-rs/core/tests/suite/agent_control_tests.rs
index 636b403c25..3289979fb4 100644
--- a/codex-rs/core/tests/suite/agent_control_tests.rs
+++ b/codex-rs/core/tests/suite/agent_control_tests.rs
@@ -15,6 +15,7 @@ use codex_core::DeliveryReceipt;
use codex_core::ForkSnapshot;
use codex_core::GuardianRootSnapshot;
use codex_core::LiveAgent;
+use codex_core::PendingAgentMessage;
use codex_core::RolloutBudgetReminder;
use codex_core::SendRequest;
use codex_core::SpawnRequest;
@@ -53,7 +54,7 @@ use wiremock::MockServer;
struct TestAgentControl {
thread_id: ThreadId,
service_tier: Mutex<Option<String>>,
- mail: Mutex<Vec<codex_protocol::protocol::InterAgentCommunication>>,
+ mail: Mutex<Vec<PendingAgentMessage>>,
mailbox_state: tokio::sync::watch::Sender<bool>,
agents: Mutex<HashMap<String, ThreadId>>,
}
@@ -104,10 +105,7 @@ impl AgentControl for TestAgentControl {
Box::pin(async { Err(CodexErr::InvalidRequest("host send rejection".to_string())) })
}
- fn take_mailbox(
- &self,
- _agent: ThreadId,
- ) -> Vec<codex_protocol::protocol::InterAgentCommunication> {
+ fn take_mailbox(&self, _agent: ThreadId) -> Vec<PendingAgentMessage> {
let messages = std::mem::take(&mut *self.mail.lock().expect("mail lock"));
self.mailbox_state.send_if_modified(std::mem::take);
messages
@@ -287,13 +285,14 @@ async fn host_threads_preserve_lineage_settings_and_resume_routing() -> anyhow::
(controller.identity(), Some(root_id))
);
assert_eq!(controller.service_tier(), Some("priority".to_string()));
- let unread_mail = vec![codex_protocol::protocol::InterAgentCommunication::new(
+ let message = codex_protocol::protocol::InterAgentCommunication::new(
AgentPath::root(),
AgentPath::root().join("worker").expect("valid child path"),
Vec::new(),
"Retain this in the host mailbox".into(),
/*trigger_turn*/ false,
- )];
+ );
+ let unread_mail = vec![message.into()];
*controller.mail.lock().expect("mail lock") = unread_mail.clone();
let error = test
.thread_manager
@@ -591,7 +590,8 @@ async fn host_mailbox_notifies_waiting_agent_and_delivers_once() -> anyhow::Resu
Vec::new(),
"Note from the host mailbox".into(),
/*trigger_turn*/ false,
- ),
+ )
+ .into(),
);
controller.mailbox_state.send_replace(true);
wait_for_event(&test.codex, |event| {
@@ -658,7 +658,11 @@ async fn agent_mail_wakes_completed_root_when_enabled(
/*trigger_turn*/ false,
);
if via_host_mailbox {
- controller.mail.lock().expect("mail lock").push(message);
+ controller
+ .mail
+ .lock()
+ .expect("mail lock")
+ .push(message.into());
controller.mailbox_state.send_replace(true);
} else {
test.codex
diff --git a/codex-rs/core/tests/suite/agent_mailbox.rs b/codex-rs/core/tests/suite/agent_mailbox.rs
index 357631a517..a06ff09414 100644
--- a/codex-rs/core/tests/suite/agent_mailbox.rs
+++ b/codex-rs/core/tests/suite/agent_mailbox.rs
@@ -5,15 +5,33 @@ use crate::suite::settings_commits::COMMITTED_MODEL;
use crate::suite::settings_commits::PauseAfterCommit;
use codex_core::config::Config;
use codex_extension_api::ExtensionRegistryBuilder;
+use codex_extension_api::MessageLifecycleContributor;
+use codex_extension_api::MessageLifecycleInput;
+use codex_protocol::ResponseItemId;
+use codex_protocol::ThreadId;
use codex_protocol::protocol::AgentStatus;
use codex_protocol::protocol::Op;
use core_test_support::ThreadIdle;
use pretty_assertions::assert_eq;
+use std::collections::HashSet;
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::mpsc;
use tokio::sync::oneshot;
+#[derive(Default)]
+struct Messages(Mutex<HashSet<ResponseItemId>>);
+impl MessageLifecycleContributor for Messages {
+ fn on_publish(&self, input: &MessageLifecycleInput) {
+ let mut pending = self.0.lock().expect("messages lock");
+ assert!(pending.insert(input.message_id.clone()));
+ }
+ fn on_consumed(&self, input: &MessageLifecycleInput, _recipient: ThreadId) {
+ let mut pending = self.0.lock().expect("messages lock");
+ assert!(pending.remove(&input.message_id));
+ }
+}
+
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn idle_mail_survives_eviction_and_preserves_followup_order() -> Result<()> {
const MAIL: &str = "Keep this note for later";
@@ -37,6 +55,8 @@ async fn idle_mail_survives_eviction_and_preserves_followup_order() -> Result<()
gate: Mutex::new(Some((entered_tx, release_rx))),
}));
extensions.thread_lifecycle_contributor(Arc::new(ThreadIdle));
+ let messages = Arc::new(Messages::default());
+ extensions.message_lifecycle_contributor(messages.clone());
let test = test_codex()
.with_model("gpt-5.6-sol")
.with_extensions(Arc::new(extensions.build()))
@@ -106,6 +126,8 @@ async fn idle_mail_survives_eviction_and_preserves_followup_order() -> Result<()
ThreadIdle::wait(&test.codex).await;
assert!(test.thread_manager.get_thread(first_id).await.is_err());
+ let retained = messages.0.lock().unwrap().clone();
+ assert_eq!(retained.len(), 2);
// Reload without starting a turn, then hold dispatch while both tools submit.
// The older queued notes must precede the follow-up, and the newer note must follow it.
test.thread_manager
@@ -130,10 +152,18 @@ async fn idle_mail_survives_eviction_and_preserves_followup_order() -> Result<()
json!({ "target": "first", "message": FOLLOWUP }),
)
.await;
+ let (at_sampling, pending_at_sampling) = mpsc::channel();
mount_sse_once_match(
&server,
- |request: &wiremock::Request| {
- body_contains(request, FOLLOWUP) && !has_function_call_output(request, "followup")
+ move |request: &wiremock::Request| {
+ let matches =
+ body_contains(request, FOLLOWUP) && !has_function_call_output(request, "followup");
+ if matches {
+ at_sampling
+ .send(messages.0.lock().unwrap().clone())
+ .unwrap();
+ }
+ matches
},
sse(vec![
ev_response_created("worker-wait"),
@@ -171,6 +201,10 @@ async fn idle_mail_survives_eviction_and_preserves_followup_order() -> Result<()
release_tx.send(())?;
wait_for_event(&resumed, |event| matches!(event, EventMsg::TurnComplete(_))).await;
ThreadIdle::wait(&resumed).await;
+ assert!(
+ pending_at_sampling.try_recv()?.is_disjoint(&retained),
+ "both retained publications must be consumed before the first resumed sample"
+ );
let request = delivered
.requests()
.into_iter()
diff --git a/codex-rs/ext/extension-api/src/lib.rs b/codex-rs/ext/extension-api/src/lib.rs
index 73767fe43e..41d85d6396 100644
--- a/codex-rs/ext/extension-api/src/lib.rs
+++ b/codex-rs/ext/extension-api/src/lib.rs
@@ -1,5 +1,6 @@
mod capabilities;
mod contributors;
+mod message_lifecycle;
mod registry;
mod session_isolation;
mod state;
@@ -7,6 +8,8 @@ mod tool_policy;
mod turn_admission;
mod user_instructions;
+pub use message_lifecycle::MessageLifecycleContributor;
+pub use message_lifecycle::MessageLifecycleInput;
pub use session_isolation::IsolatedSessionExtensions;
pub use session_isolation::SessionIsolation;
pub use tool_policy::ToolPolicy;
diff --git a/codex-rs/ext/extension-api/src/message_lifecycle.rs b/codex-rs/ext/extension-api/src/message_lifecycle.rs
new file mode 100644
index 0000000000..c81391dca5
--- /dev/null
+++ b/codex-rs/ext/extension-api/src/message_lifecycle.rs
@@ -0,0 +1,23 @@
+//! Capture publication state once; consume it independently for each delivery.
+
+use crate::ExtensionData;
+use codex_protocol::ResponseItemId;
+use codex_protocol::ThreadId;
+
+/// State shared by all deliveries of a publication, including recipients resolved later.
+pub struct MessageLifecycleInput {
+ pub message_id: ResponseItemId,
+ pub sender: ThreadId,
+ /// Capture contributor-specific state at publication; read it at consumption.
+ pub data: ExtensionData,
+}
+
+/// Observes messages published through local agent control, where the sender is known.
+/// Callbacks are synchronous and must not block. Replaying history or submitting raw
+/// protocol input does not create a publication.
+pub trait MessageLifecycleContributor: Send + Sync {
+ /// Called once before the message is exposed to any recipient.
+ fn on_publish(&self, _input: &MessageLifecycleInput) {}
+ /// Called at most once per logical delivery, at history commitment before sampling.
+ fn on_consumed(&self, _input: &MessageLifecycleInput, _recipient: ThreadId) {}
+}
diff --git a/codex-rs/ext/extension-api/src/registry.rs b/codex-rs/ext/extension-api/src/registry.rs
index ddb02113ed..46fd6e66a9 100644
--- a/codex-rs/ext/extension-api/src/registry.rs
+++ b/codex-rs/ext/extension-api/src/registry.rs
@@ -5,6 +5,7 @@ use crate::ConfigContributor;
use crate::ContextContributor;
use crate::ExtensionEventSink;
use crate::McpServerContributor;
+use crate::MessageLifecycleContributor;
use crate::ModelRequestContributor;
use crate::NoopExtensionEventSink;
use crate::SkillInvocationContributor;
@@ -40,6 +41,7 @@ impl<C: Sync> Default for ExtensionRegistryBuilder<C> {
tool_contributors: Vec::new(),
tool_lifecycle_contributors: Vec::new(),
model_request_contributors: Vec::new(),
+ message_observers: Vec::new(),
turn_item_contributors: Vec::new(),
},
}
@@ -144,6 +146,11 @@ impl<C: Sync> ExtensionRegistryBuilder<C> {
self.registry.turn_item_contributors.push(contributor);
}
+ /// Registers a synchronous direct-message observer.
+ pub fn message_lifecycle_contributor(&mut self, hook: Arc<dyn MessageLifecycleContributor>) {
+ self.registry.message_observers.push(hook);
+ }
+
/// Finishes construction and returns the immutable registry.
pub fn build(self) -> ExtensionRegistry<C> {
self.registry
@@ -165,6 +172,7 @@ pub struct ExtensionRegistry<C: Sync> {
tool_contributors: Vec<Arc<dyn ToolContributor>>,
tool_lifecycle_contributors: Vec<Arc<dyn ToolLifecycleContributor>>,
model_request_contributors: Vec<Arc<dyn ModelRequestContributor>>,
+ message_observers: Vec<Arc<dyn MessageLifecycleContributor>>,
turn_item_contributors: Vec<Arc<dyn TurnItemContributor>>,
approval_review_contributors: Vec<Arc<dyn ApprovalReviewContributor>>,
}
@@ -187,6 +195,7 @@ impl<C: Sync> ExtensionRegistry<C> {
tool_contributors: self.tool_contributors.clone(),
tool_lifecycle_contributors: self.tool_lifecycle_contributors.clone(),
model_request_contributors: self.model_request_contributors.clone(),
+ message_observers: self.message_observers.clone(),
turn_item_contributors: self.turn_item_contributors.clone(),
approval_review_contributors: self.approval_review_contributors.clone(),
},
@@ -276,6 +285,11 @@ impl<C: Sync> ExtensionRegistry<C> {
&self.tool_contributors
}
+ /// Returns direct-message observers in registration order.
+ pub fn message_lifecycle_contributors(&self) -> &[Arc<dyn MessageLifecycleContributor>] {
+ &self.message_observers
+ }
+
/// Returns response interceptor contributors in registration order.
pub fn model_request_contributors(&self) -> &[Arc<dyn ModelRequestContributor>] {
&self.model_request_contributors