npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-c - Mend

better-dsh 0.2.5 → 0.3.0-c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1002) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/google_chat.md DELETED Viewed

@@ -1,430 +0,0 @@
----
-sidebar_position: 12
-title: "Google Chat"
-description: "Set up Hermes Agent as a Google Chat bot using Cloud Pub/Sub"
----
-# Google Chat Setup
-Connect Hermes Agent to Google Chat as a bot. The integration uses Cloud Pub/Sub
-pull subscriptions for inbound events and the Chat REST API for outbound messages.
-Equivalent ergonomics to Slack Socket Mode or Telegram long-polling: your Hermes
-process does not need a public URL, a tunnel, or a TLS certificate. It connects,
-authenticates, and listens on a subscription — the same way a Telegram bot listens
-on a token.
-> Run `hermes gateway setup` and pick **Google Chat** for a guided walk-through.
-:::note Workspace edition
-Google Chat is part of Google Workspace. You can use this integration with a
-personal Workspace (`@yourdomain.com` registered through Google) or a work
-Workspace where you have the Admin rights to publish an app. Gmail-only accounts
-cannot host Chat apps.
-:::
-## Overview
-| Component | Value |
-|-----------|-------|
-| **Libraries** | `google-cloud-pubsub`, `google-api-python-client`, `google-auth` |
-| **Inbound transport** | Cloud Pub/Sub pull subscription (no public endpoint) |
-| **Outbound transport** | Chat REST API (`chat.googleapis.com`) |
-| **Authentication** | Service Account JSON with `roles/pubsub.subscriber` on the subscription |
-| **User identification** | Chat resource names (`users/{id}`) + email |
----
-## Step 1: Create or pick a GCP project
-You need a Google Cloud project to host the Pub/Sub topic. If you don't have one,
-create it at [console.cloud.google.com](https://console.cloud.google.com) —
-personal accounts get a free tier that easily covers bot traffic.
-Note the project ID (e.g., `my-chat-bot-123`). You'll use it in every subsequent
-step.
----
-## Step 2: Enable two APIs
-In the console, go to **APIs & Services → Library** and enable:
-- **Google Chat API**
-- **Cloud Pub/Sub API**
-Both are free for the volumes a personal bot generates.
----
-## Step 3: Create a Service Account
-**IAM & Admin → Service Accounts → Create Service Account.**
-- Name: `hermes-chat-bot`
-- Skip the "Grant this service account access to project" step. IAM on the specific
-  subscription is all you need — do **NOT** grant project-level Pub/Sub roles.
-After creation, open the SA, go to **Keys → Add Key → Create new key → JSON** and
-download the file. Save it somewhere only Hermes can read (e.g.,
-`~/.hermes/google-chat-sa.json`, `chmod 600`).
-:::caution There is NO "Chat Bot Caller" role
-A common mistake is to search for a Chat-specific IAM role and grant it at the
-project level. That role doesn't exist. Chat bot authority comes from being
-installed in a space, not from IAM. All your SA needs is Pub/Sub subscriber on
-the subscription you create in the next step.
-:::
----
-## Step 4: Create the Pub/Sub topic and subscription
-**Pub/Sub → Topics → Create topic.**
-- Topic ID: `hermes-chat-events`
-- Leave the defaults for everything else.
-After creation, the topic's detail page has a **Subscriptions** tab. Create one:
-- Subscription ID: `hermes-chat-events-sub`
-- Delivery type: **Pull**
-- Message retention: **7 days** (so backlog survives a hermes restart)
-- Leave the rest default.
----
-## Step 5: IAM binding on the topic (critical)
-On the **topic** (not the subscription), add an IAM principal:
-- Principal: `chat-api-push@system.gserviceaccount.com`
-- Role: `Pub/Sub Publisher`
-Without this, Google Chat cannot publish events to your topic and your bot will
-never receive anything.
----
-## Step 6: IAM binding on the subscription
-On the **subscription**, add your own Service Account as a principal:
-- Principal: `hermes-chat-bot@<your-project>.iam.gserviceaccount.com`
-- Role: `Pub/Sub Subscriber`
-Also grant `Pub/Sub Viewer` on the same subscription — Hermes calls
-`subscription.get()` at startup as a reachability check.
----
-## Step 7: Configure the Chat app
-Go to **APIs & Services → Google Chat API → Configuration**.
-- **App name**: whatever you want users to see ("Hermes" is reasonable).
-- **Avatar URL**: any public PNG (Google has some defaults).
-- **Description**: a short sentence shown in the app directory.
-- **Functionality**: enable **Receive 1:1 messages** and **Join spaces and group
-  conversations**.
-- **Connection settings**: select **Cloud Pub/Sub**, enter the topic name
-  `projects/<your-project>/topics/hermes-chat-events`.
-- **Visibility**: restrict to your workspace (or specific users) — do not publish
-  to everyone while you're testing.
-Save.
----
-## Step 8: Install the bot in a test space
-Open Google Chat in a browser. Start a DM with your app by searching for its name
-in the **+ New Chat** menu. The first time you message it, Google sends an
-`ADDED_TO_SPACE` event that Hermes uses to cache the bot's own `users/{id}` for
-self-message filtering.
----
-## Step 9: Configure Hermes
-Add the Google Chat section to `~/.hermes/.env`:
-```bash
-# Required
-GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123
-GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub
-GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/you/.hermes/google-chat-sa.json
-# Authorization — paste the emails of people allowed to talk to the bot
-GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com,coworker@yourdomain.com
-# Optional
-GOOGLE_CHAT_HOME_CHANNEL=spaces/AAAA...         # default delivery destination for cron jobs
-GOOGLE_CHAT_MAX_MESSAGES=1                      # Pub/Sub FlowControl; 1 serializes commands per session
-GOOGLE_CHAT_MAX_BYTES=16777216                  # 16 MiB — cap on in-flight message bytes
-```
-The project ID also falls back to `GOOGLE_CLOUD_PROJECT`, and the SA path falls
-back to `GOOGLE_APPLICATION_CREDENTIALS` — use whichever convention you prefer.
-Under a [multi-profile gateway](../multi-profile-gateways.md), every
-`GOOGLE_CHAT_*` setting is read from the routed profile's own `.env`; a
-secondary profile never inherits the default profile's project, subscription,
-or service account. If a profile has no SA configured while the process
-environment carries one for another profile, the adapter refuses to fall back
-to Application Default Credentials (which would authenticate as that other
-profile) and logs an explicit error instead — put
-`GOOGLE_CHAT_SERVICE_ACCOUNT_JSON` in that profile's `.env`.
-Install the Google Chat adapter dependencies through its maintained installer.
-It applies the same pinned security floors used by the runtime checks:
-```bash
-python -m plugins.platforms.google_chat.oauth --install-deps
-```
-On Docker / hosted images `/opt/hermes/.venv` is read-only. That installer
-routes through `tools.lazy_deps` into `HERMES_LAZY_INSTALL_TARGET`
-(`/opt/data/lazy-packages` in the official image) instead of writing
-site-packages. Restart the gateway after it finishes. The published image
-also bakes the `[google-chat]` extra so a fresh container does not need a
-first-boot install.
-Start the gateway:
-```bash
-hermes gateway
-```
-You should see a log line like:
-```
-[GoogleChat] Connected; project=my-chat-bot-123, subscription=<redacted>,
-             bot_user_id=users/XXXX, flow_control(msgs=1, bytes=16777216)
-```
-Send "hola" in the test DM. The bot posts a "Hermes is thinking…" marker, then
-edits that same message in place with the real response — no "message deleted"
-tombstones.
-### Customizing the working-state marker
-The marker text is configurable via `typing_status_text` in
-`~/.hermes/config.yaml` — e.g. a kitten assistant named Ada:
-```yaml
-platforms:
-  google_chat:
-    # Custom working-state marker text (default: "Hermes is thinking…").
-    typing_status_text: "is pouncing… 🐾"
-```
-Unlike Slack's ephemeral status line, this is a **real posted message** that
-gets edited in place with the response — so whatever you set here briefly
-appears in the chat as a normal message. Set `typing_indicator: false` to
-disable the marker entirely.
----
-## Formatting and capabilities
-Google Chat renders a limited markdown subset:
-| Supported | Not supported |
-|-----------|---------------|
-| `*bold*`, `_italic_`, `~strike~`, `` `code` `` | Headings, lists |
-| Inline images via URL | Interactive Card v2 buttons (v1 of this gateway) |
-| Native file attachments (after `/setup-files` — see Step 10) | Native voice notes / circular video notes |
-The agent's system prompt includes a Google Chat–specific hint so it knows these
-limits and avoids formatting that won't render.
-Message size limit: 4000 characters per message. Longer agent responses are
-automatically split across multiple messages.
-Thread support: when a user replies inside a thread, Hermes detects the
-`thread.name` and posts its reply in the same thread, so each thread gets a
-separate Hermes session.
-### Clarify questions as interactive cards
-When the agent asks a multiple-choice clarify question, the adapter renders it
-as a native **Card v2** with one button per choice plus an
-**"Other / type answer"** button, instead of a plain numbered text list.
-Clicking a button answers the question directly (`CARD_CLICKED` events route
-the choice back into the waiting session). If the card fails to send, or the
-question has no fixed choices, the adapter falls back to the standard text
-clarify. No configuration needed.
----
-## Step 10: Native attachment delivery (optional)
-Out of the box the bot can post text, inline images via URL, and download cards
-for audio/video/documents. To deliver **native** Chat attachments — the same
-file widget you get when a human drags-and-drops a file — each user authorizes
-the bot once via a per-user OAuth flow.
-### Why a separate flow
-Google Chat's `media.upload` endpoint hard-rejects service-account auth:
-> This method doesn't support app authentication with a service account.
-> Authenticate with a user account.
-There's no IAM role or scope that fixes this. The endpoint only accepts user
-credentials. So the bot has to act *as a user* whenever it uploads a file —
-specifically, as the user who asked for the file.
-### One-time setup (per profile)
-1. Go to **APIs & Services → Credentials** in the same GCP project.
-2. **Create credentials → OAuth client ID → Desktop app**.
-3. Download the JSON. Move it onto the host that runs Hermes.
-4. Register the client with Hermes (run under the profile you want it scoped to):
-```bash
-# Default profile:
-python -m plugins.platforms.google_chat.oauth \
-    --client-secret /path/to/client_secret.json
-# A named profile gets its own separate registration:
-hermes -p <profile> python -m plugins.platforms.google_chat.oauth \
-    --client-secret /path/to/client_secret.json
-```
-That writes the client secret into the active profile's Hermes home (e.g.
-`~/.hermes/google_chat_user_client_secret.json` for the default profile). The
-client secret is **profile-scoped, not shared across profiles** — each profile
-registers its own. This is deliberate: profiles are isolated auth boundaries, so
-two profiles can point at different Google OAuth apps / accounts. Register it
-once per profile that needs Google Chat attachment delivery.
-### Per-user authorization (in chat)
-Each user runs the flow once, in their own DM with the bot:
-1. They send `/setup-files` to the bot. It replies with status and the next
-   step.
-2. They send `/setup-files start`. The bot replies with an OAuth URL.
-3. They open the URL, click **Allow**, and watch the browser fail to load
-   `http://localhost:1/?...&code=...`. That failure is expected — the auth
-   code is in the URL bar.
-4. They copy the failed URL (or just the `code=...` value) and paste it back
-   into chat as `/setup-files <PASTED_URL>`. The bot exchanges it for a
-   refresh token.
-The token lands at `~/.hermes/google_chat_user_tokens/<sanitized_email>.json`.
-Subsequent file requests in that user's DM use *their* token, so the bot
-uploads as them and the message lands in their space.
-To revoke later: `/setup-files revoke` deletes only that user's token. Other
-users' tokens are untouched.
-### Scope
-The flow requests exactly one scope: `chat.messages.create`. That covers both
-`media.upload` and the `messages.create` that references the uploaded
-`attachmentDataRef`. No Drive, no broader Chat scopes — this is least-privilege
-on purpose.
-### Multi-user behavior
-When the asker has no per-user token yet, the bot falls back to a legacy
-single-user token at `~/.hermes/google_chat_user_token.json` (if present from
-a pre-multi-user install). When neither is available, the bot posts a clear
-text notice telling the asker to run `/setup-files`.
-A user revoking only clears their own slot. A 401/403 from one user's token
-evicts only that user's cache. Users don't disrupt each other.
----
-## Troubleshooting
-**Bot stays silent after sending "hola."**
-1. Check the Pub/Sub subscription has undelivered messages in the console.
-   If it does, Hermes isn't authenticated — verify `GOOGLE_CHAT_SERVICE_ACCOUNT_JSON`
-   and that the SA is listed as `Pub/Sub Subscriber` on the subscription.
-2. If the subscription has zero messages, Google Chat isn't publishing.
-   Double-check the IAM binding on the **topic**:
-   `chat-api-push@system.gserviceaccount.com` must have `Pub/Sub Publisher`.
-3. Check `hermes gateway` logs for `[GoogleChat] Connected`. If you see
-   `[GoogleChat] Config validation failed`, the error message tells you which
-   env var to fix.
-**Bot replies but an error message appears instead of the agent's answer.**
-Check logs for `[GoogleChat] Pub/Sub stream died` — if these repeat, your SA
-credentials may have been rotated or the subscription deleted. After 10 attempts
-the adapter marks itself fatal.
-**"403 Forbidden" on every outbound message.**
-The bot was removed from the space, or you revoked it in the Chat API console.
-Re-install it in the space (the next `ADDED_TO_SPACE` event will re-enable
-messaging automatically).
-**Too many "Rate limit hit" warnings.**
-The Chat API's default quotas allow 60 messages per space per minute. If your
-agent produces long streaming responses that exceed that, the adapter retries
-with exponential backoff — but you'll still see user-visible latency. Consider
-concise responses or raising the quota in the GCP console.
-**Bot keeps posting the "/setup-files" notice instead of files.**
-The asker has no per-user OAuth token and there's no legacy fallback. Run
-`/setup-files` in their DM and follow Step 10. After the exchange completes
-the next file request uploads natively without a gateway restart.
-**`/setup-files start` says "No client credentials stored."**
-The one-time setup wasn't done *for this profile* (the client secret is
-profile-scoped, so a registration under one profile won't be seen by another).
-From a terminal, run it under the profile the gateway uses:
-```bash
-# Default profile:
-python -m plugins.platforms.google_chat.oauth \
-    --client-secret /path/to/client_secret.json
-# Named profile:
-hermes -p <profile> python -m plugins.platforms.google_chat.oauth \
-    --client-secret /path/to/client_secret.json
-```
-Then send `/setup-files start` again.
-**`/setup-files <PASTED_URL>` says "Token exchange failed."**
-The auth code is single-use and short-lived (typically a few minutes). Send
-`/setup-files start` to get a fresh URL and retry.
----
-## Security notes
-- **Service Account scope**: the adapter requests `chat.bot` and `pubsub` scopes.
-  IAM should be the actual enforcement — grant your SA the minimum
-  (`roles/pubsub.subscriber` + `roles/pubsub.viewer` on the subscription), not
-  project-level or org-level Pub/Sub roles.
-- **Attachment download protection**: Hermes will only attach the SA bearer
-  token to URLs whose host matches a short allowlist of Google-owned domains
-  (`googleapis.com`, `drive.google.com`, `lh[3-6].googleusercontent.com`, and
-  a few others). Any other host is rejected before the HTTP request, to
-  protect against SSRF scenarios where a crafted event could redirect the
-  bearer token to the GCE metadata service.
-- **Redaction**: Service Account emails, subscription paths, and topic paths
-  are stripped from log output by `agent/redact.py`. The debug envelope dump
-  (`GOOGLE_CHAT_DEBUG_RAW=1`) routes through the same redaction filter and
-  logs at DEBUG level.
-- **Compliance**: if you plan to connect this bot to a regulated workspace
-  (anything with a data-residency or AI-governance policy), get that approval
-  before the first install.
-- **User OAuth scope**: the per-user attachment flow requests *only*
-  `chat.messages.create` — the minimum that covers `media.upload` plus the
-  follow-up `messages.create`. Tokens are persisted as plain JSON at
-  `~/.hermes/google_chat_user_tokens/<sanitized_email>.json` (filesystem
-  permissions are the protection — same model as the SA key file). Each
-  token is owned by exactly one user; revoke is scoped to that user.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/homeassistant.md DELETED Viewed

@@ -1,269 +0,0 @@
----
-title: Home Assistant
-description: Control your smart home with Hermes Agent via Home Assistant integration.
-sidebar_label: Home Assistant
-sidebar_position: 5
----
-# Home Assistant Integration
-Hermes Agent integrates with [Home Assistant](https://www.home-assistant.io/) in two ways:
-1. **Gateway platform** — subscribes to real-time state changes via WebSocket and responds to events
-2. **Smart home tools** — four LLM-callable tools for querying and controlling devices via the REST API
-## Setup
-### 1. Create a Long-Lived Access Token
-1. Open your Home Assistant instance
-2. Go to your **Profile** (click your name in the sidebar)
-3. Scroll to **Long-Lived Access Tokens**
-4. Click **Create Token**, give it a name like "Hermes Agent"
-5. Copy the token
-### 2. Configure Environment Variables
-```bash
-# Add to ~/.hermes/.env
-# Required: your Long-Lived Access Token
-HASS_TOKEN=your-long-lived-access-token
-# Optional: HA URL (default: http://homeassistant.local:8123)
-HASS_URL=http://192.168.1.100:8123
-```
-:::info
-The `homeassistant` toolset is automatically enabled when `HASS_TOKEN` is set. Both the gateway platform and the device control tools activate from this single token.
-:::
-### 3. Start the Gateway
-```bash
-hermes gateway
-```
-Home Assistant will appear as a connected platform alongside any other messaging platforms (Telegram, Discord, etc.).
-## Available Tools
-Hermes Agent registers four tools for smart home control:
-### `ha_list_entities`
-List Home Assistant entities, optionally filtered by domain or area.
-**Parameters:**
-- `domain` *(optional)* — Filter by entity domain: `light`, `switch`, `climate`, `sensor`, `binary_sensor`, `cover`, `fan`, `media_player`, etc.
-- `area` *(optional)* — Filter by area/room name (matches against friendly names): `living room`, `kitchen`, `bedroom`, etc.
-**Example:**
-```
-List all lights in the living room
-```
-Returns entity IDs, states, and friendly names.
-### `ha_get_state`
-Get detailed state of a single entity, including all attributes (brightness, color, temperature setpoint, sensor readings, etc.).
-**Parameters:**
-- `entity_id` *(required)* — The entity to query, e.g., `light.living_room`, `climate.thermostat`, `sensor.temperature`
-**Example:**
-```
-What's the current state of climate.thermostat?
-```
-Returns: state, all attributes, last changed/updated timestamps.
-### `ha_list_services`
-List available services (actions) for device control. Shows what actions can be performed on each device type and what parameters they accept.
-**Parameters:**
-- `domain` *(optional)* — Filter by domain, e.g., `light`, `climate`, `switch`
-**Example:**
-```
-What services are available for climate devices?
-```
-### `ha_call_service`
-Call a Home Assistant service to control a device.
-**Parameters:**
-- `domain` *(required)* — Service domain: `light`, `switch`, `climate`, `cover`, `media_player`, `fan`, `scene`, `script`
-- `service` *(required)* — Service name: `turn_on`, `turn_off`, `toggle`, `set_temperature`, `set_hvac_mode`, `open_cover`, `close_cover`, `set_volume_level`
-- `entity_id` *(optional)* — Target entity, e.g., `light.living_room`
-- `data` *(optional)* — Additional parameters as a JSON object
-**Examples:**
-```
-Turn on the living room lights
-→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")
-```
-```
-Set the thermostat to 22 degrees in heat mode
-→ ha_call_service(domain="climate", service="set_temperature",
-    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})
-```
-```
-Set living room lights to blue at 50% brightness
-→ ha_call_service(domain="light", service="turn_on",
-    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})
-```
-## Gateway Platform: Real-Time Events
-The Home Assistant gateway adapter connects via WebSocket and subscribes to `state_changed` events. When a device state changes and matches your filters, it's forwarded to the agent as a message.
-### Event Filtering
-:::warning Required Configuration
-By default, **no events are forwarded**. You must configure at least one of `watch_domains`, `watch_entities`, or `watch_all` to receive events. Without filters, a warning is logged at startup and all state changes are silently dropped.
-:::
-Configure which events the agent sees in `~/.hermes/config.yaml` under the Home Assistant platform's `extra` section:
-```yaml
-platforms:
-  homeassistant:
-    enabled: true
-    extra:
-      watch_domains:
-        - climate
-        - binary_sensor
-        - alarm_control_panel
-        - light
-      watch_entities:
-        - sensor.front_door_battery
-      ignore_entities:
-        - sensor.uptime
-        - sensor.cpu_usage
-        - sensor.memory_usage
-      cooldown_seconds: 30
-```
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `watch_domains` | *(none)* | Only watch these entity domains (e.g., `climate`, `light`, `binary_sensor`) |
-| `watch_entities` | *(none)* | Only watch these specific entity IDs |
-| `watch_all` | `false` | Set to `true` to receive **all** state changes (not recommended for most setups) |
-| `ignore_entities` | *(none)* | Always ignore these entities (applied before domain/entity filters) |
-| `cooldown_seconds` | `30` | Minimum seconds between events for the same entity |
-:::tip
-Start with a focused set of domains — `climate`, `binary_sensor`, and `alarm_control_panel` cover the most useful automations. Add more as needed. Use `ignore_entities` to suppress noisy sensors like CPU temperature or uptime counters.
-:::
-### Event Formatting
-State changes are formatted as human-readable messages based on domain:
-| Domain | Format |
-|--------|--------|
-| `climate` | "HVAC mode changed from 'off' to 'heat' (current: 21, target: 23)" |
-| `sensor` | "changed from 21°C to 22°C" |
-| `binary_sensor` | "triggered" / "cleared" |
-| `light`, `switch`, `fan` | "turned on" / "turned off" |
-| `alarm_control_panel` | "alarm state changed from 'armed_away' to 'triggered'" |
-| *(other)* | "changed from 'old' to 'new'" |
-### Agent Responses
-Outbound messages from the agent are delivered as **Home Assistant persistent notifications** (via `persistent_notification.create`). These appear in the HA notification panel with the title "Hermes Agent".
-### Connection Management
-- **WebSocket** with 30-second heartbeat for real-time events
-- **Automatic reconnection** with backoff: 5s → 10s → 30s → 60s
-- **REST API** for outbound notifications (separate session to avoid WebSocket conflicts)
-- **Authorization** — HA events are always authorized (no user allowlist needed, since the `HASS_TOKEN` authenticates the connection)
-## Security
-The Home Assistant tools enforce security restrictions:
-:::warning Blocked Domains
-The following service domains are **blocked** to prevent arbitrary code execution on the HA host:
-- `shell_command` — arbitrary shell commands
-- `command_line` — sensors/switches that execute commands
-- `python_script` — scripted Python execution
-- `pyscript` — broader scripting integration
-- `hassio` — addon control, host shutdown/reboot
-- `rest_command` — HTTP requests from HA server (SSRF vector)
-Attempting to call services in these domains returns an error.
-:::
-Entity IDs are validated against the pattern `^[a-z_][a-z0-9_]*\.[a-z0-9_]+$` to prevent injection attacks.
-## Example Automations
-### Morning Routine
-```
-User: Start my morning routine
-Agent:
-1. ha_call_service(domain="light", service="turn_on",
-     entity_id="light.bedroom", data={"brightness": 128})
-2. ha_call_service(domain="climate", service="set_temperature",
-     entity_id="climate.thermostat", data={"temperature": 22})
-3. ha_call_service(domain="media_player", service="turn_on",
-     entity_id="media_player.kitchen_speaker")
-```
-### Security Check
-```
-User: Is the house secure?
-Agent:
-1. ha_list_entities(domain="binary_sensor")
-     → checks door/window sensors
-2. ha_get_state(entity_id="alarm_control_panel.home")
-     → checks alarm status
-3. ha_list_entities(domain="lock")
-     → checks lock states
-4. Reports: "All doors closed, alarm is armed_away, all locks engaged."
-```
-### Reactive Automation (via Gateway Events)
-When connected as a gateway platform, the agent can react to events:
-```
-[Home Assistant] Front Door: triggered (was cleared)
-Agent automatically:
-1. ha_get_state(entity_id="binary_sensor.front_door")
-2. ha_call_service(domain="light", service="turn_on",
-     entity_id="light.hallway")
-3. Sends notification: "Front door opened. Hallway lights turned on."
-```
-## Troubleshooting
-**Environment variables not picked up.**
-The adapter reads credentials from `~/.hermes/.env` (auto-merged at startup) or
-from `config.yaml`. Double-check the file lives under the active Hermes profile
-home and that there's no stray quoting around the URL/token. Restart the gateway
-after editing — env changes are only applied on process start.
-**REST auth failing (`401 Unauthorized`).**
-The token must be a *Long-Lived Access Token* created from your HA user profile
-page (**Profile → Security → Long-lived access tokens**). Short-lived UI
-session tokens won't work. Also verify the base URL includes the scheme and
-port (e.g. `http://homeassistant.local:8123`) and is reachable from the host
-running Hermes — `curl -H "Authorization: Bearer <token>" <url>/api/` should
-return `{"message": "API running."}`.