@switchbot/openapi-cli 3.0.0 → 3.1.1

package/dist/commands/doctor.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { execSync } from 'node:child_process';
 import { printJson, isJsonMode, exitWithError } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
@@ -13,6 +14,8 @@ import { resolvePolicyPath, loadPolicyFile, PolicyFileNotFoundError, PolicyYamlP
 import { validateLoadedPolicy } from '../policy/validate.js';
 import { selectCredentialStore } from '../credentials/keychain.js';
 import { getActiveProfile } from '../lib/request-context.js';
+import { readDaemonState } from '../lib/daemon-state.js';
+import { isPidAlive } from '../rules/pid-file.js';
 export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
@@ -480,6 +483,46 @@ function checkPolicy() {
         };
     }
 }
+async function checkKeychain() {
+    try {
+        const { selectCredentialStore } = await import('../credentials/keychain.js');
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        const isNative = desc.backend !== 'file';
+        if (!isNative) {
+            // Native keychain not available or not detected
+            return {
+                name: 'keychain',
+                status: 'warn',
+                detail: {
+                    backend: desc.backend,
+                    message: 'OS native keychain not detected — credentials stored in plain file (~/.switchbot/config.json). Consider installing a keychain backend for better security.',
+                    hint: process.platform === 'linux'
+                        ? 'Install libsecret (secret-tool) for GNOME Keyring support.'
+                        : process.platform === 'darwin'
+                            ? 'macOS Keychain is available — re-run `switchbot config set-token` to store credentials there.'
+                            : 'Windows Credential Manager is available — re-run `switchbot config set-token` to use it.',
+                },
+            };
+        }
+        return {
+            name: 'keychain',
+            status: 'ok',
+            detail: {
+                backend: desc.backend,
+                writable: desc.writable,
+                message: `Credentials stored in OS keychain (${desc.backend}).`,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'keychain',
+            status: 'warn',
+            detail: { message: `Keychain probe failed: ${err instanceof Error ? err.message : String(err)}` },
+        };
+    }
+}
 function checkNodeVersion() {
     const major = Number(process.versions.node.split('.')[0]);
     if (Number.isFinite(major) && major < 18) {
@@ -487,6 +530,181 @@ function checkNodeVersion() {
     }
     return { name: 'node', status: 'ok', detail: `Node ${process.versions.node}` };
 }
+function detectShellFlavor() {
+    const shell = (process.env.SHELL ?? '').toLowerCase();
+    const comspec = (process.env.COMSPEC ?? '').toLowerCase();
+    if (shell.includes('pwsh') || shell.includes('powershell'))
+        return 'powershell';
+    if (comspec.includes('powershell') || comspec.includes('pwsh'))
+        return 'powershell';
+    if (comspec.endsWith('cmd.exe'))
+        return 'cmd';
+    if (shell.endsWith('/fish') || shell === 'fish')
+        return 'fish';
+    if (shell.endsWith('/zsh') || shell === 'zsh')
+        return 'zsh';
+    if (shell.endsWith('/bash') || shell === 'bash')
+        return 'bash';
+    return process.platform === 'win32' ? 'powershell' : 'unknown';
+}
+function buildPathFix(shell, missingSegment, npmBinDir) {
+    if (!npmBinDir) {
+        return process.platform === 'win32'
+            ? 'Run: npm prefix -g and add that directory to your PATH.'
+            : 'Run: npm prefix -g and add <prefix>/bin to your PATH.';
+    }
+    switch (shell) {
+        case 'powershell':
+            return `$env:Path = "${missingSegment};" + $env:Path  # persist via your PowerShell profile or System Properties`;
+        case 'cmd':
+            return `set PATH=${missingSegment};%PATH%  &&  setx PATH "${missingSegment};%PATH%"`;
+        case 'fish':
+            return `fish_add_path "${missingSegment}"`;
+        case 'zsh':
+            return `export PATH="${missingSegment}:$PATH"  # add to ~/.zshrc`;
+        case 'bash':
+            return `export PATH="${missingSegment}:$PATH"  # add to ~/.bashrc`;
+        default:
+            return `export PATH="${missingSegment}:$PATH"`;
+    }
+}
+function checkPathDiscoverability() {
+    // Detect whether the `switchbot` binary is reachable on PATH.
+    // This catches the common "npm install -g worked but PATH not updated" failure.
+    const isWindows = process.platform === 'win32';
+    const binaryName = isWindows ? 'switchbot.cmd' : 'switchbot';
+    // Find where npm puts global bins.
+    let npmBinDir = null;
+    try {
+        const prefix = execSync('npm prefix -g', { timeout: 4000, encoding: 'utf-8' }).trim();
+        npmBinDir = isWindows ? prefix : path.join(prefix, 'bin');
+    }
+    catch {
+        // npm not on PATH or other error; fall through.
+    }
+    // Check whether `switchbot` resolves via PATH.
+    let binaryOnPath = false;
+    let resolvedPath = null;
+    try {
+        const which = execSync(isWindows ? `where ${binaryName}` : `which ${binaryName}`, { timeout: 3000, encoding: 'utf-8' }).trim().split(/\r?\n/)[0];
+        if (which) {
+            binaryOnPath = true;
+            resolvedPath = which;
+        }
+    }
+    catch {
+        binaryOnPath = false;
+    }
+    if (binaryOnPath) {
+        return {
+            name: 'path',
+            status: 'ok',
+            detail: {
+                binaryOnPath: true,
+                resolvedPath,
+                npmBinDir,
+                message: `switchbot is reachable at ${resolvedPath}`,
+            },
+        };
+    }
+    // Not on PATH — figure out what the user should add.
+    const currentPath = process.env.PATH ?? '';
+    const missingSegment = npmBinDir && !currentPath.split(path.delimiter).includes(npmBinDir)
+        ? npmBinDir
+        : null;
+    const currentShell = detectShellFlavor();
+    const shellFix = buildPathFix(currentShell, missingSegment, npmBinDir);
+    return {
+        name: 'path',
+        status: 'warn',
+        detail: {
+            binaryOnPath: false,
+            resolvedPath: null,
+            npmBinDir,
+            missingPathSegment: missingSegment,
+            currentShell,
+            fix: shellFix,
+            message: `'switchbot' is not on PATH. ${shellFix}`,
+        },
+    };
+}
+function checkDaemon() {
+    const state = readDaemonState();
+    if (!state) {
+        return {
+            name: 'daemon',
+            status: 'warn',
+            detail: {
+                present: false,
+                message: 'No daemon state file found. Start one with `switchbot daemon start` if you want long-running automation.',
+            },
+        };
+    }
+    const pid = state.pid;
+    const running = pid !== null && (pid === process.pid || isPidAlive(pid));
+    return {
+        name: 'daemon',
+        status: running ? 'ok' : 'warn',
+        detail: {
+            present: true,
+            status: running ? 'running' : state.status,
+            pid: running ? pid : null,
+            stateFile: state.stateFile,
+            pidFile: state.pidFile,
+            logFile: state.logFile,
+            startedAt: state.startedAt ?? null,
+            stoppedAt: state.stoppedAt ?? null,
+            lastReloadAt: state.lastReloadAt ?? null,
+            lastReloadStatus: state.lastReloadStatus ?? null,
+            healthConfigured: typeof state.healthzPort === 'number',
+            healthzPort: state.healthzPort ?? null,
+            message: running
+                ? 'daemon running'
+                : 'daemon not running; use `switchbot daemon start` for long-running automation',
+        },
+    };
+}
+async function checkHealthEndpoint() {
+    const state = readDaemonState();
+    if (!state || typeof state.healthzPort !== 'number') {
+        return {
+            name: 'health',
+            status: 'warn',
+            detail: {
+                present: false,
+                message: 'No health endpoint configured. Start the daemon with `--healthz-port <n>` to enable it.',
+            },
+        };
+    }
+    const url = `http://127.0.0.1:${state.healthzPort}/healthz`;
+    try {
+        const res = await fetch(url);
+        const body = await res.json();
+        const overall = body?.data?.overall ?? 'unknown';
+        return {
+            name: 'health',
+            status: res.ok && overall !== 'down' ? 'ok' : 'warn',
+            detail: {
+                present: true,
+                url,
+                httpStatus: res.status,
+                overall,
+                message: res.ok ? `health endpoint reachable at ${url}` : `health endpoint returned HTTP ${res.status}`,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'health',
+            status: 'warn',
+            detail: {
+                present: true,
+                url,
+                message: `health endpoint probe failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+}
 function checkMqtt() {
     // MQTT credentials are auto-provisioned from the SwitchBot API using the
     // account's token+secret — no extra env vars needed. Report availability
@@ -603,7 +821,9 @@ function checkMcp() {
 }
 const CHECK_REGISTRY = [
     { name: 'node', description: 'Node.js version compatibility', run: () => checkNodeVersion() },
+    { name: 'path', description: 'switchbot binary reachable on PATH', run: () => checkPathDiscoverability() },
     { name: 'credentials', description: 'credentials file present and parseable', run: () => checkCredentials() },
+    { name: 'keychain', description: 'OS keychain backend availability and usage', run: () => checkKeychain() },
     { name: 'profiles', description: 'profile definitions valid', run: () => checkProfiles() },
     { name: 'catalog', description: 'catalog loads', run: () => checkCatalog() },
     { name: 'catalog-schema', description: 'catalog vs agent-bootstrap version aligned', run: () => checkCatalogSchema() },
@@ -618,6 +838,8 @@ const CHECK_REGISTRY = [
     { name: 'mcp', description: 'MCP server instantiable + tool count', run: () => checkMcp() },
     { name: 'policy', description: 'policy.yaml present + schema-valid (if configured)', run: () => checkPolicy() },
     { name: 'audit', description: 'recent command errors (last 24h)', run: () => checkAudit() },
+    { name: 'daemon', description: 'daemon state file + runtime status', run: () => checkDaemon() },
+    { name: 'health', description: 'health endpoint availability (daemon --healthz-port)', run: () => checkHealthEndpoint() },
 ];
 function applyFixes(checks, writeOk) {
     const results = [];
@@ -668,7 +890,7 @@ function applyFixes(checks, writeOk) {
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
-        .description('Self-check the SwitchBot CLI setup: credentials, catalog, cache, quota, MQTT, MCP')
+        .description('Self-check the SwitchBot CLI setup: credentials, catalog, cache, quota, MQTT, daemon, health, MCP')
         .option('--section <names>', 'Comma-separated list of checks to run (see --list for names)')
         .option('--list', 'Print the registered check names and exit 0 without running any check')
         .option('--fix', 'Apply safe, reversible remediations for failing checks (e.g. clear stale cache)')
@@ -683,6 +905,7 @@ Examples:
   $ switchbot --json doctor | jq '.checks[] | select(.status != "ok")'
   $ switchbot doctor --list
   $ switchbot doctor --section credentials,mcp --json
+  $ switchbot doctor --section daemon,health --json
   $ switchbot doctor --probe --json
   $ switchbot doctor --fix --yes --json
 `)
@@ -734,6 +957,13 @@ Examples:
         };
         const overallFail = summary.fail > 0;
         const overall = overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok';
+        const total = summary.ok + summary.warn + summary.fail;
+        const rawScore = total > 0 ? Math.round(((summary.ok + summary.warn * 0.5) / total) * 100) : 100;
+        const maturityScore = Math.min(100, Math.max(0, rawScore));
+        const maturityLabel = maturityScore >= 90 ? 'production-ready'
+            : maturityScore >= 70 ? 'mostly-ready'
+                : maturityScore >= 40 ? 'needs-work'
+                    : 'not-ready';
         let fixes;
         if (opts.fix) {
             fixes = applyFixes(checks, Boolean(opts.yes));
@@ -747,6 +977,8 @@ Examples:
             const payload = {
                 ok: overall === 'ok',
                 overall,
+                maturityScore,
+                maturityLabel,
                 generatedAt: new Date().toISOString(),
                 schemaVersion: DOCTOR_SCHEMA_VERSION,
                 summary,

package/dist/commands/health.js

@@ -0,0 +1,113 @@
+import http from 'node:http';
+import { printJson, isJsonMode, printTable, handleError } from '../utils/output.js';
+import { getHealthReport, toPrometheusText } from '../utils/health.js';
+import { intArg } from '../utils/arg-parsers.js';
+const HEALTHZ_SCHEMA_VERSION = '1.1';
+/**
+ * Create an HTTP request handler for the health endpoints. Exposed separately
+ * so integration tests can call it directly without binding a port.
+ */
+export function createHealthHandler(auditLogPath) {
+    return (req, res) => {
+        const url = (req.url ?? '/').split('?')[0];
+        if (url === '/healthz') {
+            const report = getHealthReport(auditLogPath);
+            const statusCode = report.overall === 'down' ? 503 : 200;
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ schemaVersion: HEALTHZ_SCHEMA_VERSION, data: report }));
+        }
+        else if (url === '/metrics') {
+            const report = getHealthReport(auditLogPath);
+            res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' });
+            res.end(toPrometheusText(report));
+        }
+        else {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Not found', paths: ['/healthz', '/metrics'] }));
+        }
+    };
+}
+export function registerHealthCommand(program) {
+    const health = program
+        .command('health')
+        .description('Report process health: quota, audit error rate, circuit breaker state.');
+    health
+        .command('check')
+        .description('Print a one-shot health report.')
+        .option('--prometheus', 'Emit Prometheus text format.')
+        .option('--audit-log <path>', 'Audit log path (default: ~/.switchbot/audit.log).')
+        .action((opts) => {
+        const report = getHealthReport(opts.auditLog);
+        if (opts.prometheus) {
+            process.stdout.write(toPrometheusText(report));
+            return;
+        }
+        if (isJsonMode()) {
+            printJson(report);
+            return;
+        }
+        const statusEmoji = report.overall === 'ok' ? '✓' : report.overall === 'degraded' ? '⚠' : '✗';
+        console.log(`${statusEmoji} overall: ${report.overall}  (${report.generatedAt})`);
+        console.log('');
+        printTable(['Component', 'Status', 'Detail'], [
+            ['quota', report.quota.status,
+                `${report.quota.used}/${report.quota.limit} (${report.quota.percentUsed}% used, ${report.quota.remaining} remaining)`],
+            ['audit', report.audit.status,
+                report.audit.present
+                    ? `${report.audit.recentErrors}/${report.audit.recentTotal} errors in 24h (${report.audit.errorRatePercent}%)`
+                    : 'log not present'],
+            ['circuit', report.circuit.status,
+                `${report.circuit.name}: ${report.circuit.state} (failures: ${report.circuit.failures})`],
+            ['process', 'ok',
+                `pid ${report.process.pid} · uptime ${report.process.uptimeSeconds}s · mem ${report.process.memoryMb}MB`],
+        ]);
+        if (report.overall !== 'ok')
+            process.exit(1);
+    });
+    // switchbot health serve [--port <n>]
+    health
+        .command('serve')
+        .description('Start an HTTP server exposing /healthz (JSON) and /metrics (Prometheus).')
+        .option('--port <n>', 'Port to listen on.', intArg('--port'), '3100')
+        .option('--host <host>', 'Bind address.', '127.0.0.1')
+        .option('--audit-log <path>', 'Audit log path.')
+        .addHelpText('after', `
+Endpoints:
+  GET /healthz   JSON health report (HTTP 200 ok/degraded, 503 when circuit is open).
+  GET /metrics   Prometheus text metrics.
+
+Example:
+  $ switchbot health serve --port 3100
+  $ curl http://127.0.0.1:3100/healthz
+`)
+        .action((opts) => {
+        const port = parseInt(opts.port, 10);
+        const handler = createHealthHandler(opts.auditLog);
+        const server = http.createServer(handler);
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                handleError(Object.assign(new Error(`Port ${port} is already in use. Choose a different port with --port.`), { code: err.code }));
+            }
+            else {
+                handleError(err);
+            }
+        });
+        server.listen(port, opts.host, () => {
+            const addr = server.address();
+            const boundPort = typeof addr === 'object' && addr !== null ? addr.port : port;
+            if (isJsonMode()) {
+                printJson({ status: 'listening', host: opts.host, port: boundPort, endpoints: ['/healthz', '/metrics'] });
+            }
+            else {
+                console.log(`health server listening on ${opts.host}:${boundPort}`);
+                console.log('  GET /healthz  — JSON health report');
+                console.log('  GET /metrics  — Prometheus text metrics');
+            }
+        });
+        function shutdown() {
+            server.close(() => process.exit(0));
+        }
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+    });
+}

package/dist/commands/mcp.js

@@ -25,6 +25,7 @@ import { planMigration } from '../policy/migrate.js';
 import { suggestPlan } from './plan.js';
 import { suggestRule } from '../rules/suggest.js';
 import { addRuleToPolicyFile, AddRuleError } from '../policy/add-rule.js';
+import { allowsDirectDestructiveExecution, destructiveExecutionHint } from '../lib/destructive-mode.js';
 import { writeFileSync } from 'node:fs';
 import { readAudit } from '../utils/audit.js';
 import { parseDurationToMs } from '../utils/flags.js';
@@ -135,6 +136,33 @@ function topNFromMap(counts, n) {
         .slice(0, n)
         .map(([key, count]) => ({ key, count }));
 }
+/**
+ * Compute per-action risk metadata from the device catalog.
+ * `idempotencyHint` is sourced from CommandSpec.idempotent when available;
+ * falls back to "safe" only for unknown commands on non-destructive paths.
+ */
+function buildRiskProfile(typeName, command, commandType, isDestructive) {
+    // Look up the catalog spec to get the authoritative idempotent flag.
+    let idempotencyHint = isDestructive ? 'non-idempotent' : 'safe';
+    if (typeName && commandType === 'command') {
+        const entry = findCatalogEntry(typeName);
+        const entries = Array.isArray(entry) ? entry : entry ? [entry] : [];
+        for (const e of entries) {
+            const spec = e.commands.find((c) => c.command === command);
+            if (spec !== undefined) {
+                idempotencyHint = spec.idempotent === true ? 'safe' : 'non-idempotent';
+                break;
+            }
+        }
+    }
+    return {
+        riskLevel: isDestructive ? 'high' : commandType === 'command' ? 'medium' : 'low',
+        requiresConfirmation: isDestructive,
+        supportsDryRun: true,
+        idempotencyHint,
+        recommendedMode: isDestructive ? 'review-before-execute' : 'plan',
+    };
+}
 export function createSwitchBotMcpServer(options) {
     const eventManager = options?.eventManager;
     const server = new McpServer({
@@ -301,7 +329,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     // ---- send_command ---------------------------------------------------------
     server.registerTool('send_command', {
         title: 'Send a control command to a device',
-        description: 'Execute a control command on a device (turnOn, setColor, startClean, unlock, openDoor, createKey, etc.). Destructive commands (Smart Lock unlock, Garage Door open, Keypad createKey/deleteKey) require confirm:true to proceed; otherwise rejected. Commands are validated offline against the device catalog. Use idempotencyKey to safely deduplicate retries within 60 seconds.',
+        description: 'Execute a control command on a device (turnOn, setColor, startClean, unlock, openDoor, createKey, etc.). Destructive commands require confirm:true and are still blocked in the default safety profile; use the reviewed plan workflow unless an explicit dev profile allows direct execution. Commands are validated offline against the device catalog. Use idempotencyKey to safely deduplicate retries within 60 seconds.',
         _meta: { agentSafetyTier: 'action' },
         inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
@@ -334,6 +362,16 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             command: z.string().optional(),
             deviceId: z.string().optional(),
             result: z.unknown().optional().describe('API response body from SwitchBot (absent on dryRun)'),
+            riskProfile: z
+                .object({
+                riskLevel: z.enum(['high', 'medium', 'low']),
+                requiresConfirmation: z.boolean(),
+                supportsDryRun: z.literal(true),
+                idempotencyHint: z.enum(['safe', 'non-idempotent']),
+                recommendedMode: z.enum(['review-before-execute', 'plan', 'direct']),
+            })
+                .optional()
+                .describe('Device+command-specific risk metadata. riskLevel:"high" means confirm:true was required. Always present on dryRun responses so agents can preview risk before committing.'),
             verification: z
                 .object({
                 verifiable: z.boolean(),
@@ -404,7 +442,9 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 parameter: effectiveParameter ?? 'default',
                 commandType: effectiveType,
             };
-            const structured = { ok: true, dryRun: true, wouldSend };
+            const dryIsDestructive = isDestructiveCommand(cached.type, effectiveCommand, effectiveType);
+            const dryRiskProfile = buildRiskProfile(cached.type, effectiveCommand, effectiveType, dryIsDestructive);
+            const structured = { ok: true, dryRun: true, riskProfile: dryRiskProfile, wouldSend };
             return {
                 content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
                 structuredContent: structured,
@@ -425,7 +465,21 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             }
             typeName = physical ? physical.deviceType : ir.remoteType;
         }
-        if (isDestructiveCommand(typeName, effectiveCommand, effectiveType) && !confirm) {
+        const destructive = isDestructiveCommand(typeName, effectiveCommand, effectiveType);
+        if (destructive && !allowsDirectDestructiveExecution()) {
+            const reason = getDestructiveReason(typeName, effectiveCommand, effectiveType);
+            return mcpError('guard', 3, `Direct destructive execution is disabled for command "${effectiveCommand}" on device type "${typeName}".`, {
+                hint: reason ? `${destructiveExecutionHint()} Reason: ${reason}` : destructiveExecutionHint(),
+                context: {
+                    command: effectiveCommand,
+                    deviceType: typeName,
+                    directExecutionAllowed: false,
+                    requiredWorkflow: 'plan-approval',
+                    ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}),
+                },
+            });
+        }
+        if (destructive && !confirm) {
             const reason = getDestructiveReason(typeName, effectiveCommand, effectiveType);
             const entry = typeName ? findCatalogEntry(typeName) : null;
             const spec = entry && !Array.isArray(entry)
@@ -490,7 +544,9 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             return apiErrorToMcpError(err);
         }
         const isIr = getCachedDevice(deviceId)?.category === 'ir';
-        const structured = { ok: true, command: effectiveCommand, deviceId, result };
+        const liveIsDestructive = destructive;
+        const riskProfile = buildRiskProfile(typeName, effectiveCommand, effectiveType, liveIsDestructive);
+        const structured = { ok: true, command: effectiveCommand, deviceId, result, riskProfile };
         if (isIr) {
             structured.verification = {
                 verifiable: false,
@@ -1254,7 +1310,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     // ---- plan_run -------------------------------------------------------------
     server.registerTool('plan_run', {
         title: 'Validate and execute a SwitchBot plan',
-        description: 'Execute a Plan JSON object (version 1.0). Destructive command steps are skipped unless yes=true. ' +
+        description: 'Execute a Plan JSON object (version 1.0). Destructive command steps are skipped unless yes=true, and the default safety profile still refuses direct destructive execution in favor of the reviewed plan workflow. ' +
             'Scene and wait steps run in order. Returns per-step results and a summary.',
         _meta: { agentSafetyTier: 'action' },
         inputSchema: z.object({
@@ -1289,6 +1345,38 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         };
         const continueOnError = continue_on_error === true;
         const allowDestructive = yes === true;
+        const destructiveSteps = validated.plan.steps
+            .map((step, index) => ({ step, index }))
+            .filter((entry) => entry.step.type === 'command')
+            .map(({ step, index }) => {
+            const resolvedDeviceId = resolveDeviceId(step.deviceId, step.deviceName);
+            const commandType = step.commandType ?? 'command';
+            const deviceType = getCachedDevice(resolvedDeviceId)?.type;
+            return {
+                index: index + 1,
+                deviceId: resolvedDeviceId,
+                command: step.command,
+                commandType,
+                deviceType: deviceType ?? null,
+                destructive: isDestructiveCommand(deviceType, step.command, commandType),
+            };
+        })
+            .filter((step) => step.destructive);
+        if (allowDestructive && destructiveSteps.length > 0 && !allowsDirectDestructiveExecution()) {
+            return mcpError('guard', 3, 'Direct destructive execution is disabled for plan_run.', {
+                hint: destructiveExecutionHint(),
+                context: {
+                    destructiveSteps: destructiveSteps.map((step) => ({
+                        step: step.index,
+                        deviceId: step.deviceId,
+                        deviceType: step.deviceType,
+                        command: step.command,
+                        commandType: step.commandType,
+                    })),
+                    requiredWorkflow: 'plan-approval',
+                },
+            });
+        }
         for (let i = 0; i < validated.plan.steps.length; i++) {
             const step = validated.plan.steps[i];
             const idx = i + 1;