@oneuptime/common 11.3.25 → 11.3.28

package/Server/Utils/AI/Toolbox/RecentChangesTools.ts

@@ -0,0 +1,208 @@
+import Monitor from "../../../../Models/DatabaseModels/Monitor";
+import MonitorStatusTimeline from "../../../../Models/DatabaseModels/MonitorStatusTimeline";
+import ScheduledMaintenance from "../../../../Models/DatabaseModels/ScheduledMaintenance";
+import TelemetryException from "../../../../Models/DatabaseModels/TelemetryException";
+import { JSONObject } from "../../../../Types/JSON";
+import Permission from "../../../../Types/Permission";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import MonitorStatusTimelineService from "../../../Services/MonitorStatusTimelineService";
+import ScheduledMaintenanceService from "../../../Services/ScheduledMaintenanceService";
+import TelemetryExceptionService from "../../../Services/TelemetryExceptionService";
+import QueryHelper from "../../../Types/Database/QueryHelper";
+import logger from "../../Logger";
+import ToolResultSerializer, { SerializedResult } from "./Serializer";
+import {
+  ObservabilityTool,
+  ToolArgs,
+  ToolContext,
+  ToolExecutionResult,
+  TimeRangeSchemaProperties,
+} from "./ToolTypes";
+
+/*
+ * Gate on Monitor read permissions. This is defense-in-depth only: every
+ * source query below runs under the requesting user's props, so a user who
+ * cannot see monitors / exceptions / maintenance simply gets no rows from that
+ * source — never another user's data. Resolved lazily to avoid the
+ * import-time circular-dependency TypeError other tools document.
+ */
+let cachedReadPermissions: Array<Permission> | null = null;
+const resolveReadPermissions: () => Array<Permission> =
+  (): Array<Permission> => {
+    if (!cachedReadPermissions) {
+      cachedReadPermissions = new Monitor().getReadPermissions();
+    }
+    return cachedReadPermissions;
+  };
+
+// One normalized entry in the merged "what changed" feed.
+interface ChangeEvent {
+  at: Date;
+  change: string;
+  detail: string;
+}
+
+export const RecentChangesTool: ObservabilityTool = {
+  name: "recent_changes",
+  description:
+    "Get a single chronological feed of what changed in a time window: newly-seen exceptions, monitor status changes (up/down), and scheduled maintenance overlapping the window. This is the highest-yield way to answer 'what changed right before this started?' during root-cause analysis — call it with the window around when a problem began.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ...TimeRangeSchemaProperties,
+      limitPerSource: {
+        type: "number",
+        description:
+          "Maximum items to pull from each source (exceptions, monitor changes, maintenance) before merging. Default 15, max 30.",
+      },
+    },
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveReadPermissions();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const timeRange: { startTime: Date; endTime: Date } = ToolArgs.getTimeRange(
+      args,
+      { defaultHours: 24, maxDays: 30 },
+    );
+    const startTime: Date = timeRange.startTime;
+    const endTime: Date = timeRange.endTime;
+
+    const limitPerSource: number = ToolArgs.getNumber(args, "limitPerSource", {
+      defaultValue: 15,
+      min: 1,
+      max: 30,
+    });
+
+    const events: Array<ChangeEvent> = [];
+
+    // 1) Newly-seen exceptions — their first occurrence falls inside the window.
+    try {
+      const exceptions: Array<TelemetryException> =
+        await TelemetryExceptionService.findBy({
+          query: {
+            firstSeenAt: QueryHelper.inBetween(startTime, endTime),
+          } as never,
+          select: {
+            message: true,
+            exceptionType: true,
+            firstSeenAt: true,
+            occuranceCount: true,
+          },
+          sort: { firstSeenAt: SortOrder.Descending },
+          limit: limitPerSource,
+          skip: 0,
+          props: ctx.props,
+        });
+
+      for (const exception of exceptions) {
+        if (!exception.firstSeenAt) {
+          continue;
+        }
+        events.push({
+          at: exception.firstSeenAt,
+          change: "new_exception",
+          detail: `${exception.exceptionType || "Exception"}: ${exception.message || ""} (x${exception.occuranceCount ?? 0})`,
+        });
+      }
+    } catch (error) {
+      logger.debug(`recent_changes: exceptions source skipped: ${error}`);
+    }
+
+    // 2) Monitor status changes (up/down) inside the window.
+    try {
+      const statusChanges: Array<MonitorStatusTimeline> =
+        await MonitorStatusTimelineService.findBy({
+          query: {
+            createdAt: QueryHelper.inBetween(startTime, endTime),
+          },
+          select: {
+            createdAt: true,
+            monitor: { name: true },
+            monitorStatus: { name: true },
+          },
+          sort: { createdAt: SortOrder.Descending },
+          limit: limitPerSource,
+          skip: 0,
+          props: ctx.props,
+        });
+
+      for (const statusChange of statusChanges) {
+        if (!statusChange.createdAt) {
+          continue;
+        }
+        events.push({
+          at: statusChange.createdAt,
+          change: "monitor_status_change",
+          detail: `${statusChange.monitor?.name || "Monitor"} → ${statusChange.monitorStatus?.name || "unknown"}`,
+        });
+      }
+    } catch (error) {
+      logger.debug(`recent_changes: monitor source skipped: ${error}`);
+    }
+
+    /*
+     * 3) Scheduled maintenance overlapping the window (started before it ended,
+     *    ends after it started).
+     */
+    try {
+      const maintenanceEvents: Array<ScheduledMaintenance> =
+        await ScheduledMaintenanceService.findBy({
+          query: {
+            startsAt: QueryHelper.lessThanEqualTo(endTime),
+            endsAt: QueryHelper.greaterThanEqualTo(startTime),
+          },
+          select: {
+            title: true,
+            startsAt: true,
+            endsAt: true,
+            currentScheduledMaintenanceState: { name: true },
+          },
+          sort: { startsAt: SortOrder.Descending },
+          limit: limitPerSource,
+          skip: 0,
+          props: ctx.props,
+        });
+
+      for (const maintenance of maintenanceEvents) {
+        if (!maintenance.startsAt) {
+          continue;
+        }
+        events.push({
+          at: maintenance.startsAt,
+          change: "scheduled_maintenance",
+          detail: `${maintenance.title || "Maintenance"} (${maintenance.currentScheduledMaintenanceState?.name || "scheduled"})`,
+        });
+      }
+    } catch (error) {
+      logger.debug(`recent_changes: maintenance source skipped: ${error}`);
+    }
+
+    // Merge into one chronological feed, most recent first.
+    events.sort((a: ChangeEvent, b: ChangeEvent) => {
+      return b.at.getTime() - a.at.getTime();
+    });
+
+    const rows: Array<JSONObject> = events.map((event: ChangeEvent) => {
+      return {
+        at: event.at,
+        change: event.change,
+        detail: event.detail,
+      };
+    });
+
+    const serialized: SerializedResult =
+      ToolResultSerializer.serializeRows(rows);
+
+    return {
+      dataForLlm: serialized.text,
+      rowCount: serialized.rowCount,
+      citationLabel: `Changes ${startTime.toISOString()} → ${endTime.toISOString()} (${serialized.rowCount} events)`,
+      redactionCount: serialized.redactionCount,
+      isTruncated: serialized.isTruncated,
+    };
+  },
+};

package/Server/Utils/AI/Toolbox/Serializer.ts

@@ -0,0 +1,299 @@
+import { JSONObject, JSONValue } from "../../../../Types/JSON";
+
+/*
+ * Prepares tool results for the LLM prompt: redacts likely secrets/PII,
+ * truncates long fields, and caps total payload size. Everything that enters
+ * the prompt (and therefore leaves for the LLM provider, and is previewed in
+ * LlmLog.requestPrompt) passes through here first.
+ */
+
+const MAX_ROWS: number = 50;
+const MAX_FIELD_LENGTH: number = 500;
+const MAX_PAYLOAD_BYTES: number = 16 * 1024;
+
+interface RedactionRule {
+  name: string;
+  regex: RegExp;
+  replacement: string;
+}
+
+/*
+ * These are security redactions, not the fingerprint-normalization regexes
+ * (those normalize numbers/uuids for grouping and do not cover credentials).
+ */
+const REDACTION_RULES: Array<RedactionRule> = [
+  {
+    name: "jwt",
+    regex: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/g,
+    replacement: "[redacted-jwt]",
+  },
+  {
+    name: "bearer",
+    regex: /Bearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,
+    replacement: "Bearer [redacted-token]",
+  },
+  {
+    /*
+     * PEM private key blocks (RSA/EC/OPENSSH/PGP…). Match the whole
+     * BEGIN…END block, including newlines, so no key material leaks.
+     */
+    name: "private-key",
+    regex:
+      /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY-----/g,
+    replacement: "[redacted-private-key]",
+  },
+  {
+    name: "aws-access-key-id",
+    regex: /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[0-9A-Z]{16}\b/g,
+    replacement: "[redacted-aws-key]",
+  },
+  {
+    name: "github-token",
+    regex:
+      /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{22,}\b/g,
+    replacement: "[redacted-github-token]",
+  },
+  {
+    name: "slack-token",
+    regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+    replacement: "[redacted-slack-token]",
+  },
+  {
+    name: "google-api-key",
+    regex: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    replacement: "[redacted-google-api-key]",
+  },
+  {
+    name: "email",
+    regex: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+    replacement: "[redacted-email]",
+  },
+  {
+    name: "ipv4",
+    regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    replacement: "[redacted-ip]",
+  },
+  {
+    /*
+     * Payment card numbers in the classic space/dash-separated grouping
+     * (e.g. "4111 1111 1111 1111"). Deliberately NOT matching bare 16-digit
+     * runs: an all-numeric 16-char OTel span id would collide with those and
+     * break the search_logs → get_trace pivot.
+     */
+    name: "credit-card",
+    regex: /\b\d{4}[ -]\d{4}[ -]\d{4}[ -]\d{4}\b/g,
+    replacement: "[redacted-card]",
+  },
+  {
+    /*
+     * Long hex blobs are usually secrets (SHA-256 digests, 40+ char API
+     * keys). But W3C/OTel trace IDs are exactly 32 hex chars and span IDs
+     * exactly 16 — redacting those would break the documented
+     * search_logs → get_trace pivot, since the model would never see the ID
+     * it needs to pass back. So only redact runs of 33+ hex chars, which
+     * preserves both ID lengths while still catching typical hash-length
+     * secrets. Labeled secrets of any length are still caught by
+     * key-value-secret below.
+     */
+    name: "hex-secret",
+    regex: /\b[0-9a-fA-F]{33,}\b/g,
+    replacement: "[redacted-hex]",
+  },
+  {
+    name: "key-value-secret",
+    regex:
+      /\b(password|passwd|secret|api[_-]?key|access[_-]?token|authorization)\b(\s*[:=]\s*)("[^"]{4,}"|'[^']{4,}'|[^\s,;&]{4,})/gi,
+    replacement: "$1$2[redacted]",
+  },
+];
+
+export interface SerializedResult {
+  text: string;
+  rowCount: number;
+  redactionCount: number;
+  isTruncated: boolean;
+  bytes: number;
+}
+
+export default class ToolResultSerializer {
+  // Single pass per rule: count and substitute ($1/$2 groups) together.
+  private static applyRedactionRule(
+    text: string,
+    rule: RedactionRule,
+  ): { text: string; count: number } {
+    let count: number = 0;
+
+    const result: string = text.replace(
+      rule.regex,
+      (...matchArgs: Array<unknown>): string => {
+        count++;
+        return rule.replacement.replace(
+          /\$(\d)/g,
+          (_full: string, groupIndex: string): string => {
+            return String(matchArgs[Number(groupIndex)] ?? "");
+          },
+        );
+      },
+    );
+
+    return { text: result, count };
+  }
+
+  public static redact(text: string): { text: string; count: number } {
+    let redacted: string = text;
+    let count: number = 0;
+
+    for (const rule of REDACTION_RULES) {
+      const applied: { text: string; count: number } = this.applyRedactionRule(
+        redacted,
+        rule,
+      );
+      redacted = applied.text;
+      count += applied.count;
+    }
+
+    return { text: redacted, count };
+  }
+
+  // Byte-accurate truncation (substring counts UTF-16 units, not bytes).
+  private static truncateToBytes(text: string, maxBytes: number): string {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes) {
+      return text;
+    }
+    return Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+  }
+
+  private static truncateField(value: string): {
+    value: string;
+    truncated: boolean;
+  } {
+    if (value.length <= MAX_FIELD_LENGTH) {
+      return { value, truncated: false };
+    }
+    return {
+      value: `${value.substring(0, MAX_FIELD_LENGTH)}… [truncated]`,
+      truncated: true,
+    };
+  }
+
+  private static serializeValue(value: JSONValue): string {
+    if (value === null || value === undefined) {
+      return "";
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  }
+
+  /*
+   * Serialize rows as a compact markdown-ish record list. Applies row cap,
+   * per-field truncation, redaction and total payload cap.
+   */
+  public static serializeRows(
+    rows: Array<JSONObject>,
+    totalRowCount?: number,
+  ): SerializedResult {
+    let isTruncated: boolean = false;
+    let redactionCount: number = 0;
+
+    let rowsToSerialize: Array<JSONObject> = rows;
+    if (rows.length > MAX_ROWS) {
+      rowsToSerialize = rows.slice(0, MAX_ROWS);
+      isTruncated = true;
+    }
+
+    const lines: Array<string> = [];
+
+    for (const row of rowsToSerialize) {
+      const parts: Array<string> = [];
+
+      for (const key of Object.keys(row)) {
+        const rawValue: string = this.serializeValue(row[key] as JSONValue);
+        if (!rawValue) {
+          continue;
+        }
+
+        const redacted: { text: string; count: number } = this.redact(rawValue);
+        redactionCount += redacted.count;
+
+        const truncated: { value: string; truncated: boolean } =
+          this.truncateField(redacted.text);
+        if (truncated.truncated) {
+          isTruncated = true;
+        }
+
+        parts.push(`${key}=${truncated.value}`);
+      }
+
+      lines.push(`- ${parts.join(" | ")}`);
+    }
+
+    let text: string = lines.join("\n");
+
+    if (Buffer.byteLength(text, "utf8") > MAX_PAYLOAD_BYTES) {
+      isTruncated = true;
+      while (
+        lines.length > 1 &&
+        Buffer.byteLength(lines.join("\n"), "utf8") > MAX_PAYLOAD_BYTES
+      ) {
+        lines.pop();
+      }
+      // A single oversized row can still exceed the cap — hard-slice it.
+      text = `${this.truncateToBytes(lines.join("\n"), MAX_PAYLOAD_BYTES)}\n… [payload truncated]`;
+    }
+
+    const rowCount: number = totalRowCount ?? rows.length;
+
+    if (rows.length === 0) {
+      text = "(no rows found)";
+    }
+
+    /*
+     * Tell the model when it is only seeing a slice. Without this marker a
+     * capped result looks complete, and the model reports partial data as if it
+     * were the whole picture.
+     */
+    if (rows.length > MAX_ROWS) {
+      text = `${text}\n… [showing the first ${MAX_ROWS} of ${rowCount} rows; narrow the query — a shorter time range or more filters — to see the rest]`;
+    }
+
+    return {
+      text,
+      rowCount,
+      redactionCount,
+      isTruncated,
+      bytes: Buffer.byteLength(text, "utf8"),
+    };
+  }
+
+  // Serialize free-form text (e.g. a rendered trace tree).
+  public static serializeText(
+    text: string,
+    rowCount: number,
+  ): SerializedResult {
+    const redacted: { text: string; count: number } = this.redact(text);
+    let output: string = redacted.text;
+    let isTruncated: boolean = false;
+
+    if (Buffer.byteLength(output, "utf8") > MAX_PAYLOAD_BYTES) {
+      output = `${this.truncateToBytes(output, MAX_PAYLOAD_BYTES)}… [payload truncated]`;
+      isTruncated = true;
+    }
+
+    if (!output) {
+      output = "(no data found)";
+    }
+
+    return {
+      text: output,
+      rowCount,
+      redactionCount: redacted.count,
+      isTruncated,
+      bytes: Buffer.byteLength(output, "utf8"),
+    };
+  }
+}