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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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())})?;