From bb66009d370b22d77fb8e76da4b3fe21f534f811 Mon Sep 17 00:00:00 2001 From: exijn Date: Tue, 10 Nov 2026 20:54:06 +0900 Subject: [PATCH] =?UTF-8?q?feat(execution):=20=EC=8B=A4=ED=96=89=20?= =?UTF-8?q?=EC=8B=A4=ED=8C=A8=20=EC=82=AC=EC=9C=A0=20=EC=BD=94=EB=93=9C=20?= =?UTF-8?q?=EC=A0=95=EC=9D=98=EC=99=80=20=EB=A1=9C=EC=BB=AC=20=EA=B8=B0?= =?UTF-8?q?=EB=A1=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - FailureCode(SAFETY_REJECTED·APPROVAL_EXPIRED·TELEMETRY_STALE·POSTURE_UNKNOWN·SDK_REJECTED·TIMEOUT· NOT_MOVED·EXECUTION_ERROR)와 CodedError/failure_code_of 추가. - guard·SDK client·backend 의 raise 위치에서 코드 지정, ExecutionResult.failure_code 와 execution_failed 로그 failure_code 필드로 기록. Server 보고는 Poppy-Server#134 계약 확정 후. Part of #101 Co-Authored-By: Claude Opus 5.5 --- docs/failure-codes.md | 27 +++++ src/poppy_agent/execution/__init__.py | 2 + src/poppy_agent/execution/executor.py | 6 ++ src/poppy_agent/execution/failure.py | 49 +++++++++ src/poppy_agent/execution/models.py | 2 + src/poppy_agent/execution/open_motion.py | 14 ++- src/poppy_agent/execution/trial.py | 9 +- src/poppy_agent/hardware/unitree.py | 17 ++- src/poppy_agent/hardware/unitree_sdk.py | 12 ++- src/poppy_agent/observability.py | 1 + src/poppy_agent/server/runtime.py | 1 + tests/test_failure_codes.py | 128 +++++++++++++++++++++++ 12 files changed, 255 insertions(+), 13 deletions(-) create mode 100644 docs/failure-codes.md create mode 100644 src/poppy_agent/execution/failure.py create mode 100644 tests/test_failure_codes.py diff --git a/docs/failure-codes.md b/docs/failure-codes.md new file mode 100644 index 0000000..60821ec --- /dev/null +++ b/docs/failure-codes.md @@ -0,0 +1,27 @@ +# 실행 실패 코드 (#101) + +Agent 는 FAILED 실행마다 `ExecutionResult.failure_code` 와 구조화 로그 `execution_failed` 의 +`failure_code` 필드에 아래 코드 중 하나를 남긴다. SDK 원문 오류·반환 코드·토큰은 코드와 메시지에 넣지 않는다. + +| 코드 | 의미 | 발생 위치(현재 develop) | +|---|---|---| +| `SAFETY_REJECTED` | 안전 정책·guard 한도로 dispatch 전 거부 | `ExecutionSafetyValidator`, `OpenMotionGuard`/`TrialGuard` 한도 | +| `APPROVAL_EXPIRED` | 실제 동작 승인 시간 만료 | `OpenMotionGuard.admit` | +| `TELEMETRY_STALE` | 로봇 텔레메트리가 신선하지 않아 거부 | `OpenMotionGuard`/`TrialGuard` | +| `POSTURE_UNKNOWN` | 자세 불명으로 거부 | #110(#98) 머지 후 연결 | +| `SDK_REJECTED` | SDK 가 명령을 거절(0 이 아닌 결과) | `UnitreeSdkCommandClient._call_operation`, backend 결과 검사 | +| `TIMEOUT` | SDK `Move` 호출이 제한 시간 이상 막힘 | `execute_motion_with_cancellation` | +| `NOT_MOVED` | 폐루프에서 미이동 판정 | #97 폐루프 머지 후 연결 | +| `EXECUTION_ERROR` | 위에 해당하지 않는 실패(전송 예외, StopMove 미확인 등) | 기본값 | + +코드는 예외가 만들어지는 곳에서 `failure_code` 로 붙이고(`CodedError`), executor 는 원인 체인에서 첫 코드를 +찾는다(`failure_code_of`). 코드가 없으면 위치별 기본값(guard 는 `SAFETY_REJECTED`, 실행 중은 `EXECUTION_ERROR`)이다. + +## Server 보고 (미연결) + +Server 계약(Poppy-Server#134 `failureCode`, `failureMessage`)이 확정되지 않아 아직 보고하지 않는다. +CLAUDE.md 에 따라 계약을 추측해 payload 를 바꾸지 않는다. 제안: + +- `PATCH` 실행 상태 보고 payload 에 `failureCode`(위 값, FAILED 일 때만)를 선택 필드로 추가. +- `failureMessage` 는 Server 가 코드로 만든 고정 안내문을 쓴다(Agent 의 `failure_reason` 원문은 보내지 않음). +- 이전 Server 와의 호환: 필드가 없으면 기존 동작. 재시도·중복 보고 시 같은 코드를 다시 보낸다. diff --git a/src/poppy_agent/execution/__init__.py b/src/poppy_agent/execution/__init__.py index 9388247..4fbafad 100644 --- a/src/poppy_agent/execution/__init__.py +++ b/src/poppy_agent/execution/__init__.py @@ -14,6 +14,7 @@ MockCommandTarget, MockExecutionExecutor, ) +from poppy_agent.execution.failure import FailureCode from poppy_agent.execution.models import ( SUPPORTED_EXECUTION_PROTOCOL_VERSION, ExecutionResult, @@ -48,6 +49,7 @@ ) __all__ = [ + "FailureCode", "SUPPORTED_EXECUTION_PROTOCOL_VERSION", "CancellationSleeper", "CommandExecutionTarget", diff --git a/src/poppy_agent/execution/executor.py b/src/poppy_agent/execution/executor.py index 32ddd70..f0aced0 100644 --- a/src/poppy_agent/execution/executor.py +++ b/src/poppy_agent/execution/executor.py @@ -13,6 +13,7 @@ ExecutionCancellationToken, ExecutionCancelledError, ) +from poppy_agent.execution.failure import FailureCode, failure_code_of from poppy_agent.execution.models import ExecutionResult, ExecutionStatus, ExecutionTask from poppy_agent.execution.safety import ( CommandSafetyPolicy, @@ -148,6 +149,7 @@ def execute( execution_id=task.execution_id, status=ExecutionStatus.FAILED, failure_reason="configured mock execution failure", + failure_code=FailureCode.EXECUTION_ERROR, ) try: @@ -157,6 +159,7 @@ def execute( execution_id=task.execution_id, status=ExecutionStatus.FAILED, failure_reason=str(exc), + failure_code=FailureCode.SAFETY_REJECTED, ) if self._program_guard is None: @@ -168,6 +171,7 @@ def execute( execution_id=task.execution_id, status=ExecutionStatus.FAILED, failure_reason=f"program guard rejected execution: {exc}", + failure_code=failure_code_of(exc, FailureCode.SAFETY_REJECTED), ) try: return self._dispatch_program(task, token) @@ -189,6 +193,7 @@ def _dispatch_program( failure_reason=( f"configured mock execution failure at sequence {command.sequence}" ), + failure_code=FailureCode.EXECUTION_ERROR, ) try: dispatch_with_cancellation = getattr( @@ -209,6 +214,7 @@ def _dispatch_program( execution_id=task.execution_id, status=ExecutionStatus.FAILED, failure_reason=f"execution target failed: {exc}", + failure_code=failure_code_of(exc, FailureCode.EXECUTION_ERROR), ) if should_stop: break diff --git a/src/poppy_agent/execution/failure.py b/src/poppy_agent/execution/failure.py new file mode 100644 index 0000000..0c5c530 --- /dev/null +++ b/src/poppy_agent/execution/failure.py @@ -0,0 +1,49 @@ +"""Stable, secret-free Execution failure codes (#101). + +Codes classify why an Execution FAILED without exposing SDK details. Errors +carry a ``failure_code`` attribute where they are raised; anything without one +is ``EXECUTION_ERROR``. Reporting the code to Poppy-Server waits for the Server +contract (Poppy-Server#134); until then it is recorded locally in the result and +the structured ``execution_failed`` log. +""" + +from __future__ import annotations + +from enum import StrEnum + + +class FailureCode(StrEnum): + SAFETY_REJECTED = "SAFETY_REJECTED" + APPROVAL_EXPIRED = "APPROVAL_EXPIRED" + TELEMETRY_STALE = "TELEMETRY_STALE" + POSTURE_UNKNOWN = "POSTURE_UNKNOWN" + SDK_REJECTED = "SDK_REJECTED" + TIMEOUT = "TIMEOUT" + NOT_MOVED = "NOT_MOVED" + EXECUTION_ERROR = "EXECUTION_ERROR" + + +class CodedError(RuntimeError): + """RuntimeError that may carry a ``FailureCode`` set where it is raised.""" + + failure_code: FailureCode | None = None + + def __init__(self, *args: object, failure_code: FailureCode | None = None) -> None: + super().__init__(*args) + if failure_code is not None: + self.failure_code = failure_code + + +def failure_code_of(exc: BaseException | None, default: FailureCode) -> FailureCode: + """Return the first ``failure_code`` along the cause chain, else ``default``.""" + seen: set[int] = set() + while exc is not None and id(exc) not in seen: + seen.add(id(exc)) + code = getattr(exc, "failure_code", None) + if isinstance(code, FailureCode): + return code + exc = exc.__cause__ + return default + + +__all__ = ["CodedError", "FailureCode", "failure_code_of"] diff --git a/src/poppy_agent/execution/models.py b/src/poppy_agent/execution/models.py index 90c2c15..48bead8 100644 --- a/src/poppy_agent/execution/models.py +++ b/src/poppy_agent/execution/models.py @@ -7,6 +7,7 @@ from uuid import UUID from poppy_agent.command.models import HighLevelCommandProgram +from poppy_agent.execution.failure import FailureCode SUPPORTED_EXECUTION_PROTOCOL_VERSION = 1 @@ -58,3 +59,4 @@ class ExecutionResult: execution_id: UUID status: ExecutionStatus failure_reason: str | None = None + failure_code: FailureCode | None = None diff --git a/src/poppy_agent/execution/open_motion.py b/src/poppy_agent/execution/open_motion.py index 290b22b..7c3b1ed 100644 --- a/src/poppy_agent/execution/open_motion.py +++ b/src/poppy_agent/execution/open_motion.py @@ -26,15 +26,18 @@ WaitParameters, ) from poppy_agent.config.open_motion import OpenMotionSettings +from poppy_agent.execution.failure import CodedError, FailureCode from poppy_agent.execution.readiness import ( PhysicalCommandClientKind, PhysicalReadinessEvidence, ) -class OpenMotionGuardError(RuntimeError): +class OpenMotionGuardError(CodedError): """Raised when an Execution is outside the open trial limits.""" + failure_code = FailureCode.SAFETY_REJECTED + class OpenMotionGuardState(StrEnum): AVAILABLE = "AVAILABLE" @@ -140,12 +143,17 @@ def admit(self, program: HighLevelCommandProgram) -> None: """Validate the whole Execution before dispatch; reject on any limit.""" with self._lock: if self.expired(): - raise OpenMotionGuardError("the open trial approval window has expired") + raise OpenMotionGuardError( + "the open trial approval window has expired", + failure_code=FailureCode.APPROVAL_EXPIRED, + ) if self._executing: raise OpenMotionGuardError("an Execution is already in progress") summary = self.plan(program, sitting=self._sitting) if summary.physical_commands and self._telemetry_fresh() is not True: - raise OpenMotionGuardError("Robot telemetry is not fresh") + raise OpenMotionGuardError( + "Robot telemetry is not fresh", failure_code=FailureCode.TELEMETRY_STALE + ) self._executing = True self._executions_admitted += 1 self._last_plan = summary diff --git a/src/poppy_agent/execution/trial.py b/src/poppy_agent/execution/trial.py index f62bced..156e6be 100644 --- a/src/poppy_agent/execution/trial.py +++ b/src/poppy_agent/execution/trial.py @@ -14,6 +14,7 @@ from poppy_agent.command import CommandType, HighLevelCommandProgram, TurnParameters from poppy_agent.config.physical_trial import PhysicalTrialSettings +from poppy_agent.execution.failure import CodedError, FailureCode from poppy_agent.execution.readiness import ( PhysicalCommandClientKind, PhysicalReadinessEvidence, @@ -22,9 +23,11 @@ _NON_PHYSICAL_COMMANDS = frozenset({CommandType.WAIT, CommandType.STOP}) -class TrialGuardError(RuntimeError): +class TrialGuardError(CodedError): """Raised when a program is outside the controlled trial budget.""" + failure_code = FailureCode.SAFETY_REJECTED + class TrialGuardState(StrEnum): AVAILABLE = "AVAILABLE" @@ -114,7 +117,9 @@ def admit(self, program: HighLevelCommandProgram) -> None: if self._motion_seconds_used + program_seconds > self._settings.max_total_seconds: raise TrialGuardError("controlled trial total motion time would be exceeded") if turns and self._telemetry_fresh() is not True: - raise TrialGuardError("Robot telemetry is not fresh") + raise TrialGuardError( + "Robot telemetry is not fresh", failure_code=FailureCode.TELEMETRY_STALE + ) self._commands_used += len(turns) self._turn_degrees_used += program_degrees self._motion_seconds_used += program_seconds diff --git a/src/poppy_agent/hardware/unitree.py b/src/poppy_agent/hardware/unitree.py index b67acc6..7fc16da 100644 --- a/src/poppy_agent/hardware/unitree.py +++ b/src/poppy_agent/hardware/unitree.py @@ -24,6 +24,7 @@ ExecutionCancellationToken, ExecutionCancelledError, ) +from poppy_agent.execution.failure import CodedError, FailureCode from poppy_agent.execution.motion import MotionExecutionStrategy, MotionPlan, MotionSleeper from poppy_agent.hardware.boundary import HardwareCommandIntent, HardwareCommandPort from poppy_agent.observability import ( @@ -82,7 +83,7 @@ def __call__( """Execute the full planned motion, honoring cancellation.""" -class UnitreeCommandBackendError(RuntimeError): +class UnitreeCommandBackendError(CodedError): """Raised when a Unitree mapping is unsupported or cannot be dispatched.""" @@ -286,7 +287,8 @@ def _dispatch( result = self._client.execute_motion(plan) if result is not True: raise UnitreeCommandBackendError( - f"Unitree client reported failure for {intent.type.value}" + f"Unitree client reported failure for {intent.type.value}", + failure_code=FailureCode.SDK_REJECTED, ) self._sleeper.sleep(plan.duration_seconds, cancellation_token) return False @@ -301,7 +303,8 @@ def _dispatch( result = self._client.stand_up() if result is not True: raise UnitreeCommandBackendError( - f"Unitree client reported failure for {intent.parameters.posture.value}" + f"Unitree client reported failure for {intent.parameters.posture.value}", + failure_code=FailureCode.SDK_REJECTED, ) return False @@ -388,7 +391,10 @@ def _balance_stand(self) -> object: @staticmethod def _require_client_ok(result: object, operation: str) -> None: if result is not True: - raise UnitreeCommandBackendError(f"Unitree client reported failure for {operation}") + raise UnitreeCommandBackendError( + f"Unitree client reported failure for {operation}", + failure_code=FailureCode.SDK_REJECTED, + ) def _log_action_started(self, action: str, operations: tuple[str, ...]) -> None: log_event( @@ -437,7 +443,8 @@ def _dispatch_streaming_motion( result = streaming(plan, cancellation_token) if result is not True: raise UnitreeCommandBackendError( - f"Unitree client reported failure for {plan.command_type.value}" + f"Unitree client reported failure for {plan.command_type.value}", + failure_code=FailureCode.SDK_REJECTED, ) except ExecutionCancelledError: self._log_motion_finished(plan, "CANCELLED") diff --git a/src/poppy_agent/hardware/unitree_sdk.py b/src/poppy_agent/hardware/unitree_sdk.py index 900ebd7..642b786 100644 --- a/src/poppy_agent/hardware/unitree_sdk.py +++ b/src/poppy_agent/hardware/unitree_sdk.py @@ -21,12 +21,13 @@ ExecutionCancellationToken, ExecutionCancelledError, ) +from poppy_agent.execution.failure import CodedError, FailureCode from poppy_agent.execution.motion import MotionPlan, MotionRateUnit, MotionUnit from .unitree import UnitreeCommandClient -class UnitreeSdkCommandError(RuntimeError): +class UnitreeSdkCommandError(CodedError): """Raised when the optional SDK cannot be initialized or called safely.""" @@ -330,7 +331,9 @@ def execute_motion_with_cancellation( ) from exc trace.move_calls += 1 if timing.monotonic() - call_started >= timing.max_move_call_seconds: - raise UnitreeMotionOutcomeUnknownError("Unitree SDK Move call blocked too long") + raise UnitreeMotionOutcomeUnknownError( + "Unitree SDK Move call blocked too long", failure_code=FailureCode.TIMEOUT + ) next_send = start + trace.move_calls * timing.move_period_seconds wait = min(next_send, start + plan.duration_seconds) - timing.monotonic() if wait > 0: @@ -406,7 +409,10 @@ def _call_operation(self, method_name: str, *args: object) -> bool: ) from exc normalized = _normalize_result(result, method_name) if normalized is not True: - raise UnitreeSdkCommandError(f"Unitree SDK {method_name} reported failure") + raise UnitreeSdkCommandError( + f"Unitree SDK {method_name} reported failure", + failure_code=FailureCode.SDK_REJECTED, + ) return True def _require_initialized(self) -> None: diff --git a/src/poppy_agent/observability.py b/src/poppy_agent/observability.py index 0136ff2..e92c8b7 100644 --- a/src/poppy_agent/observability.py +++ b/src/poppy_agent/observability.py @@ -64,6 +64,7 @@ "execution_status", "recovery_action", "error_type", + "failure_code", "attempt", "max_attempts", "protocol_version", diff --git a/src/poppy_agent/server/runtime.py b/src/poppy_agent/server/runtime.py index 141b2c5..d6d54e0 100644 --- a/src/poppy_agent/server/runtime.py +++ b/src/poppy_agent/server/runtime.py @@ -632,6 +632,7 @@ def _finish_execution(self, task: ExecutionTask, result: ExecutionResult) -> Exe robot_id=task.robot_id, execution_id=task.execution_id, execution_status=result.status.value, + failure_code=result.failure_code.value if result.failure_code is not None else None, ) return result diff --git a/tests/test_failure_codes.py b/tests/test_failure_codes.py new file mode 100644 index 0000000..980558b --- /dev/null +++ b/tests/test_failure_codes.py @@ -0,0 +1,128 @@ +"""Execution failure codes (#101), fakes only.""" + +from __future__ import annotations + +import logging + +import pytest + +from poppy_agent.command import Posture +from poppy_agent.execution import ExecutionStatus, FailureCode +from poppy_agent.execution.failure import CodedError, failure_code_of +from poppy_agent.hardware.unitree_sdk import MotionStreamTiming +from test_controlled_motion_open import ( + EXPIRES, + FakeClock, + FakeSportClient, + build, + move, + posture, + run, +) + + +class RejectingSportClient(FakeSportClient): + def __init__(self, clock: FakeClock, reject: str) -> None: + super().__init__(clock) + self.reject = reject + + def _record(self, name: str, *args: float) -> int: + self.calls.append((name, args)) + return 3104 if name == self.reject else 0 + + +def test_codes_are_the_issue_contract_values() -> None: + assert {code.value for code in FailureCode} == { + "SAFETY_REJECTED", + "APPROVAL_EXPIRED", + "TELEMETRY_STALE", + "POSTURE_UNKNOWN", + "SDK_REJECTED", + "TIMEOUT", + "NOT_MOVED", + "EXECUTION_ERROR", + } + + +def test_cause_chain_lookup_and_default() -> None: + inner = CodedError("inner", failure_code=FailureCode.SDK_REJECTED) + try: + try: + raise inner + except CodedError as exc: + raise RuntimeError("wrapped") from exc + except RuntimeError as outer: + assert failure_code_of(outer, FailureCode.EXECUTION_ERROR) is FailureCode.SDK_REJECTED + assert failure_code_of(ValueError("x"), FailureCode.TIMEOUT) is FailureCode.TIMEOUT + assert failure_code_of(None, FailureCode.TIMEOUT) is FailureCode.TIMEOUT + + +def test_completed_execution_has_no_code() -> None: + clock = FakeClock() + result = run(build(clock, FakeSportClient(clock)), move(0.5)) + assert result.status is ExecutionStatus.COMPLETED + assert result.failure_code is None + + +def test_guard_limit_is_safety_rejected() -> None: + clock = FakeClock() + result = run(build(clock, FakeSportClient(clock)), move(3.5)) + assert result.failure_code is FailureCode.SAFETY_REJECTED + + +def test_expired_approval_code() -> None: + clock = FakeClock() + trial = build(clock, FakeSportClient(clock)) + clock.wall = EXPIRES + assert run(trial, move(0.5)).failure_code is FailureCode.APPROVAL_EXPIRED + + +def test_stale_telemetry_code() -> None: + clock = FakeClock() + result = run(build(clock, FakeSportClient(clock), telemetry_fresh=False), move(0.5)) + assert result.failure_code is FailureCode.TELEMETRY_STALE + + +@pytest.mark.parametrize( + ("reject", "commands"), + [ + ("Sit", (posture(Posture.SIT),)), + ("Move", (move(0.5),)), + ], +) +def test_sdk_rejection_code_without_sdk_details(reject: str, commands: tuple) -> None: + clock = FakeClock() + result = run(build(clock, RejectingSportClient(clock, reject)), *commands) + assert result.status is ExecutionStatus.FAILED + assert result.failure_code is FailureCode.SDK_REJECTED + + +def test_blocked_move_call_is_timeout() -> None: + clock = FakeClock() + + class SlowSportClient(FakeSportClient): + def Move(self, vx: float, vy: float, vyaw: float) -> int: + clock.advance(1.0) + return super().Move(vx, vy, vyaw) + + sport = SlowSportClient(clock) + trial = build(clock, sport) + timing = MotionStreamTiming(monotonic=clock.monotonic, sleep=clock.sleep, wait=clock.wait) + assert timing.max_move_call_seconds < 1.0 + assert run(trial, move(0.5)).failure_code is FailureCode.TIMEOUT + + +def test_transport_exception_is_execution_error() -> None: + clock = FakeClock() + sport = FakeSportClient(clock, move_error_at=0) + assert run(build(clock, sport), move(0.5)).failure_code is FailureCode.EXECUTION_ERROR + + +def test_failure_code_is_an_allowed_log_field(caplog: pytest.LogCaptureFixture) -> None: + from poppy_agent.observability import log_event + + with caplog.at_level(logging.ERROR): + log_event( + logging.getLogger("test"), logging.ERROR, "execution_failed", failure_code="TIMEOUT" + ) + assert caplog.records[-1].poppy_context == {"failure_code": "TIMEOUT"} # type: ignore[attr-defined]