SoC TaskManager Architecture
이 장은 현재 DeviceAgent TaskManager 소스 기준 구조를 설명한다.
업체 설명 시에는 이 장을 보기 전에 Before/After Change Model을 먼저 보고, 기존 DeviceAgent 직접 실행 구조에서 TaskManager layer가 어디에 추가되는지 확인한다.
설계 관점
TaskManager의 handleControlMethod(...)는 Cloud LLM 전용 entry가 아니다.
SoC 관점에서는 아래 source들이 모두 같은 API entry로 들어올 수 있어야 한다.
Cloud A2A / LLM
MQTT Command Server
App / Remote Control
On-device Local Voice
Internal Policy / Schedule
차이는 source별 후처리 policy다. 예를 들어 Cloud source는 requires_cloud_decision=true 실패에서 replan을 요청할 수 있지만, MQTT source는 같은 실패를 server ack/status/report로 올리는 것이 기본이다.
컴포넌트 구조
| 컴포넌트 | 파일 | 역할 |
|---|---|---|
| API entry | TaskManager.java |
control method dispatch, task/workflow lifecycle |
| Event callback | TaskEventListener.java |
listener callback interface |
| Reason contract | TaskReasonContract.java |
error code를 source-agnostic reason으로 정규화 |
| Planning context | DevicePlanningContextProvider.java |
battery/map/location/cleaning/movement/task_manager/capabilities snapshot |
| Ingress classifier | TaskIngressClassifier.java |
method/signal type을 task/control/event로 분류 |
| Bundle validation | TaskBundleValidator.java |
strict validation 시 method별 필수 key 검증 |
| Policy | TaskPolicyRegistry.java, TaskPolicy.java |
execution mode, queue, retry, timeout, state-aware 정책 |
| Executor registry | TaskExecutorRegistry.java |
taskMethod와 executor 연결 |
| Bootstrap | TaskExecutorBootstrap.java |
movement/cleaning/LLM/TTS/IoT/update skeleton executor 등록 |
API entry
TaskManager.handleControlMethod(...)는 아래 method를 처리한다.
submitTask
submitWorkflow
getTaskStatus
listTasks
getQueueStatus
updateTaskProgress
cancelTask
getTaskManagerStatus
getDevicePlanningContext
classifyTaskIngress
source가 무엇이든 기본 API는 동일하게 유지한다. source별 차이는 request bundle의 source, caller, cloud_workflow_id, external_command_id, origin 같은 trace field와 event 소비 정책으로 분리한다.
Source별 이벤트 정책
| source | 정상 event | 실패 event |
|---|---|---|
| Cloud A2A | On-device가 상태 표시/완료 처리 | requires_cloud_decision=true이면 Cloud replan 후보 |
| MQTT Server | server ack/status/report | server error report, retry policy, 필요 시 사용자 알림 |
| App / Remote | UI state 갱신 | 앱에 실패 상태와 reason code 표시 |
| Local Voice | 로컬 TTS/notification 처리 | 사용자에게 재시도/불가 안내 |
| Internal Schedule | 내부 로그/상태 갱신 | schedule retry/cancel/보호 정책 수행 |
실행 흐름
submitTask 흐름:
enabled check
-> taskMethod 확인
-> TaskBundleValidator.validateSubmitTask
-> TaskPolicyRegistry.resolve
-> caller policy check
-> state condition check
-> resource policy check
-> command 생성
-> DIRECT / QUEUED_WAIT / ASYNC 실행
submitWorkflow 흐름:
subTasks 확인
-> workflow policy 생성
-> workflow TaskRecord 생성
-> subTask 순차 실행
-> parallelGroup이면 child task 병렬 실행
-> WORKFLOW_STEP_STARTED / WORKFLOW_STEP_COMPLETED event
-> workflow result에 subTaskResults, subTaskStates 기록
Event 구조
notifyTaskEvent(...)는 다음을 수행한다.
record.writeSummaryTo(eventData)
eventData.method = "onTaskEvent"
eventData.eventName = eventName
listener.onTaskEvent(eventName, eventData)
AppCmd.INSTANCE.sendModuleCallback_main(eventData)
event payload에는 snake_case와 camelCase trace alias가 함께 들어간다.
cloud_workflow_id / cloudWorkflowId
cloud_step_id / cloudStepId
cloud_plan_id / cloudPlanId
cloud_output_key / cloudOutputKey
Cloud trace alias는 Cloud A2A source에서 특히 중요하지만, 프레임워크화 단계에서는 MQTT/App 명령을 위해 아래 alias도 추가 후보로 관리해야 한다.
source / origin / caller
external_command_id / externalCommandId
mqtt_message_id / mqttMessageId
app_request_id / appRequestId
schedule_id / scheduleId