Feat/agent hub core successor identity tuple compatible

crates/common/src/agent_events.rs

@@ -1,15 +1,20 @@
 use std::fmt;
+use std::io;
 use std::sync::OnceLock;
 
 use chrono::{DateTime, Utc};
 use regex::Regex;
 use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::json;
 
 use crate::identity::{
-    validate_identity_tuple_and_placement_posture, IdentityTuple, PlacementPosture,
+    validate_identity_tuple_and_placement_posture, IdentityTuple, PlacementExecution,
+    PlacementPosture,
 };
 
 pub const AGENT_EVENT_CHANNEL_MAX_BYTES: usize = 64;
+const PURE_AGENT_ROUTER: &str = "agent_hub";
+const PURE_AGENT_PROTOCOL: &str = "uaa.agent.session";
 
 /// Canonical set of agent event categories.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
@@ -73,6 +78,8 @@ pub struct AgentEvent {
     pub agent_id: String,
     pub orchestration_session_id: String,
     pub run_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parent_run_id: Option<String>,
 
     // Attribution + correlation (optional)
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -84,6 +91,8 @@ pub struct AgentEvent {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub world_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub world_generation: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub cmd_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub span_id: Option<String>,
@@ -116,6 +125,8 @@ struct AgentEventDef {
     orchestration_session_id: String,
     run_id: String,
     #[serde(default)]
+    parent_run_id: Option<String>,
+    #[serde(default)]
     backend_id: Option<String>,
     #[serde(default)]
     thread_id: Option<String>,
@@ -124,12 +135,24 @@ struct AgentEventDef {
     #[serde(default)]
     world_id: Option<String>,
     #[serde(default)]
+    world_generation: Option<u64>,
+    #[serde(default)]
     cmd_id: Option<String>,
     #[serde(default)]
     span_id: Option<String>,
     #[serde(default, deserialize_with = "deserialize_sanitized_channel")]
     channel: Option<String>,
     #[serde(default)]
+    client: Option<String>,
+    #[serde(default)]
+    router: Option<String>,
+    #[serde(default)]
+    protocol: Option<String>,
+    #[serde(default)]
+    provider: Option<String>,
+    #[serde(default)]
+    auth_authority: Option<String>,
+    #[serde(default)]
     identity_tuple: Option<IdentityTuple>,
     #[serde(default)]
     placement_posture: Option<PlacementPosture>,
@@ -173,11 +196,13 @@ impl AgentEvent {
             kind,
             orchestration_session_id: orchestration_session_id.into(),
             run_id: run_id.into(),
+            parent_run_id: None,
             data,
             backend_id: None,
             thread_id: None,
             role: None,
             world_id: None,
+            world_generation: None,
             cmd_id: None,
             span_id: None,
             channel: None,
@@ -253,27 +278,100 @@ impl AgentEvent {
             self.placement_posture.as_ref(),
         )
     }
+
+    pub fn set_pure_agent_telemetry_identity(&mut self, client: impl Into<String>) {
+        if self.identity_tuple.is_none() {
+            self.identity_tuple = Some(IdentityTuple {
+                client: client.into(),
+                router: PURE_AGENT_ROUTER.to_string(),
+                protocol: PURE_AGENT_PROTOCOL.to_string(),
+                provider: None,
+                auth_authority: None,
+            });
+        }
+
+        if self.placement_posture.is_none() {
+            self.placement_posture = Some(PlacementPosture {
+                execution: if self.world_id.is_some() {
+                    PlacementExecution::InWorld
+                } else {
+                    PlacementExecution::HostOnly
+                },
+                host_to_world_bridge: None,
+            });
+        }
+    }
+
+    pub fn to_trace_record(&self) -> Result<serde_json::Value, serde_json::Error> {
+        let mut entry = serde_json::to_value(self)?;
+        let Some(obj) = entry.as_object_mut() else {
+            return Err(serde_json::Error::io(io::Error::other(
+                "agent event must serialize as a JSON object",
+            )));
+        };
+
+        if let Some(tuple) = self.identity_tuple.as_ref() {
+            obj.insert("client".to_string(), json!(tuple.client));
+            obj.insert("router".to_string(), json!(tuple.router));
+            obj.insert("protocol".to_string(), json!(tuple.protocol));
+
+            match tuple.provider.as_deref() {
+                Some(provider) => {
+                    obj.insert("provider".to_string(), json!(provider));
+                }
+                None => {
+                    obj.remove("provider");
+                }
+            }
+
+            match tuple.auth_authority.as_deref() {
+                Some(auth_authority) => {
+                    obj.insert("auth_authority".to_string(), json!(auth_authority));
+                }
+                None => {
+                    obj.remove("auth_authority");
+                }
+            }
+        }
+
+        Ok(entry)
+    }
 }
 
 impl TryFrom<AgentEventDef> for AgentEvent {
     type Error = String;
 
     fn try_from(value: AgentEventDef) -> Result<Self, Self::Error> {
+        let identity_tuple = value.identity_tuple.or_else(|| {
+            let client = value.client?;
+            let router = value.router?;
+            let protocol = value.protocol?;
+            Some(IdentityTuple {
+                client,
+                router,
+                protocol,
+                provider: value.provider,
+                auth_authority: value.auth_authority,
+            })
+        });
+
         let event = Self {
             ts: value.ts,
             kind: value.kind,
             data: value.data,
             agent_id: value.agent_id,
             orchestration_session_id: value.orchestration_session_id,
             run_id: value.run_id,
+            parent_run_id: value.parent_run_id,
             backend_id: value.backend_id,
             thread_id: value.thread_id,
             role: value.role,
             world_id: value.world_id,
+            world_generation: value.world_generation,
             cmd_id: value.cmd_id,
             span_id: value.span_id,
             channel: value.channel,
-            identity_tuple: value.identity_tuple,
+            identity_tuple,
             placement_posture: value.placement_posture,
             project: value.project,
         };

crates/common/src/agent_identity.rs

@@ -0,0 +1,3 @@
+pub fn derive_agent_backend_id(kind: &str, agent_id: &str) -> String {
+    format!("{}:{}", kind.trim(), agent_id.trim())
+}

crates/common/src/lib.rs

@@ -4,6 +4,7 @@ use serde::{Deserialize, Serialize};
 use std::collections::{HashMap, HashSet};
 
 pub mod agent_events;
+pub mod agent_identity;
 pub mod fs_diff;
 pub mod identity;
 pub mod manager_manifest;
@@ -12,6 +13,7 @@ pub mod settings;
 pub mod world_exec_guard;
 
 pub use agent_events::{AgentEvent, AgentEventKind};
+pub use agent_identity::derive_agent_backend_id;
 pub use fs_diff::FsDiff;
 pub use identity::{
     validate_identity_tuple_and_placement_posture, IdentityTuple, PlacementExecution,

crates/common/tests/agent_hub_event_envelope_schema.rs

@@ -50,6 +50,40 @@ fn envelope_missing_required_fields_is_rejected() {
     );
 }
 
+#[test]
+fn parent_run_id_roundtrips_when_present() {
+    let mut value = minimal_valid_envelope_json();
+    value.as_object_mut().expect("envelope object").insert(
+        "parent_run_id".to_string(),
+        json!("0195f8f1-7a35-7b7f-9c4d-9a7c2f5d6f11"),
+    );
+
+    let event: AgentEvent = serde_json::from_value(value).expect("deserialize AgentEvent");
+    let roundtrip = serde_json::to_value(&event).expect("serialize AgentEvent");
+
+    assert_eq!(
+        roundtrip.get("parent_run_id").and_then(Value::as_str),
+        Some("0195f8f1-7a35-7b7f-9c4d-9a7c2f5d6f11"),
+        "expected parent_run_id to survive roundtrip; got: {roundtrip}"
+    );
+}
+
+#[test]
+fn parent_run_id_omits_by_field_absence_when_unset() {
+    let event: AgentEvent =
+        serde_json::from_value(minimal_valid_envelope_json()).expect("deserialize AgentEvent");
+    let roundtrip = serde_json::to_value(&event).expect("serialize AgentEvent");
+
+    assert!(
+        roundtrip.get("parent_run_id").is_none(),
+        "expected parent_run_id to omit when unset; got: {roundtrip}"
+    );
+    assert!(
+        !roundtrip.to_string().contains("\"parent_run_id\":null"),
+        "parent_run_id must not serialize as null when unset: {roundtrip}"
+    );
+}
+
 #[test]
 fn safe_channel_roundtrips() {
     let mut value = minimal_valid_envelope_json();
@@ -360,6 +394,7 @@ fn trace_tuple_metadata_preserves_existing_join_keys() {
         "agent_id": "demo-agent",
         "orchestration_session_id": "0195f8f1-7a34-7b7f-9c4d-9a7c2f5d6f12",
         "run_id": "0195f8f1-7a35-7b7f-9c4d-9a7c2f5d6f13",
+        "parent_run_id": "0195f8f1-7a35-7b7f-9c4d-9a7c2f5d6f10",
         "backend_id": "cli:codex",
         "world_id": "wld_test",
         "cmd_id": "cmd_test",
@@ -396,6 +431,10 @@ fn trace_tuple_metadata_preserves_existing_join_keys() {
         roundtrip.get("span_id").and_then(Value::as_str),
         Some("spn_test")
     );
+    assert_eq!(
+        roundtrip.get("parent_run_id").and_then(Value::as_str),
+        Some("0195f8f1-7a35-7b7f-9c4d-9a7c2f5d6f10")
+    );
     assert_eq!(
         roundtrip
             .pointer("/identity_tuple/router")