@switchbot/openapi-cli 2.4.0 → 2.5.0

package/dist/commands/agent-bootstrap.js

@@ -116,6 +116,9 @@ Examples:
                 scope: cachedDevices.length > 0 ? 'used' : 'all',
                 types: catalogTypes,
             },
+            // hints: empty array means no hints to report; always emitted, never null.
+            // An empty array signals "nothing to act on" — agents should not treat
+            // it as a disabled or missing field.
             hints: cachedDevices.length === 0
                 ? ['Run `switchbot devices list` once to populate the device cache for richer bootstrap output.']
                 : [],

package/dist/commands/batch.js

@@ -100,7 +100,7 @@ export function registerBatchCommand(devices) {
         .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
-        .option('--idempotency-key-prefix <prefix>', 'Prefix for idempotency keys (key per device: <prefix>-<deviceId>)', stringArg('--idempotency-key-prefix'))
+        .option('--idempotency-key-prefix <prefix>', 'Client-supplied prefix for idempotency keys (key per device: <prefix>-<deviceId>). process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key-prefix'))
         .addHelpText('after', `
 Targets are resolved in this priority order:
   1. --ids when present       (explicit deviceIds)

package/dist/commands/cache.js

@@ -46,6 +46,7 @@ Examples:
 `);
     cache
         .command('show')
+        .alias('status')
         .description('Summarize the cache files (paths, ages, entry counts)')
         .action(() => {
         const summary = describeCache();

package/dist/commands/capabilities.js

@@ -28,6 +28,7 @@ const COMMAND_META = {
     // scenes
     'scenes list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
     'scenes execute': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1500 },
+    'scenes describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
     // webhook
     'webhook setup': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 500 },
     'webhook query': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
@@ -51,6 +52,7 @@ const COMMAND_META = {
     'history replay': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1000 },
     'history range': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 50 },
     'history stats': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
+    'history aggregate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 80 },
     'plan run': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 2000 },
     'plan validate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
     'plan schema': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
@@ -88,6 +90,7 @@ const MCP_TOOLS = [
     'account_overview',
     'get_device_history',
     'query_device_history',
+    'aggregate_device_history',
 ];
 const IDEMPOTENCY_CONTRACT = {
     flag: '--idempotency-key <key>',

package/dist/commands/devices.js

@@ -307,7 +307,7 @@ Examples:
         .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
-        .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)', stringArg('--idempotency-key'))
+        .option('--idempotency-key <key>', 'Client-supplied key to dedupe retries. process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key'))
         .addHelpText('after', `
 ────────────────────────────────────────────────────────────────────────
 For the full list of commands a specific device supports — and their

package/dist/commands/events.js

@@ -385,6 +385,13 @@ Examples:
                 else {
                     console.log(JSON.stringify(ctl));
                 }
+                // Persist to __control.jsonl — best-effort, never blocks the stream.
+                try {
+                    deviceHistoryStore.recordControl(ctl);
+                }
+                catch {
+                    // swallow
+                }
             };
             const unsubState = client.onStateChange((state) => {
                 if (!isJsonMode()) {

package/dist/commands/history.js

@@ -5,6 +5,7 @@ import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.
 import { readAudit, verifyAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
 import { queryDeviceHistory, queryDeviceHistoryStats, } from '../devices/history-query.js';
+import { aggregateDeviceHistory, ALL_AGG_FNS, } from '../devices/history-agg.js';
 const DEFAULT_AUDIT = path.join(os.homedir(), '.switchbot', 'audit.log');
 export function registerHistoryCommand(program) {
     const history = program
@@ -186,8 +187,8 @@ Examples:
         .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
         .addHelpText('after', `
 See docs/audit-log.md for the audit log format. Exit code:
-  0  every line parses and carries the current auditVersion
-  1  one or more lines are malformed OR the file is missing
+  0  every line parses and carries the current auditVersion, or file is missing (warn)
+  1  one or more lines are malformed or schema drift detected
   2  (usage) — not emitted by this subcommand
 
 Examples:
@@ -197,30 +198,132 @@ Examples:
         .action((options) => {
         const file = options.file ?? DEFAULT_AUDIT;
         const report = verifyAudit(file);
+        // Determine status and exit code
+        let status = 'ok';
+        let exitCode = 0;
+        if (report.fileMissing) {
+            status = 'warn';
+        }
+        else if (report.malformedLines > 0 || report.unversionedEntries > 0) {
+            status = 'fail';
+            exitCode = 1;
+        }
         if (isJsonMode()) {
-            printJson(report);
+            const output = {
+                status,
+                fileMissing: report.fileMissing === true,
+                parsed: report.parsedLines,
+                malformed: report.malformedLines,
+                unversioned: report.unversionedEntries,
+                message: report.fileMissing
+                    ? 'Audit log file not found (fresh install)'
+                    : report.malformedLines > 0 || report.unversionedEntries > 0
+                        ? 'Audit log has malformed or unversioned entries'
+                        : 'Audit log is valid',
+            };
+            printJson(output);
         }
         else {
-            console.log(`Audit log:       ${report.file}`);
-            console.log(`Parsed lines:    ${report.parsedLines} / ${report.totalLines}`);
-            console.log(`Malformed:       ${report.malformedLines}`);
-            console.log(`Unversioned:     ${report.unversionedEntries}`);
-            const versions = Object.entries(report.versionCounts)
-                .map(([v, n]) => `${v}:${n}`)
-                .join(', ');
-            console.log(`Version counts:  ${versions || '—'}`);
-            if (report.earliest)
-                console.log(`Earliest:        ${report.earliest}`);
-            if (report.latest)
-                console.log(`Latest:          ${report.latest}`);
-            if (report.problems.length > 0) {
-                console.log('\nProblems:');
-                for (const p of report.problems) {
-                    console.log(`  line ${p.line}: ${p.reason}${p.preview ? ` — "${p.preview}"` : ''}`);
+            if (report.fileMissing) {
+                console.log(`Audit log:       ${report.file} (missing — fresh install)`);
+                console.log(`Status:          ✓ warn (expected for new accounts)`);
+            }
+            else {
+                console.log(`Audit log:       ${report.file}`);
+                console.log(`Parsed lines:    ${report.parsedLines} / ${report.totalLines}`);
+                console.log(`Malformed:       ${report.malformedLines}`);
+                console.log(`Unversioned:     ${report.unversionedEntries}`);
+                const versions = Object.entries(report.versionCounts)
+                    .map(([v, n]) => `${v}:${n}`)
+                    .join(', ');
+                console.log(`Version counts:  ${versions || '—'}`);
+                if (report.earliest)
+                    console.log(`Earliest:        ${report.earliest}`);
+                if (report.latest)
+                    console.log(`Latest:          ${report.latest}`);
+                if (report.problems.length > 0) {
+                    console.log('\nProblems:');
+                    for (const p of report.problems) {
+                        console.log(`  line ${p.line}: ${p.reason}${p.preview ? ` — "${p.preview}"` : ''}`);
+                    }
                 }
             }
         }
-        const ok = report.malformedLines === 0 && report.problems.length === 0;
-        process.exit(ok ? 0 : 1);
+        process.exit(exitCode);
+    });
+    history
+        .command('aggregate')
+        .description('Aggregate time-ranged device history metrics into buckets')
+        .argument('<deviceId>', 'Device ID to aggregate')
+        .option('--since <duration>', 'Relative window ending now, e.g. "1h", "7d" (mutually exclusive with --from/--to)', stringArg('--since'))
+        .option('--from <iso>', 'Range start (ISO-8601)', stringArg('--from'))
+        .option('--to <iso>', 'Range end (ISO-8601)', stringArg('--to'))
+        .option('--metric <name>', 'Payload field to aggregate (repeat for multiple)', (v, acc = []) => acc.concat(v), [])
+        .option('--agg <csv>', 'Comma-separated aggregation functions (count,min,max,avg,sum,p50,p95)', stringArg('--agg'))
+        .option('--bucket <duration>', 'Bucket width, e.g. "15m", "1h", "1d"', stringArg('--bucket'))
+        .option('--max-bucket-samples <n>', 'Max samples per bucket for quantiles (1–100000)', intArg('--max-bucket-samples', { min: 1, max: 100_000 }))
+        .action(async (deviceId, options) => {
+        const metrics = options.metric ?? [];
+        if (metrics.length === 0) {
+            handleError(new UsageError('at least one --metric is required.'));
+        }
+        if (options.since && (options.from || options.to)) {
+            handleError(new UsageError('--since is mutually exclusive with --from/--to.'));
+        }
+        let aggs;
+        if (options.agg !== undefined) {
+            const parts = options.agg.split(',').map((s) => s.trim()).filter(Boolean);
+            const unknown = parts.filter((p) => !ALL_AGG_FNS.includes(p));
+            if (unknown.length > 0) {
+                handleError(new UsageError(`Unknown aggregation function(s): ${unknown.join(', ')}. Legal values: ${ALL_AGG_FNS.join(', ')}.`));
+            }
+            aggs = parts;
+        }
+        const aggOpts = {
+            metrics,
+            aggs,
+            since: options.since,
+            from: options.from,
+            to: options.to,
+            bucket: options.bucket,
+            maxBucketSamples: options.maxBucketSamples !== undefined ? Number(options.maxBucketSamples) : undefined,
+        };
+        try {
+            const res = await aggregateDeviceHistory(deviceId, aggOpts);
+            if (isJsonMode()) {
+                printJson(res);
+                return;
+            }
+            if (res.buckets.length === 0) {
+                console.log(`(no history records for ${deviceId} in requested range)`);
+                return;
+            }
+            const aggCols = res.aggs;
+            const cols = ['t', ...res.metrics.flatMap((m) => aggCols.map((a) => `${m}.${a}`))];
+            console.log(cols.join('\t'));
+            for (const bkt of res.buckets) {
+                const row = cols.map((col) => {
+                    if (col === 't')
+                        return bkt.t;
+                    const [metric, agg] = col.split('.');
+                    const val = bkt.metrics[metric]?.[agg];
+                    return val !== undefined ? String(val) : '\u2014';
+                });
+                console.log(row.join('\t'));
+            }
+            if (res.partial) {
+                for (const note of res.notes) {
+                    console.error('note: ' + note);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                if (/bucket/i.test(err.message) || /--since/i.test(err.message) || /--from/i.test(err.message) || /--to/i.test(err.message)) {
+                    handleError(new UsageError(err.message));
+                }
+            }
+            handleError(err);
+        }
     });
 }

package/dist/commands/mcp.js

@@ -4,6 +4,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { z } from 'zod';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode } from '../utils/output.js';
+import { VERSION } from '../version.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 import { findCatalogEntry } from '../devices/catalog.js';
@@ -11,6 +12,7 @@ import { getCachedDevice } from '../devices/cache.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
 import { deviceHistoryStore } from '../mcp/device-history.js';
 import { queryDeviceHistory } from '../devices/history-query.js';
+import { aggregateDeviceHistory, ALL_AGG_FNS, MAX_SAMPLE_CAP, } from '../devices/history-agg.js';
 import { todayUsage } from '../utils/quota.js';
 import { describeCache } from '../devices/cache.js';
 import { withRequestContext } from '../lib/request-context.js';
@@ -33,7 +35,7 @@ export function createSwitchBotMcpServer(options) {
     const eventManager = options?.eventManager;
     const server = new McpServer({
         name: 'switchbot',
-        version: '2.0.0',
+        version: VERSION,
     }, {
         capabilities: { tools: {}, resources: {} },
         instructions: `SwitchBot is an IoT smart home brand by Wonderlabs, Inc. This MCP server controls physical devices \
@@ -60,7 +62,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('list_devices', {
         title: 'List all devices on the account',
         description: 'Fetch the complete inventory of physical devices and IR remotes on this SwitchBot account. Refreshes the local metadata cache and groups devices by type. Use this as the bootstrap call to discover available deviceIds. Devices without enableCloudService cannot receive commands via API. IR remotes depend on a Hub for connectivity.',
-        inputSchema: {},
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({}).strict(),
         outputSchema: {
             deviceList: z.array(z.object({
                 deviceId: z.string(),
@@ -95,9 +98,10 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('get_device_status', {
         title: 'Get live status for a device',
         description: 'Query the real-time status payload for a physical device. IR remotes have no status channel and will error.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
-        },
+        }).strict(),
         outputSchema: {
             status: z.object({
                 deviceId: z.string().optional(),
@@ -119,10 +123,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         description: 'Return device state history recorded from MQTT events (persisted to ~/.switchbot/device-history/). ' +
             'No API call — zero quota cost. Use when you need recent historical readings or want to avoid a live API call. ' +
             'Omit deviceId to list all devices with stored history.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().optional().describe('Device MAC address (deviceId). Omit to list all devices with history.'),
             limit: z.number().int().min(1).max(100).optional().describe('Max history entries to return (default 20, max 100)'),
-        },
+        }).strict(),
         outputSchema: {
             deviceId: z.string().optional(),
             latest: z.unknown().optional(),
@@ -153,14 +158,15 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         description: 'Return records from the append-only JSONL history (~/.switchbot/device-history/<deviceId>.jsonl) ' +
             'filtered by a relative duration (since) or absolute ISO-8601 range (from/to). ' +
             'No API call — zero quota cost. Use for trend questions like "how many times did this switch turn on last week".',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID to query'),
             since: z.string().optional().describe('Relative window ending now, e.g. "30s", "15m", "1h", "7d". Mutually exclusive with from/to.'),
             from: z.string().optional().describe('Range start (ISO-8601).'),
             to: z.string().optional().describe('Range end (ISO-8601).'),
             fields: z.array(z.string()).optional().describe('Project these payload fields; omit for the full payload.'),
             limit: z.number().int().min(1).max(10000).optional().describe('Max records to return (default 1000).'),
-        },
+        }).strict(),
         outputSchema: {
             deviceId: z.string(),
             count: z.number().int(),
@@ -192,7 +198,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     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.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'action' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
             command: z.string().describe('Command name, case-sensitive (e.g. turnOn, setColor, unlock)'),
             parameter: z
@@ -213,12 +220,16 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 .string()
                 .optional()
                 .describe('Deduplication key — repeat calls with the same key within 60s replay the first result (adds replayed:true). Same key + different (command, parameter) within 60s returns an idempotency_conflict guard error.'),
-        },
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe('When true, do not call the API — return { ok:true, dryRun:true, wouldSend:{...} } instead.'),
+        }).strict(),
         outputSchema: {
             ok: z.literal(true),
-            command: z.string(),
-            deviceId: z.string(),
-            result: z.unknown().describe('API response body from SwitchBot'),
+            command: z.string().optional(),
+            deviceId: z.string().optional(),
+            result: z.unknown().optional().describe('API response body from SwitchBot (absent on dryRun)'),
             verification: z
                 .object({
                 verifiable: z.boolean(),
@@ -227,9 +238,30 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             })
                 .optional()
                 .describe('Present when the target is an IR device. IR is unidirectional — agents should treat the success as "signal sent" not "state changed".'),
+            dryRun: z.literal(true).optional().describe('Present when dryRun:true was requested'),
+            wouldSend: z.object({
+                deviceId: z.string(),
+                command: z.string(),
+                parameter: z.unknown(),
+                commandType: z.string(),
+            }).optional().describe('The request shape that would have been POSTed (present when dryRun:true)'),
         },
-    }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey }) => {
+    }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
+        // dryRun early-return — no API call, no validation against live device list
+        if (dryRun) {
+            const wouldSend = {
+                deviceId,
+                command,
+                parameter: parameter ?? 'default',
+                commandType: effectiveType,
+            };
+            const structured = { ok: true, dryRun: true, wouldSend };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
         // Resolve the device's catalog type via cache or a fresh lookup so we
         // can evaluate destructive/validation without an extra round-trip if
         // the cache is warm.
@@ -307,14 +339,31 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('run_scene', {
         title: 'Execute a manual scene',
         description: 'Execute a manual SwitchBot scene by its sceneId (from list_scenes).',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'action' },
+        inputSchema: z.object({
             sceneId: z.string().describe('Scene ID from list_scenes'),
-        },
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe('When true, do not call the API — return { ok:true, dryRun:true, wouldSend:{...} } instead.'),
+        }).strict(),
         outputSchema: {
             ok: z.literal(true),
-            sceneId: z.string(),
+            sceneId: z.string().optional(),
+            dryRun: z.literal(true).optional().describe('Present when dryRun:true was requested'),
+            wouldSend: z.object({
+                sceneId: z.string(),
+            }).optional().describe('The request shape that would have been POSTed (present when dryRun:true)'),
         },
-    }, async ({ sceneId }) => {
+    }, async ({ sceneId, dryRun }) => {
+        if (dryRun) {
+            const wouldSend = { sceneId };
+            const structured = { ok: true, dryRun: true, wouldSend };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
         await executeScene(sceneId);
         const structured = { ok: true, sceneId };
         return {
@@ -326,7 +375,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('list_scenes', {
         title: 'List all manual scenes',
         description: 'Fetch all manual scenes configured in the SwitchBot app.',
-        inputSchema: {},
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({}).strict(),
         outputSchema: {
             scenes: z.array(z.object({ sceneId: z.string(), sceneName: z.string() })),
         },
@@ -341,10 +391,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('search_catalog', {
         title: 'Search the offline device catalog',
         description: 'Search the built-in device catalog by type name or alias. Returns matching entries with their commands, roles, destructive flags, and status fields. No API call.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             query: z.string().describe('Search query (matches type and aliases, case-insensitive). Use empty string to list all.'),
             limit: z.number().int().min(1).max(100).optional().default(20).describe('Max entries returned (default 20)'),
-        },
+        }).strict(),
         outputSchema: {
             results: z.array(z.object({
                 type: z.string(),
@@ -376,10 +427,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('describe_device', {
         title: 'Describe a specific device',
         description: 'Resolve a deviceId to its metadata + catalog entry + suggested safe actions. Pass live:true to also fetch real-time status values.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
             live: z.boolean().optional().default(false).describe('Also fetch live /status values (costs 1 extra API call)'),
-        },
+        }).strict(),
         outputSchema: {
             device: z.object({
                 device: z.object({ deviceId: z.string(), deviceName: z.string() }).passthrough(),
@@ -417,11 +469,45 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             throw err;
         }
     });
+    // ---- aggregate_device_history --------------------------------------------
+    server.registerTool('aggregate_device_history', {
+        title: 'Aggregate device history',
+        description: 'Bucketed statistics (count/min/max/avg/sum/p50/p95) over JSONL-recorded device history. Read-only; no network calls.',
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z
+            .object({
+            deviceId: z.string().min(1),
+            since: z.string().optional(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            metrics: z.array(z.string().min(1)).min(1),
+            aggs: z.array(z.enum(ALL_AGG_FNS)).optional(),
+            bucket: z.string().optional(),
+            maxBucketSamples: z.number().int().positive().max(MAX_SAMPLE_CAP).optional(),
+        })
+            .strict(),
+    }, async (args) => {
+        const opts = {
+            since: args.since,
+            from: args.from,
+            to: args.to,
+            metrics: args.metrics,
+            aggs: args.aggs,
+            bucket: args.bucket,
+            maxBucketSamples: args.maxBucketSamples,
+        };
+        const res = await aggregateDeviceHistory(args.deviceId, opts);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(res, null, 2) }],
+            structuredContent: res,
+        };
+    });
     // ---- account_overview ---------------------------------------------------
     server.registerTool('account_overview', {
         title: 'Bootstrap account overview',
         description: 'Get a complete account snapshot: devices, scenes, quota usage, cache status, and MQTT connection state. Use this for cold-start initialization or periodic health checks.',
-        inputSchema: {},
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({}).strict(),
         outputSchema: {
             version: z.string(),
             schemaVersion: z.string(),
@@ -472,7 +558,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         const cacheInfo = describeCache();
         const quota = todayUsage();
         const overview = {
-            version: '2.0.0',
+            version: VERSION,
             schemaVersion: '1.1',
             devices: deviceList.deviceList.map(toMcpDeviceListShape),
             infraredRemotes: deviceList.infraredRemoteList.map(toMcpIrDeviceShape),
@@ -533,15 +619,18 @@ export function registerMcpCommand(program) {
         .command('mcp')
         .description('Run as a Model Context Protocol server so AI agents can call SwitchBot tools')
         .addHelpText('after', `
-The MCP server exposes eight tools:
-  - list_devices          fetch all physical + IR devices
-  - get_device_status     live status for a physical device
-  - send_command          control a device (destructive commands need confirm:true)
-  - list_scenes           list all manual scenes
-  - run_scene             execute a manual scene
-  - search_catalog        offline catalog search by type/alias
-  - describe_device       metadata + commands + (optionally) live status for one device
-  - account_overview      single cold-start snapshot: devices + scenes + quota + cache + MQTT state
+The MCP server exposes eleven tools:
+  - list_devices            fetch all physical + IR devices
+  - get_device_status       live status for a physical device
+  - send_command            control a device (destructive commands need confirm:true)
+  - list_scenes             list all manual scenes
+  - run_scene               execute a manual scene
+  - search_catalog          offline catalog search by type/alias
+  - describe_device         metadata + commands + (optionally) live status for one device
+  - account_overview        single cold-start snapshot: devices + scenes + quota + cache + MQTT state
+  - get_device_history      fetch raw JSONL history records for a device
+  - query_device_history    filter + page history records with field/time predicates
+  - aggregate_device_history compute count/min/max/avg/sum/p50/p95 over history records
 
 Resource (read-only):
   - switchbot://events    snapshot of recent MQTT shadow events from the ring buffer
@@ -650,7 +739,7 @@ Inspect locally:
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({
                             ok: true,
-                            version: '2.0.0',
+                            version: VERSION,
                             pid: process.pid,
                             uptimeSec: Math.floor(process.uptime()),
                         }));
@@ -660,7 +749,7 @@ Inspect locally:
                         const state = eventManager.getState();
                         const ready = state !== 'failed' && state !== 'disabled';
                         const status = ready ? 200 : 503;
-                        const body = { ready, version: '2.0.0', mqtt: state };
+                        const body = { ready, version: VERSION, mqtt: state };
                         if (!ready)
                             body.reason = state === 'disabled' ? 'mqtt disabled' : 'mqtt failed';
                         res.writeHead(status, { 'Content-Type': 'application/json' });

package/dist/commands/plan.js

@@ -182,7 +182,12 @@ Workflow:
         .command('schema')
         .description('Print the JSON Schema for the plan format')
         .action(() => {
-        printJson(PLAN_JSON_SCHEMA);
+        printJson({
+            ...PLAN_JSON_SCHEMA,
+            agentNotes: {
+                deviceNameStrategy: "Plan step `deviceName` fields are resolved with the `require-unique` strategy (same default as `devices command`). Plans that expect a specific device should pin `deviceId` instead.",
+            },
+        });
     });
     plan
         .command('validate')

package/dist/commands/scenes.js

@@ -1,4 +1,4 @@
-import { printJson, isJsonMode, handleError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, StructuredUsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 export function registerScenesCommand(program) {
@@ -59,4 +59,46 @@ Example:
             handleError(error);
         }
     });
+    // switchbot scenes describe <sceneId>
+    scenes
+        .command('describe')
+        .description('Show metadata for a scene by its ID (SwitchBot API v1.1 does not expose step detail)')
+        .argument('<sceneId>', 'Scene ID from "scenes list"')
+        .addHelpText('after', `
+Note: SwitchBot API v1.1 does not return scene step detail. Only the scene name is available.
+
+Example:
+  $ switchbot scenes describe T12345678
+`)
+        .action(async (sceneId) => {
+        try {
+            const sceneList = await fetchScenes();
+            const found = sceneList.find((s) => s.sceneId === sceneId);
+            if (!found) {
+                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
+                    error: 'scene_not_found',
+                    sceneId,
+                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
+                });
+            }
+            const result = {
+                sceneId: found.sceneId,
+                sceneName: found.sceneName,
+                stepCount: null,
+                note: 'SwitchBot API v1.1 does not expose scene steps — displayed name only',
+            };
+            if (isJsonMode()) {
+                printJson(result);
+            }
+            else {
+                console.log(`sceneId:   ${result.sceneId}`);
+                console.log(`sceneName: ${result.sceneName}`);
+                console.log(`stepCount: (not available)`);
+                console.log(`note:      ${result.note}`);
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/schema.js

@@ -156,6 +156,12 @@ Examples:
                     type: 'object',
                     description: 'CLI-synthesized receipt-acknowledgment metadata. For IR devices, verifiable:false signals that no device-side confirmation is possible.',
                 },
+                {
+                    field: 'hints',
+                    appliesTo: ['agent-bootstrap'],
+                    type: 'string[]',
+                    description: 'CLI-synthesized advisory messages for the calling agent. Always emitted; empty array ([]) means no hints to report — never null and not a disabled-field signal.',
+                },
             ];
         }
         printJson(payload);

package/dist/devices/history-agg.js

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { jsonlFilesForDevice, parseDurationToMs, resolveRange } from './history-query.js';
+export const ALL_AGG_FNS = ['count', 'min', 'max', 'avg', 'sum', 'p50', 'p95'];
+export const DEFAULT_AGGS = ['count', 'avg'];
+export const DEFAULT_SAMPLE_CAP = 10_000;
+export const MAX_SAMPLE_CAP = 100_000;
+export async function aggregateDeviceHistory(deviceId, opts) {
+    const { fromMs, toMs } = resolveRange(opts);
+    const aggs = (opts.aggs && opts.aggs.length > 0) ? opts.aggs : [...DEFAULT_AGGS];
+    const needQuantile = aggs.includes('p50') || aggs.includes('p95');
+    let bucketMs = null;
+    if (opts.bucket !== undefined) {
+        bucketMs = parseDurationToMs(opts.bucket);
+        if (bucketMs === null) {
+            throw new Error(`Invalid --bucket "${opts.bucket}". Expected e.g. "15m", "1h", "1d".`);
+        }
+    }
+    const sampleCap = Math.max(1, Math.min(opts.maxBucketSamples ?? DEFAULT_SAMPLE_CAP, MAX_SAMPLE_CAP));
+    let partial = false;
+    const notes = [];
+    // bucketKey (epoch ms; 0 when no --bucket) → metric name → Acc
+    const buckets = new Map();
+    for (const file of jsonlFilesForDevice(deviceId)) {
+        try {
+            const st = fs.statSync(file);
+            if (st.mtimeMs < fromMs)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const stream = fs.createReadStream(file, { encoding: 'utf-8' });
+        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+        for await (const line of rl) {
+            if (!line)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const tMs = Date.parse(rec.t);
+            if (!Number.isFinite(tMs) || tMs < fromMs || tMs > toMs)
+                continue;
+            const key = bucketMs !== null ? Math.floor(tMs / bucketMs) * bucketMs : 0;
+            let bkt = buckets.get(key);
+            if (!bkt) {
+                bkt = new Map();
+                buckets.set(key, bkt);
+            }
+            for (const metric of opts.metrics) {
+                const v = rec.payload?.[metric];
+                if (typeof v !== 'number' || !Number.isFinite(v))
+                    continue;
+                let acc = bkt.get(metric);
+                if (!acc) {
+                    acc = {
+                        min: v,
+                        max: v,
+                        sum: 0,
+                        count: 0,
+                        samples: needQuantile ? [] : null,
+                        sampleCapHit: false,
+                    };
+                    bkt.set(metric, acc);
+                }
+                acc.min = Math.min(acc.min, v);
+                acc.max = Math.max(acc.max, v);
+                acc.sum += v;
+                acc.count += 1;
+                if (acc.samples) {
+                    if (acc.samples.length < sampleCap) {
+                        acc.samples.push(v);
+                    }
+                    else if (!acc.sampleCapHit) {
+                        acc.sampleCapHit = true;
+                        partial = true;
+                        notes.push(`bucket ${new Date(key).toISOString()} metric ${metric}: sample cap ${sampleCap} reached, quantiles approximate`);
+                    }
+                }
+            }
+        }
+    }
+    return finalize(deviceId, opts, aggs, buckets, partial, notes, fromMs, toMs);
+}
+function finalize(deviceId, opts, aggs, buckets, partial, notes, fromMs, toMs) {
+    const fromIso = Number.isFinite(fromMs) ? new Date(fromMs).toISOString() : new Date(0).toISOString();
+    const toIso = Number.isFinite(toMs) ? new Date(toMs).toISOString() : new Date(Date.now()).toISOString();
+    const keys = [...buckets.keys()].sort((a, b) => a - b);
+    const outBuckets = [];
+    for (const key of keys) {
+        const perMetric = buckets.get(key);
+        const metricsOut = {};
+        for (const [metric, acc] of perMetric.entries()) {
+            if (acc.count === 0)
+                continue;
+            const r = {};
+            if (aggs.includes('count'))
+                r.count = acc.count;
+            if (aggs.includes('min'))
+                r.min = acc.min;
+            if (aggs.includes('max'))
+                r.max = acc.max;
+            if (aggs.includes('avg'))
+                r.avg = acc.sum / acc.count;
+            if (aggs.includes('sum'))
+                r.sum = acc.sum;
+            if ((aggs.includes('p50') || aggs.includes('p95')) && acc.samples) {
+                const sorted = [...acc.samples].sort((a, b) => a - b);
+                if (aggs.includes('p50'))
+                    r.p50 = sorted[Math.floor(0.5 * (sorted.length - 1))];
+                if (aggs.includes('p95'))
+                    r.p95 = sorted[Math.floor(0.95 * (sorted.length - 1))];
+            }
+            metricsOut[metric] = r;
+        }
+        if (Object.keys(metricsOut).length === 0)
+            continue;
+        outBuckets.push({
+            t: new Date(key).toISOString(),
+            metrics: metricsOut,
+        });
+    }
+    return {
+        deviceId,
+        bucket: opts.bucket,
+        from: fromIso,
+        to: toIso,
+        metrics: [...opts.metrics],
+        aggs: [...aggs],
+        buckets: outBuckets,
+        partial,
+        notes,
+    };
+}

package/dist/devices/history-query.js

@@ -24,7 +24,7 @@ export function parseInstantToMs(spec) {
     const ms = Date.parse(spec);
     return Number.isFinite(ms) ? ms : null;
 }
-function resolveRange(opts) {
+export function resolveRange(opts) {
     let fromMs = Number.NEGATIVE_INFINITY;
     let toMs = Number.POSITIVE_INFINITY;
     if (opts.since && (opts.from || opts.to)) {

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { createRequire } from 'node:module';
+import chalk from 'chalk';
 import { intArg, stringArg, enumArg } from './utils/arg-parsers.js';
 import { parseDurationToMs } from './utils/flags.js';
 import { registerConfigCommand } from './commands/config.js';
@@ -21,6 +22,11 @@ import { registerCapabilitiesCommand } from './commands/capabilities.js';
 import { registerAgentBootstrapCommand } from './commands/agent-bootstrap.js';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../package.json');
+// Early initialization: check for --no-color flag or NO_COLOR env var and disable chalk.
+// This must happen before any commands run so all chalk output is affected.
+if (process.argv.includes('--no-color') || Boolean(process.env.NO_COLOR)) {
+    chalk.level = 0;
+}
 const program = new Command();
 // Top-level subcommand names. Used by stringArg to produce clearer errors when
 // a value is omitted and the next argv token turns out to be a subcommand name.
@@ -44,6 +50,7 @@ program
     .name('switchbot')
     .description('Command-line tool for SwitchBot API v1.1')
     .version(pkgVersion)
+    .option('--no-color', 'Disable ANSI colors in output')
     .option('--json', 'Output raw JSON response (disables tables; useful for pipes/scripts)')
     .option('--format <type>', 'Output format: table (default), json, jsonl, tsv, yaml, id, markdown', enumArg('--format', ['table', 'json', 'jsonl', 'tsv', 'yaml', 'id', 'markdown']))
     .option('--fields <csv>', 'Comma-separated list of columns to include (e.g. --fields=id,name,type)', stringArg('--fields', { disallow: TOP_LEVEL_COMMANDS }))

package/dist/mcp/device-history.js

@@ -31,19 +31,30 @@ export class DeviceHistoryStore {
             existing.history = [entry, ...existing.history].slice(0, MAX_HISTORY);
             fs.writeFileSync(file, JSON.stringify(existing, null, 2), { mode: 0o600 });
             // 2. Append-only JSONL for range queries.
-            this.appendJsonl(deviceId, entry);
+            this.writeJsonl(deviceId, entry);
         }
         catch {
             // best-effort — history loss is non-fatal
         }
     }
-    appendJsonl(deviceId, entry) {
+    /** Append a mqtt control event (no deviceId) to the dedicated __control.jsonl file. */
+    recordControl(event) {
         try {
-            const jsonlPath = path.join(this.dir, `${deviceId}.jsonl`);
-            const line = JSON.stringify(entry) + '\n';
+            if (!fs.existsSync(this.dir))
+                fs.mkdirSync(this.dir, { recursive: true });
+            this.writeJsonl('__control', event);
+        }
+        catch {
+            // best-effort — never block the event stream
+        }
+    }
+    writeJsonl(fileKey, record) {
+        try {
+            const jsonlPath = path.join(this.dir, `${fileKey}.jsonl`);
+            const line = JSON.stringify(record) + '\n';
             const lineBytes = Buffer.byteLength(line, 'utf-8');
             // Seed size counter from disk on first touch (avoids drift across restarts).
-            let size = this.jsonlSizes.get(deviceId);
+            let size = this.jsonlSizes.get(fileKey);
             if (size === undefined) {
                 try {
                     size = fs.existsSync(jsonlPath) ? fs.statSync(jsonlPath).size : 0;
@@ -53,18 +64,18 @@ export class DeviceHistoryStore {
                 }
             }
             if (size + lineBytes > JSONL_ROTATE_BYTES) {
-                this.rotateJsonl(deviceId);
+                this.rotateJsonl(fileKey);
                 size = 0;
             }
             fs.appendFileSync(jsonlPath, line, { mode: 0o600 });
-            this.jsonlSizes.set(deviceId, size + lineBytes);
+            this.jsonlSizes.set(fileKey, size + lineBytes);
         }
         catch {
             // best-effort
         }
     }
-    rotateJsonl(deviceId) {
-        const base = path.join(this.dir, `${deviceId}.jsonl`);
+    rotateJsonl(fileKey) {
+        const base = path.join(this.dir, `${fileKey}.jsonl`);
         // .jsonl.3 is dropped; .2 → .3, .1 → .2, current → .1
         try {
             const oldest = `${base}.${JSONL_KEEP_ROTATIONS}`;

package/dist/utils/audit.js

@@ -55,7 +55,7 @@ export function verifyAudit(file) {
         problems: [],
     };
     if (!fs.existsSync(file)) {
-        report.problems.push({ line: 0, reason: 'audit log file does not exist' });
+        report.fileMissing = true;
         return report;
     }
     const raw = fs.readFileSync(file, 'utf-8');

package/dist/utils/format.js

@@ -12,8 +12,9 @@ export function parseFormat(flag) {
         case 'tsv': return 'tsv';
         case 'yaml': return 'yaml';
         case 'id': return 'id';
+        case 'markdown': return 'markdown';
         default: {
-            const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id.`;
+            const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id, markdown.`;
             if (isJsonMode()) {
                 console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
             }
@@ -67,6 +68,13 @@ export function renderRows(headers, rows, format, fields, aliases) {
     const filtered = filterFields(headers, rows, fields, aliases);
     const h = filtered.headers;
     const r = filtered.rows;
+    // Markdown format is rendered as table with markdown style forced regardless
+    // of the user's --table-style, so `--format markdown` is a self-contained
+    // contract (bug #8).
+    if (format === 'markdown') {
+        printTable(h, r, 'markdown');
+        return;
+    }
     switch (format) {
         case 'table':
             printTable(h, r);

package/dist/utils/name-resolver.js

@@ -34,9 +34,17 @@ function resolveDeviceByName(query, opts = {}) {
         const alias = meta.devices[deviceId]?.alias;
         const rawName = normalizeDeviceName(device.name);
         const normAlias = alias ? normalizeDeviceName(alias) : null;
-        // exact alias/name wins regardless of strategy
+        // exact alias/name wins immediately for lenient strategies.
+        // Under require-unique we must NOT short-circuit: there may be other devices
+        // that also match (e.g. via substring), making the result ambiguous.  Collect
+        // the exact hit as a candidate and let the full ambiguity check decide below.
         if ((normAlias && normAlias === q) || rawName === q) {
-            return { ok: true, deviceId };
+            if (strategy !== 'require-unique') {
+                return { ok: true, deviceId };
+            }
+            // require-unique: treat exact match as a high-priority candidate (score 0)
+            candidates.push({ deviceId, name: device.name, score: 0 });
+            continue;
         }
         if (strategy === 'exact')
             continue;

package/dist/utils/output.js

@@ -46,8 +46,8 @@ const ASCII_BORDER_CHARS = {
     left: '|', 'left-mid': '+', mid: '-', 'mid-mid': '+',
     right: '|', 'right-mid': '+', middle: '|',
 };
-export function printTable(headers, rows) {
-    const style = getTableStyle();
+export function printTable(headers, rows, styleOverride) {
+    const style = styleOverride ?? getTableStyle();
     if (style === 'markdown') {
         console.log(renderMarkdownTable(headers, rows));
         return;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",