Class CanvasError

python/copilot/canvas.py:107–139

Structured error returned from canvas handlers. .. note:: **Experimental.** This type is part of an experimental wire-protocol surface and may change or be removed in future SDK or CLI releases.

class CanvasError(Exception):
    """Structured error returned from canvas handlers.

    .. note::

        **Experimental.** This type is part of an experimental wire-protocol
        surface and may change or be removed in future SDK or CLI releases.
    """

    def __init__(self, code: str, message: str) -> None:
        self.code = code
        self.message = message
        super().__init__(f"{code}: {message}")

    def to_envelope(self) -> dict[str, str]:
        return {"code": self.code, "message": self.message}

    @classmethod
    def no_handler(cls) -> CanvasError:
        """Default error returned when a custom action has no handler."""
        return cls(
            "canvas_action_no_handler",
            "No handler implemented for this canvas action",
        )

    @classmethod
    def handler_unset(cls) -> CanvasError:
        """Error returned when a canvas RPC arrives but no handler is installed."""
        return cls(
            "canvas_handler_unset",
            "No CanvasHandler installed on this session; "
            "install one via SessionConfig.canvas_handler before creating the session.",
        )


class CanvasHandler(ABC):