---
ui_doc_type: view
view_id: runners
status: 구현됨
frame: null
source_evidence:
  - type: code
    path: packages/flutter/oto_console/lib/src/oto_runners_surface.dart
    notes: "OtoRunnersSurface 구현"
  - type: code
    path: apps/client/lib/src/app/oto_client_app.dart
    notes: "runner snapshot과 self-update action 연결"
  - type: docs
    path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md
    notes: "runner self-update는 write action 감사 후보"
  - type: user
    path: null
    notes: "agent-ui 생성 요청"
regions:
  - runners.header
  - runners.state-panel
  - runners.runner-list
  - runners.self-update-form
  - runners.action-feedback
---

# Runners

View ID: `runners`

Frame:
- 없음

Status: `구현됨`

## Source Evidence

| Type | Path | Notes |
|------|------|-------|
| code | `packages/flutter/oto_console/lib/src/oto_runners_surface.dart` | `OtoRunnersSurface` 구현 |
| code | `apps/client/lib/src/app/oto_client_app.dart` | runner snapshot과 self-update action 연결 |
| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | runner self-update write action 경계 |
| user | 없음 | agent-ui 생성 요청 |

## Purpose

등록된 runner 상태를 보고, runner별 self-update 요청을 제출하며, action 결과를 확인한다.

## Primary Users

- operator/admin
- local developer

## Primary Tasks

- runner registry 상태 확인
- active job/execution 확인
- self-update version과 HTTPS download URL 제출
- success/deferred/failed 결과 확인

## Information Priority

1. runner id와 status
2. active job/execution context
3. self-update form과 action feedback

## Jenkins Reference Alignment

- Jenkins Nodes and Clouds/agent list를 OTO runner registry의 러프 참조로 삼는다.
- row는 agent/node처럼 id, alias, status, offline/online message, 현재 job/execution context를 우선 보여준다.
- Jenkins changelog의 "temporarily offline" 같은 agent 상태 혼동 방지 흐름을 참고해, runner 상태 label과 message는 분리해서 읽히게 유지한다.
- self-update는 Jenkins core plugin action과 동일시하지 않고 OTO 고유 write action으로 둔다. 다만 결과 feedback은 Jenkins 관리 action처럼 즉시 확인 가능해야 한다.

## Target Layout Delta

- runner list는 Jenkins Nodes/Agents처럼 status, executor/work context, message를 먼저 스캔하는 dense row layout으로 재정렬한다.
- self-update form은 row 하단에 항상 펼쳐진 form이 아니라 관리 action 영역으로 묶는 방향을 목표로 둔다.
- empty/error state는 Jenkins monitor/banner 흐름처럼 다음 확인 지점을 드러내는 상태 panel로 정리한다.
- 현재 코드는 dense runner row와 관리 action 영역 반영이 완료되어 `구현됨` 상태다.

## Regions

| Region ID | Purpose | Component | Priority | Notes |
|-----------|---------|-----------|----------|-------|
| `runners.header` | 화면 제목 | 없음 | high | `Runners` |
| `runners.state-panel` | loading/empty/error 표현 | `state-panel` | high | snapshot state 기준 |
| `runners.runner-list` | runner row 목록 | `record-list` | high | runner id, alias, message, current job/execution |
| `runners.self-update-form` | runner self-update draft 입력 | `runner-self-update-form` | high | version, HTTPS download URL |
| `runners.action-feedback` | self-update 결과 표시 | `action-feedback` | medium | success/deferred/failed |

## Actions

| Action ID | Trigger | Result | Guard |
|-----------|---------|--------|-------|
| `runners.self-update` | Update button | runner self-update draft submit | version 값, HTTPS URL, handler 존재, not submitting |

## States

- loading: 중앙 progress indicator.
- empty: `No runners connected` state panel.
- error: `Error loading runners` state panel과 snapshot error message.
- permission-denied: 계획 `authorization-state` component에서 operator/admin 권한 실패를 display-safe message로 표현한다.

## Planned Extensions

- `authorization-state`: self-update action의 허용/거부, disabled/error 상태.
- `audit-action-summary`: self-update action의 actor/action/target/outcome/timestamp/reason metadata 요약.

## Open Questions

- 없음

## Decision History

- 2026-06-24: runner list와 self-update form을 주요 region으로 정의했다.
