← Docs hub

TaskManager 이해 가이드

직접 기능 호출에서 관리 가능한 실행 Framework로

이 문서는 TaskManager를 처음 접하는 독자가 왜 필요한지, 무엇이 달라졌는지, 실제로 어떻게 동작하는지를 순서대로 이해하도록 구성한 대표 입문서다. 설명은 현재 기준 소스인 a1-packages-mr6/apps/DeviceAgent에 맞췄다.

TaskManager는 새 이동·청정 기능이 아니라, 이미 존재하는 기기 기능을 task와 workflow로 접수해 순서·대기·취소·실패·실제 완료를 공통 관리하는 DeviceAgent 내부 실행 제어 계층이다.

이 문서를 읽는 순서

처음 읽을 때는 1~5장으로 전체 구조를 잡고, 구현이나 검증이 필요할 때 뒤쪽 세부 장으로 내려가면 된다.

TaskManager 개요

TaskManager는 DeviceAgent가 가진 이동, 청정, 설정, TTS, Security, Schedule 같은 기능을 새로 구현하는 모듈이 아니다. 여러 호출자가 요청한 기기 행동을 공통 작업 형식으로 접수하고, 실행 전 검사부터 순서·대기·취소·완료·실패 기록까지 관리하는 runtime이다.

어떤 문제를 해결하는가

TaskManager가 관리하는 실행 단위

Core 구성요소

외부 시스템이 넣는 것과 돌려받는 것

대표적으로 관리할 수 있는 작업

TaskManager의 핵심 산출물은 기능 실행 자체가 아니라 실행 상태를 신뢰할 수 있게 만드는 공통 기록과 event다. 어떤 요청이 언제 접수됐고, 어느 queue에서 어떤 step을 실행했으며, 무엇을 근거로 완료 또는 실패했는지를 한 흐름으로 남긴다.

1. 먼저 구분해야 하는 세 영역

TaskManager는 자연어를 해석하는 planner도 아니고 모터를 직접 구동하는 HAL도 아니다. 결정된 기기 행동을 신뢰성 있게 수행하고 결과 증거를 남기는 실행 control plane이다.

2. 5분 요약: 무엇이 바뀌었는가

AS-IS: 기능 API는 있었지만 실행 lifecycle은 호출자가 관리

기존 DeviceAgent는 이미 다양한 기능을 제공했다.

PUI / IoT / System App / 내부 모듈
  -> IDeviceControl.sendModuleCommand(Bundle)
  -> DeviceAgent
  -> MainApi.executeMethod(...)
  -> 기능별 manager / controller
  -> AMR · MCU · Schedule · WSS · LLM

단일 버튼 동작에는 충분했지만 여러 단계가 이어지면 호출자가 다음 책임까지 떠안았다.

• 명령 접수와 실제 물리 동작 완료의 구분
• 이동 완료 후 청정을 시작하는 순서 제어
• 중간 취소 시 현재 동작과 다음 대기 동작 정리
• timeout, 저전력, 경로 막힘 등 실패 해석
• PUI, IoT, App 등 source별 callback과 상태 표시

TO-BE: 기존 기능 앞뒤에 공통 실행 계약을 추가

PUI / IoT / System App / 예약 / 상위 Planner
  -> submitTask / submitWorkflow
  -> admission · policy · queue · workflow
  -> executor adapter
  -> 기존 DeviceAgent 기능
  -> domain callback / state evidence
  -> COMPLETED / FAILED / CANCELLED + reason

개발 관점: 애드훅 연결에서 Task 단위 개발로

AS-IS에서 커지기 쉬운 애드훅 구조

호출자가 기능 API, callback, timeout, 취소와 후속 동작을 모두 연결하면 같은 정책이 여러 서비스에 반복된다. 기능 하나의 변경이 호출자별 분기와 예외 처리까지 퍼지고, 조합 기능은 별도 callback 체인으로 늘어난다.

TO-BE의 표준 기능 온보딩 절차

새 기능은 다음 여섯 지점만 명시적으로 연결한다.

기능 코드는 유지하고 실행 관리만 공통화

Executor는 기존 이동·청정·화면 API를 다시 구현하지 않고 위임한다. 따라서 기능 알고리즘은 도메인에 남고, 수명주기와 실행 정책만 공통 Framework가 소유한다.

복합 기능은 callback 체인이 아니라 workflow 데이터로 표현

setMoveTo
-> startBasicAirClear
-> returnToStation

각 단계는 depends_on, completion target과 failure policy를 가진다. 이미 검증된 Task 조각을 다시 조합하므로 새 시나리오를 만들 때 기능 코드를 복제하지 않는다.

개발 변경 범위가 국소화되는 방식

• 기능 입력 변경은 validator와 adapter에서 처리한다.
• 실행 정책 변경은 policy catalog에서 검토한다.
• 물리 완료 변경은 completion bridge에서 처리한다.
• 조합 순서 변경은 Workflow 데이터에서 처리한다.
• 사용자 표현과 제품 목표는 호출자 또는 상위 기획 계층에 남긴다.

코드 리뷰에서 확인할 공통 기준

method, 입력, 실행 허용, queue, timeout, 완료, 취소, reason과 실기기 evidence가 한 기능 카드에서 추적돼야 한다. 상세 클래스와 구현 절차는 Source-Level Implementation Guide를 기준으로 한다.

Framework 사용 형태: TaskManagerClient AAR

두 계층을 분리하는 이유

DeviceAgent 내부 Core는 실행 lifecycle을 소유한다. product-level AAR은 시스템 앱이 문자열과 Bundle을 직접 조립하지 않도록 typed request와 callback을 제공한다.

앱 개발자에게 노출되는 API

• TaskSubmitRequest.builder()
• TaskWorkflowRequest.builder()
• TaskManagerClient.submitTask()와 submitWorkflow()
• 상태 조회와 취소 API
• TaskManagerClientCallback.onTaskEvent()

System App 사용 예

TaskWorkflowRequest request = TaskWorkflowRequest.builder("room_clean_return")
        .addTask(moveTask)
        .addTask(cleanTask)
        .addTask(returnTask)
        .build();
client.submitWorkflow(request, callback);

Framework API로서 지켜야 할 계약

AAR과 Core는 method, 필드 기본값, alias, event와 reason 의미가 같아야 한다. AAR은 Core runtime을 포함하거나 Binder 권한을 우회하지 않는다.

소스와 배포 산출물

배포 산출물은 taskmanagerclient-release.aar이며, 공개 API와 builder의 전체 사양은 TaskManagerClient AAR API Specification에만 유지한다.

3. 왜 method return만으로는 부족한가

기기 제어에서는 요청 전달 성공과 사용자가 기대한 결과 달성이 다르다. returnToStation 호출이 예외 없이 반환돼도 경로가 막히거나, 도킹하지 못하거나, 사용자가 이동을 취소할 수 있다.

command accepted != movement completed

returnToStation command 실행
  -> movement 상태 관찰
  -> station charging/docking evidence
  -> Task COMPLETED

그래서 TaskManager의 완료는 단순 return 값이 아니라 domain이 제공하는 증거로 닫힌다. 이것이 도입 전과 후를 가르는 핵심이다.

4. 예시로 보는 구축 전과 구축 후

예시 A. “스테이션으로 복귀해”

AS-IS

PUI 또는 App
  -> returnToStation 직접 호출
  -> 호출 성공 반환
  -> 실제 도킹 실패는 이동 로그나 별도 상태에서 확인

TO-BE

submitTask(taskMethod=returnToStation)
  -> movement queue
  -> 기존 returnToStation 실행
  -> movement.stationCharging evidence 대기
  -> COMPLETED 또는 FAILED(reason_code)

예시 B. “안방으로 가서 청정하고 복귀해”

AS-IS

setMoveTo 호출
  -> 도착 callback을 caller가 해석
  -> setAirCleanerOperation 호출
  -> 청정 완료 또는 정지 조건 관리
  -> returnToStation 호출

caller process가 종료되거나 중간 단계가 실패하면 어디까지 실행됐고 무엇을 취소해야 하는지 caller별 보상 로직이 필요하다.

TO-BE

submitWorkflow
  1. setMoveTo
     완료 증거: movement.arrived
  2. setAirCleanerOperation
     선행 조건: step 1 completed
     완료 증거: cleaning.stopped
  3. returnToStation
     선행 조건: step 2 completed
     완료 증거: movement.stationCharging

첫 번째 command가 반환됐다는 이유만으로 청정을 시작하지 않는다. movement.arrived가 관측돼 첫 단계가 완료된 뒤 두 번째 단계로 진행한다.

예시 C. 이동 중 PUI에서 취소

취소는 record만 CANCELLED로 바꾸는 것이 아니다. policy에 등록된 cancel 또는 compensation method를 domain에 전달하고 실행 중 child와 대기 step을 정리한다.

예시 D. “30초 후 나이트모드로 바꿔”

제품의 반복 Schedule과 TaskManager deferred task는 목적이 다르다. 반복 생활 일정은 기존 Schedule domain이 소유하고, “N분 뒤 한 번 실행” 같은 단기 지연 작업은 TaskManager scheduling이 관리한다.

예시 E. “30분 뒤 안방으로 가서 청정해줘”

이 요청은 단일 설정 변경이 아니라 실행 시각과 두 단계 행동을 함께 가진 일회성 workflow 예약이다.

scheduleWorkflow
  trigger: relativeDelayMs=1800000
  subTasks:
    1. setMoveTo(안방) -> movement.arrived
    2. startBasicAirClear -> cleaning terminal evidence

등록 시점에는 이동이나 청정을 시작하지 않는다. SCHEDULED record와 절대 triggerAtMs를 저장하고, 30분 뒤 runDueScheduledTasks가 현재 위치·배터리·busy 상태와 공간 정보를 다시 확인한다. 실행 가능하면 기존 submitWorkflow로 재진입하고, 불가능하면 동작하지 않은 채 구조화된 reason을 남긴다.

따라서 “이 구조로 소화할 수 있다”와 “모든 실기기 자동 실행이 release 검증까지 끝났다”는 구분해야 한다. 반복되는 매일·매주 청정은 기존 제품 Schedule에 등록하고, 이 예시처럼 한 번만 지연 실행하는 workflow는 TaskManager scheduling이 담당한다.

5. Framework 전체 구조

그림의 왼쪽에서 오른쪽으로는 요청 접수와 실행 경로, 오른쪽에서 아래를 거쳐 TaskManager로 돌아오는 흐름은 실제 완료 evidence와 결과 보고 경로다. 기존 DeviceAgent domain은 기능을 계속 소유하고, TaskManager는 그 앞뒤에서 실행 lifecycle을 관리한다.

6. 단일 task가 처리되는 순서

현재 submitTask의 핵심 흐름은 다음과 같다.

1. TaskManager 활성 여부 확인
2. alias를 canonical taskMethod로 정규화
3. method별 payload schema 검증
4. source/caller policy 확인
5. 기기 상태와 domain 자원 충돌 확인
6. CPU·RAM·thermal admission 확인
7. preempt policy 적용
8. mode·queue·priority·timeout 결정
9. registry에서 executor 생성
10. TaskRecord 생성
11. DIRECT / QUEUED_WAIT / ASYNC 실행
12. 필요한 completion evidence 대기
13. terminal event와 reason 발행

대표 요청은 다음 의미를 갖는다.

method=submitTask
taskMethod=returnToStation
source=PUI
requestId=pui-return-001
traceId=pui-return-001
priority=HIGH
completionTarget=movement.stationCharging
timeoutMs=240000

Cloud, IoT, PUI, System App은 같은 의미의 field와 lifecycle을 사용하고 source와 correlation만 보존한다.

7. Queue, mode, priority가 해결하는 문제

실행 mode

queue

동일 queue는 single worker와 priority queue로 순서를 관리한다. 서로 다른 queue는 policy가 허용할 때 병렬로 실행할 수 있다.

movement queue: setMoveTo -> returnToStation
cleaning queue: start -> stop
ai queue: TTS -> stopTTS

같은 queue: 높은 priority 우선, 같은 priority는 FIFO
다른 queue: 자원 충돌 policy를 통과하면 병렬 가능

공개 domain queue는 movement, cleaning, state, update, sound, settings, ai, routine, schedule, interaction, security, mapping, emergency, default로 구성된다. workflow parent는 내부 workflow queue를 사용한다.

priority는 source 이름만으로 결정하면 안 된다. 동일한 음성 입력도 단순 청정과 긴급 정지는 다른 실행 정책을 가져야 한다.

8. Workflow가 관리하는 것

workflow는 자연어 문장이 아니라 구조화된 subTasks의 실행 관계다.

중요한 현재 경계

• parent workflow는 내부 workflow queue의 single worker에서 관리된다.
• 순차 step은 parent workflow worker 안에서 실행된다.
• parallel child는 각 domain queue에 독립 task로 등록된다.
• 모든 workflow step이 항상 domain queue를 통해 완전 직렬화된다고 과장하면 안 된다.
• 짧은 after_step 지연은 workflow worker가 대기할 수 있지만 긴 지연은 durable scheduler로 넘기는 것이 맞다.

9. 완료 evidence와 실패 reason

기존 domain callback
  -> TaskCompletionStateStore.mark(target, key, status)
  -> TaskCompletionWatcher.waitFor(...)
  -> executor 완료
  -> TaskRecord COMPLETED
  -> onTaskEvent(COMPLETED)

오래된 callback이 새 task를 완료시키지 않도록 task 시작 시각 이후의 evidence만 인정하고, 필요하면 area ID 또는 completion key로 범위를 좁힌다.

실패는 사용자 문장 한 줄이 아니라 상위 시스템이 판단 가능한 구조로 남긴다.

reason_code
reason_params
recoverability
suggested_action
requires_cloud_decision

예를 들어 LOW_BATTERY는 기기가 도킹 후 재개할 수 있는 실패일 수 있고, UNKNOWN_ROOM은 사용자에게 공간명을 다시 확인해야 하는 실패다. TaskManager는 사실과 복구 성격을 제공하고 PUI·IoT·상위 planner가 자기 UX 정책에 맞게 안내한다.

10. TaskManager가 하는 일과 하지 않는 일

재계획이 필요한 실패에서는 requires_cloud_decision 같은 신호를 제공할 수 있지만 목표 변경과 사용자 재질문은 상위 판단 계층의 책임이다.

11. AOSP 안에서의 위치

DeviceAgent는 android.uid.system을 사용하는 privileged product app이며 TaskManager는 그 내부 package다.

Application / System App ingress
  -> Binder/AIDL product IPC
  -> DeviceAgent privileged app
     -> MainApi
     -> TaskManager
     -> existing domain managers
  -> vendor service / HAL / MCU / AMR

TaskManager는 frameworks/base의 Android framework service가 아니며 Android public SDK도 아니다. 다만 A1 제품 관점에서는 여러 system app과 domain 기능을 공통 계약으로 연결하는 Product Execution Framework 역할을 한다.

12. 현재 소스에서 확인할 위치

기준 checkout:

/home/silogood/work/1.A1_SoC_new/SoC/a1-packages-mr6

13. 구현 완료와 제품 검증을 구분하는 법

“APK 빌드 성공”은 TaskManager 제품 검증 완료가 아니다. 실기기 acceptance에는 서명 일치, system app 배치, task event, domain callback, 실제 물리 완료, cancel/timeout 증거가 함께 필요하다.

14. TaskManager 도입이 가져오는 결과

가장 큰 변화는 기능 수가 늘어난 것이 아니다. 기기 행동이 추적·취소·복구 가능한 관리 대상이 됐다는 것이다.

15. 다음에 읽을 문서