rhombus-node-mcp 0.1.56 → 0.1.57

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,6 +31,7 @@ const TOOL_HANDLER = async (args, extra) => {
                 text: JSON.stringify(cameraRebootData),
             },
         ],
+        structuredContent: cameraRebootData,
     };
 };
 export function createTool(server) {
@@ -34,6 +39,16 @@ export function createTool(server) {
         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;

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);
+}