ha-mcp-dev 8.4.3.dev2572__tar.gz → 8.4.3.dev2579__tar.gz

{ha_mcp_dev-8.4.3.dev2572/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2579}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2572
+Version: 8.4.3.dev2579
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2572"
+version = "8.4.3.dev2579"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579}/src/ha_mcp/policy/approval_queue.py

@@ -33,6 +33,7 @@ class PendingApproval:
     expires_at: datetime
     _decision: Decision = "pending"
     _event: anyio.Event = field(default_factory=anyio.Event)
+    _claimed: bool = False
 
     @property
     def decision(self) -> Decision:
@@ -51,6 +52,26 @@ class PendingApproval:
         await self._event.wait()
         return self._decision
 
+    def claim(self) -> bool:
+        """Take exclusive ownership of this approval. False if already taken.
+
+        ``decide()`` wakes every waiter sharing this entry, and each one
+        would otherwise consume it and dispatch — one click authorizing N
+        executions (issue #2387). This is the same one-shot transition
+        ``decide()`` uses, and for the same reason: exactly one caller may
+        act on a given decision.
+
+        The flag lives on the entry rather than on queue membership
+        because ``_sweep_expired`` can drop an approved row (it ignores
+        ``decision``) while a waiter still holds this reference and is
+        legitimately entitled to consume it. There is no ``await`` here,
+        so the check-and-set cannot interleave with another task.
+        """
+        if self._claimed:
+            return False
+        self._claimed = True
+        return True
+
     def __post_init__(self) -> None:
         if self.expires_at <= self.created_at:
             raise ValueError("expires_at must be after created_at")
@@ -221,10 +242,18 @@ class ApprovalQueue:
 
     def consume_and_maybe_remember(
         self, entry: PendingApproval, *, remember_minutes: int
-    ) -> None:
+    ) -> bool:
+        """Consume one approval. False when another waiter already did.
+
+        A losing caller must not dispatch on this entry, and must not
+        arm the remember-cache from a decision it did not consume.
+        """
+        if not entry.claim():
+            return False
         self.remove(entry.token)
         if remember_minutes > 0:
             self.remember(entry.tool_name, entry.args_hash, minutes=remember_minutes)
+        return True
 
     def _sweep_expired(self) -> None:
         now = datetime.now(UTC)

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579}/src/ha_mcp/policy/middleware.py

@@ -56,7 +56,12 @@ class PolicyMiddleware(Middleware):
 
         Loads the policy, evaluates the call, and -- when approval is
         required -- finds or creates a pending queue entry and waits up to
-        the configured window for a decision. A dynamic selector call
+        the configured window for a decision. Identical static calls share
+        one queue entry so the user sees a single approval row, but the
+        approval itself is consumed exactly once
+        (``PendingApproval.claim``): a second waiter woken by the same
+        decision gets its own pending row instead of riding the first
+        call's click. A dynamic selector call
         (``has_dynamic_selector_targets``) never shares or reuses another
         call's pending entry, and is never reissued on TTL eviction: see
         the inline comments above the ``existing =``, ``pending =``, and
@@ -167,36 +172,16 @@ class PolicyMiddleware(Middleware):
         # The accepted cost is that a retry never silently rides an earlier
         # approval: each blocked call gets its own approval row, and only
         # approving the row for the CURRENTLY-blocked call has any effect.
-        existing = None if dynamic_targets else self._queue.find(name, args_hash)
-        if existing and existing.decision == "approved":
-            self._queue.consume_and_maybe_remember(
-                existing,
-                remember_minutes=remember_minutes,
-            )
+        if self._resolve_already_decided(
+            name,
+            args_hash,
+            dynamic_targets=dynamic_targets,
+            remember_minutes=remember_minutes,
+        ):
             return await call_next(context)
-        if existing and existing.decision == "denied":
-            self._queue.remove(existing.token)
-            self._raise_denied_error()
 
-        # find_or_create serialises the create — two concurrent calls with
-        # the same args_hash share one pending entry, so the user only sees
-        # one approval row and approving it releases every waiter. Dynamic
-        # selector calls must NOT share a pending entry: two concurrent
-        # identical calls can still resolve to different (or overlapping)
-        # target sets by the time each one dispatches, so folding them onto
-        # one approval would let a single click authorize more executions
-        # than the user saw. Skip the sharing and always mint a fresh entry.
-        pending = (
-            self._queue.create(
-                name, args_hash, args, ttl_minutes=policy.approval_ttl_minutes
-            )
-            if dynamic_targets
-            else await self._queue.find_or_create(
-                name,
-                args_hash,
-                args,
-                ttl_minutes=policy.approval_ttl_minutes,
-            )
+        pending = await self._new_pending(
+            name, args_hash, args, policy=policy, dynamic_targets=dynamic_targets
         )
 
         wait = (
@@ -207,11 +192,24 @@ class PolicyMiddleware(Middleware):
         await self._wait_for_decision(context, pending, wait)
 
         if pending.decision == "approved":
-            self._queue.consume_and_maybe_remember(
+            if self._claim_approval(
                 pending,
+                name,
+                args_hash,
+                dynamic_targets=dynamic_targets,
                 remember_minutes=remember_minutes,
+            ):
+                return await call_next(context)
+            # Another waiter on this shared entry consumed the approval
+            # first. This call has none of its own, so it must not ride
+            # that click: mint a fresh row and tell the caller to get it
+            # approved. Its wait budget is already spent, so it does not
+            # wait again here -- re-waiting would also let a steady
+            # stream of identical calls starve one another.
+            pending = await self._new_pending(
+                name, args_hash, args, policy=policy, dynamic_targets=dynamic_targets
             )
-            return await call_next(context)
+            self._raise_pending_error(pending, rule, dynamic_targets=dynamic_targets)
         if pending.decision == "denied":
             self._queue.remove(pending.token)
             self._raise_denied_error()
@@ -222,6 +220,116 @@ class PolicyMiddleware(Middleware):
         self._raise_pending_error(pending, rule, dynamic_targets=dynamic_targets)
         return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
 
+    def _resolve_already_decided(
+        self,
+        name: str,
+        args_hash: str,
+        *,
+        dynamic_targets: bool,
+        remember_minutes: int,
+    ) -> bool:
+        """Act on an entry this call did not create. True means dispatch now.
+
+        A dynamic selector call must never consume an entry it did not
+        itself create and is not itself still waiting on, so it skips this
+        lookup entirely -- see the creator-only binding rationale above the
+        call site in ``on_call_tool``.
+
+        The claim cannot currently fail on this path: consuming an entry
+        also removes it, and there is no ``await`` between the ``find()``
+        and the claim, so no other task can interleave. It is checked
+        anyway so that adding an await to this stretch degrades into an
+        extra approval prompt rather than silently restoring the double
+        dispatch the claim exists to stop.
+        """
+        if dynamic_targets:
+            return False
+        existing = self._queue.find(name, args_hash)
+        if existing is None:
+            return False
+        if existing.decision == "approved":
+            return self._claim_approval(
+                existing,
+                name,
+                args_hash,
+                dynamic_targets=dynamic_targets,
+                remember_minutes=remember_minutes,
+            )
+        if existing.decision == "denied":
+            self._queue.remove(existing.token)
+            self._raise_denied_error()
+        return False
+
+    def _claim_approval(
+        self,
+        entry: PendingApproval,
+        name: str,
+        args_hash: str,
+        *,
+        dynamic_targets: bool,
+        remember_minutes: int,
+    ) -> bool:
+        """Consume an approved entry for this invocation.
+
+        Exactly one caller may act on a given approval (see
+        ``PendingApproval.claim``). A caller that loses the claim still
+        proceeds when the winner's ``remember_minutes`` armed a
+        remember-cache entry covering this exact call: that window is the
+        user saying "stop asking for this", so re-prompting would
+        contradict the rule they configured. The ``is_remembered`` gate
+        earlier in ``on_call_tool`` ran before the approval existed, which
+        is why it has to be re-checked here rather than relied upon.
+
+        A dynamic selector call never reads the remember-cache -- that
+        same gate skips the lookup for it, and ``remember_minutes`` is
+        forced to 0 -- so it must not consult one here either. No
+        reachable case arms such a key today (``has_dynamic_selector_targets``
+        is a pure function of the name and args that also produce
+        ``args_hash``, so static and dynamic calls cannot collide on one
+        key), but the guard keeps this branch degrading the same
+        direction as the defensive claim check in
+        ``_resolve_already_decided``: toward an extra prompt, never
+        toward a dispatch the caller was not entitled to.
+        """
+        if self._queue.consume_and_maybe_remember(
+            entry, remember_minutes=remember_minutes
+        ):
+            return True
+        if dynamic_targets:
+            return False
+        return self._queue.is_remembered(name, args_hash)
+
+    async def _new_pending(
+        self,
+        name: str,
+        args_hash: str,
+        args: dict[str, Any],
+        *,
+        policy: Policy,
+        dynamic_targets: bool,
+    ) -> PendingApproval:
+        """Mint the pending entry this invocation will wait on.
+
+        ``find_or_create`` serialises the create -- two concurrent calls
+        with the same args_hash share one pending entry, so the user only
+        sees one approval row. Sharing the row is safe; sharing the
+        *decision* is not, which is what ``_claim_approval`` enforces.
+
+        Dynamic selector calls must NOT share a pending entry at all: two
+        concurrent identical calls can still resolve to different (or
+        overlapping) target sets by the time each one dispatches, so
+        folding them onto one approval would let a single click authorize
+        a broader effect than the user saw. Skip the sharing and always
+        mint a fresh entry.
+        """
+        if dynamic_targets:
+            return self._queue.create(
+                name, args_hash, args, ttl_minutes=policy.approval_ttl_minutes
+            )
+        return await self._queue.find_or_create(
+            name, args_hash, args, ttl_minutes=policy.approval_ttl_minutes
+        )
+
     def _finalize_timed_out_pending(
         self,
         pending: PendingApproval,

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579}/src/ha_mcp/tools/smart_search/_overview.py

@@ -21,6 +21,18 @@ logger = logging.getLogger(__name__)
 class SystemOverviewMixin(_SearchBase):
     """``get_system_overview`` and its analysis/format/paginate helpers."""
 
+    async def _fetch_legacy_overview_slices(self) -> list[Any]:
+        """Fetch broad legacy slices in parallel after states succeeds."""
+        states = await self.client.get_states()
+        optional_results = await asyncio.gather(
+            self.client.get_services(),
+            self.client.send_websocket_message({"type": "config/area_registry/list"}),
+            self.client.send_websocket_message({"type": "config/entity_registry/list"}),
+            self.client.send_websocket_message({"type": "config/device_registry/list"}),
+            return_exceptions=True,
+        )
+        return [states, *optional_results]
+
     async def get_system_overview(
         self,
         detail_level: str = "standard",
@@ -76,29 +88,10 @@ class SystemOverviewMixin(_SearchBase):
                     prefetched_slices["device_registry"],
                 ]
             else:
-                # Fetch all data in parallel. return_exceptions=True so a degraded
-                # registry/service fetch doesn't abort the whole overview.
-                results = await asyncio.gather(
-                    self.client.get_states(),
-                    self.client.get_services(),
-                    self.client.send_websocket_message(
-                        {"type": "config/area_registry/list"}
-                    ),
-                    self.client.send_websocket_message(
-                        {"type": "config/entity_registry/list"}
-                    ),
-                    self.client.send_websocket_message(
-                        {"type": "config/device_registry/list"}
-                    ),
-                    return_exceptions=True,
-                )
+                # Fetch mandatory states first, then read optional slices in
+                # parallel; optional failures degrade independently below.
+                results = await self._fetch_legacy_overview_slices()
 
-            # Entities are mandatory — surface connection/auth errors immediately.
-            # Use BaseException so a cancelled states fetch propagates instead of
-            # being assigned to `entities` and crashing downstream iteration
-            # (mirrors get_entities_by_area / _fetch_search_entities).
-            if isinstance(results[0], BaseException):
-                raise results[0]
             entities = results[0]
             # A cancelled services/registry sub-task must propagate too, not be
             # silently degraded by the fail-open handlers below.

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579}/src/ha_mcp/tools/tools_search.py

@@ -1558,6 +1558,51 @@ class _OverviewSlices:
     repairs: dict[str, Any]
 
 
+# These disjoint sets partition every key documented by ha_get_overview's
+# fields parameter. Keep the manifest test in sync when the public schema changes.
+_OVERVIEW_INDEPENDENT_FIELDS = frozenset(
+    {
+        "success",
+        "system_info",
+        "notification_count",
+        "notifications",
+        "repair_count",
+        "dismissed_repair_count",
+        "repairs",
+        "repairs_error",
+        "tool_discovery",
+        "settings_url",
+        "settings_url_hint",
+        "read_only_mode",
+        "read_only_mode_hint",
+        "ha_mcp_update",
+    }
+)
+_OVERVIEW_NOTIFICATION_FIELDS = frozenset({"notification_count", "notifications"})
+_OVERVIEW_REPAIR_FIELDS = frozenset(
+    {
+        "repair_count",
+        "dismissed_repair_count",
+        "repairs",
+        "repairs_error",
+    }
+)
+_OVERVIEW_ENTITY_FIELDS = frozenset(
+    {
+        "system_summary",
+        "domain_stats",
+        "area_analysis",
+        "ai_insights",
+        "pagination",
+        "partial",
+        "warnings",
+        "device_types",
+        "service_availability",
+    }
+)
+_OVERVIEW_AVAILABLE_FIELDS = _OVERVIEW_INDEPENDENT_FIELDS | _OVERVIEW_ENTITY_FIELDS
+
+
 def _build_component_overview_request(inputs: _OverviewInputs) -> dict[str, Any]:
     """Translate resolved ha_get_overview inputs into an ``ha_mcp_tools/overview`` request.
 
@@ -4045,7 +4090,7 @@ class SearchTools:
                 default=None,
                 description=(
                     "Return only the specified top-level response keys to reduce "
-                    'response size (e.g. ["system_info", "domains"]). '
+                    'response size (e.g. ["system_info", "domain_stats"]). '
                     "None = full response (default). "
                     "Available keys: success, system_summary, domain_stats, "
                     "area_analysis, ai_insights, pagination, partial, warnings, "
@@ -4078,6 +4123,14 @@ class SearchTools:
         Use fields= to project the response to only the keys you need — a
         significantly smaller payload when fetching a single sub-section (e.g.
         fields=["system_info"] returns just that section instead of the full overview).
+        Requests composed only of system_info, notification, repair, or server
+        metadata fields also skip the unrelated state, service, and registry reads.
+
+        Do not use this tool to inspect a known entity or a narrow set of entities.
+        Use ha_get_state for one entity, ha_get_entity for registry metadata, or
+        ha_search with a domain or area filter. An unprojected overview collects
+        system-wide state, service, and registry data and can be expensive on large
+        Home Assistant installations.
 
         When (and only when) the ha-mcp settings-UI sidecar is running
         (stdio mode, e.g. Claude Desktop / Claude Code), the response
@@ -4126,19 +4179,32 @@ class SearchTools:
         except ValueError as exc:
             raise_tool_error(create_validation_error(str(exc), parameter="domains"))
 
-        result = await self._collect_overview(
-            _OverviewInputs(
+        requested_fields = set(parsed_fields or [])
+        recognized_fields = requested_fields & _OVERVIEW_INDEPENDENT_FIELDS
+        use_independent_collectors = (
+            parsed_fields is not None and not requested_fields & _OVERVIEW_ENTITY_FIELDS
+        )
+        if use_independent_collectors:
+            result = await self._collect_independent_overview(
+                requested_fields=recognized_fields,
                 detail_level=detail_level,
-                max_entities_per_domain=max_entities_per_domain,
-                include_state=include_state_bool,
-                include_entity_id=include_entity_id_bool,
-                domains_filter=parsed_domains,
-                limit=limit,
-                offset=offset,
                 include_notifications=include_notifications_bool,
                 include_dismissed_repairs=include_dismissed_repairs_bool,
             )
-        )
+        else:
+            result = await self._collect_overview(
+                _OverviewInputs(
+                    detail_level=detail_level,
+                    max_entities_per_domain=max_entities_per_domain,
+                    include_state=include_state_bool,
+                    include_entity_id=include_entity_id_bool,
+                    domains_filter=parsed_domains,
+                    limit=limit,
+                    offset=offset,
+                    include_notifications=include_notifications_bool,
+                    include_dismissed_repairs=include_dismissed_repairs_bool,
+                )
+            )
 
         settings = get_global_settings()
         if settings.enable_tool_search:
@@ -4170,7 +4236,11 @@ class SearchTools:
         # (issue #863).
         from ..stdio_settings_sidecar import read_sidecar_url
 
-        projected = project_fields(result, parsed_fields)
+        projected = project_fields(
+            result,
+            parsed_fields,
+            available_fields=_OVERVIEW_AVAILABLE_FIELDS,
+        )
         sidecar_url = read_sidecar_url()
         if sidecar_url:
             projected["settings_url"] = sidecar_url
@@ -4215,6 +4285,32 @@ class SearchTools:
 
         return projected
 
+    async def _collect_independent_overview(
+        self,
+        *,
+        requested_fields: set[str],
+        detail_level: str,
+        include_notifications: bool,
+        include_dismissed_repairs: bool,
+    ) -> dict[str, Any]:
+        """Collect requested independent sections with full-path error semantics."""
+        result: dict[str, Any] = {"success": True}
+        if "system_info" in requested_fields:
+            await self._fetch_system_info(result, detail_level)
+        if requested_fields & _OVERVIEW_NOTIFICATION_FIELDS:
+            if include_notifications:
+                await self._fetch_notifications(result)
+            else:
+                result.setdefault("warnings", []).append(
+                    "notifications omitted: include_notifications=False"
+                )
+        if requested_fields & _OVERVIEW_REPAIR_FIELDS:
+            await self._fetch_repairs(
+                result,
+                include_dismissed_repairs,
+            )
+        return result
+
     async def _fetch_system_info(
         self,
         result: dict[str, Any],
@@ -4222,7 +4318,7 @@ class SearchTools:
         *,
         prefetched_config: dict[str, Any] | None = None,
     ) -> None:
-        """Populate result['system_info'] from HA config; tolerates failure.
+        """Populate result['system_info'] from HA config, warning on failure.
 
         ``prefetched_config`` (the component's ``config`` slice, already the bare
         ``get_config()`` dict) is used verbatim when given, skipping the fetch.
@@ -4268,6 +4364,7 @@ class SearchTools:
             logger.warning(
                 "Failed to fetch system info for overview: %s", e, exc_info=True
             )
+            result.setdefault("warnings", []).append(f"system info unavailable: {e}")
             if "system_summary" in result:
                 result["system_summary"].setdefault("version", "unknown")
 
@@ -4277,7 +4374,7 @@ class SearchTools:
         *,
         prefetched_notifications: dict[str, Any] | None = None,
     ) -> None:
-        """Attach active persistent notifications to result.
+        """Attach active persistent notifications, warning on failure.
 
         ``prefetched_notifications`` (the component's ``notifications`` slice
         re-wrapped in the ``{success, result}`` envelope) is unwrapped by the same
@@ -4331,7 +4428,7 @@ class SearchTools:
         *,
         prefetched_repairs: dict[str, Any] | None = None,
     ) -> None:
-        """Attach active repairs issues to result.
+        """Attach active repairs issues, recording failures in repairs_error.
 
         ``prefetched_repairs`` (the component's ``repairs`` slice re-wrapped in the
         ``{success, result: {issues: [...]}}`` envelope) is unwrapped, filtered

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579}/src/ha_mcp/tools/util_helpers.py

@@ -390,6 +390,7 @@ def project_fields(
     fields: str | list[str] | None,
     *,
     extra_always_keep: frozenset[str] | None = None,
+    available_fields: frozenset[str] | None = None,
 ) -> dict[str, Any]:
     """Apply optional field projection to a response data dict.
 
@@ -401,6 +402,10 @@ def project_fields(
     contract / diagnostic keys (e.g. the orchestrator's pagination + partial-
     state keys) without having to reimplement the projection logic.
 
+    ``available_fields`` supplies the complete response schema when *data* was
+    collected narrowly. It affects typo diagnostics only; projection still
+    returns only keys present in *data*.
+
     Typo guard: if any requested key does not exist in *data* (excluding the
     always-retained keys), a diagnostic is appended to ``result["warnings"]``
     listing the unknown keys and the available ones.  This mirrors the
@@ -417,9 +422,10 @@ def project_fields(
     result = {k: v for k, v in data.items() if k in keep}
     # Typo guard — flag any requested keys that are absent from the response.
     # Exclude the always-retained sentinels so fields=["success"] never warns.
-    unknown = sorted(set(parsed) - set(data.keys()) - always_keep)
+    known_fields = set(available_fields) if available_fields is not None else set(data)
+    unknown = sorted(set(parsed) - known_fields - always_keep)
     if unknown:
-        available = sorted(k for k in data.keys() if k not in always_keep)
+        available = sorted(k for k in known_fields if k not in always_keep)
         result.setdefault("warnings", []).append(
             f"fields {unknown!r} not found in response — available keys: {available!r}"
         )

{ha_mcp_dev-8.4.3.dev2572 → ha_mcp_dev-8.4.3.dev2579/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2572
+Version: 8.4.3.dev2579
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT