feat: drive integration config flows and options flows from ha_set_integration (#1822)

* feat: drive integration config flows and options flows from ha_set_integration

Renames ha_set_integration_enabled to ha_set_integration and adds two flow
modes alongside enable/disable (issue #1814):

- Add integration: domain (+ config) starts and walks the domain's config
  flow via the generic flow driver that already powers ha_config_set_helper
  (menus and multi-step forms included, no helper-domain allowlist).
- Update options: entry_id + config drives the entry's options flow, the
  same as the Configure button in the HA UI.

The shared flow walker now surfaces external (browser/OAuth) and progress
steps as structured errors instead of failing with INTERNAL_UNEXPECTED,
and the helper create/update wrappers delegate to the new generic
create_config_entry / update_config_entry_options functions.

Also fixes the stale policy value-source registry key (the old entry
pointed at a nonexistent args.entity_id path) by mapping
ha_set_integration's args.entry_id to a new ha_config_entries source.

Closes #1814

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: address PR #1822 review findings

- Guard require_restart read against a present-but-null result payload
  (Gemini finding).
- Consume the awaited coroutine explicitly in the mode-routing test
  helper (CodeQL py/ineffectual-statement, the one red CI finding).
- Add unit coverage for the undrivable-step branch (external/progress
  step types) and for the new ha_config_entries value-source fetcher +
  registry mapping.
- Attach an existing-entry hint to benign config-flow aborts
  (already_configured / single_instance_allowed), with tests.
- Docstring accuracy: rewrite the stale HAOS module rationale, correct
  the OAuth-caveat wording, and drop the implied prior helper gating.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: raise on options/config flows that consume none of the supplied keys

When a flow presents form steps and none of the caller's config keys
match any step's schema (typos, wrong field names), the walker used to
submit empty forms — HA saved defaults — and still report
'updated successfully' with only a warning. LLM callers gating on
success treat that as done. Raise VALIDATION_INVALID_PARAMETER instead,
pointing at the schema route. Partial matches and zero-form instant
creates keep the established success + warnings contract. Applies to
both ha_set_integration and ha_config_set_helper (shared walker).

Extracts the CREATE_ENTRY and ABORT handling into helpers to stay
under the complexity limit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/policy/value_sources.py

@@ -40,7 +40,7 @@
     ("ha_get_history", "args.entity_ids"): "ha_entities",
     ("ha_remove_entity", "args.entity_id"): "ha_entities",
     ("ha_get_entity_exposure", "args.entity_id"): "ha_entities",
-    ("ha_set_integration_enabled", "args.entity_id"): "ha_entities",
+    ("ha_set_integration", "args.entry_id"): "ha_config_entries",
 }
 
 # Fetched-value TTL cache so the UI can click through path options
@@ -171,8 +171,24 @@ async def _fetch_ha_entities(client: Any, params: dict[str, str]) -> list[str]:
     return out
 
 
+async def _fetch_ha_config_entries(client: Any, _params: dict[str, str]) -> list[str]:
+    entries = await client._request("GET", "/config/config_entries/entry")
+    if not isinstance(entries, list):
+        logger.warning(
+            "ha_config_entries: config entry list returned unexpected shape %s",
+            type(entries).__name__,
+        )
+        return []
+    return [
+        e["entry_id"]
+        for e in entries
+        if isinstance(e, dict) and isinstance(e.get("entry_id"), str)
+    ]
+
+
 _FETCHERS: dict[str, Callable[[Any, dict[str, str]], Awaitable[list[str]]]] = {
     "ha_domains": _fetch_ha_domains,
     "ha_services": _fetch_ha_services,
     "ha_entities": _fetch_ha_entities,
+    "ha_config_entries": _fetch_ha_config_entries,
 }

src/ha_mcp/tools/config_entry_flow.py

@@ -14,7 +14,7 @@
 import logging
 from collections.abc import Iterator
 from enum import StrEnum
-from typing import Any, Literal
+from typing import Any, Literal, NoReturn
 
 from ..client.rest_client import HomeAssistantAPIError
 from ..errors import ErrorCode, create_error_response
@@ -65,6 +65,13 @@
 
 # Keys used to specify a menu selection — stripped before submitting form data.
 _MENU_SELECTION_KEYS = frozenset({"group_type", "next_step_id", "menu_option"})
+
+# Flow step types an MCP client cannot drive: external steps need a browser
+# (OAuth / cloud authorization), progress steps wait on HA-side async work.
+# Surfaced as structured errors instead of attempted (issue #1814).
+_UNDRIVABLE_STEP_TYPES = frozenset(
+    {"external", "external_done", "progress", "progress_done"}
+)
 _RECONFIGURE_SUCCESS_REASONS = frozenset(
     {
         "reauth_successful",
@@ -618,6 +625,74 @@ async def _submit_step(
         raise
 
 
+def _finish_flow_entry(
+    flow_id: str,
+    current_step: dict[str, Any],
+    *,
+    supplied_keys: list[str],
+    saw_form_step: bool,
+    any_form_key_consumed: bool,
+    ignored_config_keys: set[str],
+    remaining_config: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the CREATE_ENTRY success response, or raise on total key miss.
+
+    When the flow presented at least one form step, the caller supplied
+    config keys, and NONE were consumed by any form (typos / wrong field
+    names), the flow was walked on empty forms and HA saved form defaults —
+    not the caller's values. A success + warning there reads as "done" to an
+    LLM caller, so fail loudly with the schema route instead. Partial
+    consumption — and flows that complete without any form step (instant
+    creates) — keep the established success + warnings contract.
+    """
+    if supplied_keys and saw_form_step and not any_form_key_consumed:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                "Flow completed without consuming any of the supplied "
+                "config keys — every form step was submitted empty, so "
+                "the flow saved its defaults, not your values",
+                suggestions=[
+                    "Check the field names against the flow's data_schema — "
+                    "ha_get_integration(entry_id=..., include_schema=True) "
+                    "shows the accepted fields — then retry with corrected "
+                    "keys.",
+                ],
+                context={
+                    "flow_id": flow_id,
+                    "supplied_keys": supplied_keys,
+                    "details": current_step,
+                },
+            )
+        )
+    response: dict[str, Any] = {"success": True, "entry": current_step}
+    warnings = _ignored_keys_warnings(ignored_config_keys, remaining_config)
+    if warnings:
+        response["warnings"] = warnings
+    return response
+
+
+def _raise_flow_abort(flow_id: str, current_step: dict[str, Any]) -> NoReturn:
+    """Raise the structured error for an ABORT flow step."""
+    reason = current_step.get("reason")
+    abort_suggestions: list[str] = []
+    if reason in ("already_configured", "single_instance_allowed"):
+        # Common benign aborts on the add-integration path (#1814): give the
+        # caller a route to the existing entry instead of a bare failure.
+        abort_suggestions.append(
+            "The integration is already set up — use "
+            "ha_get_integration() to find the existing entry."
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            f"Flow aborted: {reason}",
+            suggestions=abort_suggestions or None,
+            context={"flow_id": flow_id, "details": current_step},
+        )
+    )
+
+
 async def _handle_flow_steps(
     client: Any,
     flow_id: str,
@@ -650,35 +725,40 @@ async def _handle_flow_steps(
 
     Returns:
         ``{"success": True, "entry": result}`` on success, plus ``warnings``
-        when caller-supplied config keys were not declared by any flow step.
-        Raises ToolError on any failure.
+        when SOME caller-supplied config keys were not declared by any flow
+        step. When the flow presented at least one form step and NONE of the
+        supplied keys were consumed, raises ``VALIDATION_INVALID_PARAMETER``
+        instead of reporting a misleading success — the flow completed on
+        empty forms (defaults), applying nothing the caller asked for (see
+        :func:`_finish_flow_entry`). Raises ToolError on any failure.
     """
     if submit_fn is None:
         submit_fn = client.submit_config_flow_step
     remaining_config = dict(config)
     current_step = initial_step
     last_menu_choice: str | None = None
     ignored_config_keys: set[str] = set()
+    supplied_keys = sorted(k for k in config if k not in _MENU_SELECTION_KEYS)
+    saw_form_step = False
+    any_form_key_consumed = False
     max_steps = 10
 
     for step_num in range(max_steps):
         result_type = current_step.get("type")
 
         if result_type == _FlowType.CREATE_ENTRY:
-            response: dict[str, Any] = {"success": True, "entry": current_step}
-            warnings = _ignored_keys_warnings(ignored_config_keys, remaining_config)
-            if warnings:
-                response["warnings"] = warnings
-            return response
+            return _finish_flow_entry(
+                flow_id,
+                current_step,
+                supplied_keys=supplied_keys,
+                saw_form_step=saw_form_step,
+                any_form_key_consumed=any_form_key_consumed,
+                ignored_config_keys=ignored_config_keys,
+                remaining_config=remaining_config,
+            )
 
         if result_type == _FlowType.ABORT:
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.SERVICE_CALL_FAILED,
-                    f"Flow aborted: {current_step.get('reason')}",
-                    context={"flow_id": flow_id, "details": current_step},
-                )
-            )
+            _raise_flow_abort(flow_id, current_step)
 
         if result_type == _FlowType.MENU:
             menu_choice = _handle_menu_step(flow_id, current_step, remaining_config)
@@ -702,12 +782,15 @@ async def _handle_flow_steps(
             # step's data_schema, leaving any other keys in remaining_config
             # for subsequent steps (HA can present multi-step forms, e.g.
             # statistics: user step then pick-characteristic step).
+            saw_form_step = True
             form_data = _handle_form_step(
                 flow_id,
                 current_step,
                 remaining_config,
                 ignored_config_keys,
             )
+            if form_data:
+                any_form_key_consumed = True
             logger.debug(
                 f"Flow step {step_num}: form submit "
                 f"(step_id={current_step.get('step_id')}, keys={list(form_data.keys())})"
@@ -722,6 +805,21 @@ async def _handle_flow_steps(
                 current_step=current_step,
             )
 
+        elif result_type in _UNDRIVABLE_STEP_TYPES:
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    f"Flow reached a '{result_type}' step that cannot be "
+                    "completed via MCP (browser/OAuth authorization or an "
+                    "asynchronous provider step)",
+                    suggestions=[
+                        "Complete this flow in the Home Assistant UI "
+                        "(Settings > Devices & Services)."
+                    ],
+                    context={"flow_id": flow_id, "details": current_step},
+                )
+            )
+
         else:
             raise_tool_error(
                 create_error_response(
@@ -981,30 +1079,35 @@ async def get_user_step_field_names(client: Any, helper_type: str) -> set[str] |
                 )
 
 
-async def update_flow_helper(
+async def update_config_entry_options(
     client: Any,
-    helper_type: str,
-    config_dict: dict[str, Any],
     entry_id: str,
+    config_dict: dict[str, Any],
+    *,
+    expected_domain: str | None = None,
+    noun: str = "integration",
 ) -> dict[str, Any]:
-    """Update an existing flow-based helper via its options flow.
+    """Update an existing config entry via its options flow.
 
-    Verifies the entry domain matches helper_type, starts an options flow,
-    walks the flow steps, and returns the result. Aborts the flow on error.
+    When ``expected_domain`` is provided, verifies the entry's domain matches
+    it first (the helper path passes the helper_type; the generic
+    ``ha_set_integration`` path passes ``None`` to accept any domain). Starts
+    an options flow, walks the flow steps, and returns the result. Aborts the
+    flow on error. ``noun`` only affects response wording.
     """
     config_entry = await client.get_config_entry(entry_id)
     actual_domain = config_entry.get("domain")
-    if actual_domain != helper_type:
+    if expected_domain is not None and actual_domain != expected_domain:
         raise_tool_error(
             create_error_response(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
-                f"entry_id '{entry_id}' belongs to domain '{actual_domain}', not '{helper_type}'",
+                f"entry_id '{entry_id}' belongs to domain '{actual_domain}', not '{expected_domain}'",
                 suggestions=[
-                    f"Use ha_get_integration(domain='{helper_type}') to find valid entry IDs",
+                    f"Use ha_get_integration(domain='{expected_domain}') to find valid entry IDs",
                 ],
                 context={
                     "entry_id": entry_id,
-                    "expected": helper_type,
+                    "expected": expected_domain,
                     "actual": actual_domain,
                 },
             )
@@ -1032,7 +1135,7 @@ async def update_flow_helper(
             flow_result,
             config_dict,
             submit_fn=client.submit_options_flow_step,
-            helper_type=helper_type,
+            helper_type=expected_domain,
         )
     except Exception:
         try:
@@ -1048,26 +1151,49 @@ async def update_flow_helper(
         "success": True,
         "entry_id": entry_id,
         "title": entry.get("title"),
-        "domain": helper_type,
-        "message": f"{helper_type} helper updated successfully",
+        "domain": actual_domain,
+        "message": f"{actual_domain} {noun} updated successfully",
         "updated": True,
     }
     if result.get("warnings"):
         response["warnings"] = result["warnings"]
     return response
 
 
-async def create_flow_helper(
+async def update_flow_helper(
     client: Any,
     helper_type: str,
     config_dict: dict[str, Any],
+    entry_id: str,
 ) -> dict[str, Any]:
-    """Create a new flow-based helper via the config flow.
+    """Update an existing flow-based helper via its options flow.
 
-    Starts a config flow, walks the flow steps, and returns the result.
-    Aborts the flow on error.
+    Verifies the entry domain matches helper_type, starts an options flow,
+    walks the flow steps, and returns the result. Aborts the flow on error.
     """
-    flow_result = await client.start_config_flow(helper_type)
+    return await update_config_entry_options(
+        client,
+        entry_id,
+        config_dict,
+        expected_domain=helper_type,
+        noun="helper",
+    )
+
+
+async def create_config_entry(
+    client: Any,
+    domain: str,
+    config_dict: dict[str, Any],
+    *,
+    noun: str = "integration",
+) -> dict[str, Any]:
+    """Create a config entry by driving ``domain``'s config flow.
+
+    Starts a config flow, walks the flow steps (menus and multi-step forms),
+    and returns the result. Aborts the flow on error. ``noun`` only affects
+    response wording.
+    """
+    flow_result = await client.start_config_flow(domain)
     flow_id = flow_result.get("flow_id")
 
     if not flow_id:
@@ -1076,9 +1202,9 @@ async def create_flow_helper(
                 ErrorCode.SERVICE_CALL_FAILED,
                 "Failed to start config flow",
                 suggestions=[
-                    "Check that the helper type is supported and Home Assistant is reachable"
+                    f"Check that the {noun} domain exists and Home Assistant is reachable"
                 ],
-                context={"helper_type": helper_type, "details": flow_result},
+                context={"domain": domain, "details": flow_result},
             )
         )
 
@@ -1088,7 +1214,7 @@ async def create_flow_helper(
             flow_id,
             flow_result,
             config_dict,
-            helper_type=helper_type,
+            helper_type=domain,
         )
     except Exception:
         try:
@@ -1104,9 +1230,22 @@ async def create_flow_helper(
         "success": True,
         "entry_id": entry.get("entry_id"),
         "title": entry.get("title"),
-        "domain": helper_type,
-        "message": f"{helper_type} helper created successfully",
+        "domain": domain,
+        "message": f"{domain} {noun} created successfully",
     }
     if result.get("warnings"):
         response["warnings"] = result["warnings"]
     return response
+
+
+async def create_flow_helper(
+    client: Any,
+    helper_type: str,
+    config_dict: dict[str, Any],
+) -> dict[str, Any]:
+    """Create a new flow-based helper via the config flow.
+
+    Starts a config flow, walks the flow steps, and returns the result.
+    Aborts the flow on error.
+    """
+    return await create_config_entry(client, helper_type, config_dict, noun="helper")