Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add agent inspection without restoring unloaded runtimes (#47010)

jif7d99ee82d743
diff --git a/codex-rs/core/src/agent/api.rs b/codex-rs/core/src/agent/api.rs
index 04e2ab4e2d..6d5f7e2e16 100644
--- a/codex-rs/core/src/agent/api.rs
+++ b/codex-rs/core/src/agent/api.rs
@@ -170,6 +170,22 @@ pub enum AgentInfo {
Unloaded(AgentMetadata),
}
+impl AgentInfo {
+ pub fn metadata(&self) -> &AgentMetadata {
+ match self {
+ Self::Loaded { agent, .. } => &agent.metadata,
+ Self::Unloaded(metadata) => metadata,
+ }
+ }
+
+ pub fn status(&self) -> Option<&AgentStatus> {
+ match self {
+ Self::Loaded { agent, .. } => Some(&agent.status),
+ Self::Unloaded(_) => None,
+ }
+ }
+}
+
/// User input starts or steers a turn; agent messages retain their sender and wake mode.
pub enum AgentInput {
UserInput(Vec<UserInput>),
diff --git a/codex-rs/core/src/agent/control.rs b/codex-rs/core/src/agent/control.rs
index a819a1cceb..e44fc8b6ff 100644
--- a/codex-rs/core/src/agent/control.rs
+++ b/codex-rs/core/src/agent/control.rs
@@ -67,14 +67,13 @@ use tracing::warn;
use uuid::Uuid;
use self::execution::AgentExecutionLimiter;
-pub(crate) use self::interrupt::AgentInterruptError;
-pub(crate) use self::interrupt::AgentInterruptOutcome;
use self::residency::V2Residency;
mod budget;
mod completion;
mod delivery;
mod execution;
+mod inspection;
mod interrupt;
mod legacy;
mod residency;
@@ -430,13 +429,10 @@ impl LocalAgentControl {
&self,
agent_id: ThreadId,
) -> Option<ThreadConfigSnapshot> {
- let Ok(state) = self.upgrade() else {
- return None;
- };
- let Ok(thread) = state.get_thread(agent_id).await else {
- return None;
- };
- Some(thread.config_snapshot().await)
+ match self.inspect_agent(agent_id).await.ok()? {
+ crate::agent::api::AgentInfo::Loaded { config, .. } => Some(*config),
+ crate::agent::api::AgentInfo::Unloaded(_) => None,
+ }
}
/// Subscribe to status updates for `agent_id`, yielding the latest value and changes.
diff --git a/codex-rs/core/src/agent/control/inspection.rs b/codex-rs/core/src/agent/control/inspection.rs
new file mode 100644
index 0000000000..4f0a963997
--- /dev/null
+++ b/codex-rs/core/src/agent/control/inspection.rs
@@ -0,0 +1,40 @@
+//! Reads registered agent identity, status and settings without restoring a runtime.
+//! Known unloaded agents stay distinct from missing identities and backend failures.
+
+use super::LocalAgentControl;
+use crate::agent::api::AgentInfo;
+use crate::agent::api::AgentTarget;
+use crate::agent::types::LiveAgent;
+use codex_protocol::ThreadId;
+use codex_protocol::error::CodexErrorDetails;
+use codex_protocol::error::Result as CodexResult;
+
+impl LocalAgentControl {
+ pub(crate) async fn inspect(
+ &self,
+ caller: ThreadId,
+ target: AgentTarget,
+ ) -> CodexResult<AgentInfo> {
+ let target = self.resolve_target(caller, &target)?;
+ self.inspect_agent(target).await
+ }
+
+ pub(super) async fn inspect_agent(&self, thread_id: ThreadId) -> CodexResult<AgentInfo> {
+ let manager = self.upgrade()?;
+ let thread = match manager.get_thread(thread_id).await {
+ Ok(thread) => thread,
+ Err(err) if matches!(err.details(), CodexErrorDetails::ThreadNotFound(_)) => {
+ return Ok(AgentInfo::Unloaded(self.ensure_agent_known(thread_id)?));
+ }
+ Err(err) => return Err(err),
+ };
+ Ok(AgentInfo::Loaded {
+ agent: LiveAgent {
+ thread_id,
+ metadata: self.get_agent_metadata(thread_id).unwrap_or_default(),
+ status: thread.agent_status().await,
+ },
+ config: Box::new(thread.config_snapshot().await),
+ })
+ }
+}
diff --git a/codex-rs/core/src/agent/control/interrupt.rs b/codex-rs/core/src/agent/control/interrupt.rs
index a9ffa441af..c729e42a65 100644
--- a/codex-rs/core/src/agent/control/interrupt.rs
+++ b/codex-rs/core/src/agent/control/interrupt.rs
@@ -4,23 +4,13 @@
//! interruption; this operation never reloads it.
use super::LocalAgentControl;
-use crate::agent::AgentStatus;
+use crate::agent::api::AgentInfo;
+use crate::agent::api::AgentTarget;
use codex_protocol::AgentPath;
use codex_protocol::ThreadId;
use codex_protocol::error::CodexErr;
use codex_protocol::error::CodexErrorDetails;
-
-pub(crate) struct AgentInterruptOutcome {
- pub(crate) agent_path: AgentPath,
- pub(crate) previous_status: AgentStatus,
-}
-
-/// Keeps request validation distinct from runtime failures for the tool adapter's error mapping.
-#[derive(Debug)]
-pub(crate) enum AgentInterruptError {
- InvalidRequest(String),
- Agent(CodexErr),
-}
+use codex_protocol::error::Result as CodexResult;
impl LocalAgentControl {
/// Interrupts a spawned agent's current task, preserving the status observed before dispatch.
@@ -28,29 +18,27 @@ impl LocalAgentControl {
&self,
caller: ThreadId,
target: ThreadId,
- ) -> Result<AgentInterruptOutcome, AgentInterruptError> {
- let receiver_agent = self
- .ensure_agent_known(target)
- .map_err(AgentInterruptError::Agent)?;
+ ) -> CodexResult<AgentInfo> {
+ let receiver_agent = self.ensure_agent_known(target)?;
if receiver_agent
.agent_path
.as_ref()
.is_some_and(AgentPath::is_root)
{
- return Err(AgentInterruptError::InvalidRequest(
+ return Err(CodexErr::UnsupportedOperation(
"root is not a spawned agent".to_string(),
));
}
if target == caller {
- return Err(AgentInterruptError::InvalidRequest(
+ return Err(CodexErr::UnsupportedOperation(
"an agent cannot interrupt itself; return your result and let the parent interrupt you if needed"
.to_string(),
));
}
- let agent_path = receiver_agent.agent_path.clone().ok_or_else(|| {
- AgentInterruptError::InvalidRequest("target agent is missing an agent_path".to_string())
+ receiver_agent.agent_path.as_ref().ok_or_else(|| {
+ CodexErr::UnsupportedOperation("target agent is missing an agent_path".to_string())
})?;
- let previous_status = self.get_status(target).await;
+ let snapshot = self.inspect(caller, AgentTarget::Id(target)).await?;
match self.interrupt_agent(target).await {
Ok(_) => {}
Err(err)
@@ -58,11 +46,8 @@ impl LocalAgentControl {
err.details(),
CodexErrorDetails::ThreadNotFound(_) | CodexErrorDetails::InternalAgentDied
) => {}
- Err(err) => return Err(AgentInterruptError::Agent(err)),
+ Err(err) => return Err(err),
}
- Ok(AgentInterruptOutcome {
- agent_path,
- previous_status,
- })
+ Ok(snapshot)
}
}
diff --git a/codex-rs/core/src/agent/control_tests.rs b/codex-rs/core/src/agent/control_tests.rs
index b1de6b3e97..577865135f 100644
--- a/codex-rs/core/src/agent/control_tests.rs
+++ b/codex-rs/core/src/agent/control_tests.rs
@@ -3,6 +3,8 @@ use crate::CodexThread;
use crate::StateDbHandle;
use crate::ThreadManager;
use crate::agent::agent_status_from_event;
+use crate::agent::api::AgentInfo;
+use crate::agent::api::AgentTarget;
use crate::agent::next_thread_spawn_depth;
use crate::agent::types::AgentMessage;
use crate::agent::types::LiveAgent;
@@ -881,6 +883,14 @@ async fn check_v2_agent_reload(route: V2ReloadRoute) {
.await
.is_some()
);
+ assert_matches!(
+ control
+ .inspect(parent_thread_id, AgentTarget::Id(spawned_agent.thread_id))
+ .await
+ .expect("inspect registered unloaded agent"),
+ AgentInfo::Unloaded(_)
+ );
+ // Inspection must not restore the evicted runtime.
match harness.manager.get_thread(spawned_agent.thread_id).await {
Err(err) => match err.details() {
CodexErrorDetails::ThreadNotFound(id) => assert_eq!(*id, spawned_agent.thread_id),
diff --git a/codex-rs/core/src/tools/handlers/multi_agents_common.rs b/codex-rs/core/src/tools/handlers/multi_agents_common.rs
index 715a02be4c..4f8f9072d0 100644
--- a/codex-rs/core/src/tools/handlers/multi_agents_common.rs
+++ b/codex-rs/core/src/tools/handlers/multi_agents_common.rs
@@ -87,6 +87,16 @@ pub(crate) fn collab_agent_error(agent_id: ThreadId, err: CodexErr) -> FunctionC
}
}
+/// Keeps V2 request validation distinct from a dropped local manager.
+pub(crate) fn collab_v2_agent_error(agent_id: ThreadId, err: CodexErr) -> FunctionCallError {
+ match err.details() {
+ CodexErrorDetails::UnsupportedOperation(message) if message != "thread manager dropped" => {
+ FunctionCallError::RespondToModel(message.clone())
+ }
+ _ => collab_agent_error(agent_id, err),
+ }
+}
+
pub(crate) fn thread_spawn_source(
parent_thread_id: ThreadId,
parent_session_source: &SessionSource,
diff --git a/codex-rs/core/src/tools/handlers/multi_agents_v2/interrupt_agent.rs b/codex-rs/core/src/tools/handlers/multi_agents_v2/interrupt_agent.rs
index db16be7396..a9d620497a 100644
--- a/codex-rs/core/src/tools/handlers/multi_agents_v2/interrupt_agent.rs
+++ b/codex-rs/core/src/tools/handlers/multi_agents_v2/interrupt_agent.rs
@@ -1,7 +1,5 @@
use super::analytics::ToolCallAnalytics;
use super::*;
-use crate::agent::control::AgentInterruptError;
-use crate::agent::control::AgentInterruptOutcome;
use crate::tools::handlers::multi_agents_spec::create_interrupt_agent_tool_v2;
use codex_tools::ToolSpec;
@@ -45,20 +43,16 @@ async fn handle_interrupt_agent(
let args: InterruptAgentArgs = parse_arguments(&arguments)?;
let agent_id = resolve_agent_target(&session, &turn, &args.target).await?;
analytics.set_receiver(agent_id);
- let AgentInterruptOutcome {
- agent_path,
- previous_status,
- } = session
+ let snapshot = session
.services
.agent_control
.interrupt_spawned_agent(session.thread_id, agent_id)
.await
- .map_err(|err| match err {
- AgentInterruptError::InvalidRequest(message) => {
- FunctionCallError::RespondToModel(message)
- }
- AgentInterruptError::Agent(err) => collab_agent_error(agent_id, err),
- })?;
+ .map_err(|err| collab_v2_agent_error(agent_id, err))?;
+ let agent_path = snapshot.metadata().agent_path.clone().ok_or_else(|| {
+ FunctionCallError::RespondToModel("target agent is missing an agent_path".to_string())
+ })?;
+ let previous_status = snapshot.status().cloned().unwrap_or(AgentStatus::NotFound);
emit_sub_agent_activity(
&session,
&turn,
diff --git a/codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs b/codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs
index cbf5ff5436..26d329fa0e 100644
--- a/codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs
+++ b/codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs
@@ -12,7 +12,6 @@ use crate::agent::api::SendRequest;
use crate::agent::child_config::build_agent_resume_config;
use crate::agent::types::MessageDeliveryMode;
use crate::tools::context::FunctionToolOutput;
-use codex_protocol::error::CodexErrorDetails;
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
@@ -80,14 +79,7 @@ pub(super) async fn handle_message_string_tool(
},
})
.await
- .map_err(|err| match err.details() {
- CodexErrorDetails::UnsupportedOperation(message)
- if message != "thread manager dropped" =>
- {
- FunctionCallError::RespondToModel(message.clone())
- }
- _ => collab_agent_error(receiver_thread_id, err),
- })?;
+ .map_err(|err| collab_v2_agent_error(receiver_thread_id, err))?;
let receiver_agent_path = receipt.metadata.agent_path.ok_or_else(|| {
FunctionCallError::RespondToModel("target agent is missing an agent_path".to_string())
})?;