@switchbot/openapi-cli 2.4.0 → 2.5.1

package/dist/commands/history.js

@@ -1,10 +1,11 @@
 import path from 'node:path';
 import os from 'node:os';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, emitJsonError } from '../utils/output.js';
 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
@@ -71,7 +72,7 @@ Examples:
         if (!Number.isInteger(idx) || idx < 1 || idx > entries.length) {
             const msg = `Invalid index ${indexArg}. Log has ${entries.length} entries.`;
             if (isJsonMode()) {
-                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                emitJsonError({ code: 2, kind: 'usage', message: msg });
             }
             else {
                 console.error(msg);
@@ -82,7 +83,7 @@ Examples:
         if (entry.kind !== 'command') {
             const msg = `Entry ${idx} is not a command (kind=${entry.kind}).`;
             if (isJsonMode()) {
-                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                emitJsonError({ code: 2, kind: 'usage', message: msg });
             }
             else {
                 console.error(msg);
@@ -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,129 @@ 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}"` : ''}`);
+                    }
+                }
+            }
+        }
+        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'))
+        .requiredOption('--metric <name>', 'Payload field to aggregate (repeat for multiple; required)', (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 (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);
                 }
             }
         }
-        const ok = report.malformedLines === 0 && report.problems.length === 0;
-        process.exit(ok ? 0 : 1);
+        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

@@ -3,7 +3,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode } from '../utils/output.js';
+import { handleError, isJsonMode, buildErrorPayload, emitJsonError } 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';
@@ -24,16 +26,41 @@ function mcpError(kind, code, message, options) {
         obj.retryable = true;
     if (options?.context)
         obj.context = options.context;
+    if (options?.subKind !== undefined)
+        obj.subKind = options.subKind;
+    if (options?.errorClass !== undefined)
+        obj.errorClass = options.errorClass;
+    if (options?.transient !== undefined)
+        obj.transient = options.transient;
+    if (options?.retryAfterMs !== undefined)
+        obj.retryAfterMs = options.retryAfterMs;
     return {
         isError: true,
         content: [{ type: 'text', text: JSON.stringify({ error: obj }, null, 2) }],
+        structuredContent: { error: obj },
     };
 }
+/**
+ * Convert any thrown error into a structured MCP tool-error response,
+ * preserving all ErrorPayload fields (subKind, transient, hint, etc.).
+ */
+function apiErrorToMcpError(err) {
+    const payload = buildErrorPayload(err);
+    return mcpError(payload.kind, payload.code, payload.message, {
+        hint: payload.hint,
+        retryable: payload.retryable,
+        context: payload.context,
+        subKind: payload.subKind,
+        errorClass: payload.errorClass,
+        transient: payload.transient,
+        retryAfterMs: payload.retryAfterMs,
+    });
+}
 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 +87,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 +123,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 +148,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 +183,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 +223,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 +245,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 +263,41 @@ 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. We still preflight the deviceId
+        // against the local cache so fabricated IDs don't silently pass
+        // validation (bug #SYS-3). Dry-run is meant to catch bad inputs; a
+        // dry-run that accepts anything is worse than no dry-run at all.
+        if (dryRun) {
+            const cached = getCachedDevice(deviceId);
+            if (!cached) {
+                return mcpError('usage', 2, `Device "${deviceId}" not found in local cache.`, {
+                    subKind: 'device-not-found',
+                    hint: "Run 'list_devices' first to warm the cache, then retry with dryRun:true.",
+                    context: { deviceId },
+                });
+            }
+            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.
@@ -287,7 +355,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     },
                 });
             }
-            throw err;
+            return apiErrorToMcpError(err);
         }
         const isIr = getCachedDevice(deviceId)?.category === 'ir';
         const structured = { ok: true, command, deviceId, result };
@@ -307,15 +375,37 @@ 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 }) => {
-        await executeScene(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,
+            };
+        }
+        try {
+            await executeScene(sceneId);
+        }
+        catch (err) {
+            return apiErrorToMcpError(err);
+        }
         const structured = { ok: true, sceneId };
         return {
             content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
@@ -326,7 +416,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 +432,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: {
-            query: z.string().describe('Search query (matches type and aliases, case-insensitive). Use empty string to list all.'),
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
+            query: z.string().describe('Search query (matches type and aliases, case-insensitive). Must be non-empty; use list_catalog_types to enumerate instead.'),
             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(),
@@ -365,6 +457,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             total: z.number().int().describe('Number of entries returned'),
         },
     }, async ({ query, limit }) => {
+        if (query.trim() === '') {
+            return mcpError('usage', 2, 'search_catalog requires a non-empty query.', {
+                hint: "Pass a search term like 'Bot' or 'Hub', or call list_catalog_types to enumerate all types without a query.",
+            });
+        }
         const hits = searchCatalog(query, limit);
         const structured = { results: hits, total: hits.length };
         return {
@@ -376,10 +473,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(),
@@ -414,14 +512,48 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     context: { deviceId },
                 });
             }
-            throw err;
+            return apiErrorToMcpError(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 +604,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 +665,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
@@ -581,7 +716,7 @@ Inspect locally:
                 if (!Number.isFinite(port) || port < 1 || port > 65535) {
                     const msg = `Invalid --port "${options.port}". Must be 1-65535.`;
                     if (isJsonMode()) {
-                        console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                        emitJsonError({ code: 2, kind: 'usage', message: msg });
                     }
                     else {
                         console.error(msg);
@@ -597,7 +732,7 @@ Inspect locally:
                 if (!isLocalhost && !authToken) {
                     const msg = 'Refusing to listen on 0.0.0.0 without --auth-token. Pass --auth-token <token> or bind to localhost (default).';
                     if (isJsonMode()) {
-                        console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                        emitJsonError({ code: 2, kind: 'usage', message: msg });
                     }
                     else {
                         console.error(msg);
@@ -650,7 +785,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 +795,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,12 +182,22 @@ 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')
-        .description('Validate a plan file (or stdin) against the schema')
+        .description('Validate a plan file (or stdin) against the schema (structural only; does not verify device or scene existence)')
         .argument('[file]', 'Path to plan.json, or "-" / omit to read stdin')
+        .addHelpText('after', `
+To check semantic validity (e.g., that deviceIds and sceneIds actually exist),
+use 'plan run --dry-run' which exercises name resolution and device lookup
+against the live API without executing any mutations.
+`)
         .action(async (file) => {
         let raw;
         try {