---
test_env: local
test_profile: agent-smoke
domain: agent
verification_type: smoke
last_rule_updated_at: 2026-06-12
---

# agent-smoke local 테스트

## 읽기 조건

- `apps/runner/lib/oto/agent/**`, `apps/runner/lib/cli/commands/command_agent.dart`, `apps/runner/assets/script/shell/oto_agent_bootstrap.sh`, `services/core/cmd/oto-core/main.go`, `services/core/internal/httpserver/**`, `services/core/internal/runnersocket/**`, 또는 `services/core/internal/runnerregistry/**` 변경 검증이 필요한 경우

## 적용 범위

- OTO agent 등록/설정/CLI/bootstrap smoke 경로
- OTO Server runner registration, bootstrap command, release URL validation 경로
- legacy iop smoke는 별도 iop 쪽 OTO 제거 작업의 검증 대상이며, 이 OTO 독립 마이그레이션 agent-smoke 필수 검증에서는 제외한다.

## 분류

- domain: agent
- verification_type: smoke
- scope: OTO agent 로컬 동작과 기존 smoke test

## 환경

- host: `ssh toki@toki-labs.com` 원격 runner, checkout `/Users/toki/agent-work/oto`
- port: OTO Core HTTP workspace host publish `18020`; local compatibility 기본값 `127.0.0.1:8080`
- runtime: Dart SDK, Go toolchain
- package manager: dart pub, Go modules
- docker: 기본 smoke는 Docker를 사용하지 않는다.
- external service: 없음
- model endpoint:
- credential: `OTO_RUNNER_RELEASE_BASE_URL`, enrollment token, private release host 원문은 tracked 파일에 기록하지 않는다.

## 포트/환경 체크리스트

- Core publish 검증은 원격 runner에서 `make core-run` 또는 `OTO_CORE_ADDR=0.0.0.0:18020 go run ./cmd/oto-core` 기준을 사용한다. `127.0.0.1:8080`은 기존 local default compatibility로만 남긴다.
- 외부 브라우저/클라이언트가 원격 Core에 접근해야 하면 `http://toki-labs.com:18020`을 서버 URL로 사용한다.
- bootstrap command는 `--server-url`을 기준 인자로 문서화한다. `--edge-url`은 script 호환 alias로만 본다.
- `OTO_RUNNER_RELEASE_BASE_URL`은 `https://` scheme만 허용한다. token, credential, private release host 원문은 테스트 규칙과 tracked 문서에 쓰지 않는다.
- OS별 bootstrap asset 이름은 README의 `Runner bootstrap asset matrix`와 테스트 fixture가 같은 값을 사용한다.
  - Linux: `oto-linux-x64.tar.gz`, `oto-linux-arm64.tar.gz`
  - macOS: `oto-macos-x64.tar.gz`, `oto-macos-arm64.tar.gz`
  - Windows: `oto-windows-x64.zip`, `oto-windows-arm64.zip`
- iop Edge/wire endpoint는 독립 OTO Control Plane smoke의 필수 검증 대상이 아니다.
- Control Plane의 기본 연결 방식은 proto-socket 기반입니다. HTTP 기반 runner 연결(job claim/polling/report/log/artifact)은 오직 legacy compatibility fallback으로만 사용하고 기본 smoke 대상이 아닙니다.

## 명령

- setup:
  - runner: `cd apps/runner && dart pub get` (또는 `make runner-get`)
  - core: `cd services/core && go mod download`
- lint:
  - runner: `cd apps/runner && dart analyze` (또는 `make runner-analyze`)
- unit:
  - runner: `cd apps/runner && dart test test/oto_agent_migration_plan_test.dart test/oto_agent_bootstrap_script_test.dart test/oto_agent_cli_test.dart test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart` (또는 `make runner-test`)
  - legacy iop: `make runner-test-legacy-iop` (수동 migration evidence 전용, 기본 `make runner-test`에서는 제외)
  - core: `cd services/core && go test ./...` (또는 `make core-test`)
- smoke:
- e2e:
- model:
- full-cycle:

## 필수 검증

- runner agent 도메인 변경 후 `cd apps/runner && dart analyze`를 실행한다.
- runner agent 도메인 변경 후 agent 관련 `cd apps/runner && dart test ...` 명령을 실행한다.
- services/core registration, bootstrap command, release URL validation 변경 후 `cd services/core && go test ./...`를 실행한다.
- OS별 bootstrap matrix 또는 release asset 이름을 바꾸면 `README.md`, `apps/runner/test/oto_agent_bootstrap_script_test.dart`, 이 문서의 asset 이름이 함께 갱신되었는지 확인한다.
- `apps/runner/lib/oto/agent/registration_client.dart` 또는 `services/core/internal/runnersocket/**` 변경 후 `oto_server_connection_smoke_test.dart` socket-first transport smoke group(heartbeat/lifecycle, cancel dispatch, idempotent close)이 통과해야 한다.

## 보조 검증

- 전체 현재 runner 회귀가 필요한 경우 `make runner-test`를 실행한다.
- legacy iop Edge 직접 연결 증거가 필요할 때만 `make runner-test-legacy-iop`를 수동 실행한다.
- OTO Server 전체 회귀가 필요한 경우 `make core-test`를 실행한다.

## 판정 기준

- `cd apps/runner && dart analyze`가 issue 없이 종료한다.
- 지정한 `cd apps/runner && dart test`가 모두 통과한다.
- 지정한 `cd services/core && go test ./...`가 모두 통과한다.
- `oto_server_connection_smoke_test.dart` socket-first transport smoke group의 heartbeat/lifecycle, cancel dispatch, idempotent close tests가 모두 통과한다. HTTP compatibility fallback HTTP group은 보조 evidence이며 기본 smoke 판정 기준이 아니다.

## 기준 출력 예시

```text
No issues found!
All tests passed!
```

## 차단 기준

- 원격 runner에 Dart SDK, Go toolchain, path dependency가 없어 `dart pub get`, `dart analyze`, `dart test`, `go test`를 시작할 수 없는 경우

## 보고 항목

- 실행한 명령:
- 성공한 검증:
- 실패/차단된 검증:
- 생략 사유:
- 남은 위험:

## 금지 사항

- 외부 iop endpoint, secret, token 원문을 테스트 규칙이나 tracked 문서에 기록하지 않는다.
