homeassistant-ai
diff --git a/‎.github/workflows/addon-publish-dev.yml‎
Lines changed: 12 additions & 1 deletion b/‎.github/workflows/addon-publish-dev.yml‎
Lines changed: 12 additions & 1 deletion
diff --git a/‎.github/workflows/publish-dev.yml‎
Lines changed: 12 additions & 1 deletion b/‎.github/workflows/publish-dev.yml‎
Lines changed: 12 additions & 1 deletion
diff --git a/‎AGENTS.md‎
Lines changed: 1 addition & 0 deletions b/‎AGENTS.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎custom_components/ha_mcp_tools/config_flow.py‎
Lines changed: 6 additions & 4 deletions b/‎custom_components/ha_mcp_tools/config_flow.py‎
Lines changed: 6 additions & 4 deletions
diff --git a/‎custom_components/ha_mcp_tools/embedded_server.py‎
Lines changed: 106 additions & 7 deletions b/‎custom_components/ha_mcp_tools/embedded_server.py‎
Lines changed: 106 additions & 7 deletions
diff --git a/‎custom_components/ha_mcp_tools/manifest.json‎
Lines changed: 1 addition & 1 deletion b/‎custom_components/ha_mcp_tools/manifest.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/dev-mode.md‎
Lines changed: 50 additions & 0 deletions b/‎docs/dev-mode.md‎
Lines changed: 50 additions & 0 deletions
diff --git a/‎docs/in-process-server.md‎
Lines changed: 5 additions & 1 deletion b/‎docs/in-process-server.md‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎src/ha_mcp/_version.py‎
Lines changed: 12 additions & 0 deletions b/‎src/ha_mcp/_version.py‎
Lines changed: 12 additions & 0 deletions
@@ -46,13 +46,24 @@ jobs:
       short_sha: ${{ steps.version.outputs.short_sha }}
     steps:
       - uses: actions/checkout@v7
+        with:
+          # Full history: the dev version number is the commit count.
+          fetch-depth: 0
 
       - name: Generate dev version
         id: version
         run: |
           BASE_VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
           SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
-          DEV_VERSION="${BASE_VERSION}.dev${{ github.run_number }}"
+          # dev N = commit count on master: the same commit produces the SAME
+          # number in every workflow (PyPI/Docker in publish-dev, the dev
+          # add-on here), so all surfaces report one dev version. run_number
+          # was per-workflow, which is how the add-on drifted ~300 builds
+          # behind the PyPI counter and made version reports incomparable.
+          # Count origin/master (not HEAD): a workflow_dispatch on an older
+          # ref would otherwise mint a LOWER number that collides with an
+          # existing dev release and clobbers it.
+          DEV_VERSION="${BASE_VERSION}.dev$(git rev-list --count origin/master)"
 
           echo "dev_version=$DEV_VERSION" >> $GITHUB_OUTPUT
           echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
 
@@ -45,14 +45,25 @@ jobs:
       short_sha: ${{ steps.version.outputs.short_sha }}
     steps:
       - uses: actions/checkout@v7
+        with:
+          # Full history: the dev version number is the commit count.
+          fetch-depth: 0
 
       - name: Generate dev version
         id: version
         run: |
           # Get base version from pyproject.toml
           BASE_VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
           SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
-          DEV_VERSION="${BASE_VERSION}.dev${{ github.run_number }}"
+          # dev N = commit count on master: the same commit produces the SAME
+          # number in every workflow (PyPI/Docker in publish-dev, the dev
+          # add-on here), so all surfaces report one dev version. run_number
+          # was per-workflow, which is how the add-on drifted ~300 builds
+          # behind the PyPI counter and made version reports incomparable.
+          # Count origin/master (not HEAD): a workflow_dispatch on an older
+          # ref would otherwise mint a LOWER number that collides with an
+          # existing dev release and clobbers it.
+          DEV_VERSION="${BASE_VERSION}.dev$(git rev-list --count origin/master)"
 
           echo "dev_version=$DEV_VERSION" >> $GITHUB_OUTPUT
           echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
 
@@ -470,6 +470,7 @@ src/ha_mcp/
 
 **Namespace prefixes**: An optional `<namespace>_` prefix between `ha_` and the verb is allowed for grouped tool families that share a domain. The full shape becomes `ha_<namespace>_<verb>_<noun>`:
 - `ha_config_<verb>_<noun>` — config-management tools (`ha_config_set_helper`, `ha_config_set_automation`, `ha_config_remove_automation`, `ha_config_delete_dashboard`)
+- `ha_dev_<verb>_<noun>` — developer-mode tools (`ha_dev_manage_server`, `ha_dev_manage_settings`); registered only when the `enable_dev_mode` setting is on (Developer section at the bottom of the web settings UI's Server Settings tab)
 
 **Accepted exceptions**: A small set of tools name a single, distinct operation where forcing a `<verb>_<noun>` shape would read worse than the natural name. These are accepted as-is and should not be flagged:
 - `ha_restart`, `ha_reload_core`, `ha_eval_template`
 
@@ -252,10 +252,12 @@ async def async_step_init(
                 ),
                 vol.Optional(
                     OPT_PIP_SPEC,
-                    # ``or DEFAULT_PIP_SPEC`` so a stored-empty spec (the normalized
-                    # "no override" state) re-displays the default (the unpinned
-                    # stable distribution) as a hint.
-                    default=opts.get(OPT_PIP_SPEC) or DEFAULT_PIP_SPEC,
+                    # Pre-fill only a genuinely saved override. The normalized
+                    # "no override" state renders an EMPTY field — pre-filling
+                    # DEFAULT_PIP_SPEC as a hint made a field whose help text
+                    # says "leave blank" always look populated, and showed the
+                    # STABLE dist name even on the dev channel.
+                    default=opts.get(OPT_PIP_SPEC, ""),
                 ): str,
                 vol.Optional(
                     OPT_SERVER_URL,
 
@@ -90,8 +90,12 @@
 _ACCESS_TOKEN_TTL = timedelta(days=3650)
 
 # Readiness probe: how long to wait for the server thread to accept a loopback
-# TCP connection before declaring the start failed.
-_READY_TIMEOUT_SECONDS = 30.0
+# TCP connection before declaring the start failed. Generous on purpose: a
+# cold import of the fastmcp tree takes 1-3s on real hardware but has been
+# observed to exceed 30s on QEMU-emulated HAOS (the e2e lane), and a single
+# readiness timeout fails the bring-up outright — there is no retry. Real
+# deployments only pay this budget on the failure path.
+_READY_TIMEOUT_SECONDS = 90.0
 _READY_POLL_INTERVAL_SECONDS = 0.5
 
 # How long to wait for the worker thread to exit on stop before giving up and
@@ -169,6 +173,14 @@ def __init__(self, hass: HomeAssistant, entry: ConfigEntry) -> None:
         self._loop: asyncio.AbstractEventLoop | None = None
         self._stop_event: asyncio.Event | None = None
         self._thread_exc: BaseException | None = None
+        # A worker that refused to die within the stop-join timeout (e.g.
+        # wedged in a slow cold import). Tracked so the next start can skip
+        # the module purge while it might still be importing.
+        self._orphaned_thread: threading.Thread | None = None
+        # ha_mcp.__version__ as imported by the CURRENT worker thread (stashed
+        # by _serve). Compared against the installed distribution after start
+        # to detect a stale-code worker (see _purge_ha_mcp_modules).
+        self._running_version: str | None = None
 
     @property
     def port(self) -> int:
@@ -199,6 +211,33 @@ async def async_start(self) -> None:
         access_token = await self._async_provision_token()
         await self._hass.async_add_executor_job(self._prepare_config_dir)
 
+        # Drop cached ha_mcp modules so the worker imports the code that is on
+        # disk NOW. Without this, a reload after a pip install keeps serving
+        # the OLD code forever: all workers are threads of the one HA core
+        # process, and Python resolves ``import ha_mcp`` from sys.modules —
+        # installs only took effect after a full HA core restart (issue
+        # observed live: options saves reinstalled the package, the web UI
+        # footer showed the new on-disk version, yet the serving worker kept
+        # reporting the version it was first imported with).
+        #
+        # SKIPPED while an orphaned worker may still be importing: ripping
+        # entries out of sys.modules under a live importer corrupts its
+        # import in progress (seen on QEMU-slow HAOS, where a cold import
+        # can outlive both the readiness timeout and the stop-join budget).
+        # The post-start staleness check below surfaces the consequence
+        # (old code possibly serving) instead.
+        orphan = self._orphaned_thread
+        if orphan is not None and not orphan.is_alive():
+            self._orphaned_thread = orphan = None
+        if orphan is None:
+            _purge_ha_mcp_modules()
+        else:
+            _LOGGER.warning(
+                "Skipping the ha_mcp module purge: a previous worker thread "
+                "is still shutting down. The new worker may serve the "
+                "previously imported code until Home Assistant restarts."
+            )
+
         self._thread_exc = None
         self._thread = threading.Thread(
             target=self._thread_main,
@@ -210,6 +249,25 @@ async def async_start(self) -> None:
 
         await self._async_wait_until_ready()
 
+        # Belt-and-braces staleness check: the worker stashed the
+        # ha_mcp.__version__ it actually imported; if that disagrees with the
+        # installed distribution the purge did not fully take (e.g. a stray
+        # import of ha_mcp outside the worker re-cached old modules) and only
+        # an HA core restart applies the update — say so instead of serving
+        # old code silently.
+        if self._running_version:
+            installed = await self._hass.async_add_executor_job(
+                _installed_ha_mcp_version
+            )
+            if installed and installed != self._running_version:
+                _LOGGER.warning(
+                    "HA-MCP in-process server is running version %s but "
+                    "version %s is installed; restart Home Assistant to "
+                    "finish applying the update.",
+                    self._running_version,
+                    installed,
+                )
+
     async def async_stop(self) -> None:
         """Signal the worker thread to shut down and join it (bounded).
 
@@ -240,10 +298,16 @@ async def async_stop(self) -> None:
                 "leaving it to terminate with the process.",
                 _STOP_JOIN_TIMEOUT_SECONDS,
             )
+            # Remember the zombie: the next start must not purge modules
+            # while this thread may still be importing them. The worker
+            # holds its own loop/stop-event as locals, so clearing the
+            # published references below cannot crash it.
+            self._orphaned_thread = thread
         self._thread = None
         self._loop = None
         self._stop_event = None
         self._thread_exc = None
+        self._running_version = None
 
     async def async_revoke_credentials(self) -> None:
         """Revoke the provisioned refresh token and remove the server's user.
@@ -582,10 +646,14 @@ def _thread_main(self, access_token: str) -> None:
 
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
+        # Created here and handed to _serve as a LOCAL; publishing to self
+        # is one-way, for async_stop's signaling only — see async_stop's
+        # zombie-thread comment for why the worker must never re-read it.
+        stop_event = asyncio.Event()
         self._loop = loop
-        self._stop_event = asyncio.Event()
+        self._stop_event = stop_event
         try:
-            loop.run_until_complete(self._serve(access_token))
+            loop.run_until_complete(self._serve(access_token, stop_event))
         except Exception as err:
             self._thread_exc = err
             _LOGGER.exception("HA-MCP in-process server thread crashed")
@@ -609,7 +677,7 @@ def _thread_main(self, access_token: str) -> None:
                     )
             loop.close()
 
-    async def _serve(self, access_token: str) -> None:
+    async def _serve(self, access_token: str, stop_event: asyncio.Event) -> None:
         """Build the ha-mcp server and run it until a stop is signaled.
 
         Mirrors the CLI HTTP runner in ``ha_mcp.__main__`` without importing it
@@ -621,6 +689,11 @@ async def _serve(self, access_token: str) -> None:
         # of os.environ is the whole point of the in-process channel.
         import ha_mcp.config as _hamcp_config
 
+        # Record which code generation this worker actually imported — the
+        # post-start staleness check in async_start compares it against the
+        # installed distribution.
+        self._running_version = getattr(sys.modules.get("ha_mcp"), "__version__", None)
+
         # Drop any settings singleton cached by a PREVIOUS start in this same
         # Python process: an entry reload must re-read the override files
         # (feature flags, advanced settings) exactly like an add-on restart
@@ -739,8 +812,7 @@ async def _serve(self, access_token: str) -> None:
         )
         uv_server = uvicorn.Server(config)
 
-        assert self._stop_event is not None
-        stop_task = asyncio.create_task(self._stop_event.wait())
+        stop_task = asyncio.create_task(stop_event.wait())
         async with server.mcp._lifespan_manager():
             serve_task = asyncio.create_task(uv_server.serve())
             done, _pending = await asyncio.wait(
@@ -812,6 +884,33 @@ async def _async_probe_port(self) -> bool:
         return True
 
 
+def _purge_ha_mcp_modules() -> None:
+    """Drop every cached ``ha_mcp`` module so the next import loads fresh code.
+
+    The in-process server runs as a thread of the HA core Python process, and
+    Python resolves imports from the process-wide ``sys.modules`` cache — so
+    after a pip install the next worker would silently reuse the OLD code
+    unless the cache is purged first. Safe here because ``ha_mcp`` is pure
+    Python and is only ever imported inside the (currently stopped) worker
+    thread; third-party dependencies are deliberately NOT purged (they are
+    shared with the rest of Home Assistant), so a dependency-version change
+    still needs an HA core restart.
+    """
+    # Snapshot the keys: sys.modules can be mutated by concurrent imports on
+    # other threads mid-iteration (HA core is heavily threaded).
+    purged = [
+        name
+        for name in list(sys.modules)
+        if name == "ha_mcp" or name.startswith("ha_mcp.")
+    ]
+    if not purged:
+        return
+    for name in purged:
+        sys.modules.pop(name, None)
+    importlib.invalidate_caches()
+    _LOGGER.debug("Purged %d cached ha_mcp module(s) before worker start", len(purged))
+
+
 def _installed_ha_mcp_version() -> str | None:
     """Return the installed ha-mcp distribution version, or None (blocking).
 
 
@@ -19,5 +19,5 @@
     "requirements": [
         "ruamel.yaml>=0.18.0"
     ],
-    "version": "1.0.0"
+    "version": "1.0.1"
 }
@@ -0,0 +1,50 @@
+# Developer Mode
+
+Developer mode registers two hidden MCP tools intended for people developing
+or testing ha-mcp itself. It is **off by default**, and while it is off the
+tools are never registered — MCP clients cannot see or call them.
+
+> **Warning**: with developer mode on, any connected MCP client (i.e. any AI
+> agent using this server) can change server settings and replace the running
+> server version. Enable it only on instances used for development/testing.
+
+## Enabling
+
+The toggle lives at the **very bottom of the web settings UI**: Server
+Settings tab → **Developer** section (below the beta features). Flip the
+switch, confirm the warning, and restart the server for the tools to
+register. Alternatively set the `HAMCP_ENABLE_DEV_MODE=true` env var.
+
+The flag is intentionally absent from the add-on Configuration page.
+
+## Tools
+
+### `ha_dev_manage_server`
+
+| Action | What it does |
+| ------ | ------------- |
+| `info` | Reports server version, deployment mode (embedded / add-on / standalone), Python version, data dir, HA version, and — when the [in-process server](in-process-server.md) entry exists — its current channel and pip spec. |
+| `update_source` | Points the in-process (custom component) server at a release `channel` (`stable` / `dev`) or an explicit `pip_spec` — a version pin or a GitHub tarball URL such as `https://github.com/homeassistant-ai/ha-mcp/archive/refs/pull/<PR>/head.tar.gz` — then reinstalls and restarts it via the component's own options flow. |
+| `restart` | Restarts this server: config-entry reload in embedded mode, Supervisor self-restart in add-on mode. Standalone processes must be restarted externally. |
+
+`update_source` makes PR testing a one-call operation on an in-process
+server install: point the pip spec at the PR tarball, wait for the reinstall,
+reconnect, and verify with `info`. No extra repos or add-on rebuilds needed.
+Server-code updates apply on the entry reload itself (component >= 1.0.1
+purges the module cache per worker start); a change that needs *newer
+third-party dependencies* still wants a Home Assistant core restart, since
+shared libraries already loaded by the HA process are not reloaded.
+
+### `ha_dev_manage_settings`
+
+| Action | What it does |
+| ------ | ------------- |
+| `list` | Returns the full server-settings matrix (the same fields as the web UI's Server Settings tab) with each value's origin: `env` (pinned, read-only), `file` (override file), `addon` (Supervisor-managed), or `default`. |
+| `set` | Validates and persists one setting through the same override layer the web UI uses. Env-pinned settings are refused; beta sub-flags still require the beta master to be on. |
+| `reset` | Removes one setting's override-file entry, returning it to its default. Refused for env-pinned and add-on-managed settings, like `set`. |
+
+Changes persist immediately but — like the web UI — most settings only take
+effect after a restart (`ha_dev_manage_server` `restart`).
+
+Backup settings and per-tool enable/disable state are separate surfaces
+(Backups tab / Tools tab) and are not covered by this tool.
@@ -146,7 +146,11 @@ unpinned: an entry reload or a Home Assistant restart always reinstalls the
 newest build of the selected channel, and on top of that the component checks
 PyPI for a newer build every 6 hours and reloads the entry automatically when
 one is published — so a long-running instance picks up releases without a
-restart. Each automatic update also raises a notification naming the old and
+restart. The reload applies the new server code immediately (component >=
+1.0.1 reloads the module cache per worker start); only updates that require
+newer *third-party dependencies* still need a Home Assistant core restart.
+The web settings UI's **Restart HA-MCP Server** button performs the same
+entry reload. Each automatic update also raises a notification naming the old and
 new version, with a link to the release notes. Turn **Automatic server
 updates** off to freeze the server on the version currently installed:
 reloads/restarts keep that exact version until you turn it back on or install
 
@@ -30,6 +30,18 @@ def get_version() -> str:
     """
     if override := os.environ.get("HA_MCP_BUILD_VERSION"):
         return override
+    # Prefer the distribution that actually OWNS the installed ha_mcp package.
+    # Both channel dists (ha-mcp / ha-mcp-dev) can leave metadata behind — an
+    # interrupted channel switch, a best-effort uninstall that failed — and a
+    # fixed name order then reports the leftover dist's version instead of the
+    # one whose files are really installed.
+    try:
+        owners = importlib.metadata.packages_distributions().get("ha_mcp", [])
+        unique = sorted(set(owners))
+        if len(unique) == 1:
+            return importlib.metadata.version(unique[0])
+    except Exception as exc:
+        logger.debug("packages_distributions probe failed: %s", exc)
     for pkg_name in ("ha-mcp", "ha-mcp-dev"):
         try:
             return importlib.metadata.version(pkg_name)
Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,5 @@`
`19`	`19`	`"requirements": [`
`20`	`20`	`"ruamel.yaml>=0.18.0"`
`21`	`21`	`],`
`22`		`- "version": "1.0.0"`
	`22`	`+ "version": "1.0.1"`
`23`	`23`	`}`