Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/failure-codes.md
Original file line number Diff line number Diff line change
@@ -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 와의 호환: 필드가 없으면 기존 동작. 재시도·중복 보고 시 같은 코드를 다시 보낸다.
2 changes: 2 additions & 0 deletions src/poppy_agent/execution/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
MockCommandTarget,
MockExecutionExecutor,
)
from poppy_agent.execution.failure import FailureCode
from poppy_agent.execution.models import (
SUPPORTED_EXECUTION_PROTOCOL_VERSION,
ExecutionResult,
Expand Down Expand Up @@ -48,6 +49,7 @@
)

__all__ = [
"FailureCode",
"SUPPORTED_EXECUTION_PROTOCOL_VERSION",
"CancellationSleeper",
"CommandExecutionTarget",
Expand Down
6 changes: 6 additions & 0 deletions src/poppy_agent/execution/executor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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)
Expand All @@ -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(
Expand All @@ -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
Expand Down
49 changes: 49 additions & 0 deletions src/poppy_agent/execution/failure.py
Original file line number Diff line number Diff line change
@@ -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"]
2 changes: 2 additions & 0 deletions src/poppy_agent/execution/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -58,3 +59,4 @@ class ExecutionResult:
execution_id: UUID
status: ExecutionStatus
failure_reason: str | None = None
failure_code: FailureCode | None = None
14 changes: 11 additions & 3 deletions src/poppy_agent/execution/open_motion.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions src/poppy_agent/execution/trial.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand Down
17 changes: 12 additions & 5 deletions src/poppy_agent/hardware/unitree.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -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."""


Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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")
Expand Down
12 changes: 9 additions & 3 deletions src/poppy_agent/hardware/unitree_sdk.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""


Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions src/poppy_agent/observability.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@
"execution_status",
"recovery_action",
"error_type",
"failure_code",
"attempt",
"max_attempts",
"protocol_version",
Expand Down
1 change: 1 addition & 0 deletions src/poppy_agent/server/runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading