← Docs hub

TaskManager 사양 6 · 운영, 보안과 검증

관측성, 영속성, 용량, 보안, 실패 UX, 인수 시험과 변경 절차를 정의한다.

이 장의 결론: 출시 판정은 코드 존재가 아니라 요청부터 실제 terminal 증거까지 이어지는 반복 검증으로 결정한다.

21. 모니터링과 관측성

21.1 운영자가 봐야 하는 상태

Task Monitor와 A2A Text Console은 같은 정보를 다른 관점으로 보여준다.

• Task Monitor: DeviceAgent의 실제 실행 상태 중심
• Text Console: Planner 판단, 요청, 콜백과 기기 컨텍스트의 연결 중심

21.2 필수 상관관계

21.3 UI에서 구분해야 하는 상태

• 접수됨과 실행 중
• 실행 중과 완료 증거 대기
• 완료와 취소
• 실패와 차단
• 현재 단계와 다음 대기 단계
• Planner 계획과 DeviceAgent 실제 진행
• 현재 컨텍스트와 계획 시점 스냅숏

21.4 운영 지표

현재 런타임은 Task 최종 결과와 대기열 상태를 바탕으로 다음 운영 지표를 만들 수 있다.

• 제출/완료/실패/부분실패/취소 수
• 대기열별 대기·실행 Task 수
• Task 실행 시간
• 재시도 수
• 시간 초과 수
• 실패 사유 코드 분포
• Workflow 단계 성공률
• 예약의 실행 허용·차단·미실행 수
• 취소·보상 동작 성공률

제품 지표는 단순 접수 비율이 아니라 실제 완료 증거를 기준으로 산정해야 한다.

22. 영속성·용량·런타임 설정

22.1 TaskManager 속성

persist.sys.deviceagent.taskmanager.enable
persist.sys.deviceagent.taskmanager.legacy_queue
persist.sys.deviceagent.taskmanager.queue_size
persist.sys.deviceagent.taskmanager.persist
persist.sys.deviceagent.taskmanager.persist_path
persist.sys.deviceagent.taskmanager.schedule_persist
persist.sys.deviceagent.taskmanager.schedule_persist_path
persist.sys.deviceagent.taskmanager.strict_validation
persist.sys.deviceagent.taskmanager.executor_dry_run
persist.sys.deviceagent.taskmanager.scheduler.enable
persist.sys.deviceagent.taskmanager.scheduler.interval_ms
persist.sys.deviceagent.taskmanager.scheduler.limit
persist.sys.deviceagent.taskmanager.scheduler.exact_alarm
persist.sys.deviceagent.taskmanager.resource_policy
persist.sys.deviceagent.taskmanager.cpu_limit
persist.sys.deviceagent.taskmanager.ram_pressure_limit
persist.sys.deviceagent.taskmanager.thermal_limit
persist.sys.deviceagent.taskmanager.move_timeout_ms
persist.sys.deviceagent.taskmanager.clean_dwell_ms

22.2 기본값

22.3 영속성 원칙

• 최종 상태의 실행 기록은 디버깅과 운영 분석을 위해 제한적으로 보존한다.
• 장기 보관은 DeviceAgent 메모리 내 기록이 아니라 외부 관측 저장소가 담당한다.
• 부팅 복원 시 RUNNING을 그대로 재개했다고 가정하면 안 된다.
• 기기 동작 Task를 다시 실행하기 전에 멱등성과 현재 상태를 확인한다.
• 예약 저장소 쓰기 실패를 등록 성공으로 숨기면 안 된다.

현재 일반 Task 영속성은 persistTaskSnapshot()이 Task ID, 메서드, 대기열, 상태, 진행률과 시각을 JSON으로 남기는 쓰기 전용 진단 스냅숏이다. 이를 읽어 TaskRecord와 비동기 실행을 복원하는 런타임은 없다. 반면 지연 예약은 허용된 Bundle 키를 저장하고 ScheduledTaskRecord를 다시 읽는 별도 경로가 있다. 두 영속성 기능을 같은 수준의 장애 복구 기능으로 표현하면 안 된다.

22.4 용량 관리 원칙

• 대기열 포화는 DEVICE_BUSY로 정규화한다.
• 빈도가 높은 센서 갱신은 Task 대기열로 보내지 않는다.
• 연결 상태 보고와 진행 이벤트는 표본 추출과 빈도 제한을 적용한다.
• 장기 Workflow가 대기열 작업자를 과도하게 점유하지 않도록 도메인 콜백 기반 대기와 전용 런타임 분리를 검토한다.

23. 보안과 권한

23.1 Binder 경계

TaskManager API는 DeviceAgent Binder를 통과한다. 제품 배포에서 확인할 항목:

• DeviceAgent와 클라이언트 APK 인증서
• 서명 권한
• 패키지 UID와 설치 경로
• 외부 공개 컴포넌트
• 콜백 클래스 등록
• 호출자 식별 검증

23.2 시스템 앱 배포

• DeviceAgent와 MaumAi·온디바이스 Agent는 디버그 인증서로 /system/priv-app에 배포하면 안 된다.
• 플랫폼 인증서를 apksigner verify --print-certs로 비교한다.
• 파일 소유자, 권한 모드와 SELinux 컨텍스트를 확인한다.
• APK 교체 전 원본을 백업한다.
• 빌드 성공은 부팅과 Binder 연결 성공을 의미하지 않는다.

23.3 모니터 전송 보안

• Bearer 토큰 없는 제품 외부 전송은 금지한다.
• 테스트 콘솔 수신기는 제품 형상의 외부 공개 정책을 별도로 검토한다.
• endpoint는 HTTPS를 기본으로 한다.
• 기기 ID와 토큰을 문서, Git과 UI 기본값에 직접 넣지 않는다.
• 명령 조회와 이벤트 확인 응답에는 재전송 공격과 중복 실행 방어가 필요하다.

23.4 특권 우회 필드

다음 필드는 일반 외부 호출자에게 직접 노출하지 않는다.

• bypassCallerPolicy
• forceTaskManager의 무제한 사용
• requiredResources 임의 축소
• executorDryRun=false 원격 강제
• replace_all 긴급 선점

24. 실패 처리와 사용자 UX

24.1 구조화 실패에서 사용자 문장으로

reason_code=ROOM_NOT_FOUND
reason_params.target_location_name=거실
suggested_action=ASK_USER_TARGET

사용자 응답:
  “거실은 등록된 공간에서 찾지 못했어. 등록된 다른 공간으로 이동할까?”

내부 필드를 그대로 TTS로 읽지 않는다.

나쁜 예:

context 기준으로 current_room_id=0입니다.
CAPABILITY_UNAVAILABLE reason_params가 발생했습니다.

좋은 예:

현재 스테이션에 있어.
요청한 공간을 찾지 못했어. 공간 이름을 다시 알려줘.

24.2 실패 후 동작

25. 테스트 전략과 인수 기준

25.1 테스트 계층

25.2 최소 기능 검증

1. DIRECT 조회 성공과 실패
2. ASYNC Task 접수 후 최종 이벤트
3. QUEUED_WAIT 시간 초과
4. 같은 대기열의 실행 순서
5. 우선순위 순서
6. 대기열 포화
7. 엄격한 입력 검증 거절
8. 요청 출처별 긴급 우선순위 거절
9. 상태·자원 실행 허용 거절
10. 대기·실행 Task 취소
11. 취소 명령 실패
12. 보상 동작 실행
13. 순차 Workflow
14. 병렬 그룹 성공과 부분 실패
15. 조건에 따른 생략과 실패
16. 선행 단계 기준 지연
17. 과거 완료 증거 재사용 방어
18. PUI 취소 콜백
19. 예약 중복 제거, 저장, 복원, 실행, 취소와 미실행 처리
20. 이벤트 상관관계와 모니터 표시

25.3 도메인별 실기기 인수 시험

25.4 기존 검증 증거 해석

기존 문서에는 다음 수준의 증거가 있다.

• submitTask, submitWorkflow, 조회·대기열·관리 제어 API의 계측 확인 기록
• 실기기 TaskManager 계측 시험 통과 기록
• Cloud·On-device 요청 구조와 콜백 분배 확인 기록
• 예약 등록, 복원과 실행 시각 관련 실기기 검증 기록
• 이동을 제외한 혼합 Workflow 검증 기록

이 기록은 당시 기기와 APK 조합에 한정된 증거다. MR6 소스, 서명 또는 빌드 산출물이 바뀌면 출시 인수 시험을 다시 수행한다.

25.5 출시 판정 기준

위 구조도의 Gate 1~10은 API 정합에서 입력 검증, 실행기, 완료 증거, 취소·보상, 실패 사유, Binder 보안, 실기기 시험, 장시간 시험, 관측성과 원복까지 순서대로 확인한다.

26. 현재 구현의 한계와 목표 확장

26.1 현재 확인된 한계

26.2 목표 확장

1. 기능 설명자에서 정책, 스키마, 실행기와 완료 증거를 일관되게 생성한다.
2. 요청 진입점에서 queue 별칭을 표준 이름으로 완전히 정규화한다.
3. 엄격한 입력 검증을 단계적으로 기본 활성화한다.
4. 자원 점유 계약을 카메라, 화면, 스피커, 이동과 앱 세션으로 확장한다.
5. 이벤트 기반 Workflow 재개로 긴 대기를 대기열 작업자에서 분리한다.
6. 장애·재부팅 복구와 멱등성 원장을 강화한다.
7. 실행 조건을 타입 기반 연산자로 확장한다.
8. Task·이벤트 스키마의 버전 전환 절차를 정의한다.
9. AAR, DeviceAgent와 Cloud 기능 목록의 불일치를 CI에서 검사한다.
10. 도메인별 완료 증거 범위표를 출시 판정 기준으로 운영한다.

26.3 선택적 상위 계획 연동과 Core 안정성

동적 목표 해석, 상태 관찰과 기능 조합은 TaskManager 위의 선택 확장이다. Core는 다음을 유지해야 한다.

• 일반 단일 명령의 응답 시간을 늘리지 않는다.
• 정상 Task마다 Planner를 재호출하지 않는다.
• 상위 Planner 장애 시에도 현재 Task를 안전하게 종료한다.
• 기능이 없으면 차단 상태로 남기고 다른 기능으로 임의 치환하지 않는다.
• 재계획 횟수와 도구 사용 횟수에 상한을 둔다.

27. 구현 변경 절차

27.1 신규 메서드 추가

1. TaskMethods의 public/internal 상수를 추가한다.
2. TaskSupportedCommands의 도메인 그룹을 추가한다.
3. TaskBundleValidator 입력 스키마를 추가한다.
4. TaskPolicyRegistry의 정확한 실행 정책을 추가한다.
5. 기기 도메인 TaskExecutor를 구현하고 등록한다.
6. 별칭 변환기 적용 여부를 확인한다.
7. 완료 대상과 Completion Bridge를 연결한다.
8. 취소와 보상 동작을 정의한다.
9. 실패 사유 매핑과 컨텍스트 필드를 정의한다.
10. AAR API 사양과 llmwiki를 갱신한다.
11. 단위, 기기 계측과 실기기 시험을 수행한다.

27.2 기존 메서드 수정

• method 문자열은 호환성 영향이 크므로 alias를 먼저 추가한다.
• field type 변경은 JSON→Bundle bridge와 AAR builder를 함께 수정한다.
• timeout 변경은 workflow timeout 계산과 실기기 duration 근거를 확인한다.
• 완료 조건 변경은 콜백 제공자와 감시기를 함께 수정한다.
• queue 변경은 concurrency와 preempt 동작을 회귀 테스트한다.

27.3 문서 변경

28. 참조 규격과 문서 색인

이 사양서는 Core 규범을 소유한다. 상세 문서는 한 가지 책임만 갖고, 같은 계약을 다시 정의하지 않는다.

해석 충돌 시 제품 안전 정책과 승인된 요구사항, 이 사양서, 세부 계약 문서, 검증 기록 순서로 판단한다. 통합된 이전 문서는 기존 URL의 리다이렉트로만 유지하며, 활성 검색과 신규 링크에서는 사용하지 않는다.

제6부 · 상세 규범과 호환성 — 29~31장은 Core 불변 조건, 도메인별 Task 사양, 기존 시스템 전환과 적합성 판정을 고정한다.