# ADR-UI-03: Run Monitor UI

**狀態**：Accepted
**日期**：2026-05-03（台北）
**決策者**：統帥
**範圍**：M5 Run Monitor + M6 Run Detail 的詳細設計
**關聯**：ADR-UI-01（架構）、ADR-114（worker lease）、ADR-119（SAGA）、ADR-120（budget）

---

## M5 — Run Monitor

### 頁面設計

**路由**：`/awooop/runs`

**主要資訊（即時更新，SSE）**：

```
┌──────────────────────────────────────────────────────────────────────────────┐
│ Run Monitor          Filter: [All Projects ▼] [Status ▼] [Agent ▼]  🔴 Live │
├────────────────────┬───────────────────┬───────────────┬──────────┬──────────┤
│ Run ID             │ Project / Agent   │ Status        │ Budget   │ Started  │
├────────────────────┼───────────────────┼───────────────┼──────────┼──────────┤
│ abc123...          │ awoooi / openclaw │ 🟡 RUNNING    │ $0.12/$1 │ 14:23:01 │
│ def456...          │ awoooi / openclaw │ 🔵 WAITING    │ $0.08/$1 │ 14:20:45 │
│                    │                   │  _APPROVAL    │          │          │
│ ghi789...          │ awoooi / openclaw │ ✅ COMPLETED  │ $0.45/$1 │ 14:15:00 │
│ jkl012...          │ awoooi / openclaw │ ❌ FAILED     │ $0.30/$1 │ 14:10:22 │
└────────────────────┴───────────────────┴───────────────┴──────────┴──────────┘
```

**狀態顏色對應**（ADR-114 D4 狀態機）：
- 🟡 RUNNING：黃色（進行中）
- 🔵 WAITING_APPROVAL：藍色（等待人工）
- ⚪ WAITING_TOOL：灰色（等待工具）
- ✅ COMPLETED：綠色
- ❌ FAILED：紅色
- 🚫 CANCELLED：灰色刪除線

**Budget 進度條**：

```tsx
<BudgetBar
  used={run.total_cost_usd}
  limit={run.token_budget_usd}
  // 80% → warning color，95% → critical color
/>
```

### SSE 連線

```typescript
// apps/web/src/lib/awooop/runs.ts
export function subscribeToRunUpdates(
  projectId: string,
  onUpdate: (update: RunStateUpdate) => void
) {
  const url = `/v1/platform/runs/stream?project_id=${projectId}&status=RUNNING,WAITING_APPROVAL`
  const es = new EventSource(url)

  es.onmessage = (event) => {
    const update: RunStateUpdate = JSON.parse(event.data)
    onUpdate(update)
  }

  return () => es.close()  // cleanup
}
```

---

## M6 — Run Detail

### 頁面設計

**路由**：`/awooop/runs/[run_id]`

**頁面分 Tab**：

```
[Overview] [SAGA Steps] [Budget] [Trace]
```

#### Tab 1: Overview

```
Run: abc12345-...
Status: RUNNING       Worker: worker-pod-abc   Attempt: 1/3
Agent: openclaw-sre   Project: awoooi
Started: 2026-05-04 14:23:01 (台北)
Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736

Channel: Telegram | Subject: awoooi:telegram:123456789
Trigger: "請幫我重啟 api deployment"
```

#### Tab 2: SAGA Steps（ADR-119）

```
Step 1 [LLM Call]     ✅ completed    14:23:01 → 14:23:04 (3.2s)
  ↳ Model: llama3.2 | Tokens: 512+128 | Cost: $0.0042
  ↳ Decision: tool_call → k8s_scale_deployment

Step 2 [Tool Call]    ✅ completed    14:23:04 → 14:23:07 (3.1s)
  ↳ Tool: k8s_scale_deployment
  ↳ Params: {deployment: "api", replicas: 3 → 1}
  ↳ Compensation: scale back to 3 ← [如果此 step 要補償]

Step 3 [Approval Req] 🔵 pending      14:23:07 → ...
  ↳ Waiting for human approval
  ↳ Token expires: 14:38:07 (14分鐘後)

[Run SAGA Compensation]  ← 緊急按鈕（只有 admin 可見）
```

SAGA Step 視圖特別功能：
- 補償命令（compensation_cmd）展開顯示
- 緊急 SAGA 補償按鈕（確認對話框後觸發）

#### Tab 3: Budget

```
Token Budget: [$0.12 / $1.00]  ████░░░░░░  12%

Per-call Breakdown:
  Step 1 LLM: 512 prompt + 128 completion = $0.0042
  Step 2 Tool: —（不計 token）
  ──────────────────────────────────────
  Total: 640 tokens | $0.0042

Daily Tenant Budget: [$1.23 / $10.00]  12.3%
```

#### Tab 4: Trace（OTel）

```
Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
[在 SignOz 查看 →]  ← 外部連結到 SignOz 188:3301

Span List:
  chat ollama (openclaw-sre/awoooi)  3.2s  ✅
  ├── gen_ai.request.model: llama3.2
  ├── gen_ai.usage.prompt_tokens: 512
  └── gen_ai.usage.completion_tokens: 128
```

SignOz 連結（從環境變數）：
```typescript
const SIGNOZ_BASE_URL = process.env.NEXT_PUBLIC_SIGNOZ_URL
// 設置：NEXT_PUBLIC_SIGNOZ_URL=http://192.168.0.188:3301
// 注意：這是監控工具的內網 URL，不進 JS Bundle 的 public API call，只作為連結目標
```

---

## 後果

### Benefits
- Run Monitor 即時顯示所有 RUNNING + WAITING_APPROVAL run（SSE）
- Run Detail 的 SAGA Steps tab 讓 operator 清楚看到每步的執行狀況
- Budget tab：run 級和 tenant 級 budget 可視化
- 緊急 SAGA 補償按鈕：operator 可手動觸發補償（高風險操作，需確認）

### Costs
- SSE 連線維持 → server 端需要 AsyncGenerator endpoint（約 30 行）
- SignOz 連結是外部連結，不嵌入（避免 CSP 問題）

---

## 驗收標準

- [ ] M5：RUNNING + WAITING_APPROVAL run 即時更新（SSE 整合測試）
- [ ] M5：Budget bar 80%/95% 顏色正確（視覺測試）
- [ ] M6：SAGA Steps 展開顯示補償命令（Phase 5）
- [ ] M6：Budget tab 顯示 per-call breakdown（Phase 5）
- [ ] M6：緊急 SAGA 補償按鈕 → 確認對話框 → API 呼叫（整合測試）

## 關聯

- ADR-UI-01（路由結構）
- ADR-114（run 狀態機，狀態顏色對應）
- ADR-119（SAGA steps，Tab 2 資料來源）
- ADR-120（budget，Tab 3 資料來源）
- ADR-121（OTel spans，Tab 4）
