mirror of
https://github.com/openai/codex.git
synced 2026-11-17 14:58:36 +00:00
multi-agent: add path-based v2 activity tracking (#27007)
## Why Multi-agent v2 identifies agents by canonical paths, but its tool handlers still emitted the larger legacy collaboration begin/end events built around nickname and role metadata. App-server, rollout-trace, analytics, and TUI consumers therefore lacked one compact path-based completion signal that behaved consistently across live events and replay. The TUI also needs a bounded `/agent` status surface for v2 agents. It should use recent local activity for previews, refresh liveness without loading full histories, and keep the legacy picker available when no path-backed v2 agent is known. ## What changed - Replace the v2 `spawn_agent`, `send_message`, `followup_task`, and `interrupt_agent` legacy lifecycle emissions with a success-only `SubAgentActivity` event. The event records the tool call ID, occurrence time, affected thread, canonical agent path, and `started`, `interacted`, or `interrupted` kind. - Expose the activity as a completion-only app-server v2 `subAgentActivity` thread item in live notifications and reconstructed history, regenerate the protocol schemas, and count it in sub-agent tool analytics. - Track canonical paths from live activity and loaded-thread metadata in the TUI, and render the activity in live and replayed transcripts. - Make `/agent` list running path-backed agents with summaries from bounded local event buffers. Each summary is capped at 240 graphemes, the scan is capped at six recent items, only the last three wrapped lines are shown, and command output is omitted. Liveness falls back to metadata-only `thread/read` when local turn state is unavailable. - Persist the activity as a terminal rollout-trace runtime payload and reduce it to the corresponding spawn, send, follow-up, or close interaction edge. `interrupt_agent` is classified as a close-edge operation. - Preserve the legacy picker when no path-backed v2 agent is known. ## Compatibility App-server v2 clients that consumed `collabAgentToolCall` begin/end pairs for these tools must handle the new completion-only `subAgentActivity` item. Legacy v1 collaboration behavior is unchanged. ## Screenshot <img width="684" height="288" alt="Screenshot 2026-06-08 at 15 40 47" src="https://github.com/user-attachments/assets/194b3cd0-619d-45fb-b587-cf3e2b1b8a1d" /> ## Testing - `just test -p codex-app-server-protocol` - `just test -p codex-rollout-trace` - Added focused coverage for activity analytics, terminal trace serialization, spawn-edge reduction, `interrupt_agent` classification, TUI status rendering without aggregated command output, and clearing stale running state after a completed turn.
This commit is contained in:
57 files changed
+2070
-176
No files matched your search
@@ -7,6 +7,10 @@ use codex_protocol::protocol::CollabAgentSpawnEndEvent;
|
||||
use codex_protocol::protocol::CollabCloseBeginEvent;
|
||||
use codex_protocol::protocol::CollabCloseEndEvent;
|
||||
use codex_protocol::protocol::InterAgentCommunication;
|
||||
use codex_protocol::protocol::SubAgentActivityEvent;
|
||||
use codex_protocol::protocol::SubAgentActivityKind;
|
||||
use serde::Deserialize;
|
||||
use serde_json::Value;
|
||||
|
||||
use super::super::TraceReducer;
|
||||
use crate::model::ConversationItem;
|
||||
@@ -52,6 +56,11 @@ pub(in crate::reducer) struct ObservedAgentResultEdge {
|
||||
pub(in crate::reducer) carried_payload: Option<RawPayloadRef>,
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct AgentMessageInvocationArgs {
|
||||
message: String,
|
||||
}
|
||||
|
||||
/// Builds the stable edge id for the spawn relationship between two threads.
|
||||
pub(in crate::reducer) fn spawn_edge_id(parent_thread_id: &str, child_thread_id: &str) -> String {
|
||||
format!("edge:spawn:{parent_thread_id}:{child_thread_id}")
|
||||
@@ -123,15 +132,20 @@ impl TraceReducer {
|
||||
runtime_payload: &RawPayloadRef,
|
||||
) -> Result<()> {
|
||||
let kind = self.rollout.tool_calls[tool_call_id].kind.clone();
|
||||
let runtime_payload_json = self.read_payload_json(runtime_payload)?;
|
||||
if runtime_payload_json.get("agent_thread_id").is_some() {
|
||||
let payload: SubAgentActivityEvent = serde_json::from_value(runtime_payload_json)?;
|
||||
return self.end_sub_agent_activity(wall_time_unix_ms, tool_call_id, &kind, &payload);
|
||||
}
|
||||
match kind {
|
||||
ToolCallKind::SpawnAgent => {
|
||||
let payload: CollabAgentSpawnEndEvent =
|
||||
serde_json::from_value(self.read_payload_json(runtime_payload)?)?;
|
||||
serde_json::from_value(runtime_payload_json)?;
|
||||
self.end_spawn_agent_interaction(wall_time_unix_ms, tool_call_id, &payload)
|
||||
}
|
||||
ToolCallKind::AssignAgentTask => {
|
||||
let payload: CollabAgentInteractionEndEvent =
|
||||
serde_json::from_value(self.read_payload_json(runtime_payload)?)?;
|
||||
serde_json::from_value(runtime_payload_json)?;
|
||||
self.end_message_agent_interaction(
|
||||
wall_time_unix_ms,
|
||||
tool_call_id,
|
||||
@@ -141,7 +155,7 @@ impl TraceReducer {
|
||||
}
|
||||
ToolCallKind::SendMessage => {
|
||||
let payload: CollabAgentInteractionEndEvent =
|
||||
serde_json::from_value(self.read_payload_json(runtime_payload)?)?;
|
||||
serde_json::from_value(runtime_payload_json)?;
|
||||
self.end_message_agent_interaction(
|
||||
wall_time_unix_ms,
|
||||
tool_call_id,
|
||||
@@ -150,8 +164,7 @@ impl TraceReducer {
|
||||
)
|
||||
}
|
||||
ToolCallKind::CloseAgent => {
|
||||
let payload: CollabCloseEndEvent =
|
||||
serde_json::from_value(self.read_payload_json(runtime_payload)?)?;
|
||||
let payload: CollabCloseEndEvent = serde_json::from_value(runtime_payload_json)?;
|
||||
self.upsert_close_agent_interaction(
|
||||
tool_call_id,
|
||||
payload.receiver_thread_id.to_string(),
|
||||
@@ -169,6 +182,127 @@ impl TraceReducer {
|
||||
}
|
||||
}
|
||||
|
||||
fn end_sub_agent_activity(
|
||||
&mut self,
|
||||
wall_time_unix_ms: i64,
|
||||
tool_call_id: &str,
|
||||
tool_kind: &ToolCallKind,
|
||||
payload: &SubAgentActivityEvent,
|
||||
) -> Result<()> {
|
||||
let target_thread_id = payload.agent_thread_id.to_string();
|
||||
match (tool_kind, &payload.kind) {
|
||||
(ToolCallKind::SpawnAgent, SubAgentActivityKind::Started) => {
|
||||
let parent_thread_id = self
|
||||
.rollout
|
||||
.tool_calls
|
||||
.get(tool_call_id)
|
||||
.with_context(|| {
|
||||
format!("agent activity referenced unknown tool call {tool_call_id}")
|
||||
})?
|
||||
.thread_id
|
||||
.clone();
|
||||
self.queue_sub_agent_activity_message_edge(
|
||||
wall_time_unix_ms,
|
||||
tool_call_id,
|
||||
spawn_edge_id(&parent_thread_id, &target_thread_id),
|
||||
InteractionEdgeKind::SpawnAgent,
|
||||
target_thread_id.clone(),
|
||||
Some(target_thread_id),
|
||||
)
|
||||
}
|
||||
(ToolCallKind::AssignAgentTask, SubAgentActivityKind::Interacted) => self
|
||||
.queue_sub_agent_activity_message_edge(
|
||||
wall_time_unix_ms,
|
||||
tool_call_id,
|
||||
tool_edge_id(tool_call_id),
|
||||
InteractionEdgeKind::AssignAgentTask,
|
||||
target_thread_id,
|
||||
/*unresolved_spawn_thread_id*/ None,
|
||||
),
|
||||
(ToolCallKind::SendMessage, SubAgentActivityKind::Interacted) => self
|
||||
.queue_sub_agent_activity_message_edge(
|
||||
wall_time_unix_ms,
|
||||
tool_call_id,
|
||||
tool_edge_id(tool_call_id),
|
||||
InteractionEdgeKind::SendMessage,
|
||||
target_thread_id,
|
||||
/*unresolved_spawn_thread_id*/ None,
|
||||
),
|
||||
(ToolCallKind::CloseAgent, SubAgentActivityKind::Interrupted) => self
|
||||
.upsert_close_agent_interaction(
|
||||
tool_call_id,
|
||||
target_thread_id,
|
||||
Some(wall_time_unix_ms),
|
||||
),
|
||||
_ => bail!(
|
||||
"sub-agent activity {:?} does not match tool call kind {tool_kind:?}",
|
||||
payload.kind
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
fn queue_sub_agent_activity_message_edge(
|
||||
&mut self,
|
||||
wall_time_unix_ms: i64,
|
||||
tool_call_id: &str,
|
||||
edge_id: String,
|
||||
edge_kind: InteractionEdgeKind,
|
||||
target_thread_id: String,
|
||||
unresolved_spawn_thread_id: Option<String>,
|
||||
) -> Result<()> {
|
||||
let tool_call = self.rollout.tool_calls.get(tool_call_id).with_context(|| {
|
||||
format!("agent activity referenced unknown tool call {tool_call_id}")
|
||||
})?;
|
||||
let started_at_unix_ms = tool_call.execution.started_at_unix_ms;
|
||||
let message_content = self.agent_message_content_from_invocation(tool_call_id)?;
|
||||
let carried_raw_payload_ids = self.agent_tool_payload_ids(tool_call_id)?;
|
||||
self.queue_or_resolve_agent_interaction_edge(PendingAgentInteractionEdge {
|
||||
edge_id,
|
||||
kind: edge_kind,
|
||||
source: TraceAnchor::ToolCall {
|
||||
tool_call_id: tool_call_id.to_string(),
|
||||
},
|
||||
target_thread_id,
|
||||
message_content,
|
||||
unresolved_spawn_thread_id,
|
||||
started_at_unix_ms,
|
||||
ended_at_unix_ms: Some(wall_time_unix_ms),
|
||||
carried_raw_payload_ids,
|
||||
})
|
||||
}
|
||||
|
||||
fn agent_message_content_from_invocation(&self, tool_call_id: &str) -> Result<String> {
|
||||
let tool_call = self.rollout.tool_calls.get(tool_call_id).with_context(|| {
|
||||
format!("agent activity referenced unknown tool call {tool_call_id}")
|
||||
})?;
|
||||
let invocation_payload_id = tool_call
|
||||
.raw_invocation_payload_id
|
||||
.as_deref()
|
||||
.with_context(|| {
|
||||
format!("agent activity tool call {tool_call_id} missing invocation payload")
|
||||
})?;
|
||||
let invocation_payload = self
|
||||
.rollout
|
||||
.raw_payloads
|
||||
.get(invocation_payload_id)
|
||||
.with_context(|| {
|
||||
format!(
|
||||
"agent activity tool call {tool_call_id} referenced missing invocation payload {invocation_payload_id}"
|
||||
)
|
||||
})?;
|
||||
let invocation = self.read_payload_json(invocation_payload)?;
|
||||
let arguments = invocation
|
||||
.get("payload")
|
||||
.and_then(|payload| payload.get("arguments"))
|
||||
.and_then(Value::as_str)
|
||||
.with_context(|| {
|
||||
format!("agent activity tool call {tool_call_id} missing function arguments")
|
||||
})?;
|
||||
let args: AgentMessageInvocationArgs = serde_json::from_str(arguments)
|
||||
.with_context(|| format!("parse agent activity tool call {tool_call_id} arguments"))?;
|
||||
Ok(args.message)
|
||||
}
|
||||
|
||||
/// Adds the canonical tool result payload to an already reduced multi-agent edge.
|
||||
pub(super) fn attach_agent_interaction_tool_result(
|
||||
&mut self,
|
||||
|
||||
@@ -194,6 +194,92 @@ fn spawn_runtime_payload_falls_back_to_child_thread_without_delivery_item() -> a
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sub_agent_started_activity_creates_spawn_edge() -> anyhow::Result<()> {
|
||||
let temp = TempDir::new()?;
|
||||
let writer = create_started_agent_writer(&temp)?;
|
||||
start_agent_turn(&writer, "turn-1")?;
|
||||
let child_thread_id = "019d0000-0000-7000-8000-000000000002";
|
||||
let invocation_payload = writer.write_json_payload(
|
||||
RawPayloadKind::ToolInvocation,
|
||||
&json!({
|
||||
"tool_name": "spawn_agent",
|
||||
"payload": {
|
||||
"type": "function",
|
||||
"arguments": "{\"message\":\"review this\",\"task_name\":\"reviewer\"}"
|
||||
}
|
||||
}),
|
||||
)?;
|
||||
writer.append_with_context(
|
||||
trace_context_for_agent("turn-1"),
|
||||
RawTraceEventPayload::ToolCallStarted {
|
||||
tool_call_id: "call-spawn-v2".to_string(),
|
||||
model_visible_call_id: Some("call-spawn-v2".to_string()),
|
||||
code_mode_runtime_tool_id: None,
|
||||
requester: RawToolCallRequester::Model,
|
||||
kind: ToolCallKind::SpawnAgent,
|
||||
summary: ToolCallSummary::Generic {
|
||||
label: "spawn_agent".to_string(),
|
||||
input_preview: None,
|
||||
output_preview: None,
|
||||
},
|
||||
invocation_payload: Some(invocation_payload.clone()),
|
||||
},
|
||||
)?;
|
||||
let activity_payload = writer.write_json_payload(
|
||||
RawPayloadKind::ToolRuntimeEvent,
|
||||
&json!({
|
||||
"event_id": "call-spawn-v2",
|
||||
"occurred_at_ms": 1234,
|
||||
"agent_thread_id": child_thread_id,
|
||||
"agent_path": "/root/reviewer",
|
||||
"kind": "started"
|
||||
}),
|
||||
)?;
|
||||
writer.append_with_context(
|
||||
trace_context_for_agent("turn-1"),
|
||||
RawTraceEventPayload::ToolCallRuntimeEnded {
|
||||
tool_call_id: "call-spawn-v2".to_string(),
|
||||
status: ExecutionStatus::Completed,
|
||||
runtime_payload: activity_payload.clone(),
|
||||
},
|
||||
)?;
|
||||
start_thread(&writer, child_thread_id, "/root/reviewer")?;
|
||||
start_turn_for_thread(&writer, child_thread_id, "turn-child-1")?;
|
||||
let delivered = inter_agent_message(
|
||||
"/root",
|
||||
"/root/reviewer",
|
||||
"review this",
|
||||
/*trigger_turn*/ true,
|
||||
);
|
||||
append_inference_request(
|
||||
&writer,
|
||||
child_thread_id,
|
||||
"turn-child-1",
|
||||
"inference-child-1",
|
||||
vec![message("assistant", &delivered)],
|
||||
)?;
|
||||
|
||||
let replayed = replay_bundle(temp.path())?;
|
||||
let edge_id = format!("edge:spawn:019d0000-0000-7000-8000-000000000001:{child_thread_id}");
|
||||
let edge = &replayed.interaction_edges[&edge_id];
|
||||
assert_eq!(edge.kind, InteractionEdgeKind::SpawnAgent);
|
||||
let target_item_id = target_conversation_item_id(&edge.target);
|
||||
assert_eq!(edge.carried_item_ids, vec![target_item_id.clone()]);
|
||||
assert_eq!(
|
||||
replayed.conversation_items[target_item_id].thread_id,
|
||||
child_thread_id
|
||||
);
|
||||
assert_eq!(
|
||||
edge.carried_raw_payload_ids,
|
||||
vec![
|
||||
invocation_payload.raw_payload_id,
|
||||
activity_payload.raw_payload_id,
|
||||
]
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn send_message_runtime_payload_targets_delivered_child_message() -> anyhow::Result<()> {
|
||||
let temp = TempDir::new()?;
|
||||
@@ -300,6 +386,178 @@ fn send_message_runtime_payload_targets_delivered_child_message() -> anyhow::Res
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn send_message_activity_targets_delivered_child_message() -> anyhow::Result<()> {
|
||||
let temp = TempDir::new()?;
|
||||
let writer = create_started_agent_writer(&temp)?;
|
||||
start_agent_turn(&writer, "turn-1")?;
|
||||
let child_thread_id = "019d0000-0000-7000-8000-000000000002";
|
||||
let invocation_payload = writer.write_json_payload(
|
||||
RawPayloadKind::ToolInvocation,
|
||||
&json!({
|
||||
"tool_name": "send_message",
|
||||
"payload": {
|
||||
"type": "function",
|
||||
"arguments": "{\"target\":\"/root/child\",\"message\":\"hello again\"}"
|
||||
}
|
||||
}),
|
||||
)?;
|
||||
writer.append_with_context(
|
||||
trace_context_for_agent("turn-1"),
|
||||
RawTraceEventPayload::ToolCallStarted {
|
||||
tool_call_id: "call-send-v2".to_string(),
|
||||
model_visible_call_id: Some("call-send-v2".to_string()),
|
||||
code_mode_runtime_tool_id: None,
|
||||
requester: RawToolCallRequester::Model,
|
||||
kind: ToolCallKind::SendMessage,
|
||||
summary: ToolCallSummary::Generic {
|
||||
label: "send_message".to_string(),
|
||||
input_preview: None,
|
||||
output_preview: None,
|
||||
},
|
||||
invocation_payload: Some(invocation_payload.clone()),
|
||||
},
|
||||
)?;
|
||||
let activity_payload = writer.write_json_payload(
|
||||
RawPayloadKind::ToolRuntimeEvent,
|
||||
&json!({
|
||||
"event_id": "call-send-v2",
|
||||
"occurred_at_ms": 1234,
|
||||
"agent_thread_id": child_thread_id,
|
||||
"agent_path": "/root/child",
|
||||
"kind": "interacted"
|
||||
}),
|
||||
)?;
|
||||
writer.append_with_context(
|
||||
trace_context_for_agent("turn-1"),
|
||||
RawTraceEventPayload::ToolCallRuntimeEnded {
|
||||
tool_call_id: "call-send-v2".to_string(),
|
||||
status: ExecutionStatus::Completed,
|
||||
runtime_payload: activity_payload.clone(),
|
||||
},
|
||||
)?;
|
||||
start_thread(&writer, child_thread_id, "/root/child")?;
|
||||
start_turn_for_thread(&writer, child_thread_id, "turn-child-1")?;
|
||||
let delivered = inter_agent_message(
|
||||
"/root",
|
||||
"/root/child",
|
||||
"hello again",
|
||||
/*trigger_turn*/ false,
|
||||
);
|
||||
append_inference_request(
|
||||
&writer,
|
||||
child_thread_id,
|
||||
"turn-child-1",
|
||||
"inference-child-1",
|
||||
vec![message("assistant", &delivered)],
|
||||
)?;
|
||||
|
||||
let replayed = replay_bundle(temp.path())?;
|
||||
let edge = &replayed.interaction_edges["edge:tool:call-send-v2"];
|
||||
assert_eq!(edge.kind, InteractionEdgeKind::SendMessage);
|
||||
let target_item_id = target_conversation_item_id(&edge.target);
|
||||
assert_eq!(edge.carried_item_ids, vec![target_item_id.clone()]);
|
||||
assert_eq!(
|
||||
replayed.conversation_items[target_item_id].thread_id,
|
||||
child_thread_id
|
||||
);
|
||||
assert_eq!(
|
||||
edge.carried_raw_payload_ids,
|
||||
vec![
|
||||
invocation_payload.raw_payload_id,
|
||||
activity_payload.raw_payload_id,
|
||||
]
|
||||
);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn followup_activity_targets_delivered_child_message() -> anyhow::Result<()> {
|
||||
let temp = TempDir::new()?;
|
||||
let writer = create_started_agent_writer(&temp)?;
|
||||
start_agent_turn(&writer, "turn-1")?;
|
||||
let child_thread_id = "019d0000-0000-7000-8000-000000000002";
|
||||
let invocation_payload = writer.write_json_payload(
|
||||
RawPayloadKind::ToolInvocation,
|
||||
&json!({
|
||||
"tool_name": "followup_task",
|
||||
"payload": {
|
||||
"type": "function",
|
||||
"arguments": "{\"target\":\"/root/child\",\"message\":\"continue\"}"
|
||||
}
|
||||
}),
|
||||
)?;
|
||||
writer.append_with_context(
|
||||
trace_context_for_agent("turn-1"),
|
||||
RawTraceEventPayload::ToolCallStarted {
|
||||
tool_call_id: "call-followup-v2".to_string(),
|
||||
model_visible_call_id: Some("call-followup-v2".to_string()),
|
||||
code_mode_runtime_tool_id: None,
|
||||
requester: RawToolCallRequester::Model,
|
||||
kind: ToolCallKind::AssignAgentTask,
|
||||
summary: ToolCallSummary::Generic {
|
||||
label: "followup_task".to_string(),
|
||||
input_preview: None,
|
||||
output_preview: None,
|
||||
},
|
||||
invocation_payload: Some(invocation_payload.clone()),
|
||||
},
|
||||
)?;
|
||||
let activity_payload = writer.write_json_payload(
|
||||
RawPayloadKind::ToolRuntimeEvent,
|
||||
&json!({
|
||||
"event_id": "call-followup-v2",
|
||||
"occurred_at_ms": 1234,
|
||||
"agent_thread_id": child_thread_id,
|
||||
"agent_path": "/root/child",
|
||||
"kind": "interacted"
|
||||
}),
|
||||
)?;
|
||||
writer.append_with_context(
|
||||
trace_context_for_agent("turn-1"),
|
||||
RawTraceEventPayload::ToolCallRuntimeEnded {
|
||||
tool_call_id: "call-followup-v2".to_string(),
|
||||
status: ExecutionStatus::Completed,
|
||||
runtime_payload: activity_payload.clone(),
|
||||
},
|
||||
)?;
|
||||
start_thread(&writer, child_thread_id, "/root/child")?;
|
||||
start_turn_for_thread(&writer, child_thread_id, "turn-child-1")?;
|
||||
let delivered = inter_agent_message(
|
||||
"/root",
|
||||
"/root/child",
|
||||
"continue",
|
||||
/*trigger_turn*/ true,
|
||||
);
|
||||
append_inference_request(
|
||||
&writer,
|
||||
child_thread_id,
|
||||
"turn-child-1",
|
||||
"inference-child-1",
|
||||
vec![message("assistant", &delivered)],
|
||||
)?;
|
||||
|
||||
let replayed = replay_bundle(temp.path())?;
|
||||
let edge = &replayed.interaction_edges["edge:tool:call-followup-v2"];
|
||||
assert_eq!(edge.kind, InteractionEdgeKind::AssignAgentTask);
|
||||
let target_item_id = target_conversation_item_id(&edge.target);
|
||||
assert_eq!(edge.carried_item_ids, vec![target_item_id.clone()]);
|
||||
assert_eq!(
|
||||
replayed.conversation_items[target_item_id].thread_id,
|
||||
child_thread_id
|
||||
);
|
||||
assert_eq!(
|
||||
edge.carried_raw_payload_ids,
|
||||
vec![
|
||||
invocation_payload.raw_payload_id,
|
||||
activity_payload.raw_payload_id,
|
||||
]
|
||||
);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn close_agent_runtime_payload_targets_thread() -> anyhow::Result<()> {
|
||||
let temp = TempDir::new()?;
|
||||
|
||||
Reference in new issue
Block a user