← Docs hub

SoC TaskManager Source-Level Implementation Guide

이 장은 SoC/DeviceAgent 업체가 실제 코드 기준으로 구현을 따라 할 수 있도록 정리한 소스 레벨 가이드다. 개념 설명은 Before/After Change Model을 보고, 실제 구현 위치와 method 단위 작업은 이 문서를 기준으로 본다.

1. 핵심 결론

TaskManager는 기존 domain 동작을 대체하는 별도 앱이 아니다. 기존 MainApi.executeMethod(...) 앞단에 공통 실행 layer를 넣고, 실제 기기 동작은 기존 executeMethodInternal(...) 또는 domain executor로 위임하는 구조다.

현재 코드에서 이 구조는 아래처럼 연결되어 있다.

MainApi.executeMethod(...)
-> TaskManager.handleControlMethod(...)
-> handled이면 TaskManager API 처리 후 return
-> 아니면 TaskManager.executeLegacy(...)
-> executeMethodInternal(...)로 기존 domain 기능 실행

근거:

apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/main/api/MainApi.java
  import com.sk.airbot.deviceagent.task.TaskManager;
  executeMethod(...)에서 TaskManager.handleControlMethod(...)를 먼저 호출
  처리되지 않은 method는 executeLegacy(...)를 통해 executeMethodInternal(...)로 위임

2. 기존 진입점에 추가되는 Hook

기존 구조:

DeviceAgent
-> MainApi.executeMethod(method, indata, outdata)
-> executeMethodInternal(method, indata, outdata)
-> FrameworkCommandBridge 또는 기존 switch/handler

변경 구조:

DeviceAgent
-> MainApi.executeMethod(method, indata, outdata)
-> TaskManager.handleControlMethod(method, indata, outdata, factory)
   -> submitTask / submitWorkflow / getTaskStatus / cancelTask 등 TaskManager API면 여기서 처리
-> TaskManager.executeLegacy(...)
   -> 기존 executeMethodInternal(...) 호출 유지

업체 구현 포인트:

3. TaskManager API Entry

TaskManager.java는 아래 control method를 공통 API로 제공해야 한다.

submitTask
submitWorkflow
getTaskStatus
listTasks
getQueueStatus
updateTaskProgress
cancelTask
getTaskManagerStatus
getDevicePlanningContext
classifyTaskIngress

현재 코드 기준 책임:

3.1 Control Method별 입력/출력

3.2 공통 Bundle Key 규칙

3.3 최신 Task 등록 API 예시

단일 task는 method=submitTask, 실제 기능은 taskMethod에 넣는다. 기존 기능 method를 직접 호출하지 않고 TaskManager admission/policy/queue를 통과시키려면 forceTaskManager=true를 함께 둔다.

forceTaskManager = true
method = "submitTask"
taskMethod = "setMoveTo"
source = "IOT"
executionMode = "async"
targetRoom = "안방"
areaId = "5"
positionId = "5"
timeoutMs = "240000"

복합 task는 method=submitWorkflow와 subTasks를 사용한다. 아래 예시는 실기기 검증 기준 5명령 workflow다.

forceTaskManager = true
method = "submitWorkflow"
workflowName = "bedroom_livingroom_clean_return"
source = "IOT"
executionMode = "queued_wait"
subTasks = [
  { taskMethod = "setMoveTo", label = "안방 이동", targetRoom = "안방", areaId = "5", positionId = "5", timeoutMs = "240000" },
  { taskMethod = "startBasicAirClear", label = "안방 청정", action = "1", mode = "0", completionTarget = "cleaning.stopped", cleanMinTimeMs = "60000", cleanMaxTimeMs = "90000", timeoutMs = "180000" },
  { taskMethod = "setMoveTo", label = "거실 이동", targetRoom = "거실", areaId = "6", positionId = "6", timeoutMs = "240000" },
  { taskMethod = "startBasicAirClear", label = "거실 청정", action = "1", mode = "0", completionTarget = "cleaning.stopped", cleanMinTimeMs = "60000", cleanMaxTimeMs = "90000", timeoutMs = "180000" },
  { taskMethod = "returnToStation", label = "스테이션 복귀", timeoutMs = "240000" }
]

완료 기준:

4. submitTask 처리 상세

submitTask는 단일 실행 요청의 공통 admission gate다.

흐름:

enabled check
-> taskMethod 필수 확인
-> TaskBundleValidator.validateSubmitTask(...)
-> copyForTask(...)
-> TaskPolicyRegistry.resolve(...)
-> TaskSource.from(source)
-> caller policy check
-> state condition check
-> resource policy check
-> createTaskCommand(...)
-> DIRECT / QUEUED_WAIT / ASYNC 실행

업체 구현 의미:

5. submitWorkflow 처리 상세

submitWorkflow는 복합명령을 위한 핵심이다. 단순히 여러 method를 한 번에 보내는 것이 아니라, workflow 자체를 task로 만들고 subTask 상태를 추적한다.

흐름:

subTasks 필수 확인
-> workflow policy 생성
-> workflow TaskRecord 생성
-> 각 subTask 순차 실행
-> parallelGroup이면 병렬 그룹 실행
-> currentStepIndex / currentStepMethod 갱신
-> WORKFLOW_STEP_STARTED event
-> subCommand.run()
-> WORKFLOW_STEP_COMPLETED event
-> subTaskResults / subTaskStates 결과 기록

예시:

submitWorkflow
  workflowName = "bedroom_livingroom_clean_return"
  subTasks[0] = { taskMethod: "setMoveTo", targetRoom: "안방", areaId: "5" }
  subTasks[1] = { taskMethod: "startBasicAirClear", action: "1", mode: "0", completionTarget: "cleaning.stopped" }
  subTasks[2] = { taskMethod: "setMoveTo", targetRoom: "거실", areaId: "6" }
  subTasks[3] = { taskMethod: "startBasicAirClear", action: "1", mode: "0", completionTarget: "cleaning.stopped" }
  subTasks[4] = { taskMethod: "returnToStation" }

업체 구현 포인트:

5.1 Workflow에서 실행 시점 조건 판단

복합명령에서 중요한 점은 “workflow 등록 시점”과 “subTask 실행 시점”의 기기 상태가 다를 수 있다는 것이다.

예:

1. 거실로 이동
2. 거실에서 청정 시작
3. 안방으로 이동

이 경우 2번 청정 조건은 workflow 등록 시점이 아니라 1번 이동 완료 후 확인해야 한다. 따라서 업체 구현은 아래 원칙을 따른다.

5.2 Workflow Event 순서

정상 순차 workflow:

ACCEPTED
RUNNING
WORKFLOW_STEP_STARTED(index=0)
WORKFLOW_STEP_COMPLETED(index=0)
WORKFLOW_STEP_STARTED(index=1)
WORKFLOW_STEP_COMPLETED(index=1)
WORKFLOW_STEP_STARTED(index=2)
WORKFLOW_STEP_COMPLETED(index=2)
COMPLETED or WORKFLOW_COMPLETED

실패 workflow:

ACCEPTED
RUNNING
WORKFLOW_STEP_STARTED(index=0)
WORKFLOW_STEP_COMPLETED(index=0)
WORKFLOW_STEP_STARTED(index=1)
FAILED(reason_code=PATH_BLOCKED or STATE_CONDITION_FAILED)

6. Policy Registry

TaskPolicyRegistry.java는 method별 실행 정책을 정의한다.

현재 주요 queue:

emergency
movement
cleaning
state
update
sound
settings
ai
default

대표 정책:

업체 구현 포인트:

• get/is/info/version/dump 성격은 기본적으로 DIRECT 후보로 둔다.
• 이동/청정/AI/TTS처럼 시간이 걸리는 제어는 ASYNC 또는 QUEUED_WAIT로 둔다.
• stop/emergency/error/reset 계열은 emergency 성격으로 우선순위를 높인다.
• cancel/compensation method는 queue별 default를 제공한다.

7. Bundle Validation

TaskBundleValidator.java는 strict validation이 켜졌을 때 method별 필수 입력을 검사한다.

현재 schema 예시:

주의:

• 이 validation은 domain safety logic을 대체하지 않는다.
• 기능 내부 조건 판단은 기존 handler/domain manager가 계속 수행한다.
• validation의 목적은 명백한 slot 누락을 execution 전에 차단하는 것이다.

8. Executor Binding

TaskExecutorBootstrap.java는 task method와 executor를 연결한다.

현재 skeleton binding:

업체가 해야 할 일:

1. skeleton executor를 실제 domain manager 호출로 연결한다.
2. dry-run executor와 real executor를 구분한다.
3. long-running 동작은 progress update 또는 event callback을 보장한다.
4. cancel method가 있는 domain은 stop/cancel path까지 연결한다.
5. domain 실패를 TaskReasonContract가 이해 가능한 error code로 넘긴다.

8.1 Domain Adapter 작성 패턴

TaskManager executor는 가능하면 얇은 adapter로 유지한다.

TaskExecutor
-> input Bundle normalize
-> 기존 domain handler 호출
-> domain 결과/error를 task output 또는 exception/errorCode로 변환

청정 예시:

taskMethod = setAirCleanerOperation
-> CleaningAmpTaskExecutor
-> CleanOperationCommandHandler.handleSetAirCleanerOperation(...)
-> CleaningTransaction / PolicyGate / Executor
-> success or domain error

이동 예시:

taskMethod = setMoveTo
-> MovementTaskExecutor
-> MovingController / RobotMovementController / map location lookup
-> success, PATH_BLOCKED, ROOM_NOT_FOUND 등

금지할 구현:

• TaskManager executor 안에 청정/이동 business rule을 중복 구현
• source가 cloud인지 mqtt인지에 따라 domain 동작 자체를 다르게 구현
• event를 보내지 않고 domain method만 호출
• 실패를 exception message나 toast string으로만 남김

9. 기존 Domain Handler와의 관계

예를 들어 setAirCleanerOperation은 기존 CleanOperationCommandHandler에서 이미 많은 조건 판단을 수행한다.

근거:

apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/framework/command/CleanOperationCommandHandler.java
  handleSetAirCleanerOperation(...)
  AppCmd.INSTANCE.sendModuleCommand_iot(indata)
  Settings lock mode 확인
  InputNormalizer.normalize(...)
  PolicyGate.shouldSkipCurrentStep(...)
  PolicyGate.applyBeforeExecution(...)
  Executor.execute(...)

따라서 TaskManager가 해야 하는 일과 domain handler가 해야 하는 일을 분리해야 한다.

9.1 기존 제품 정책 계승 경로

실행기는 기존 기능 메서드만 재사용하는 것이 아니라 그 메서드 앞뒤에 연결된 제품 정책까지 계승해야 한다. 기준 구조와 정책 행렬은 기준 사양 6.7에 둔다.

TaskManager 공통 Admission
-> FrameworkCommandBridge 또는 승인된 Domain Adapter
-> PolicyEngine / StateManager / CmdPolicyManager
-> 기존 Domain Manager와 Controller
-> HAL·MCU·AMR
-> Domain callback과 CompletionStateStore

이동의 경우 MovementTaskExecutor가 이동 좌표만 처리하고, 실제 허용 판정은 MovementCommandHandler -> PolicyEngine -> CmdPolicyManager 경로가 맡는다. 이동이 시작된 뒤에는 MovingLocationManager가 MOVING 틸트 조건과 LCD 깨움을 적용하고, TiltingManager가 LLM·관찰·도킹 조건을 합성해 최종 자세를 결정한다.

따라서 구현 검토에서는 다음을 확인한다.

• Task 경로가 기존 도메인 정책 진입점을 건너뛰지 않는가
• 기존 경로의 거절을 Task 성공으로 잘못 변환하지 않는가
• 틸트·화면·팬처럼 내부 부수 정책을 Workflow 작성자에게 전가하지 않는가
• 도메인 자동 전환과 완료 증거가 Task 이벤트에 남는가
• 기존 호출과 관리 호출이 같은 상태에서 같은 허용 결과를 내는가

10. Reason Contract

TaskReasonContract.java는 내부 error를 상위가 이해 가능한 reason으로 정규화한다.

대표 mapping:

후처리 필드:

중요:

• LOW_BATTERY, DEVICE_BUSY, RESOURCE_LIMIT은 기본적으로 Cloud LLM 재판단 없이 device/server policy로 처리 가능하다.
• PATH_BLOCKED, ROOM_NOT_FOUND, STATE_CONDITION_FAILED, SENSOR_ERROR 등은 사용자 질문 또는 replan 후보가 된다.
• MQTT/App source에서는 requires_cloud_decision을 그대로 Cloud 호출로 해석하지 말고, server report/user notification 정책과 분리해서 사용한다.

11. Planning Context

DevicePlanningContextProvider.java는 실행 전 상위 planner/server가 참고할 수 있는 snapshot을 만든다.

현재 snapshot field:

schema_version = device_context.v1
snapshot_ts
updated_at_ms
main_state
battery
map
location
cleaning
movement
task_manager
capabilities

세부 내용:

업체 구현 포인트:

• rooms는 실제 map/room 정보를 채워야 한다.
• current_room_id/name은 가능한 경우 localization 결과로 채운다.
• blocked는 이동 controller가 제공하는 장애물/path 상태와 연결해야 한다.
• capability는 제품/펌웨어/설정에 따라 false가 될 수 있어야 한다.

12. Ingress Classification

TaskIngressClassifier.java는 method를 task/control/progress/result/sensor/event/trigger로 분류한다.

분류 결과는 아래 용도로 쓴다.

업체 구현 포인트:

• MQTT 서버에서 내려온 method도 이 classifier를 통과시키면 task로 넣을지, progress/result로 볼지 일관되게 판단할 수 있다.
• 예약/알람은 곧바로 실행하기보다 trigger로 분류한 뒤 policy를 거쳐 task 생성하는 편이 안전하다.

12.1 Source별 정책 분기

13. Event Payload Contract

TaskManager event는 notifyTaskEvent(...)에서 생성된다.

공통 흐름:

record.writeSummaryTo(eventData)
eventData.method = "onTaskEvent"
eventData.eventName = eventName
listener.onTaskEvent(eventName, eventData)
AppCmd.INSTANCE.sendModuleCallback_main(eventData)

event에 반드시 남겨야 할 계열:

14. 업체 구현 순서

권장 구현 순서:

1. MainApi.executeMethod(...) 앞단에 TaskManager hook을 붙인다.
2. submitTask, submitWorkflow, query/cancel/status API를 구현한다.
3. TaskPolicyRegistry에 method별 queue/mode/timeout/cancel 정책을 채운다.
4. TaskBundleValidator에 필수 slot schema를 채운다.
5. TaskExecutorRegistry에 기존 domain handler adapter를 연결한다.
6. TaskReasonContract에 domain error mapping을 추가한다.
7. DevicePlanningContextProvider에 실제 map/location/movement/cleaning/battery 상태를 채운다.
8. onTaskEvent payload를 Cloud/MQTT/App/예약 source별 trace와 함께 검증한다.
9. unit/integration/instrumented/logcat evidence를 제출한다.

15. 구현 완료 기준

업체 구현은 아래가 모두 확인되어야 한다.

15.1 2026-07-23 A1 실기기 확인 결과

현재 A1 실기기에서 원복된 기존 배포 APK는 서비스 안정성은 확인됐지만, TaskManager API surface는 아직 열려 있지 않다.

확인 조건:

device = 192.168.123.116:5555
DeviceAgent = com.sk.airbot.deviceagent / versionName 0.249
MaumAi = com.skmagic.ondeviceai.agent / versionName 1.19.28
MaumAi ForegroundService = isForeground=true

확인 결과:

dumpsys activity service com.sk.airbot.deviceagent/.DeviceAgent method=getDevicePlanningContext
-> dump outdata : Bundle[{}]

dumpsys activity service com.sk.airbot.deviceagent/.DeviceAgent method=getTaskManagerStatus
-> dump outdata : Bundle[{}]

해석:

• 기존 배포 APK는 부팅과 MaumAi 서비스 기동에는 문제가 없지만 getDevicePlanningContext, getTaskManagerStatus의 실제 응답이 비어 있다.
• 따라서 기존 APK만으로는 Cloud A2A -> On-device Bridge -> DeviceAgent TaskManager submitWorkflow E2E를 완료할 수 없다.
• 실제품 검증은 TaskManager hook/API가 포함된 DeviceAgent 소스를 실제 단말 버전과 맞춘 뒤 platform-signed privileged APK로만 진행해야 한다.
• dumpsys는 문자열 Bundle로 들어가는 값이 많아 forceTaskManager=true, executorDryRun=true 같은 boolean 계약 검증에 부적합하다. 실제 workflow 제출 검증은 On-device Bridge/AAR/SDK 같은 typed Bundle caller로 수행해야 한다.
• /system/priv-app 교체 전에는 skmagic_ondeviceai_agent/scripts/real_device_apk_preflight.sh로 candidate APK와 backup APK의 signing SHA-256을 비교해야 한다. Android debug certificate가 감지되면 배포를 중단한다.
• Cloud repo의 device_e2e_runner는 getTaskManagerStatus가 실제 payload를 반환하지 않으면 task_manager_status_unavailable에서 중단해야 한다. 기존 0.249 APK처럼 dumpsys returncode만 성공이고 outdata가 비어 있는 상태에서는 submitTask를 실행하지 않는다.
• device_task_dry_run --run submit-cleaning은 --allow-submit 없이는 실행되지 않아야 한다. dry-run 출력은 명령 확인용이고, 실기기 실행 승인은 별도 단계로 둔다.

Cloud/On-device 계약 보강:

이 필드는 실패를 숨기지 않기 위한 진단 계약이다. Cloud가 room name만 가진 multi-step device workflow를 만들었는데 DeviceAgent planning context가 없거나 target room을 찾지 못하면, 조용히 device_workflow_requests를 생략하지 않고 device_workflow_blocked를 함께 내려야 한다.

TaskManager callback ingress:

Cloud Lambda는 두 envelope를 모두 받아야 한다. 즉 {"request_kind":"task_event","task_event":{...}} 형태뿐 아니라 TaskMonitorReporter가 직접 보내는 {"type":"task_event", ...} 형태도 request_kind=task_event로 정규화한다. 이때 status=RUNNING과 eventName=WORKFLOW_STEP_COMPLETED가 함께 오면 eventName은 workflow delta의 이벤트 종류로 유지하고, status는 현재 task 상태 계산에만 사용한다. 이렇게 해야 monitor timeline의 step 완료 신호와 Cloud workflow state가 어긋나지 않는다.

16. 최소 테스트 시나리오