@switchbot/openapi-cli 2.6.3 → 2.7.2

package/dist/commands/doctor.js

@@ -1,10 +1,14 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { printJson, isJsonMode } from '../utils/output.js';
+import { printJson, isJsonMode, exitWithError } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
-import { describeCache } from '../devices/cache.js';
+import { describeCache, resetListCache } from '../devices/cache.js';
+import { DAILY_QUOTA, todayUsage } from '../utils/quota.js';
+import { AGENT_BOOTSTRAP_SCHEMA_VERSION } from './agent-bootstrap.js';
+import { CATALOG_SCHEMA_VERSION } from '../devices/catalog.js';
+import { createSwitchBotMcpServer, listRegisteredTools } from './mcp.js';
 export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
@@ -160,15 +164,148 @@ function checkCache() {
 function checkQuotaFile() {
     const p = path.join(os.homedir(), '.switchbot', 'quota.json');
     if (!fs.existsSync(p)) {
-        return { name: 'quota', status: 'ok', detail: 'no quota file yet (will be created on first call)' };
+        return {
+            name: 'quota',
+            status: 'ok',
+            detail: {
+                path: p,
+                percentUsed: 0,
+                remaining: DAILY_QUOTA,
+                message: 'no quota file yet (will be created on first call)',
+            },
+        };
     }
     try {
         const raw = fs.readFileSync(p, 'utf-8');
         JSON.parse(raw);
-        return { name: 'quota', status: 'ok', detail: p };
     }
     catch {
-        return { name: 'quota', status: 'warn', detail: `${p} unreadable/malformed — run 'switchbot quota reset'` };
+        return {
+            name: 'quota',
+            status: 'warn',
+            detail: { path: p, message: `unreadable/malformed — run 'switchbot quota reset'` },
+        };
+    }
+    // P9: surface headroom so agents can decide when to slow down or pause.
+    // Quota resets at local midnight (the quota counter buckets by local
+    // date), so project the next reset to the next 00:00:00 local.
+    const usage = todayUsage();
+    const percentUsed = Math.round((usage.total / DAILY_QUOTA) * 100);
+    const now = new Date();
+    const reset = new Date(now);
+    reset.setHours(24, 0, 0, 0); // next local midnight
+    const status = percentUsed > 80 ? 'warn' : 'ok';
+    const recommendation = percentUsed > 90
+        ? 'over 90% used — consider --no-quota for read-only triage or rescheduling work after the reset'
+        : percentUsed > 80
+            ? 'over 80% used — avoid bulk operations until the daily reset'
+            : 'headroom available';
+    return {
+        name: 'quota',
+        status,
+        detail: {
+            path: p,
+            percentUsed,
+            remaining: usage.remaining,
+            total: usage.total,
+            dailyCap: DAILY_QUOTA,
+            projectedResetTime: reset.toISOString(),
+            recommendation,
+        },
+    };
+}
+function checkCatalogSchema() {
+    // P9: sentinel against silent drift between the catalog shape and the
+    // agent-bootstrap payload. Both constants are exported from their
+    // respective modules; if a future refactor changes one without the
+    // other, this check fails so consumers (agents) learn before the
+    // mismatch corrupts their mental model.
+    const match = CATALOG_SCHEMA_VERSION === AGENT_BOOTSTRAP_SCHEMA_VERSION;
+    return {
+        name: 'catalog-schema',
+        status: match ? 'ok' : 'fail',
+        detail: {
+            catalogSchemaVersion: CATALOG_SCHEMA_VERSION,
+            bootstrapExpectsVersion: AGENT_BOOTSTRAP_SCHEMA_VERSION,
+            match,
+            message: match
+                ? 'catalog and agent-bootstrap schemaVersion aligned'
+                : 'catalog and agent-bootstrap schemaVersion have drifted — bump in lockstep',
+        },
+    };
+}
+function checkAudit() {
+    // P9: surface recent command failures so agents / ops can spot problems
+    // before they page. When --audit-log was never enabled, the file won't
+    // exist — report that cleanly rather than as an error.
+    const p = path.join(os.homedir(), '.switchbot', 'audit.log');
+    if (!fs.existsSync(p)) {
+        return {
+            name: 'audit',
+            status: 'ok',
+            detail: {
+                path: p,
+                enabled: false,
+                message: 'audit log not present (enable with --audit-log)',
+            },
+        };
+    }
+    try {
+        const raw = fs.readFileSync(p, 'utf-8');
+        const since = Date.now() - 24 * 60 * 60 * 1000;
+        const recent = [];
+        let total = 0;
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (rec.result !== 'error')
+                continue;
+            total += 1;
+            const ts = rec.t ? Date.parse(rec.t) : NaN;
+            if (Number.isFinite(ts) && ts >= since) {
+                recent.push({
+                    t: rec.t,
+                    command: rec.command ?? '?',
+                    deviceId: rec.deviceId,
+                    error: rec.error ?? 'unknown',
+                });
+            }
+        }
+        // Cap the report to the 10 most recent so the doctor payload stays
+        // bounded even on a log with thousands of errors.
+        recent.sort((a, b) => (a.t < b.t ? 1 : -1));
+        const clipped = recent.slice(0, 10);
+        const status = recent.length > 0 ? 'warn' : 'ok';
+        return {
+            name: 'audit',
+            status,
+            detail: {
+                path: p,
+                enabled: true,
+                totalErrors: total,
+                errorsLast24h: recent.length,
+                recent: clipped,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'audit',
+            status: 'warn',
+            detail: {
+                path: p,
+                enabled: true,
+                message: `could not read audit log: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
     }
 }
 function checkNodeVersion() {
@@ -210,10 +347,160 @@ function checkMqtt() {
         detail: "unavailable — configure credentials first (see credentials check above)",
     };
 }
+async function checkMqttProbe() {
+    // P10: live-probe the MQTT broker. Only runs when --probe is passed.
+    // Does not subscribe — just connects + disconnects to verify the
+    // credential + TLS handshake works end-to-end. Hard 5s timeout so
+    // a misbehaving broker never wedges the doctor command.
+    const { fetchMqttCredential } = await import('../mqtt/credential.js');
+    const { SwitchBotMqttClient } = await import('../mqtt/client.js');
+    const token = process.env.SWITCHBOT_TOKEN;
+    const secret = process.env.SWITCHBOT_SECRET;
+    let creds = null;
+    if (token && secret) {
+        creds = { token, secret };
+    }
+    else {
+        const file = configFilePath();
+        if (fs.existsSync(file)) {
+            try {
+                const cfg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+                if (cfg.token && cfg.secret) {
+                    creds = { token: cfg.token, secret: cfg.secret };
+                }
+            }
+            catch { /* fall through */ }
+        }
+    }
+    if (!creds) {
+        return {
+            name: 'mqtt',
+            status: 'warn',
+            detail: { probe: 'skipped', reason: 'no credentials configured' },
+        };
+    }
+    const deadline = new Promise((_, reject) => setTimeout(() => reject(new Error('probe timeout after 5000ms')), 5000));
+    try {
+        const cred = await Promise.race([fetchMqttCredential(creds.token, creds.secret), deadline]);
+        const client = new SwitchBotMqttClient(cred);
+        await Promise.race([client.connect(), deadline]);
+        await client.disconnect();
+        return {
+            name: 'mqtt',
+            status: 'ok',
+            detail: { probe: 'connected', brokerUrl: cred.brokerUrl, region: cred.region },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'mqtt',
+            status: 'warn',
+            detail: { probe: 'failed', reason: err instanceof Error ? err.message : String(err) },
+        };
+    }
+}
+function checkMcp() {
+    // P10: dry-run instantiation of the MCP server to catch tool-registration
+    // regressions. No network I/O, no token needed. If createSwitchBotMcpServer
+    // throws (e.g. duplicate tool name, schema build error) the check fails.
+    try {
+        const server = createSwitchBotMcpServer();
+        const tools = listRegisteredTools(server);
+        return {
+            name: 'mcp',
+            status: 'ok',
+            detail: {
+                serverInstantiated: true,
+                toolCount: tools.length,
+                tools,
+                transportsAvailable: ['stdio', 'http'],
+                message: `${tools.length} tools registered; no network probe`,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'mcp',
+            status: 'fail',
+            detail: {
+                serverInstantiated: false,
+                error: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+}
+const CHECK_REGISTRY = [
+    { name: 'node', description: 'Node.js version compatibility', run: () => checkNodeVersion() },
+    { name: 'credentials', description: 'credentials file present and parseable', run: () => checkCredentials() },
+    { 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() },
+    { name: 'cache', description: 'device cache state', run: () => checkCache() },
+    { name: 'quota', description: 'API quota headroom', run: () => checkQuotaFile() },
+    { name: 'clock', description: 'system clock skew', run: () => checkClockSkew() },
+    {
+        name: 'mqtt',
+        description: 'MQTT credentials (+ --probe for live broker handshake)',
+        run: ({ probe }) => (probe ? checkMqttProbe() : checkMqtt()),
+    },
+    { name: 'mcp', description: 'MCP server instantiable + tool count', run: () => checkMcp() },
+    { name: 'audit', description: 'recent command errors (last 24h)', run: () => checkAudit() },
+];
+function applyFixes(checks, writeOk) {
+    const results = [];
+    for (const c of checks) {
+        if (c.name === 'cache' && c.status !== 'ok') {
+            if (writeOk) {
+                try {
+                    resetListCache();
+                    results.push({ check: 'cache', action: 'cache-cleared', applied: true });
+                }
+                catch (err) {
+                    results.push({
+                        check: 'cache',
+                        action: 'cache-clear',
+                        applied: false,
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            else {
+                results.push({
+                    check: 'cache',
+                    action: 'cache-clear',
+                    applied: false,
+                    message: 'pass --yes to apply',
+                });
+            }
+        }
+        else if (c.name === 'catalog-schema' && c.status !== 'ok') {
+            results.push({
+                check: 'catalog-schema',
+                action: 'manual',
+                applied: false,
+                message: "drift detected — run 'switchbot capabilities --reload' to refresh overlay",
+            });
+        }
+        else if (c.name === 'credentials' && c.status === 'fail') {
+            results.push({
+                check: 'credentials',
+                action: 'manual',
+                applied: false,
+                message: "run 'switchbot config set-token' to configure credentials",
+            });
+        }
+    }
+    return results;
+}
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
-        .description('Self-check: credentials, catalog, cache, quota, profiles, Node version')
+        .description('Self-check the SwitchBot CLI setup: credentials, catalog, cache, quota, MQTT, 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)')
+        .option('--yes', 'Required together with --fix to confirm write actions')
+        .option('--probe', 'Perform live-probe variant of checks that support it (mqtt)')
         .addHelpText('after', `
 Runs a battery of local sanity checks and exits with code 0 only when every
 check is 'ok'. 'warn' → exit 0 (informational); 'fail' → exit 1.
@@ -221,18 +508,52 @@ check is 'ok'. 'warn' → exit 0 (informational); 'fail' → exit 1.
 Examples:
   $ switchbot doctor
   $ switchbot --json doctor | jq '.checks[] | select(.status != "ok")'
+  $ switchbot doctor --list
+  $ switchbot doctor --section credentials,mcp --json
+  $ switchbot doctor --probe --json
+  $ switchbot doctor --fix --yes --json
 `)
-        .action(async () => {
-        const checks = [
-            checkNodeVersion(),
-            await checkCredentials(),
-            checkProfiles(),
-            checkCatalog(),
-            checkCache(),
-            checkQuotaFile(),
-            await checkClockSkew(),
-            checkMqtt(),
-        ];
+        .action(async (opts) => {
+        // --list: print the registry and exit 0.
+        if (opts.list) {
+            if (isJsonMode()) {
+                printJson({
+                    checks: CHECK_REGISTRY.map((c) => ({ name: c.name, description: c.description })),
+                });
+            }
+            else {
+                console.log('Available checks:');
+                for (const c of CHECK_REGISTRY) {
+                    console.log(`  ${c.name.padEnd(16)} ${c.description}`);
+                }
+            }
+            return;
+        }
+        // --section: run only the named subset, dedup and validate.
+        let selected = CHECK_REGISTRY;
+        if (opts.section) {
+            const raw = opts.section.split(',').map((s) => s.trim()).filter(Boolean);
+            const names = Array.from(new Set(raw));
+            const known = new Set(CHECK_REGISTRY.map((c) => c.name));
+            const unknown = names.filter((n) => !known.has(n));
+            if (unknown.length > 0) {
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: `Unknown check name(s): ${unknown.join(', ')}. Valid: ${CHECK_REGISTRY.map((c) => c.name).join(', ')}`,
+                });
+                return;
+            }
+            const order = new Map(CHECK_REGISTRY.map((c, i) => [c.name, i]));
+            selected = names
+                .map((n) => CHECK_REGISTRY.find((c) => c.name === n))
+                .sort((a, b) => (order.get(a.name) - order.get(b.name)));
+        }
+        const runOpts = { probe: Boolean(opts.probe) };
+        const checks = [];
+        for (const def of selected) {
+            checks.push(await def.run(runOpts));
+        }
         const summary = {
             ok: checks.filter((c) => c.status === 'ok').length,
             warn: checks.filter((c) => c.status === 'warn').length,
@@ -240,20 +561,27 @@ Examples:
         };
         const overallFail = summary.fail > 0;
         const overall = overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok';
+        let fixes;
+        if (opts.fix) {
+            fixes = applyFixes(checks, Boolean(opts.yes));
+        }
         if (isJsonMode()) {
             // Stable contract (locked as doctor.schemaVersion=1):
             //   { ok: boolean, overall: 'ok'|'warn'|'fail', generatedAt, schemaVersion,
             //     summary: { ok, warn, fail }, checks: [{ name, status, detail }] }
             // `ok` is an alias of (overall === 'ok') — agents prefer the boolean,
             // humans prefer the string; both are provided.
-            printJson({
+            const payload = {
                 ok: overall === 'ok',
                 overall,
                 generatedAt: new Date().toISOString(),
                 schemaVersion: DOCTOR_SCHEMA_VERSION,
                 summary,
                 checks,
-            });
+            };
+            if (fixes !== undefined)
+                payload.fixes = fixes;
+            printJson(payload);
         }
         else {
             for (const c of checks) {
@@ -263,6 +591,14 @@ Examples:
             }
             console.log('');
             console.log(`${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);
+            if (fixes && fixes.length > 0) {
+                console.log('');
+                console.log('Fixes:');
+                for (const f of fixes) {
+                    const marker = f.applied ? '✓' : '-';
+                    console.log(`  ${marker} ${f.check}: ${f.action}${f.message ? ' — ' + f.message : ''}`);
+                }
+            }
         }
         if (overallFail)
             process.exit(1);

package/dist/commands/events.js

@@ -1,6 +1,6 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
-import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, emitStreamHeader } from '../utils/output.js';
 import { intArg, stringArg, durationArg } from '../utils/arg-parsers.js';
 import { parseDurationToMs } from '../utils/flags.js';
 import { parseFilterExpr, matchClause, FilterSyntaxError } from '../utils/filter.js';
@@ -19,6 +19,16 @@ import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
+/**
+ * P6: unified-envelope schema version shared by webhook and MQTT event output.
+ *
+ * The same key set now appears on both `events tail` (webhook) and
+ * `events mqtt-tail` (MQTT) output lines so downstream JSONL consumers can
+ * use a single parser regardless of source. Old fields are kept for one
+ * minor window so existing consumers keep working — see README and
+ * CHANGELOG for the deprecation schedule.
+ */
+export const EVENTS_SCHEMA_VERSION = '1';
 function extractEventId(parsed) {
     if (!parsed || typeof parsed !== 'object')
         return null;
@@ -30,13 +40,27 @@ function extractEventId(parsed) {
         return ctx.eventId;
     return null;
 }
-function matchFilter(body, clauses) {
+function extractDeviceId(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    const ctx = p.context ?? p;
+    const mac = ctx.deviceMac;
+    if (typeof mac === 'string' && mac.length > 0)
+        return mac;
+    const id = ctx.deviceId;
+    if (typeof id === 'string' && id.length > 0)
+        return id;
+    return null;
+}
+function matchFilterDetail(body, clauses) {
     if (!clauses || clauses.length === 0)
-        return true;
+        return { matched: true, matchedKeys: [] };
     if (!body || typeof body !== 'object')
-        return false;
+        return { matched: false, matchedKeys: [] };
     const b = body;
     const ctx = (b.context ?? b);
+    const hitKeys = [];
     for (const c of clauses) {
         let candidate;
         if (c.key === 'deviceId') {
@@ -49,9 +73,10 @@ function matchFilter(body, clauses) {
             candidate = typeof t === 'string' ? t : '';
         }
         if (!matchClause(candidate, c))
-            return false;
+            return { matched: false, matchedKeys: [] };
+        hitKeys.push(c.key);
     }
-    return true;
+    return { matched: true, matchedKeys: hitKeys };
 }
 const EVENT_FILTER_KEYS = ['deviceId', 'type'];
 function parseFilter(flag) {
@@ -108,11 +133,22 @@ export function startReceiver(port, pathMatch, filter, onEvent) {
             catch {
                 // keep raw
             }
-            const matched = matchFilter(body, filter);
+            const { matched, matchedKeys } = matchFilterDetail(body, filter);
+            const t = new Date().toISOString();
+            const urlPath = req.url ?? '/';
             onEvent({
-                t: new Date().toISOString(),
+                schemaVersion: EVENTS_SCHEMA_VERSION,
+                source: 'webhook',
+                kind: 'event',
+                t,
+                eventId: extractEventId(body),
+                deviceId: extractDeviceId(body),
+                topic: urlPath,
+                payload: body,
+                matchedKeys,
+                // Legacy mirror:
                 remote: `${req.socket.remoteAddress ?? ''}:${req.socket.remotePort ?? ''}`,
-                path: req.url ?? '/',
+                path: urlPath,
                 body,
                 matched,
             });
@@ -143,9 +179,14 @@ SwitchBot posts events to a single webhook URL configured via:
 the port to the internet yourself (ngrok/cloudflared/reverse proxy) and
 point the SwitchBot webhook at that public URL.
 
-Output (JSONL, one event per line):
-  { "t": "<ISO>", "remote": "<ip:port>", "path": "/",
-    "body": <parsed JSON or raw string>, "matched": true }
+Output (JSONL, one event per line; P6 unified envelope v2.7+):
+  { "schemaVersion": "1", "source": "webhook", "kind": "event",
+    "t": "<ISO>", "eventId": <string|null>, "deviceId": <string|null>,
+    "topic": "/",               // = path
+    "payload": <parsed JSON or raw string>,
+    "matchedKeys": ["deviceId"], // which filter clauses matched
+    // Legacy fields kept for one minor window (removed in v3.0):
+    "remote": "<ip:port>", "path": "/", "body": <payload>, "matched": true }
 
 Filter grammar: comma-separated clauses (AND-ed). Each clause is one of
   key=value     — case-insensitive substring
@@ -179,6 +220,10 @@ Examples:
             const forTimer = forMs !== null && forMs > 0
                 ? setTimeout(() => ac.abort(), forMs)
                 : null;
+            // P7: streaming JSON contract — first line under --json is the
+            // stream header (webhook events arrive via push cadence).
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'event', cadence: 'push' });
             await new Promise((resolve, reject) => {
                 let server = null;
                 try {
@@ -244,14 +289,20 @@ Connects to the SwitchBot MQTT service using your existing credentials
 (SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
 No additional MQTT configuration required.
 
-Output (JSONL, one event per line):
-  { "t": "<ISO>", "eventId": "<uuid>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+Output (JSONL, one event per line; P6 unified envelope v2.7+):
+  { "schemaVersion": "1", "source": "mqtt", "kind": "event",
+    "t": "<ISO>", "eventId": "<uuid>", "deviceId": <string|null>,
+    "topic": "<mqtt-topic>",
+    "payload": <parsed JSON or raw string> }
 
-Control records (interleaved, no "payload" field — use type-prefix to filter):
-  { "type": "__session_start", "at": "<ISO>", "eventId": "<uuid>", "state": "connecting" }  before credential fetch (JSON mode only)
-  { "type": "__connect",     "at": "<ISO>", "eventId": "<uuid>" }   first successful connect
-  { "type": "__reconnect",   "at": "<ISO>", "eventId": "<uuid>" }   connect after a disconnect
-  { "type": "__disconnect",  "at": "<ISO>", "eventId": "<uuid>" }   reconnecting or failed
+Control records (interleaved, kind: "control" — filter by the "kind" field):
+  { "schemaVersion": "1", "source": "mqtt", "kind": "control",
+    "controlKind": "session_start"|"connect"|"reconnect"|"disconnect"|"heartbeat",
+    "t": "<ISO>", "eventId": "<uuid>",
+    "state": "connecting"         // present on session_start only
+    // Legacy fields kept for one minor window (removed in v3.0):
+    "type": "__session_start"|"__connect"|"__reconnect"|"__disconnect",
+    "at":   "<ISO>"  }
 
 Reconnect policy: the MQTT client retries with exponential backoff
 (1s → 30s capped, forever) while the credential is still valid; if the
@@ -346,15 +397,27 @@ Examples:
             if (!isJsonMode()) {
                 console.error('Fetching MQTT credentials from SwitchBot service…');
             }
+            // P7: streaming JSON contract — first line under --json is the stream
+            // header (mqtt events arrive via push cadence). Must emit BEFORE
+            // __session_start so header is always the very first line.
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'event', cadence: 'push' });
             // Emit a __session_start envelope immediately (before any credential
             // fetch) so JSON consumers can distinguish "connecting" from "never
             // connected" even when mqtt-tail exits before the broker connects.
             if (isJsonMode()) {
+                const sessionStartAt = new Date().toISOString();
                 printJson({
-                    type: '__session_start',
-                    at: new Date().toISOString(),
+                    schemaVersion: EVENTS_SCHEMA_VERSION,
+                    source: 'mqtt',
+                    kind: 'control',
+                    controlKind: 'session_start',
+                    t: sessionStartAt,
                     eventId: crypto.randomUUID(),
                     state: 'connecting',
+                    // Legacy (deprecated as of v2.7; removed in v3.0):
+                    type: '__session_start',
+                    at: sessionStartAt,
                 });
             }
             const credential = await fetchMqttCredential(loaded.token, loaded.secret);
@@ -389,7 +452,16 @@ Examples:
                     // Default behavior: record history + print to stdout
                     const { deviceId, deviceType } = parseSinkEvent(parsed);
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
-                    const record = { t, eventId, topic: msgTopic, payload: parsed };
+                    const record = {
+                        schemaVersion: EVENTS_SCHEMA_VERSION,
+                        source: 'mqtt',
+                        kind: 'event',
+                        t,
+                        eventId,
+                        deviceId: deviceId ?? null,
+                        topic: msgTopic,
+                        payload: parsed,
+                    };
                     if (isJsonMode()) {
                         printJson(record);
                     }
@@ -405,7 +477,24 @@ Examples:
             let mqttFailed = false;
             let hasConnectedBefore = false;
             const emitControl = (kind) => {
-                const ctl = { type: kind, at: new Date().toISOString(), eventId: crypto.randomUUID() };
+                const at = new Date().toISOString();
+                const controlKindMap = {
+                    __connect: 'connect',
+                    __reconnect: 'reconnect',
+                    __disconnect: 'disconnect',
+                    __heartbeat: 'heartbeat',
+                };
+                const ctl = {
+                    schemaVersion: EVENTS_SCHEMA_VERSION,
+                    source: 'mqtt',
+                    kind: 'control',
+                    controlKind: controlKindMap[kind],
+                    t: at,
+                    eventId: crypto.randomUUID(),
+                    // Legacy (deprecated as of v2.7; removed in v3.0):
+                    type: kind,
+                    at,
+                };
                 // Control events always go to stdout as JSONL so consumers that
                 // filter real events by presence of `payload` can skip them.
                 if (isJsonMode()) {