rhombus-node-mcp 0.1.55 → 0.1.57

package/dist/tools-console/policy-alerts-tool.js

@@ -3,35 +3,10 @@ import { ApiPayloadSchema, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/policy-ale
 import { extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "policy-alerts-tool";
 const TOOL_DESCRIPTION = `
-Retrieves Rhombus policy alerts. Policy alerts in the Rhombus system are generated based on user-defined alert
-policies configured in the Rhombus Console. These policies trigger alerts when specific events occur, such as:
-* AI & Computer Vision Events: Based on intelligent video analytics for motion, people, vehicles, facial recognition,
-  license plate recognition, or unusual behavior.
-* Device Status Changes: Like camera disconnections or sensor low battery.
-* Physical or Visual Tamper: Detection of physical movement of a device or obstruction of a camera's field of view.
-* Access Control Events: Such as unauthorized access attempts in restricted areas.
+Retrieves Rhombus policy alerts — alerts generated by user-defined alert policies when configured events occur: AI/computer-vision events (motion, people, vehicles, faces, license plates, unusual behavior), device status changes (disconnection, low battery), physical/visual tamper, and access-control events. Alerts are NOT the same as notifications (only some alerts notify, per user settings). Can also report which alert labels have been seen. Supports filtering by existing/expiring, time range, device UUIDs or location UUIDs — pagination and per-queryType requirements are documented on the parameters.
 
-Alerts are generated on triggers, but are NOT the same as notifications. Only certain alerts generate notifications based on user settings.
-
-Can inquire about labels that have been seen.
-
-Please note, this is not an exhaustive list, and there may be other types of triggers or events that generate
-policy alerts within the Rhombus system.
-
-This tool allows you to filter existing alerts by existing/expiring, a specific time range (before or after a timestamp in ISO 8601 format),
-by a list of device UUIDs, or by a list of location UUIDs.
-You can also specify the maximum number of results to return.
-The output is provided in JSON format.
-
-**Pagination**: Results are paginated and have a maximum page size. If the response includes a \`lastEvaluatedKey\` (for queryType "expiringSoon") or both \`lastTimestampISO\` and \`lastUuid\` (for queryTypes "existing" and "alert-groups"), more results are available. Pass these values back in the next call using the corresponding input parameters (lastEvaluatedKey, or lastTimestampISO and lastUuid) to retrieve the next page. Repeat until the response no longer includes these fields.
-
-IMPORTANT: The "unhealthy-devices" queryType returns historical alert notifications that were triggered for device health issues.
-It does NOT return live/real-time device connection status. If no device health alert policies are configured, or alerts were
-dismissed, this may return empty even when devices are offline.
-
-**To check which devices are currently online/offline, use the get-entity-tool instead.** The get-entity-tool returns the
-current state of all devices including their live connection status (the "connected" field). Request all entity types
-(CAMERA, DOORBELL_CAMERA, BADGE_READER, etc.) and check the "connected" field on each device to determine which are offline.`;
+IMPORTANT: queryType "unhealthy-devices" returns HISTORICAL device-health alert notifications, not live status — it can be empty while devices are offline. To check which devices are currently online/offline, use get-entity-tool instead (filterBy on its "connected" field).
+`;
 const TOOL_HANDLER = async (args, extra) => {
     const payload = ApiPayloadSchema.parse(args);
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
@@ -71,8 +46,11 @@ const TOOL_HANDLER = async (args, extra) => {
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
+        title: "Policy Alerts",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
+        // `dismiss` cannot be undone, which is what destructiveHint is for.
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }

package/dist/tools-console/reboot-cameras-tool.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { isConfirmed, requireConfirmation } from "../utils/confirmation.js";
 import { rebootCameras } from "../api/reboot-cameras-tool-api.js";
 import { TOOL_ARGS } from "../types/reboot-cameras-tool-types.js";
@@ -10,12 +11,15 @@ const TOOL_HANDLER = async (args, extra) => {
         return confirmation;
     }
     const cameraRebootData = await rebootCameras(cameraUuids, extra._meta?.requestModifiers, extra.sessionId);
-    if (!cameraRebootData) {
+    if (!cameraRebootData || ("error" in cameraRebootData && cameraRebootData.error)) {
         return {
+            isError: true,
             content: [
                 {
                     type: "text",
-                    text: "Failed to reboot cameras",
+                    text: cameraRebootData && "status" in cameraRebootData && cameraRebootData.status
+                        ? String(cameraRebootData.status)
+                        : "Failed to reboot cameras",
                 },
             ],
         };
@@ -27,8 +31,24 @@ const TOOL_HANDLER = async (args, extra) => {
                 text: JSON.stringify(cameraRebootData),
             },
         ],
+        structuredContent: cameraRebootData,
     };
 };
 export function createTool(server) {
-    server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_ARGS, TOOL_HANDLER);
+    server.registerTool(TOOL_NAME, {
+        title: "Reboot Cameras",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        // The confirmation-needed result goes through createToolTextContent,
+        // which sets isError: true — so it legitimately skips output validation.
+        outputSchema: {
+            status: z
+                .string()
+                .optional()
+                .describe("SUCCESS when every camera rebooted, PARTIAL_SUCCESS when some did, ERROR when none did"),
+            successCount: z.number().optional(),
+            errorCount: z.number().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, TOOL_HANDLER);
 }

package/dist/tools-console/report-tool.js

@@ -3,50 +3,20 @@ import { logger } from "../logger.js";
 import { OUTPUT_SCHEMA, RequestType, TOOL_ARGS, } from "../types/report-tool-types.js";
 import { extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "report-tool";
+// Tool descriptions are billed on EVERY LLM call even while the tool is
+// deferred behind hosted tool_search, so this string carries only what the
+// model needs to CHOOSE this tool. Per-requestType behaviour, call ordering,
+// and the people/occupancy strategy live on the requestType parameter
+// description (unbilled until the tool is loaded, still in front of the model
+// when it builds the call). See PERF_MASTER_PLAN P2 #4a.
 const TOOL_DESCRIPTION = `
-**Scope:** This tool returns **aggregated counts and time-series summaries** over specified intervals and scopes. Use **events-tool** when you need raw, event-level data (individual events with timestamps). Use this tool for high-level reports, analytics, and trends—especially over periods of a day or more.
+**Scope:** **aggregated counts and time-series summaries** over specified intervals and scopes (device, location, region, org). Use **events-tool** when you need raw, event-level data (individual events with timestamps). Use this tool for high-level reports, analytics, and trends—especially over periods of a day or more.
 
-**Interval guidance:** A shorter interval (HOURLY instead of DAILY) gives a better representation of data over time. Balance interval and range so you don't request too much data. For ranges spanning a week or so, HOURLY is appropriate.
-
----
-
-**People / occupancy counting strategy**
-
-When asked to count people on a camera or at a location, follow this strategy:
-1. **Always call GET_OCCUPANCY_ENABLED_CAMERAS first** to discover which cameras have occupancy counting enabled.
-2. If the target camera IS in the list, call **GET_OCCUPANCY_COUNT_REPORT** for that device. The response will automatically include a \`faceCountEnrichment\` field with the number of unique individuals identified by face recognition in the same time range. Present both data sources: occupancy estimate and unique face count.
-3. If the target camera is NOT in the list, **tell the user** that camera does not have occupancy counting enabled, and list the cameras that do. You can still call GET_SUMMARY_COUNT_REPORT with PEOPLE type — its response will also include \`faceCountEnrichment\` with unique face data as a fallback. If the PEOPLE count returns zero, the response will also include the list of occupancy-enabled cameras and a hint.
-4. When both occupancy data and face recognition data are available, **synthesize both** in your answer (e.g., "Occupancy estimates ~15 people. Face recognition identified 9 unique individuals during this period.").
-
-**PEOPLE type (in GET_SUMMARY_COUNT_REPORT):** Not a unique person count; it counts people-detection events. Requires people detection to be enabled on the camera. Use for high-level activity trends, not for deduplicated head counts.
-
----
+Covers: people counting and occupancy reports (enriched with unique-face counts), line-crossing / threshold ingress-egress counts, custom LLM event reports and their prompt configurations (e.g. "black dog sightings", "delivery truck arrivals", "parking availability %"), the org audit log of user and admin actions, device diagnostic feeds, and the most recent people-count readings for a device.
 
-**Summary and occupancy**
-- **GET_SUMMARY_COUNT_REPORT:** Aggregated counts (people, faces, motion, vehicles, etc.) over time at device, location, or org scope. Interval: minutely, hourly, daily, weekly, monthly, yearly. When called with PEOPLE type at DEVICE scope, the response is automatically enriched with face recognition data.
-- **GET_OCCUPANCY_ENABLED_CAMERAS:** List of cameras with occupancy reporting enabled. **Always call this first** before any people/occupancy counting request to verify camera support.
-- **GET_OCCUPANCY_COUNT_REPORT:** Occupancy count time series for a specific device over a time range. Response is automatically enriched with face recognition data. If the device does not support occupancy, the response will include a hint and the list of cameras that do.
+Pick one with "requestType". Each type's arguments, response enrichment, and required call ordering (some types must be called first to discover which cameras support a feature) are documented on the requestType parameter.
 
----
-
-**Line crossing**
-- **GET_LINE_CROSSING_ENABLED_CAMERAS:** Cameras at a location with line crossing enabled, plus their configs. Call first to see which cameras support threshold crossing reports.
-- **GET_THRESHOLD_CROSSING_COUNT_REPORT:** Ingress/egress counts for line crossings over time. Supports human and vehicle detection; bucket size: quarter hour, hour, day, week. Response includes computed metrics: average entries/exits per hour, hour with most entries/exits, busiest hour (with breakdown).
-
----
-
-**Custom LLM events**
-- **FIND_PROMPT_CONFIGURATIONS:** All custom event prompt configurations (e.g. "black dog sightings", "delivery truck arrivals", "parking availability %"). Each has prompt text, UUID, and promptType (COUNT, PERCENT, BOOLEAN). Call first to discover available custom events.
-- **GET_CUSTOM_LLM_REPORT:** **This is the PRIMARY way to get custom event reports.** Aggregated time-series for one custom event by prompt UUID. Automatically selects the correct API based on promptType: COUNT (numeric counts), PERCENT (percentages), BOOLEAN (true/false). Intervals: minutely, quarter-hourly, hourly, daily, weekly, monthly. **Always use this for custom event reports, trends, and analytics.** Use FIND_PROMPT_CONFIGURATIONS first to get the promptUuid and promptType.
-- **GET_CUSTOM_EVENTS_REPORT:** Raw individual event values only (not aggregated). Use only when you need per-event granularity, not for reports or trends.
-
----
-
-**Audit and diagnostics**
-- **GET_AUDIT_FEED:** Audit log of all user/admin actions in the org over a time range. Returns who did what and when (principalName, targetName, action, displayText).
-- **GET_DIAGNOSTIC_FEED:** Device diagnostic events over a time range.
-- **GET_THRESHOLD_CROSSING_EVENTS:** Individual line-crossing events (not aggregated counts).
-- **GET_PEOPLE_COUNT_EVENTS:** Most recent people count readings for specified devices.
+**Interval guidance:** A shorter interval (HOURLY instead of DAILY) gives a better representation of data over time. Balance interval and range so you don't request too much data. For ranges spanning a week or so, HOURLY is appropriate.
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { requestType } = args;
@@ -322,8 +292,10 @@ const TOOL_HANDLER = async (args, extra) => {
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
+        title: "Reports",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS.shape,
         outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: true },
     }, TOOL_HANDLER);
 }

package/dist/tools-console/rules-tool.js

@@ -69,8 +69,10 @@ const TOOL_HANDLER = async (args, _extra) => {
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
+        title: "Automation Rules",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }

package/dist/tools-console/schedule-tool.js

@@ -0,0 +1,190 @@
+import { createSchedule, deleteSchedule, findSchedules, getPoliciesUsingSchedule, updateSchedule, } from "../api/schedule-tool-api.js";
+import { INTERVALS_EXAMPLE, OUTPUT_SCHEMA, ScheduleToolRequestType, TOOL_ARGS, WEEKLY_REPEATING_STRATEGY, describeIntervals, parseWeeklyIntervals, } from "../types/schedule-tool-types.js";
+import { createToolStructuredContent, createToolTextContent, extractFromToolExtra, } from "../util.js";
+const TOOL_NAME = "schedule-tool";
+const TOOL_DESCRIPTION = `
+This tool manages Rhombus schedules — the named weekly time windows that policies attach to, e.g. "Business Hours" or "After Hours".
+
+Use it to resolve a schedule NAME to the scheduleUuid that other tools require. create-camera-policy-tool needs a scheduleUuid and has no other legitimate source for one, so start here rather than guessing a UUID.
+
+It has the following modes of operation, determined by the "requestType" parameter:
+- ${ScheduleToolRequestType.LIST}: List every schedule in the organization with its UUID, name and active windows.
+- ${ScheduleToolRequestType.GET}: Get one schedule by scheduleUuid.
+- ${ScheduleToolRequestType.CREATE}: Create a weekly schedule. Requires name and intervals, e.g. intervals=${INTERVALS_EXAMPLE}.
+- ${ScheduleToolRequestType.UPDATE}: Rename a schedule and/or replace its windows. Requires scheduleUuid plus name and/or intervals. Fields you omit are left unchanged; passing intervals REPLACES all existing windows.
+- ${ScheduleToolRequestType.DELETE}: Delete a schedule. Requires scheduleUuid. Refuses (without deleting) when policies still reference the schedule, and lists them — see confirmDeleteInUse.
+- ${ScheduleToolRequestType.GET_POLICIES_USING}: List the policies that reference a schedule. Requires scheduleUuid.
+
+Schedules are org-wide and shared: editing one changes the behaviour of every policy attached to it. Schedules reported with "mutable": false are system-managed and cannot be updated or deleted.
+`;
+/** Look a schedule up in the org list; the API has no get-one endpoint. */
+async function findScheduleByUuid(scheduleUuid, requestModifiers, sessionId) {
+    const { schedules } = await findSchedules(requestModifiers, sessionId);
+    return schedules.find(schedule => schedule.uuid === scheduleUuid);
+}
+const TOOL_HANDLER = async (args, extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(extra);
+    try {
+        switch (args.requestType) {
+            case ScheduleToolRequestType.LIST: {
+                const { schedules, warningMsg } = await findSchedules(requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    schedules,
+                    warningMsg,
+                    // A bare [] reads as "no schedules exist" indistinguishably from
+                    // "this org has none configured yet"; say which it is.
+                    note: schedules.length === 0
+                        ? "This organization has no schedules configured. A camera or door policy cannot be scheduled until one is created — offer to create one with requestType 'create'."
+                        : undefined,
+                });
+            }
+            case ScheduleToolRequestType.GET: {
+                if (!args.scheduleUuid) {
+                    return createToolTextContent("scheduleUuid is required for 'get'.");
+                }
+                const schedule = await findScheduleByUuid(args.scheduleUuid, requestModifiers, sessionId);
+                if (!schedule) {
+                    return createToolTextContent(`No schedule in this organization has the uuid "${args.scheduleUuid}". Use requestType 'list' to see the schedules that exist — do not guess a uuid.`);
+                }
+                return createToolStructuredContent({ schedule });
+            }
+            case ScheduleToolRequestType.CREATE: {
+                if (!args.name?.trim()) {
+                    return createToolTextContent("name is required for 'create'.");
+                }
+                if (!args.intervals) {
+                    return createToolTextContent(`intervals is required for 'create'. Example: ${INTERVALS_EXAMPLE}`);
+                }
+                const parsed = parseWeeklyIntervals(args.intervals);
+                if (!parsed.ok) {
+                    // Pre-mutation: nothing was created, so a corrected retry is safe.
+                    return createToolTextContent(`RETRYABLE — nothing was created. ${parsed.message}`);
+                }
+                const scheduleInput = {
+                    name: args.name.trim(),
+                    strategy: WEEKLY_REPEATING_STRATEGY,
+                    intervalList: parsed.value,
+                };
+                const { scheduleUuid, warningMsg } = await createSchedule(scheduleInput, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    created: { success: true, scheduleUuid },
+                    warningMsg,
+                    note: `Created "${args.name.trim()}" active ${describeIntervals(parsed.value)}.`,
+                });
+            }
+            case ScheduleToolRequestType.UPDATE: {
+                if (!args.scheduleUuid) {
+                    return createToolTextContent("scheduleUuid is required for 'update'.");
+                }
+                if (!args.name?.trim() && !args.intervals) {
+                    return createToolTextContent("'update' needs at least one of name or intervals — both were empty, so there is nothing to change.");
+                }
+                // api2's updateSchedule takes the WHOLE schedule, so sending only the
+                // changed field would blank the other one. Read first and merge.
+                const existing = await findScheduleByUuid(args.scheduleUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`No schedule in this organization has the uuid "${args.scheduleUuid}". Use requestType 'list' to see the schedules that exist.`);
+                }
+                if (existing.mutable === false) {
+                    return createToolTextContent(`Schedule "${existing.name ?? args.scheduleUuid}" is system-managed (mutable: false) and cannot be edited. Tell the user this schedule is read-only; creating a new schedule is the alternative.`);
+                }
+                let intervalList = existing.intervals
+                    ?.flatMap(interval => typeof interval.minuteOfWeekStart === "number" &&
+                    typeof interval.minuteOfWeekStop === "number"
+                    ? [
+                        {
+                            minuteOfWeekStart: interval.minuteOfWeekStart,
+                            minuteOfWeekStop: interval.minuteOfWeekStop,
+                        },
+                    ]
+                    : [])
+                    .slice();
+                let replacedWindows = false;
+                if (args.intervals) {
+                    const parsed = parseWeeklyIntervals(args.intervals);
+                    if (!parsed.ok) {
+                        return createToolTextContent(`RETRYABLE — nothing was changed. ${parsed.message}`);
+                    }
+                    intervalList = parsed.value;
+                    replacedWindows = true;
+                }
+                const { updated, warningMsg } = await updateSchedule({
+                    uuid: args.scheduleUuid,
+                    name: args.name?.trim() || existing.name,
+                    strategy: WEEKLY_REPEATING_STRATEGY,
+                    intervalList,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    updated,
+                    warningMsg,
+                    note: replacedWindows
+                        ? `Replaced all windows on "${args.name?.trim() || existing.name}" — it is now active ${describeIntervals(intervalList ?? [])}. Every policy using this schedule now follows the new windows.`
+                        : `Renamed to "${args.name?.trim()}". Its windows are unchanged.`,
+                });
+            }
+            case ScheduleToolRequestType.DELETE: {
+                if (!args.scheduleUuid) {
+                    return createToolTextContent("scheduleUuid is required for 'delete'.");
+                }
+                const existing = await findScheduleByUuid(args.scheduleUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`No schedule in this organization has the uuid "${args.scheduleUuid}". Use requestType 'list' to see the schedules that exist.`);
+                }
+                if (existing.mutable === false) {
+                    return createToolTextContent(`Schedule "${existing.name ?? args.scheduleUuid}" is system-managed (mutable: false) and cannot be deleted.`);
+                }
+                // Deleting a schedule silently rewires every policy attached to it, so
+                // check usage first and make the caller confirm.
+                const { usedBy } = await getPoliciesUsingSchedule(args.scheduleUuid, requestModifiers, sessionId);
+                if (usedBy.length > 0 && !args.confirmDeleteInUse) {
+                    return createToolStructuredContent({
+                        usedBy,
+                        note: `NOT DELETED — nothing was changed. "${existing.name ?? args.scheduleUuid}" is still used by ` +
+                            `${usedBy.length} ${usedBy.length === 1 ? "policy" : "policies"}: ` +
+                            `${usedBy.map(policy => `${policy.name ?? policy.uuid} (${policy.policyType})`).join(", ")}. ` +
+                            `Deleting it changes how those policies behave. Tell the user which policies are affected and ask them to ` +
+                            `confirm, then call this tool again with confirmDeleteInUse: true.`,
+                    });
+                }
+                const { deleted, warningMsg } = await deleteSchedule(args.scheduleUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleted,
+                    warningMsg,
+                    note: usedBy.length > 0
+                        ? `Deleted "${existing.name ?? args.scheduleUuid}", which was in use by ${usedBy.length} ${usedBy.length === 1 ? "policy" : "policies"}: ${usedBy.map(policy => policy.name ?? policy.uuid).join(", ")}. Those policies no longer have this schedule.`
+                        : `Deleted "${existing.name ?? args.scheduleUuid}". No policies referenced it.`,
+                });
+            }
+            case ScheduleToolRequestType.GET_POLICIES_USING: {
+                if (!args.scheduleUuid) {
+                    return createToolTextContent("scheduleUuid is required for 'get-policies-using'.");
+                }
+                const { usedBy, warningMsg } = await getPoliciesUsingSchedule(args.scheduleUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    usedBy,
+                    warningMsg,
+                    note: usedBy.length === 0
+                        ? "No policies reference this schedule, so it can be deleted or edited without affecting anything."
+                        : undefined,
+                });
+            }
+        }
+    }
+    catch (error) {
+        return createToolStructuredContent({
+            error: error instanceof Error ? error.message : "Unknown error",
+        });
+    }
+    return createToolStructuredContent({
+        error: `Invalid requestType. Valid values are: ${Object.values(ScheduleToolRequestType).join(", ")}.`,
+    });
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        title: "Schedules",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, TOOL_HANDLER);
+}

package/dist/tools-console/search-tool.js

@@ -62,8 +62,10 @@ const TOOL_HANDLER = async (args, _extra) => {
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
+        title: "Search",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: true },
     }, TOOL_HANDLER);
 }