homeassistant-ai
diff --git a/‎SECURITY.md‎
Lines changed: 9 additions & 0 deletions b/‎SECURITY.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎scripts/codeql_quality_gate.py‎
Lines changed: 10 additions & 0 deletions b/‎scripts/codeql_quality_gate.py‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎site/src/data/tools.json‎
Lines changed: 3 additions & 3 deletions b/‎site/src/data/tools.json‎
Lines changed: 3 additions & 3 deletions
@@ -39,6 +39,15 @@ secrecy and is designed for loopback HTTP or LAN HTTP with a high-entropy
 `MCP_SECRET_PATH`. Any peer that can reach the configured path is treated as
 trusted — securing the local network is outside ha-mcp's scope.
 
+On app (add-on) installs, ha-mcp additionally talks to the Supervisor REST
+API at `http://supervisor` with the Supervisor-issued token. That transport
+is the platform's contract, not a choice this project can harden: Supervisor
+serves its API over plain HTTP only (`web.TCPSite(..., port=80)` in
+`supervisor/api/__init__.py` — no TLS endpoint, no IPC socket), on the
+internal `hassio` docker network that is not reachable from the LAN. The
+isolation of that internal network is the boundary protecting the token, and
+it is enforced by the Home Assistant OS platform, not by ha-mcp.
+
 For internet-facing deployments use the OAuth entrypoint (`ha-mcp-oauth`) or,
 for gating access behind an external identity provider instead of per-user HA
 tokens, the OIDC entrypoint (`ha-mcp-oidc`; see [docs/oidc.md](docs/oidc.md)),
 
@@ -187,6 +187,16 @@
         "default. CodeQL's single-file analysis misses the cross-module "
         "import, so the declaration looks dead.",
     ),
+    (
+        "py/unused-global-variable",
+        "src/ha_mcp/tools/log_common.py",
+        "_LOG_LEVEL_RE",
+        "",
+        "Cross-module use: log_common.py is the leaf module of the tools_utility "
+        "split, so this regex is imported and read by log_sources.py's "
+        "_build_raw_error_log level filter. CodeQL's single-file analysis misses "
+        "the cross-module import, so the declaration looks dead.",
+    ),
     (
         "py/unused-import",
         "packaging/binary/pyinstaller_hooks/runtime_hook.py",
 
@@ -2100,7 +2100,7 @@
   {
     "name": "ha_get_logs",
     "title": "Get Logs",
-    "description": "Get Home Assistant logs from various sources.\n\n**Sources:**\n- \"logbook\" (default): Entity state change history with pagination\n- \"system\": Structured system log entries (errors, warnings) via system_log/list\n- \"error_log\": Raw log text (home-assistant.log on container/pip installs; HA Core's journald stream on Supervisor-backed installs)\n- \"supervisor\": Add-on container logs (requires slug = add-on slug)\n- \"system_service\": HA-Supervisor-managed system service logs (requires\n  slug ∈ {supervisor, host, core, dns, audio, cli, multicast, observer})\n- \"logger\": Effective log level per integration via logger/log_info (confirms logger.set_level changes took effect)\n\n**Prefer source='system' for triage.** It returns HA's own deduplicated\nsystem_log entries with counts, first_occurred and full tracebacks; of\nthose only the tracebacks are unrecoverable from the structured\nerror_log summary — they are present in the raw text, so structured=False\ngets them back. Its counts also run\nsince each error first occurred, while structured error_log counts only\nwhat is inside the fetched window (reported as window_start/window_end;\nSupervisor-backed installs read a capped journald slice). Use error_log\nwith structured=True for entries below system_log's WARNING+ ~50-entry\ncap, or for the per-component rollup.\n\n**Shared params:** limit, search (keyword filter on entries/lines; matches integration domain for source='logger')\n**Order:** order='newest' (default) returns most-recent first; order='oldest' returns chronological-first. Applies to all time-ordered sources (logbook, system, error_log, supervisor, system_service); ignored for source='logger' and for error_log with structured=True. For raw-text sources (error_log, supervisor, system_service) it sets the read direction of the most-recent window.\n**Logbook params:** hours_back, entity_id, end_time, offset, compact (default True — strips attribute dicts to save context)\n**System/error_log params:** level (ERROR, WARNING, INFO, DEBUG, CRITICAL)\n**error_log params:** structured, top_n. In structured mode `search`\n    matches the message and logger name only, whereas on the raw path it\n    matches the whole line; `limit`/`order` do not apply, and issues are\n    ranked by count, then severity, then recency.\n**Supervisor params:** slug = add-on slug, e.g. \"core_mosquitto\" (use\n    ha_get_app() to list installed slugs)\n**System-service params:** slug = service name. The slug \"supervisor\"\n    here means the Supervisor service's own logs, NOT an add-on with\n    that name — the source param disambiguates.",
+    "description": "Get Home Assistant logs from various sources.\n\n**Sources:**\n- \"logbook\" (default): Entity state change history with pagination\n- \"system\": Structured system log entries (errors, warnings) via system_log/list\n- \"error_log\": Raw log text (home-assistant.log on container/pip installs; HA Core's journald stream on Supervisor-backed installs)\n- \"supervisor\": App (add-on) container logs (requires slug = app slug)\n- \"system_service\": HA-Supervisor-managed system service logs (requires\n  slug ∈ {supervisor, host, core, dns, audio, cli, multicast, observer})\n- \"logger\": Effective log level per integration via logger/log_info (confirms logger.set_level changes took effect)\n\n**Prefer source='system' for triage.** It returns HA's own deduplicated\nsystem_log entries with counts, first_occurred and full tracebacks; of\nthose only the tracebacks are unrecoverable from the structured\nerror_log summary — they are present in the raw text, so structured=False\ngets them back. Its counts also run\nsince each error first occurred, while structured error_log counts only\nwhat is inside the fetched window (reported as window_start/window_end;\nevery install now reads a capped window). Use error_log\nwith structured=True for entries below system_log's WARNING+ ~50-entry\ncap, or for the per-component rollup.\n\n**Shared params:** limit, search (keyword filter on entries/lines; matches integration domain for source='logger')\n**Order:** order='newest' (default) returns most-recent first; order='oldest' returns chronological-first. Applies to all time-ordered sources (logbook, system, error_log, supervisor, system_service); ignored for source='logger' and for error_log with structured=True. For raw-text sources (error_log, supervisor, system_service) it sets the read direction of the most-recent window.\n**Logbook params:** hours_back, entity_id, end_time, compact (default True — strips attribute dicts to save context)\n**Pagination (logbook + error_log):** offset pages deeper; ignored for the\n    other sources. Logbook responses carry has_more plus a\n    pagination_hint. On error_log, offset counts raw log lines back from\n    the newest entry (journald entries on Supervisor-backed installs),\n    both modes read a bounded window per call — so `level`/`search`\n    filter and `limit` slice within that window only, and window_lines\n    reports the size actually requested — and the response carries\n    has_more with a next_offset to pass back while it stays true.\n**System/error_log params:** level (ERROR, WARNING, INFO, DEBUG, CRITICAL)\n**error_log params:** structured, top_n. In structured mode `search`\n    matches the message and logger name only, whereas on the raw path it\n    matches the whole line; `limit`/`order` do not apply, issues are\n    ranked by count, then severity, then recency, and the summary covers\n    a fixed deep window rather than the caller's limit.\n**Supervisor params:** slug = app slug, e.g. \"core_mosquitto\" (use\n    ha_get_app() to list installed slugs)\n**System-service params:** slug = service name. The slug \"supervisor\"\n    here means the Supervisor service's own logs, NOT an app with\n    that name — the source param disambiguates.",
     "inputSchema": {
       "properties": {
         "source": {
@@ -2132,7 +2132,7 @@
           "default": null
         },
         "offset": {
-          "type": "Annotated[int, Field(ge=0)]",
+          "type": "Annotated[int, Field(ge=0, description=\"Page deeper into source='logbook' and source='error_log' (ignored for other sources). On error_log it counts raw log lines back from the newest entry; pass the response's 'next_offset' to continue while 'has_more' is true.\")]",
           "default": 0
         },
         "compact": {
@@ -2165,7 +2165,7 @@
     "tags": [
       "History & Statistics"
     ],
-    "source_file": "tools_utility.py"
+    "source_file": "tools_logs.py"
   },
   {
     "name": "ha_get_integration",