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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.3.0
+Version: 0.4.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -62,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.3.0"
+    ├── __init__.py                 # __version__ = "0.4.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -92,8 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
-`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
+`0.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
+`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

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

@@ -43,7 +43,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.3.0"
+    ├── __init__.py                 # __version__ = "0.4.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -73,8 +73,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
-`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
+`0.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
+`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

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

@@ -4,4 +4,4 @@ Reusable across products: device discovery (USB/WiFi/identity) + MCP adapter
 (debug HTTP protocol → MCP tool surface). Extracted from an internal app
 (R019/R020, S2 Python slice, R021-BF004).
 """
-__version__ = "0.3.0"
+__version__ = "0.4.0"

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

@@ -279,6 +279,11 @@ class BridgeClient:
         method: str,
         path: list[str],
         body: Any = None,
+        *,
+        capability_id: str | None = None,
+        scope: str | None = None,
+        page_id: str | None = None,
+        scope_revision: int | None = None,
     ) -> Any:
         """Forward ``method path body`` to the phone (byte-level pass-through).
 
@@ -295,6 +300,9 @@ class BridgeClient:
             body: request body. If it's a dict/list it's sent as JSON
                 (``json=``); otherwise it's sent raw (``content=``) and may
                 be ``None``.
+            capability_id/scope/page_id/scope_revision: optional R003
+                selector metadata forwarded as ``X-DCP-*`` headers. Omitted
+                values keep the legacy flat dispatch behavior.
 
         Returns:
             The phone's response body, parsed: dict/list for JSON, ``str``
@@ -309,6 +317,14 @@ class BridgeClient:
         host = self.resolve(device_id)
         url = self._build_url(host, path)
         headers = self._auth_headers(device_id)
+        headers.update(
+            selector_headers(
+                capability_id=capability_id,
+                scope=scope,
+                page_id=page_id,
+                scope_revision=scope_revision,
+            )
+        )
         try:
             if isinstance(body, (dict, list)):
                 resp = self._client.request(method, url, json=body, headers=headers)
@@ -322,13 +338,31 @@ class BridgeClient:
             raise self._http_error(device_id, resp)
         return _safe_body(resp)
 
-    def read(self, device_id: str, path: list[str]) -> Any:
+    def read(
+        self,
+        device_id: str,
+        path: list[str],
+        *,
+        capability_id: str | None = None,
+        scope: str | None = None,
+        page_id: str | None = None,
+        scope_revision: int | None = None,
+    ) -> Any:
         """GET convenience for ``read_resource`` / ``get_state``.
 
         Equivalent to ``invoke(device_id, "GET", path, None)`` but signals
         intent at the call site. Returns the parsed phone body.
         """
-        return self.invoke(device_id, "GET", path, None)
+        return self.invoke(
+            device_id,
+            "GET",
+            path,
+            None,
+            capability_id=capability_id,
+            scope=scope,
+            page_id=page_id,
+            scope_revision=scope_revision,
+        )
 
     def hello(self, device_id: str) -> NetworkTarget:
         """Fetch ``/hello`` and parse to a typed :class:`NetworkTarget`.
@@ -530,6 +564,26 @@ def _safe_body(resp: httpx.Response) -> Any:
         return resp.text
 
 
+def selector_headers(
+    *,
+    capability_id: str | None = None,
+    scope: str | None = None,
+    page_id: str | None = None,
+    scope_revision: int | None = None,
+) -> dict[str, str]:
+    """Build optional R003 selector headers for capability-scoped dispatch."""
+    headers: dict[str, str] = {}
+    if isinstance(capability_id, str) and capability_id:
+        headers["X-DCP-Capability-Id"] = capability_id
+    if scope in ("app", "page"):
+        headers["X-DCP-Capability-Scope"] = scope
+    if isinstance(page_id, str) and page_id:
+        headers["X-DCP-Page-Id"] = page_id
+    if isinstance(scope_revision, int) and not isinstance(scope_revision, bool):
+        headers["X-DCP-Scope-Revision"] = str(scope_revision)
+    return headers
+
+
 def _quote_segment(seg: str) -> str:
     """URL-encode a single path segment (preserving ``/`` within a segment).
 
@@ -647,6 +701,7 @@ __all__ = [
     "DeviceAuthError",
     "DeviceHttpError",
     "DeviceStale",
+    "selector_headers",
     # AD-B9: DeviceUnreachable 已下沉 device_discovery.protocol,
     # 本模块 forward import(BF007),不 re-export。
 ]

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

@@ -129,12 +129,21 @@ class CapabilitySchema:
         resources: declared REST resources (read side).
         commands: declared commands (write side).
         description: optional capability-level description (may be absent).
+        scope: ``app`` or ``page``; missing/malformed wire values downgrade
+            locally to ``app``.
+        page_id: optional business-provided page identity for page scope.
+        page_name: optional display metadata; never participates in tool names.
+        scope_revision: optional integer mirror revision for stale detection.
     """
 
     capability_id: str
     resources: tuple[ResourceDecl, ...] = ()
     commands: tuple[CommandDecl, ...] = ()
     description: str | None = None
+    scope: str = "app"
+    page_id: str | None = None
+    page_name: str | None = None
+    scope_revision: int | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -249,6 +258,19 @@ _STATIC_META_TOOLS: tuple[ToolSpec, ...] = (
                     "description": "Request body (object) or null.",
                     "additionalProperties": True,
                 },
+                "scope": {
+                    "type": "string",
+                    "enum": ["app", "page"],
+                    "description": "Optional capability scope selector.",
+                },
+                "page_id": {
+                    "type": "string",
+                    "description": "Optional page id selector for page scope.",
+                },
+                "scope_revision": {
+                    "type": "integer",
+                    "description": "Optional scope revision selector.",
+                },
             },
             "required": ["device_id", "capability_id", "command_path"],
             "additionalProperties": False,
@@ -274,6 +296,19 @@ _STATIC_META_TOOLS: tuple[ToolSpec, ...] = (
                     "type": ["object", "null"],
                     "additionalProperties": True,
                 },
+                "scope": {
+                    "type": "string",
+                    "enum": ["app", "page"],
+                    "description": "Optional capability scope selector.",
+                },
+                "page_id": {
+                    "type": "string",
+                    "description": "Optional page id selector for page scope.",
+                },
+                "scope_revision": {
+                    "type": "integer",
+                    "description": "Optional scope revision selector.",
+                },
             },
             "required": ["device_id", "capability_id", "resource_path"],
             "additionalProperties": False,
@@ -595,6 +630,10 @@ class CapabilityMirror:
                     resources=(),
                     commands=(),
                     description=None,
+                    scope="app",
+                    page_id=None,
+                    page_name=None,
+                    scope_revision=None,
                 )
                 for tag in target.capabilities
             ]
@@ -618,11 +657,19 @@ class CapabilityMirror:
         description = (
             description_raw if isinstance(description_raw, str) and description_raw else None
         )
+        scope = _parse_scope(cap.get("scope"))
+        page_id = _parse_optional_string(cap.get("pageId"))
+        page_name = _parse_optional_string(cap.get("pageName"))
+        scope_revision = _parse_scope_revision(cap.get("scopeRevision"))
         return CapabilitySchema(
             capability_id=cap_id,
             resources=resources,
             commands=commands,
             description=description,
+            scope=scope,
+            page_id=page_id,
+            page_name=page_name,
+            scope_revision=scope_revision,
         )
 
 
@@ -663,6 +710,23 @@ def _parse_decls(
     return tuple(out)  # type: ignore[return-value]
 
 
+def _parse_scope(raw: Any) -> str:
+    """Parse registeredCapabilities[].scope with legacy-safe downgrade."""
+    return raw if raw in ("app", "page") else "app"
+
+
+def _parse_optional_string(raw: Any) -> str | None:
+    """Return non-empty string metadata, otherwise local downgrade to None."""
+    return raw if isinstance(raw, str) and raw else None
+
+
+def _parse_scope_revision(raw: Any) -> int | None:
+    """Return real integer revisions only; bool/malformed values downgrade."""
+    if isinstance(raw, bool):
+        return None
+    return raw if isinstance(raw, int) else None
+
+
 __all__ = [
     "CapabilityMirror",
     "CapabilitySchema",

{debug_control_plane-0.3.0 → debug_control_plane-0.4.0}/debug_control_plane/mcp_plane/server.py

@@ -85,7 +85,7 @@ from .bridge_client import (
     DeviceStale,
     DeviceUnreachable,
 )
-from .capability_mirror import CapabilityMirror, ToolSpec
+from .capability_mirror import CapabilityMirror, CapabilitySchema, ToolSpec
 from .semantic_provider import SemanticProvider
 
 # ★ BF008-010 (Contract §0.1 边界 1 收尾 + 方案 X): capability-specific semantic
@@ -256,7 +256,7 @@ class McpServer:
         pool: DevicePool,
         *,
         server_name: str = "mcp-debug-bridge",
-        server_version: str = "0.3.0",
+        server_version: str = "0.4.0",
         providers: list[SemanticProvider] | None = None,
         tool_handlers: dict[str, Any] | None = None,
     ) -> None:
@@ -342,20 +342,25 @@ class McpServer:
             # method+path, so we forward command_path as the path and pass
             # the body verbatim. method defaults to POST (R19 commands are
             # all POST per the debug-capability declarations); a future
-            # schema field could override it. capability_id is reserved for
-            # routing/audit (the phone's path already encodes it) so it's
-            # validated for presence by the schema but not forwarded.
-            return await _run(
+            # schema field could override it. BF007 forwards capability_id
+            # plus optional scope fields as selector headers when provided.
+            selector = _selector_from_meta_args(args)
+            await self._ensure_page_selector_current(args["device_id"], selector)
+            return await self._run_meta_call(
                 client.invoke,
                 args["device_id"], "POST",
                 list(args.get("command_path", [])),
                 args.get("args"),
+                selector=selector,
             )
 
         async def h_read_resource(args):
-            return await _run(
+            selector = _selector_from_meta_args(args)
+            await self._ensure_page_selector_current(args["device_id"], selector)
+            return await self._run_meta_call(
                 client.read,
                 args["device_id"], list(args.get("resource_path", [])),
+                selector=selector,
             )
 
         async def h_list_capabilities(args):
@@ -572,6 +577,75 @@ class McpServer:
             "register_device": h_register_device,
         }
 
+    async def _ensure_page_selector_current(
+        self,
+        device_id: str,
+        selector: dict[str, Any],
+    ) -> None:
+        """Reject stale page-scoped meta calls before forwarding to the App."""
+        if selector.get("scope") != "page":
+            return
+
+        schemas = self._mirror.schemas(device_id)
+        if not schemas:
+            schemas = await self._refresh_selector_snapshot(device_id)
+
+        if _has_page_capability(schemas, selector):
+            return
+
+        raise McpError(types.ErrorData(
+            code=-32602,
+            message=(
+                "page capability stale: "
+                f"capability_id={selector['capability_id']!r} "
+                f"page_id={selector['page_id']!r}; "
+                "call list_capabilities/tools list and retry with a current selector"
+            ),
+        ))
+
+    async def _refresh_selector_snapshot(
+        self,
+        device_id: str,
+    ) -> list[CapabilitySchema]:
+        """Refresh an empty selector snapshot and surface auth distinctly."""
+        await anyio.to_thread.run_sync(lambda: self._mirror.refresh(device_id))
+        auth_err = self._mirror.auth_error(device_id)
+        if auth_err is not None:
+            raise _bridge_error_to_mcp(auth_err)
+        return self._mirror.schemas(device_id)
+
+    async def _run_meta_call(
+        self,
+        sync_fn,
+        device_id: str,
+        *args,
+        selector: dict[str, Any],
+    ):
+        """Run a meta dispatch and converge page stale App responses."""
+        try:
+            return await anyio.to_thread.run_sync(
+                lambda: sync_fn(device_id, *args, **selector)
+            )
+        except DeviceAuthError as exc:
+            raise _bridge_error_to_mcp(exc) from exc
+        except DeviceHttpError as exc:
+            if _is_page_scope_error(exc):
+                await self._refresh_after_page_scope_error(device_id)
+            raise _bridge_error_to_mcp(exc) from exc
+        except (BridgeError, DeviceUnreachable) as exc:
+            raise _bridge_error_to_mcp(exc) from exc
+
+    async def _refresh_after_page_scope_error(self, device_id: str) -> None:
+        """Best-effort manifest refresh after App says a page selector is stale."""
+        try:
+            changed = await anyio.to_thread.run_sync(
+                lambda: self._mirror.refresh(device_id)
+            )
+            if changed:
+                await self._emit_list_changed()
+        except Exception:  # noqa: BLE001
+            logger.debug("stale page capability refresh failed", exc_info=True)
+
     # ------------------------------------------------------------------
     # list_changed emission (§5.5 ②③; main path is ①, this is auxiliary)
     # ------------------------------------------------------------------
@@ -880,13 +954,80 @@ def _schemas_to_jsonable(schemas) -> list[dict[str, Any]]:
             "capability_id": sch.capability_id,
             "resources": [dataclasses.asdict(r) for r in sch.resources],
             "commands": [dataclasses.asdict(c) for c in sch.commands],
+            "scope": sch.scope,
         }
         if sch.description is not None:
             entry["description"] = sch.description
+        if sch.page_id is not None:
+            entry["pageId"] = sch.page_id
+        if sch.page_name is not None:
+            entry["pageName"] = sch.page_name
+        if sch.scope_revision is not None:
+            entry["scopeRevision"] = sch.scope_revision
         out.append(entry)
     return out
 
 
+def _selector_from_meta_args(args: dict[str, Any]) -> dict[str, Any]:
+    """Return BridgeClient selector kwargs from meta-tool arguments."""
+    if not any(key in args for key in ("scope", "page_id", "scope_revision")):
+        return {}
+
+    capability_id = args.get("capability_id")
+    if not isinstance(capability_id, str) or not capability_id:
+        raise ValueError("capability_id is required when selector is provided")
+
+    scope = args.get("scope")
+    if scope not in ("app", "page"):
+        raise ValueError("scope must be app or page")
+
+    page_id = args.get("page_id")
+    if page_id is not None and (not isinstance(page_id, str) or not page_id):
+        raise ValueError("page_id must be a non-empty string")
+    if scope == "page" and page_id is None:
+        raise ValueError("page_id is required when scope=page")
+    if scope != "page" and page_id is not None:
+        raise ValueError("page_id requires scope=page")
+
+    scope_revision = args.get("scope_revision")
+    if scope_revision is not None and (
+        not isinstance(scope_revision, int) or isinstance(scope_revision, bool)
+    ):
+        raise ValueError("scope_revision must be an integer")
+
+    return {
+        "capability_id": capability_id,
+        "scope": scope,
+        "page_id": page_id,
+        "scope_revision": scope_revision,
+    }
+
+
+def _has_page_capability(
+    schemas: list[CapabilitySchema],
+    selector: dict[str, Any],
+) -> bool:
+    """Return whether the mirror has the exact page-scoped capability."""
+    return any(
+        sch.capability_id == selector["capability_id"]
+        and sch.scope == "page"
+        and sch.page_id == selector["page_id"]
+        for sch in schemas
+    )
+
+
+def _is_page_scope_error(exc: DeviceHttpError) -> bool:
+    """True for App signals that mean the page-scoped tool cache is stale."""
+    if exc.status_code not in (409, 410) or not isinstance(exc.body, dict):
+        return False
+    code = exc.body.get("errorCode") or exc.body.get("code")
+    return (
+        exc.status_code == 410 and code == "page_capability_gone"
+    ) or (
+        exc.status_code == 409 and code == "capability_scope_expired"
+    )
+
+
 def _event_to_jsonable(ev) -> dict[str, Any]:
     """Serialize a DebugEvent for the ``subscribe_events`` tool."""
     import dataclasses

{debug_control_plane-0.3.0 → debug_control_plane-0.4.0}/debug_control_plane.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-control-plane
-Version: 0.3.0
+Version: 0.4.0
 Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
 Author: tangxiaolu
 License: MIT
@@ -62,7 +62,7 @@ python/
 ├── README.md                       # this file
 ├── LICENSE                         # MIT
 └── debug_control_plane/
-    ├── __init__.py                 # __version__ = "0.3.0"
+    ├── __init__.py                 # __version__ = "0.4.0"
     ├── device_discovery/           # USB/LAN device discovery + device pool
     │   ├── device_candidates.py
     │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
@@ -92,8 +92,8 @@ Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no busi
 
 ## Version / 版本
 
-`0.3.0` — aligned with Kotlin/Dart/Flutter `0.3.0`, API unstable.
-`0.3.0` —— 与 Kotlin/Dart/Flutter `0.3.0` 对齐，API 不稳定。
+`0.4.0` — aligned with Kotlin/Dart/Flutter `0.4.0`, API unstable.
+`0.4.0` —— 与 Kotlin/Dart/Flutter `0.4.0` 对齐，API 不稳定。
 
 ## License / 许可证
 

{debug_control_plane-0.3.0 → debug_control_plane-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "debug-control-plane"
-version = "0.3.0"
+version = "0.4.0"
 description = "Multi-product reusable debug control plane (device discovery + MCP adapter)."
 readme = "README.md"
 requires-python = ">=3.10"

{debug_control_plane-0.3.0 → debug_control_plane-0.4.0}/tests/test_bridge_client.py

@@ -46,6 +46,7 @@ from debug_control_plane.mcp_plane.bridge_client import (
     DeviceUnreachable,
     _iter_sse,
     _safe_body,
+    selector_headers,
 )
 
 # ---------------------------------------------------------------------------
@@ -333,6 +334,52 @@ class TestInvoke:
         client.invoke("dev1", "POST", ["raw"], b"hello-bytes")
         assert captured[0].content == b"hello-bytes"
 
+    def test_selector_headers_forwarded_with_auth_header(self):
+        captured: list[httpx.Request] = []
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            captured.append(req)
+            return _ok_json({"ok": True})
+
+        pool = _MockPool({"dev1": _fresh()}, [])
+        provider = _FakeTokenProvider({"dev1": "token-1"}, [], [], [])
+        client = _make_client(pool, handler, token_provider=provider)
+
+        client.invoke(
+            "dev1",
+            "POST",
+            ["debug", "tap"],
+            {},
+            capability_id="debug",
+            scope="page",
+            page_id="page-a",
+            scope_revision=7,
+        )
+
+        headers = captured[0].headers
+        assert headers["Authorization"] == "Bearer token-1"
+        assert headers["X-DCP-Capability-Id"] == "debug"
+        assert headers["X-DCP-Capability-Scope"] == "page"
+        assert headers["X-DCP-Page-Id"] == "page-a"
+        assert headers["X-DCP-Scope-Revision"] == "7"
+
+    def test_no_selector_keeps_legacy_headers(self):
+        captured: list[httpx.Request] = []
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            captured.append(req)
+            return _ok_json({"ok": True})
+
+        pool = _MockPool({"dev1": _fresh()}, [])
+        client = _make_client(pool, handler)
+
+        client.invoke("dev1", "POST", ["debug", "tap"], {})
+
+        assert "X-DCP-Capability-Id" not in captured[0].headers
+        assert "X-DCP-Capability-Scope" not in captured[0].headers
+        assert "X-DCP-Page-Id" not in captured[0].headers
+        assert "X-DCP-Scope-Revision" not in captured[0].headers
+
 
 # ---------------------------------------------------------------------------
 # auth token provider + auth error taxonomy (R001-BF009)
@@ -581,6 +628,55 @@ class TestRead:
         assert result == [{"id": "a"}, {"id": "b"}]
         assert captured[0].url.path == "/profiles"
 
+    def test_read_forwards_selector_headers(self):
+        captured: list[httpx.Request] = []
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            captured.append(req)
+            return _ok_json({"status": "ok"})
+
+        pool = _MockPool({"dev1": _fresh()}, [])
+        client = _make_client(pool, handler)
+
+        result = client.read(
+            "dev1",
+            ["debug", "status"],
+            capability_id="debug",
+            scope="page",
+            page_id="page-a",
+            scope_revision=8,
+        )
+
+        assert result == {"status": "ok"}
+        assert captured[0].method == "GET"
+        assert captured[0].headers["X-DCP-Capability-Id"] == "debug"
+        assert captured[0].headers["X-DCP-Capability-Scope"] == "page"
+        assert captured[0].headers["X-DCP-Page-Id"] == "page-a"
+        assert captured[0].headers["X-DCP-Scope-Revision"] == "8"
+
+
+class TestSelectorHeaders:
+    def test_selector_headers_stringifies_int_revision(self):
+        assert selector_headers(
+            capability_id="debug",
+            scope="page",
+            page_id="page-a",
+            scope_revision=3,
+        ) == {
+            "X-DCP-Capability-Id": "debug",
+            "X-DCP-Capability-Scope": "page",
+            "X-DCP-Page-Id": "page-a",
+            "X-DCP-Scope-Revision": "3",
+        }
+
+    def test_selector_headers_ignores_malformed_optional_values(self):
+        assert selector_headers(
+            capability_id="debug",
+            scope="invalid",
+            page_id="",
+            scope_revision=True,
+        ) == {"X-DCP-Capability-Id": "debug"}
+
 
 # ---------------------------------------------------------------------------
 # hello() → NetworkTarget (含 BF005 扩展字段)