refactor(runtime): extract shared exceptions from watchdog.errors

PhyAgentOS/plugins/perception_plugins/sam3_open_vocab.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 from PhyAgentOS.plugins.perception_plugins.base import BasePerceptionPlugin
+from PhyAgentOS.runtime.errors import SchemaValidationError
 from PhyAgentOS.runtime.perception.sensor_frame import SensorFrame
 from PhyAgentOS.runtime.schemas.perception import EnvironmentDelta
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
 
 
 class SAM3OpenVocabPlugin(BasePerceptionPlugin):

PhyAgentOS/plugins/perception_plugins/yolo_seg.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 from PhyAgentOS.plugins.perception_plugins.base import BasePerceptionPlugin
+from PhyAgentOS.runtime.errors import SchemaValidationError
 from PhyAgentOS.runtime.perception.sensor_frame import SensorFrame
 from PhyAgentOS.runtime.schemas.perception import EnvironmentDelta
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
 
 
 class YOLOSegPlugin(BasePerceptionPlugin):

PhyAgentOS/runtime/adapters/behavior1k/target_adapter.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.base import BaseTargetAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class Behavior1kTargetAdapter(BaseTargetAdapter):

PhyAgentOS/runtime/adapters/bridges.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.base import BaseActionBridge
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class SafetyClampBridge(BaseActionBridge):

PhyAgentOS/runtime/adapters/factory.py

@@ -5,19 +5,23 @@
 from collections.abc import Callable
 from typing import Any
 
-from PhyAgentOS.runtime.adapters.bridges import SafetyClampBridge
 from PhyAgentOS.runtime.adapters.behavior1k.target_adapter import Behavior1kTargetAdapter
+from PhyAgentOS.runtime.adapters.bridges import SafetyClampBridge
 from PhyAgentOS.runtime.adapters.go2.target_adapter import Go2BuiltinTargetAdapter
 from PhyAgentOS.runtime.adapters.isaacsim.target_adapter import IsaacSimTargetAdapter
 from PhyAgentOS.runtime.adapters.libero.target_adapter import LiberoTargetAdapter
 from PhyAgentOS.runtime.adapters.openpi.b1k_dummy_policy_adapter import Behavior1kDummyPolicyAdapter
-from PhyAgentOS.runtime.adapters.openpi.b1k_openpi_policy_adapter import Behavior1kOpenPIPolicyAdapter
+from PhyAgentOS.runtime.adapters.openpi.b1k_openpi_policy_adapter import (
+    Behavior1kOpenPIPolicyAdapter,
+)
 from PhyAgentOS.runtime.adapters.openpi.dummy_openpi_adapter import DummyOpenPIAdapter
-from PhyAgentOS.runtime.adapters.openpi.pipergo2_isaac_policy_adapter import PiperGo2IsaacPolicyAdapter
 from PhyAgentOS.runtime.adapters.openpi.pi05_policy_adapter import OpenPIPi05Adapter
+from PhyAgentOS.runtime.adapters.openpi.pipergo2_isaac_policy_adapter import (
+    PiperGo2IsaacPolicyAdapter,
+)
 from PhyAgentOS.runtime.adapters.target_dummy import DummySimTargetAdapter
+from PhyAgentOS.runtime.errors import AdapterError
 from PhyAgentOS.runtime.schemas.adapter_plan import AdapterPlan
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
 
 AdapterFactory = Callable[[], Any]
 

PhyAgentOS/runtime/adapters/go2/target_adapter.py

@@ -5,7 +5,7 @@
 from typing import Any
 
 from PhyAgentOS.runtime.adapters.base import BaseTargetAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class Go2BuiltinTargetAdapter(BaseTargetAdapter):

PhyAgentOS/runtime/adapters/isaacsim/target_adapter.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.base import BaseTargetAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class IsaacSimTargetAdapter(BaseTargetAdapter):

PhyAgentOS/runtime/adapters/libero/target_adapter.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.base import BaseTargetAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class LiberoTargetAdapter(BaseTargetAdapter):

PhyAgentOS/runtime/adapters/openpi/b1k_dummy_policy_adapter.py

@@ -8,7 +8,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.openpi.base_openpi_adapter import BaseOpenPIAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class Behavior1kDummyPolicyAdapter(BaseOpenPIAdapter):

PhyAgentOS/runtime/adapters/openpi/b1k_openpi_policy_adapter.py

@@ -14,7 +14,7 @@
     RIGHT_WRIST_RGB_KEY,
 )
 from PhyAgentOS.runtime.adapters.openpi.base_openpi_adapter import BaseOpenPIAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class Behavior1kOpenPIPolicyAdapter(BaseOpenPIAdapter):

PhyAgentOS/runtime/adapters/openpi/base_openpi_adapter.py

@@ -8,7 +8,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.base import BasePolicyAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class BaseOpenPIAdapter(BasePolicyAdapter):

PhyAgentOS/runtime/adapters/openpi/dummy_openpi_adapter.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.openpi.base_openpi_adapter import BaseOpenPIAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class DummyOpenPIAdapter(BaseOpenPIAdapter):

PhyAgentOS/runtime/adapters/openpi/pi05_policy_adapter.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.openpi.base_openpi_adapter import BaseOpenPIAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class OpenPIPi05Adapter(BaseOpenPIAdapter):

PhyAgentOS/runtime/adapters/openpi/pipergo2_isaac_policy_adapter.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.openpi.base_openpi_adapter import BaseOpenPIAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class PiperGo2IsaacPolicyAdapter(BaseOpenPIAdapter):

PhyAgentOS/runtime/adapters/target_dummy.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from PhyAgentOS.runtime.adapters.base import BaseTargetAdapter
-from PhyAgentOS.runtime.watchdog.errors import AdapterError
+from PhyAgentOS.runtime.errors import AdapterError
 
 
 class DummySimTargetAdapter(BaseTargetAdapter):

PhyAgentOS/runtime/communication/target_ws_client.py

@@ -8,7 +8,7 @@
 
 from PhyAgentOS.runtime.communication.envelope import RuntimeEnvelope
 from PhyAgentOS.runtime.communication.msgpack_codec import decode_msgpack, encode_msgpack
-from PhyAgentOS.runtime.watchdog.errors import TargetConnectionError, TargetProtocolError
+from PhyAgentOS.runtime.errors import TargetConnectionError, TargetProtocolError
 
 
 class TargetWSClient:

PhyAgentOS/runtime/errors.py

@@ -0,0 +1,110 @@
+"""Runtime shared exception types and failure mapping (neutral base module).
+
+All lower-level runtime modules (Target / Policy / Adapter / Perception /
+Communication / Perception Plugin, etc.) import shared exception types from
+here, avoiding a dependency inversion where the Session orchestration layer
+(watchdog) is treated as a common base package.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "RuntimeErrorBase",
+    "SchemaValidationError",
+    "TargetBuildError",
+    "TargetResetError",
+    "TargetStepError",
+    "TargetConnectionError",
+    "TargetProtocolError",
+    "AdapterError",
+    "PolicyClientError",
+    "PolicyConnectionError",
+    "PolicyTimeoutError",
+    "PolicyProtocolError",
+    "SessionTimeoutError",
+    "error_code_for",
+    "terminal_status_for",
+]
+
+
+class RuntimeErrorBase(Exception):  # noqa: N818 - historical public API name, kept for compatibility
+    """Base class for recoverable runtime v2 failures."""
+
+
+class SchemaValidationError(RuntimeErrorBase):
+    pass
+
+
+class TargetBuildError(RuntimeErrorBase):
+    pass
+
+
+class TargetResetError(RuntimeErrorBase):
+    pass
+
+
+class TargetStepError(RuntimeErrorBase):
+    pass
+
+
+class TargetConnectionError(RuntimeErrorBase):
+    pass
+
+
+class TargetProtocolError(RuntimeErrorBase):
+    pass
+
+
+class AdapterError(RuntimeErrorBase):
+    pass
+
+
+class PolicyClientError(RuntimeErrorBase):
+    pass
+
+
+class PolicyConnectionError(PolicyClientError):
+    pass
+
+
+class PolicyTimeoutError(PolicyClientError):
+    pass
+
+
+class PolicyProtocolError(PolicyClientError):
+    pass
+
+
+class SessionTimeoutError(RuntimeErrorBase):
+    pass
+
+
+def error_code_for(exc: Exception) -> str:
+    """Return the protocol error code for an exception."""
+    mapping = {
+        SchemaValidationError: "SCHEMA_VALIDATION",
+        TargetBuildError: "TARGET_BUILD",
+        TargetResetError: "TARGET_RESET",
+        TargetStepError: "TARGET_STEP",
+        TargetConnectionError: "TARGET_CONNECTION",
+        TargetProtocolError: "TARGET_PROTOCOL",
+        AdapterError: "ADAPTER",
+        PolicyTimeoutError: "POLICY_TIMEOUT",
+        PolicyProtocolError: "POLICY_PROTOCOL",
+        PolicyConnectionError: "POLICY_CONNECTION",
+        PolicyClientError: "POLICY_CLIENT",
+        SessionTimeoutError: "SESSION_TIMEOUT",
+    }
+    for cls, code in mapping.items():
+        if isinstance(exc, cls):
+            return code
+    return "RUNTIME_ERROR"
+
+
+def terminal_status_for(exc: Exception) -> str:
+    """Return the terminal session status for an exception."""
+    if isinstance(exc, SchemaValidationError):
+        return "rejected"
+    if isinstance(exc, SessionTimeoutError):
+        return "timed_out"
+    return "failed"

PhyAgentOS/runtime/perception/config_resolver.py

@@ -8,14 +8,14 @@
 import yaml
 from pydantic import BaseModel, Field, ValidationError
 
+from PhyAgentOS.runtime.errors import SchemaValidationError
 from PhyAgentOS.runtime.schemas.perception import (
     PerceptionConfigDocument,
     PerceptionModelSpec,
     PerceptionPipelineSpec,
     PerceptionPluginCandidate,
 )
 from PhyAgentOS.runtime.schemas.sensor_config import SensorConfigDocument, SensorSpec
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
 from PhyAgentOS.runtime.watchdog.scheduler import ScheduledSession
 
 

PhyAgentOS/runtime/perception/perception_runtime.py

@@ -6,12 +6,15 @@
 from time import perf_counter
 from uuid import uuid4
 
-from PhyAgentOS.runtime.perception.config_resolver import PerceptionConfigResolver, ResolvedPerceptionPlan
+from PhyAgentOS.runtime.errors import SchemaValidationError
+from PhyAgentOS.runtime.perception.config_resolver import (
+    PerceptionConfigResolver,
+    ResolvedPerceptionPlan,
+)
 from PhyAgentOS.runtime.perception.environment_writer import EnvironmentWriter
 from PhyAgentOS.runtime.perception.plugin_pipeline import PerceptionPluginPipeline
 from PhyAgentOS.runtime.perception.preflight import PerceptionPreflightChecker
 from PhyAgentOS.runtime.perception.sensor_frame_builder import SensorFrameBuilder
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
 from PhyAgentOS.runtime.watchdog.scheduler import ScheduledSession
 
 

PhyAgentOS/runtime/perception/plugin_pipeline.py

@@ -9,11 +9,10 @@
 from PhyAgentOS.plugins.perception_plugins.dummy_segmenter import DummySegmenter
 from PhyAgentOS.plugins.perception_plugins.rgbd_object_builder import RGBDObjectBuilder
 from PhyAgentOS.plugins.perception_plugins.sim_oracle import SimOraclePlugin
+from PhyAgentOS.runtime.errors import SchemaValidationError
 from PhyAgentOS.runtime.perception.config_resolver import ResolvedPerceptionPlan
 from PhyAgentOS.runtime.perception.sensor_frame import SensorFrame
 from PhyAgentOS.runtime.schemas.perception import EnvironmentDelta
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
-
 
 _BUILTIN_PLUGINS: dict[str, type[BasePerceptionPlugin]] = {
     "dummy_segmenter": DummySegmenter,

PhyAgentOS/runtime/perception/preflight.py

@@ -7,14 +7,14 @@
 
 import httpx
 
+from PhyAgentOS.runtime.errors import SchemaValidationError
 from PhyAgentOS.runtime.perception.config_resolver import (
     PerceptionConfigResolver,
     ResolvedPerceptionPlan,
     sensor_by_id,
 )
 from PhyAgentOS.runtime.perception.diagnostics import PreflightResult
 from PhyAgentOS.runtime.schemas.perception import PerceptionModelSpec
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
 
 
 class PerceptionPreflightError(SchemaValidationError):

PhyAgentOS/runtime/perception/sensor_frame_builder.py

@@ -6,9 +6,9 @@
 
 import numpy as np
 
+from PhyAgentOS.runtime.errors import SchemaValidationError
 from PhyAgentOS.runtime.perception.config_resolver import ResolvedPerceptionPlan, sensor_by_id
 from PhyAgentOS.runtime.perception.sensor_frame import SensorFrame
-from PhyAgentOS.runtime.watchdog.errors import SchemaValidationError
 
 
 class SensorFrameBuilder:

PhyAgentOS/runtime/policy/b1k_websocket_client.py

@@ -16,13 +16,13 @@
 import requests
 import websocket
 
-from PhyAgentOS.runtime.policy.base_client import BasePolicyClient
-from PhyAgentOS.runtime.policy.msgpack_numpy import packb, unpackb
-from PhyAgentOS.runtime.watchdog.errors import (
+from PhyAgentOS.runtime.errors import (
     PolicyConnectionError,
     PolicyProtocolError,
     PolicyTimeoutError,
 )
+from PhyAgentOS.runtime.policy.base_client import BasePolicyClient
+from PhyAgentOS.runtime.policy.msgpack_numpy import packb, unpackb
 
 
 class Behavior1kWebsocketPolicyClient(BasePolicyClient):

PhyAgentOS/runtime/policy/factory.py

@@ -4,11 +4,11 @@
 
 from urllib.parse import urlparse
 
-from PhyAgentOS.runtime.policy.base_client import BasePolicyClient
+from PhyAgentOS.runtime.errors import PolicyConnectionError
 from PhyAgentOS.runtime.policy.b1k_websocket_client import Behavior1kWebsocketPolicyClient
+from PhyAgentOS.runtime.policy.base_client import BasePolicyClient
 from PhyAgentOS.runtime.policy.dummy_client import DummyPolicyClient
 from PhyAgentOS.runtime.policy.openpi.client import OpenPIClientPolicyWrapper
-from PhyAgentOS.runtime.watchdog.errors import PolicyConnectionError
 
 
 def parse_policy_endpoint(endpoint: str) -> tuple[str, str, int]:

PhyAgentOS/runtime/policy/openpi/client.py

@@ -9,13 +9,13 @@
 import numpy as np
 import websocket
 
-from PhyAgentOS.runtime.policy.base_client import BasePolicyClient
-from PhyAgentOS.runtime.policy.msgpack_numpy import packb, unpackb
-from PhyAgentOS.runtime.watchdog.errors import (
+from PhyAgentOS.runtime.errors import (
     PolicyConnectionError,
     PolicyProtocolError,
     PolicyTimeoutError,
 )
+from PhyAgentOS.runtime.policy.base_client import BasePolicyClient
+from PhyAgentOS.runtime.policy.msgpack_numpy import packb, unpackb
 
 
 class OpenPIClientPolicyWrapper(BasePolicyClient):