@oneuptime/common 11.5.4 → 11.5.5

package/Server/API/AIInsightAPI.ts

@@ -0,0 +1,220 @@
+import UserMiddleware from "../Middleware/UserAuthorization";
+import CommonAPI from "./CommonAPI";
+import Express, {
+  ExpressRequest,
+  ExpressResponse,
+  ExpressRouter,
+  NextFunction,
+} from "../Utils/Express";
+import Response from "../Utils/Response";
+import DatabaseCommonInteractionProps from "../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import ObjectID from "../../Types/ObjectID";
+import BadDataException from "../../Types/Exception/BadDataException";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+import { JSONArray, JSONObject } from "../../Types/JSON";
+import AIInsightStatus from "../../Types/AI/AIInsightStatus";
+import AIInsightHumanVerdict from "../../Types/AI/AIInsightHumanVerdict";
+import AIInsight from "../../Models/DatabaseModels/AIInsight";
+import AIRun from "../../Models/DatabaseModels/AIRun";
+import AIRunEvent from "../../Models/DatabaseModels/AIRunEvent";
+import BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import AIInsightService from "../Services/AIInsightService";
+
+const router: ExpressRouter = Express.getRouter();
+
+/*
+ * Human-action endpoints for the AI insights inbox. Insight rows are
+ * server-authored (empty create/update table permissions) — humans act on
+ * them only through these routes: a one-click Confirm / Dismiss verdict
+ * (the G11 precision measurement), Resolve, and the live triage panel
+ * read. Each route access-checks the insight under the USER's permissions
+ * first (project membership + the AIInsight read ACL), then the
+ * service performs the root read/write — the AIInvestigationAPI idiom.
+ */
+
+async function getLoggedInProps(
+  req: ExpressRequest,
+): Promise<DatabaseCommonInteractionProps> {
+  const props: DatabaseCommonInteractionProps =
+    await CommonAPI.getDatabaseCommonInteractionProps(req);
+
+  if (!props.userId) {
+    throw new NotAuthorizedException("A logged-in user session is required.");
+  }
+
+  return props;
+}
+
+/*
+ * Access check under the USER's permissions: the user props enforce project
+ * membership and the model's read ACL, so a null result means "does not
+ * exist or is not yours" — reported identically so the route never leaks
+ * whether an insight id exists in another project.
+ */
+async function findAccessibleInsight(
+  req: ExpressRequest,
+  props: DatabaseCommonInteractionProps,
+): Promise<AIInsight> {
+  const insightIdString: string | undefined = req.body["insightId"] as
+    | string
+    | undefined;
+
+  if (!insightIdString) {
+    throw new BadDataException("insightId is required.");
+  }
+
+  const insight: AIInsight | null = await AIInsightService.findOneById({
+    id: new ObjectID(insightIdString),
+    select: { _id: true },
+    props,
+  });
+
+  if (!insight || !insight.id) {
+    throw new BadDataException(
+      "AI insight not found (or you do not have access to it).",
+    );
+  }
+
+  return insight;
+}
+
+/*
+ * One-click human verdict (the G11 precision measurement — confirm/dismiss
+ * rates per insight type gate future automation). Overwriting an existing
+ * verdict is allowed: the latest verdict wins. Dismissed also closes the
+ * insight; Confirmed leaves its status untouched.
+ * Body: { insightId, verdict: "Confirmed" | "Dismissed" }.
+ * Response: { insightId, verdict }.
+ */
+router.post(
+  "/ai-insight/verdict",
+  UserMiddleware.getUserMiddleware,
+  async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const props: DatabaseCommonInteractionProps = await getLoggedInProps(req);
+
+      const verdict: string | undefined = req.body["verdict"] as
+        | string
+        | undefined;
+
+      if (
+        verdict !== AIInsightHumanVerdict.Confirmed &&
+        verdict !== AIInsightHumanVerdict.Dismissed
+      ) {
+        throw new BadDataException(
+          'verdict must be "Confirmed" or "Dismissed".',
+        );
+      }
+
+      const insight: AIInsight = await findAccessibleInsight(req, props);
+
+      const result: {
+        insightId: ObjectID;
+        verdict: AIInsightHumanVerdict;
+      } = await AIInsightService.applyHumanVerdict({
+        insightId: insight.id!,
+        verdict: verdict as AIInsightHumanVerdict,
+        byUserId: props.userId!,
+      });
+
+      Response.sendJsonObjectResponse(req, res, {
+        insightId: result.insightId.toString(),
+        verdict: result.verdict,
+      });
+      return;
+    } catch (err) {
+      next(err);
+      return;
+    }
+  },
+);
+
+/*
+ * Marks the insight handled. Resolving implies the finding was real: when
+ * no verdict was recorded yet, the service also stamps Confirmed.
+ * Body: { insightId }. Response: { insightId, status }.
+ */
+router.post(
+  "/ai-insight/resolve",
+  UserMiddleware.getUserMiddleware,
+  async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const props: DatabaseCommonInteractionProps = await getLoggedInProps(req);
+
+      const insight: AIInsight = await findAccessibleInsight(req, props);
+
+      const result: { insightId: ObjectID; status: AIInsightStatus } =
+        await AIInsightService.resolveInsight({
+          insightId: insight.id!,
+          byUserId: props.userId!,
+        });
+
+      Response.sendJsonObjectResponse(req, res, {
+        insightId: result.insightId.toString(),
+        status: result.status,
+      });
+      return;
+    } catch (err) {
+      next(err);
+      return;
+    }
+  },
+);
+
+/*
+ * Live triage panel data: the insight's triage AIRun + its ordered event
+ * trail (capped — see MAX_TRIAGE_RUN_EVENTS on the service). Triage runs
+ * are system-authored and hidden by the per-user pin on the generic AIRun
+ * CRUD, so after the access check the service reads them as root — the
+ * sendLatestInvestigation idiom. An insight without a triage run responds
+ * { run: null, events: [] }, not an error.
+ * Body: { insightId }. Response: { run, events }.
+ */
+router.post(
+  "/ai-insight/triage-run",
+  UserMiddleware.getUserMiddleware,
+  async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const props: DatabaseCommonInteractionProps = await getLoggedInProps(req);
+
+      const insight: AIInsight = await findAccessibleInsight(req, props);
+
+      const result: { run: AIRun | null; events: Array<AIRunEvent> } =
+        await AIInsightService.getLatestTriageRunWithEvents({
+          insightId: insight.id!,
+        });
+
+      const runJson: JSONObject | undefined = result.run
+        ? BaseModel.toJSONArray([result.run], AIRun)[0]
+        : undefined;
+
+      const eventsJson: JSONArray = BaseModel.toJSONArray(
+        result.events,
+        AIRunEvent,
+      );
+
+      Response.sendJsonObjectResponse(req, res, {
+        run: runJson || null,
+        events: eventsJson,
+      });
+      return;
+    } catch (err) {
+      next(err);
+      return;
+    }
+  },
+);
+
+export default router;

package/Server/API/AIInvestigationAPI.ts

@@ -15,22 +15,38 @@ import SortOrder from "../../Types/BaseDatabase/SortOrder";
 import Query from "../../Types/BaseDatabase/Query";
 import { JSONArray, JSONObject } from "../../Types/JSON";
 import AIRunType from "../../Types/AI/AIRunType";
+import AIRunHumanVerdict from "../../Types/AI/AIRunHumanVerdict";
 import AIRun from "../../Models/DatabaseModels/AIRun";
 import AIRunEvent from "../../Models/DatabaseModels/AIRunEvent";
 import Incident from "../../Models/DatabaseModels/Incident";
 import Alert from "../../Models/DatabaseModels/Alert";
+import Service from "../../Models/DatabaseModels/Service";
+import Span from "../../Models/AnalyticsModels/Span";
 import BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import IncidentService from "../Services/IncidentService";
 import AlertService from "../Services/AlertService";
 import AIRunService from "../Services/AIRunService";
 import AIRunEventService from "../Services/AIRunEventService";
+import ServiceService from "../Services/ServiceService";
+import SpanService from "../Services/SpanService";
+import FixFromIncidentTaskTrigger from "../Utils/AI/SRE/FixFromIncidentTaskTrigger";
+import FixPerformanceTaskTrigger from "../Utils/AI/SRE/FixPerformanceTaskTrigger";
+import { AnalyzableSpan } from "../Utils/AI/PerfEvidence/SpanTreeAnalyzer";
 
 const router: ExpressRouter = Express.getRouter();
 
+/*
+ * Upper bound on spans analyzed for one performance-fix trigger — mirrors
+ * the trace waterfall's own cap (TraceTools.MAX_TRACE_SPANS). Findings are
+ * computed over the first 500 spans by start time; a truncated giant trace
+ * still yields honest evidence about the loaded portion.
+ */
+const MAX_ANALYZED_TRACE_SPANS: number = 500;
+
 const MAX_EVENTS: number = 500;
 
 /*
- * Returns the latest Sentinel investigation (the AIRun + its ordered
+ * Returns the latest AI investigation (the AIRun + its ordered
  * AIRunEvents) for an incident or alert, so the dashboard can render a live
  * "watch it think" panel.
  *
@@ -75,6 +91,11 @@ async function sendLatestInvestigation(
       toolCallCount: true,
       totalTokens: true,
       createdAt: true,
+      // Measurement layer: the panel renders verdict/grade state from these.
+      humanVerdict: true,
+      humanVerdictAt: true,
+      autoGrade: true,
+      autoGradeAt: true,
     },
     sort: { createdAt: SortOrder.Descending },
     limit: 1,
@@ -213,4 +234,345 @@ router.post(
   },
 );
 
+/*
+ * Human verdict capture (Phase 2 measurement layer): one-click Confirm /
+ * Reject on the investigation panel. Applies to the LATEST COMPLETED
+ * investigation run for the subject; overwriting is allowed (a user may
+ * change their mind), and the request is rejected when no completed
+ * investigation exists. The subject is access-checked under the USER's
+ * permissions first (same idiom as the read routes above); the run itself is
+ * written as root because investigation runs are system-authored.
+ * Body: { subjectType: "incident" | "alert", subjectId,
+ * verdict: "Confirmed" | "Rejected" }. Response: { runId, verdict }.
+ */
+router.post(
+  "/ai-investigation/verdict",
+  UserMiddleware.getUserMiddleware,
+  async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const props: DatabaseCommonInteractionProps = await getLoggedInProps(req);
+
+      const subjectType: string | undefined = req.body["subjectType"] as
+        | string
+        | undefined;
+
+      if (subjectType !== "incident" && subjectType !== "alert") {
+        throw new BadDataException(
+          'subjectType must be "incident" or "alert".',
+        );
+      }
+
+      const subjectIdString: string | undefined = req.body["subjectId"] as
+        | string
+        | undefined;
+
+      if (!subjectIdString) {
+        throw new BadDataException("subjectId is required.");
+      }
+
+      const subjectId: ObjectID = new ObjectID(subjectIdString);
+
+      const verdict: string | undefined = req.body["verdict"] as
+        | string
+        | undefined;
+
+      if (
+        verdict !== AIRunHumanVerdict.Confirmed &&
+        verdict !== AIRunHumanVerdict.Rejected
+      ) {
+        throw new BadDataException(
+          'verdict must be "Confirmed" or "Rejected".',
+        );
+      }
+
+      // Access check under the USER's permissions (null when not allowed).
+      if (subjectType === "incident") {
+        const incident: Incident | null = await IncidentService.findOneById({
+          id: subjectId,
+          select: { _id: true },
+          props,
+        });
+
+        if (!incident) {
+          throw new BadDataException(
+            "Incident not found (or you do not have access to it).",
+          );
+        }
+      } else {
+        const alert: Alert | null = await AlertService.findOneById({
+          id: subjectId,
+          select: { _id: true },
+          props,
+        });
+
+        if (!alert) {
+          throw new BadDataException(
+            "Alert not found (or you do not have access to it).",
+          );
+        }
+      }
+
+      const result: { runId: ObjectID; verdict: AIRunHumanVerdict } =
+        await AIRunService.applyHumanVerdictToLatestInvestigation({
+          ...(subjectType === "incident"
+            ? { incidentId: subjectId }
+            : { alertId: subjectId }),
+          verdict: verdict as AIRunHumanVerdict,
+          verdictByUserId: props.userId!,
+        });
+
+      Response.sendJsonObjectResponse(req, res, {
+        runId: result.runId.toString(),
+        verdict: result.verdict,
+      });
+      return;
+    } catch (err) {
+      next(err);
+      return;
+    }
+  },
+);
+
+/*
+ * Human-triggered `code_fix` (the FixFromIncident recipe): after a AI
+ * investigation completes on an incident/alert, the user can ask the agent
+ * to open a fix pull request from the posted analysis. The subject is
+ * access-checked under the USER's permissions first (same idiom as the read
+ * routes above); the trigger's gates (completed investigation, GitHub-App
+ * repository, per-subject dedupe) fail early with a clear message.
+ * Body: { subjectType: "incident" | "alert", subjectId }. Response:
+ * { aiRunId } — the Queued CodeFix run the agent worker will claim.
+ */
+router.post(
+  "/ai-investigation/create-fix-task",
+  UserMiddleware.getUserMiddleware,
+  async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const props: DatabaseCommonInteractionProps = await getLoggedInProps(req);
+
+      const subjectType: string | undefined = req.body["subjectType"] as
+        | string
+        | undefined;
+
+      if (subjectType !== "incident" && subjectType !== "alert") {
+        throw new BadDataException(
+          'subjectType must be "incident" or "alert".',
+        );
+      }
+
+      const subjectIdString: string | undefined = req.body["subjectId"] as
+        | string
+        | undefined;
+
+      if (!subjectIdString) {
+        throw new BadDataException("subjectId is required.");
+      }
+
+      const subjectId: ObjectID = new ObjectID(subjectIdString);
+
+      // Access check under the USER's permissions (null when not allowed).
+      let projectId: ObjectID | undefined = undefined;
+
+      if (subjectType === "incident") {
+        const incident: Incident | null = await IncidentService.findOneById({
+          id: subjectId,
+          select: { _id: true, projectId: true },
+          props,
+        });
+
+        if (!incident || !incident.projectId) {
+          throw new BadDataException(
+            "Incident not found (or you do not have access to it).",
+          );
+        }
+
+        projectId = incident.projectId;
+      } else {
+        const alert: Alert | null = await AlertService.findOneById({
+          id: subjectId,
+          select: { _id: true, projectId: true },
+          props,
+        });
+
+        if (!alert || !alert.projectId) {
+          throw new BadDataException(
+            "Alert not found (or you do not have access to it).",
+          );
+        }
+
+        projectId = alert.projectId;
+      }
+
+      const run: AIRun =
+        await FixFromIncidentTaskTrigger.createFixTaskFromInvestigation({
+          projectId,
+          ...(subjectType === "incident"
+            ? { incidentId: subjectId }
+            : { alertId: subjectId }),
+          userId: props.userId!,
+        });
+
+      Response.sendJsonObjectResponse(req, res, {
+        aiRunId: run.id!.toString(),
+      });
+      return;
+    } catch (err) {
+      next(err);
+      return;
+    }
+  },
+);
+
+/*
+ * Human-triggered FixPerformance: from a slow trace, one click opens a
+ * performance-fix PR grounded in deterministic span-tree evidence. The
+ * spans are loaded under the USER's permissions (the same telemetry-read
+ * ACL the trace explorer enforces — a user who cannot read the trace gets
+ * "not found"), the SpanTreeAnalyzer gates on a mechanical finding, and
+ * the trigger's remaining gates (GitHub-App repository, per-trace dedupe)
+ * fail early with a clear message. Body: { traceId }. Response:
+ * { aiRunId } — the Queued CodeFix run the agent worker will claim.
+ */
+router.post(
+  "/ai-investigation/create-performance-fix-task",
+  UserMiddleware.getUserMiddleware,
+  async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ): Promise<void> => {
+    try {
+      const props: DatabaseCommonInteractionProps = await getLoggedInProps(req);
+
+      const traceId: string | undefined = req.body["traceId"] as
+        | string
+        | undefined;
+
+      if (!traceId) {
+        throw new BadDataException("traceId is required.");
+      }
+
+      const projectId: ObjectID | undefined = props.tenantId;
+
+      if (!projectId) {
+        throw new BadDataException("A project scope is required.");
+      }
+
+      /*
+       * Access check + data load in one: the analytics permission layer
+       * pins this query to the user's tenant and telemetry-read
+       * permissions (the Span model's read ACL — same enforcement the
+       * trace explorer's list API applies). No spans back means the trace
+       * does not exist or the user may not see it.
+       */
+      const spans: Array<Span> = await SpanService.findBy({
+        query: {
+          traceId: traceId,
+        } as never,
+        select: {
+          spanId: true,
+          parentSpanId: true,
+          name: true,
+          startTimeUnixNano: true,
+          endTimeUnixNano: true,
+          durationUnixNano: true,
+          attributes: true,
+          primaryEntityId: true,
+        } as never,
+        sort: {
+          startTimeUnixNano: SortOrder.Ascending,
+        } as never,
+        limit: MAX_ANALYZED_TRACE_SPANS,
+        skip: 0,
+        props: props,
+      });
+
+      if (spans.length === 0) {
+        throw new BadDataException(
+          "Trace not found (or you do not have access to it).",
+        );
+      }
+
+      // Nanoseconds -> milliseconds for the analyzer.
+      const analyzableSpans: Array<AnalyzableSpan> = spans.map(
+        (span: Span): AnalyzableSpan => {
+          const attributes: Record<string, string> = {};
+
+          for (const [key, value] of Object.entries(span.attributes || {})) {
+            if (value !== null && value !== undefined) {
+              attributes[key] = String(value);
+            }
+          }
+
+          return {
+            spanId: span.spanId?.toString() || "",
+            parentSpanId: span.parentSpanId?.toString() || undefined,
+            name: span.name || "",
+            startMs: Number(span.startTimeUnixNano) / 1_000_000,
+            endMs: Number(span.endTimeUnixNano) / 1_000_000,
+            durationMs: Number(span.durationUnixNano) / 1_000_000,
+            attributes,
+          };
+        },
+      );
+
+      /*
+       * Best-effort service attribution: the trace's most frequent
+       * primaryEntityId, resolved to a Service name when it IS a Service
+       * (findOneById returns null for hosts/clusters/unattributed ids).
+       * Only feeds the repository name-match fallback — null is fine.
+       */
+      const entityIdCounts: Map<string, number> = new Map();
+      for (const span of spans) {
+        const entityId: string | undefined = span.primaryEntityId?.toString();
+        if (entityId) {
+          entityIdCounts.set(entityId, (entityIdCounts.get(entityId) || 0) + 1);
+        }
+      }
+
+      let dominantEntityId: string | null = null;
+      let dominantEntityCount: number = 0;
+      for (const [entityId, count] of entityIdCounts) {
+        if (count > dominantEntityCount) {
+          dominantEntityId = entityId;
+          dominantEntityCount = count;
+        }
+      }
+
+      const service: Service | null = dominantEntityId
+        ? await ServiceService.findOneById({
+            id: new ObjectID(dominantEntityId),
+            select: { name: true },
+            props: { isRoot: true },
+          })
+        : null;
+
+      const run: AIRun =
+        await FixPerformanceTaskTrigger.createPerformanceFixTaskFromTrace({
+          projectId,
+          traceId,
+          spans: analyzableSpans,
+          serviceName: service?.name,
+          userId: props.userId!,
+        });
+
+      Response.sendJsonObjectResponse(req, res, {
+        aiRunId: run.id!.toString(),
+      });
+      return;
+    } catch (err) {
+      next(err);
+      return;
+    }
+  },
+);
+
 export default router;