fix: HA Core proxy fallback for ha_get_logs(source=system_service) on non-addon installs

[kingpanther13]

What does this PR do?

Closes #1260. Adds the is_running_in_addon() gate plus HA Core proxy fallback to _get_system_service_logs, matching the pattern PR #1126 already established for get_addon_logs and (in round 3) get_error_log. Plus two follow-ons from the review pass that fix real behavior gaps the branch split exposes:

1. Branch-aware error suggestions in the tool-layer wrappers (_get_supervisor_log, _get_system_service_log). Pre-fix they always emitted "verify SUPERVISOR_TOKEN" / "hassio_role must be 'manager'" hints — useless advice on the new non-addon proxy path. The wrappers now gate on is_running_in_addon() and emit admin-LLA suggestions when the call came in via the HA Core proxy.
2. Add cli to SYSTEM_SERVICE_SLUGS. HA Core's hassio proxy already whitelists cli/logs in PATHS_ADMIN; ha-mcp's enum just didn't include it. Eight slugs total now.

Background

Pre-#1126, ha_get_logs(source="supervisor") and source="error_log" both routed through HA Core's hassio proxy. #1126 added the is_running_in_addon() branch so addon installs go direct to Supervisor (http://supervisor/...), while non-addon installs (Docker image, uvx ha-mcp, pip-based) keep the Core-proxy fallback. The same PR introduced source="system_service" as a new scope but only wired up the addon-direct branch — _get_system_service_logs ended up a one-liner with no gate:

async def _get_system_service_logs(self, service: str) -> str:
    return await self._supervisor_logs_get(service)

Result for non-addon installs: every system_service call (supervisor, host, core, dns, audio, multicast, observer) hit the SUPERVISOR_TOKEN-absent fail-fast inside _supervisor_logs_get with the misleading (addon-mode gate fired but SUPERVISOR_TOKEN env var not set) text — even though no addon-mode gate ever fired.

Reproduced on a uvx ha-mcp install pointed at a Supervisor-equipped HA: source="supervisor" slug=core_mosquitto succeeded; source="system_service" for supervisor/core/host all returned AUTH_INVALID_TOKEN. Identical to #1260's report.

Fix

1. Client-layer gate (rest_client.py): Mirror get_addon_logs: gate on is_running_in_addon(), fall back to /hassio/{service}/logs via _raw_request (the same call shape get_addon_logs uses for /hassio/addons/{slug}/logs). All eight service slugs are reachable: HA Core's homeassistant/components/hassio/http.py lists audio/logs, cli/logs, core/logs, dns/logs, host/logs, multicast/logs, observer/logs, supervisor/logs, and addons/{slug}/logs in PATHS_ADMIN. Admin LLA is sufficient.

With the gate in place, the existing fail-fast string in _supervisor_logs_get is accurate again because the only callers landing there are addon-mode-confirmed.

2. Branch-aware wrapper suggestions (tools_utility.py): _get_supervisor_log and _get_system_service_log now check is_running_in_addon() on HomeAssistantAuthError (and on 403 for the system_service path) and pick suggestions matching the branch that produced the error:

Branch	Error	Suggestions
In-addon	401	Verify SUPERVISOR_TOKEN / reinstall addon
Non-addon	401	Verify HOMEASSISTANT_TOKEN is a valid admin LLA / re-create if expired
In-addon	403 (system_service)	Bump hassio_role to manager
Non-addon	403 (system_service)	LLA must belong to an admin user / generate a new admin LLA

This avoids steering Docker/uvx users toward SUPERVISOR_TOKEN or hassio_role — env-var and role concepts that don't apply outside the addon container.

3. cli slug. Added to SYSTEM_SERVICE_SLUGS (the in-addon validation set), to the supervisor-mock's mirrored set in tests/src/e2e/utilities/supervisor_mock.py, and to the dispatch and proxy-branch parametrized tests. Tool docstrings updated to mention the eight-slug set.

Tests

TestGetSystemServiceLogsBranchSelection (new in this PR):

• test_non_addon_install_uses_ha_core_proxy — parametrized over all 8 slugs (post-cli-add), asserts the proxy URL is /hassio/{service}/logs, the Accept: text/plain header is passed (without it the proxy negotiates application/json and the body stops being raw log text — same silent-failure signature [BUG] ha_get_logs(source="supervisor") always fails + error suggests nonexistent ha_list_addons() #950 describes one layer up), and the response text flows through.
• test_non_addon_install_404_raises_api_error_with_service_context — anchors the live "observer returns 404 on hubs that don't run it" case from the end-to-end verification. Guards against a future refactor wrapping the proxy call in a swallow-and-return-empty try/except in _get_system_service_logs. Parallels TestGetAddonLogs.test_raises_api_error_on_404_with_slug_context.
• test_addon_install_does_not_call_ha_core_proxy — gate-only assertion that addon installs skip the proxy path (URL/auth contract for the Supervisor-direct branch stays pinned by the existing TestGetSystemServiceLogs class).

Branch-aware-suggestion tests:

• _get_supervisor_log: test_auth_error_in_addon_suggests_supervisor_token, test_auth_error_non_addon_suggests_admin_lla
• _get_system_service_log: same two for AuthError, plus test_403_in_addon_suggests_hassio_role (renamed from test_403_role_hint_suggestion and now mocks the gate explicitly) and test_403_non_addon_suggests_admin_lla_privileges.

Existing test_all_seven_allowed_services_dispatch renamed to test_all_allowed_services_dispatch and extended over 8 slugs.

71 tests pass in test_tools_utility_supervisor_logs.py (was 63 pre-PR, 64 after first review-pass additions, 71 now). uv run ruff check clean on touched files.

Type of change

• 🐛 Bug fix
• ✨ New feature (cli added to system_service slug set)
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
  • Bug reproduced pre-fix on uvx ha-mcp (stable PyPI) pointed at a Supervisor-equipped HA: source="system_service" returned AUTH_INVALID_TOKEN for supervisor/core/host while source="supervisor" succeeded. Matches issue [BUG] ha_get_logs(source="system_service") fails with "Supervisor token absent" while source="supervisor" succeeds in same session #1260's report exactly.
  • Post-fix verified end-to-end against the same hub via uv run --with "git+...@fix/system-service-logs-non-addon-fallback" python <script> calling _get_system_service_logs for seven of the eight slugs. Six return content (or expected-empty for audio/multicast); observer returns 404 — same 404 the in-addon Supervisor-direct path produces on the same hub, confirming code-path parity rather than a proxy gap. (cli not exercised live; its path is covered by the unit tests and HA Core's PATHS_ADMIN source.)
• All automated tests pass (uv run pytest tests/src/unit/test_tools_utility_supervisor_logs.py — 71 passed. Full unit run on Windows shows only pre-existing OS-specific failures in test_kill_signal_diagnostics.py, test_custom_component_filesystem.py, test_data_paths.py that reproduce on clean master.)
• Code follows style guidelines (uv run ruff check clean on touched files)

Checklist

• I have updated documentation if needed (tool docstring + client docstring + e2e mock docstring updated to reflect the 8-slug set and the gate split; site/src/data/tools.json regeneration is owned by sync-tool-docs.yml on merge)

Closes #1260

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses an issue where system service log retrieval failed for non-addon Home Assistant installations. By introducing a conditional check that mirrors existing patterns, the system now correctly routes requests through the HA Core proxy when running outside of an addon container, ensuring consistent access to logs across different deployment types.

Highlights

• Logic Update: Added an is_running_in_addon() gate to _get_system_service_logs to properly handle non-addon installations.
• Proxy Fallback: Implemented a fallback to the HA Core proxy (/api/hassio/{service}/logs) for non-addon environments, resolving authentication errors.
• Test Coverage: Introduced TestGetSystemServiceLogsBranchSelection to verify both the addon-direct path and the proxy fallback across all supported service slugs.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request updates the _get_system_service_logs method in the REST client to support non-addon installations by falling back to the Home Assistant Core proxy when not running within a Supervisor environment. Previously, this method only supported direct Supervisor API calls, causing failures in Docker or pip-based setups. Comprehensive unit tests have been added to verify the branching logic for both addon and non-addon environments. I have no feedback to provide.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.