@coffeerunhobby/mcp-ha-connect 2.1.1 → 2.2.1

package/src/server/http.ts

@@ -15,6 +15,7 @@ import { handleEventSubscription } from './eventSubscription.js';
 import { RateLimiter } from './rateLimiter.js';
 import { createAuthMiddleware } from './auth.js';
 import { sanitizeError } from '../utils/sanitizeError.js';
+import { OwnerQuestionService } from '../ownerQuestions/service.js';
 import {
   LEGACY_BINDINGS,
   resolveChatBindings,
@@ -343,23 +344,45 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     audience: config.authAudience,
   });
 
-  // Initialize event subscriber if SSE events are enabled and HA is configured
+  // Initialize the HA event subscriber when SSE events or owner questions need it
   let eventSubscriber: EventSubscriber | null = null;
-  if (config.sseEventsEnabled && config.baseUrl && config.token) {
+  if ((config.sseEventsEnabled || config.ownerQuestionsEnabled) && config.baseUrl && config.token) {
     eventSubscriber = new EventSubscriber({
       baseUrl: config.baseUrl,
       token: config.token,
+      strictSsl: config.strictSsl,
     });
 
-    // Connect to Home Assistant WebSocket
+    // Connect to Home Assistant WebSocket. On failure the subscriber keeps
+    // retrying in the background; it is kept (not dropped) so events and owner
+    // questions start working as soon as Home Assistant is reachable.
     try {
       await eventSubscriber.connect();
       logger.info('Event subscriber connected to Home Assistant');
     } catch (error) {
-      logger.warn('Failed to connect event subscriber, SSE events will be unavailable', {
+      logger.warn('Home Assistant WebSocket not reachable yet; retrying in the background', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // Owner questions (askOwner & co.) listen for notification taps on the subscriber.
+  let ownerQuestions: OwnerQuestionService | undefined;
+  if (config.ownerQuestionsEnabled && eventSubscriber && client) {
+    const subscriber = eventSubscriber;
+    const service = new OwnerQuestionService({
+      notify: (target, serviceData) => client.callService({ domain: 'notify', service: target, service_data: serviceData }),
+      subscribe: (eventType, callback, onRejected) => subscriber.subscribeEventType(eventType, callback, onRejected),
+      secret: config.authSecret,
+      allowedUserIds: config.ownerQuestionsHaUsers,
+    });
+    try {
+      await service.start();
+      ownerQuestions = service;
+    } catch (error) {
+      logger.warn('Owner questions unavailable: could not subscribe to notification taps', {
         error: error instanceof Error ? error.message : String(error),
       });
-      eventSubscriber = null;
     }
   }
 
@@ -482,7 +505,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
         const existingState = sessionId ? sessions.get(sessionId) : undefined;
 
         const body = req.method !== 'GET' ? await parseBody(req) : undefined;
-        const streamOptions: StreamTransportOptions = { haClient: client, omadaClient, aiClient, config };
+        const streamOptions: StreamTransportOptions = { haClient: client, omadaClient, aiClient, config, ownerQuestions };
         const state = await handleStreamRequest(streamOptions, req, res, body, existingState);
 
         if (state && config.stateful && sessionId) {
@@ -562,6 +585,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     sessions.clear();
 
     // Close event subscriber
+    ownerQuestions?.stop();
     if (eventSubscriber) {
       eventSubscriber.disconnect();
     }

package/src/server/stream.ts

@@ -12,6 +12,7 @@ import type { LocalAIClient } from '../localAI/index.js';
 import type { OmadaClient } from '../omadaClient/index.js';
 import { logger } from '../utils/logger.js';
 import { createServer } from './common.js';
+import type { OwnerQuestionService } from '../ownerQuestions/service.js';
 import type { AuthenticatedRequest } from './auth.js';
 
 interface StreamTransportState {
@@ -27,6 +28,7 @@ export interface StreamTransportOptions {
   omadaClient?: OmadaClient;
   aiClient?: LocalAIClient;
   config: EnvironmentConfig;
+  ownerQuestions?: OwnerQuestionService;
 }
 
 export interface TransportSecurityOptions {
@@ -94,11 +96,12 @@ export function buildTransportSecurityOptions(config: EnvironmentConfig): Transp
  * This implements the MCP protocol version 2025-03-26
  */
 export function createStreamTransport(options: StreamTransportOptions, callerPermissions?: number): StreamTransportState {
-  const { haClient, omadaClient, aiClient, config } = options;
+  const { haClient, omadaClient, aiClient, config, ownerQuestions } = options;
   const mcpServer = createServer({
     haClient,
     omadaClient,
     aiClient,
+    ownerQuestions,
     restActions: config.restActions,
     toolRegistrationMode: config.toolRegistrationMode,
     // Hide tools this caller can never use from tools/list (RBAC still enforced per call).

package/src/tools/common.ts

@@ -6,6 +6,7 @@
 import type { CallToolResult, ServerContext } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { logger } from '../utils/logger.js';
+import { redactSecrets } from '../utils/redact.js';
 import { Permission, hasPermission, getPermissionNames } from '../permissions/index.js';
 
 // Re-export Permission for tool files
@@ -54,7 +55,10 @@ export function getCallerPermissions(extra: ToolExtra): number {
  * Convert any value to a CallToolResult
  */
 export function toToolResult(value: unknown, isError = false): CallToolResult {
-  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  // Every tool response passes here: secrets returned by Home Assistant or Omada
+  // (Wi-Fi password, RADIUS/VPN keys, access tokens) never reach the client.
+  const safe = redactSecrets(value);
+  const text = typeof safe === 'string' ? safe : JSON.stringify(safe, null, 2);
   return {
     content: text ? [{ type: 'text' as const, text }] : [],
     isError,
@@ -147,7 +151,10 @@ export function wrapToolHandler<T>(
       }, true);
     }
 
-    logger.info('Tool invoked', { tool: name, sessionId, args: safeSerialize(args) });
+    // Arguments can carry message text, entity names or MAC addresses: they are
+    // logged at debug level only, never in normal (info) operation.
+    logger.info('Tool invoked', { tool: name, sessionId });
+    logger.debug('Tool arguments', { tool: name, sessionId, args: safeSerialize(args) });
 
     try {
       const result = await handler(args, extra);

package/src/tools/homeassistant/askOwner.ts

@@ -0,0 +1,133 @@
+/**
+ * Owner question tools: askOwner / getOwnerAnswer / cancelOwnerQuestion.
+ * See src/ownerQuestions/service.ts for the design.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+
+import { LIMITS, type OwnerQuestionService } from '../../ownerQuestions/service.js';
+import { validatePlainText } from '../../utils/plainText.js';
+import { toToolResult, wrapToolHandler, Permission, type ToolExtra } from '../common.js';
+
+const plainText = (field: string, maxLength: number, allowNewlines = false) =>
+    z.string().transform((value, ctx) => {
+        try {
+            return validatePlainText(value, { field, maxLength, allowNewlines });
+        } catch (error) {
+            ctx.addIssue({ code: 'custom', message: error instanceof Error ? error.message : String(error) });
+            return z.NEVER;
+        }
+    });
+
+export const askOwnerSchema = z.object({
+    question: plainText('question', LIMITS.questionChars, true).describe(
+        `The question, plain text only (no emoji), at most ${LIMITS.questionChars} characters; longer text is refused, not cut`
+    ),
+    title: plainText('title', LIMITS.titleChars).optional().describe(`Notification title, at most ${LIMITS.titleChars} characters (default "Approval needed")`),
+    buttons: z
+        .array(plainText('button label', LIMITS.buttonChars))
+        .min(1)
+        .max(LIMITS.maxButtons)
+        .refine((labels) => new Set(labels.map((l) => l.toLowerCase())).size === labels.length, 'Button labels must be unique')
+        .optional()
+        .describe('1-3 button labels; default ["Approve", "Deny"]. The answer reports the tapped index (0 = first).'),
+    target: z
+        .string()
+        .regex(/^mobile_app_[a-z0-9_]{1,64}$/, 'target must be a mobile app notify service, e.g. "mobile_app_pixel_7"')
+        .describe('The phone to ask: its notify service name, e.g. "mobile_app_pixel_7"'),
+    timeoutSeconds: z
+        .number()
+        .int()
+        .min(LIMITS.minTimeoutSeconds)
+        .max(LIMITS.maxTimeoutSeconds)
+        .optional()
+        .describe(`How long the question stays open (default ${LIMITS.defaultTimeoutSeconds} s, max 7 days). No answer by then = timeout, treat as NO.`),
+    channel: plainText('channel', 40).optional().describe('Android notification channel name'),
+    importance: z.enum(['high', 'default', 'low', 'min']).optional().describe('Android notification channel importance'),
+});
+
+const requestIdSchema = z.string().min(1).max(4096).describe('The requestId returned by askOwner');
+
+export const getOwnerAnswerSchema = z.object({
+    requestId: requestIdSchema,
+    waitSeconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(LIMITS.maxWaitSeconds)
+        .optional()
+        .describe(`Wait up to this many seconds for an answer before returning "pending" (default 25, max ${LIMITS.maxWaitSeconds})`),
+});
+
+export const cancelOwnerQuestionSchema = z.object({ requestId: requestIdSchema });
+
+/** The token `sub` of the caller; stdio (local trust) has none. */
+function callerOf(extra: ToolExtra): string {
+    return extra.http?.authInfo?.clientId ?? 'local';
+}
+
+export function registerOwnerQuestionTools(server: McpServer, service: OwnerQuestionService): number {
+    server.registerTool(
+        'askOwner',
+        {
+            description:
+                "Ask the owner a question on their phone with up to 3 buttons (default Approve / Deny) and return immediately with a requestId. " +
+                'Then call getOwnerAnswer(requestId) until the status is not "pending". ' +
+                'Anything except an explicit approving answer must be treated as NO: deny, timeout, cancelled and unknown. ' +
+                'The owner may be away from the phone for hours; use a timeout that fits.',
+            inputSchema: askOwnerSchema,
+        },
+        wrapToolHandler(
+            'askOwner',
+            async (args: z.infer<typeof askOwnerSchema>, extra: ToolExtra) =>
+                toToolResult(
+                    await service.ask(
+                        {
+                            question: args.question,
+                            title: args.title ?? 'Approval needed',
+                            buttons: args.buttons ?? ['Approve', 'Deny'],
+                            target: args.target,
+                            timeoutSeconds: args.timeoutSeconds ?? LIMITS.defaultTimeoutSeconds,
+                            channel: args.channel,
+                            importance: args.importance,
+                        },
+                        callerOf(extra)
+                    )
+                ),
+            Permission.NOTIFY
+        )
+    );
+
+    server.registerTool(
+        'getOwnerAnswer',
+        {
+            description:
+                'Get the answer to an askOwner question, waiting up to waitSeconds. Status: "answered" (with index, button, answeredAt, answeredBy), ' +
+                '"pending" (ask again), "timeout", "cancelled" or "unknown". Only the client that asked can read the answer.',
+            inputSchema: getOwnerAnswerSchema,
+        },
+        wrapToolHandler(
+            'getOwnerAnswer',
+            async (args: z.infer<typeof getOwnerAnswerSchema>, extra: ToolExtra) =>
+                toToolResult(await service.getAnswer(args.requestId, callerOf(extra), args.waitSeconds ?? 25)),
+            Permission.NOTIFY
+        )
+    );
+
+    server.registerTool(
+        'cancelOwnerQuestion',
+        {
+            description: 'Withdraw an open askOwner question; the phone notification changes to "Cancelled". Returns the final status.',
+            inputSchema: cancelOwnerQuestionSchema,
+        },
+        wrapToolHandler(
+            'cancelOwnerQuestion',
+            async (args: z.infer<typeof cancelOwnerQuestionSchema>, extra: ToolExtra) =>
+                toToolResult(await service.cancel(args.requestId, callerOf(extra))),
+            Permission.NOTIFY
+        )
+    );
+
+    return 3;
+}

package/src/tools/homeassistant/getAutomationTrace.ts

@@ -3,22 +3,28 @@
  */
 
 import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
 import type { HaClient } from '../../haClient/index.js';
 import { entityIdSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
-import type { z } from 'zod';
 
-type EntityIdArgs = z.infer<typeof entityIdSchema>;
+export const getAutomationTraceSchema = entityIdSchema.extend({
+  limit: z.number().int().min(1).max(20).optional().describe('How many of the most recent runs to return (default 5, max 20)'),
+});
+
+type GetAutomationTraceArgs = z.infer<typeof getAutomationTraceSchema>;
 
 export function registerGetAutomationTraceTool(server: McpServer, client: HaClient): void {
   server.registerTool(
     'getAutomationTrace',
     {
-      description: 'Get the execution trace (history) of an automation. Shows when it was triggered and what actions were executed.',
-      inputSchema: entityIdSchema,
+      description:
+        'Get the most recent runs of an automation, newest first: when it ran, what triggered it, how it ended (state, last step, error). ' +
+        'Only automations with an id (created in the UI, or YAML with an id) have traces.',
+      inputSchema: getAutomationTraceSchema,
     },
-    wrapToolHandler('getAutomationTrace', async ({ entity_id }: EntityIdArgs) => {
-      const trace = await client.getAutomationTrace(entity_id);
-      return toToolResult({ entity_id, trace_count: Array.isArray(trace) ? trace.length : 0, traces: trace });
+    wrapToolHandler('getAutomationTrace', async ({ entity_id, limit }: GetAutomationTraceArgs) => {
+      const traces = await client.getAutomationTrace(entity_id, limit);
+      return toToolResult({ entity_id, trace_count: traces.length, traces });
     }, Permission.QUERY)
   );
 }

package/src/tools/index.ts

@@ -13,6 +13,8 @@ import { registerHomeAssistantTools } from './homeassistant/index.js';
 import { registerOmadaTools, type OmadaRegistrationMode } from './omada/index.js';
 import { registerAITools } from './ai/index.js';
 import { registerInfraTools, type RestAction } from './infra/index.js';
+import { registerOwnerQuestionTools } from './homeassistant/askOwner.js';
+import type { OwnerQuestionService } from '../ownerQuestions/service.js';
 
 export interface RegisterToolsOptions {
   server: McpServer;
@@ -23,13 +25,15 @@ export interface RegisterToolsOptions {
   restActions?: Record<string, RestAction>;
   /** Tool registration strategy for the Omada plugin (default 'eager'). */
   toolRegistrationMode?: OmadaRegistrationMode;
+  /** Owner questions (askOwner & co.); registered only when the service is running. */
+  ownerQuestions?: OwnerQuestionService;
 }
 
 /**
  * Register all available tools based on configured clients
  */
 export function registerAllTools(options: RegisterToolsOptions): void {
-  const { server, haClient, omadaClient, aiClient, restActions, toolRegistrationMode } = options;
+  const { server, haClient, omadaClient, aiClient, restActions, toolRegistrationMode, ownerQuestions } = options;
   logger.debug('Registering all tools');
 
   let totalTools = 0;
@@ -38,6 +42,9 @@ export function registerAllTools(options: RegisterToolsOptions): void {
   if (haClient) {
     const haToolCount = registerHomeAssistantTools(server, haClient);
     totalTools += haToolCount;
+    if (ownerQuestions) {
+      totalTools += registerOwnerQuestionTools(server, ownerQuestions);
+    }
   }
 
   // Omada tools (if client provided)

package/src/tools/omada/blockClient.ts

@@ -15,7 +15,9 @@ export function registerBlockClientTool(server: McpServer, client: OmadaClient):
         {
             description:
                 'Block a client from the network by MAC address. The client is denied all network access until unblocked. ' +
-                'Use omada_listClients first to find the exact MAC. This affects real network connectivity - confirm with the user before applying.',
+                'Use omada_listClients first to find the exact MAC. This affects real network connectivity - confirm with the user before applying. ' +
+                "Caution: a blocked device cannot reconnect, and once the controller stops treating it as current, Omada's API can no longer unblock it. " +
+                'For recurring schedules (e.g. a curfew) prefer an Omada time-range access rule on the controller over daily block/unblock calls.',
             inputSchema: inputSchema,
         },
         wrapToolHandler('omada_blockClient', async ({ clientMac, siteId }) =>

package/src/tools/omada/deleteClient.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+
+import type { OmadaClient } from '../../omadaClient/index.js';
+import { toToolResult, wrapToolHandler, Permission } from '../common.js';
+
+export function registerDeleteClientTool(server: McpServer, client: OmadaClient): void {
+    const inputSchema = z.object({
+        clientMac: z.string().min(1, 'clientMac (MAC address) is required'),
+        siteId: z.string().min(1).optional(),
+    });
+
+    server.registerTool(
+        'omada_deleteClient',
+        {
+            description:
+                "Delete the controller's record of a client by MAC: its name, history and block state. " +
+                'Use it to clear a block that omada_unblockClient can no longer reach (the device stays refused by the access points although Omada lists nothing). ' +
+                'The device is treated as new when it reconnects. Irreversible for that history - confirm with the user before applying.',
+            inputSchema,
+        },
+        wrapToolHandler('omada_deleteClient', async ({ clientMac, siteId }: z.infer<typeof inputSchema>) =>
+            toToolResult(await client.deleteClient(clientMac, siteId)),
+            Permission.CONFIGURE
+        )
+    );
+}

package/src/tools/omada/index.ts

@@ -7,6 +7,8 @@ import type { OmadaClient } from '../../omadaClient/index.js';
 import { logger } from '../../utils/logger.js';
 
 import { registerBlockClientTool } from './blockClient.js';
+import { registerDeleteClientTool } from './deleteClient.js';
+import { registerListBlockedClientsTool } from './listBlockedClients.js';
 import { registerCyclePoePortTool } from './cyclePoePort.js';
 import { registerOmadaGraphTools } from './graph.js';
 import { registerSetSiteNtpServersTool } from './setSiteNtpServers.js';
@@ -91,7 +93,9 @@ export function registerOmadaTools(
   // Client block tools
   registerBlockClientTool(server, client);
   registerUnblockClientTool(server, client);
-  toolCount += 2;
+  registerListBlockedClientsTool(server, client);
+  registerDeleteClientTool(server, client);
+  toolCount += 4;
 
   // Device action tools
   registerCyclePoePortTool(server, client);
@@ -138,10 +142,11 @@ function registerOmadaToolsGraph(server: McpServer, client: OmadaClient): number
   registerDisableClientRateLimitTool(server, client);
   registerBlockClientTool(server, client);
   registerUnblockClientTool(server, client);
+  registerDeleteClientTool(server, client);
   registerCyclePoePortTool(server, client);
   registerSetSsidEnabledTool(server, client);
   registerSetSiteNtpServersTool(server, client);
-  toolCount += 8;
+  toolCount += 9;
 
   logger.info('Omada tools registered', { mode: 'graph', toolCount });
   return toolCount;

package/src/tools/omada/listBlockedClients.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+
+import type { OmadaClient } from '../../omadaClient/index.js';
+import { siteInputSchema, toToolResult, wrapToolHandler, Permission } from '../common.js';
+
+export function registerListBlockedClientsTool(server: McpServer, client: OmadaClient): void {
+    server.registerTool(
+        'omada_listBlockedClients',
+        {
+            description:
+                'List clients that are currently blocked, including offline ones (from the known-clients list). ' +
+                'Use it to check block state before or after omada_blockClient / omada_unblockClient.',
+            inputSchema: siteInputSchema,
+        },
+        wrapToolHandler('omada_listBlockedClients', async ({ siteId }) => toToolResult(await client.listBlockedClients(siteId)), Permission.QUERY)
+    );
+}

package/src/tools/omada/namespace.ts

@@ -291,6 +291,25 @@ export const OMADA_RESOURCES: ResourceNode[] = [
     description: 'Most active clients by traffic.',
     fetch: (c, a) => c.listMostActiveClients(a.siteId),
   },
+  {
+    path: '/clients/known',
+    kind: 'collection',
+    permission: Q,
+    paginated: true,
+    defaultPageSize: 50,
+    estimatedSize: 'medium',
+    description:
+      'Clients the controller remembers, online and offline, with their block state (paginated; use page/pageSize). ' +
+      'Blocked clients have block=true; the controller cannot filter by it, so check every page.',
+    fetch: (c, a) =>
+      c.readResource({
+        pathTemplate: '/sites/{siteId}/insight/clients',
+        siteId: a.siteId,
+        paginated: true,
+        page: a.page,
+        pageSize: a.pageSize,
+      }),
+  },
   {
     path: '/clients/activity',
     kind: 'collection',

package/src/utils/plainText.ts

@@ -0,0 +1,48 @@
+/**
+ * Plain-text validation for user-visible strings we put on the owner's phone.
+ *
+ * Text is NFC-normalized first (so composed letters such as Romanian ș/ț/ă count
+ * as one character), then every character must be a letter, digit, punctuation,
+ * a math/currency/modifier symbol, the degree sign, or a plain space; line
+ * breaks only where allowed. Everything else is refused, never stripped:
+ * emoji and pictographs, control and invisible format characters (zero-width
+ * joiners, bidi overrides that make text display differently than it reads),
+ * variation selectors and leftover combining marks ("zalgo"), private-use and
+ * lone surrogates.
+ */
+
+const ALLOWED_CHAR = /^[\p{L}\p{N}\p{P}\p{Sm}\p{Sc}\p{Sk}° ]$/u;
+
+export interface PlainTextOptions {
+    field: string;
+    maxLength: number;
+    allowNewlines?: boolean;
+}
+
+/**
+ * @returns the NFC-normalized text
+ * @throws Error naming the field and the first offending character
+ */
+export function validatePlainText(text: string, options: PlainTextOptions): string {
+    const normalized = text.normalize('NFC');
+    const chars = [...normalized];
+    if (chars.length === 0 || normalized.trim() === '') {
+        throw new Error(`${options.field} must not be empty`);
+    }
+    if (chars.length > options.maxLength) {
+        throw new Error(`${options.field} is ${chars.length} characters; the maximum is ${options.maxLength}`);
+    }
+    for (const [index, char] of chars.entries()) {
+        if (char === '\n' && options.allowNewlines) {
+            continue;
+        }
+        if (!ALLOWED_CHAR.test(char)) {
+            const codePoint = char.codePointAt(0)!.toString(16).toUpperCase().padStart(4, '0');
+            throw new Error(
+                `${options.field} contains a disallowed character U+${codePoint} at position ${index + 1}; ` +
+                'only plain text is accepted (no emoji, control or invisible characters)'
+            );
+        }
+    }
+    return normalized;
+}

package/src/utils/redact.ts

@@ -0,0 +1,59 @@
+/**
+ * Redaction of secrets in tool responses.
+ *
+ * Home Assistant and Omada return secrets inside ordinary read results: the
+ * Wi-Fi password (Omada `pskSetting.securityKey`), RADIUS / CoA / SNMP secrets,
+ * PPSK and VPN keys, portal passwords, camera access tokens in image URLs. A tool
+ * response goes to an AI client and from there into transcripts, so every tool
+ * response is passed through `redactSecrets` (see toToolResult).
+ *
+ * Only non-empty string values under secret-looking names are replaced, with
+ * "<redacted>": an empty value stays empty (so "is a password set?" is still
+ * answerable), and booleans or numbers under similar names (`hidePwd`,
+ * `encryptionPsk`) are left alone. `token=` / `access_token=` query values inside
+ * URLs are masked as well. The input is never modified.
+ *
+ * Applied at the response boundary only, never inside the API clients: internal
+ * read-modify-write paths (SSID schedule, site NTP) must see real values.
+ */
+
+export const REDACTED = '<redacted>';
+
+/**
+ * Secret-looking field names, matched on the whole name or its ending
+ * (case-insensitive), from the Omada Open API and Home Assistant responses.
+ */
+const SECRET_NAME =
+  /(^key$|password|passwd|pwd$|secret|token$|passphrase|presharedkey|privatekey|securitykey|communitystring|^psk$|md5key|simplekey|authcode|devicekey)/i;
+
+/** Credentials inside URLs, e.g. /api/camera_proxy/camera.door?token=abc123 */
+const URL_SECRET = /([?&](?:access_token|token|key|password|secret)=)[^&#\s"]+/gi;
+
+export function isSecretName(name: string): boolean {
+  return SECRET_NAME.test(name);
+}
+
+export function redactSecrets<T>(value: T): T {
+  return redact(value, new WeakSet()) as T;
+}
+
+function redact(value: unknown, seen: WeakSet<object>): unknown {
+  if (typeof value === 'string') {
+    return value.includes('=') ? value.replace(URL_SECRET, `$1${REDACTED}`) : value;
+  }
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+  if (seen.has(value)) {
+    return '[circular]';
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((item) => redact(item, seen));
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = typeof field === 'string' && field !== '' && isSecretName(key) ? REDACTED : redact(field, seen);
+  }
+  return out;
+}

package/src/version.ts

@@ -2,4 +2,4 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export const VERSION = '2.1.1';
+export const VERSION = '2.2.1';

package/tests/config.test.ts

@@ -37,6 +37,18 @@ describe('loadConfig', () => {
     expect(config.stateful).toBe(false);
   });
 
+  it('parses owner question settings (enabled by default; HA users as a trimmed list)', () => {
+    const base = { HA_URL: 'http://homeassistant.10.0.0.19.nip.io:8123', HA_TOKEN: 't' };
+
+    const defaults = loadConfig(base);
+    expect(defaults.ownerQuestionsEnabled).toBe(true);
+    expect(defaults.ownerQuestionsHaUsers).toEqual([]);
+
+    const set = loadConfig({ ...base, MCP_OWNER_QUESTIONS_ENABLED: 'false', MCP_OWNER_QUESTIONS_HA_USERS: ' a1b2 , c3d4 ,' });
+    expect(set.ownerQuestionsEnabled).toBe(false);
+    expect(set.ownerQuestionsHaUsers).toEqual(['a1b2', 'c3d4']);
+  });
+
   it('should apply default values for optional fields', () => {
     const env = {
       HA_URL: 'http://homeassistant.10.0.0.19.nip.io:8123',

package/tests/haClient/automationTrace.test.ts

@@ -0,0 +1,59 @@
+/**
+ * getAutomationTrace goes over the WebSocket (`trace/list`), keyed by the
+ * automation's config id — there is no REST trace endpoint in Home Assistant.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { AutomationOperations } from '../../src/haClient/automations.js';
+import type { StateOperations } from '../../src/haClient/states.js';
+
+function setup(state: unknown, traces: unknown = []) {
+    const stateOps = { getState: vi.fn().mockResolvedValue(state) } as unknown as StateOperations;
+    const wsCommand = vi.fn().mockResolvedValue(traces);
+    const request = { get: vi.fn() };
+    const ops = new AutomationOperations(stateOps, undefined, request as never, wsCommand as never);
+    return { ops, wsCommand, request };
+}
+
+const automation = (attributes: Record<string, unknown>) => ({ entity_id: 'automation.relay', state: 'on', attributes });
+
+const run = (id: string, start: string) => ({ run_id: id, timestamp: { start, finish: start }, trigger: 'state of sensor.x' });
+
+describe('AutomationOperations.getAutomationTrace', () => {
+    it('lists traces by the automation id attribute, newest first, over the WebSocket only', async () => {
+        const { ops, wsCommand, request } = setup(automation({ id: '1700000000000' }), [
+            run('a', '2026-10-07T08:00:00Z'),
+            run('c', '2026-10-07T10:00:00Z'),
+            run('b', '2026-10-07T09:00:00Z'),
+        ]);
+
+        const traces = await ops.getAutomationTrace('automation.relay');
+
+        expect(wsCommand).toHaveBeenCalledWith({ type: 'trace/list', domain: 'automation', item_id: '1700000000000' });
+        expect(traces.map((t) => t.run_id)).toEqual(['c', 'b', 'a']);
+        expect(request.get).not.toHaveBeenCalled();
+    });
+
+    it('returns at most `limit` runs (default 5)', async () => {
+        const many = Array.from({ length: 8 }, (_, i) => run(String(i), `2026-10-07T0${i}:00:00Z`));
+        const { ops } = setup(automation({ id: 7 }), many);
+
+        expect(await ops.getAutomationTrace('automation.relay')).toHaveLength(5);
+        expect((await ops.getAutomationTrace('automation.relay', 2)).map((t) => t.run_id)).toEqual(['7', '6']);
+    });
+
+    it('explains that a YAML automation without an id has no traces', async () => {
+        const { ops, wsCommand } = setup(automation({ friendly_name: 'Relay' }));
+
+        await expect(ops.getAutomationTrace('automation.relay')).rejects.toThrow(/has no 'id'.*no traces/);
+        expect(wsCommand).not.toHaveBeenCalled();
+    });
+
+    it('reports an unknown automation', async () => {
+        const { ops, wsCommand } = setup(null);
+
+        await expect(ops.getAutomationTrace('automation.nope')).rejects.toThrow('Automation automation.nope not found');
+        expect(wsCommand).not.toHaveBeenCalled();
+    });
+});