@ajclarkson/homerun 0.0.1-edge.3ff83fe → 0.0.1-edge.465375

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

@@ -20,13 +20,20 @@ interface Deps {
     eventPublisher: EventPublisher;
     dryRun: boolean;
     metrics?: MetricsBackend;
+    commandAck?: {
+        enabled: boolean;
+        timeoutMs: number;
+    };
 }
 export declare class ActionRuntime {
     private readonly deps;
     constructor(deps: Deps);
+    private handleAckTimeout;
     execute(actions: Action[], ctx: ExecutionContext): Promise<void>;
     private runAction;
     private dispatch;
-    private makeEvent;
+    private baseFields;
+    private makeStartedEvent;
+    private makeResultEvent;
 }
 export {};

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

@@ -6,10 +6,85 @@ function safeStringify(err) {
         return String(err);
     }
 }
+// HA `data` keys are conventionally the same name as the attribute they end up setting
+// (temperature, brightness, position, ...) — true across core and third-party integrations
+// as a platform-wide naming convention, not something homerun needs to hand-map per service.
+// These are the known exceptions: call parameters that don't name a resulting attribute.
+const NON_ATTRIBUTE_DATA_KEYS = new Set(['transition', 'entity_id']);
+// `set_value` on these domains sets the entity's top-level `state` directly — unlike most
+// services, where a `data` key names the attribute it ends up on, these have no attribute
+// called `value` at all. Found the hard way (#153): computeExpectedAck's generic convention
+// falsely flagged every number/input_text room-sensor feed call as an ack timeout, since
+// `attributes.value` never existed to satisfy.
+const SET_VALUE_TO_STATE_DOMAINS = new Set(['number', 'input_number', 'input_text', 'input_select', 'text']);
+// Domains/services excluded from tracking entirely rather than guessing at a convention that
+// doesn't hold cleanly — group membership attributes don't reliably come back as an exact
+// match of what was passed (ordering, or reflecting the whole group rather than the delta).
+// scene.turn_on is here for a different reason (#156): a scene entity's `state` is a
+// last-activated timestamp, not 'on'/'off', so the generic turn_on special-case never
+// matches — and even a timestamp-based check would only confirm HA accepted the call, not
+// that the scene's member entities (the things that actually matter) responded. Real
+// coverage would mean tracking each member entity individually — see #155.
+const UNTRACKED_SERVICES = new Set(['media_player.join', 'media_player.unjoin', 'scene.turn_on']);
+// Computes the field/attribute -> value map a dispatched call is expected to produce, or
+// undefined if there's nothing to track (no inferable fields, an excluded service, or the
+// entity already matches every expected field — an idempotent call that legitimately produces
+// no state_changed at all). See #55's design discussion for why this is convention-based
+// rather than a per-service table.
+function computeExpectedAck(action, current) {
+    if (UNTRACKED_SERVICES.has(`${action.domain}.${action.service}`))
+        return undefined;
+    const expected = {};
+    if (action.service === 'turn_on') {
+        expected.state = 'on';
+    }
+    else if (action.service === 'turn_off') {
+        expected.state = 'off';
+    }
+    else if (action.service === 'set_value' && SET_VALUE_TO_STATE_DOMAINS.has(action.domain) && action.data?.value !== undefined) {
+        expected.state = action.data.value;
+    }
+    for (const [key, value] of Object.entries(action.data ?? {})) {
+        if (NON_ATTRIBUTE_DATA_KEYS.has(key))
+            continue;
+        if ('state' in expected && key === 'value' && SET_VALUE_TO_STATE_DOMAINS.has(action.domain))
+            continue;
+        expected[key] = value;
+    }
+    if (Object.keys(expected).length === 0)
+        return undefined;
+    // See ha-client.ts's ackSatisfied for why `state` needs string coercion (#158) — the same
+    // number-vs-string gap applies here to the idempotency pre-check.
+    const alreadySatisfied = Object.entries(expected).every(([key, value]) => key === 'state' ? current !== undefined && String(current.state) === String(value) : current?.attributes[key] === value);
+    if (alreadySatisfied)
+        return undefined;
+    return expected;
+}
 export class ActionRuntime {
     deps;
     constructor(deps) {
         this.deps = deps;
+        this.deps.haClient.on('action_ack_timeout', (e) => this.handleAckTimeout(e));
+    }
+    handleAckTimeout(e) {
+        this.deps.metrics?.incrementCounter('homerun_action_ack_timeout_total', {
+            location: e.location,
+            action_type: e.action.type,
+        });
+        this.deps.eventPublisher.publishActionEvent({
+            schema: 'home.events.v2',
+            correlation_id: e.correlationId,
+            root_correlation_id: e.rootCorrelationId ?? e.correlationId,
+            automation_id: e.automationId,
+            location: e.location,
+            subsystem: e.subsystem,
+            timestamp: new Date().toISOString(),
+            ...(this.deps.dryRun ? { dry_run: true } : {}),
+            event_type: 'action_ack_timeout',
+            action: e.action,
+            entity: e.entity_id,
+            expected: e.expected,
+        });
     }
     async execute(actions, ctx) {
         for (const action of actions) {
@@ -18,7 +93,7 @@ export class ActionRuntime {
     }
     async runAction(action, ctx) {
         const labels = { location: ctx.location, action_type: action.type };
-        this.deps.eventPublisher.publishActionEvent(this.makeEvent(ctx, 'action_started', action));
+        this.deps.eventPublisher.publishActionEvent(this.makeStartedEvent(ctx, action));
         this.deps.metrics?.incrementCounter('homerun_actions_dispatched_total', labels);
         const start = performance.now();
         try {
@@ -28,29 +103,45 @@ 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_succeeded_total', labels);
-            this.deps.eventPublisher.publishActionEvent(this.makeEvent(ctx, 'action_result', action, { reason: 'ok' }));
+            this.deps.eventPublisher.publishActionEvent(this.makeResultEvent(ctx, action, 'ok'));
         }
         catch (err) {
             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
+            const error = 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 }));
+            this.deps.eventPublisher.publishActionEvent(this.makeResultEvent(ctx, action, 'error', error));
         }
     }
     async dispatch(action, ctx) {
         switch (action.type) {
-            case 'ha.call_service':
+            case 'ha.call_service': {
+                const entityId = action.target?.entity_id;
+                if (this.deps.commandAck?.enabled && entityId) {
+                    const expected = computeExpectedAck(action, this.deps.haClient.state(entityId));
+                    if (expected) {
+                        this.deps.haClient.registerPendingAck(entityId, {
+                            correlationId: ctx.correlationId,
+                            rootCorrelationId: ctx.rootCorrelationId,
+                            automationId: ctx.automationId,
+                            location: ctx.location,
+                            subsystem: ctx.subsystem,
+                            action,
+                            expected,
+                        }, this.deps.commandAck.timeoutMs);
+                    }
+                }
                 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, {
@@ -73,21 +164,30 @@ export class ActionRuntime {
             }
         }
     }
-    makeEvent(ctx, event_type, action, extra = {}) {
+    baseFields(ctx) {
         return {
-            schema: 'home.events.v1',
+            schema: 'home.events.v2',
             correlation_id: ctx.correlationId,
             root_correlation_id: ctx.rootCorrelationId ?? ctx.correlationId,
             automation_id: ctx.automationId,
             location: ctx.location,
             subsystem: ctx.subsystem,
-            event_type,
-            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,
+        };
+    }
+    makeStartedEvent(ctx, action) {
+        return { ...this.baseFields(ctx), event_type: 'action_started', action };
+    }
+    makeResultEvent(ctx, action, status, error) {
+        return {
+            ...this.baseFields(ctx),
+            event_type: 'action_result',
+            action,
+            status,
+            ...(error !== undefined && { error }),
         };
     }
 }

package/dist/src/framework/config.d.ts

@@ -20,6 +20,13 @@ declare const ConfigSchema: z.ZodObject<{
     metrics: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    events: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    commandAck: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        timeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type HomerunConfig = z.infer<typeof ConfigSchema>;
 export declare function parseConfig(configContent: string, secretsContent?: string): HomerunConfig;

package/dist/src/framework/config.js

@@ -9,6 +9,8 @@ function isSecretRef(v) {
 const secretTag = defineScalarTag('!secret', {
     implicit: false,
     resolve: (source) => ({ __secret: source }),
+    // Load-only tag — config is never dumped back to YAML, so identify() is unreachable.
+    identify: () => false,
 });
 const SCHEMA_WITH_SECRET = CORE_SCHEMA.withTags(secretTag);
 const ConfigSchema = z.object({
@@ -32,6 +34,17 @@ const ConfigSchema = z.object({
     metrics: z.object({
         enabled: z.boolean().default(false),
     }).default({ enabled: false }),
+    events: z.object({
+        // Defaults to true — preserves existing behaviour for deployments that don't set this.
+        enabled: z.boolean().default(true),
+    }).default({ enabled: true }),
+    commandAck: z.object({
+        // Opt-in: unlike events.enabled, this is new/experimental behaviour with no prior
+        // installed base to preserve, so it defaults off rather than needing a reason to disable.
+        enabled: z.boolean().default(false),
+        // Needs to accommodate slow Zigbee mesh round-trips, not just fast local calls.
+        timeoutMs: z.coerce.number().int().min(0).default(8_000),
+    }).default({ enabled: false, timeoutMs: 8_000 }),
 });
 function resolveSecrets(value, secrets) {
     if (isSecretRef(value)) {

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

@@ -1,22 +1,46 @@
 import type { MqttClient } from 'mqtt';
 import type { Action } from '../types/actions.js';
-export interface ObsEvent {
-    schema: 'home.events.v1';
+import type { TriggerSummary } from '../types/triggers.js';
+type ObsEventBase = {
+    schema: 'home.events.v2';
     correlation_id: string;
-    root_correlation_id?: string;
+    root_correlation_id: string;
     parent_correlation_id?: string;
     parent_automation_id?: string;
     automation_id: string;
     location: string;
     subsystem: string;
-    event_type: 'decision' | 'abort' | 'action_started' | 'action_result';
-    decision?: string;
-    reason?: string;
-    inputs?: Record<string, unknown>;
-    actions?: Action[];
-    dry_run?: boolean;
     timestamp: string;
-}
+    dry_run?: boolean;
+};
+export type ObsEvent = ObsEventBase & ({
+    event_type: 'decision';
+    trigger: TriggerSummary;
+    decision: string;
+    reason?: string;
+    conditions?: Record<string, unknown>;
+    actions: Action[];
+    hasAction: boolean;
+} | {
+    event_type: 'abort';
+    trigger: TriggerSummary;
+    abort_kind: 'disabled' | 'unhandled_error' | 'guard' | 'unavailable_input';
+    reason?: string;
+    entity?: string;
+} | {
+    event_type: 'action_started';
+    action: Action;
+} | {
+    event_type: 'action_result';
+    action: Action;
+    status: 'ok' | 'error';
+    error?: string;
+} | {
+    event_type: 'action_ack_timeout';
+    action: Action;
+    entity: string;
+    expected: Record<string, unknown>;
+});
 export type LifecycleEventType = 'server_started' | 'server_stopping' | 'rescan_complete' | 'ha_reconnected';
 export interface LifecycleEvent {
     schema: 'home.lifecycle.v1';
@@ -27,11 +51,15 @@ export interface LifecycleEvent {
 }
 export declare class EventPublisher {
     private readonly mqtt;
+    private readonly enabled;
     private readonly listeners;
-    constructor(mqtt: MqttClient);
+    constructor(mqtt: MqttClient, enabled?: boolean);
     subscribe(listener: (event: ObsEvent) => void): () => void;
     publishDecision(event: ObsEvent): void;
     publishActionEvent(event: ObsEvent): void;
     publishLifecycle(type: LifecycleEventType, automationCount: number, dryRun?: boolean): void;
     private publish;
+    private safeSerialize;
+    private notifyListeners;
 }
+export {};

package/dist/src/framework/event-publisher.js

@@ -1,8 +1,14 @@
 export class EventPublisher {
     mqtt;
+    enabled;
     listeners = [];
-    constructor(mqtt) {
+    // `enabled` gates MQTT publishing of decision/action ObsEvents only (mirrors metrics.enabled;
+    // see #144) — publishLifecycle (status/online heartbeat) is unaffected, and listeners (the
+    // /events SSE endpoint, any future persistent store) are always notified regardless, so
+    // consumers that don't want the MQTT stream aren't forced to lose in-process observability too.
+    constructor(mqtt, enabled = true) {
         this.mqtt = mqtt;
+        this.enabled = enabled;
     }
     subscribe(listener) {
         this.listeners.push(listener);
@@ -13,18 +19,25 @@ export class EventPublisher {
         };
     }
     publishDecision(event) {
-        const payload = JSON.stringify(event);
-        const ns = event.dry_run ? 'homerun/dev' : 'homerun';
-        this.publish(`${ns}/events`, payload, false);
-        this.publish(`${ns}/${event.location}/${event.subsystem}/decision`, payload, true);
-        for (const l of this.listeners)
-            l(event);
+        if (this.enabled) {
+            const payload = this.safeSerialize(event);
+            if (payload !== undefined) {
+                const ns = event.dry_run ? 'homerun/dev' : 'homerun';
+                this.publish(`${ns}/events`, payload, false);
+                this.publish(`${ns}/${event.location}/${event.subsystem}/decision`, payload, true);
+            }
+        }
+        this.notifyListeners(event);
     }
     publishActionEvent(event) {
-        const ns = event.dry_run ? 'homerun/dev' : 'homerun';
-        this.publish(`${ns}/events`, JSON.stringify(event), false);
-        for (const l of this.listeners)
-            l(event);
+        if (this.enabled) {
+            const payload = this.safeSerialize(event);
+            if (payload !== undefined) {
+                const ns = event.dry_run ? 'homerun/dev' : 'homerun';
+                this.publish(`${ns}/events`, payload, false);
+            }
+        }
+        this.notifyListeners(event);
     }
     publishLifecycle(type, automationCount, dryRun = false) {
         const event = {
@@ -44,4 +57,29 @@ export class EventPublisher {
             console.error(`[EventPublisher] MQTT publish failed on ${topic}:`, err);
         });
     }
+    // Observability must never affect automation behaviour — a decision/action event that fails
+    // to serialize (e.g. conditions defaulting to a context object with a circular reference) must
+    // not throw, since runPipeline awaits this alongside actionRuntime.execute() in the same
+    // Promise.all; a synchronous throw here would silently prevent real actions from ever running.
+    safeSerialize(event) {
+        try {
+            return JSON.stringify(event);
+        }
+        catch (err) {
+            console.error(`[EventPublisher] failed to serialize ${event.event_type} event for ${event.automation_id} — MQTT publish skipped:`, err);
+            return undefined;
+        }
+    }
+    // Isolates listeners from each other and from the publisher — the same reliability principle
+    // applied to subscribers (e.g. the /events SSE endpoint) as to serialization above.
+    notifyListeners(event) {
+        for (const l of this.listeners) {
+            try {
+                l(event);
+            }
+            catch (err) {
+                console.error('[EventPublisher] listener threw, continuing:', err);
+            }
+        }
+    }
 }

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

@@ -1,5 +1,6 @@
 import { type HassServiceTarget } from 'home-assistant-js-websocket';
 import { EventEmitter } from 'node:events';
+import type { Action } from '../types/actions.js';
 export interface EntityState {
     entity_id: string;
     state: string;
@@ -32,13 +33,27 @@ export interface WriteOrigin {
     rootCorrelationId?: string;
     automationId: string;
 }
+export interface AckOrigin {
+    correlationId: string;
+    rootCorrelationId?: string;
+    automationId: string;
+    location: string;
+    subsystem: string;
+    action: Action;
+    expected: Record<string, unknown>;
+}
+export interface AckTimeoutEvent extends AckOrigin {
+    entity_id: string;
+}
 export declare interface HAClient {
     on(event: 'state_changed', listener: (e: StateChangedEvent) => void): this;
     on(event: 'ready', listener: () => void): this;
     on(event: 'reconnected', listener: () => void): this;
+    on(event: 'action_ack_timeout', listener: (e: AckTimeoutEvent) => void): this;
     emit(event: 'state_changed', e: StateChangedEvent): boolean;
     emit(event: 'ready'): boolean;
     emit(event: 'reconnected'): boolean;
+    emit(event: 'action_ack_timeout', e: AckTimeoutEvent): boolean;
 }
 export declare class HAClient extends EventEmitter {
     private readonly stateCache;
@@ -46,6 +61,7 @@ export declare class HAClient extends EventEmitter {
     private readonly entityToLabels;
     private readonly areaToEntities;
     private readonly pendingWrites;
+    private readonly pendingAcks;
     private connection;
     private reconnecting;
     private _readyResolve;
@@ -59,6 +75,7 @@ export declare class HAClient extends EventEmitter {
     };
     callService(domain: string, service: string, target?: HassServiceTarget, data?: Record<string, unknown>, origin?: WriteOrigin): Promise<void>;
     registerPendingWrite(entityId: string, origin: WriteOrigin): void;
+    registerPendingAck(entityId: string, origin: AckOrigin, timeoutMs: number): void;
     disconnect(): void;
     connect(url: string, token: string): Promise<void>;
     private repopulateCache;

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

@@ -1,6 +1,12 @@
 import { callService, createConnection, createLongLivedTokenAuth, subscribeEntities, } from 'home-assistant-js-websocket';
 import { EventEmitter } from 'node:events';
 const PENDING_WRITE_TTL_MS = 2000;
+function ackSatisfied(expected, state) {
+    // HA represents every entity's state as a string, even numeric domains (number,
+    // input_number, ...) — a dispatched call's data.value is typically a plain JS number, so
+    // comparing `state` with strict equality never matches regardless of what HA does. See #158.
+    return Object.entries(expected).every(([key, value]) => key === 'state' ? String(state.state) === String(value) : state.attributes[key] === value);
+}
 export class HAClient extends EventEmitter {
     stateCache = new Map();
     labelToEntities = new Map();
@@ -9,6 +15,10 @@ export class HAClient extends EventEmitter {
     // 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();
+    // entity_id -> ack tracking for a dispatched call awaiting its expected state/attribute
+    // change. Consumed (timer cleared, deleted) the moment diffAndUpdate sees a satisfying
+    // state_changed; otherwise self-fires action_ack_timeout after its own timeout.
+    pendingAcks = 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.
@@ -47,6 +57,18 @@ export class HAClient extends EventEmitter {
         this.pendingWrites.set(entityId, origin);
         setTimeout(() => this.pendingWrites.delete(entityId), PENDING_WRITE_TTL_MS);
     }
+    // Registers that `entityId` is expected to reach `origin.expected` (a field/attribute ->
+    // value map) within `timeoutMs`. Consumed (timer cleared, deleted) by diffAndUpdate the
+    // moment a satisfying state_changed arrives; otherwise emits action_ack_timeout on expiry
+    // with the same origin, so a listener has everything needed to publish a self-sufficient
+    // ObsEvent without HAClient itself knowing about observability. See #55.
+    registerPendingAck(entityId, origin, timeoutMs) {
+        const timer = setTimeout(() => {
+            this.pendingAcks.delete(entityId);
+            this.emit('action_ack_timeout', { ...origin, entity_id: entityId });
+        }, timeoutMs);
+        this.pendingAcks.set(entityId, { ...origin, timer });
+    }
     disconnect() {
         this.connection?.close();
         this.connection = null;
@@ -104,9 +126,17 @@ export class HAClient extends EventEmitter {
         for (const [id, rawEntity] of Object.entries(entities)) {
             const old_state = this.stateCache.get(id);
             const new_state = toEntityState(id, rawEntity);
-            // last_updated changes whenever state or attributes change in HA.
-            if (!old_state || old_state.last_updated !== new_state.last_updated) {
+            // last_updated changes whenever state or attributes change in HA. It's also compared as
+            // a millisecond-precision string (see toEntityState), so two distinct state changes to
+            // the same entity within the same millisecond collide on last_updated alone — compare
+            // state directly too so a genuine transition is never silently dropped. See #170.
+            if (!old_state || old_state.state !== new_state.state || old_state.last_updated !== new_state.last_updated) {
                 this.stateCache.set(id, new_state);
+                const ack = this.pendingAcks.get(id);
+                if (ack && ackSatisfied(ack.expected, new_state)) {
+                    clearTimeout(ack.timer);
+                    this.pendingAcks.delete(id);
+                }
                 const correlation_id = crypto.randomUUID();
                 const origin = this.pendingWrites.get(id);
                 if (origin)

package/dist/src/framework/pipeline.js

@@ -1,4 +1,5 @@
-import { isAbort } from '../types/automation.js';
+import { summarizeTrigger } from '../types/triggers.js';
+import { isAbort, UnavailableInputError } from '../types/automation.js';
 export async function runPipeline(automation, event, haClient, deps) {
     deps.metrics?.incrementCounter('homerun_pipeline_runs_total', {
         location: automation.location,
@@ -7,8 +8,9 @@ export async function runPipeline(automation, event, haClient, deps) {
     const correlationId = event.correlation_id;
     const rootCorrelationId = event.root_correlation_id ?? correlationId;
     const timestamp = new Date().toISOString();
+    const trigger = summarizeTrigger(event);
     const base = {
-        schema: 'home.events.v1',
+        schema: 'home.events.v2',
         correlation_id: correlationId,
         root_correlation_id: rootCorrelationId,
         automation_id: automation.id,
@@ -21,7 +23,7 @@ export async function runPipeline(automation, event, haClient, deps) {
     };
     // Step 1: Enabled check
     if (automation.enabled === false) {
-        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', reason: 'disabled' });
+        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'disabled', trigger });
         return;
     }
     // Step 2: Context
@@ -29,12 +31,17 @@ export async function runPipeline(automation, event, haClient, deps) {
     try {
         ctx = automation.context(haClient.state, haClient.context, event);
     }
-    catch {
-        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', reason: 'unhandled_error' });
+    catch (err) {
+        if (err instanceof UnavailableInputError) {
+            deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'unavailable_input', entity: err.entityId, trigger });
+        }
+        else {
+            deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'unhandled_error', trigger });
+        }
         return;
     }
     if (isAbort(ctx)) {
-        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', reason: ctx.reason });
+        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'guard', reason: ctx.reason, trigger });
         return;
     }
     // Step 3: Reduce
@@ -43,18 +50,24 @@ export async function runPipeline(automation, event, haClient, deps) {
         result = automation.reduce(ctx);
     }
     catch {
-        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', reason: 'unhandled_error' });
+        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'unhandled_error', trigger });
         return;
     }
     // Step 4: Validate — safe defaults
     const actions = result.actions ?? [];
+    // Defaults to the full context object so authors get observability "for free" without
+    // hand-duplicating context fields into conditions — reduce() can still override with its
+    // own (e.g. trimmed) conditions when the full context isn't what should be published.
+    const conditions = result.conditions ?? ctx;
     const decision = {
         ...base,
         event_type: 'decision',
+        trigger,
         decision: result.decision,
         reason: result.reason,
-        inputs: result.inputs,
+        conditions,
         actions,
+        hasAction: actions.length > 0,
     };
     // Step 5: Fanout
     await Promise.all([

package/dist/src/index.js

@@ -38,7 +38,7 @@ await new Promise((resolve, reject) => {
 //    `engine` is assigned before any timer can fire.
 const haClient = new HAClient();
 const registry = new AutomationRegistry();
-const eventPublisher = new EventPublisher(mqtt);
+const eventPublisher = new EventPublisher(mqtt, config.events.enabled);
 let engine;
 const timerManager = new TimerManager((e) => engine.dispatch(e));
 const actionRuntime = new ActionRuntime({
@@ -48,6 +48,7 @@ const actionRuntime = new ActionRuntime({
     eventPublisher,
     dryRun,
     metrics: metricsBackend,
+    commandAck: config.commandAck,
 });
 // 3. Initial automation load — must complete before the engine and scheduler start.
 const automationsDir = path.resolve(config.automations.dir);

package/dist/src/lib.d.ts

@@ -1,4 +1,4 @@
-export { defineAutomation, abort } from './types/automation.js';
+export { defineAutomation, abort, requireState, requireNumericState, UnavailableInputError } from './types/automation.js';
 export type { Automation, Decision, Abort, HAState, HAContext } from './types/automation.js';
 export type { Trigger, TriggerEvent } from './types/triggers.js';
 export type { Action } from './types/actions.js';

package/dist/src/lib.js

@@ -1,2 +1,2 @@
-export { defineAutomation, abort } from './types/automation.js';
+export { defineAutomation, abort, requireState, requireNumericState, UnavailableInputError } from './types/automation.js';
 export { HomeAssistant } from './services.js';

package/dist/src/testing.d.ts

@@ -14,4 +14,5 @@ interface TestOptions {
 }
 export declare function testAutomation<C>(automation: Automation<C>, options: TestOptions): Decision;
 export declare function testAbort<C>(automation: Automation<C>, options: TestOptions): Abort;
+export declare function testUnavailable<C>(automation: Automation<C>, options: TestOptions): string;
 export {};

package/dist/src/testing.js

@@ -1,6 +1,6 @@
-import { isAbort } from './types/automation.js';
-function run(automation, options) {
-    const { event, state = {}, ha = {} } = options;
+import { isAbort, UnavailableInputError } from './types/automation.js';
+function buildStateAndHa(options) {
+    const { state = {}, ha = {} } = options;
     const stateFunc = (entityId) => {
         const entry = state[entityId];
         if (!entry)
@@ -18,10 +18,17 @@ function run(automation, options) {
         labelsFor: ha.labelsFor ?? (() => []),
         entitiesByArea: ha.entitiesByArea ?? (() => []),
     };
-    const ctx = automation.context(stateFunc, haContext, event);
+    return { stateFunc, haContext };
+}
+function run(automation, options) {
+    const { stateFunc, haContext } = buildStateAndHa(options);
+    const ctx = automation.context(stateFunc, haContext, options.event);
     if (isAbort(ctx))
         return ctx;
-    return automation.reduce(ctx);
+    const result = automation.reduce(ctx);
+    // Mirrors runPipeline's default in src/framework/pipeline.ts, so tests observe the same
+    // `conditions` a real run would publish.
+    return { ...result, conditions: result.conditions ?? ctx };
 }
 export function testAutomation(automation, options) {
     const result = run(automation, options);
@@ -35,3 +42,19 @@ export function testAbort(automation, options) {
         throw new Error(`expected abort but got decision: ${result.decision}`);
     return result;
 }
+// For automations using requireState()/requireNumericState(), which throw
+// UnavailableInputError rather than returning Abort — testAbort() can't observe these since
+// run() never catches an exception thrown out of context(). Returns the entity id the
+// automation required, so tests can assert on which input was missing.
+export function testUnavailable(automation, options) {
+    const { stateFunc, haContext } = buildStateAndHa(options);
+    try {
+        automation.context(stateFunc, haContext, options.event);
+    }
+    catch (err) {
+        if (err instanceof UnavailableInputError)
+            return err.entityId;
+        throw err;
+    }
+    throw new Error('expected UnavailableInputError but context() completed normally');
+}

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

@@ -1,4 +1,4 @@
-export type Action = {
+export interface HaCallServiceAction {
     type: 'ha.call_service';
     domain: string;
     service: string;
@@ -6,7 +6,8 @@ export type Action = {
         entity_id: string;
     };
     data?: Record<string, unknown>;
-} | {
+}
+export type Action = HaCallServiceAction | {
     type: 'mqtt.publish';
     topic: string;
     payload: string;

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

@@ -6,7 +6,7 @@ export interface Decision {
     decision: string;
     reason?: string;
     actions: Action[];
-    inputs?: Record<string, unknown>;
+    conditions?: Record<string, unknown>;
 }
 export type Abort = {
     abort: true;
@@ -14,6 +14,12 @@ export type Abort = {
 };
 export declare const abort: (reason: string) => Abort;
 export declare function isAbort(value: unknown): value is Abort;
+export declare class UnavailableInputError extends Error {
+    readonly entityId: string;
+    constructor(entityId: string);
+}
+export declare function requireState(state: HAState, entityId: Parameters<HAState>[0]): string;
+export declare function requireNumericState(state: HAState, entityId: Parameters<HAState>[0]): number;
 export interface Automation<C> {
     id: string;
     location: string;

package/dist/src/types/automation.js

@@ -2,6 +2,41 @@ export const abort = (reason) => ({ abort: true, reason });
 export function isAbort(value) {
     return typeof value === 'object' && value !== null && value.abort === true;
 }
+// ---------- Required state ----------
+// Covers the dominant abort() pattern found across real automations (~70% of call sites,
+// per #142's audit): a required entity's state is missing or invalid, so context() can't
+// proceed. Thrown, not returned — pipeline.ts already wraps context() in try/catch, so this
+// collapses `const x = state(id)?.state; if (x === undefined) return abort(...)` at every call
+// site down to one line, with no per-call guard needed. Caught specially in pipeline.ts and
+// classified as abort_kind: 'unavailable_input' with the entity name, distinct from a genuine
+// bug (abort_kind: 'unhandled_error').
+export class UnavailableInputError extends Error {
+    entityId;
+    constructor(entityId) {
+        super(`required entity unavailable: ${entityId}`);
+        this.entityId = entityId;
+        this.name = 'UnavailableInputError';
+    }
+}
+// HA's own sentinel values for "entity is registered but not producing readings" — an
+// offline zigbee device, an integration that hasn't polled yet. Distinct from the entity
+// key being absent from the state cache entirely, but the same "unavailable" in practice:
+// every real audited call site treated these three cases identically.
+const HA_UNAVAILABLE_STATES = new Set(['unavailable', 'unknown']);
+export function requireState(state, entityId) {
+    const value = state(entityId)?.state;
+    if (value === undefined || HA_UNAVAILABLE_STATES.has(value)) {
+        throw new UnavailableInputError(String(entityId));
+    }
+    return value;
+}
+export function requireNumericState(state, entityId) {
+    const raw = requireState(state, entityId);
+    const parsed = parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        throw new UnavailableInputError(String(entityId));
+    return parsed;
+}
 // Identity function — provides type inference on C so the reduce argument
 // is typed correctly without the user annotating the context shape explicitly.
 export function defineAutomation(automation) {

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

@@ -51,4 +51,27 @@ export type TriggerEvent = TriggerEventBase & ({
     topic: string;
     payload: string;
 });
+export type TriggerSummary = {
+    type: 'state_changed';
+    entity_id: string;
+    to: string;
+    from?: string;
+} | {
+    type: 'schedule';
+    cron: string;
+} | {
+    type: 'on_start';
+} | {
+    type: 'timer_expired';
+    timerKey: string;
+} | {
+    type: 'button';
+    entity_id: string;
+    gesture: 'single_press' | 'double_press' | 'hold';
+    button?: string;
+} | {
+    type: 'mqtt_in';
+    topic: string;
+};
+export declare function summarizeTrigger(event: TriggerEvent): TriggerSummary;
 export {};

package/dist/src/types/triggers.js

@@ -1 +1,26 @@
-export {};
+export function summarizeTrigger(event) {
+    switch (event.type) {
+        case 'state_changed':
+            return {
+                type: 'state_changed',
+                entity_id: event.entity_id,
+                to: event.new_state.state,
+                ...(event.old_state && { from: event.old_state.state }),
+            };
+        case 'schedule':
+            return { type: 'schedule', cron: event.cron };
+        case 'on_start':
+            return { type: 'on_start' };
+        case 'timer_expired':
+            return { type: 'timer_expired', timerKey: event.timerKey };
+        case 'button':
+            return {
+                type: 'button',
+                entity_id: event.entity_id,
+                gesture: event.gesture,
+                ...(event.button !== undefined && { button: event.button }),
+            };
+        case 'mqtt_in':
+            return { type: 'mqtt_in', topic: event.topic };
+    }
+}

package/package.json

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