errors

Typed integration error model and classification helpers.

This package provides boundary-aware exceptions for side-effect adapters and a small classifier used to distinguish expected task-level failures from internal/system integration failures.

IntegrationBoundary

Bases: str, Enum

External boundary where an integration failure originated.

Attributes:

Name	Type	Description
WORKSPACE		Workspace provisioning/cleanup operations.
SIGNAL		Instruction/signal publication or completion polling.
PULL_REQUEST		Pull-request create/merge/status operations.
AGENT_LAUNCH		Agent process launch or kickoff behavior.

Source code in src/agentrelay/errors/__init__.py

class IntegrationBoundary(str, Enum):
    """External boundary where an integration failure originated.

    Attributes:
        WORKSPACE: Workspace provisioning/cleanup operations.
        SIGNAL: Instruction/signal publication or completion polling.
        PULL_REQUEST: Pull-request create/merge/status operations.
        AGENT_LAUNCH: Agent process launch or kickoff behavior.
    """

    WORKSPACE = "workspace"
    SIGNAL = "signal"
    PULL_REQUEST = "pull_request"
    AGENT_LAUNCH = "agent_launch"

IntegrationFailureClass

Bases: str, Enum

Classification used for orchestration policy decisions.

Attributes:

Name	Type	Description
EXPECTED_TASK_FAILURE		Expected task-level failure (retry policy may apply).
INTERNAL_ERROR		Internal/system failure (usually fail-fast).

Source code in src/agentrelay/errors/__init__.py

class IntegrationFailureClass(str, Enum):
    """Classification used for orchestration policy decisions.

    Attributes:
        EXPECTED_TASK_FAILURE: Expected task-level failure (retry policy may apply).
        INTERNAL_ERROR: Internal/system failure (usually fail-fast).
    """

    EXPECTED_TASK_FAILURE = "expected_task_failure"
    INTERNAL_ERROR = "internal_error"

IntegrationError

Bases: Exception

Base integration error carrying boundary and failure classification.

Use raise IntegrationError(...) from original_exc to chain the underlying cause (accessible via __cause__).

Attributes:

Name	Type	Description
boundary		Integration boundary where failure originated.
failure_class		Classification used by orchestration policy.

Source code in src/agentrelay/errors/__init__.py

class IntegrationError(Exception):
    """Base integration error carrying boundary and failure classification.

    Use ``raise IntegrationError(...) from original_exc`` to chain the
    underlying cause (accessible via ``__cause__``).

    Attributes:
        boundary: Integration boundary where failure originated.
        failure_class: Classification used by orchestration policy.
    """

    def __init__(
        self,
        message: str,
        *,
        boundary: IntegrationBoundary,
        failure_class: IntegrationFailureClass,
    ) -> None:
        """Initialize a boundary-aware integration error.

        Args:
            message: Human-readable error message.
            boundary: Boundary where the failure originated.
            failure_class: Classification for orchestration policy.
        """
        super().__init__(message)
        self.boundary = boundary
        self.failure_class = failure_class

__init__(message, *, boundary, failure_class)

Initialize a boundary-aware integration error.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error message.	required
boundary	IntegrationBoundary	Boundary where the failure originated.	required
failure_class	IntegrationFailureClass	Classification for orchestration policy.	required

Source code in src/agentrelay/errors/__init__.py

def __init__(
    self,
    message: str,
    *,
    boundary: IntegrationBoundary,
    failure_class: IntegrationFailureClass,
) -> None:
    """Initialize a boundary-aware integration error.

    Args:
        message: Human-readable error message.
        boundary: Boundary where the failure originated.
        failure_class: Classification for orchestration policy.
    """
    super().__init__(message)
    self.boundary = boundary
    self.failure_class = failure_class

ExpectedTaskFailureError

Bases: IntegrationError

Expected task-level failure from an integration boundary.

Source code in src/agentrelay/errors/__init__.py

class ExpectedTaskFailureError(IntegrationError):
    """Expected task-level failure from an integration boundary."""

    def __init__(
        self,
        message: str,
        *,
        boundary: IntegrationBoundary,
    ) -> None:
        """Initialize an expected task-level failure.

        Args:
            message: Human-readable error message.
            boundary: Boundary where the failure originated.
        """
        super().__init__(
            message,
            boundary=boundary,
            failure_class=IntegrationFailureClass.EXPECTED_TASK_FAILURE,
        )

__init__(message, *, boundary)

Initialize an expected task-level failure.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error message.	required
boundary	IntegrationBoundary	Boundary where the failure originated.	required

Source code in src/agentrelay/errors/__init__.py

def __init__(
    self,
    message: str,
    *,
    boundary: IntegrationBoundary,
) -> None:
    """Initialize an expected task-level failure.

    Args:
        message: Human-readable error message.
        boundary: Boundary where the failure originated.
    """
    super().__init__(
        message,
        boundary=boundary,
        failure_class=IntegrationFailureClass.EXPECTED_TASK_FAILURE,
    )

InternalIntegrationError

Bases: IntegrationError

Internal/system integration failure from an external boundary.

Source code in src/agentrelay/errors/__init__.py

class InternalIntegrationError(IntegrationError):
    """Internal/system integration failure from an external boundary."""

    def __init__(
        self,
        message: str,
        *,
        boundary: IntegrationBoundary,
    ) -> None:
        """Initialize an internal/system integration failure.

        Args:
            message: Human-readable error message.
            boundary: Boundary where the failure originated.
        """
        super().__init__(
            message,
            boundary=boundary,
            failure_class=IntegrationFailureClass.INTERNAL_ERROR,
        )

__init__(message, *, boundary)

Initialize an internal/system integration failure.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error message.	required
boundary	IntegrationBoundary	Boundary where the failure originated.	required

Source code in src/agentrelay/errors/__init__.py

def __init__(
    self,
    message: str,
    *,
    boundary: IntegrationBoundary,
) -> None:
    """Initialize an internal/system integration failure.

    Args:
        message: Human-readable error message.
        boundary: Boundary where the failure originated.
    """
    super().__init__(
        message,
        boundary=boundary,
        failure_class=IntegrationFailureClass.INTERNAL_ERROR,
    )

classify_integration_error(exc)

Classify an exception for orchestration retry/fail-fast policy.

Parameters:

Name	Type	Description	Default
exc	BaseException	Exception raised by integration code.	required

Returns:

Name	Type	Description
IntegrationFailureClass	IntegrationFailureClass	Expected task failure or internal error. Non-IntegrationError exceptions default to INTERNAL_ERROR.

Source code in src/agentrelay/errors/__init__.py

def classify_integration_error(exc: BaseException) -> IntegrationFailureClass:
    """Classify an exception for orchestration retry/fail-fast policy.

    Args:
        exc: Exception raised by integration code.

    Returns:
        IntegrationFailureClass: Expected task failure or internal error.
            Non-``IntegrationError`` exceptions default to ``INTERNAL_ERROR``.
    """
    if isinstance(exc, IntegrationError):
        return exc.failure_class
    return IntegrationFailureClass.INTERNAL_ERROR