@ajclarkson/homerun 0.0.1-edge.c7ffb3a → 0.0.1-edge.ced2eaa

package/dist/src/framework/action-runtime.d.ts

@@ -9,6 +9,9 @@ export interface ExecutionContext {
     automationId: string;
     location: string;
     subsystem: string;
+    rootCorrelationId?: string;
+    parentCorrelationId?: string;
+    parentAutomationId?: string;
 }
 interface Deps {
     haClient: HAClient;

package/dist/src/framework/action-runtime.js

@@ -1,3 +1,11 @@
+function safeStringify(err) {
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
 export class ActionRuntime {
     deps;
     constructor(deps) {
@@ -15,7 +23,7 @@ export class ActionRuntime {
         const start = performance.now();
         try {
             if (!this.deps.dryRun) {
-                await this.dispatch(action);
+                await this.dispatch(action, ctx);
             }
             const duration = (performance.now() - start) / 1000;
             this.deps.metrics?.observeHistogram('homerun_action_duration_seconds', duration, labels);
@@ -26,16 +34,31 @@ export class ActionRuntime {
             const duration = (performance.now() - start) / 1000;
             this.deps.metrics?.observeHistogram('homerun_action_duration_seconds', duration, labels);
             this.deps.metrics?.incrementCounter('homerun_actions_failed_total', labels);
-            const reason = err instanceof Error ? err.message : String(err);
+            const reason = err instanceof Error
+                ? err.message
+                : typeof err === 'object' && err !== null
+                    ? safeStringify(err)
+                    : String(err);
             this.deps.eventPublisher.publishActionEvent(this.makeEvent(ctx, 'action_result', action, { reason }));
         }
     }
-    async dispatch(action) {
+    async dispatch(action, ctx) {
         switch (action.type) {
             case 'ha.call_service':
-                await this.deps.haClient.callService(action.domain, action.service, action.target, action.data);
+                await this.deps.haClient.callService(action.domain, action.service, action.target, action.data, {
+                    correlationId: ctx.correlationId,
+                    rootCorrelationId: ctx.rootCorrelationId,
+                    automationId: ctx.automationId,
+                });
                 break;
             case 'mqtt.publish':
+                if (action.impliesEntity) {
+                    this.deps.haClient.registerPendingWrite(action.impliesEntity, {
+                        correlationId: ctx.correlationId,
+                        rootCorrelationId: ctx.rootCorrelationId,
+                        automationId: ctx.automationId,
+                    });
+                }
                 await this.deps.mqttClient.publishAsync(action.topic, action.payload, { retain: action.retain ?? false });
                 break;
             case 'timer.start':
@@ -54,6 +77,7 @@ export class ActionRuntime {
         return {
             schema: 'home.events.v1',
             correlation_id: ctx.correlationId,
+            root_correlation_id: ctx.rootCorrelationId ?? ctx.correlationId,
             automation_id: ctx.automationId,
             location: ctx.location,
             subsystem: ctx.subsystem,
@@ -61,6 +85,8 @@ export class ActionRuntime {
             actions: [action],
             timestamp: new Date().toISOString(),
             ...(this.deps.dryRun ? { dry_run: true } : {}),
+            ...(ctx.parentCorrelationId && { parent_correlation_id: ctx.parentCorrelationId }),
+            ...(ctx.parentAutomationId && { parent_automation_id: ctx.parentAutomationId }),
             ...extra,
         };
     }

package/dist/src/framework/api-server.js

@@ -64,7 +64,8 @@ export class ApiServer {
             json(res, 404, { error: `no automation with id "${id}"` });
             return;
         }
-        this.deps.onTrigger(automation, { type: 'on_start', correlation_id: crypto.randomUUID() });
+        const correlation_id = crypto.randomUUID();
+        this.deps.onTrigger(automation, { type: 'on_start', correlation_id, root_correlation_id: correlation_id });
         json(res, 200, { ok: true });
     }
     postReload(res) {

package/dist/src/framework/event-publisher.d.ts

@@ -3,6 +3,9 @@ import type { Action } from '../types/actions.js';
 export interface ObsEvent {
     schema: 'home.events.v1';
     correlation_id: string;
+    root_correlation_id?: string;
+    parent_correlation_id?: string;
+    parent_automation_id?: string;
     automation_id: string;
     location: string;
     subsystem: string;

package/dist/src/framework/ha-client.d.ts

@@ -23,6 +23,14 @@ export interface StateChangedEvent {
     old_state: EntityState | undefined;
     new_state: EntityState;
     correlation_id: string;
+    parent_correlation_id?: string;
+    root_correlation_id?: string;
+    parent_automation_id?: string;
+}
+export interface WriteOrigin {
+    correlationId: string;
+    rootCorrelationId?: string;
+    automationId: string;
 }
 export declare interface HAClient {
     on(event: 'state_changed', listener: (e: StateChangedEvent) => void): this;
@@ -37,6 +45,7 @@ export declare class HAClient extends EventEmitter {
     private readonly labelToEntities;
     private readonly entityToLabels;
     private readonly areaToEntities;
+    private readonly pendingWrites;
     private connection;
     private reconnecting;
     private _readyResolve;
@@ -44,7 +53,12 @@ export declare class HAClient extends EventEmitter {
     readonly state: HAState;
     readonly context: HAContext;
     get entityCount(): number;
-    callService(domain: string, service: string, target?: HassServiceTarget, data?: Record<string, unknown>): Promise<void>;
+    get registryStats(): {
+        labels: number;
+        areas: number;
+    };
+    callService(domain: string, service: string, target?: HassServiceTarget, data?: Record<string, unknown>, origin?: WriteOrigin): Promise<void>;
+    registerPendingWrite(entityId: string, origin: WriteOrigin): void;
     disconnect(): void;
     connect(url: string, token: string): Promise<void>;
     private repopulateCache;

package/dist/src/framework/ha-client.js

@@ -1,10 +1,14 @@
 import { callService, createConnection, createLongLivedTokenAuth, subscribeEntities, } from 'home-assistant-js-websocket';
 import { EventEmitter } from 'node:events';
+const PENDING_WRITE_TTL_MS = 2000;
 export class HAClient extends EventEmitter {
     stateCache = new Map();
     labelToEntities = new Map();
     entityToLabels = new Map();
     areaToEntities = new Map();
+    // entity_id -> origin of the write that's expected to produce a state_changed for it.
+    // Self-evicts after PENDING_WRITE_TTL_MS; consumed (deleted) the moment it's matched.
+    pendingWrites = new Map();
     connection = null;
     // True between a disconnect event and the next subscribeEntities callback.
     // During this window we repopulate silently — no state_changed events emitted.
@@ -23,11 +27,26 @@ export class HAClient extends EventEmitter {
     get entityCount() {
         return this.stateCache.size;
     }
-    async callService(domain, service, target, data) {
+    get registryStats() {
+        return { labels: this.labelToEntities.size, areas: this.areaToEntities.size };
+    }
+    async callService(domain, service, target, data, origin) {
         if (!this.connection)
             throw new Error('HAClient not connected');
+        const entityId = target?.entity_id;
+        if (origin && entityId)
+            this.registerPendingWrite(entityId, origin);
         await callService(this.connection, domain, service, data, target);
     }
+    // Registers that `origin` is expected to produce a state_changed for `entityId` — consumed
+    // (and stamped as parent_correlation_id/parent_automation_id) by diffAndUpdate on match, or
+    // self-evicted after PENDING_WRITE_TTL_MS if nothing arrives. Used by ha.call_service writes
+    // (automatically, via target.entity_id) and by mqtt.publish writes that declare `impliesEntity`
+    // (explicitly, since a topic alone carries no entity information — see #28, #138).
+    registerPendingWrite(entityId, origin) {
+        this.pendingWrites.set(entityId, origin);
+        setTimeout(() => this.pendingWrites.delete(entityId), PENDING_WRITE_TTL_MS);
+    }
     disconnect() {
         this.connection?.close();
         this.connection = null;
@@ -88,7 +107,18 @@ export class HAClient extends EventEmitter {
             // last_updated changes whenever state or attributes change in HA.
             if (!old_state || old_state.last_updated !== new_state.last_updated) {
                 this.stateCache.set(id, new_state);
-                this.emit('state_changed', { entity_id: id, old_state, new_state, correlation_id: crypto.randomUUID() });
+                const correlation_id = crypto.randomUUID();
+                const origin = this.pendingWrites.get(id);
+                if (origin)
+                    this.pendingWrites.delete(id);
+                this.emit('state_changed', {
+                    entity_id: id,
+                    old_state,
+                    new_state,
+                    correlation_id,
+                    root_correlation_id: origin ? (origin.rootCorrelationId ?? origin.correlationId) : correlation_id,
+                    ...(origin && { parent_correlation_id: origin.correlationId, parent_automation_id: origin.automationId }),
+                });
             }
         }
         // Prune entities that disappeared from the snapshot.

package/dist/src/framework/pipeline.js

@@ -5,15 +5,19 @@ export async function runPipeline(automation, event, haClient, deps) {
         trigger_type: event.type,
     });
     const correlationId = event.correlation_id;
+    const rootCorrelationId = event.root_correlation_id ?? correlationId;
     const timestamp = new Date().toISOString();
     const base = {
         schema: 'home.events.v1',
         correlation_id: correlationId,
+        root_correlation_id: rootCorrelationId,
         automation_id: automation.id,
         location: automation.location,
         subsystem: automation.subsystem,
         timestamp,
         ...(deps.dryRun ? { dry_run: true } : {}),
+        ...(event.parent_correlation_id && { parent_correlation_id: event.parent_correlation_id }),
+        ...(event.parent_automation_id && { parent_automation_id: event.parent_automation_id }),
     };
     // Step 1: Enabled check
     if (automation.enabled === false) {
@@ -60,6 +64,9 @@ export async function runPipeline(automation, event, haClient, deps) {
             automationId: automation.id,
             location: automation.location,
             subsystem: automation.subsystem,
+            rootCorrelationId,
+            ...(event.parent_correlation_id && { parentCorrelationId: event.parent_correlation_id }),
+            ...(event.parent_automation_id && { parentAutomationId: event.parent_automation_id }),
         }),
     ]);
 }

package/dist/src/framework/registry.js

@@ -10,7 +10,10 @@ export class AutomationRegistry {
             cb();
     }
     unregister(id) {
-        this.automations.delete(id);
+        if (!this.automations.delete(id))
+            return;
+        for (const cb of this.changeCallbacks)
+            cb();
     }
     getAll() {
         return Array.from(this.automations.values());

package/dist/src/framework/scheduler.js

@@ -12,7 +12,8 @@ export class Scheduler {
     start() {
         this.registerCronTriggers(this.automations);
         this.ready.then(() => {
-            this.dispatch({ type: 'on_start', correlation_id: crypto.randomUUID() });
+            const correlation_id = crypto.randomUUID();
+            this.dispatch({ type: 'on_start', correlation_id, root_correlation_id: correlation_id });
         }).catch((err) => {
             console.error('[scheduler] ready promise rejected:', err);
         });
@@ -27,22 +28,28 @@ export class Scheduler {
         this.cleanups.length = 0;
     }
     registerCronTriggers(automations) {
+        const automationIdsByExpression = new Map();
         for (const automation of automations) {
             for (const trigger of automation.triggers) {
                 if (trigger.type === 'schedule') {
-                    const { cron: expression } = trigger;
-                    try {
-                        const task = cron.schedule(expression, () => {
-                            this.dispatch({ type: 'schedule', cron: expression, correlation_id: crypto.randomUUID() });
-                        });
-                        this.cleanups.push(() => task.stop());
-                        console.log(`[scheduler] registered cron "${expression}" for ${automation.id}`);
-                    }
-                    catch (err) {
-                        console.error(`[scheduler] failed to register cron "${expression}" for ${automation.id}:`, err);
-                    }
+                    const ids = automationIdsByExpression.get(trigger.cron) ?? [];
+                    ids.push(automation.id);
+                    automationIdsByExpression.set(trigger.cron, ids);
                 }
             }
         }
+        for (const [expression, automationIds] of automationIdsByExpression) {
+            try {
+                const task = cron.schedule(expression, () => {
+                    const correlation_id = crypto.randomUUID();
+                    this.dispatch({ type: 'schedule', cron: expression, correlation_id, root_correlation_id: correlation_id });
+                });
+                this.cleanups.push(() => task.stop());
+                console.log(`[scheduler] registered cron "${expression}" for ${automationIds.join(', ')}`);
+            }
+            catch (err) {
+                console.error(`[scheduler] failed to register cron "${expression}" for ${automationIds.join(', ')}:`, err);
+            }
+        }
     }
 }

package/dist/src/framework/timer-manager.js

@@ -8,7 +8,8 @@ export class TimerManager {
         this.cancel(timerKey);
         const handle = setTimeout(() => {
             this.timers.delete(timerKey);
-            this.dispatch({ type: 'timer_expired', timerKey, correlation_id: crypto.randomUUID() });
+            const correlation_id = crypto.randomUUID();
+            this.dispatch({ type: 'timer_expired', timerKey, correlation_id, root_correlation_id: correlation_id });
         }, delayMs);
         this.timers.set(timerKey, handle);
     }

package/dist/src/framework/trigger-engine.d.ts

@@ -17,7 +17,10 @@ export declare class TriggerEngine {
     private readonly buttonHandlers;
     private regexButtonTriggers;
     private readonly durationTimers;
+    private readonly subscribedTopics;
+    private started;
     constructor(registry: AutomationRegistry, haClient: HAClient, onMatch: (automation: Automation<unknown>, event: TriggerEvent) => void, mqttClient?: MqttClient | undefined, metrics?: MetricsBackend | undefined);
+    private syncMqttSubscriptions;
     private rebuildButtonHandlers;
     start(): void;
     dispatch(event: TriggerEvent): void;

package/dist/src/framework/trigger-engine.js

@@ -14,7 +14,7 @@ class ButtonGestureHandler {
         this.dispatch = dispatch;
         this.supportsDoublePress = supportsDoublePress;
     }
-    handle(actionState, correlationId) {
+    handle(actionState, corr) {
         if (actionState === '')
             return;
         const parsed = parseButtonAction(actionState);
@@ -31,7 +31,7 @@ class ButtonGestureHandler {
             }
             if (!this.holdFired) {
                 this.holdFired = true;
-                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'hold', button, correlation_id: correlationId });
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'hold', button, ...corr });
             }
             return;
         }
@@ -50,14 +50,14 @@ class ButtonGestureHandler {
             this.shortFired = true;
         if (this.gestureState === 'idle') {
             if (!this.supportsDoublePress) {
-                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, correlation_id: correlationId });
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, ...corr });
             }
             else {
                 this.gestureState = 'resolving';
                 this.resolveTimer = setTimeout(() => {
                     this.resolveTimer = null;
                     this.gestureState = 'idle';
-                    this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, correlation_id: correlationId });
+                    this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, ...corr });
                 }, DOUBLE_PRESS_WINDOW_MS);
             }
         }
@@ -66,7 +66,7 @@ class ButtonGestureHandler {
             clearTimeout(this.resolveTimer);
             this.resolveTimer = null;
             this.gestureState = 'idle';
-            this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'double_press', button, correlation_id: correlationId });
+            this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'double_press', button, ...corr });
         }
     }
 }
@@ -95,6 +95,8 @@ export class TriggerEngine {
     buttonHandlers = new Map();
     regexButtonTriggers = [];
     durationTimers = new Map();
+    subscribedTopics = new Set();
+    started = false;
     constructor(registry, haClient, onMatch, mqttClient, metrics) {
         this.registry = registry;
         this.haClient = haClient;
@@ -102,7 +104,38 @@ export class TriggerEngine {
         this.mqttClient = mqttClient;
         this.metrics = metrics;
         this.rebuildButtonHandlers();
-        registry.onChange(() => this.rebuildButtonHandlers());
+        registry.onChange(() => {
+            this.rebuildButtonHandlers();
+            this.syncMqttSubscriptions();
+        });
+    }
+    // Reconciles the set of subscribed mqtt_in topics against the registry's current
+    // automations. Called on start() and again whenever the registry changes (hot
+    // reload / git-sync rescan) so topics added or removed after startup take effect.
+    syncMqttSubscriptions() {
+        if (!this.mqttClient || !this.started)
+            return;
+        const desired = new Set();
+        for (const automation of this.registry.getAll()) {
+            for (const trigger of automation.triggers) {
+                if (trigger.type === 'mqtt_in')
+                    desired.add(trigger.topic);
+            }
+        }
+        for (const topic of desired) {
+            if (!this.subscribedTopics.has(topic)) {
+                this.mqttClient.subscribe(topic);
+                this.subscribedTopics.add(topic);
+                console.log(`[trigger-engine] mqtt subscribed: ${topic}`);
+            }
+        }
+        for (const topic of this.subscribedTopics) {
+            if (!desired.has(topic)) {
+                this.mqttClient.unsubscribe(topic);
+                this.subscribedTopics.delete(topic);
+                console.log(`[trigger-engine] mqtt unsubscribed: ${topic}`);
+            }
+        }
     }
     rebuildButtonHandlers() {
         this.buttonHandlers.clear();
@@ -137,6 +170,12 @@ export class TriggerEngine {
             .then(() => {
             this.haClient.on('state_changed', (event) => {
                 this.metrics?.incrementCounter('homerun_ha_events_received_total', { event_type: 'state_changed' });
+                const corr = {
+                    correlation_id: event.correlation_id,
+                    ...(event.parent_correlation_id && { parent_correlation_id: event.parent_correlation_id }),
+                    ...(event.root_correlation_id && { root_correlation_id: event.root_correlation_id }),
+                    ...(event.parent_automation_id && { parent_automation_id: event.parent_automation_id }),
+                };
                 let handler = this.buttonHandlers.get(event.entity_id);
                 if (!handler) {
                     const matchingGestures = new Set();
@@ -152,7 +191,7 @@ export class TriggerEngine {
                     }
                 }
                 if (handler) {
-                    handler.handle(event.new_state.state, event.correlation_id);
+                    handler.handle(event.new_state.state, corr);
                 }
                 else {
                     this.dispatch({
@@ -160,7 +199,7 @@ export class TriggerEngine {
                         entity_id: event.entity_id,
                         old_state: event.old_state,
                         new_state: event.new_state,
-                        correlation_id: event.correlation_id,
+                        ...corr,
                     });
                 }
             });
@@ -169,16 +208,8 @@ export class TriggerEngine {
             console.error('[trigger-engine] failed to start:', err);
         });
         if (this.mqttClient) {
-            const topics = new Set();
-            for (const automation of this.registry.getAll()) {
-                for (const trigger of automation.triggers) {
-                    if (trigger.type === 'mqtt_in')
-                        topics.add(trigger.topic);
-                }
-            }
-            for (const topic of topics) {
-                this.mqttClient.subscribe(topic);
-            }
+            this.started = true;
+            this.syncMqttSubscriptions();
             this.mqttClient.subscribe('homerun/trigger/+');
             this.mqttClient.on('message', (topic, payload) => {
                 if (topic.startsWith('homerun/trigger/')) {
@@ -188,14 +219,17 @@ export class TriggerEngine {
                         console.warn(`[trigger-engine] manual trigger: no automation with id "${automationId}"`);
                         return;
                     }
-                    this.onMatch(automation, { type: 'on_start', correlation_id: crypto.randomUUID() });
+                    const correlation_id = crypto.randomUUID();
+                    this.onMatch(automation, { type: 'on_start', correlation_id, root_correlation_id: correlation_id });
                     return;
                 }
+                const correlation_id = `mqtt-${Date.now()}`;
                 this.dispatch({
                     type: 'mqtt_in',
                     topic,
                     payload: payload.toString(),
-                    correlation_id: `mqtt-${Date.now()}`,
+                    correlation_id,
+                    root_correlation_id: correlation_id,
                 });
             });
         }

package/dist/src/index.js

@@ -115,7 +115,8 @@ haClient.on('reconnected', () => {
 await haClient.connect(config.homeassistant.url, config.homeassistant.token);
 await haClient.ready;
 haReady = true;
-console.log(`[homerun] ready — ${haClient.entityCount} entities cached`);
+const { labels, areas } = haClient.registryStats;
+console.log(`[homerun] ready — ${haClient.entityCount} entities cached (${labels} labels, ${areas} areas)`);
 eventPublisher.publishLifecycle('server_started', registry.getAll().length, dryRun);
 // 8. Graceful SIGTERM shutdown.
 process.on('SIGTERM', () => {

package/dist/src/types/actions.d.ts

@@ -11,6 +11,7 @@ export type Action = {
     topic: string;
     payload: string;
     retain?: boolean;
+    impliesEntity?: string;
 } | {
     type: 'timer.start';
     timerKey: string;

package/dist/src/types/triggers.d.ts

@@ -25,6 +25,8 @@ export type Trigger = {
 type TriggerEventBase = {
     correlation_id: string;
     parent_correlation_id?: string;
+    root_correlation_id?: string;
+    parent_automation_id?: string;
 };
 export type TriggerEvent = TriggerEventBase & ({
     type: 'state_changed';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ajclarkson/homerun",
   "type": "module",
-  "version": "0.0.1-edge.c7ffb3a",
+  "version": "0.0.1-edge.ced2eaa",
   "description": "TypeScript automation framework for Home Assistant",
   "files": [
     "dist"