feat(team): add run state snapshot endpoint (#549)

## Summary
- Add a read-only `GET /api/teams/{id}/run-state` endpoint that returns
the authoritative active team run snapshot.
- Introduce `TeamRunStateResponse` with `active_run:
Option<TeamRunPayload>` and export it from `aionui-api-types`.
- Validate team ownership before reading existing session state,
returning `active_run: null` without creating sessions or runs.

## Validation
- `just push -u origin aionissue/fix-130884740-002`
- `cargo fmt --all -- --check`
- `cargo test -p aionui-api-types team_run_state_response --
--nocapture`
- `cargo test -p aionui-team run_state_returns_ -- --nocapture`
- `cargo test -p aionui-app trs -- --nocapture`
- `cargo clippy -p aionui-api-types -p aionui-team -p aionui-app -- -D
warnings`
- `git diff --check`

## Notes
- Paired AionUi PR: iOfficeAI/AionUi#3480
- No database migration is included.

Co-authored-by: zynx <>

Author: piorpua

crates/aionui-api-types/src/lib.rs

@@ -156,10 +156,10 @@ pub use team::{
     RenameAgentRequest, RenameTeamRequest, SendAgentMessageRequest, SendTeamMessageRequest, TeamAgentInput,
     TeamAgentRemovedPayload, TeamAgentRenamedPayload, TeamAgentResponse, TeamAgentSpawnedPayload,
     TeamAgentStatusPayload, TeamChildTurnPayload, TeamListResponse, TeamMcpPhase, TeamMcpRuntimeConfig,
-    TeamMcpStatusPayload, TeamResponse, TeamRunAckResponse, TeamRunPayload, TeamRunSource, TeamRunStatus,
-    TeamRunTargetRole, TeamRuntimeSeed, TeamSendMessageDelivery, TeamSendMessageQueuedResponse, TeamSendMessageReason,
-    TeamSendMessageStatus, TeamSendMessageTargetQueueState, TeamSessionBinding, TeamSlotRuntimeHealth,
-    TeamSlotWorkPayload, TeammateMessagePayload,
+    TeamMcpStatusPayload, TeamResponse, TeamRunAckResponse, TeamRunPayload, TeamRunSource, TeamRunStateResponse,
+    TeamRunStatus, TeamRunTargetRole, TeamRuntimeSeed, TeamSendMessageDelivery, TeamSendMessageQueuedResponse,
+    TeamSendMessageReason, TeamSendMessageStatus, TeamSendMessageTargetQueueState, TeamSessionBinding,
+    TeamSlotRuntimeHealth, TeamSlotWorkPayload, TeammateMessagePayload,
 };
 pub use team_mcp::{TEAM_MCP_SERVER_NAME, TeamMcpStdioConfig};
 pub use websocket::WebSocketMessage;

crates/aionui-api-types/src/team.rs

@@ -372,6 +372,11 @@ pub struct TeamRunPayload {
     pub slot_work: Vec<TeamSlotWorkPayload>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct TeamRunStateResponse {
+    pub active_run: Option<TeamRunPayload>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct TeamChildTurnPayload {
     pub team_id: String,
@@ -1452,6 +1457,57 @@ mod tests {
         assert_eq!(json["message_id"], "mailbox-1");
     }
 
+    fn active_run_payload() -> TeamRunPayload {
+        TeamRunPayload {
+            team_id: "team-1".to_owned(),
+            team_run_id: "run-1".to_owned(),
+            source: TeamRunSource::UserMessage,
+            has_user_intervention: true,
+            target_slot_id: "lead".to_owned(),
+            target_role: TeamRunTargetRole::Lead,
+            status: TeamRunStatus::Running,
+            active_child_count: 1,
+            pending_wake_count: 0,
+            starting_child_count: 0,
+            slot_work: vec![TeamSlotWorkPayload {
+                slot_id: "lead".to_owned(),
+                role: TeamRunTargetRole::Lead,
+                pending_wake_count: 0,
+                starting_child_count: 0,
+                paused: false,
+                suppressed_wake_count: 0,
+                active_turn_id: Some("turn-1".to_owned()),
+                active_turn_started_at_ms: Some(10),
+                active_turn_elapsed_ms: Some(20),
+                active_turn_slow: Some(false),
+                active_turn_slow_threshold_ms: Some(600_000),
+                runtime_health: None,
+            }],
+        }
+    }
+
+    #[test]
+    fn team_run_state_response_serializes_null_active_run() {
+        let value = serde_json::to_value(TeamRunStateResponse { active_run: None }).unwrap();
+        assert_eq!(value, serde_json::json!({ "active_run": null }));
+    }
+
+    #[test]
+    fn team_run_state_response_serializes_some_active_run() {
+        let payload = active_run_payload();
+        let value = serde_json::to_value(TeamRunStateResponse {
+            active_run: Some(payload.clone()),
+        })
+        .unwrap();
+
+        assert_eq!(value["active_run"]["team_id"], payload.team_id);
+        assert_eq!(value["active_run"]["team_run_id"], payload.team_run_id);
+        assert_eq!(value["active_run"]["source"], "user_message");
+        assert_eq!(value["active_run"]["has_user_intervention"], true);
+        assert_eq!(value["active_run"]["status"], "running");
+        assert_eq!(value["active_run"]["slot_work"][0]["slot_id"], "lead");
+    }
+
     #[test]
     fn team_run_payload_omits_sensitive_content() {
         let payload = TeamRunPayload {

crates/aionui-app/tests/team_e2e.rs

@@ -6,7 +6,7 @@ use serde_json::json;
 use tower::ServiceExt;
 
 use common::{
-    body_json, build_app, build_app_with_mock_agents, delete_with_token, get_with_token, json_with_token,
+    body_json, build_app, build_app_with_mock_agents, delete_with_token, get_request, get_with_token, json_with_token,
     setup_and_login,
 };
 
@@ -422,6 +422,98 @@ async fn pause_team_slot_endpoint_requires_owned_team_and_active_run() {
     assert!(body["success"].as_bool().is_some_and(|success| !success));
 }
 
+#[tokio::test]
+async fn trs1_run_state_returns_null_for_existing_team_without_active_run() {
+    let (mut app, services) = build_app_with_mock_agents().await;
+    let (token, csrf) = setup_and_login(&mut app, &services, "admin", "StrongP@ss1").await;
+    let data = create_team(&mut app, &token, &csrf).await;
+    let team_id = data["id"].as_str().unwrap();
+
+    let stop_req = delete_with_token(&format!("/api/teams/{team_id}/session"), &token, &csrf);
+    let stop_resp = app.clone().oneshot(stop_req).await.unwrap();
+    assert_eq!(stop_resp.status(), StatusCode::OK);
+
+    let req = get_with_token(&format!("/api/teams/{team_id}/run-state"), &token);
+    let resp = app.oneshot(req).await.unwrap();
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = body_json(resp).await;
+    assert_eq!(body["success"], true);
+    assert!(body["data"]["active_run"].is_null());
+}
+
+#[tokio::test]
+async fn trs2_run_state_returns_active_run_payload() {
+    let (mut app, services) = build_app_with_mock_agents().await;
+    let (token, csrf) = setup_and_login(&mut app, &services, "admin", "StrongP@ss1").await;
+    let data = create_team(&mut app, &token, &csrf).await;
+    let team_id = data["id"].as_str().unwrap();
+
+    let send_req = json_with_token(
+        "POST",
+        &format!("/api/teams/{team_id}/messages"),
+        json!({ "content": "hello", "files": [] }),
+        &token,
+        &csrf,
+    );
+    let send_resp = app.clone().oneshot(send_req).await.unwrap();
+    assert_eq!(send_resp.status(), StatusCode::OK);
+    let send_body = body_json(send_resp).await;
+    let team_run_id = send_body["data"]["team_run_id"].as_str().unwrap();
+
+    let req = get_with_token(&format!("/api/teams/{team_id}/run-state"), &token);
+    let resp = app.oneshot(req).await.unwrap();
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = body_json(resp).await;
+    assert_eq!(body["success"], true);
+    assert_eq!(body["data"]["active_run"]["team_id"], team_id);
+    assert_eq!(body["data"]["active_run"]["team_run_id"], team_run_id);
+    assert_eq!(body["data"]["active_run"]["source"], "user_message");
+    assert_eq!(body["data"]["active_run"]["has_user_intervention"], true);
+    assert_eq!(body["data"]["active_run"]["status"], "accepted");
+    assert_eq!(body["data"]["active_run"]["pending_wake_count"], 1);
+    assert!(body["data"]["active_run"]["slot_work"].as_array().unwrap().len() >= 1);
+}
+
+#[tokio::test]
+async fn trs3_run_state_unauthenticated_returns_401() {
+    let (app, _services) = build_app().await;
+
+    let resp = app.oneshot(get_request("/api/teams/team-1/run-state")).await.unwrap();
+
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+    let body = body_json(resp).await;
+    assert_eq!(body["code"], "UNAUTHORIZED");
+}
+
+#[tokio::test]
+async fn trs4_run_state_missing_team_returns_404() {
+    let (mut app, services) = build_app().await;
+    let (token, _csrf) = setup_and_login(&mut app, &services, "admin", "StrongP@ss1").await;
+
+    let req = get_with_token("/api/teams/team-missing/run-state", &token);
+    let resp = app.oneshot(req).await.unwrap();
+
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn trs5_run_state_rejects_cross_user_access() {
+    let (mut app, services) = build_app_with_mock_agents().await;
+    let (admin_token, admin_csrf) = setup_and_login(&mut app, &services, "admin", "StrongP@ss1").await;
+    let data = create_team(&mut app, &admin_token, &admin_csrf).await;
+    let team_id = data["id"].as_str().unwrap();
+
+    let (other_token, _other_csrf) = setup_and_login(&mut app, &services, "other", "StrongP@ss2").await;
+    let req = get_with_token(&format!("/api/teams/{team_id}/run-state"), &other_token);
+    let resp = app.oneshot(req).await.unwrap();
+
+    assert_eq!(resp.status(), StatusCode::FORBIDDEN);
+    let body = body_json(resp).await;
+    assert_eq!(body["code"], "FORBIDDEN");
+}
+
 // TL-3: Each team contains full assistants info
 #[tokio::test]
 async fn tl3_teams_contain_full_agent_info() {

crates/aionui-team/src/routes.rs

@@ -11,7 +11,7 @@ use axum::routing::{get, post};
 use aionui_api_types::{
     AddAgentRequest, ApiResponse, CancelTeamChildTurnRequest, CancelTeamRunRequest, CreateTeamRequest,
     PauseTeamSlotRequest, RenameAgentRequest, RenameTeamRequest, SendAgentMessageRequest, SendTeamMessageRequest,
-    SetModeRequest, TeamAgentResponse, TeamListResponse, TeamResponse, TeamRunAckResponse,
+    SetModeRequest, TeamAgentResponse, TeamListResponse, TeamResponse, TeamRunAckResponse, TeamRunStateResponse,
 };
 use aionui_auth::CurrentUser;
 use aionui_common::ApiError;
@@ -67,6 +67,7 @@ pub fn team_routes(state: TeamRouterState) -> Router {
     Router::new()
         .route("/api/teams", post(create_team).get(list_teams))
         .route("/api/teams/{id}", get(get_team).delete(remove_team))
+        .route("/api/teams/{id}/run-state", get(get_run_state))
         .route("/api/teams/{id}/name", axum::routing::patch(rename_team))
         .route("/api/teams/{id}/agents", post(add_agent))
         .route("/api/teams/{id}/agents/{slot_id}", axum::routing::delete(remove_agent))
@@ -117,6 +118,15 @@ async fn get_team(
     Ok(Json(ApiResponse::ok(team)))
 }
 
+async fn get_run_state(
+    State(state): State<TeamRouterState>,
+    Extension(user): Extension<CurrentUser>,
+    Path(id): Path<String>,
+) -> Result<Json<ApiResponse<TeamRunStateResponse>>, ApiError> {
+    let run_state = state.service.get_run_state(&user.id, &id).await?;
+    Ok(Json(ApiResponse::ok(run_state)))
+}
+
 async fn remove_team(
     State(state): State<TeamRouterState>,
     Extension(user): Extension<CurrentUser>,

crates/aionui-team/src/service.rs

@@ -8,7 +8,7 @@ use std::sync::{Arc, Weak};
 use aionui_ai_agent::{AgentError, AgentInstance, IWorkerTaskManager};
 use aionui_api_types::{
     AddAgentRequest, CreateTeamRequest, TeamAgentResponse, TeamMcpPhase, TeamMcpStatusPayload, TeamResponse,
-    TeamRunAckResponse, TeamRunTargetRole, WebSocketMessage,
+    TeamRunAckResponse, TeamRunStateResponse, TeamRunTargetRole, WebSocketMessage,
 };
 use aionui_common::{AgentKillReason, generate_id, now_ms};
 use aionui_db::models::TeamRow;
@@ -697,6 +697,17 @@ impl TeamSessionService {
         self.sessions.get(team_id).map(|e| e.session.user_id().to_owned())
     }
 
+    pub async fn get_run_state(&self, user_id: &str, team_id: &str) -> Result<TeamRunStateResponse, TeamError> {
+        self.load_owned_team(user_id, team_id).await?;
+        let session = self.sessions.get(team_id).map(|entry| Arc::clone(&entry.session));
+        let active_run = match session {
+            Some(session) => session.team_run_manager().current_payload().await,
+            None => None,
+        };
+
+        Ok(TeamRunStateResponse { active_run })
+    }
+
     pub fn get_session_scheduler(&self, team_id: &str) -> Option<Arc<crate::scheduler::TeammateManager>> {
         self.sessions.get(team_id).map(|e| e.session.scheduler().clone())
     }
@@ -709,6 +720,11 @@ impl TeamSessionService {
             .unwrap_or(false)
     }
 
+    #[cfg(test)]
+    fn session_count_for_test(&self) -> usize {
+        self.sessions.len()
+    }
+
     pub async fn stop_session(&self, user_id: &str, team_id: &str) -> Result<(), TeamError> {
         self.load_owned_team(user_id, team_id).await?;
         self.stop_session_unchecked(team_id);
@@ -1002,4 +1018,43 @@ mod tests {
         assert!(svc.session_has_slow_monitor(&created.id));
         svc.stop_session("user-test", &created.id).await.unwrap();
     }
+
+    #[tokio::test]
+    async fn run_state_returns_none_without_session_and_does_not_create_session() {
+        let (svc, _repo, _task_manager, _conv_repo) = setup_with_factory_metadata_team_repo_and_conversation_repo();
+        let created = svc
+            .create_team("user-test", single_agent_team_request("Run State"))
+            .await
+            .unwrap();
+        svc.stop_session("user-test", &created.id).await.unwrap();
+
+        assert_eq!(svc.session_count_for_test(), 0);
+
+        let state = svc.get_run_state("user-test", &created.id).await.unwrap();
+
+        assert!(state.active_run.is_none());
+        assert_eq!(svc.session_count_for_test(), 0);
+    }
+
+    #[tokio::test]
+    async fn run_state_returns_current_active_payload() {
+        let (svc, _repo, _task_manager, _conv_repo) = setup_with_factory_metadata_team_repo_and_conversation_repo();
+        let created = svc
+            .create_team("user-test", single_agent_team_request("Active Run State"))
+            .await
+            .unwrap();
+
+        let ack = svc.send_message("user-test", &created.id, "hello", None).await.unwrap();
+        let state = svc.get_run_state("user-test", &created.id).await.unwrap();
+        let active_run = state.active_run.expect("active run state");
+
+        assert_eq!(active_run.team_id, created.id);
+        assert_eq!(active_run.team_run_id, ack.team_run_id);
+        assert_eq!(active_run.status, ack.status);
+        assert_eq!(active_run.target_slot_id, ack.target_slot_id);
+        assert_eq!(active_run.target_role, ack.target_role);
+        assert_eq!(active_run.pending_wake_count, 1);
+        assert_eq!(active_run.slot_work.len(), 1);
+        assert_eq!(active_run.slot_work[0].slot_id, ack.accepted_slot_id);
+    }
 }