← Docs hub

TaskManager 사양 2 · 요청, API와 실행 정책

요청 유입부터 공개 API, 기본값, 검증, 호출자·기기·자원 정책까지 실행 전 경계를 정의한다.

이 장의 결론: 요청을 접수한 뒤 입력, 호출자, 기기 상태와 자원을 순서대로 검증하고 허용된 작업만 실행 대기열로 보낸다.

4. 요청 유입과 유형 분류

4.1 지원 요청 출처

4.2 신호 유형

TaskIngressClassifier는 들어오는 모든 메서드를 Task로 만들지 않는다.

핵심 원칙은 명령과 관찰을 분리하는 것이다. 센서 콜백을 다시 구동 Task로 감싸면 순환 호출과 중복 실행이 생길 수 있다.

4.3 MainApi의 세 경로

1. method가 TaskManager 제어 메서드이면 handleControlMethod()가 직접 처리한다.
2. forceTaskManager=true이거나 Task 관리 대상 메서드이면 관리 실행 경로를 사용한다.
3. TaskManager 대상이 아니거나 호환성이 필요한 호출은 기존 경로를 유지한다.

이 구조는 기존 기능을 한 번에 전부 교체하지 않고 점진적으로 Task 계약에 편입하기 위한 호환 경계다.

5. 공개 제어 API

현재 TaskManager.handleControlMethod()와 TaskManagerClient가 공유하는 제어 메서드는 17개다.

위 17개 메서드는 현재 TaskManager의 제어 분기와 TaskManagerClient 공개 상수에 모두 존재한다. 출시할 때마다 양쪽 목록과 실제 처리 분기를 교차 점검해야 한다.

5.1 submitTask 최소 요청

{
  "method": "submitTask",
  "forceTaskManager": true,
  "taskMethod": "setMoveTo",
  "source": "APP",
  "requestId": "move-bedroom-001",
  "traceId": "trace-001",
  "positionId": "5",
  "positionName": "안방",
  "completionTarget": "movement.arrived",
  "timeoutMs": "120000"
}

5.2 submitWorkflow 최소 요청

{
  "method": "submitWorkflow",
  "forceTaskManager": true,
  "workflowName": "room_clean_return",
  "source": "APP",
  "requestId": "wf-room-clean-001",
  "traceId": "wf-room-clean-001",
  "subTasks": [
    {
      "stepId": "move-bedroom",
      "taskMethod": "setMoveTo",
      "positionId": "5",
      "positionName": "안방",
      "completionTarget": "movement.arrived"
    },
    {
      "stepId": "clean-bedroom",
      "taskMethod": "setAirCleanerOperation",
      "action": "1",
      "mode": "0",
      "completionTarget": "cleaning.stopped"
    },
    {
      "stepId": "return-station",
      "taskMethod": "returnToStation",
      "completionTarget": "movement.stationCharging"
    }
  ]
}

5.3 공통 요청 필드

queue와 queueKey는 계층별 명칭 차이가 남아 있다. AAR builder는 queue를 쓰지만 TaskPolicyRegistry.resolve()는 직접 변경값으로 queueKey를 읽는다. 외부 계약은 queue를 표준 이름으로 유지하고 DeviceAgent 경계에서 별칭을 정규화해야 한다.

5.4 생략 필드의 기본값과 적용 순서

요약: TaskManager의 기본값은 요청 생성기 한 곳에서 일괄 입력되지 않는다. 호출 경로가 자동으로 넣는 값, 메서드 정책 목록이 채우는 값, Workflow·예약 런타임이 계산하는 값과 도메인 실행기가 보완하는 값이 순서대로 결합된다. 따라서 “필드를 생략해도 된다”는 말은 어느 계층이 어떤 값으로 보완하는지 계약에 고정돼 있다는 뜻이어야 한다.

5.4.1 기본값 결정 우선순위

실행값은 다음 순서로 결정된다.

1. 호출자가 명시한 값: 허용된 변경 필드는 요청값을 우선 사용한다.
2. 호출 경로의 정규화·자동 삽입: AAR, Cloud 어댑터, Task Monitor가 제어 메서드와 일부 메타데이터를 넣는다.
3. 메서드별 명시 정책: TaskPolicyRegistry의 exact policy가 실행 방식, 대기열, 우선순위, 시간 제한, 재시도, 취소와 보상 동작을 제공한다.
4. 등록되지 않은 메서드의 추정 정책: 메서드 이름으로 임시 fallback policy를 만든다. 이는 호환 안전망이며 출시 기능의 정식 사양으로 사용하면 안 된다.
5. Workflow·예약 런타임 기본값: Workflow 이름, 병렬 그룹 정책, 단계 지연, 예약 유형과 실행 허용 옵션을 보완한다.
6. 도메인 실행기 기본값: 이동, 청정, Security 등 실제 기능이 안전한 호출 형식이나 완료 조건을 추가로 정규화한다.
7. 시스템 속성 기본값: 엄격 검증, 자원 정책, 영속성, 대기열 크기 같은 운영값을 최종 적용한다.

TaskRecord의 taskId는 호출자가 보내지 않아도 <taskMethod>-<sequence> 형식으로 생성된다. 예약 ID도 scheduled-<sequence> 형식으로 생성된다. 반면 requestId와 traceId는 자동 생성되지 않는다. 내부 Task ID가 생긴다는 사실을 외부 멱등성과 분산 추적이 확보된 것으로 해석하면 안 된다.

5.4.2 호출 경로별 자동 입력

forceTaskManager를 raw 요청에서 생략하면 요청 자체의 기본값은 false다. 다만 현재 시스템 속성 persist.sys.deviceagent.taskmanager.enable의 기본값이 true이므로 Core는 활성화된다. AAR가 forceTaskManager=true를 넣는 이유는 시스템 속성 상태와 무관하게 관리 경로를 명시하기 위해서다.

5.4.3 공통 실행 정책 기본값

등록되지 않은 메서드의 fallback은 일반적으로 timeoutMs=30000, retry=0, stateAware=true를 사용한다. 이름이 get, is, Info, Version, Dump 계열이면 DIRECT로, 그 외에는 ASYNC로 추정한다. 이름에 stop, reset, error, emergency가 들어가면 EMERGENCY로 추정할 수 있으므로, 외부의 source 누락은 UNKNOWN이 되어 호출자 정책에서 거절될 수 있다. 이름 기반 fallback은 개발 중 호환용이지 기능 등록을 대신하지 않는다.

5.4.4 Workflow와 예약 기본값

5.4.5 도메인 실행기가 보완하는 값

도메인 기본값은 편의를 위한 임의 추정이 아니라 기존 기능 계약을 안정된 Task 입력으로 바꾸는 어댑터 규칙이어야 한다. 예를 들어 이동 대상 공간, TTS 문장, 화면 이름, 외부 앱 세션 키처럼 의미를 바꾸는 값은 도메인 실행기가 임의 생성하면 안 된다.

청정 기본값 주의: 엄격 검증이 꺼진 상태에서 setAirCleanerOperation에 action, mode, speed, operation을 모두 생략하면 실행기가 시작·기본 청정·speed=0·ai=false를 보완한다. 기본 청정의 완료 조건은 cleaning.stopped이고 cleanMinTimeMs 기본은 0ms이므로, 시작 직후 정지 명령으로 이어질 수 있다. 이는 하위 호환을 위한 실행기 보완이지 안전한 공개 API 최소 요청이 아니다. 제품 호출자는 최소한 동작과 모드를 명시하고 엄격 검증 시험을 통과해야 한다.

5.4.6 기본값이 없거나 생략하면 안 되는 필드

현재 엄격 검증의 기본값은 false다. 이는 기존 호출 호환성을 위한 선택이지 필수 매개변수가 실제로 선택이라는 뜻이 아니다. 출시 계약에서는 기능 카드에 호출자가 반드시 보내는 값, AAR가 넣는 값, Core 정책값, 도메인 실행기 기본값, 기본값 금지값을 분리해 고정하고, 엄격 검증을 켠 회귀 시험까지 통과해야 한다.

5.5 공통 결과 필드

6. 실행 허용 절차

submitTask는 실행기를 호출하기 전에 아래 절차를 통과한다.

6.1 활성화 조건

TaskManager는 다음 중 하나면 활성화된다.

• 요청에 forceTaskManager=true
• persist.sys.deviceagent.taskmanager.enable=true

해당 속성을 읽지 못했을 때의 기본값은 현재 true다.

6.2 입력 검증

현재 입력 검증은 기존 시스템 호환을 위해 두 단계로 동작한다.

전역 속성:

persist.sys.deviceagent.taskmanager.strict_validation

예시:

알 수 없는 메서드는 입력 검증기를 통과하더라도 실행기 생성 단계에서 missing_task_command로 거절될 수 있다. 따라서 엄격한 입력 검증만으로 기능 등록 여부까지 보장할 수는 없다.

6.3 호출자 정책

현재 가장 명시적인 요청 출처 정책은 긴급 우선순위 제한이다.

• EMERGENCY 우선순위는 INTERNAL, AUTONOMOUS, SENSOR 요청에만 허용한다.
• bypassCallerPolicy=true는 특권 우회이므로 일반 외부 요청에 노출하면 안 된다.

6.4 도메인 자원 정책

현재 명시적으로 관리하는 충돌 예시는 다음과 같다.

requiredResources를 요청에 추가하면 기능별 조건문을 계속 늘리지 않고 자원 요구사항을 구조화할 수 있다. 선택적 상위 Planner도 기능 설명자에 정의된 같은 자원 용어를 사용해야 한다.

6.5 시스템 자원 정책

TaskResourceMonitor는 CPU 사용률, RAM 압력과 발열 단계의 최신 스냅숏을 보관한다. 실행 허용 절차는 resourcePolicyEnabled와 정책 임계값에 따라 작업을 거절할 수 있다. 스냅숏은 하드웨어 상태의 영구 진실이 아니므로 측정 시점과 출처를 함께 확인해야 한다.

6.6 선점 실행 허용

새 요청은 기본적으로 기존 작업을 중단하지 않는다. preemptPolicy가 명시된 경우에만 대기열과 Task 상태를 변경한다.

6.7 기존 DeviceAgent 제품 정책의 계승

TaskManager 도입 전부터 DeviceAgent에는 제품 상태, 배터리, LLM 세션, 개인정보 보호, 오류, 이동 자세와 동작 간 충돌을 판단하는 정책이 있다. TaskManager는 이 정책을 별도 규칙으로 복사하지 않고 승인된 기존 도메인 진입점을 통해 반드시 통과해야 한다.

정책은 다음 네 계층으로 나눈다.

6.7.1 대표 정책 계승 행렬

이 표의 틸트, LCD 깨움과 도킹 처리처럼 기능 수행에 내재된 제품 정책은 독립 Task로 노출하지 않는다. 독립 Task로 노출하면 Planner나 호출자가 내부 안전 순서를 생략하거나 잘못 재배열할 수 있다. 대신 이동 capability의 실행 계약과 결과에 posturePolicyApplied, physicalCompletionObserved 같은 관측 필드를 추가할 수 있다.

6.7.2 정책 계승 불변 조건

1. 관리 실행기는 기존 도메인 정책 담당자를 우회해 HAL·MCU·AMR을 직접 호출하면 안 된다.
2. 저수준 호출이 필요한 전용 실행기는 기존 진입점과 동등한 상태·자원 검사를 갖췄다는 별도 검토와 실기기 증거가 있어야 한다.
3. TaskManager의 priority, preemptPolicy, forceTaskManager는 제품 안전 정책을 무효화하는 권한이 아니다.
4. 도메인 정책의 거절·대기·자동 전환 결과는 accepted, errorCode, reason, recoverability로 변환해야 한다.
5. 암묵적 제품 동작은 Workflow 단계 수를 늘리지 않되, 로그·이벤트·완료 증거에서 적용 여부를 확인할 수 있어야 한다.
6. 같은 기능의 기존 경로와 관리 경로는 동일한 정책 조건에서 같은 물리 허용·거절 결과를 내야 한다.

6.7.3 현재 보강이 필요한 경계

7. 실행 정책 목록

TaskPolicyRegistry는 메서드별 기본 실행 정책을 중앙에서 관리한다.

7.1 실행 방식

문자열 alias:

• direct, sync → DIRECT
• queued_wait, wait → QUEUED_WAIT
• async → ASYNC

7.2 대기열

현재 정책 목록과 런타임에서 사용하는 대기열은 다음과 같다.

7.3 우선순위

7.4 현재 정책 예시

등록되지 않은 메서드는 이름을 기준으로 실행 방식과 대기열을 추정한다. 이 기본 처리는 기존 기능을 수용하기 위한 임시 안전망일 뿐, 출시 가능한 기능 등록을 뜻하지 않는다. 제품 출시 대상 기능에는 명시적 정책과 실행기를 등록해야 한다.

제3부 · 실행 생명주기와 Workflow — 8~15장은 Task 상태, 실행 방식, 단계 제어, 완료 증거, 취소, 실패와 예약을 정의한다.