@oneuptime/common 11.3.25 → 11.3.26

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

@@ -0,0 +1,257 @@
+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]",
+  },
+  {
+    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]",
+  },
+  {
+    /*
+     * 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"),
+    };
+  }
+}

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

@@ -0,0 +1,249 @@
+import DatabaseCommonInteractionProps from "../../../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../Types/Date";
+import Permission from "../../../../Types/Permission";
+import {
+  AIChatCitationTarget,
+  AIChatWidget,
+} from "../../../../Types/AI/AIChatTypes";
+
+/*
+ * The execution context for a tool call. projectId is ALWAYS the tenant from
+ * the authenticated request props — it is never a tool argument, so the model
+ * cannot point a tool at another project.
+ */
+export interface ToolContext {
+  projectId: ObjectID;
+  props: DatabaseCommonInteractionProps;
+}
+
+export interface ToolExecutionResult {
+  // Serialized, truncated and redacted data that goes into the LLM prompt.
+  dataForLlm: string;
+  rowCount: number;
+  citationLabel: string;
+  citationTarget?: AIChatCitationTarget | undefined;
+  redactionCount: number;
+  isTruncated: boolean;
+  /*
+   * Optional structured widget (chart, table, trace waterfall, resource card)
+   * rendered inline in the chat. Built from the RAW rows the tool fetched — not
+   * the redacted LLM payload — because it is rendered back to the same user who
+   * already has RBAC access to this data.
+   */
+  widget?: AIChatWidget | undefined;
+}
+
+export interface ObservabilityTool {
+  name: string;
+  description: string;
+  // JSON Schema for the tool arguments, handed to the LLM.
+  inputSchema: JSONObject;
+  /*
+   * The user must hold at least one of these permissions for the tool to
+   * execute. For tools that call permission-checked services this is
+   * defense-in-depth; for tools that call raw-SQL aggregation services it is
+   * the authorization.
+   */
+  requiredPermissions: Array<Permission>;
+  /*
+   * True for tools that MUTATE project data (create/acknowledge/resolve, etc).
+   * These are gated by the conversation's permission mode: paused for approval
+   * in AskForApproval mode, run immediately in AutoRun, and not offered to the
+   * model at all in ReadOnly. Undefined/false = a read-only tool that always
+   * runs.
+   */
+  isMutation?: boolean | undefined;
+  /*
+   * Optional human-readable label for the approval card, derived from the
+   * (already validated) tool arguments — e.g. "Create incident: Checkout down".
+   * Falls back to the tool name when omitted.
+   */
+  buildActionTitle?: ((args: JSONObject) => string) | undefined;
+  execute(args: JSONObject, ctx: ToolContext): Promise<ToolExecutionResult>;
+}
+
+/*
+ * Defensive argument readers. Tool arguments come from the LLM and are
+ * untrusted: everything is type-checked, defaulted and clamped.
+ */
+export class ToolArgs {
+  public static getString(args: JSONObject, key: string): string | undefined {
+    const value: unknown = args[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+    return undefined;
+  }
+
+  public static getStringArray(
+    args: JSONObject,
+    key: string,
+  ): Array<string> | undefined {
+    const value: unknown = args[key];
+    if (Array.isArray(value)) {
+      const strings: Array<string> = value.filter((item: unknown) => {
+        return typeof item === "string" && item.trim().length > 0;
+      }) as Array<string>;
+      if (strings.length > 0) {
+        return strings;
+      }
+    }
+    return undefined;
+  }
+
+  public static getNumber(
+    args: JSONObject,
+    key: string,
+    options: { defaultValue: number; min: number; max: number },
+  ): number {
+    const value: unknown = args[key];
+    let parsed: number = options.defaultValue;
+
+    if (typeof value === "number" && Number.isFinite(value)) {
+      parsed = value;
+    } else if (typeof value === "string" && value.trim().length > 0) {
+      const fromString: number = Number(value);
+      if (Number.isFinite(fromString)) {
+        parsed = fromString;
+      }
+    }
+
+    return Math.min(options.max, Math.max(options.min, Math.floor(parsed)));
+  }
+
+  public static getBoolean(args: JSONObject, key: string): boolean | undefined {
+    const value: unknown = args[key];
+    if (typeof value === "boolean") {
+      return value;
+    }
+    if (value === "true") {
+      return true;
+    }
+    if (value === "false") {
+      return false;
+    }
+    return undefined;
+  }
+
+  public static getObjectID(
+    args: JSONObject,
+    key: string,
+  ): ObjectID | undefined {
+    const value: string | undefined = this.getString(args, key);
+    if (!value) {
+      return undefined;
+    }
+    return new ObjectID(value);
+  }
+
+  /*
+   * Combines the caller's optional serviceId filter with the user's owned-scope
+   * access (from ModelPermission.getAccessibleServiceIdsForAnalyticsModel) into
+   * the `serviceIds` filter to hand an aggregation service.
+   *
+   * `allowed === null` means the user has project-wide access: pass only the
+   * caller's own filter (or undefined for no filter). Otherwise the user is
+   * label/owned-restricted: intersect with any requested service and NEVER
+   * return undefined or an empty array — an empty result is forced to a
+   * no-match sentinel, because the aggregation services treat a missing/empty
+   * serviceIds as "no filter" (which would leak the whole project).
+   */
+  public static scopeServiceIds(
+    allowed: Array<ObjectID> | null,
+    requested: ObjectID | undefined,
+  ): Array<ObjectID> | undefined {
+    if (allowed === null) {
+      return requested ? [requested] : undefined;
+    }
+
+    let effective: Array<ObjectID> = allowed;
+    if (requested) {
+      effective = allowed.filter((id: ObjectID) => {
+        return id.toString() === requested.toString();
+      });
+    }
+
+    if (effective.length === 0) {
+      return [ObjectID.getZeroObjectID()];
+    }
+
+    return effective;
+  }
+
+  /*
+   * Time range for a tool call: explicit ISO startTime/endTime arguments,
+   * clamped to a maximum window, defaulting to the last hour.
+   */
+  public static getTimeRange(
+    args: JSONObject,
+    options?: { defaultHours?: number; maxDays?: number },
+  ): { startTime: Date; endTime: Date } {
+    const defaultHours: number = options?.defaultHours ?? 1;
+    const maxDays: number = options?.maxDays ?? 30;
+
+    const endTimeString: string | undefined = this.getString(args, "endTime");
+    const startTimeString: string | undefined = this.getString(
+      args,
+      "startTime",
+    );
+
+    /*
+     * Reject unparseable timestamps instead of silently falling back to the
+     * default window — a silent fallback answers a different question than the
+     * one asked. Throwing lets the model see the error and retry with a valid
+     * ISO 8601 value.
+     */
+    let endTime: Date = OneUptimeDate.getCurrentDate();
+    if (endTimeString) {
+      const parsed: Date = new Date(endTimeString);
+      if (isNaN(parsed.getTime())) {
+        throw new BadDataException(
+          `endTime "${endTimeString}" is not a valid ISO 8601 timestamp (e.g. 2024-01-31T14:00:00Z).`,
+        );
+      }
+      endTime = parsed;
+    }
+
+    let startTime: Date = OneUptimeDate.addRemoveHours(
+      endTime,
+      -1 * defaultHours,
+    );
+    if (startTimeString) {
+      const parsed: Date = new Date(startTimeString);
+      if (isNaN(parsed.getTime())) {
+        throw new BadDataException(
+          `startTime "${startTimeString}" is not a valid ISO 8601 timestamp (e.g. 2024-01-31T13:00:00Z).`,
+        );
+      }
+      startTime = parsed;
+    }
+
+    if (startTime.getTime() >= endTime.getTime()) {
+      throw new BadDataException("startTime must be before endTime.");
+    }
+
+    const maxWindowMs: number = maxDays * 24 * 60 * 60 * 1000;
+    if (endTime.getTime() - startTime.getTime() > maxWindowMs) {
+      startTime = new Date(endTime.getTime() - maxWindowMs);
+    }
+
+    return { startTime, endTime };
+  }
+}
+
+// Shared JSON-Schema fragments for tool input schemas.
+export const TimeRangeSchemaProperties: JSONObject = {
+  startTime: {
+    type: "string",
+    description:
+      "Start of the time range as an ISO 8601 timestamp. Defaults to one hour before endTime.",
+  },
+  endTime: {
+    type: "string",
+    description:
+      "End of the time range as an ISO 8601 timestamp. Defaults to now.",
+  },
+};