@ajclarkson/homerun 0.0.1-edge.f81eb62 → 0.0.1-edge.fc9ccb3

package/README.md

@@ -131,6 +131,7 @@ const ctx = kitchenLights.context(mockState, mockHAContext);
 | `on_start` | The system is ready and the state cache is fully populated. |
 | `timer_expired` | A named timer set by a previous `timer.start` action expires. |
 | `button` | A Zigbee button entity emits a `single_press`, `double_press`, or `hold` gesture. |
+| `mqtt_in` | A message arrives on a subscribed MQTT topic. |
 
 ```typescript
 triggers: [
@@ -192,7 +193,7 @@ Every pipeline run publishes a decision snapshot to MQTT — whether it complete
   "automation_id": "kitchen:lighting",
   "location": "kitchen",
   "subsystem": "lighting",
-  "type": "decision",
+  "event_type": "decision",
   "decision": "lights_on",
   "inputs": { "motion": true, "lux": 20, "luxThreshold": 40 },
   "actions": [{ "type": "ha.call_service", "domain": "light", "service": "turn_on" }],
@@ -230,6 +231,21 @@ Set `DRY_RUN=true` to run the full pipeline — context, reduce, observability
 
 ---
 
+## API
+
+The server exposes an HTTP API on port `7070` by default.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health/live` | Always returns `200 { status: "live" }` — used for liveness probes. |
+| `GET` | `/health/ready` | Returns `200` when the HA state cache is populated and automations are loaded, `503` while starting. Response includes `entities`, `automations` counts, and `dry_run: true` if running in dry-run mode. |
+| `GET` | `/automations` | Lists all registered automations with their `id`, `location`, `subsystem`, and trigger types. |
+| `POST` | `/automations/:id/trigger` | Manually fires an `on_start` event for the given automation. |
+| `POST` | `/reload` | Rescans the automations directory and hot-reloads changed files. |
+| `GET` | `/events` | Server-sent event stream of all pipeline decisions and action events in real time. |
+
+---
+
 ## Architecture
 
 ```

package/dist/scripts/generate-ha-services.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+export interface HAServicePayload {
+    domain: string;
+    services: Record<string, HAServiceDef>;
+}
+export interface HAServiceDef {
+    fields: Record<string, HAServiceField>;
+    target?: unknown;
+}
+export interface HAServiceField {
+    required?: boolean;
+    selector?: Record<string, unknown>;
+    advanced?: boolean;
+}
+export declare function inferFieldType(field: HAServiceField): string;
+export declare function generateFileContent(services: HAServicePayload[], domains?: string[]): string;

package/dist/scripts/generate-ha-services.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+// ---------- Type inference ----------
+export function inferFieldType(field) {
+    const selector = field.selector;
+    if (!selector)
+        return 'unknown';
+    const key = Object.keys(selector)[0];
+    if (!key)
+        return 'unknown';
+    switch (key) {
+        case 'number':
+        case 'color_temp':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'color_rgb':
+            return '[number, number, number]';
+        case 'duration':
+            return '{ hours?: number; minutes?: number; seconds?: number }';
+        case 'object':
+            return 'Record<string, unknown>';
+        default:
+            return 'string';
+    }
+}
+// ---------- Service builder generation ----------
+function generateServiceBuilder(domain, service, def) {
+    const hasTarget = !!def.target;
+    const fieldEntries = Object.entries(def.fields ?? {});
+    const hasFields = fieldEntries.length > 0;
+    const params = [];
+    if (hasTarget)
+        params.push('target: { entity_id: string }');
+    let anyRequired = false;
+    if (hasFields) {
+        anyRequired = fieldEntries.some(([, f]) => f.required);
+        const fieldDefs = fieldEntries
+            .map(([name, field]) => `${name}${field.required ? '' : '?'}: ${inferFieldType(field)}`)
+            .join('; ');
+        params.push(`data${anyRequired ? '' : '?'}: { ${fieldDefs} }`);
+    }
+    const bodyParts = [
+        `type: 'ha.call_service'`,
+        `domain: '${domain}'`,
+        `service: '${service}'`,
+    ];
+    if (hasTarget)
+        bodyParts.push('target');
+    if (hasFields) {
+        bodyParts.push(`data: data as Record<string, unknown>${anyRequired ? '' : ' | undefined'}`);
+    }
+    return `    ${service}: (${params.join(', ')}): Action => ({ ${bodyParts.join(', ')} })`;
+}
+// ---------- File generation ----------
+export function generateFileContent(services, domains) {
+    const filtered = domains
+        ? services.filter(({ domain }) => domains.includes(domain))
+        : services;
+    const domainBlocks = filtered.map(({ domain, services: svcMap }) => {
+        const builders = Object.entries(svcMap)
+            .map(([service, def]) => generateServiceBuilder(domain, service, def))
+            .join(',\n');
+        return `  ${domain}: {\n${builders},\n  }`;
+    });
+    const domainsNote = domains ? `\n// domains: ${domains.join(', ')}` : '';
+    const blockStr = domainBlocks.length > 0 ? `\n${domainBlocks.join(',\n')},\n` : '';
+    return `// generated — do not edit — run: npm run generate:ha-services${domainsNote}
+import type { Action } from '@ajclarkson/homerun';
+
+export const Services = {${blockStr}};
+`;
+}
+// ---------- CLI ----------
+async function main() {
+    const url = process.env.HA_URL;
+    const token = process.env.HA_TOKEN;
+    if (!url || !token) {
+        console.error('Error: HA_URL and HA_TOKEN must be set');
+        process.exit(1);
+    }
+    const domainsArg = process.argv.find((a) => a.startsWith('--domains='));
+    const domains = domainsArg ? domainsArg.slice('--domains='.length).split(',') : undefined;
+    const res = await fetch(`${url}/api/services`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        console.error(`Error: HA API returned ${res.status} ${res.statusText}`);
+        process.exit(1);
+    }
+    const allServices = (await res.json());
+    const content = generateFileContent(allServices, domains);
+    const outPath = path.join(process.cwd(), 'types', 'ha-services.ts');
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, content, 'utf8');
+    const filtered = domains
+        ? allServices.filter(({ domain }) => domains.includes(domain))
+        : allServices;
+    const serviceCount = filtered.reduce((n, { services: s }) => n + Object.keys(s).length, 0);
+    const domainLabel = domains ? `${domains.length} selected` : `all ${allServices.length}`;
+    console.log(`Written ${serviceCount} services across ${domainLabel} domains to ${outPath}`);
+}
+if (process.argv[1]?.endsWith('generate-ha-services.ts') ||
+    process.argv[1]?.endsWith('generate-ha-services.js') ||
+    process.argv[1]?.endsWith('homerun-generate-ha-services')) {
+    main().catch((err) => {
+        console.error('Fatal:', err);
+        process.exit(1);
+    });
+}

package/dist/scripts/generate-ha-types.js

@@ -8,18 +8,14 @@ export function inferStateType(entity, allObservedStates) {
         case 'binary_sensor':
         case 'input_boolean':
         case 'switch':
-            return "'on' | 'off'";
+            return "'on' | 'off' | 'unavailable' | 'unknown'";
         case 'input_select': {
             const options = entity.attributes.options;
             if (Array.isArray(options) && options.length > 0) {
-                return options.map((o) => `'${o}'`).join(' | ');
+                return options.map((o) => `'${o}'`).join(' | ') + " | 'unavailable' | 'unknown'";
             }
             return 'string';
         }
-        case 'person': {
-            const states = allObservedStates ?? [entity.state];
-            return [...new Set(states)].map((s) => `'${s}'`).join(' | ');
-        }
         default:
             return 'string';
     }
@@ -37,18 +33,16 @@ export function generateFileContent(states) {
     const entries = states
         .map((s) => {
         const stateType = inferStateType(s, personStates.get(s.entity_id));
-        return `  '${s.entity_id}': { state: ${stateType} };`;
+        return `    '${s.entity_id}': { state: ${stateType} };`;
     })
         .join('\n');
     return `// generated — do not edit — run: npm run generate:ha-types
-export interface HAEntities {
+declare global {
+  interface HAEntities {
 ${entries}
+  }
 }
-
-export type HAState = {
-  <E extends keyof HAEntities>(entity: E): HAEntities[E]['state'];
-  <E extends string>(entity: E): string | undefined;
-};
+export {};
 `;
 }
 // ---------- CLI ----------

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

@@ -2,26 +2,38 @@ import type { MqttClient } from 'mqtt';
 import type { Action } from '../types/actions.js';
 import type { HAClient } from './ha-client.js';
 import type { TimerManager } from './timer-manager.js';
-import type { Observability } from './observability.js';
+import type { EventPublisher } from './event-publisher.js';
+import type { MetricsBackend } from './metrics.js';
 export interface ExecutionContext {
     correlationId: string;
     automationId: string;
     location: string;
     subsystem: string;
+    rootCorrelationId?: string;
+    parentCorrelationId?: string;
+    parentAutomationId?: string;
 }
 interface Deps {
     haClient: HAClient;
     mqttClient: MqttClient;
     timerManager: TimerManager;
-    observability: Observability;
+    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

@@ -1,7 +1,90 @@
+function safeStringify(err) {
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        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) {
@@ -9,24 +92,64 @@ export class ActionRuntime {
         }
     }
     async runAction(action, ctx) {
-        this.deps.observability.publishActionEvent(this.makeEvent(ctx, 'action_started', action));
+        const labels = { location: ctx.location, action_type: action.type };
+        this.deps.eventPublisher.publishActionEvent(this.makeStartedEvent(ctx, action));
+        this.deps.metrics?.incrementCounter('homerun_actions_dispatched_total', labels);
+        const start = performance.now();
         try {
             if (!this.deps.dryRun) {
-                await this.dispatch(action);
+                await this.dispatch(action, ctx);
             }
-            this.deps.observability.publishActionEvent(this.makeEvent(ctx, 'action_result', action, { reason: 'ok' }));
+            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.makeResultEvent(ctx, action, 'ok'));
         }
         catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
-            this.deps.observability.publishActionEvent(this.makeEvent(ctx, 'action_result', action, { reason }));
+            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 error = err instanceof Error
+                ? err.message
+                : typeof err === 'object' && err !== null
+                    ? safeStringify(err)
+                    : String(err);
+            this.deps.eventPublisher.publishActionEvent(this.makeResultEvent(ctx, action, 'error', error));
         }
     }
-    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);
+            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, {
+                        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':
@@ -41,18 +164,30 @@ export class ActionRuntime {
             }
         }
     }
-    makeEvent(ctx, 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,
-            type,
-            actions: [action],
             timestamp: new Date().toISOString(),
             ...(this.deps.dryRun ? { dry_run: true } : {}),
-            ...extra,
+            ...(ctx.parentCorrelationId && { parent_correlation_id: ctx.parentCorrelationId }),
+            ...(ctx.parentAutomationId && { parent_automation_id: ctx.parentAutomationId }),
+        };
+    }
+    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/api-server.d.ts

@@ -1,14 +1,20 @@
 import type { AutomationRegistry } from './registry.js';
-import type { Observability } from './observability.js';
+import type { EventPublisher } from './event-publisher.js';
 import type { Automation } from '../types/automation.js';
 import type { TriggerEvent } from '../types/triggers.js';
+export interface MetricsProvider {
+    getMetrics(): Promise<string>;
+    contentType: string;
+}
 export interface ApiServerDeps {
     registry: AutomationRegistry;
     onTrigger: (automation: Automation<unknown>, event: TriggerEvent) => void;
     onReload: () => Promise<void>;
     isReady: () => boolean;
     entityCount: () => number;
-    observability: Observability;
+    eventPublisher: EventPublisher;
+    dryRun?: boolean;
+    metrics?: MetricsProvider;
 }
 export declare class ApiServer {
     private readonly deps;
@@ -24,5 +30,6 @@ export declare class ApiServer {
     private postReload;
     private getHealthLive;
     private getHealthReady;
+    private getMetrics;
     private getEvents;
 }

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

@@ -41,6 +41,8 @@ export class ApiServer {
             return this.getHealthReady(res);
         if (method === 'GET' && url === '/events')
             return this.getEvents(req, res);
+        if (method === 'GET' && url === '/metrics')
+            return this.getMetrics(res);
         const triggerMatch = method === 'POST' && url.match(/^\/automations\/(.+)\/trigger$/);
         if (triggerMatch)
             return this.postTrigger(triggerMatch[1], res);
@@ -51,7 +53,8 @@ export class ApiServer {
             id: a.id,
             location: a.location,
             subsystem: a.subsystem,
-            triggerTypes: a.triggers.map((t) => t.type),
+            enabled: a.enabled ?? true,
+            triggers: a.triggers.map(serializeTrigger),
         }));
         json(res, 200, automations);
     }
@@ -61,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) {
@@ -84,6 +88,22 @@ export class ApiServer {
             status: 'ready',
             entities: this.deps.entityCount(),
             automations: this.deps.registry.getAll().length,
+            ...(this.deps.dryRun && { dry_run: true }),
+        });
+    }
+    getMetrics(res) {
+        if (!this.deps.metrics) {
+            json(res, 404, { error: 'metrics not enabled' });
+            return;
+        }
+        this.deps.metrics.getMetrics()
+            .then((output) => {
+            res.writeHead(200, { 'Content-Type': this.deps.metrics.contentType });
+            res.end(output);
+        })
+            .catch((err) => {
+            console.error('[ApiServer] metrics scrape failed:', err);
+            json(res, 500, { error: 'metrics scrape failed' });
         });
     }
     getEvents(req, res) {
@@ -93,12 +113,18 @@ export class ApiServer {
             Connection: 'keep-alive',
         });
         res.flushHeaders();
-        const unsubscribe = this.deps.observability.subscribe((event) => {
+        const unsubscribe = this.deps.eventPublisher.subscribe((event) => {
             res.write(`data: ${JSON.stringify(event)}\n\n`);
         });
         req.on('close', unsubscribe);
     }
 }
+function serializeTrigger(trigger) {
+    if (trigger.type === 'state_changed' && trigger.entity instanceof RegExp) {
+        return { ...trigger, entity: trigger.entity.toString() };
+    }
+    return trigger;
+}
 function json(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, { 'Content-Type': 'application/json' });

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

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+declare const ConfigSchema: z.ZodObject<{
+    homeassistant: z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>;
+    mqtt: z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>;
+    automations: z.ZodObject<{
+        dir: z.ZodString;
+    }, z.core.$strip>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        shutdown_timeout_ms: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>>;
+    options: z.ZodDefault<z.ZodObject<{
+        dry_run: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    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;
+export declare function loadConfig(configPath?: string): Promise<HomerunConfig>;
+export {};