@oneuptime/common 11.3.25 → 11.3.28

package/Types/AI/AIChatMessageRole.ts

@@ -0,0 +1,6 @@
+enum AIChatMessageRole {
+  User = "User",
+  Assistant = "Assistant",
+}
+
+export default AIChatMessageRole;

package/Types/AI/AIChatMessageStatus.ts

@@ -0,0 +1,32 @@
+enum AIChatMessageStatus {
+  Pending = "Pending",
+  InProgress = "InProgress",
+  /*
+   * The turn paused because the agent wants to run one or more mutating tools
+   * and the conversation is in "Ask for approval" mode. The message carries the
+   * pending tool actions; the user approves or denies them to resume the turn.
+   */
+  WaitingForApproval = "WaitingForApproval",
+  Completed = "Completed",
+  Error = "Error",
+}
+
+export default AIChatMessageStatus;
+
+export class AIChatMessageStatusHelper {
+  public static isTerminalStatus(status: AIChatMessageStatus): boolean {
+    return (
+      status === AIChatMessageStatus.Completed ||
+      status === AIChatMessageStatus.Error
+    );
+  }
+
+  // Statuses in which a run is still in flight (spinner or approval card shown).
+  public static isActiveStatus(status: AIChatMessageStatus): boolean {
+    return (
+      status === AIChatMessageStatus.Pending ||
+      status === AIChatMessageStatus.InProgress ||
+      status === AIChatMessageStatus.WaitingForApproval
+    );
+  }
+}

package/Types/AI/AIChatPermissionMode.ts

@@ -0,0 +1,69 @@
+/*
+ * How the AI chat agent is allowed to run tools that MUTATE project data
+ * (create/acknowledge/resolve incidents and alerts, etc). Read-only tools are
+ * never gated by this — they always run. This is stored per-conversation on
+ * AIConversation.permissionMode and enforced in ChatAgentRunner.
+ */
+enum AIChatPermissionMode {
+  /*
+   * The agent pauses before every mutating tool and asks the user to approve
+   * it. This is the safe default.
+   */
+  AskForApproval = "AskForApproval",
+  /*
+   * The agent runs mutating tools immediately (still gated by the user's RBAC
+   * permissions). "Bypass permissions" / YOLO mode.
+   */
+  AutoRun = "AutoRun",
+  // Mutating tools are not even offered to the model. The agent can only read.
+  ReadOnly = "ReadOnly",
+}
+
+export default AIChatPermissionMode;
+
+export interface AIChatPermissionModeOption {
+  value: AIChatPermissionMode;
+  title: string;
+  description: string;
+}
+
+export class AIChatPermissionModeHelper {
+  public static getDefault(): AIChatPermissionMode {
+    return AIChatPermissionMode.AskForApproval;
+  }
+
+  public static isValid(
+    value: string | undefined,
+  ): value is AIChatPermissionMode {
+    return Object.values(AIChatPermissionMode).includes(
+      value as AIChatPermissionMode,
+    );
+  }
+
+  public static parse(value: string | undefined): AIChatPermissionMode {
+    return this.isValid(value) ? value : this.getDefault();
+  }
+
+  public static getOptions(): Array<AIChatPermissionModeOption> {
+    return [
+      {
+        value: AIChatPermissionMode.AskForApproval,
+        title: "Ask for approval",
+        description:
+          "The copilot pauses and asks before it changes anything (creating incidents, acknowledging alerts, etc).",
+      },
+      {
+        value: AIChatPermissionMode.AutoRun,
+        title: "Auto-run (bypass approvals)",
+        description:
+          "The copilot performs actions immediately, still limited to what your role can do.",
+      },
+      {
+        value: AIChatPermissionMode.ReadOnly,
+        title: "Read-only",
+        description:
+          "The copilot can investigate and answer questions but can never change anything.",
+      },
+    ];
+  }
+}

package/Types/AI/AIChatTypes.ts

@@ -0,0 +1,231 @@
+import { JSONObject } from "../JSON";
+
+/*
+ * Shared types for the AI observability chat feature. These shapes are
+ * persisted as JSON columns on AIConversationMessage / AIRun / AIRunEvent and
+ * rendered by the dashboard, so they must stay JSON-serializable.
+ */
+
+/*
+ * Where a citation chip should deep-link to in the dashboard. The dashboard
+ * maps each target type onto its own RouteMap entry.
+ */
+export enum AIChatCitationTargetType {
+  Logs = "Logs",
+  Traces = "Traces",
+  TraceView = "TraceView",
+  Metrics = "Metrics",
+  Exceptions = "Exceptions",
+  Incidents = "Incidents",
+  IncidentView = "IncidentView",
+  Alerts = "Alerts",
+  AlertView = "AlertView",
+  Monitors = "Monitors",
+  MonitorView = "MonitorView",
+}
+
+export interface AIChatCitationTarget {
+  type: AIChatCitationTargetType;
+  // Route params keyed by param name (e.g. { traceId: "abc" }).
+  params?: { [key: string]: string };
+}
+
+/*
+ * Citations are minted server-side from validated tool arguments — never by
+ * the model. rowCount 0 is meaningful: it is proof of absence ("checked,
+ * found nothing").
+ */
+export interface AIChatCitation {
+  id: string; // "C1", "C2" — sequential per message
+  toolName: string;
+  label: string;
+  queryArguments: JSONObject; // validated tool args as executed — replayable
+  rowCount: number;
+  target?: AIChatCitationTarget | undefined;
+}
+
+/*
+ * ---------------------------------------------------------------------------
+ * Inline widgets
+ * ---------------------------------------------------------------------------
+ * A tool can attach a widget to its result. The widget is persisted on the
+ * assistant message (AIConversationMessage.widgets) and rendered inline in the
+ * chat by the dashboard. Widget `data` is type-specific and MUST stay
+ * JSON-serializable. Unlike the text sent to the LLM, widget data is built from
+ * the RAW rows (not the redacted/truncated LLM payload) because it is rendered
+ * back to the same user who already has RBAC access to it.
+ */
+export enum AIChatWidgetType {
+  // A time-series line chart (e.g. a metric aggregated over time).
+  TimeSeriesChart = "TimeSeriesChart",
+  // A bar chart, optionally stacked (e.g. log volume by severity over time).
+  BarChart = "BarChart",
+  // A generic sortable table.
+  Table = "Table",
+  // A trace waterfall (span tree with durations).
+  TraceWaterfall = "TraceWaterfall",
+  // A list of incident cards.
+  IncidentList = "IncidentList",
+  // A list of alert cards.
+  AlertList = "AlertList",
+  // A list of exception cards.
+  ExceptionList = "ExceptionList",
+  // KPI stat tiles.
+  StatCards = "StatCards",
+  // A single created/updated resource (e.g. the incident the agent just made).
+  ResourceCard = "ResourceCard",
+}
+
+/*
+ * One point in a chart series. x is an ISO timestamp (time charts) or a
+ * category label (categorical charts); y is the numeric value.
+ */
+export interface AIChatWidgetPoint {
+  x: string;
+  y: number | null;
+}
+
+export interface AIChatWidgetSeries {
+  name: string;
+  points: Array<AIChatWidgetPoint>;
+}
+
+export interface AIChatWidgetColumn {
+  key: string;
+  title: string;
+  // Rough hint for alignment/formatting in the renderer.
+  type?: "text" | "number" | "date" | undefined;
+}
+
+export interface AIChatWidgetStat {
+  label: string;
+  value: string | number;
+  unit?: string | undefined;
+}
+
+export interface AIChatWidgetSpan {
+  spanId: string;
+  parentSpanId?: string | undefined;
+  name: string;
+  // Offset of the span start from the trace start, in milliseconds.
+  startOffsetMs: number;
+  durationMs: number;
+  isError: boolean;
+  serviceName?: string | undefined;
+}
+
+/*
+ * Type-specific widget payload. Only the fields relevant to `type` are set:
+ * - TimeSeriesChart / BarChart: `series` (+ `stacked`, `unit`, `xIsTime`)
+ * - Table: `columns` + `rows`
+ * - TraceWaterfall: `spans` + `totalDurationMs`
+ * - IncidentList / AlertList / ExceptionList: `items`
+ * - StatCards: `stats`
+ * - ResourceCard: `resourceType`, `heading`, `subheading`, `fields`, `link`
+ */
+export interface AIChatWidgetData {
+  series?: Array<AIChatWidgetSeries> | undefined;
+  stacked?: boolean | undefined;
+  xIsTime?: boolean | undefined;
+  unit?: string | undefined;
+  valueLabel?: string | undefined;
+  columns?: Array<AIChatWidgetColumn> | undefined;
+  rows?: Array<JSONObject> | undefined;
+  spans?: Array<AIChatWidgetSpan> | undefined;
+  totalDurationMs?: number | undefined;
+  items?: Array<JSONObject> | undefined;
+  stats?: Array<AIChatWidgetStat> | undefined;
+  resourceType?: string | undefined;
+  heading?: string | undefined;
+  subheading?: string | undefined;
+  fields?: Array<{ label: string; value: string }> | undefined;
+  link?: AIChatCitationTarget | undefined;
+}
+
+export interface AIChatWidget {
+  id: string; // "W1", "W2" — sequential per message
+  citationId?: string | undefined; // correlates to the citation of the same tool call
+  type: AIChatWidgetType;
+  title: string;
+  description?: string | undefined;
+  data: AIChatWidgetData;
+}
+
+/*
+ * ---------------------------------------------------------------------------
+ * Tool actions (mutations + approvals)
+ * ---------------------------------------------------------------------------
+ * When the agent wants to run a mutating tool it records an AIChatToolAction on
+ * the assistant message. In "Ask for approval" mode the action starts Pending
+ * and the run pauses until the user approves/denies it; the resumed run then
+ * executes approved actions and marks them Executed/Failed.
+ */
+export enum AIChatToolActionStatus {
+  Pending = "Pending", // awaiting the user's decision
+  Approved = "Approved", // user approved; not yet executed
+  Denied = "Denied", // user declined
+  Executed = "Executed", // ran successfully
+  Failed = "Failed", // ran but failed
+  Skipped = "Skipped", // not run (e.g. budget exhausted)
+}
+
+export interface AIChatToolAction {
+  id: string; // equals the LLM tool call id
+  toolName: string;
+  title: string; // human label, e.g. "Create incident: Checkout is down"
+  description?: string | undefined;
+  arguments: JSONObject;
+  isMutation: boolean;
+  requiresApproval: boolean;
+  status: AIChatToolActionStatus;
+  resultSummary?: string | undefined;
+}
+
+export interface AIRunEventResultSummary {
+  rowCount?: number | undefined;
+  durationInMs?: number | undefined;
+  isTruncated?: boolean | undefined;
+  bytesSentToLlm?: number | undefined;
+  errorMessage?: string | undefined;
+}
+
+// What was sent to which LLM during a run — the per-run egress manifest.
+export interface AIRunEgressManifestToolEntry {
+  toolName: string;
+  rowCount: number;
+  bytesSentToLlm: number;
+  redactionCount: number;
+}
+
+/*
+ * The serialized in-flight state of a turn that paused to wait for tool
+ * approval. Persisted on AIRun.pausedState so ChatAgentRunner.resumeTurn can
+ * rehydrate the exact conversation and continue the loop. `messages` and
+ * `pendingToolCalls` are JSON projections of the runner's internal
+ * LLMMessage / LLMToolCall types (kept as JSONObject here so this shared type
+ * does not depend on server code).
+ */
+export interface AIRunPausedState {
+  messages: Array<JSONObject>;
+  pendingToolCalls: Array<JSONObject>;
+  llmCallCount: number;
+  toolCallCount: number;
+  totalTokens: number;
+  totalCostInUSDCents: number;
+  eventSequence: number;
+  citations: Array<AIChatCitation>;
+  widgets: Array<AIChatWidget>;
+  toolActions: Array<AIChatToolAction>;
+  egressToolEntries: Array<AIRunEgressManifestToolEntry>;
+  startedAtMs: number;
+}
+
+export interface AIRunEgressManifest {
+  llmProviderName?: string | undefined;
+  llmType?: string | undefined;
+  modelName?: string | undefined;
+  isGlobalProvider?: boolean | undefined;
+  llmCallCount: number;
+  totalTokens: number;
+  toolDataSentToLlm: Array<AIRunEgressManifestToolEntry>;
+}

package/Types/AI/AIRunEventType.ts

@@ -0,0 +1,17 @@
+enum AIRunEventType {
+  RunStarted = "RunStarted",
+  LlmCallStarted = "LlmCallStarted",
+  LlmCallCompleted = "LlmCallCompleted",
+  ToolCallStarted = "ToolCallStarted",
+  ToolCallCompleted = "ToolCallCompleted",
+  ToolCallFailed = "ToolCallFailed",
+  // The run paused to ask the user to approve one or more mutating actions.
+  ApprovalRequested = "ApprovalRequested",
+  // A mutating action the user approved was executed (or denied and skipped).
+  ActionExecuted = "ActionExecuted",
+  ActionDenied = "ActionDenied",
+  RunCompleted = "RunCompleted",
+  RunFailed = "RunFailed",
+}
+
+export default AIRunEventType;

package/Types/AI/AIRunStatus.ts

@@ -0,0 +1,28 @@
+enum AIRunStatus {
+  Running = "Running",
+  /*
+   * The run paused mid-turn to wait for the user to approve pending tool
+   * actions (see AIChatPermissionMode.AskForApproval). It is not terminal — it
+   * resumes when the user responds — but it is also not actively consuming
+   * compute, so the stale-run sweeper (which only touches Running runs) leaves
+   * it alone.
+   */
+  WaitingForApproval = "WaitingForApproval",
+  Completed = "Completed",
+  Error = "Error",
+  Cancelled = "Cancelled",
+  Stale = "Stale",
+}
+
+export default AIRunStatus;
+
+export class AIRunStatusHelper {
+  public static isTerminalStatus(status: AIRunStatus): boolean {
+    return (
+      status === AIRunStatus.Completed ||
+      status === AIRunStatus.Error ||
+      status === AIRunStatus.Cancelled ||
+      status === AIRunStatus.Stale
+    );
+  }
+}

package/Types/AI/AIRunType.ts

@@ -0,0 +1,6 @@
+enum AIRunType {
+  Chat = "Chat",
+  Investigation = "Investigation",
+}
+
+export default AIRunType;