feat: add metrics/auth REST routes and wire frontend event handling

Backend:
- GET /api/metrics returns SpendingSummary, GET /api/metrics/:task_id
  returns per-task TaskMetrics (new metrics.rs route module)
- POST /api/auth/login, GET /api/auth/profile, POST /api/auth/logout
  cloud auth endpoints (added to cloud.rs)

Frontend:
- Add MetricsUpdateEvent, BudgetAlertEvent, GateResultEvent to
  ServerEvent union type
- Wire gate_result, metrics_update, budget_alert events in App.tsx
  handleServerEvent switch
- Add handleMetricsUpdate, handleGateResult, handleBudgetAlert actions
  and gateResults/budgetAlerts state to observability store
- Add fetchMetrics() action for REST-based dashboard loading

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: h4x0r

crates/shepherd-server/src/lib.rs

@@ -42,6 +42,11 @@ pub fn build_router(state: Arc<AppState>) -> Router {
             "/api/sessions/:id/fresh",
             post(routes::iterm2::fresh_session),
         )
+        .route("/api/auth/login", post(routes::cloud::auth_login))
+        .route("/api/auth/profile", get(routes::cloud::auth_profile))
+        .route("/api/auth/logout", post(routes::cloud::auth_logout))
+        .route("/api/metrics", get(routes::metrics::spending_summary))
+        .route("/api/metrics/:task_id", get(routes::metrics::task_metrics))
         .route("/api/cloud/status", get(routes::cloud::cloud_status))
         .route("/api/cloud/balance", get(routes::cloud::cloud_balance))
         .route("/api/cloud/costs", get(routes::cloud::cloud_costs))

crates/shepherd-server/src/routes/cloud.rs

@@ -91,6 +91,85 @@ pub async fn cloud_balance(
     }))
 }
 
+/// Login response — returns the OAuth login URL.
+#[derive(Debug, Serialize)]
+pub struct LoginResponse {
+    pub login_url: String,
+}
+
+/// POST /api/auth/login — returns the OAuth login URL.
+#[tracing::instrument(skip(state))]
+pub async fn auth_login(
+    State(state): State<Arc<AppState>>,
+) -> Result<Json<LoginResponse>, (StatusCode, Json<serde_json::Value>)> {
+    let cloud = state.cloud_client.as_ref().ok_or_else(|| {
+        (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(serde_json::json!({
+                "error": "Cloud features not available"
+            })),
+        )
+    })?;
+
+    Ok(Json(LoginResponse {
+        login_url: cloud.login_url(None, None),
+    }))
+}
+
+/// Profile response — user profile information.
+#[derive(Debug, Serialize)]
+pub struct ProfileResponse {
+    pub user_id: String,
+    pub email: Option<String>,
+    pub display_name: Option<String>,
+    pub plan: String,
+    pub credits_balance: u32,
+}
+
+/// GET /api/auth/profile — returns the cached user profile.
+#[tracing::instrument]
+pub async fn auth_profile() -> Result<Json<ProfileResponse>, (StatusCode, Json<serde_json::Value>)>
+{
+    if !cloud::auth::is_authenticated() {
+        return Err((
+            StatusCode::UNAUTHORIZED,
+            Json(serde_json::json!({
+                "error": "Not authenticated"
+            })),
+        ));
+    }
+
+    let profile = cloud::auth::load_cached_profile().ok_or_else(|| {
+        (
+            StatusCode::NOT_FOUND,
+            Json(serde_json::json!({
+                "error": "No cached profile found"
+            })),
+        )
+    })?;
+
+    Ok(Json(ProfileResponse {
+        user_id: profile.user_id,
+        email: profile.email,
+        display_name: profile.github_handle,
+        plan: profile.plan.to_string(),
+        credits_balance: profile.credits_balance,
+    }))
+}
+
+/// Logout response.
+#[derive(Debug, Serialize)]
+pub struct LogoutResponse {
+    pub success: bool,
+}
+
+/// POST /api/auth/logout — clears auth credentials and cached profile.
+#[tracing::instrument]
+pub async fn auth_logout() -> Json<LogoutResponse> {
+    let _ = cloud::auth::logout();
+    Json(LogoutResponse { success: true })
+}
+
 /// Feature cost info for the frontend.
 #[derive(Debug, Serialize)]
 pub struct FeatureCostResponse {
@@ -271,6 +350,69 @@ mod tests {
         assert_eq!(features[1]["credits"], 3);
     }
 
+    #[test]
+    fn auth_login_response_serialize() {
+        let resp = LoginResponse {
+            login_url: "https://api.shepherd.codes/api/auth/login?provider=github".to_string(),
+        };
+        let json = serde_json::to_value(&resp).unwrap();
+        assert_eq!(
+            json["login_url"],
+            "https://api.shepherd.codes/api/auth/login?provider=github"
+        );
+        // Ensure only expected fields are present
+        let obj = json.as_object().unwrap();
+        assert_eq!(obj.len(), 1);
+        assert!(obj.contains_key("login_url"));
+    }
+
+    #[test]
+    fn auth_profile_response_serialize() {
+        let resp = ProfileResponse {
+            user_id: "u-123".to_string(),
+            email: Some("user@example.com".to_string()),
+            display_name: Some("testuser".to_string()),
+            plan: "pro".to_string(),
+            credits_balance: 42,
+        };
+        let json = serde_json::to_value(&resp).unwrap();
+        assert_eq!(json["user_id"], "u-123");
+        assert_eq!(json["email"], "user@example.com");
+        assert_eq!(json["display_name"], "testuser");
+        assert_eq!(json["plan"], "pro");
+        assert_eq!(json["credits_balance"], 42);
+        // Ensure all expected fields are present
+        let obj = json.as_object().unwrap();
+        assert_eq!(obj.len(), 5);
+    }
+
+    #[test]
+    fn auth_profile_response_serialize_with_nulls() {
+        let resp = ProfileResponse {
+            user_id: "u-456".to_string(),
+            email: None,
+            display_name: None,
+            plan: "free".to_string(),
+            credits_balance: 0,
+        };
+        let json = serde_json::to_value(&resp).unwrap();
+        assert_eq!(json["user_id"], "u-456");
+        assert!(json["email"].is_null());
+        assert!(json["display_name"].is_null());
+        assert_eq!(json["plan"], "free");
+        assert_eq!(json["credits_balance"], 0);
+    }
+
+    #[test]
+    fn auth_logout_response_serialize() {
+        let resp = LogoutResponse { success: true };
+        let json = serde_json::to_value(&resp).unwrap();
+        assert!(json["success"].as_bool().unwrap());
+        let obj = json.as_object().unwrap();
+        assert_eq!(obj.len(), 1);
+        assert!(obj.contains_key("success"));
+    }
+
     #[test]
     fn credit_balance_response_all_fields() {
         let resp = CreditBalanceResponse {

crates/shepherd-server/src/routes/metrics.rs

@@ -0,0 +1,135 @@
+use axum::{extract::Path, extract::State, http::StatusCode, Json};
+use shepherd_core::observability::{self, SpendingSummary, TaskMetrics};
+use std::sync::Arc;
+
+use crate::state::AppState;
+
+/// GET /api/metrics — return aggregate spending summary.
+#[tracing::instrument(skip(state))]
+pub async fn spending_summary(
+    State(state): State<Arc<AppState>>,
+) -> Result<Json<SpendingSummary>, (StatusCode, Json<serde_json::Value>)> {
+    let db = state.db.lock().await;
+    let summary = observability::store::get_spending_summary(&db).map_err(|e| {
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            Json(serde_json::json!({ "error": format!("{}", e) })),
+        )
+    })?;
+    Ok(Json(summary))
+}
+
+/// GET /api/metrics/:task_id — return metrics for a specific task.
+#[tracing::instrument(skip(state))]
+pub async fn task_metrics(
+    State(state): State<Arc<AppState>>,
+    Path(task_id): Path<i64>,
+) -> Result<Json<TaskMetrics>, (StatusCode, Json<serde_json::Value>)> {
+    let db = state.db.lock().await;
+    let metrics = observability::store::get_task_metrics(&db, task_id).map_err(|e| {
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            Json(serde_json::json!({ "error": format!("{}", e) })),
+        )
+    })?;
+    match metrics {
+        Some(m) => Ok(Json(m)),
+        None => Err((
+            StatusCode::NOT_FOUND,
+            Json(serde_json::json!({ "error": format!("No metrics found for task {}", task_id) })),
+        )),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use shepherd_core::observability::{
+        AgentSpending, ModelSpending, SpendingSummary, TaskMetrics,
+    };
+
+    #[test]
+    fn spending_summary_response_serialize() {
+        let summary = SpendingSummary {
+            total_cost_usd: 1.25,
+            total_tokens: 50_000,
+            total_tasks: 3,
+            total_llm_calls: 10,
+            by_agent: vec![AgentSpending {
+                agent_id: "claude".to_string(),
+                total_cost_usd: 1.25,
+                total_tokens: 50_000,
+                task_count: 3,
+            }],
+            by_model: vec![ModelSpending {
+                model_id: "claude-sonnet-4".to_string(),
+                total_cost_usd: 1.25,
+                total_tokens: 50_000,
+                call_count: 10,
+            }],
+        };
+
+        let json = serde_json::to_value(&summary).expect("serialize SpendingSummary");
+        assert_eq!(json["total_cost_usd"], 1.25);
+        assert_eq!(json["total_tokens"], 50_000);
+        assert_eq!(json["total_tasks"], 3);
+        assert_eq!(json["total_llm_calls"], 10);
+
+        let agents = json["by_agent"].as_array().expect("by_agent is array");
+        assert_eq!(agents.len(), 1);
+        assert_eq!(agents[0]["agent_id"], "claude");
+        assert_eq!(agents[0]["task_count"], 3);
+
+        let models = json["by_model"].as_array().expect("by_model is array");
+        assert_eq!(models.len(), 1);
+        assert_eq!(models[0]["model_id"], "claude-sonnet-4");
+        assert_eq!(models[0]["call_count"], 10);
+    }
+
+    #[test]
+    fn task_metrics_response_serialize() {
+        let metrics = TaskMetrics {
+            task_id: 42,
+            agent_id: "codex".to_string(),
+            model_id: "gpt-4o".to_string(),
+            total_input_tokens: 10_000,
+            total_output_tokens: 5_000,
+            total_tokens: 15_000,
+            total_cost_usd: 0.75,
+            llm_calls: 4,
+            duration_secs: Some(120.5),
+            status: "done".to_string(),
+            created_at: "2026-03-20T00:00:00Z".to_string(),
+            updated_at: "2026-03-20T00:05:00Z".to_string(),
+        };
+
+        let json = serde_json::to_value(&metrics).expect("serialize TaskMetrics");
+        assert_eq!(json["task_id"], 42);
+        assert_eq!(json["agent_id"], "codex");
+        assert_eq!(json["model_id"], "gpt-4o");
+        assert_eq!(json["total_input_tokens"], 10_000);
+        assert_eq!(json["total_output_tokens"], 5_000);
+        assert_eq!(json["total_tokens"], 15_000);
+        assert_eq!(json["total_cost_usd"], 0.75);
+        assert_eq!(json["llm_calls"], 4);
+        assert_eq!(json["duration_secs"], 120.5);
+        assert_eq!(json["status"], "done");
+        assert_eq!(json["created_at"], "2026-03-20T00:00:00Z");
+        assert_eq!(json["updated_at"], "2026-03-20T00:05:00Z");
+    }
+
+    #[test]
+    fn task_metrics_not_found_response() {
+        let task_id = 999;
+        let body = serde_json::json!({ "error": format!("No metrics found for task {}", task_id) });
+
+        assert_eq!(
+            body["error"].as_str().unwrap(),
+            "No metrics found for task 999"
+        );
+        // Verify the shape: single "error" key with a string value
+        let map = body.as_object().expect("response is a JSON object");
+        assert_eq!(map.len(), 1, "response should have exactly one key");
+        assert!(map.contains_key("error"), "key must be 'error'");
+        assert!(map["error"].is_string(), "error value must be a string");
+    }
+}

crates/shepherd-server/src/routes/mod.rs

@@ -3,6 +3,7 @@ pub mod gates;
 pub mod health;
 pub mod iterm2;
 pub mod logogen;
+pub mod metrics;
 pub mod namegen;
 pub mod northstar;
 pub mod pr;

src/App.tsx

@@ -47,6 +47,14 @@ const App: React.FC = () => {
         store.dispatchTerminalOutput(event.data.task_id, event.data.data);
         break;
       case "gate_result":
+        store.handleGateResult(event.data);
+        break;
+      case "metrics_update":
+        store.handleMetricsUpdate(event.data);
+        break;
+      case "budget_alert":
+        store.handleBudgetAlert(event.data);
+        break;
       case "notification":
         break;
     }