@switchbot/openapi-cli 3.0.0 → 3.1.1

package/dist/lib/plan-store.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export const PLANS_DIR = path.join(os.homedir(), '.switchbot', 'plans');
+function ensurePlansDir() {
+    fs.mkdirSync(PLANS_DIR, { recursive: true, mode: 0o700 });
+}
+function planPath(planId) {
+    return path.join(PLANS_DIR, `${planId}.json`);
+}
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertValidPlanId(planId) {
+    if (!UUID_V4_RE.test(planId)) {
+        throw new Error(`invalid planId: ${planId}`);
+    }
+}
+export function savePlanRecord(plan) {
+    ensurePlansDir();
+    const record = {
+        planId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        status: 'pending',
+        plan,
+    };
+    fs.writeFileSync(planPath(record.planId), JSON.stringify(record, null, 2), { mode: 0o600 });
+    return record;
+}
+export function loadPlanRecord(planId) {
+    assertValidPlanId(planId);
+    try {
+        const raw = fs.readFileSync(planPath(planId), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function updatePlanRecord(planId, updates) {
+    assertValidPlanId(planId);
+    const record = loadPlanRecord(planId);
+    if (!record)
+        throw new Error(`Plan ${planId} not found in ${PLANS_DIR}`);
+    const updated = { ...record, ...updates };
+    fs.writeFileSync(planPath(planId), JSON.stringify(updated, null, 2), { mode: 0o600 });
+    return updated;
+}
+export function listPlanRecords() {
+    try {
+        if (!fs.existsSync(PLANS_DIR))
+            return [];
+        return fs
+            .readdirSync(PLANS_DIR)
+            .filter((f) => f.endsWith('.json'))
+            .flatMap((f) => {
+            try {
+                return [JSON.parse(fs.readFileSync(path.join(PLANS_DIR, f), 'utf-8'))];
+            }
+            catch {
+                return [];
+            }
+        })
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/policy/schema/v0.2.json

@@ -130,10 +130,39 @@
               "type": "string",
               "pattern": "^\\d+[smh]$",
               "description": "Minimum spacing between fires, e.g. \"10m\". Later triggers inside the window are suppressed and audited."
+            },
+            "dedupe_window": {
+              "type": "string",
+              "pattern": "^\\d+[smh]$",
+              "description": "Deduplicate identical events arriving within this window after the last fire. Complements max_per: use when rapid sensor bursts should collapse into one action."
             }
           },
           "required": ["max_per"]
         },
+        "cooldown": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Shorthand cooldown — minimum pause after a rule fires before it can fire again. Equivalent to throttle.max_per but at rule level. Takes precedence over throttle.max_per when both are set."
+        },
+        "requires_stable_for": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Hysteresis guard — the triggering device state must remain stable (unchanged) for this duration before the rule fires. Prevents action storms from transient sensor flicker. Validated at lint; enforcement is best-effort in the engine."
+        },
+        "hysteresis": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Alias for requires_stable_for with clearer semantics. Takes precedence when both are set. The triggering state must be continuously observed for this duration before the rule fires."
+        },
+        "maxFiringsPerHour": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of times this rule may fire in any rolling 60-minute window. Applied after cooldown/throttle checks. Useful as an absolute safety cap for high-frequency MQTT triggers."
+        },
+        "suppressIfAlreadyDesired": {
+          "type": "boolean",
+          "description": "When true, skip the rule's actions if the target device's last-known cached state already matches the expected outcome of the command (e.g. skip turnOn if powerState is already 'on'). Best-effort: requires a warm device cache."
+        },
         "dry_run": {
           "type": "boolean",
           "default": true,

package/dist/rules/action.js

@@ -203,3 +203,14 @@ export async function executeRuleAction(action, ctx) {
         return { ok: false, error: msg, deviceId, verb: parsed.verb };
     }
 }
+/**
+ * Extract the raw deviceId from an action object without alias resolution.
+ * Prefers `action.device` over the deviceId embedded in the command string.
+ * Use resolveActionDevice() when alias resolution is needed.
+ */
+export function extractDeviceIdFromAction(action) {
+    if (action.device)
+        return action.device;
+    const m = /\bdevices\s+command\s+(\S+)/.exec(action.command ?? '');
+    return m ? m[1] : null;
+}

package/dist/rules/conflict-analyzer.js

@@ -0,0 +1,214 @@
+/**
+ * Static conflict analysis for automation rules.
+ *
+ * Detects patterns that are technically valid but likely to cause
+ * operational problems:
+ *
+ *   1. Opposing-action pairs — same device, opposite commands (e.g.
+ *      turnOn / turnOff), triggered by the same source within a short
+ *      window and with no throttle on either rule.
+ *
+ *   2. High-frequency MQTT rules without throttle — rules that listen
+ *      on `device.shadow` (catch-all) with no throttle can fire on
+ *      every shadow push (up to once per second) and exhaust the daily
+ *      API quota quickly.
+ *
+ *   3. Potentially-destructive action without quiet-hours protection —
+ *      a rule that targets a destructive verb is technically blocked by
+ *      the engine, but we can still flag it early so users don't get a
+ *      surprise at runtime.
+ *
+ * Results are designed to be consumed by `rules doctor --json` and
+ * by CI pipelines. Each finding carries a `severity` so callers can
+ * decide how to gate on them.
+ */
+import { isTimeBetween, isAllCondition, isAnyCondition, isNotCondition } from './types.js';
+import { parseMaxPerMs } from './throttle.js';
+import { isDestructiveCommand } from './destructive.js';
+import { extractDeviceIdFromAction } from './action.js';
+/** Known opposing command pairs (order-independent). */
+const OPPOSING_PAIRS = [
+    ['turnOn', 'turnOff'],
+    ['lock', 'unlock'],
+    ['open', 'close'],
+    ['openDoor', 'closeDoor'],
+    ['openCurtain', 'closeCurtain'],
+    ['turnOn', 'standby'],
+    ['brightnessUp', 'brightnessDown'],
+    ['volumeUp', 'volumeDown'],
+    ['fanSpeedUp', 'fanSpeedDown'],
+];
+/**
+ * MQTT events that fire on every device state push and can rapidly exhaust
+ * the daily API quota when a rule has no throttle.
+ *
+ * Conditional events like `motion.detected` are intentionally excluded —
+ * they fire discretely, not at continuous high frequency. Extend this set
+ * when new catch-all or near-continuous event types are added to the classifier.
+ */
+export const HIGH_FREQ_EVENTS = ['device.shadow', '*'];
+/** Returns true when an MQTT event is known to fire at high frequency. */
+export function isHighFreqEvent(event) {
+    return HIGH_FREQ_EVENTS.includes(event);
+}
+function commandsAreOpposing(a, b) {
+    for (const [x, y] of OPPOSING_PAIRS) {
+        if ((a === x && b === y) || (a === y && b === x))
+            return true;
+    }
+    return false;
+}
+function extractCommandVerb(command) {
+    // command strings are like "devices command <id> turnOn" — extract last token
+    const parts = command.trim().split(/\s+/);
+    return parts[parts.length - 1] ?? command;
+}
+function effectiveCooldownMs(rule) {
+    if (rule.cooldown) {
+        try {
+            return parseMaxPerMs(rule.cooldown);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (rule.throttle?.max_per) {
+        try {
+            return parseMaxPerMs(rule.throttle.max_per);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function hasTimeBetweenGuard(conditions) {
+    if (!conditions)
+        return false;
+    for (const c of conditions) {
+        if (isTimeBetween(c))
+            return true;
+        if (isAllCondition(c) && hasTimeBetweenGuard(c.all))
+            return true;
+        if (isAnyCondition(c) && hasTimeBetweenGuard(c.any))
+            return true;
+        if (isNotCondition(c) && hasTimeBetweenGuard([c.not]))
+            return true;
+    }
+    return false;
+}
+export function analyzeConflicts(rules, quietHours) {
+    const findings = [];
+    const active = rules.filter((r) => r.enabled !== false);
+    // 1. Opposing-action pairs on the same device
+    for (let i = 0; i < active.length; i++) {
+        for (let j = i + 1; j < active.length; j++) {
+            const a = active[i];
+            const b = active[j];
+            // Only flag when they share the same trigger source (otherwise they
+            // can't race each other in normal operation).
+            if (a.when.source !== b.when.source)
+                continue;
+            const cooldownA = effectiveCooldownMs(a);
+            const cooldownB = effectiveCooldownMs(b);
+            // If both rules have meaningful cooldowns (≥ 5 minutes), the risk is
+            // low — skip.
+            const bothThrottled = cooldownA !== null && cooldownA >= 5 * 60_000 &&
+                cooldownB !== null && cooldownB >= 5 * 60_000;
+            if (bothThrottled)
+                continue;
+            for (const actionA of a.then) {
+                for (const actionB of b.then) {
+                    const deviceA = extractDeviceIdFromAction(actionA);
+                    const deviceB = extractDeviceIdFromAction(actionB);
+                    // Skip if devices can't be compared.
+                    if (!deviceA || !deviceB || deviceA !== deviceB)
+                        continue;
+                    const verbA = extractCommandVerb(actionA.command);
+                    const verbB = extractCommandVerb(actionB.command);
+                    if (commandsAreOpposing(verbA, verbB)) {
+                        const noThrottle = cooldownA === null || cooldownB === null;
+                        findings.push({
+                            severity: noThrottle ? 'warning' : 'info',
+                            code: 'opposing-actions',
+                            message: `Rules "${a.name}" and "${b.name}" issue opposing commands (${verbA} / ${verbB}) on device "${deviceA}" via the same trigger source.`,
+                            rules: [a.name, b.name],
+                            hint: noThrottle
+                                ? 'Add a "cooldown" or "throttle.max_per" to both rules to prevent rapid state oscillation.'
+                                : undefined,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // 2. High-frequency MQTT catch-all rules without throttle
+    for (const rule of active) {
+        if (rule.when.source !== 'mqtt')
+            continue;
+        const event = rule.when.event;
+        const isHighFreq = isHighFreqEvent(event);
+        if (!isHighFreq)
+            continue;
+        const cooldown = effectiveCooldownMs(rule);
+        if (cooldown === null) {
+            findings.push({
+                severity: 'warning',
+                code: 'high-frequency-no-throttle',
+                message: `Rule "${rule.name}" listens on "${event}" (high-frequency catch-all) with no throttle/cooldown. This can rapidly exhaust the daily API quota.`,
+                rules: [rule.name],
+                hint: 'Add "cooldown: 1m" or "throttle: { max_per: 1m }" to rate-limit this rule.',
+            });
+        }
+        else if (cooldown < 30_000) {
+            findings.push({
+                severity: 'info',
+                code: 'high-frequency-low-throttle',
+                message: `Rule "${rule.name}" listens on "${event}" with a throttle under 30 s. Consider increasing to at least 1 m to protect API quota.`,
+                rules: [rule.name],
+            });
+        }
+    }
+    // 3. Destructive actions in rules (engine blocks these at runtime, but
+    //    surface early with clear guidance).
+    for (const rule of active) {
+        for (let i = 0; i < rule.then.length; i++) {
+            const verb = extractCommandVerb(rule.then[i].command);
+            if (isDestructiveCommand(verb)) {
+                findings.push({
+                    severity: 'error',
+                    code: 'destructive-action-in-rule',
+                    message: `Rule "${rule.name}" then[${i}] contains destructive command "${verb}". The engine blocks this at runtime.`,
+                    rules: [rule.name],
+                    hint: 'Remove the destructive command or replace it with a non-destructive alternative.',
+                });
+            }
+        }
+    }
+    // 4. Event-driven rules with no time_between guard when quiet_hours is defined.
+    //    Cron rules fire on an explicit schedule so their overlap with quiet hours
+    //    requires schedule analysis — flag those separately when needed.
+    if (quietHours?.start && quietHours?.end) {
+        for (const rule of active) {
+            if (rule.when.source === 'cron')
+                continue;
+            if (!hasTimeBetweenGuard(rule.conditions)) {
+                findings.push({
+                    severity: 'warning',
+                    code: 'no-quiet-hours-guard',
+                    message: `Rule "${rule.name}" (${rule.when.source} trigger) has no time_between condition and may fire during quiet hours (${quietHours.start}–${quietHours.end}).`,
+                    rules: [rule.name],
+                    hint: `Add a conditions entry "{ time_between: ['${quietHours.end}', '${quietHours.start}'] }" to block this rule during quiet hours.`,
+                });
+            }
+        }
+    }
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return {
+        findings,
+        counts,
+        clean: counts.error === 0,
+    };
+}

package/dist/rules/engine.js

@@ -22,7 +22,7 @@ import { fetchDeviceStatus } from '../lib/devices.js';
 import { isDestructiveCommand } from './destructive.js';
 import { classifyMqttPayload, evaluateConditions, matchesMqttTrigger, } from './matcher.js';
 import { ThrottleGate, parseMaxPerMs } from './throttle.js';
-import { executeRuleAction } from './action.js';
+import { executeRuleAction, parseRuleCommand } from './action.js';
 import { CronScheduler } from './cron-scheduler.js';
 import { WebhookListener, DEFAULT_WEBHOOK_PORT } from './webhook-listener.js';
 import { isCronTrigger, isMqttTrigger, isWebhookTrigger, } from './types.js';
@@ -102,6 +102,88 @@ export function lintRules(automation) {
                     message: `throttle.max_per "${r.throttle.max_per}" is not a valid duration.`,
                 });
             }
+            if (r.throttle.dedupe_window) {
+                try {
+                    parseMaxPerMs(r.throttle.dedupe_window);
+                }
+                catch {
+                    issues.push({
+                        rule: r.name,
+                        severity: 'error',
+                        code: 'invalid-dedupe-window',
+                        message: `throttle.dedupe_window "${r.throttle.dedupe_window}" is not a valid duration.`,
+                    });
+                }
+            }
+        }
+        // cooldown field validation
+        if (r.cooldown) {
+            try {
+                parseMaxPerMs(r.cooldown);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-cooldown',
+                    message: `cooldown "${r.cooldown}" is not a valid duration (expected e.g. "10m", "1h").`,
+                });
+            }
+            if (r.throttle?.max_per) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'warning',
+                    code: 'cooldown-throttle-overlap',
+                    message: `Both "cooldown" and "throttle.max_per" are set. "cooldown" takes precedence.`,
+                });
+            }
+        }
+        // requires_stable_for field validation
+        if (r.requires_stable_for) {
+            try {
+                parseMaxPerMs(r.requires_stable_for);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-requires-stable-for',
+                    message: `requires_stable_for "${r.requires_stable_for}" is not a valid duration.`,
+                });
+            }
+        }
+        // hysteresis field validation
+        if (r.hysteresis) {
+            try {
+                parseMaxPerMs(r.hysteresis);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-hysteresis',
+                    message: `hysteresis "${r.hysteresis}" is not a valid duration (expected e.g. "10m", "1h").`,
+                });
+            }
+            if (r.requires_stable_for) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'warning',
+                    code: 'hysteresis-requires-stable-overlap',
+                    message: `Both "hysteresis" and "requires_stable_for" are set. "hysteresis" takes precedence.`,
+                });
+            }
+        }
+        // maxFiringsPerHour field validation
+        if (r.maxFiringsPerHour !== undefined) {
+            if (!Number.isInteger(r.maxFiringsPerHour) || r.maxFiringsPerHour < 1) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-maxFiringsPerHour',
+                    message: `maxFiringsPerHour must be a positive integer (got ${r.maxFiringsPerHour}).`,
+                });
+            }
         }
         const enabled = r.enabled !== false;
         const hasError = issues.some((i) => i.severity === 'error');
@@ -126,6 +208,8 @@ export class RulesEngine {
     rules;
     aliases;
     throttle = new ThrottleGate();
+    /** hysteresis / requires_stable_for: tracks when each (rule::device) trigger was first seen. */
+    hysteresisFirstSeen = new Map();
     unsubscribeMessage = null;
     unsubscribeState = null;
     cronScheduler = null;
@@ -341,6 +425,24 @@ export class RulesEngine {
     async ingestMqttForTest(payload) {
         await this.enqueue(() => this.onMqttMessage(payload, { preParsed: true }));
     }
+    /**
+     * Dispatch a pre-built EngineEvent through all matching MQTT rules.
+     * Used by tests that need full control over the event timestamp (e.g.
+     * hysteresis tests that advance time manually).
+     */
+    async ingestEventForTest(event) {
+        for (const rule of this.rules) {
+            if (!isMqttTrigger(rule.when))
+                continue;
+            const resolvedFilter = rule.when.device
+                ? this.aliases[rule.when.device] ?? rule.when.device
+                : undefined;
+            if (!matchesMqttTrigger(rule.when, event, resolvedFilter))
+                continue;
+            this.stats.eventsProcessed++;
+            await this.enqueue(() => this.dispatchRule(rule, event));
+        }
+    }
     /**
      * Fire a cron rule directly without needing the scheduler/timers.
      * Used by tests that want to exercise the dispatch pipeline without
@@ -478,6 +580,13 @@ export class RulesEngine {
             fetchStatus,
         });
         if (!cond.matched) {
+            // If conditions are not met, the trigger is no longer "continuously stable" —
+            // reset the hysteresis clock so intermittent satisfaction never accumulates.
+            const hasHysteresis = rule.hysteresis ?? rule.requires_stable_for;
+            if (hasHysteresis) {
+                const hysteresisKey = `${rule.name}::${event.deviceId ?? ''}`;
+                this.hysteresisFirstSeen.delete(hysteresisKey);
+            }
             if (cond.unsupported.length > 0) {
                 writeAudit({
                     t: event.t.toISOString(),
@@ -504,9 +613,13 @@ export class RulesEngine {
             this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'conditions-failed', deviceId: event.deviceId, reason: cond.failures.join('; ') });
             return;
         }
-        const windowMs = rule.throttle ? parseMaxPerMs(rule.throttle.max_per) : null;
+        // cooldown takes precedence over throttle.max_per when both are set.
+        const effectiveMaxPerMs = rule.cooldown
+            ? parseMaxPerMs(rule.cooldown)
+            : rule.throttle ? parseMaxPerMs(rule.throttle.max_per) : null;
+        const dedupeWindowMs = rule.throttle?.dedupe_window ? parseMaxPerMs(rule.throttle.dedupe_window) : null;
         const throttleKey = event.deviceId;
-        const check = this.throttle.check(rule.name, windowMs, event.t.getTime(), throttleKey);
+        const check = this.throttle.check(rule.name, effectiveMaxPerMs, event.t.getTime(), throttleKey, dedupeWindowMs);
         if (!check.allowed) {
             this.stats.throttled++;
             writeAudit({
@@ -524,13 +637,87 @@ export class RulesEngine {
                     matchedDevice: event.deviceId,
                     fireId,
                     reason: check.nextAllowedAt
-                        ? `throttled — next allowed at ${new Date(check.nextAllowedAt).toISOString()}`
-                        : 'throttled',
+                        ? `${check.dedupedBy ?? 'throttled'} — next allowed at ${new Date(check.nextAllowedAt).toISOString()}`
+                        : check.dedupedBy ?? 'throttled',
                 },
             });
             this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId });
             return;
         }
+        // hysteresis / requires_stable_for: require the trigger to have been continuously
+        // observed for the specified duration before firing.
+        const hysteresisMs = rule.hysteresis
+            ? parseMaxPerMs(rule.hysteresis)
+            : rule.requires_stable_for ? parseMaxPerMs(rule.requires_stable_for) : null;
+        if (hysteresisMs !== null) {
+            const hysteresisKey = `${rule.name}::${event.deviceId ?? ''}`;
+            const firstSeen = this.hysteresisFirstSeen.get(hysteresisKey);
+            const now = event.t.getTime();
+            if (firstSeen === undefined) {
+                this.hysteresisFirstSeen.set(hysteresisKey, now);
+                writeAudit({
+                    t: event.t.toISOString(), kind: 'rule-throttled',
+                    deviceId: event.deviceId ?? 'unknown', command: rule.then[0]?.command ?? '',
+                    parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                    rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `hysteresis — first observation, waiting ${hysteresisMs}ms for stability` },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'hysteresis-first-seen' });
+                return;
+            }
+            if (now - firstSeen < hysteresisMs) {
+                writeAudit({
+                    t: event.t.toISOString(), kind: 'rule-throttled',
+                    deviceId: event.deviceId ?? 'unknown', command: rule.then[0]?.command ?? '',
+                    parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                    rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `hysteresis — stable for ${now - firstSeen}ms of required ${hysteresisMs}ms` },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'hysteresis-not-stable' });
+                return;
+            }
+            // Stable long enough — clear so the next trigger starts fresh.
+            this.hysteresisFirstSeen.delete(hysteresisKey);
+        }
+        // maxFiringsPerHour: count-based rate cap over a rolling 1-hour window.
+        if (rule.maxFiringsPerHour !== undefined) {
+            const countCheck = this.throttle.checkMaxFirings(rule.name, rule.maxFiringsPerHour, 3_600_000, event.t.getTime(), event.deviceId);
+            if (!countCheck.allowed) {
+                this.stats.throttled++;
+                writeAudit({
+                    t: event.t.toISOString(), kind: 'rule-throttled',
+                    deviceId: event.deviceId ?? 'unknown', command: rule.then[0]?.command ?? '',
+                    parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                    rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `maxFiringsPerHour — ${countCheck.count}/${countCheck.max} in last hour` },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'maxFiringsPerHour' });
+                return;
+            }
+        }
+        // suppressIfAlreadyDesired: skip if device's live state already matches the command outcome.
+        if (rule.suppressIfAlreadyDesired) {
+            const firstAction = rule.then[0];
+            const parsed = firstAction ? parseRuleCommand(firstAction.command) : null;
+            const verb = parsed?.verb ?? firstAction?.command;
+            if ((verb === 'turnOn' || verb === 'turnOff') && (firstAction?.device || event.deviceId)) {
+                const targetId = firstAction?.device ? (this.aliases[firstAction.device] ?? firstAction.device) : event.deviceId;
+                try {
+                    const deviceStatus = await fetchStatus(targetId);
+                    const powerState = deviceStatus['powerState'];
+                    if ((verb === 'turnOn' && powerState === 'on') || (verb === 'turnOff' && powerState === 'off')) {
+                        writeAudit({
+                            t: event.t.toISOString(), kind: 'rule-throttled',
+                            deviceId: targetId, command: verb ?? '',
+                            parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                            rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `suppressIfAlreadyDesired — powerState already "${powerState}"` },
+                        });
+                        this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'already-desired' });
+                        return;
+                    }
+                }
+                catch {
+                    // best-effort — if status fetch fails, proceed with the action
+                }
+            }
+        }
         let fired = false;
         let allDry = true;
         for (const action of rule.then) {
@@ -561,6 +748,9 @@ export class RulesEngine {
             else
                 this.stats.fires++;
             this.throttle.record(rule.name, event.t.getTime(), throttleKey);
+            if (rule.maxFiringsPerHour !== undefined) {
+                this.throttle.recordFire(rule.name, event.t.getTime(), throttleKey);
+            }
             this.opts.onFire?.({ ruleName: rule.name, fireId, status: allDry ? 'dry' : 'fired', deviceId: event.deviceId });
         }
     }

package/dist/rules/suggest.js

@@ -80,7 +80,7 @@ export function suggestRule(opts) {
     const then = actionDevices.length > 0
         ? actionDevices.map((d) => ({
             command: `devices command <id> ${command}`,
-            device: d.name ?? d.id,
+            device: d.id,
         }))
         : [{ command: `devices command <id> ${command}` }];
     const rule = {