rhombus-node-mcp 0.1.50 → 0.1.51

package/dist/api/elements-access-anomaly-tool-api.js

@@ -0,0 +1,105 @@
+import { buildMediaHints } from "./badge-correlation.js";
+import { searchElementsEvents } from "./elements-tool-api.js";
+const ALL_RULES = [
+    "lost_or_inactive_badge",
+    "entry_not_made",
+    "off_hours",
+    "impossible_travel",
+    "area_novelty",
+];
+const DAY_MS = 86_400_000;
+/**
+ * Flags anomalous Honeywell Elements access events over a window: deterministic rules (lost/inactive badge,
+ * no-entry, off-hours, impossible travel, first-time-in-area vs a baseline) computed over searchElementsEvents,
+ * each finding carrying the still/clip hints to confirm it. The agent narrates/triages from here.
+ */
+export async function getElementsAccessAnomalies(args, timeZone, requestModifiers, sessionId) {
+    const rules = new Set(args.rules && args.rules.length ? args.rules : ALL_RULES);
+    const offStart = args.offHoursStartHour ?? 7;
+    const offEnd = args.offHoursEndHour ?? 19;
+    const maxTravelSec = args.impossibleTravelMaxSeconds ?? 30;
+    const baselineDays = args.baselineDays ?? 30;
+    const scope = { area: args.area, locationUuids: args.locationUuids, deviceUuids: args.deviceUuids };
+    const { events } = await searchElementsEvents({ ...scope, afterMs: args.afterMs, beforeMs: args.beforeMs, limit: args.limit ?? 500 }, timeZone, requestModifiers, sessionId);
+    // Baseline area-set per cardholder (for area_novelty).
+    const baselineAreas = new Map();
+    if (rules.has("area_novelty") && baselineDays > 0 && args.afterMs != null) {
+        const { events: baseEvents } = await searchElementsEvents({ ...scope, afterMs: args.afterMs - baselineDays * DAY_MS, beforeMs: args.afterMs, limit: 1000 }, timeZone, requestModifiers, sessionId);
+        for (const e of baseEvents) {
+            if (!e.cardholderName || !e.areaEntering)
+                continue;
+            const set = baselineAreas.get(e.cardholderName) ?? new Set();
+            set.add(e.areaEntering);
+            baselineAreas.set(e.cardholderName, set);
+        }
+    }
+    const hourFmt = new Intl.DateTimeFormat("en-US", { timeZone, hour: "2-digit", hourCycle: "h23" });
+    const localHour = (ms) => parseInt(hourFmt.format(new Date(ms)), 10);
+    const findings = [];
+    const seen = new Set();
+    const add = (e, rule, severity, rationale) => {
+        const key = `${e.cardholderName ?? ""}|${rule}|${e.timestampMs ?? ""}|${e.areaEntering ?? ""}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const { clipHint, stillHint } = buildMediaHints({ deviceUuid: e.deviceUuid, timestampMs: e.timestampMs });
+        findings.push({
+            cardholderName: e.cardholderName,
+            rule,
+            severity,
+            datetime: e.datetime,
+            timestampMs: e.timestampMs,
+            deviceUuid: e.deviceUuid,
+            area: e.areaEntering ?? e.areaExiting,
+            rationale,
+            clipHint,
+            stillHint,
+        });
+    };
+    for (const e of events) {
+        const at = e.areaEntering ? ` at "${e.areaEntering}"` : "";
+        if (rules.has("lost_or_inactive_badge") && e.badgeStatus && e.badgeStatus.toLowerCase() !== "active") {
+            add(e, "lost_or_inactive_badge", "high", `Badge status "${e.badgeStatus}" used${at}.`);
+        }
+        if (rules.has("entry_not_made") && e.entryMade === false) {
+            add(e, "entry_not_made", "medium", `Access granted but no entry made${at} — possible tailgating or aborted entry.`);
+        }
+        if (rules.has("off_hours") && e.timestampMs != null) {
+            const h = localHour(e.timestampMs);
+            if (h < offStart || h >= offEnd) {
+                add(e, "off_hours", "medium", `Entry ${e.datetime ?? `${h}:00`} is outside business hours (${offStart}:00–${offEnd}:00)${at}.`);
+            }
+        }
+        if (rules.has("area_novelty") && baselineAreas.size > 0 && e.cardholderName && e.areaEntering) {
+            const base = baselineAreas.get(e.cardholderName);
+            if (base && !base.has(e.areaEntering)) {
+                add(e, "area_novelty", "high", `First entry to "${e.areaEntering}" — not in ${e.cardholderName}'s prior ${baselineDays}-day pattern.`);
+            }
+        }
+    }
+    // Impossible travel: per cardholder, consecutive taps in different areas within the window.
+    if (rules.has("impossible_travel")) {
+        const byPerson = new Map();
+        for (const e of events) {
+            if (!e.cardholderName || e.timestampMs == null)
+                continue;
+            const arr = byPerson.get(e.cardholderName) ?? [];
+            arr.push(e);
+            byPerson.set(e.cardholderName, arr);
+        }
+        for (const [name, evs] of byPerson) {
+            const sorted = evs.slice().sort((a, b) => (a.timestampMs ?? 0) - (b.timestampMs ?? 0));
+            for (let i = 1; i < sorted.length; i++) {
+                const a = sorted[i - 1];
+                const b = sorted[i];
+                const gapSec = ((b.timestampMs ?? 0) - (a.timestampMs ?? 0)) / 1000;
+                if (a.areaEntering && b.areaEntering && a.areaEntering !== b.areaEntering && gapSec <= maxTravelSec) {
+                    add(b, "impossible_travel", "high", `${name} at "${a.areaEntering}" then "${b.areaEntering}" ${Math.round(gapSec)}s apart — physically implausible for one person.`);
+                }
+            }
+        }
+    }
+    const sev = (s) => (s === "high" ? 0 : 1);
+    findings.sort((a, b) => sev(a.severity) - sev(b.severity) || (b.timestampMs ?? 0) - (a.timestampMs ?? 0));
+    return { findings, eventsAnalyzed: events.length };
+}

package/dist/api/elements-badge-timeline-tool-api.js

@@ -0,0 +1,56 @@
+import { buildMediaHints } from "./badge-correlation.js";
+import { searchElementsEvents } from "./elements-tool-api.js";
+/**
+ * Reconstructs a single cardholder's movements as a chronological timeline of Honeywell Elements badge taps,
+ * each with the still/clip hints needed to show what happened. Pure orchestration over
+ * searchElementsEvents + the shared correlation helper.
+ */
+export async function getElementsBadgeTimeline(args, timeZone, requestModifiers, sessionId) {
+    const { events } = await searchElementsEvents({
+        cardholderQuery: args.cardholderQuery,
+        locationUuids: args.locationUuids,
+        afterMs: args.afterMs,
+        beforeMs: args.beforeMs,
+        limit: args.limit ?? 200,
+    }, timeZone, requestModifiers, sessionId);
+    // searchElementsEvents returns newest-first; a timeline reads chronologically.
+    const ordered = events
+        .filter((e) => e.timestampMs != null)
+        .sort((a, b) => (a.timestampMs ?? 0) - (b.timestampMs ?? 0));
+    const stops = ordered.map((e, i) => {
+        const next = ordered[i + 1];
+        const gapToNextSeconds = next?.timestampMs != null && e.timestampMs != null
+            ? Math.round((next.timestampMs - e.timestampMs) / 1000)
+            : undefined;
+        const { clipHint, stillHint } = buildMediaHints({ deviceUuid: e.deviceUuid, timestampMs: e.timestampMs }, args.clipPaddingSeconds);
+        return {
+            timestampMs: e.timestampMs,
+            datetime: e.datetime,
+            deviceUuid: e.deviceUuid,
+            area: e.areaEntering ?? e.areaExiting,
+            label: e.label,
+            isAnomaly: e.isAnomaly,
+            clipHint,
+            stillHint,
+            gapToNextSeconds,
+        };
+    });
+    // The sequence of areas traversed, collapsing consecutive repeats.
+    const path = [];
+    for (const stop of stops) {
+        if (stop.area && stop.area !== path[path.length - 1]) {
+            path.push(stop.area);
+        }
+    }
+    // cardholderQuery is full-text, so it can match more than one person — surface that so the agent
+    // can disambiguate rather than silently merge two people's movements.
+    const distinctCardholders = [
+        ...new Set(ordered.map((e) => e.cardholderName).filter((n) => !!n)),
+    ];
+    return {
+        cardholderName: distinctCardholders[0],
+        ambiguousCardholders: distinctCardholders.length > 1 ? distinctCardholders : undefined,
+        stops,
+        path,
+    };
+}

package/dist/api/elements-lost-badge-tool-api.js

@@ -0,0 +1,86 @@
+import { buildMediaHints } from "./badge-correlation.js";
+import { searchElementsEvents } from "./elements-tool-api.js";
+import { getFaceEvents, searchSimilarFaces } from "./faces-tool-api.js";
+/**
+ * Lost / stolen-badge live response for Honeywell Elements. Finds recent lost/inactive-badge use, and for
+ * each: the door clip/still, the face captured at the door (identified or UNIDENTIFIED), and a cross-camera
+ * track of that same face (via similar-face search) ordered to a last-known location. Detection + door
+ * evidence are exact; the track is best-effort (depends on face capture + recognition coverage).
+ */
+export async function getElementsLostBadgeResponse(args, timeZone, requestModifiers, sessionId) {
+    const scope = { area: args.area, locationUuids: args.locationUuids, deviceUuids: args.deviceUuids };
+    const { events } = await searchElementsEvents({ ...scope, anomalyOnly: true, afterMs: args.afterMs, beforeMs: args.beforeMs, limit: args.limit ?? 50 }, timeZone, requestModifiers, sessionId);
+    // anomalyOnly returns lost-badge AND no-entry anomalies; keep the lost/inactive-badge ones. Elements
+    // credentialStatus uses values like Lost/Stolen/Terminated — anything that isn't "active".
+    const lostEvents = events.filter((e) => e.badgeStatus && e.badgeStatus.toLowerCase() !== "active");
+    const winMs = (args.faceWindowSeconds ?? 30) * 1000;
+    const incidents = [];
+    for (const e of lostEvents) {
+        const { clipHint, stillHint } = buildMediaHints({ deviceUuid: e.deviceUuid, timestampMs: e.timestampMs });
+        let facesAtDoor = [];
+        let sightings = [];
+        if (e.deviceUuid && e.timestampMs != null) {
+            try {
+                // Face(s) at the door: query by time window (the faces tool can't filter by device), then match
+                // the door camera client-side.
+                const { faceEvents } = await getFaceEvents({
+                    pageRequest: { lastEvaluatedKey: null, maxPageSize: 75 },
+                    searchFilter: {
+                        faceNameContains: null,
+                        faceNames: [],
+                        hasEmbedding: null,
+                        hasName: null,
+                        labels: [],
+                        locationUuids: [],
+                        personUuids: [],
+                        timestampFilter: {
+                            rangeStart: new Date(e.timestampMs - winMs).toISOString(),
+                            rangeEnd: new Date(e.timestampMs + winMs).toISOString(),
+                        },
+                    },
+                }, timeZone, requestModifiers, sessionId);
+                facesAtDoor = faceEvents
+                    .filter((f) => f.deviceUuid === e.deviceUuid)
+                    .map((f) => ({
+                    faceName: f.faceName ?? undefined,
+                    personUuid: f.personUuid ?? undefined,
+                    thumbnailS3Key: f.thumbnailS3Key ?? undefined,
+                    faceEventUuid: f.uuid ?? undefined,
+                    eventTimestamp: f.eventTimestamp,
+                }));
+                // Track that face across cameras, ordered in time.
+                const seed = facesAtDoor.find((f) => f.faceEventUuid);
+                if (seed?.faceEventUuid) {
+                    const similar = await searchSimilarFaces(seed.faceEventUuid, timeZone, requestModifiers, sessionId);
+                    sightings = similar
+                        .map((s) => ({
+                        deviceUuid: s.deviceUuid,
+                        datetime: s.eventTimestamp,
+                        timestampMs: s.eventTimestampMs,
+                        similarity: s.similarity,
+                        personUuid: s.personUuid,
+                    }))
+                        .sort((a, b) => (a.timestampMs ?? 0) - (b.timestampMs ?? 0));
+                }
+            }
+            catch {
+                // Face enrichment is best-effort — never fail the whole response over it.
+            }
+        }
+        const last = sightings.length ? sightings[sightings.length - 1] : undefined;
+        incidents.push({
+            cardholderOfRecord: e.cardholderName,
+            badgeStatus: e.badgeStatus,
+            datetime: e.datetime,
+            timestampMs: e.timestampMs,
+            deviceUuid: e.deviceUuid,
+            area: e.areaEntering ?? e.areaExiting,
+            clipHint,
+            stillHint,
+            facesAtDoor,
+            sightings,
+            lastKnownSighting: last ? { deviceUuid: last.deviceUuid, datetime: last.datetime } : undefined,
+        });
+    }
+    return { incidents, count: incidents.length };
+}

package/dist/api/elements-tool-api.js

@@ -0,0 +1,64 @@
+import { postApi } from "../network/network.js";
+import { formatTimestamp } from "../util.js";
+/**
+ * Honeywell Elements (LenelS2 Elements) activity enum values. Passing these as `activityTypes` to the
+ * generalized access-control event search scopes results to Elements events only — exactly mirroring the
+ * OnGuard search, which is implicitly scoped to ONGUARD_* types server-side.
+ */
+export const ELEMENTS_ACTIVITY_TYPES = [
+    "ELEMENTS_BADGE_AUTHORIZED",
+    "ELEMENTS_BADGE_ANOMALY",
+    "ELEMENTS_NO_ENTRY_MADE",
+];
+/**
+ * Calls the generalized webservice access-control event search
+ * (POST /eventSearchV2/searchIntegrationAccessEvents) scoped to Honeywell Elements via `activityTypes`, and
+ * maps the raw seekpoints to the same agent-friendly shape as searchOnGuardEvents. The request DTO mirrors
+ * Eventsearch_SearchOnGuardEventsWSRequest plus an `activityTypes` array; the response shape is identical.
+ *
+ * The generalized endpoint, its `activityTypes` field, and the ELEMENTS_* enum values predate the generated
+ * public OpenAPI schema, so the body is built off the OnGuard request DTO and the extra field is added via a
+ * cast until `assets/openapi.json` is regenerated.
+ */
+export async function searchElementsEvents(args, timeZone, requestModifiers, sessionId) {
+    const body = {
+        deviceUuids: args.deviceUuids,
+        locationUuids: args.locationUuids,
+        afterMs: args.afterMs,
+        beforeMs: args.beforeMs,
+        cardholderQuery: args.cardholderQuery,
+        badgeStatus: args.badgeStatus,
+        badgeType: args.badgeType,
+        area: args.area,
+        anomalyOnly: args.anomalyOnly,
+        entryMade: args.entryMade,
+        limit: args.limit ?? 200,
+        activityTypes: [...ELEMENTS_ACTIVITY_TYPES],
+    };
+    const res = await postApi({
+        route: "/eventSearchV2/searchIntegrationAccessEvents",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error) {
+        throw new Error(res.status ?? res.errorMsg ?? "Elements event search failed");
+    }
+    const events = (res.events ?? []).map((e) => ({
+        timestampMs: e.timestampMs ?? undefined,
+        datetime: e.timestampMs != null ? formatTimestamp(e.timestampMs, timeZone) : undefined,
+        deviceUuid: e.deviceUuid ?? undefined,
+        label: e.customDisplayName ?? e.objectType ?? undefined,
+        // Dedicated-event-types put the cardholder in its own `cardholderName` field (customDescription
+        // is null on those docs); keep customDescription as a legacy fallback. The generated schema
+        // predates the field, so read it through a cast until `assets/openapi.json` is regenerated.
+        cardholderName: e.cardholderName ?? e.customDescription ?? undefined,
+        badgeStatus: e.badgeStatus ?? undefined,
+        badgeType: e.badgeType ?? undefined,
+        areaEntering: e.areaEntering ?? undefined,
+        areaExiting: e.areaExiting ?? undefined,
+        entryMade: e.entryMade ?? undefined,
+        isAnomaly: e.alert ?? undefined,
+    }));
+    return { events };
+}

package/dist/api/onguard-tool-api.js

@@ -1,10 +1,23 @@
 import { postApi } from "../network/network.js";
 import { formatTimestamp } from "../util.js";
 /**
- * Calls the webservice OnGuard event search (POST /eventSearchV2/searchOnGuardEvents) and maps the
+ * Calls the unified integration access-event search (POST /eventSearchV2/searchIntegrationAccessEvents),
+ * scoped to OnGuard via `activityTypes`, and maps the
  * raw seekpoints to an agent-friendly shape. Typed against the generated public OpenAPI schema.
  */
+/**
+ * Honeywell OnGuard (Lenel) activity enum values. Passing these as `activityTypes` to the generalized
+ * integration access-event search scopes results to OnGuard events only.
+ */
+export const ONGUARD_ACTIVITY_TYPES = [
+    "ONGUARD_BADGE_AUTHORIZED",
+    "ONGUARD_BADGE_ANOMALY",
+    "ONGUARD_NO_ENTRY_MADE",
+];
 export async function searchOnGuardEvents(args, timeZone, requestModifiers, sessionId) {
+    // Unified third-party integration access-event search, scoped to OnGuard via `activityTypes`. The
+    // generalized endpoint + `activityTypes` predate the generated schema, so the extra field is added via
+    // a cast off the OnGuard request DTO until `assets/openapi.json` is regenerated.
     const body = {
         deviceUuids: args.deviceUuids,
         locationUuids: args.locationUuids,
@@ -17,9 +30,10 @@ export async function searchOnGuardEvents(args, timeZone, requestModifiers, sess
         anomalyOnly: args.anomalyOnly,
         entryMade: args.entryMade,
         limit: args.limit ?? 200,
+        activityTypes: [...ONGUARD_ACTIVITY_TYPES],
     };
     const res = await postApi({
-        route: "/eventSearchV2/searchOnGuardEvents",
+        route: "/eventSearchV2/searchIntegrationAccessEvents",
         body,
         modifiers: requestModifiers,
         sessionId,

package/dist/tools-console/elements-access-anomaly-tool.js

@@ -0,0 +1,53 @@
+import { getElementsAccessAnomalies } from "../api/elements-access-anomaly-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/elements-access-anomaly-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+const TOOL_NAME = "elements-access-anomaly-tool";
+const TOOL_DESCRIPTION = `
+Scans Honeywell Elements (LenelS2 Elements) access events over a time window and flags anomalous badge activity. Use for
+"find unusual badge activity", "anything suspicious in access this week", or proactive access review.
+
+Runs deterministic rules and returns ranked findings (high severity first):
+- lost_or_inactive_badge: a non-active badge (lost/suspended) was used
+- entry_not_made: access granted but no entry made (possible tailgating)
+- off_hours: entry outside business hours (configurable)
+- impossible_travel: one cardholder at two different areas seconds apart
+- area_novelty: a cardholder's first-ever entry to an area vs their prior history (needs a baseline window)
+
+Each finding includes cardholderName, the rule, severity, datetime, area, the camera deviceUuid, a plain-language
+rationale, and clip/still hints. Resolve relative times (e.g. "this week") to ISO 8601 first via the timestamp tool.
+
+This is a triage aid: present findings grouped by severity, and for the notable ones call the camera-tool
+(requestType "image", cameraUuid = finding.deviceUuid, timestamp = finding.timestampMs) and/or clips-tool
+("createClip" using finding.clipHint) — in PARALLEL — so a human can confirm. Don't assert wrongdoing; surface the
+evidence.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        const result = await getElementsAccessAnomalies({
+            area: args.area ?? undefined,
+            locationUuids: args.locationUuids ?? undefined,
+            deviceUuids: args.deviceUuids ?? undefined,
+            afterMs: args.startTime ? new Date(args.startTime).getTime() : undefined,
+            beforeMs: args.endTime ? new Date(args.endTime).getTime() : undefined,
+            rules: args.rules ?? undefined,
+            baselineDays: args.baselineDays ?? undefined,
+            offHoursStartHour: args.offHoursStartHour ?? undefined,
+            offHoursEndHour: args.offHoursEndHour ?? undefined,
+            impossibleTravelMaxSeconds: args.impossibleTravelMaxSeconds ?? undefined,
+            limit: args.limit ?? undefined,
+        }, args.timeZone ?? "UTC", requestModifiers, sessionId);
+        return createToolStructuredContent(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return createToolStructuredContent({ error: message });
+    }
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/tools-console/elements-badge-timeline-tool.js

@@ -0,0 +1,50 @@
+import { getElementsBadgeTimeline } from "../api/elements-badge-timeline-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/elements-badge-timeline-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+const TOOL_NAME = "elements-badge-timeline-tool";
+const TOOL_DESCRIPTION = `
+Reconstructs one person's movements through a building from their Honeywell Elements (LenelS2 Elements) badge taps.
+Use this for incident reconstruction / "follow the badge" requests, e.g. "reconstruct Eve's movements
+yesterday" or "where did this cardholder go".
+
+Returns the cardholder's badge taps in CHRONOLOGICAL order (oldest first), each with:
+- datetime / timestampMs and the area entered
+- deviceUuid: the camera at that door
+- clipHint (camera + start/end window) and stillHint (camera + timestamp)
+- gapToNextSeconds: time until the next tap (a large gap = unobserved movement between doors)
+plus a "path" array summarizing the areas traversed in order.
+
+Resolve relative times like "yesterday" to ISO 8601 first (use the timestamp tool), then pass
+startTime/endTime. cardholderQuery is a full-text name match; if "ambiguousCardholders" is returned the
+query matched more than one person — ask the user which one before trusting the timeline.
+
+IMPORTANT — to show the movement visually: for each stop (or the key transitions), call the camera-tool
+(requestType "image", cameraUuid = stop.deviceUuid, timestamp = stop.timestampMs) for a still you can see,
+and/or the clips-tool (requestType "createClip", using stop.clipHint) for video. Issue those per-stop
+media calls in PARALLEL, then present the timeline as a chronological narrative.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        const result = await getElementsBadgeTimeline({
+            cardholderQuery: args.cardholderQuery,
+            locationUuids: args.locationUuids ?? undefined,
+            afterMs: args.startTime ? new Date(args.startTime).getTime() : undefined,
+            beforeMs: args.endTime ? new Date(args.endTime).getTime() : undefined,
+            clipPaddingSeconds: args.clipPaddingSeconds ?? undefined,
+            limit: args.limit ?? undefined,
+        }, args.timeZone ?? "UTC", requestModifiers, sessionId);
+        return createToolStructuredContent(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return createToolStructuredContent({ error: message });
+    }
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/tools-console/elements-lost-badge-tool.js

@@ -0,0 +1,47 @@
+import { getElementsLostBadgeResponse } from "../api/elements-lost-badge-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/elements-lost-badge-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+const TOOL_NAME = "elements-lost-badge-tool";
+const TOOL_DESCRIPTION = `
+Lost / stolen-badge live response for Honeywell Elements (LenelS2 Elements) access. Use for "a lost badge was just used —
+who is it and where did they go?", or to review lost/inactive-badge use over a window.
+
+For each lost/inactive-badge use it returns:
+- cardholderOfRecord (who the badge belongs to — may NOT be who used it) and badgeStatus
+- the door deviceUuid + time, plus clipHint / stillHint for the door footage
+- facesAtDoor: the face(s) captured at the door at that moment — a recognized name, or UNIDENTIFIED (an unknown
+  face on a valid badge is the strongest stolen/shared-badge signal), with a thumbnail
+- sightings: that same face tracked across cameras, ordered in time, ending in lastKnownSighting (last-known location)
+
+Resolve relative times (e.g. "in the last hour") to ISO 8601 first via the timestamp tool.
+
+To present: show the door still/clip (camera-tool image / clips-tool createClip with the hints), the face at the
+door, and the cross-camera track to last-known location. Detection + door evidence are reliable; the face track
+depends on face-recognition coverage, so treat it as investigative, not proof.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        const result = await getElementsLostBadgeResponse({
+            area: args.area ?? undefined,
+            locationUuids: args.locationUuids ?? undefined,
+            deviceUuids: args.deviceUuids ?? undefined,
+            afterMs: args.startTime ? new Date(args.startTime).getTime() : undefined,
+            beforeMs: args.endTime ? new Date(args.endTime).getTime() : undefined,
+            faceWindowSeconds: args.faceWindowSeconds ?? undefined,
+            limit: args.limit ?? undefined,
+        }, args.timeZone ?? "UTC", requestModifiers, sessionId);
+        return createToolStructuredContent(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return createToolStructuredContent({ error: message });
+    }
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

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

@@ -0,0 +1,55 @@
+import { searchElementsEvents } from "../api/elements-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/elements-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+const TOOL_NAME = "elements-events-tool";
+const TOOL_DESCRIPTION = `
+Searches Honeywell Elements (LenelS2 Elements) badge / access-control events for the organization. Use this to answer
+"who entered WHERE and WHEN" questions, e.g. "who entered the back office yesterday".
+
+Each returned event includes:
+- cardholderName: the person's name
+- deviceUuid: the camera that saw the event
+- timestampMs / datetime: when it happened
+- label: e.g. "Elements: Badge Authorized" (a grant) or an anomaly label
+- badgeStatus, badgeType, areaEntering, areaExiting, entryMade, isAnomaly
+
+Filters (all optional): area, locationUuids, deviceUuids, cardholderQuery, badgeStatus, badgeType,
+anomalyOnly, entryMade, startTime, endTime, limit. Resolve relative times like "yesterday" to ISO 8601
+first (use the timestamp tool), then pass startTime/endTime.
+
+IMPORTANT — to show pictures and video of each person so the user can visually identify them: after this
+returns, for each event (or the most relevant ones) call the camera-tool (requestType "image",
+cameraUuid = the event's deviceUuid, timestamp = the event's time) to get a still you can see, and/or the
+clips-tool (requestType "createClip") with a short window around the timestamp for video. Issue those
+per-event media calls in PARALLEL.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        const result = await searchElementsEvents({
+            area: args.area ?? undefined,
+            locationUuids: args.locationUuids ?? undefined,
+            deviceUuids: args.deviceUuids ?? undefined,
+            cardholderQuery: args.cardholderQuery ?? undefined,
+            badgeStatus: args.badgeStatus ?? undefined,
+            badgeType: args.badgeType ?? undefined,
+            anomalyOnly: args.anomalyOnly ?? undefined,
+            entryMade: args.entryMade ?? undefined,
+            afterMs: args.startTime ? new Date(args.startTime).getTime() : undefined,
+            beforeMs: args.endTime ? new Date(args.endTime).getTime() : undefined,
+            limit: args.limit ?? undefined,
+        }, args.timeZone ?? "UTC", requestModifiers, sessionId);
+        return createToolStructuredContent(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return createToolStructuredContent({ error: message });
+    }
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/types/elements-access-anomaly-tool-types.js

@@ -0,0 +1,3 @@
+// Identical arg/output shapes to the OnGuard access-anomaly tool (same generalized backend), so reuse
+// the OnGuard Zod schemas verbatim. Re-exported to keep the elements-* module naming convention parallel.
+export { ANOMALY_RULES, TOOL_ARGS, AnomalyFindingSchema, OUTPUT_SCHEMA, } from "./access-anomaly-tool-types.js";

package/dist/types/elements-badge-timeline-tool-types.js

@@ -0,0 +1,3 @@
+// Identical arg/output shapes to the OnGuard badge-timeline tool (same generalized backend), so reuse
+// the OnGuard Zod schemas verbatim. Re-exported to keep the elements-* module naming convention parallel.
+export { TOOL_ARGS, BadgeTimelineStopSchema, OUTPUT_SCHEMA, } from "./badge-timeline-tool-types.js";

package/dist/types/elements-lost-badge-tool-types.js

@@ -0,0 +1,3 @@
+// Identical arg/output shapes to the OnGuard lost-badge tool (same generalized backend), so reuse the
+// OnGuard Zod schemas verbatim. Re-exported to keep the elements-* module naming convention parallel.
+export { TOOL_ARGS, LostBadgeIncidentSchema, OUTPUT_SCHEMA, } from "./lost-badge-tool-types.js";

package/dist/types/elements-tool-types.js

@@ -0,0 +1,4 @@
+// The Honeywell Elements event search exposes the exact same filters and result shape as OnGuard
+// (the backend uses one generalized DTO), so reuse the OnGuard Zod schemas verbatim rather than
+// duplicating them. Re-exported here to keep the elements-* module naming convention parallel.
+export { TOOL_ARGS, OnGuardEventSchema as ElementsEventSchema, OUTPUT_SCHEMA, } from "./onguard-tool-types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rhombus-node-mcp",
-  "version": "0.1.50",
+  "version": "0.1.51",
   "description": "MCP server for Rhombus API",
   "keywords": [
     "ai",