@coffeerunhobby/mcp-ha-connect 2.1.1 → 2.2.0

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export declare const VERSION = "2.1.1";
+export declare const VERSION = "2.2.0";

package/dist/version.js

@@ -2,5 +2,5 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export const VERSION = '2.1.1';
+export const VERSION = '2.2.0';
 //# sourceMappingURL=version.js.map

package/docs/CHANGELOG.md

@@ -1,3 +1,18 @@
+### 2.2.0
+- **New: owner questions — approve or deny from the phone.** `askOwner` sends a sticky, persistent notification with 1-3 buttons (default Approve / Deny) and returns a `requestId` at once; `getOwnerAnswer` waits up to 50 s per call and returns `answered` (button index and label, `answeredAt`, the HA user who tapped), `pending`, `timeout`, `cancelled` or `unknown`; `cancelOwnerQuestion` withdraws a question and marks the notification "Cancelled". Two calls rather than one long one because Cloudflare cuts requests at ~100 s. Questions stay open up to 7 days (default 10 min); the phone removes the notification at expiry by itself.
+  - **No database, restart-proof:** the requestId carries the question, buttons, target, expiry and asking client, signed with a key derived from `MCP_AUTH_SECRET`; each button's action id is signed separately and cannot be derived from the requestId. After a restart the server still recognises open questions and the taps on them. Only a tap during the restart itself is lost (the question then expires as NO).
+  - **Security:** a tap counts only with origin REMOTE and a user (the mobile app webhook), so an automation firing a fake `mobile_app_notification_action` cannot approve anything; tampered ids, extended expiries and swapped button indexes are rejected; only the asking token `sub` can read or cancel; at most 3 open questions and 30 per hour per client; first tap wins; late taps are ignored. Needs `NOTIFY`.
+  - **Plain text only:** question at most 256 characters (line breaks allowed), title 60, button labels 20. Text is NFC-normalized (Romanian diacritics are fine), then emoji, control and invisible characters (zero-width joiners, bidi overrides), variation selectors and stacked combining marks are refused with the offending character named — never silently stripped or cut.
+  - **`MCP_OWNER_QUESTIONS_HA_USERS`**: comma-separated HA user ids allowed to answer (the `answeredBy` of an answer); unset = any HA user, with a startup warning.
+  - Known limit, accepted: cancellations and answers are kept in memory only. After a restart, someone with a Home Assistant login could re-send an old button id through HA's API and answer a question that had been cancelled or denied (the phone no longer shows its buttons; that access already controls the house).
+  - Needs HTTP mode, an **admin** Home Assistant token (button taps are not on HA's non-admin event allowlist) and `MCP_AUTH_SECRET`. If Home Assistant refuses the tap subscription at startup, the three tools are not offered (logged); if it refuses later, `askOwner` returns an error saying so instead of sending questions nobody can answer. New `MCP_OWNER_QUESTIONS_ENABLED` (default `true`).
+- **Fix — `getAutomationTrace` always answered "Not Found".** Home Assistant has no REST trace endpoint; traces exist only over the WebSocket (`trace/list`, admin-only) and are keyed by the automation's `id` attribute, not its entity id. The tool now uses a one-off WebSocket command, returns the newest runs first (new `limit`, default 5, max 20) with trigger, state and errors, and explains when an automation defined in YAML without an `id` has no traces.
+- **Fix — Home Assistant events stopped after an HA restart.** The WebSocket client reconnected but never re-sent its subscriptions (HA forgets them with the connection), so `/subscribe_events` went silent after every HA restart. Subscriptions are now restored on reconnect; the client keeps retrying with the delay capped at 60 s instead of giving up after 10 attempts; commands are matched to their results by id (they were matched in arrival order); connecting has a deadline and fails at once if HA closes before authenticating; and a subscription made while Home Assistant is unreachable (also at server startup) is queued and sent once HA is back, instead of failing (an SSE client stays connected and receives events when HA returns; previously owner questions and SSE stayed unavailable until a server restart). Unsubscribing works while HA is offline (the subscription is forgotten for good, never restored on reconnect), and a subscription cancelled before HA confirmed it is cancelled on HA's side too. A subscription HA refuses (e.g. a non-admin token) is reported and dropped; one whose confirmation is lost is cancelled and retried (no duplicate subscriptions on HA); and an event HA sends right after confirming a subscription is no longer dropped. Errors from these WebSocket commands reach callers and logs as HA's error code only (e.g. `Home Assistant rejected 'trace/list' (unauthorized)`), never HA's free text or the internal address; the detail stays in the server log. The WebSocket connections now follow `HA_STRICT_SSL` like the REST client.
+- **Fix — duplicate events.** With two subscriptions to the same event type, each received every event twice (HA sends one copy per subscription). Each copy now goes only to its own subscription.
+- **Logging — tool arguments are logged at debug level only.** The info-level `Tool invoked` line now carries just the tool and session; the arguments (message and question text, entity names, MAC addresses) appear only with `LOG_LEVEL=debug`.
+- README: `MCP_SSE_EVENTS_ENABLED` defaults to `true` (the README said `false`).
+- +88 tests (owner question service and tools incl. a real MCP round trip and concurrent rate limits, plain-text validation, WebSocket client against a fake HA server incl. reconnects, deadlines and the TLS policy, trace lookup; the security checks are mutation-tested).
+
 ### 2.1.1
 - **Fix — `omada_setSiteNtpServers` was rejected by the controller on sites with daylight saving off.** Omada returns the DST start/end as empty objects when DST is off, but rejects them on write ("Daylight saving parameter [month] should not be null"). The site update now sends DST start/end only when complete; with DST on and an incomplete start/end it refuses to write. The rejected 2.1.0 call changed nothing (the controller validates before saving).
 - +2 tests (the live DST-off shape; DST on with an incomplete start/end).

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Home Assistant MCP Wrapper",
-    "version": "2.1.1",
+    "version": "2.2.0",
     "description": "REST endpoints that wrap MCP tools for Home Assistant integration."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeerunhobby/mcp-ha-connect",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Smart home MCP server for Home Assistant plus Local AI integration",
   "type": "module",
   "main": "dist/index.js",

package/src/config.ts

@@ -80,6 +80,8 @@ const envSchema = z
 
     // SSE Event Subscription Configuration
     sseEventsEnabled: createBooleanStringSchema(true),
+    ownerQuestionsEnabled: createBooleanStringSchema(true),
+    ownerQuestionsHaUsers: z.string().optional(),
     sseEventsPath: z.string().optional(),
 
     // Rate Limiting Configuration
@@ -230,6 +232,10 @@ export interface EnvironmentConfig {
 
   // SSE Event Subscription Configuration
   sseEventsEnabled: boolean;
+  /** askOwner / getOwnerAnswer / cancelOwnerQuestion (HTTP mode with Home Assistant). */
+  ownerQuestionsEnabled: boolean;
+  /** HA user ids allowed to answer owner questions; empty = any HA user. */
+  ownerQuestionsHaUsers: string[];
   sseEventsPath: string;
 
   // Rate Limiting Configuration
@@ -301,6 +307,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
 
     // SSE Event Subscription Configuration
     sseEventsEnabled: env.MCP_SSE_EVENTS_ENABLED,
+    ownerQuestionsEnabled: env.MCP_OWNER_QUESTIONS_ENABLED,
+    ownerQuestionsHaUsers: env.MCP_OWNER_QUESTIONS_HA_USERS,
     sseEventsPath: env.MCP_SSE_EVENTS_PATH,
 
     // Rate Limiting Configuration
@@ -401,6 +409,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
 
     // SSE Event Subscription Configuration
     sseEventsEnabled: parsed.data.sseEventsEnabled,
+    ownerQuestionsEnabled: parsed.data.ownerQuestionsEnabled,
+    ownerQuestionsHaUsers: (parsed.data.ownerQuestionsHaUsers ?? '').split(',').map((u) => u.trim()).filter(Boolean),
     sseEventsPath: parsed.data.sseEventsPath ?? '/subscribe_events',
 
     // Rate Limiting Configuration

package/src/haClient/automations.ts

@@ -8,6 +8,19 @@ import { logger } from '../utils/logger.js';
 import type { StateOperations } from './states.js';
 import type { ServiceOperations } from './services.js';
 import type { RequestHandler } from './request.js';
+import type { HaWebSocketCommand } from './wsCommand.js';
+
+/** One run of an automation, as `trace/list` summarizes it. */
+export interface AutomationTraceSummary {
+  run_id: string;
+  state?: string;
+  script_execution?: string | null;
+  last_step?: string | null;
+  error?: string;
+  trigger?: string;
+  timestamp?: { start: string; finish: string | null };
+  [key: string]: unknown;
+}
 
 /**
  * Automation-related operations for the Home Assistant API.
@@ -16,7 +29,8 @@ export class AutomationOperations {
   constructor(
     private readonly stateOps: StateOperations,
     private readonly serviceOps?: ServiceOperations,
-    private readonly request?: RequestHandler
+    private readonly request?: RequestHandler,
+    private readonly wsCommand?: HaWebSocketCommand
   ) {}
 
   /**
@@ -216,14 +230,32 @@ export class AutomationOperations {
   /**
    * Get automation trace (execution history)
    */
-  async getAutomationTrace(entityId: string): Promise<unknown[]> {
-    if (!this.request) {
-      throw new Error('RequestHandler not available');
+  async getAutomationTrace(entityId: string, limit = 5): Promise<AutomationTraceSummary[]> {
+    if (!this.wsCommand) {
+      throw new Error('Automation traces need the Home Assistant WebSocket API, which is not available');
     }
 
-    const automationId = entityId.replace('automation.', '');
-    logger.debug('Fetching automation trace', { automationId });
+    // Traces are WebSocket-only (there is no REST endpoint) and are keyed by the
+    // automation's config id (its `id` attribute), not by the entity id.
+    const state = await this.stateOps.getState(entityId);
+    if (!state) {
+      throw new Error(`Automation ${entityId} not found`);
+    }
+    const itemId = state.attributes.id;
+    if (itemId === undefined || itemId === null || itemId === '') {
+      throw new Error(
+        `Automation ${entityId} has no 'id' (an automation defined in YAML without an id), so Home Assistant keeps no traces for it`
+      );
+    }
+    logger.debug('Fetching automation traces', { entityId, itemId });
 
-    return this.request.get<unknown[]>(`/trace/automation/${encodeURIComponent(automationId)}`);
+    const traces = await this.wsCommand<AutomationTraceSummary[]>({
+      type: 'trace/list',
+      domain: 'automation',
+      item_id: String(itemId),
+    });
+    return [...(traces ?? [])]
+      .sort((a, b) => (b.timestamp?.start ?? '').localeCompare(a.timestamp?.start ?? ''))
+      .slice(0, limit);
   }
 }

package/src/haClient/events.ts

@@ -39,13 +39,30 @@ export interface HaEvent {
   };
 }
 
+/** Home Assistant answered a command with `success: false` (a refusal, not a connection problem). */
+export class HaCommandError extends Error {
+  constructor(
+    readonly commandType: string,
+    readonly code: string
+  ) {
+    super(`Home Assistant rejected '${commandType}' (${code})`);
+    this.name = 'HaCommandError';
+  }
+}
+
 export interface EventSubscription {
   id: string;
   subscriptionId: number;
+  /** The socket this subscription was sent on (HA forgets it when that socket closes). */
+  connection?: WebSocket | null;
+  /** The subscribe_events command in flight on that socket. */
+  sending?: Promise<number>;
   eventType?: string;
   domain?: string;
   entityId?: string;
   callback: (event: HaEvent) => void;
+  /** Called if Home Assistant refuses the subscription (e.g. a non-admin token); it is then dropped. */
+  onRejected?: (error: HaCommandError) => void;
 }
 
 export interface EventSubscriberConfig {
@@ -53,6 +70,16 @@ export interface EventSubscriberConfig {
   token: string;
   reconnectInterval?: number;
   maxReconnectAttempts?: number;
+  /** Upper bound for the exponential reconnect delay (ms). Default 60 s. */
+  maxReconnectDelay?: number;
+  /** Deadline for connecting and authenticating (ms). Default 30 s. */
+  connectTimeout?: number;
+  /** Verify the TLS certificate of a wss:// Home Assistant (HA_STRICT_SSL). Default true. */
+  strictSsl?: boolean;
+  /** How long a command waits for its result (ms). Default 30 s. */
+  commandTimeout?: number;
+  /** Delay before re-sending subscriptions that failed for a transient reason (ms). Default 30 s. */
+  resubscribeRetryDelay?: number;
 }
 
 /**
@@ -64,21 +91,33 @@ export class EventSubscriber extends EventEmitter {
   private messageId = 1;
   private authenticated = false;
   private subscriptions = new Map<string, EventSubscription>();
-  private pendingSubscriptions: Array<{ resolve: (id: number) => void; reject: (error: Error) => void }> = [];
+  /** Commands awaiting their `result`, keyed by message id (HA answers by id). */
+  private pendingCommands = new Map<
+    number,
+    { type: string; resolve: (result: unknown) => void; reject: (error: Error) => void }
+  >();
   private reconnectAttempts = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Deadline of the connect attempt in progress (cleared on auth_ok or close). */
+  private connectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Pending retry of subscriptions that failed for a transient reason. */
+  private resubscribeTimer: ReturnType<typeof setTimeout> | null = null;
   private isConnecting = false;
   private shouldReconnect = true;
 
   private readonly config: EventSubscriberConfig;
   private readonly reconnectInterval: number;
   private readonly maxReconnectAttempts: number;
+  private readonly maxReconnectDelay: number;
 
   constructor(config: EventSubscriberConfig) {
     super();
     this.config = config;
     this.reconnectInterval = config.reconnectInterval ?? 5000;
-    this.maxReconnectAttempts = config.maxReconnectAttempts ?? 10;
+    // Keep retrying by default: a long Home Assistant outage must not leave the
+    // server permanently deaf to events (the delay is capped, see handleDisconnect).
+    this.maxReconnectAttempts = config.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+    this.maxReconnectDelay = config.maxReconnectDelay ?? 60000;
   }
 
   /**
@@ -107,7 +146,20 @@ export class EventSubscriber extends EventEmitter {
 
         logger.info('Connecting to Home Assistant WebSocket', { url: wsUrl });
 
-        this.ws = new WebSocket(wsUrl);
+        // Same TLS policy as the REST client: only HA_STRICT_SSL=false skips verification.
+        this.ws = new WebSocket(wsUrl, { rejectUnauthorized: this.config.strictSsl !== false });
+        const ws = this.ws;
+        // A connection that never authenticates must not hang its caller.
+        this.clearConnectTimer();
+    if (this.resubscribeTimer) {
+      clearTimeout(this.resubscribeTimer);
+      this.resubscribeTimer = null;
+    }
+        this.connectTimer = setTimeout(() => {
+          this.connectTimer = null;
+          reject(new Error('Timed out connecting to the Home Assistant WebSocket'));
+          ws.terminate();
+        }, this.config.connectTimeout ?? 30000);
 
         this.ws.on('open', () => {
           logger.info('WebSocket connection established');
@@ -125,15 +177,20 @@ export class EventSubscriber extends EventEmitter {
 
         this.ws.on('close', (code, reason) => {
           logger.info('WebSocket connection closed', { code, reason: reason.toString() });
+          this.clearConnectTimer();
           this.authenticated = false;
           this.isConnecting = false;
+          this.rejectPendingCommands(new Error('WebSocket connection closed'));
+          // Closed before authenticating: fail the connect attempt (no-op once resolved).
+          reject(new Error('Home Assistant closed the WebSocket before authentication'));
           this.handleDisconnect();
         });
 
         this.ws.on('error', (error) => {
+          // The detail (often the internal address) stays in the server log.
           logger.error('WebSocket error', { error: error.message });
           this.isConnecting = false;
-          reject(error);
+          reject(new Error('Could not connect to the Home Assistant WebSocket'));
         });
       } catch (error) {
         this.isConnecting = false;
@@ -161,13 +218,18 @@ export class EventSubscriber extends EventEmitter {
         });
         break;
 
-      case 'auth_ok':
+      case 'auth_ok': {
         logger.info('WebSocket authentication successful');
+        this.clearConnectTimer();
         this.authenticated = true;
         this.isConnecting = false;
         this.emit('connected');
         resolveConnect();
+        // HA forgets subscriptions with the connection: (re)send every registered
+        // one, including those queued while Home Assistant was unreachable.
+        void this.resubscribeAll();
         break;
+      }
 
       case 'auth_invalid':
         logger.error('WebSocket authentication failed', { message: message.message });
@@ -193,17 +255,159 @@ export class EventSubscriber extends EventEmitter {
    */
   private handleResult(message: Record<string, unknown>): void {
     const id = message.id as number;
-    const success = message.success as boolean;
-
-    if (this.pendingSubscriptions.length > 0) {
-      const pending = this.pendingSubscriptions.shift()!;
-      if (success) {
-        pending.resolve(id);
-      } else {
-        const error = message.error as { message?: string } | undefined;
-        pending.reject(new Error(error?.message ?? 'Subscription failed'));
+    const pending = this.pendingCommands.get(id);
+    if (!pending) {
+      return;
+    }
+    this.pendingCommands.delete(id);
+    if (message.success) {
+      pending.resolve(message.result);
+    } else {
+      // Callers and logs get only HA's error code (a fixed vocabulary such as
+      // "unauthorized" or "not_found"); HA's free-text message can carry URLs or
+      // other detail and is never passed on or logged.
+      const error = message.error as { code?: string; message?: string } | undefined;
+      const code = typeof error?.code === 'string' && /^[a-z_]{1,40}$/.test(error.code) ? error.code : 'unknown_error';
+      logger.warn('Home Assistant command failed', { type: pending.type, code });
+      pending.reject(new HaCommandError(pending.type, code));
+    }
+  }
+
+  private clearConnectTimer(): void {
+    if (this.connectTimer) {
+      clearTimeout(this.connectTimer);
+      this.connectTimer = null;
+    }
+  }
+
+  private rejectPendingCommands(error: Error): void {
+    for (const pending of this.pendingCommands.values()) {
+      pending.reject(error);
+    }
+    this.pendingCommands.clear();
+  }
+
+  /**
+   * Send a WebSocket command and resolve with its `result` (rejects on
+   * `success: false`, on disconnect, or after `timeoutMs`).
+   */
+  async sendCommand<T = unknown>(
+    command: { type: string; [key: string]: unknown },
+    timeoutMs = this.config.commandTimeout ?? 30000
+  ): Promise<T> {
+    return (await this.dispatchCommand<T>(command, timeoutMs)).result;
+  }
+
+  /** Like sendCommand, but also reports the message id the command was sent with. */
+  private async dispatchCommand<T>(
+    command: { type: string; [key: string]: unknown },
+    timeoutMs = this.config.commandTimeout ?? 30000
+  ): Promise<{ id: number; result: T }> {
+    if (!this.authenticated) {
+      await this.connect();
+    }
+    const { id, result } = this.beginCommand<T>(command, timeoutMs);
+    return { id, result: await result };
+  }
+
+  /**
+   * Send a command now and return its message id synchronously, with a promise
+   * for its result. Callers that must act on the id before the result arrives
+   * (subscriptions) use this directly.
+   */
+  private beginCommand<T>(
+    command: { type: string; [key: string]: unknown },
+    timeoutMs = this.config.commandTimeout ?? 30000
+  ): { id: number; result: Promise<T> } {
+    const id = this.messageId++;
+    const result = new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingCommands.delete(id);
+        reject(new Error(`Home Assistant command '${command.type}' timed out`));
+      }, timeoutMs);
+      this.pendingCommands.set(id, {
+        type: command.type,
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value as T);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      try {
+        this.sendMessage({ ...command, id });
+      } catch (error) {
+        clearTimeout(timer);
+        this.pendingCommands.delete(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
       }
+    });
+    return { id, result };
+  }
+
+  /** Send subscribe_events for every registered subscription on a new connection. */
+  private async resubscribeAll(): Promise<void> {
+    for (const sub of this.subscriptions.values()) {
+      if (sub.connection === this.ws) {
+        continue; // already subscribed (or in flight) on this connection
+      }
+      const connection = this.ws;
+      sub.connection = connection;
+      // HA identifies the subscription by this message's id and may send events
+      // right after its confirmation (even in the same read): accept them from
+      // the moment the command is sent, not when the confirmation is processed.
+      const { id, result } = this.beginCommand(
+        sub.eventType ? { type: 'subscribe_events', event_type: sub.eventType } : { type: 'subscribe_events' }
+      );
+      sub.subscriptionId = id;
+      sub.sending = result.then(() => id);
+      try {
+        await sub.sending;
+        logger.info('Event subscription active on new connection', { id: sub.id, eventType: sub.eventType });
+      } catch (error) {
+        if (this.subscriptions.get(sub.id) !== sub) {
+          continue; // unsubscribed meanwhile; unsubscribe() already cancelled it on HA's side
+        }
+        sub.subscriptionId = -1;
+        sub.connection = null;
+        if (error instanceof HaCommandError) {
+          // A refusal (e.g. a non-admin token for a non-allowlisted event) is
+          // permanent: drop it and tell the owner of the subscription.
+          this.subscriptions.delete(sub.id);
+          logger.error('Home Assistant refused an event subscription', { id: sub.id, eventType: sub.eventType, code: error.code });
+          sub.onRejected?.(error);
+        } else {
+          // Unconfirmed (e.g. timed out): HA may still have registered it. HA
+          // handles a connection's messages in order, so cancelling now is safe
+          // either way and keeps a retry from adding a duplicate.
+          if (this.authenticated && this.ws === connection) {
+            this.sendUnsubscribe(id);
+          }
+          logger.warn('Event subscription not confirmed; will retry', {
+            id: sub.id,
+            eventType: sub.eventType,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          this.scheduleResubscribe();
+        }
+      }
+    }
+  }
+
+  /** Retry failed subscriptions later on the same connection (a reconnect also retries them). */
+  private scheduleResubscribe(): void {
+    if (this.resubscribeTimer) {
+      return;
     }
+    this.resubscribeTimer = setTimeout(() => {
+      this.resubscribeTimer = null;
+      if (this.authenticated) {
+        void this.resubscribeAll();
+      }
+    }, this.config.resubscribeRetryDelay ?? 30000);
+    this.resubscribeTimer.unref?.();
   }
 
   /**
@@ -213,9 +417,12 @@ export class EventSubscriber extends EventEmitter {
     const event = message.event as HaEvent;
     if (!event) return;
 
-    // Emit to all matching subscriptions
+    // HA sends one copy of the event per subscription, tagged with that
+    // subscription's id: deliver each copy only to its own subscription, or two
+    // subscriptions to the same event type would each get every event twice.
+    const subscriptionId = message.id as number;
     for (const sub of this.subscriptions.values()) {
-      if (this.eventMatchesSubscription(event, sub)) {
+      if (sub.subscriptionId === subscriptionId && this.eventMatchesSubscription(event, sub)) {
         try {
           sub.callback(event);
         } catch (error) {
@@ -277,7 +484,7 @@ export class EventSubscriber extends EventEmitter {
     }
 
     this.reconnectAttempts++;
-    const delay = this.reconnectInterval * Math.pow(2, this.reconnectAttempts - 1);
+    const delay = Math.min(this.reconnectInterval * Math.pow(2, this.reconnectAttempts - 1), this.maxReconnectDelay);
 
     logger.info('Scheduling reconnect', {
       attempt: this.reconnectAttempts,
@@ -286,6 +493,7 @@ export class EventSubscriber extends EventEmitter {
     });
 
     this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
       this.connect().catch((error) => {
         logger.error('Reconnect failed', { error: error.message });
       });
@@ -304,10 +512,15 @@ export class EventSubscriber extends EventEmitter {
   /**
    * Subscribe to specific event type
    */
-  async subscribeEventType(eventType: string, callback: (event: HaEvent) => void): Promise<string> {
+  async subscribeEventType(
+    eventType: string,
+    callback: (event: HaEvent) => void,
+    onRejected?: (error: HaCommandError) => void
+  ): Promise<string> {
     return this.subscribe({
       eventType,
       callback,
+      onRejected,
     });
   }
 
@@ -334,30 +547,34 @@ export class EventSubscriber extends EventEmitter {
   }
 
   /**
-   * Internal subscribe method
+   * Internal subscribe method.
+   *
+   * The subscription is registered first and then sent on every authenticated
+   * connection: right away when connected, otherwise as soon as Home Assistant
+   * is reachable, and again after any reconnect (HA forgets subscriptions with
+   * the connection). It never fails because Home Assistant is down.
    */
   private async subscribe(options: {
     eventType?: string;
     domain?: string;
     entityId?: string;
     callback: (event: HaEvent) => void;
+    onRejected?: (error: HaCommandError) => void;
   }): Promise<string> {
-    if (!this.authenticated) {
-      await this.connect();
-    }
-
-    const subscriptionId = await this.sendSubscribeEvents(options.eventType);
     const id = `sub_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-
-    this.subscriptions.set(id, {
+    const entry: EventSubscription = {
       id,
-      subscriptionId,
+      subscriptionId: -1,
+      connection: null,
       eventType: options.eventType,
       domain: options.domain,
       entityId: options.entityId,
       callback: options.callback,
-    });
-
+      // Refusals that arrive later (after HA becomes reachable, or after a
+      // reconnect) are reported here.
+      onRejected: options.onRejected,
+    };
+    this.subscriptions.set(id, entry);
     logger.info('Created event subscription', {
       id,
       eventType: options.eventType,
@@ -365,27 +582,33 @@ export class EventSubscriber extends EventEmitter {
       entityId: options.entityId,
     });
 
-    return id;
-  }
-
-  /**
-   * Send subscribe_events command
-   */
-  private sendSubscribeEvents(eventType?: string): Promise<number> {
-    return new Promise((resolve, reject) => {
-      this.pendingSubscriptions.push({ resolve, reject });
-
-      const message: Record<string, unknown> = {
-        id: this.messageId++,
-        type: 'subscribe_events',
-      };
-
-      if (eventType) {
-        message.event_type = eventType;
+    if (!this.authenticated && !this.reconnectTimer) {
+      try {
+        await this.connect();
+      } catch (error) {
+        logger.warn('Home Assistant WebSocket not reachable; the subscription will be sent once it is', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return id;
       }
-
-      this.sendMessage(message);
-    });
+    }
+    if (this.authenticated) {
+      // Return once Home Assistant has confirmed it. A refusal now is thrown to
+      // the caller (and the subscription dropped) rather than reported to
+      // onRejected; a transient failure leaves it queued.
+      entry.onRejected = undefined;
+      try {
+        await this.resubscribeAll();
+        await entry.sending;
+      } catch (error) {
+        if (error instanceof HaCommandError) {
+          throw error;
+        }
+      } finally {
+        entry.onRejected = options.onRejected;
+      }
+    }
+    return id;
   }
 
   /**
@@ -397,15 +620,24 @@ export class EventSubscriber extends EventEmitter {
       return;
     }
 
-    // Send unsubscribe command
-    this.sendMessage({
-      id: this.messageId++,
-      type: 'unsubscribe_events',
-      subscription: sub.subscriptionId,
-    });
-
+    // Forget it locally first, whatever the connection state, so it is never
+    // restored on a later reconnect.
     this.subscriptions.delete(subscriptionId);
     logger.info('Removed event subscription', { id: subscriptionId });
+
+    // Tell HA if it was sent on the current connection, confirmed or not: HA
+    // handles a connection's messages in order, so the cancel follows the subscribe.
+    if (this.authenticated && sub.connection === this.ws && sub.subscriptionId >= 0) {
+      this.sendUnsubscribe(sub.subscriptionId);
+    }
+  }
+
+  private sendUnsubscribe(haSubscriptionId: number): void {
+    try {
+      this.sendMessage({ id: this.messageId++, type: 'unsubscribe_events', subscription: haSubscriptionId });
+    } catch (error) {
+      logger.debug('Could not send unsubscribe_events', { error: error instanceof Error ? error.message : String(error) });
+    }
   }
 
   /**
@@ -429,6 +661,7 @@ export class EventSubscriber extends EventEmitter {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    this.clearConnectTimer();
 
     if (this.ws) {
       this.ws.close();