debug-control-plane 0.1.0__tar.gz → 0.3.0__tar.gz

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.1.0
+Version: 0.3.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -9,10 +9,12 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp<2,>=1.28
 Requires-Dist: httpx>=0.28
+Requires-Dist: anyio<5,>=4
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Requires-Dist: pytest-cov>=4; extra == "test"
 Requires-Dist: ruff>=0.4; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Dynamic: license-file
 
 # debug-control-plane (Python)
@@ -29,7 +31,7 @@ Provides / 提供：
 ## Dependency direction / 依赖方向
 
 ```
-business app (pantas_launcher / future products)   业务应用（pantas_launcher / 未来产品）
+business apps   业务应用
         │  depends on (downward)                     依赖（向下）
         ▼
 debug_control_plane (this package)                        本包
@@ -38,8 +40,8 @@ debug_control_plane (this package)                        本包
   mcp (SDK) · httpx (HTTP client)
 ```
 
-This package is **pure infrastructure**: it MUST NOT import any business package (`pantas_launcher`, `host4_flutter_gmacro`, gamepad/feature code). Business apps depend on this package; never the reverse.
-本包是**纯基础设施**：绝不 import 任何业务包（`pantas_launcher`、`host4_flutter_gmacro`、手柄/特性代码）。业务应用依赖本包，反之禁止。
+This package is **pure infrastructure**: it MUST NOT import any business package. Business apps depend on this package; never the reverse.
+本包是**纯基础设施**：绝不 import 任何业务包。业务应用依赖本包，反之禁止。
 
 ## Install / 安装
 
@@ -60,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.1.0"
+    ├── __init__.py                 # __version__ = "0.3.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -90,7 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.1.0` — initial release, API unstable. 首发，API 不稳定。
+`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
+`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/README.md

@@ -12,7 +12,7 @@ Provides / 提供：
 ## Dependency direction / 依赖方向
 
 ```
-business app (pantas_launcher / future products)   业务应用（pantas_launcher / 未来产品）
+business apps   业务应用
         │  depends on (downward)                     依赖（向下）
         ▼
 debug_control_plane (this package)                        本包
@@ -21,8 +21,8 @@ debug_control_plane (this package)                        本包
   mcp (SDK) · httpx (HTTP client)
 ```
 
-This package is **pure infrastructure**: it MUST NOT import any business package (`pantas_launcher`, `host4_flutter_gmacro`, gamepad/feature code). Business apps depend on this package; never the reverse.
-本包是**纯基础设施**：绝不 import 任何业务包（`pantas_launcher`、`host4_flutter_gmacro`、手柄/特性代码）。业务应用依赖本包，反之禁止。
+This package is **pure infrastructure**: it MUST NOT import any business package. Business apps depend on this package; never the reverse.
+本包是**纯基础设施**：绝不 import 任何业务包。业务应用依赖本包，反之禁止。
 
 ## Install / 安装
 
@@ -43,7 +43,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.1.0"
+    ├── __init__.py                 # __version__ = "0.3.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -73,7 +73,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.1.0` — initial release, API unstable. 首发，API 不稳定。
+`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
+`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/__init__.py

@@ -1,7 +1,7 @@
 """debug_control_plane — multi-product debug control plane.
 
 Reusable across products: device discovery (USB/WiFi/identity) + MCP adapter
-(debug HTTP protocol → MCP tool surface). Extracted from pantas_launcher R019/
-R020 (S2 Python slice, R021-BF004).
+(debug HTTP protocol → MCP tool surface). Extracted from an internal app
+(R019/R020, S2 Python slice, R021-BF004).
 """
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/device_discovery/__init__.py

@@ -1,15 +1,13 @@
 """device_discovery — 设备发现平面 (网络 DTO + 设备池 + 发现逻辑).
 
-BF006 迁入 (R021):
-  - network 3 模块 (protocol / endpoint / device_candidates, 字节级零修改,
-    自旧 network 子包)
+模块职责:
+  - protocol / endpoint / device_candidates: 网络 DTO 与探测
   - device_pool (认身份不认地址)
   - discovery/ 5 模块 (USB / LAN / 手动 / 交叉识别)
-  - AD-B9: DeviceUnreachable 下沉 (直继承 Exception 脱离协议层基类反向依赖;
-    BF007 删旧定义 + 改正向 import)
+  - DeviceUnreachable 定义于 protocol (网络平面异常, 直继承 Exception)
 
-零业务依赖: 不 import 旧 network 子包 / host4 gmacro / launcher /
-协议层 client / mcp plane. 纯 stdlib + 同包相对 import, 可独立 pip install.
+零业务依赖: 不 import 任何业务包.
+纯 stdlib + 同包相对 import, 可独立 pip install.
 """
 from .device_candidates import (
     CommandRunner,

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/device_discovery/device_candidates.py

@@ -215,7 +215,7 @@ def _run_command(command: list[str], timeout: float) -> str:
 # ---------------------------------------------------------------------------
 
 
-# macOS 上 flutter 不在默认 PATH,显式回退路径(防止 mcp_debug_bridge 进程环境没装 fvm)
+# macOS 上 flutter 不在默认 PATH,显式回退路径(防止子进程环境没装 fvm)
 _FLUTTER_CANDIDATES: tuple[str, ...] = (
     "flutter",
     "/usr/local/bin/flutter",
@@ -228,7 +228,7 @@ _FLUTTER_CANDIDATES: tuple[str, ...] = (
 class IosDeviceCandidate:
     """iOS 设备身份候选(来自 `flutter devices` 解析)。
 
-    供 R020 mcp_debug_bridge/discovery USB 身份源消费(BF004 UsbCandidate 用此)。
+    供 USB 身份源消费(BF004 UsbCandidate 用此)。
     `device_id` = usbmuxd id(如 3992f440...,稳定身份源);
     `model` = 机型显示名(iPhone X / iPhone 14 Pro 等,弱唯一供交叉识别用)。
     """

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/device_discovery/discovery/manual_registry.py

@@ -43,7 +43,7 @@ from typing import TYPE_CHECKING
 from ..device_pool import DevicePool, DeviceRecord, manual_device_id
 from ..endpoint import Endpoint, UrlOpen, default_urlopen, probe_hello
 
-# AD-B9: DeviceUnreachable 自 mcp_debug_bridge/bridge_client 下沉至 device_discovery/protocol.
+# AD-B9: DeviceUnreachable 定义于 device_discovery/protocol.
 from ..protocol import DeviceUnreachable
 
 if TYPE_CHECKING:  # pragma: no cover - typing only

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/device_discovery/endpoint.py

@@ -170,7 +170,7 @@ def _default_route_ipv4_addresses() -> set[str]:
 #
 # 新增独立函数,不改任何旧签名(旧 _default_route_ipv4_addresses/
 # local_ipv4_addresses/discover_default_endpoints 保持原状供 GUI 复用)。
-# 供 R020 mcp_debug_bridge/discovery 经 sys.path 复用。
+# 供经 sys.path 复用。
 # 设计见 .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-backend.md §5.4
 # ---------------------------------------------------------------------------
 

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/device_discovery/protocol.py

@@ -82,7 +82,7 @@ class NetworkTarget:
     events_endpoint: str = "/events"
     # --- R020 FF001/FF002 bridge fields (optional, backward compatible) ---
     # Older /hello responses omit these; they default to None so existing GUI
-    # / R019 contract behavior is unchanged. Consumed by mcp_debug_bridge
+    # / R019 contract behavior is unchanged. Consumed by the MCP plane
     # BF005 LanCandidate / BF006 cross_identify for device disambiguation.
     hardware_name: str | None = None
     machine_id: str | None = None
@@ -221,10 +221,10 @@ class ControllerProfile:
 # ---------------------------------------------------------------------------
 # AD-B9: DeviceUnreachable 下沉 (device_discovery 网络平面异常)
 # ---------------------------------------------------------------------------
-#: BF006 自 ``mcp_debug_bridge/bridge_client.py:99`` 下沉至此。原继承 ``BridgeError``
-#: (MCP 协议层基类),下沉后直继承 ``Exception`` 脱离 mcp_plane 反向依赖 —— 本属
-#: 网络平面异常 (设备不可达/设备池未识别 device_id)。BF007 删 ``bridge_client.py:99``
-#: 旧定义 + 改 ``from debug_control_plane.device_discovery.protocol import DeviceUnreachable``
-#: 正向 import;BF006 后双定义中间态 (不同类/不同基类/不同模块路径) 语义不冲突。
+#: AD-B9: 网络平面异常 (设备不可达/设备池未识别 device_id)。直继承 ``Exception``,
+#: 不继承 MCP 协议层 ``BridgeError`` 基类 —— 避免网络层反向依赖 mcp_plane。
+#: BF006 + BF007 后, ``bridge_client.py`` 改为
+#: ``from debug_control_plane.device_discovery.protocol import DeviceUnreachable``
+#: 正向 import (单一真源)。
 class DeviceUnreachable(Exception):
     """The device_id is unknown to the pool (连手机失败, 网络平面异常)."""

debug_control_plane-0.3.0/debug_control_plane/mcp_plane/__init__.py

@@ -0,0 +1,44 @@
+"""mcp_plane — MCP 适配平面(server/bridge_client/capability_mirror).
+
+模块职责:
+  - server.py: MCP stdio server, R019 8 端点 handler
+  - bridge_client.py: HTTP + SSE 客户端
+  - capability_mirror.py: Capability 镜像 (动态 tools)
+  - semantic_provider.py: BF002 SemanticProvider Protocol (字符串前向引用)
+
+零业务依赖: 不 import 任何业务包(留业务).
+mcp_plane → device_discovery 单向正向依赖.
+"""
+from .bridge_client import (
+    BridgeClient,
+    BridgeError,
+    DeviceHttpError,
+    DeviceStale,
+)
+from .capability_mirror import (
+    CapabilityMirror,
+    CapabilitySchema,
+    CommandDecl,
+    ResourceDecl,
+    ToolSpec,
+)
+from .semantic_provider import SemanticProvider
+from .server import McpServer
+
+__all__ = [
+    # bridge_client
+    "BridgeClient",
+    "BridgeError",
+    "DeviceHttpError",
+    "DeviceStale",
+    # capability_mirror
+    "CapabilityMirror",
+    "CapabilitySchema",
+    "CommandDecl",
+    "ResourceDecl",
+    "ToolSpec",
+    # semantic_provider (BF002)
+    "SemanticProvider",
+    # server
+    "McpServer",
+]

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/mcp_plane/bridge_client.py

@@ -54,8 +54,8 @@ Refs:
 
 from __future__ import annotations
 
-from collections.abc import Iterator
-from typing import TYPE_CHECKING, Any
+from collections.abc import Iterator, Mapping
+from typing import TYPE_CHECKING, Any, Protocol
 
 import httpx
 
@@ -138,6 +138,30 @@ class DeviceHttpError(BridgeError):
         super().__init__(f"{prefix}{detail}")
 
 
+class DeviceAuthError(DeviceHttpError):
+    """The phone returned a stable debug auth failure code."""
+
+    def __init__(self, status_code: int, body: Any, code: str, message: str = "") -> None:
+        self.code = code
+        super().__init__(status_code, body, message or f" auth_code={code}")
+
+
+class DebugAuthTokenProvider(Protocol):
+    """Per-device debug auth token provider.
+
+    Implementations own storage. DevicePool remains identity-only and must not
+    be used to persist bearer tokens.
+    """
+
+    def get_token(self, device_id: str) -> str | None: ...
+
+    def save_token(
+        self, device_id: str, token: str, metadata: Mapping[str, Any]
+    ) -> None: ...
+
+    def clear_token(self, device_id: str, reason: str) -> None: ...
+
+
 # ---------------------------------------------------------------------------
 # Service
 # ---------------------------------------------------------------------------
@@ -181,6 +205,7 @@ class BridgeClient:
         client: httpx.Client | None = None,
         request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
         stream_timeout: float = DEFAULT_STREAM_TIMEOUT,
+        token_provider: DebugAuthTokenProvider | None = None,
     ) -> None:
         self._pool = pool
         self._port = port
@@ -192,6 +217,7 @@ class BridgeClient:
             self._owns_client = True
         self._request_timeout = request_timeout
         self._stream_timeout = stream_timeout
+        self._token_provider = token_provider
 
     # ------------------------------------------------------------------
     # Lifecycle
@@ -282,17 +308,18 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, path)
+        headers = self._auth_headers(device_id)
         try:
             if isinstance(body, (dict, list)):
-                resp = self._client.request(method, url, json=body)
+                resp = self._client.request(method, url, json=body, headers=headers)
             else:
-                resp = self._client.request(method, url, content=body)
+                resp = self._client.request(method, url, content=body, headers=headers)
         except httpx.HTTPError as exc:
             # Connect refused / DNS / timeout / etc — surface as transport
             # failure so the caller catches a single exception type.
             raise DeviceHttpError(0, None, f"transport: {exc!s}") from exc
         if resp.status_code >= 400:
-            raise DeviceHttpError(resp.status_code, _safe_body(resp))
+            raise self._http_error(device_id, resp)
         return _safe_body(resp)
 
     def read(self, device_id: str, path: list[str]) -> Any:
@@ -317,12 +344,13 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, ["hello"])
+        headers = self._auth_headers(device_id)
         try:
-            resp = self._client.get(url)
+            resp = self._client.get(url, headers=headers)
         except httpx.HTTPError as exc:
             raise DeviceHttpError(0, None, f"transport: {exc!s}") from exc
         if resp.status_code != 200:
-            raise DeviceHttpError(resp.status_code, _safe_body(resp))
+            raise self._http_error(device_id, resp)
         data = resp.json()
         if not isinstance(data, dict):
             raise DeviceHttpError(
@@ -370,13 +398,16 @@ class BridgeClient:
         """
         host = self.resolve(device_id)
         url = self._build_url(host, ["events"])
+        headers = self._auth_headers(device_id)
         type_set = set(event_types) if event_types else None
         try:
-            with self._client.stream("GET", url, timeout=self._stream_timeout) as resp:
+            with self._client.stream(
+                "GET", url, headers=headers, timeout=self._stream_timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     # Read the body so the caller sees the error payload.
                     resp.read()
-                    raise DeviceHttpError(resp.status_code, _safe_body(resp))
+                    raise self._http_error(device_id, resp)
                 for raw_data, _event_field in _iter_sse(resp):
                     try:
                         payload = _parse_json_object(raw_data)
@@ -392,10 +423,75 @@ class BridgeClient:
         except httpx.HTTPError as exc:
             raise DeviceHttpError(0, None, f"transport: {exc!s}") from exc
 
+    def auth_request(
+        self,
+        device_id: str,
+        client_nonce: str,
+        *,
+        client_label: str | None = None,
+        requested_method: str | None = None,
+        requested_path: str | None = None,
+    ) -> Any:
+        """Create a pending App-side authorization request."""
+        body: dict[str, Any] = {"clientNonce": client_nonce}
+        if client_label is not None:
+            body["clientLabel"] = client_label
+        if requested_method is not None:
+            body["requestedMethod"] = requested_method
+        if requested_path is not None:
+            body["requestedPath"] = requested_path
+        return self.invoke(device_id, "POST", ["auth", "request"], body)
+
+    def auth_status(self, device_id: str, request_id: str, client_nonce: str) -> Any:
+        """Poll App-side authorization status."""
+        return self.invoke(
+            device_id,
+            "POST",
+            ["auth", "status"],
+            {"requestId": request_id, "clientNonce": client_nonce},
+        )
+
+    def auth_claim(self, device_id: str, request_id: str, client_nonce: str) -> Any:
+        """Claim an approved App-side authorization token and save it if present."""
+        body = self.invoke(
+            device_id,
+            "POST",
+            ["auth", "claim"],
+            {"requestId": request_id, "clientNonce": client_nonce},
+        )
+        if isinstance(body, dict):
+            token = body.get("token")
+            if isinstance(token, str) and self._token_provider is not None:
+                metadata = {
+                    key: body[key]
+                    for key in ("tokenId", "expiresAt")
+                    if key in body
+                }
+                self._token_provider.save_token(device_id, token, metadata)
+        return body
+
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
 
+    def _auth_headers(self, device_id: str) -> dict[str, str]:
+        provider = self._token_provider
+        if provider is None:
+            return {}
+        token = provider.get_token(device_id)
+        if not token:
+            return {}
+        return {"Authorization": f"Bearer {token}"}
+
+    def _http_error(self, device_id: str, resp: httpx.Response) -> DeviceHttpError:
+        body = _safe_body(resp)
+        code = _auth_error_code(resp.status_code, body)
+        if code is None:
+            return DeviceHttpError(resp.status_code, body)
+        if code in _CLEAR_TOKEN_AUTH_CODES and self._token_provider is not None:
+            self._token_provider.clear_token(device_id, reason=code)
+        return DeviceAuthError(resp.status_code, body, code=code)
+
     def _build_url(self, host: str, path: list[str]) -> str:
         """Assemble ``http://{host}:{port}/{seg1}/{seg2}...``.
 
@@ -512,12 +608,43 @@ def _parse_json_object(raw: str) -> dict[str, Any]:
     return parsed
 
 
+def _auth_error_code(status_code: int, body: Any) -> str | None:
+    if status_code not in (401, 403) or not isinstance(body, dict):
+        return None
+    code = body.get("code")
+    if isinstance(code, str) and code in _AUTH_ERROR_CODES:
+        return code
+    return None
+
+
+_AUTH_ERROR_CODES = frozenset(
+    {
+        "authorization_required",
+        "invalid_token",
+        "token_expired",
+        "token_revoked",
+        "authorization_denied",
+        "forbidden",
+    }
+)
+
+_CLEAR_TOKEN_AUTH_CODES = frozenset(
+    {
+        "invalid_token",
+        "token_expired",
+        "token_revoked",
+    }
+)
+
+
 __all__ = [
     "DEFAULT_PORT",
     "DEFAULT_REQUEST_TIMEOUT",
     "DEFAULT_STREAM_TIMEOUT",
     "BridgeClient",
     "BridgeError",
+    "DebugAuthTokenProvider",
+    "DeviceAuthError",
     "DeviceHttpError",
     "DeviceStale",
     # AD-B9: DeviceUnreachable 已下沉 device_discovery.protocol,

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/mcp_plane/capability_mirror.py

@@ -78,6 +78,7 @@ from debug_control_plane.device_discovery.protocol import JsonMap, NetworkTarget
 from .bridge_client import (
     BridgeClient,
     BridgeError,
+    DeviceAuthError,
     DeviceHttpError,
     DeviceStale,
     DeviceUnreachable,
@@ -397,6 +398,12 @@ class CapabilityMirror:
         # (design §4.1 note: capability schema is CapabilityMirror's runtime
         # mirror, NOT a DeviceRecord field).
         self._cache: dict[str, list[CapabilitySchema]] = {}
+        # R001-BB001: per-device last auth error (DeviceAuthError). Auth
+        # failure ≠ offline — the schema cache is preserved and the signal is
+        # queryable via auth_error() instead of silently degrading. Cleared on
+        # the next successful refresh. GIL-guarded dict ops suffice (contract
+        # risk note).
+        self._auth_errors: dict[str, DeviceAuthError] = {}
 
     # ------------------------------------------------------------------
     # Provider registry (BF010 registration hook)
@@ -430,19 +437,31 @@ class CapabilityMirror:
             True iff the parsed schema differs from the cached snapshot
             (including "no cache → cache populated", which IS a change).
             False if /hello failed (cache cleared) or the schema is identical.
+            Auth errors (R001-BB001): cache is PRESERVED and False returned —
+            the phone is reachable, just unauthorized; see :meth:`auth_error`.
         """
         try:
             target = self._client.hello(device_id)
+        except DeviceAuthError as exc:
+            # R001-BB001: auth error ≠ offline. Preserve the schema cache
+            # (capabilities remain valid once authorized), record the auth
+            # failure for auth_error() queries, return False (no spurious
+            # list_changed). refresh stays poll-safe (never raises).
+            self._auth_errors[device_id] = exc
+            return False
         except (DeviceUnreachable, DeviceStale, DeviceHttpError, BridgeError):
-            # Any /hello failure → degrade. Clear cache so build_tools falls
-            # to static-only and a later successful refresh re-signals the
-            # transition back. We do NOT report a change here: list_changed
-            # signals "the manifest grew/shrank", and going from "had tools"
-            # to "static only" is a real change — but only if we actually had
-            # a non-empty manifest before. Reporting False on a cache→empty
-            # transition would be a lie, so we surface it honestly.
+            # Any non-auth /hello failure → degrade. Clear cache (and any
+            # stale auth state — an unreachable phone has no auth verdict)
+            # so build_tools falls to static-only and a later successful
+            # refresh re-signals the transition back. We do NOT report a
+            # change here: list_changed signals "the manifest grew/shrank",
+            # and going from "had tools" to "static only" is a real change —
+            # but only if we actually had a non-empty manifest before.
+            # Reporting False on a cache→empty transition would be a lie, so
+            # we surface it honestly.
             had_cache = device_id in self._cache
             self._cache.pop(device_id, None)
+            self._auth_errors.pop(device_id, None)
             # Transition from "had dynamic tools" to "static only" IS a change
             # the AI client needs to know about (its cached tools are stale).
             return had_cache
@@ -452,8 +471,20 @@ class CapabilityMirror:
         changed = old_schemas != new_schemas
         if changed:
             self._cache[device_id] = new_schemas
+        # Successful /hello means the device is authorized again.
+        self._auth_errors.pop(device_id, None)
         return changed
 
+    def auth_error(self, device_id: str) -> DeviceAuthError | None:
+        """Return the last :class:`DeviceAuthError` seen for ``device_id``.
+
+        R001-BB001: lets callers (h_list_capabilities) distinguish "auth
+        failed" from "offline degrade" without refresh raising. ``None`` when
+        the device is healthy or the last failure was non-auth (offline /
+        stale / HTTP). Cleared by the next successful refresh.
+        """
+        return self._auth_errors.get(device_id)
+
     # ------------------------------------------------------------------
     # Cache access (no I/O)
     # ------------------------------------------------------------------

{debug_control_plane-0.1.0 → debug_control_plane-0.3.0}/debug_control_plane/mcp_plane/semantic_provider.py

@@ -1,6 +1,6 @@
 """SemanticProvider — pluggable hook for known-capability sugar (BF002).
 
-固化自 R020 ``pantas_launcher/tools/mcp_debug_bridge/capability_mirror.py:177``。
+R020 capability_mirror 语义糖接口固化。
 本轮(R021-BF002)将 R020 既有 Protocol 抽出固化到独立 repo,作为契约源头迁移
 (非新设计 — R020 BF010 hook 已落地代码)。
 
@@ -26,10 +26,9 @@ if TYPE_CHECKING:
 class SemanticProvider(Protocol):
     """Builds semantic-sugar tools for a known capability.
 
-    BF010 (gamepad) implements this protocol and registers its instance on
-    :class:`CapabilityMirror` via the ``providers`` constructor arg. BF009
-    ships no built-in provider — the hook itself is exercised by a stub in
-    BF009's own tests.
+    业务侧(BF010)实现此协议，并通过 ``providers`` 构造参数把实例注册到
+    :class:`CapabilityMirror`。BF009 不内置 provider —— 钩子本身由 BF009 自己
+    的测试用 stub 验证。
 
     Contract:
         * :meth:`matches` is called once per parsed schema; return ``True`` if