@oneuptime/common 11.3.26 → 11.4.0

package/Server/Utils/AI/Sentinel/IncidentInvestigationRunner.ts

@@ -0,0 +1,178 @@
+import ObjectID from "../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../Types/Date";
+import { Blue500 } from "../../../../Types/BrandColors";
+import { IncidentFeedEventType } from "../../../../Models/DatabaseModels/IncidentFeed";
+import IncidentFeedService from "../../../Services/IncidentFeedService";
+import IncidentAIContextBuilder, {
+  IncidentContextData,
+} from "../IncidentAIContextBuilder";
+import SentinelInvestigationEngine from "./SentinelInvestigationEngine";
+import SentinelMemory from "./SentinelMemory";
+import { ObservabilityAssistantResult } from "../Chat/ObservabilityAssistant";
+import logger from "../../Logger";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+
+/*
+ * Sentinel — incident investigation.
+ *
+ * When a new incident is declared, wakes Sentinel to investigate it (read-only)
+ * and post a cited root-cause analysis into the incident timeline + Slack/Teams
+ * — before the on-call engineer has finished reading the page. The heavy lifting
+ * (run lifecycle, the agent loop, confidence gating) lives in the shared
+ * SentinelInvestigationEngine; this file only assembles incident context and
+ * posts the result to the incident's feed.
+ *
+ * Built on the fire-and-forget async pattern already used throughout
+ * IncidentService.onCreateSuccess. See Internal/Roadmap/AISentinelReliabilityBrain.md.
+ */
+export default class SentinelIncidentInvestigationRunner {
+  /*
+   * Entry point called (fire-and-forget) from IncidentService.onCreateSuccess.
+   * Never throws — all failures are logged and recorded on the AIRun.
+   */
+  @CaptureSpan()
+  public static async investigateNewIncident(data: {
+    incidentId: ObjectID;
+    projectId: ObjectID;
+  }): Promise<void> {
+    const { incidentId, projectId } = data;
+
+    try {
+      if (
+        !(await SentinelInvestigationEngine.isEnabledForProject(
+          projectId,
+          "Incident",
+        ))
+      ) {
+        return;
+      }
+
+      const contextData: IncidentContextData =
+        await IncidentAIContextBuilder.buildIncidentContext({
+          incidentId,
+          includeWorkspaceMessages: false,
+        });
+
+      /*
+       * Recurrence memory: pull in past resolved incidents that share this
+       * incident's monitors/labels so Sentinel can recognise "I've seen this
+       * before" and reference the prior fix.
+       */
+      const priorCasesContext: string =
+        await SentinelMemory.getPriorSimilarIncidentsContext({
+          projectId,
+          currentIncidentId: incidentId,
+          monitorNames: (contextData.incident.monitors || [])
+            .map((m: { name?: string }) => {
+              return m.name || "";
+            })
+            .filter(Boolean),
+          labelNames: (contextData.incident.labels || [])
+            .map((l: { name?: string }) => {
+              return l.name || "";
+            })
+            .filter(Boolean),
+        });
+
+      await SentinelInvestigationEngine.investigate({
+        projectId,
+        feature: "Sentinel Incident Investigation",
+        subjectIncidentId: incidentId,
+        contextSummary:
+          this.buildIncidentSummary(contextData) + priorCasesContext,
+        postAnalysis: async (postData: {
+          analysisMarkdown: string;
+          isConfident: boolean;
+          result: ObservabilityAssistantResult;
+        }): Promise<void> => {
+          await IncidentFeedService.createIncidentFeedItem({
+            incidentId,
+            projectId,
+            incidentFeedEventType: IncidentFeedEventType.RootCause,
+            displayColor: Blue500,
+            feedInfoInMarkdown: postData.analysisMarkdown,
+            /*
+             * Quiet mode: an inconclusive investigation posts to the timeline
+             * but does NOT loudly ping the workspace / on-call.
+             */
+            workspaceNotification: {
+              sendWorkspaceNotification: postData.isConfident,
+            },
+          });
+        },
+      });
+    } catch (error) {
+      logger.error(
+        `Sentinel: unexpected error investigating incident ${incidentId.toString()}: ${error}`,
+      );
+    }
+  }
+
+  // Build a compact incident record to seed the investigation.
+  private static buildIncidentSummary(
+    contextData: IncidentContextData,
+  ): string {
+    const { incident, internalNotes } = contextData;
+
+    const lines: Array<string> = [];
+    lines.push("# Incident");
+    lines.push(`Title: ${incident.title || "N/A"}`);
+
+    if (incident.description) {
+      lines.push(`Description: ${incident.description}`);
+    }
+
+    lines.push(`Severity: ${incident.incidentSeverity?.name || "N/A"}`);
+    lines.push(
+      `Current state: ${incident.currentIncidentState?.name || "N/A"}`,
+    );
+    lines.push(
+      `Declared at: ${
+        incident.createdAt
+          ? OneUptimeDate.getDateAsFormattedString(incident.createdAt)
+          : "N/A"
+      }`,
+    );
+
+    if (incident.monitors && incident.monitors.length > 0) {
+      lines.push(
+        `Affected monitors: ${incident.monitors
+          .map((m: { name?: string }) => {
+            return m.name;
+          })
+          .filter(Boolean)
+          .join(", ")}`,
+      );
+    }
+
+    if (incident.labels && incident.labels.length > 0) {
+      lines.push(
+        `Labels: ${incident.labels
+          .map((l: { name?: string }) => {
+            return l.name;
+          })
+          .filter(Boolean)
+          .join(", ")}`,
+      );
+    }
+
+    if (incident.rootCause) {
+      lines.push(`Root cause (as recorded so far): ${incident.rootCause}`);
+    }
+
+    const recentNotes: Array<string> = (internalNotes || [])
+      .slice(-5)
+      .map((note: { note?: string }) => {
+        return note.note ? `- ${note.note}` : "";
+      })
+      .filter(Boolean);
+
+    if (recentNotes.length > 0) {
+      lines.push("");
+      lines.push("Recent internal notes:");
+      lines.push(...recentNotes);
+    }
+
+    return lines.join("\n");
+  }
+}

package/Server/Utils/AI/Sentinel/IncidentPostmortemRunner.ts

@@ -0,0 +1,105 @@
+import ObjectID from "../../../../Types/ObjectID";
+import { Blue500 } from "../../../../Types/BrandColors";
+import Incident from "../../../../Models/DatabaseModels/Incident";
+import { IncidentFeedEventType } from "../../../../Models/DatabaseModels/IncidentFeed";
+import IncidentService from "../../../Services/IncidentService";
+import IncidentFeedService from "../../../Services/IncidentFeedService";
+import SentinelInvestigationEngine from "./SentinelInvestigationEngine";
+import logger from "../../Logger";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+
+/*
+ * Sentinel — auto-draft postmortem on resolve (Phase 3, "close the loop").
+ *
+ * When an incident moves to a resolved state, Sentinel drafts a postmortem from
+ * the incident timeline + telemetry (reusing the existing
+ * IncidentService.generatePostmortemFromAI) and saves it to the incident for a
+ * human to review and edit — turning a ~90-minute manual writeup into a review.
+ *
+ * It NEVER overwrites a postmortem that already exists (human work wins), is
+ * gated by the same per-project opt-in + LLM provider as investigations, and is
+ * fire-and-forget: failures are logged, never surfaced to the resolve flow.
+ */
+const MAX_FEED_PREVIEW_CHARS: number = 6000;
+
+export default class SentinelIncidentPostmortemRunner {
+  @CaptureSpan()
+  public static async draftPostmortemOnResolve(data: {
+    incidentId: ObjectID;
+    projectId: ObjectID;
+  }): Promise<void> {
+    const { incidentId, projectId } = data;
+
+    try {
+      if (
+        !(await SentinelInvestigationEngine.isEnabledForProject(
+          projectId,
+          "Incident",
+        ))
+      ) {
+        return;
+      }
+
+      const incident: Incident | null = await IncidentService.findOneById({
+        id: incidentId,
+        select: {
+          _id: true,
+          incidentNumber: true,
+          postmortemNote: true,
+        },
+        props: { isRoot: true },
+      });
+
+      if (!incident) {
+        return;
+      }
+
+      // Never clobber an existing postmortem (human or previously drafted).
+      if (
+        incident.postmortemNote &&
+        incident.postmortemNote.trim().length > 0
+      ) {
+        return;
+      }
+
+      const draft: string = await IncidentService.generatePostmortemFromAI({
+        incidentId,
+      });
+
+      if (!draft || !draft.trim()) {
+        return;
+      }
+
+      await IncidentService.updateOneById({
+        id: incidentId,
+        data: {
+          postmortemNote: draft,
+        },
+        props: { isRoot: true },
+      });
+
+      await IncidentFeedService.createIncidentFeedItem({
+        incidentId,
+        projectId,
+        incidentFeedEventType: IncidentFeedEventType.PostmortemNote,
+        displayColor: Blue500,
+        feedInfoInMarkdown: `## 🧠 Sentinel — Draft Postmortem\n\nSentinel drafted a postmortem for incident #${incident.incidentNumber} from the incident timeline and telemetry. It has been saved on the incident for you to review and edit.`,
+        moreInformationInMarkdown:
+          draft.length > MAX_FEED_PREVIEW_CHARS
+            ? `${draft.substring(0, MAX_FEED_PREVIEW_CHARS)}\n\n…(truncated — the full draft is saved on the incident.)`
+            : draft,
+        workspaceNotification: {
+          sendWorkspaceNotification: true,
+        },
+      });
+
+      logger.debug(
+        `Sentinel: drafted postmortem for incident ${incidentId.toString()}.`,
+      );
+    } catch (error) {
+      logger.error(
+        `Sentinel: failed to draft postmortem for incident ${incidentId.toString()}: ${error}`,
+      );
+    }
+  }
+}

package/Server/Utils/AI/Sentinel/SentinelInvestigationEngine.ts

@@ -0,0 +1,405 @@
+import ObjectID from "../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../Types/Date";
+import { JSONObject } from "../../../../Types/JSON";
+import {
+  AIChatCitation,
+  AIRunEventResultSummary,
+} from "../../../../Types/AI/AIChatTypes";
+import AIRunType from "../../../../Types/AI/AIRunType";
+import AIRunStatus from "../../../../Types/AI/AIRunStatus";
+import AIRunEventType from "../../../../Types/AI/AIRunEventType";
+import AIRun from "../../../../Models/DatabaseModels/AIRun";
+import AIRunEvent from "../../../../Models/DatabaseModels/AIRunEvent";
+import Project from "../../../../Models/DatabaseModels/Project";
+import LlmProvider from "../../../../Models/DatabaseModels/LlmProvider";
+import AIRunService from "../../../Services/AIRunService";
+import AIRunEventService from "../../../Services/AIRunEventService";
+import ProjectService from "../../../Services/ProjectService";
+import LlmProviderService from "../../../Services/LlmProviderService";
+import ObservabilityAssistant, {
+  ObservabilityAssistantResult,
+  ObservabilityAssistantStep,
+  ObservabilityAssistantStepType,
+} from "../Chat/ObservabilityAssistant";
+import logger from "../../Logger";
+import CaptureSpan from "../../Telemetry/CaptureSpan";
+
+/*
+ * Sentinel — the shared autonomous-investigation engine.
+ *
+ * A single subject-agnostic core that powers "wake on signal" investigations
+ * for both incidents and alerts (and, later, anomalies). It:
+ *   1. records the run as an AIRun(Investigation) + AIRunEvents (audit trail),
+ *   2. runs the existing read-only, tool-grounded, citation-minting agent loop
+ *      (ObservabilityAssistant) with the Sentinel persona and a larger budget,
+ *   3. brands the cited analysis, judges confidence, and
+ *   4. hands the finished analysis back to the caller to post to the subject's
+ *      timeline.
+ *
+ * The investigation is strictly READ-ONLY: it can never mutate anything.
+ * Enablement + provider gating is shared via isEnabledForProject().
+ */
+
+// Budgets — larger than an interactive chat-ops answer, small enough to stay cheap.
+const MAX_LLM_CALLS: number = 8;
+const MAX_TOOL_CALLS: number = 12;
+const MAX_WALL_CLOCK_MS: number = 150 * 1000;
+const MAX_OUTPUT_TOKENS: number = 2000;
+
+/*
+ * Sentinel's own contract: it writes exactly this phrase when it cannot
+ * determine a cause. We match it deterministically to drive "quiet mode" —
+ * a non-answer should never loudly page the on-call.
+ */
+const INCONCLUSIVE_RE: RegExp = /inconclusive[^.\n]*insufficient signal/i;
+
+// Maps a live agent step to the AIRunEvent type persisted for the glass-box trail.
+const STEP_EVENT_TYPE: Record<ObservabilityAssistantStepType, AIRunEventType> =
+  {
+    llm_started: AIRunEventType.LlmCallStarted,
+    llm_completed: AIRunEventType.LlmCallCompleted,
+    tool_started: AIRunEventType.ToolCallStarted,
+    tool_completed: AIRunEventType.ToolCallCompleted,
+    tool_failed: AIRunEventType.ToolCallFailed,
+  };
+
+const INVESTIGATION_PERSONA: string = `You are "Sentinel", OneUptime's autonomous AI Site Reliability Engineer. You have been woken automatically because a NEW signal (an incident or alert) was just declared in this project — no human has asked you a question yet. Investigate it proactively and produce a first-pass root cause analysis that the on-call engineer will read the moment they are paged.
+
+Investigate like a senior on-call engineer:
+- Start from the affected monitors/services named in the signal.
+- Use your read tools to inspect the telemetry AROUND the signal's creation time: recent exceptions and their trends, error/latency metrics versus their normal range, failing traces, relevant logs, and recent changes / deploys.
+- Form the single most likely root-cause hypothesis. If the evidence is inconclusive, say so plainly and list what you checked — do NOT guess a cause the data does not support.
+- If the context lists past resolved incidents, check whether this is a RECURRENCE. If the current signal matches one, say so explicitly, reference that incident number, and note how it was resolved before — but still verify against the current telemetry.
+
+Write your final answer as a concise incident-response note with exactly these sections (use these markdown headings):
+**Summary** — one or two sentences a paged engineer can read in five seconds.
+**Most likely root cause** — your hypothesis, with only the confidence the evidence actually supports, each factual claim carrying its [C#] citation. If you could not determine it, write "Inconclusive — insufficient signal" and explain what is missing.
+**Evidence** — the key findings that support or rule out the hypothesis, each cited.
+**Suggested next steps** — concrete actions for the on-call engineer.
+
+Keep it tight and skimmable. You are read-only: never claim to have changed anything.`;
+
+// Which signal an investigation is about — each has its own per-project opt-in.
+export type SentinelSubjectType = "Incident" | "Alert";
+
+export interface InvestigationRequest {
+  projectId: ObjectID;
+  // Label recorded on LlmLog, e.g. "Sentinel Incident Investigation".
+  feature: string;
+  // A compact markdown summary of the subject that seeds the investigation.
+  contextSummary: string;
+  /*
+   * The subject that triggered this run — links the AIRun so the live panel can
+   * find "the investigation for this incident/alert". Exactly one is set.
+   */
+  subjectIncidentId?: ObjectID | undefined;
+  subjectAlertId?: ObjectID | undefined;
+  /*
+   * Called with the finished, branded, cited analysis so the caller can post it
+   * to the subject's timeline. `isConfident` is false when Sentinel reported it
+   * could not determine the cause — callers use it to post QUIETLY (no loud
+   * workspace ping) rather than paging a non-answer.
+   */
+  postAnalysis: (data: {
+    analysisMarkdown: string;
+    isConfident: boolean;
+    result: ObservabilityAssistantResult;
+  }) => Promise<void>;
+}
+
+export default class SentinelInvestigationEngine {
+  /*
+   * Shared gate: AI enabled, the subject's auto-investigation opt-in on, and an
+   * LLM provider configured. Incidents and alerts each have their own opt-in so
+   * they can be enabled independently. Runs before any (subject-specific)
+   * context assembly.
+   */
+  @CaptureSpan()
+  public static async isEnabledForProject(
+    projectId: ObjectID,
+    subjectType: SentinelSubjectType,
+  ): Promise<boolean> {
+    const project: Project | null = await ProjectService.findOneById({
+      id: projectId,
+      select: {
+        enableAi: true,
+        enableAutomaticIncidentInvestigation: true,
+        enableAutomaticAlertInvestigation: true,
+      },
+      props: { isRoot: true },
+    });
+
+    if (!project) {
+      return false;
+    }
+
+    if (project.enableAi === false) {
+      return false;
+    }
+
+    const isOptedIn: boolean =
+      subjectType === "Alert"
+        ? project.enableAutomaticAlertInvestigation === true
+        : project.enableAutomaticIncidentInvestigation === true;
+
+    if (!isOptedIn) {
+      return false;
+    }
+
+    const llmProvider: LlmProvider | null =
+      await LlmProviderService.getLLMProviderForProject(projectId);
+
+    if (!llmProvider) {
+      logger.debug(
+        `Sentinel: skipping investigation for project ${projectId.toString()} — no LLM provider configured.`,
+      );
+      return false;
+    }
+
+    return true;
+  }
+
+  /*
+   * Run one investigation end-to-end. Never throws — failures are logged and
+   * recorded on the AIRun.
+   */
+  @CaptureSpan()
+  public static async investigate(
+    request: InvestigationRequest,
+  ): Promise<void> {
+    const { projectId } = request;
+
+    // Record the run up front so it is auditable even if it fails.
+    const run: AIRun = new AIRun();
+    run.projectId = projectId;
+    run.runType = AIRunType.Investigation;
+    run.status = AIRunStatus.Running;
+    run.startedAt = OneUptimeDate.getCurrentDate();
+    run.lastHeartbeatAt = OneUptimeDate.getCurrentDate();
+
+    if (request.subjectIncidentId) {
+      run.triggeredByIncidentId = request.subjectIncidentId;
+    }
+    if (request.subjectAlertId) {
+      run.triggeredByAlertId = request.subjectAlertId;
+    }
+
+    let createdRun: AIRun;
+    try {
+      createdRun = await AIRunService.create({
+        data: run,
+        props: { isRoot: true },
+      });
+    } catch (error) {
+      logger.error(`Sentinel: failed to create investigation run: ${error}`);
+      return;
+    }
+
+    const aiRunId: ObjectID = createdRun.id!;
+    let sequence: number = 0;
+
+    await this.emitEvent({
+      projectId,
+      aiRunId,
+      sequence: sequence++,
+      eventType: AIRunEventType.RunStarted,
+    });
+
+    /*
+     * Live narration: persist each LLM/tool step as an AIRunEvent so the UI can
+     * "watch it think" by polling the run's events. Best-effort, ordered.
+     */
+    const onStep: (step: ObservabilityAssistantStep) => Promise<void> = async (
+      step: ObservabilityAssistantStep,
+    ): Promise<void> => {
+      const resultSummary: AIRunEventResultSummary | undefined =
+        step.rowCount !== undefined ||
+        step.durationMs !== undefined ||
+        step.errorMessage !== undefined
+          ? {
+              rowCount: step.rowCount,
+              durationInMs: step.durationMs,
+              errorMessage: step.errorMessage,
+            }
+          : undefined;
+
+      await this.emitEvent({
+        projectId,
+        aiRunId,
+        sequence: sequence++,
+        eventType: STEP_EVENT_TYPE[step.type],
+        toolName: step.toolName,
+        toolArguments: step.toolArguments,
+        resultSummary,
+        citationId: step.citationId,
+      });
+
+      // Keep the run visibly alive for the stale-run sweeper + live UI.
+      if (step.type === "llm_started") {
+        await this.touchHeartbeat(aiRunId);
+      }
+    };
+
+    try {
+      const result: ObservabilityAssistantResult =
+        await ObservabilityAssistant.answerQuestion({
+          projectId,
+          // System run — full read access to the project's telemetry.
+          props: { isRoot: true },
+          feature: request.feature,
+          systemInstructions: INVESTIGATION_PERSONA,
+          question: `A new signal has just been declared and you have been woken to investigate it. Investigate now and produce your root cause analysis.\n\n${request.contextSummary}`,
+          maxLlmCalls: MAX_LLM_CALLS,
+          maxToolCalls: MAX_TOOL_CALLS,
+          maxWallClockMs: MAX_WALL_CLOCK_MS,
+          maxOutputTokens: MAX_OUTPUT_TOKENS,
+          onStep,
+        });
+
+      await AIRunService.updateOneBy({
+        query: { _id: aiRunId.toString(), status: AIRunStatus.Running },
+        data: {
+          status: AIRunStatus.Completed,
+          completedAt: OneUptimeDate.getCurrentDate(),
+          lastHeartbeatAt: OneUptimeDate.getCurrentDate(),
+          llmCallCount: result.llmCallCount,
+          toolCallCount: result.toolCallCount,
+          totalTokens: result.totalTokens,
+        } as never,
+        props: { isRoot: true },
+      });
+
+      await this.emitEvent({
+        projectId,
+        aiRunId,
+        sequence: sequence++,
+        eventType: AIRunEventType.RunCompleted,
+      });
+
+      const analysis: string = (result.contentInMarkdown || "").trim();
+
+      if (!analysis) {
+        logger.debug(
+          `Sentinel: investigation (run ${aiRunId.toString()}) produced no analysis; nothing posted.`,
+        );
+        return;
+      }
+
+      const isConfident: boolean = !INCONCLUSIVE_RE.test(analysis);
+
+      await request.postAnalysis({
+        analysisMarkdown: this.buildBrandedMarkdown(result, analysis),
+        isConfident,
+        result,
+      });
+
+      logger.debug(
+        `Sentinel: investigation complete (run ${aiRunId.toString()}, confident=${isConfident}, ${result.llmCallCount} LLM calls, ${result.toolCallCount} tools, ${result.totalTokens} tokens).`,
+      );
+    } catch (error) {
+      const message: string =
+        error instanceof Error ? error.message : String(error);
+
+      await AIRunService.updateOneBy({
+        query: { _id: aiRunId.toString(), status: AIRunStatus.Running },
+        data: {
+          status: AIRunStatus.Error,
+          completedAt: OneUptimeDate.getCurrentDate(),
+          errorMessage: message.substring(0, 480),
+        } as never,
+        props: { isRoot: true },
+      });
+
+      await this.emitEvent({
+        projectId,
+        aiRunId,
+        sequence: sequence++,
+        eventType: AIRunEventType.RunFailed,
+      });
+
+      logger.error(
+        `Sentinel: investigation failed (run ${aiRunId.toString()}): ${message}`,
+      );
+    }
+  }
+
+  // Wrap the agent's analysis with Sentinel branding + an evidence list.
+  private static buildBrandedMarkdown(
+    result: ObservabilityAssistantResult,
+    analysisMarkdown: string,
+  ): string {
+    let markdown: string = `## 🧠 Sentinel — Automated Root Cause Analysis\n\n${analysisMarkdown}`;
+
+    const citations: Array<AIChatCitation> = result.citations || [];
+
+    if (citations.length > 0) {
+      markdown += `\n\n**Evidence checked**`;
+      for (const citation of citations.slice(0, 15)) {
+        markdown += `\n- **[${citation.id}]** ${citation.label} — ${citation.rowCount} row(s)`;
+      }
+    }
+
+    markdown += `\n\n---\n*Investigated automatically by OneUptime Sentinel — read-only, ${result.toolCallCount} quer${
+      result.toolCallCount === 1 ? "y" : "ies"
+    } run across your own telemetry${
+      result.modelName ? ` using ${result.modelName}` : ""
+    }. This is an AI-generated first pass; verify before acting.*`;
+
+    return markdown;
+  }
+
+  // Refresh lastHeartbeatAt so a long-running investigation isn't swept as stale.
+  private static async touchHeartbeat(aiRunId: ObjectID): Promise<void> {
+    try {
+      await AIRunService.updateOneBy({
+        query: { _id: aiRunId.toString(), status: AIRunStatus.Running },
+        data: {
+          lastHeartbeatAt: OneUptimeDate.getCurrentDate(),
+        } as never,
+        props: { isRoot: true },
+      });
+    } catch (error) {
+      logger.error(`Sentinel: heartbeat update failed: ${error}`);
+    }
+  }
+
+  private static async emitEvent(data: {
+    projectId: ObjectID;
+    aiRunId: ObjectID;
+    sequence: number;
+    eventType: AIRunEventType;
+    toolName?: string | undefined;
+    toolArguments?: JSONObject | undefined;
+    resultSummary?: AIRunEventResultSummary | undefined;
+    citationId?: string | undefined;
+  }): Promise<void> {
+    try {
+      const event: AIRunEvent = new AIRunEvent();
+      event.projectId = data.projectId;
+      event.aiRunId = data.aiRunId;
+      event.sequence = data.sequence;
+      event.eventType = data.eventType;
+
+      if (data.toolName) {
+        event.toolName = data.toolName;
+      }
+      if (data.toolArguments) {
+        event.toolArguments = data.toolArguments;
+      }
+      if (data.resultSummary) {
+        event.resultSummary = data.resultSummary;
+      }
+      if (data.citationId) {
+        event.citationId = data.citationId;
+      }
+
+      await AIRunEventService.create({
+        data: event,
+        props: { isRoot: true },
+      });
+    } catch (error) {
+      // Events are best-effort telemetry — never fail the run because of them.
+      logger.error(`Sentinel: failed to emit AIRunEvent: ${error}`);
+    }
+  }
+}