@uipath/insights-tool 1.201.0-preview.115 → 1.201.0-preview.121

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   Command,
   metadata,
   registerCommands
-} from "./tool-vs72q3tv.js";
+} from "./tool-b9c68vwv.js";
 import"./tool-9qecd4wb.js";
 import"./tool-7eva0peq.js";
 import"./tool-5arsyj36.js";

package/dist/{tool-vs72q3tv.js → tool-b9c68vwv.js}

@@ -2112,7 +2112,7 @@ var require_commander = __commonJS((exports) => {
 var package_default = {
   name: "@uipath/insights-tool",
   license: "MIT",
-  version: "1.201.0-preview.115",
+  version: "1.201.0-preview.121",
   description: "Query UiPath Insights data — jobs, failures, and performance metrics.",
   private: false,
   repository: {
@@ -2205,17 +2205,9 @@ var TLS_ERROR_CODES = new Set([
 ]);
 var TLS_INSTRUCTIONS = "The server's TLS certificate could not be verified. Most often a " + "corporate proxy/firewall re-signs HTTPS with a root CA that Node does " + "not trust — set NODE_EXTRA_CA_CERTS to that CA's PEM file (and HTTPS_PROXY " + "if you connect through a proxy). If the certificate is instead expired or " + "its hostname does not match, fix the endpoint URL or the system clock. " + "Then retry.";
 var NETWORK_INSTRUCTIONS = "Could not reach the UiPath service. Check your network connection and " + "VPN, confirm any HTTP_PROXY/HTTPS_PROXY/NO_PROXY settings are correct, " + "then retry.";
+var LOCAL_PERMISSION_ERROR_CODES = new Set(["EACCES", "EPERM", "EROFS"]);
 function describeConnectivityError(error) {
-  const queue = [error];
-  const seen = new Set;
-  for (let steps = 0;queue.length > 0 && steps < 32; steps++) {
-    const current = queue.shift();
-    if (current === null || typeof current !== "object")
-      continue;
-    if (seen.has(current))
-      continue;
-    seen.add(current);
-    const cur = current;
+  for (const cur of walkErrorGraph(error)) {
     const code = typeof cur.code === "string" ? cur.code : undefined;
     const message = typeof cur.message === "string" ? cur.message : undefined;
     if (code && TLS_ERROR_CODES.has(code)) {
@@ -2234,6 +2226,21 @@ function describeConnectivityError(error) {
         instructions: NETWORK_INSTRUCTIONS
       };
     }
+  }
+  return;
+}
+function* walkErrorGraph(error) {
+  const queue = [error];
+  const seen = new Set;
+  for (let steps = 0;queue.length > 0 && steps < 32; steps++) {
+    const current = queue.shift();
+    if (current === null || typeof current !== "object")
+      continue;
+    if (seen.has(current))
+      continue;
+    seen.add(current);
+    const cur = current;
+    yield cur;
     if (cur.cause !== undefined)
       queue.push(cur.cause);
     if (Array.isArray(cur.errors))
@@ -3418,6 +3425,7 @@ var CLI_ERROR_CODES = [
   "invalid_argument",
   "authentication_required",
   "permission_denied",
+  "local_permission_denied",
   "not_found",
   "rate_limited",
   "network_error",
@@ -3458,18 +3466,31 @@ class Pagination {
   Offset;
   Total;
   HasMore;
+  NextPage;
   constructor({
     returned,
     limit,
     offset,
-    total
+    total,
+    hasMore,
+    nextPage
   }) {
     this.Returned = returned;
     this.Limit = limit;
     this.Offset = offset;
     this.Total = total;
-    this.HasMore = total === undefined ? returned === limit : offset + returned < total;
+    this.HasMore = hasMore ?? derivePaginationHasMore(returned, limit, offset, total, nextPage);
+    this.NextPage = nextPage;
+  }
+}
+function derivePaginationHasMore(returned, limit, offset, total, nextPage) {
+  if (nextPage) {
+    return true;
+  }
+  if (total === undefined) {
+    return returned >= limit;
   }
+  return (offset ?? 0) + returned < total;
 }
 
 class SuccessOutput {
@@ -3874,12 +3895,16 @@ function defaultErrorCodeForHttpStatus(status) {
     return "server_error";
   return;
 }
+var LOCAL_PERMISSION_TEXT_PATTERN = /(?:\b|\()(?:EACCES|EPERM|EROFS)(?::\s|\))/;
 function defaultErrorCodeForFailure(data) {
   if (data.Result === RESULTS.Failure) {
     const status = data.Context?.httpStatus ?? parseHttpStatusFromMessage(data.Message);
     const errorCode = defaultErrorCodeForHttpStatus(status);
     if (errorCode)
       return errorCode;
+    if (status === undefined && (LOCAL_PERMISSION_TEXT_PATTERN.test(data.Message) || LOCAL_PERMISSION_TEXT_PATTERN.test(data.Instructions))) {
+      return "local_permission_denied";
+    }
   }
   return defaultErrorCodeForResult(data.Result);
 }
@@ -4427,11 +4452,10 @@ function getSdkUserAgentToken(pkg) {
   const packageName = pkg.name.replace(/^@uipath\//, "");
   return getEffectiveUserAgent(`${packageName}/${pkg.version}`);
 }
-// ../common/src/tool-provider.ts
-var factorySlot = singleton("PackagerFactoryProvider");
-var moduleSlot = singleton("ToolModuleProvider");
 // ../common/src/telemetry/ship-succeeded.ts
 var shippedKeysSlot = singleton("ShipSucceededDedupeKeys");
+// ../common/src/tool-provider.ts
+var factorySlot = singleton("PackagerFactoryProvider");
 // ../insights-sdk/src/errors.ts
 class InsightsHttpError extends Error {
   status;
@@ -4473,7 +4497,7 @@ class InsightsProtocolError extends Error {
 var package_default2 = {
   name: "@uipath/insights-sdk",
   license: "MIT",
-  version: "1.201.0-preview.115",
+  version: "1.201.0-preview.121",
   description: "SDK for the UiPath Insights API — jobs, failures, and performance metrics.",
   repository: {
     type: "git",
@@ -4754,6 +4778,26 @@ async function requestInsightsRoute(config, routeKey, request = {}) {
   }
   return parsed;
 }
+
+// ../insights-sdk/src/alerts.ts
+async function listAlertDefinitions(config, request) {
+  return requestInsightsRoute(config, "alertDefinitionsList", {
+    body: request ?? {}
+  });
+}
+async function listAgenticAlertDefinitions(config, processKey) {
+  return requestInsightsRoute(config, "alertDefinitionsListAgentic", {
+    pathParams: { processKey }
+  });
+}
+async function getAlertDefinition(config, alertDefinitionId) {
+  return requestInsightsRoute(config, "alertDefinitionsGet", {
+    pathParams: { alertDefinitionId }
+  });
+}
+async function checkAlertEntitlement(config) {
+  return requestInsightsRoute(config, "alertDefinitionsCheckEntitlement");
+}
 // ../insights-sdk/src/client.ts
 function buildInsightsUrl(config, path) {
   return `${config.baseUrl}/${config.organizationId}/${config.tenantName}/insightsrtm_/api/v1.0/InsightsJobs${path}`;
@@ -6060,6 +6104,9 @@ var getAuthContext = async (options = {}) => {
     tenantName
   };
 };
+// ../auth/src/tenantSelection.ts
+var IDENTIFIER_STATUSES = new Set([400, 403, 404]);
+
 // ../auth/src/selectTenant.ts
 var TENANT_SELECTION_REQUIRED_CODE = "TENANT_SELECTION_REQUIRED";
 var INVALID_TENANT_CODE = "INVALID_TENANT";
@@ -6162,58 +6209,15 @@ function fail(message, instructions) {
   });
   processContext.exit(1);
 }
-
-// src/utils/filters.ts
-var DEFAULT_LIMIT = 50;
-var FIXED_WINDOW_NOTE = "Results cover resources with Insights activity in the backend's fixed 30-day window that are visible to the current caller.";
-var EMPTY_RESULT_NOTE = "No rows were found in the backend's fixed 30-day activity window for the current caller. That is not proof the resource does not exist.";
-var TRUNCATED_NOTE = "More rows exist beyond this page; page with --offset or raise --limit before concluding a resource is absent.";
-function overPagedNote(total) {
-  return `The requested --offset is past the last row: ${total} rows exist in the backend's fixed 30-day activity window. Lower --offset to see them.`;
-}
-function listInstructions(total, pageLength, hasMore) {
-  if (total === 0) {
-    return EMPTY_RESULT_NOTE;
-  }
-  if (pageLength === 0) {
-    return overPagedNote(total);
-  }
-  return hasMore ? `${FIXED_WINDOW_NOTE} ${TRUNCATED_NOTE}` : FIXED_WINDOW_NOTE;
+function failValidation(message, instructions) {
+  OutputFormatter.error({
+    Result: RESULTS.ValidationError,
+    Message: message,
+    Instructions: instructions
+  });
 }
 
-class FilterContractError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "FilterContractError";
-  }
-}
-function addFilterListOptions(cmd) {
-  return cmd.option("-l, --limit <number>", "Maximum rows to return", parseLimit, DEFAULT_LIMIT).option("-o, --offset <number>", "Rows to skip before returning results", parseOffset);
-}
-function pairFilterRows(input, toRow) {
-  const left = input.left ?? [];
-  const right = input.right ?? [];
-  if (left.length !== right.length) {
-    throw new FilterContractError(`Insights returned misaligned filter arrays: ${input.leftField} has ${left.length} entries but ${input.rightField} has ${right.length}`);
-  }
-  return left.map((value, index) => toRow(value, right[index]));
-}
-function dedupeAndSortRows(rows) {
-  const byKey = new Map;
-  for (const row of rows) {
-    const key = JSON.stringify(row);
-    if (!byKey.has(key)) {
-      byKey.set(key, row);
-    }
-  }
-  return [...byKey.entries()].sort(([a], [b]) => compareRowKeys(a, b)).map(([, row]) => row);
-}
-function compareRowKeys(a, b) {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
+// src/utils/errors.ts
 function isEnvAuthConfigError(error) {
   return error.name === "EnvAuthConfigError";
 }
@@ -6241,25 +6245,56 @@ function writeConfigError(error) {
   OutputFormatter.error({
     Result: RESULTS.AuthenticationError,
     Message: error.message,
-    Instructions: "Run 'uip login' to authenticate first."
+    Instructions: "Run 'uip login' to authenticate first. If the message says a tenant must be selected, run 'uip login tenant set' instead."
   });
   processContext.exit(EXIT_CODES.AuthenticationError);
 }
+async function resolveInsightsConfig() {
+  const [configError, config] = await catchError2(createInsightsConfig());
+  if (configError) {
+    writeConfigError(configError);
+    return null;
+  }
+  return config;
+}
+function ensureFailureExit() {
+  if (!process.exitCode) {
+    processContext.exit(EXIT_CODES.Failure);
+  }
+}
 function httpErrorContext(error) {
   return {
     httpStatus: error.status,
     endpoint: error.endpoint,
-    ...error.requestId ? { requestId: error.requestId } : {},
+    ...error.requestId !== undefined ? { requestId: error.requestId } : {},
     ...error.retryAfterSeconds !== undefined ? { retryAfter: error.retryAfterSeconds } : {}
   };
 }
-function writeFilterError(error) {
+function forbiddenInstructions(family) {
+  return [
+    "Check the active tenant and your Insights access.",
+    ...family.forbiddenExtra === "" ? [] : [family.forbiddenExtra],
+    "Do not retry until access or tenant context changes."
+  ].join(" ");
+}
+function writeInsightsNotFound(error, message, instructions) {
+  OutputFormatter.error({
+    Result: RESULTS.Failure,
+    ErrorCode: "not_found",
+    Retry: "RetryWillNotFix",
+    Message: message,
+    Instructions: instructions,
+    Context: httpErrorContext(error)
+  });
+  processContext.exit(EXIT_CODES.Failure);
+}
+function writeInsightsError(error, family) {
   if (error instanceof InsightsHttpError) {
     const context = httpErrorContext(error);
     if (error.status === 401) {
       OutputFormatter.error({
         Result: RESULTS.AuthenticationError,
-        Message: "The Insights Filter request was not authenticated.",
+        Message: `The Insights ${family.subject} request was not authenticated.`,
         Instructions: "Run 'uip login', select the intended tenant, and try again.",
         Context: context
       });
@@ -6270,8 +6305,8 @@ function writeFilterError(error) {
       OutputFormatter.error({
         Result: RESULTS.Failure,
         ErrorCode: "permission_denied",
-        Message: "You cannot read Insights Filters in the current tenant.",
-        Instructions: "Check the active tenant and your Insights access. Do not retry until access or tenant context changes.",
+        Message: `You cannot read Insights ${family.subject}s in the current tenant.`,
+        Instructions: forbiddenInstructions(family),
         Context: context
       });
       processContext.exit(EXIT_CODES.Failure);
@@ -6281,7 +6316,7 @@ function writeFilterError(error) {
       OutputFormatter.error({
         Result: RESULTS.Failure,
         ErrorCode: "rate_limited",
-        Message: "Insights rate-limited the Filter request.",
+        Message: `Insights rate-limited the ${family.subject} request.`,
         Instructions: error.retryAfterSeconds !== undefined ? `The service reported a rate-limit window of ${error.retryAfterSeconds} seconds. No automatic retry was made.` : "The service rate-limited the request. No automatic retry was made.",
         Retry: "RetryLater",
         Context: context
@@ -6302,29 +6337,42 @@ function writeFilterError(error) {
     writeNetworkFailure(error, describeConnectivityError(error), error.endpoint);
     return;
   }
-  if (error instanceof InsightsProtocolError || error instanceof FilterContractError) {
+  if (error instanceof InsightsProtocolError || family.isContractError(error)) {
     fail(error.message, "Retrying cannot fix a malformed response. Report the endpoint to the Insights owner if it repeats.");
     return;
   }
   fail(error.message, "Check your authentication, tenant, and network, then try again.");
 }
-async function executeFilterList(options, fetchList, toRows, code) {
-  const [configError, config] = await catchError2(createInsightsConfig());
-  if (configError) {
-    writeConfigError(configError);
+
+// src/utils/list-executor.ts
+function truncatedNote(nounPhrase) {
+  return `More rows exist beyond this page; page with --offset or raise --limit before concluding ${nounPhrase} is absent.`;
+}
+function overPagedNote(total, scope = "") {
+  return `The requested --offset is past the last row: ${total} rows exist${scope}. Lower --offset to see them.`;
+}
+function compareRowKeys(a, b) {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+async function executeInsightsList(options, fetchList, spec) {
+  const config = await resolveInsightsConfig();
+  if (config === null) {
     return;
   }
   const [requestError, response] = await catchError2(fetchList(config));
   if (requestError) {
-    writeFilterError(requestError);
+    writeInsightsError(requestError, spec.family);
     return;
   }
-  const [contractError, rawRows] = catchError2(() => toRows(response));
+  const [contractError, projected] = catchError2(() => spec.project(response));
   if (contractError) {
-    writeFilterError(contractError);
+    writeInsightsError(contractError, spec.family);
     return;
   }
-  const rows = dedupeAndSortRows(rawRows);
+  const rows = spec.finalize ? spec.finalize(projected) : projected;
   const offset = options.offset ?? 0;
   const page = rows.slice(offset, offset + options.limit);
   const pagination = new Pagination({
@@ -6335,10 +6383,381 @@ async function executeFilterList(options, fetchList, toRows, code) {
   });
   OutputFormatter.success({
     Result: RESULTS.Success,
-    Code: code,
+    Code: spec.code,
     Data: page,
     Pagination: pagination,
-    Instructions: listInstructions(rows.length, page.length, pagination.HasMore)
+    Instructions: spec.instructions(rows, page, pagination.HasMore)
+  });
+}
+async function executeInsightsGet(fetchOne, spec) {
+  const config = await resolveInsightsConfig();
+  if (config === null) {
+    return;
+  }
+  const [requestError, response] = await catchError2(fetchOne(config));
+  if (requestError) {
+    if (requestError instanceof InsightsHttpError && spec.onHttpError?.(requestError)) {
+      ensureFailureExit();
+      return;
+    }
+    writeInsightsError(requestError, spec.family);
+    return;
+  }
+  const [contractError, data] = catchError2(() => spec.project(response, config));
+  if (contractError) {
+    writeInsightsError(contractError, spec.family);
+    return;
+  }
+  OutputFormatter.success({
+    Result: RESULTS.Success,
+    Code: spec.code,
+    Data: data,
+    Instructions: spec.instructions(data)
+  });
+}
+
+// src/utils/records.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord2(value) ? value : null;
+}
+
+// src/utils/alerts.ts
+class AlertContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AlertContractError";
+  }
+}
+var ALERTS_FAMILY = {
+  subject: "Alert",
+  forbiddenExtra: "A 403 here usually means the caller's Orchestrator folder access could not be resolved rather than an entitlement problem, so check the active tenant and your folder permissions first. 'uip insights alerts check-entitlement' reports entitlement separately.",
+  isContractError: (error) => error instanceof AlertContractError
+};
+var MAX_INT32 = 2147483647;
+function parseRouteId(raw, label) {
+  return parseBoundedInt(raw, label, { min: 1, max: MAX_INT32 });
+}
+function pickScalar(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const kind = typeof value;
+  if (kind === "string" || kind === "number" || kind === "boolean") {
+    return value;
+  }
+  return null;
+}
+var ENGINE_NAMES = { 0: "curated", 1: "query" };
+var SIDE_EFFECT_NOTE = "This command also runs an entitlement and permission check that can bootstrap Insights permissions and queue a warehouse warmup, so it is not a free read.";
+var ENTITLEMENT_SIDE_EFFECT_NOTE = "Running this check can bootstrap Insights permissions and queue a warehouse warmup, so it is not a free read.";
+var ENTITLEMENT_UNKNOWN_CLAUSE = "This result does not show whether the tenant is entitled to Insights alerts.";
+var ENTITLEMENT_FILTER_CLAUSE = "When the tenant is not entitled, the backend silently returns only alerts tied to a process key.";
+var ACTIVE_ONLY_NOTE = "Only active alert definitions are returned.";
+var FOLDER_NAMES_NOTE = "Folder scopes on this command may be folder names, and folders you cannot see appear as N/A. The backend rewrites only the first folder scope it finds, so a second or nested one stays a folder key. A scope covering several folders arrives as one bracketed string rather than one value per folder, so do not count Values to count folders. Use 'alerts get' for folder keys, one value per folder.";
+var FOLDER_KEYS_NOTE = "Folder scopes on this command are folder keys, one value per folder. They are shown as folder names on 'alerts list' without --agentic.";
+var EMPTY_LIST_NOTE = `No alert definitions were returned. ${ENTITLEMENT_UNKNOWN_CLAUSE} ${ENTITLEMENT_FILTER_CLAUSE} Run 'uip insights alerts check-entitlement' before concluding that no alerts exist. ${ACTIVE_ONLY_NOTE}`;
+var EMPTY_AGENTIC_NOTE = "No active alert definitions match this process key in the current tenant. The backend matches the key exactly, so a wrong or mistyped key returns the same empty result as real absence. Inactive alerts and alerts for other process keys are not returned by this route.";
+var ENTITLEMENT_UNCONFIRMED_NOTE = `${ENTITLEMENT_UNKNOWN_CLAUSE} ${ENTITLEMENT_FILTER_CLAUSE} Run 'uip insights alerts check-entitlement' before concluding this list is complete.`;
+var ENGINE_QUERY_EMPTY_FIELDS = "Metric, MetricState, Operator, Threshold, and WindowSeconds do not apply and are null, and Scopes is empty";
+var ENGINE_QUERY_PAGE_NOTE = `One or more alerts on this page are scheduled query alerts. Their condition is a stored query. ConditionVisible says whether a readable form exists, and Condition is present only when it does. ${ENGINE_QUERY_EMPTY_FIELDS}. Use the Insights UI to see or change the query.`;
+var ENGINE_QUERY_ROW_NOTE = `This alert is a scheduled query alert. Its condition is a stored query. ConditionVisible says whether a readable form exists, and Condition is present only when it does. ${ENGINE_QUERY_EMPTY_FIELDS}. Use the Insights UI to see or change the query.`;
+var ENGINE_UNKNOWN_NOTE = "One or more alerts report an alert engine this CLI does not recognize, shown as the raw Engine value. The typed condition fields may not apply to them. Use the Insights UI to see those alerts.";
+var AGENTIC_BASE_NOTE = `Only active alert definitions tied to this process key are returned. ${FOLDER_KEYS_NOTE}`;
+var ENTITLED_TRUE_NOTE = "True means the organization holds the Insights full-mode entitlement and the current caller passed the Insights admin check. While this is true, 'alerts list' and 'alerts get' are not entitlement-filtered, so an earlier partial-result warning from those commands does not apply. They still return only active alert definitions.";
+var ENTITLED_FALSE_NOTE = "False means at least one of three things: the organization has no Insights full-mode entitlement, the caller is not an Insights admin, or the Insights portal service is unreachable in this tenant. The backend does not say which. While this is false, 'alerts list' and 'alerts get' return only alerts tied to a process key. The agentic list is unaffected.";
+var DEFINITION_NOT_FOUND_INSTRUCTIONS = `A 404 can mean the ID does not exist, the alert is inactive, or the alert was filtered out because the tenant is not entitled to Insights alerts. ${ENTITLEMENT_FILTER_CLAUSE} 'uip insights alerts list' applies the same filter, so an ID missing there is not proof it does not exist. Run 'uip insights alerts check-entitlement' first. Both of those commands also run the entitlement and permission check, so neither is a free read.`;
+function parseScopeValues(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (typeof value !== "string") {
+    return (Array.isArray(value) ? value : [value]).map(pickScalar);
+  }
+  const [parseError, parsed] = catchError2(() => JSON.parse(value));
+  if (!parseError && Array.isArray(parsed)) {
+    return parsed.map(pickScalar);
+  }
+  return [pickScalar(value)];
+}
+function collectScopes(raw, out) {
+  const entry = asRecord(raw);
+  if (!entry) {
+    return;
+  }
+  if (Array.isArray(entry.subFilters)) {
+    for (const nested of entry.subFilters) {
+      collectScopes(nested, out);
+    }
+    return;
+  }
+  out.push({
+    field: pickScalar(entry.fieldName),
+    values: parseScopeValues(entry.value)
+  });
+}
+function projectScopes(rawFilter) {
+  const filter = asRecord(rawFilter);
+  const scopes = [];
+  if (filter && Array.isArray(filter.subFilters)) {
+    for (const entry of filter.subFilters) {
+      collectScopes(entry, scopes);
+    }
+  }
+  return scopes;
+}
+function extractCondition(dto) {
+  const queryJson = asRecord(dto.queryJson);
+  const mappings = queryJson && asRecord(queryJson.idToDisplayNameMappings);
+  if (!queryJson || !mappings) {
+    return null;
+  }
+  const metrics = Array.isArray(queryJson.aggregates) ? queryJson.aggregates : [];
+  for (const metric of metrics) {
+    const id = typeof metric === "string" ? metric : asRecord(metric)?.id;
+    if (typeof id !== "string") {
+      continue;
+    }
+    const mapped = mappings[id];
+    if (typeof mapped === "string" && mapped.trim() !== "") {
+      return mapped;
+    }
+  }
+  return null;
+}
+function projectEngine(engine) {
+  if (engine === null) {
+    return null;
+  }
+  return ENGINE_NAMES[engine] ?? engine;
+}
+function projectAlertDefinition(raw) {
+  const dto = asRecord(raw);
+  if (!dto) {
+    throw new AlertContractError("Insights returned an alert definition that is not an object");
+  }
+  const engine = typeof dto.engineType === "number" ? dto.engineType : null;
+  const computation = asRecord(dto.computation);
+  const trigger = asRecord(dto.trigger);
+  const window = asRecord(dto.window);
+  const row = {
+    id: pickScalar(dto.id),
+    name: pickScalar(dto.alertName),
+    severity: pickScalar(dto.severity),
+    isActive: pickScalar(dto.isActive),
+    engine: projectEngine(engine),
+    metric: pickScalar(computation?.computation),
+    metricState: pickScalar(computation?.filterValue),
+    operator: pickScalar(trigger?.type),
+    threshold: pickScalar(trigger?.value),
+    windowSeconds: pickScalar(window?.windowSizeSec),
+    deliveryId: pickScalar(dto.deliveryId),
+    autoSnoozeSeconds: pickScalar(dto.autoSnoozeTimeInterval),
+    snoozedUntil: pickScalar(dto.endDeliveryPauseTime),
+    lastTriggeredAt: pickScalar(dto.lastTriggerTime),
+    processKey: pickScalar(dto.processKey),
+    folderKey: pickScalar(dto.folderKey),
+    projectKey: pickScalar(dto.projectKey),
+    processVersion: pickScalar(dto.processVersion),
+    scopes: projectScopes(dto.filter)
+  };
+  if (engine === 1) {
+    const condition = extractCondition(dto);
+    row.conditionVisible = condition !== null;
+    if (condition !== null) {
+      row.condition = condition;
+    }
+  }
+  return row;
+}
+function projectDefinitionRows(response) {
+  if (!Array.isArray(response)) {
+    throw new AlertContractError("Insights returned an alert definition list that is not an array");
+  }
+  return response.map(projectAlertDefinition);
+}
+function compareDefinitionRows(a, b) {
+  if (typeof a.id === "number" && typeof b.id === "number" && a.id !== b.id) {
+    return a.id - b.id;
+  }
+  return compareRowKeys(JSON.stringify(a), JSON.stringify(b));
+}
+function countCaveats(variant, rows) {
+  const parts = [ACTIVE_ONLY_NOTE];
+  if (variant === "all" && !rows.some((row) => row.processKey === null)) {
+    parts.push(ENTITLEMENT_UNCONFIRMED_NOTE);
+  }
+  return parts;
+}
+function pageDisclosures(variant, rows, page) {
+  const parts = variant === "all" ? [...countCaveats(variant, rows), FOLDER_NAMES_NOTE] : [AGENTIC_BASE_NOTE];
+  if (page.some((row) => row.engine === "query")) {
+    parts.push(ENGINE_QUERY_PAGE_NOTE);
+  }
+  if (page.some((row) => typeof row.engine === "number")) {
+    parts.push(ENGINE_UNKNOWN_NOTE);
+  }
+  return parts;
+}
+function buildListInstructions(variant, rows, page, hasMore) {
+  const parts = [];
+  if (rows.length === 0) {
+    parts.push(variant === "all" ? EMPTY_LIST_NOTE : EMPTY_AGENTIC_NOTE);
+  } else if (page.length === 0) {
+    parts.push(overPagedNote(rows.length), ...countCaveats(variant, rows));
+  } else {
+    parts.push(...pageDisclosures(variant, rows, page));
+    if (hasMore) {
+      parts.push(truncatedNote("an alert"));
+    }
+  }
+  if (variant === "all") {
+    parts.push(SIDE_EFFECT_NOTE);
+  }
+  return parts.join(" ");
+}
+async function executeAlertsList(options, fetchList, variant) {
+  await executeInsightsList(options, fetchList, {
+    code: "InsightsAlertsList",
+    family: ALERTS_FAMILY,
+    project: projectDefinitionRows,
+    finalize: (rows) => [...rows].sort(compareDefinitionRows),
+    instructions: (rows, page, hasMore) => buildListInstructions(variant, rows, page, hasMore)
+  });
+}
+function buildGetInstructions(row) {
+  const parts = [ACTIVE_ONLY_NOTE, FOLDER_KEYS_NOTE];
+  if (row.engine === "query") {
+    parts.push(ENGINE_QUERY_ROW_NOTE);
+  }
+  if (typeof row.engine === "number") {
+    parts.push(ENGINE_UNKNOWN_NOTE);
+  }
+  parts.push(SIDE_EFFECT_NOTE);
+  return parts.join(" ");
+}
+async function executeAlertGet(alertId) {
+  await executeInsightsGet((config) => getAlertDefinition(config, alertId), {
+    code: "InsightsAlertGet",
+    family: ALERTS_FAMILY,
+    project: (response) => projectAlertDefinition(response),
+    instructions: buildGetInstructions,
+    onHttpError: (error) => {
+      if (error.status !== 404) {
+        return false;
+      }
+      writeInsightsNotFound(error, `Alert definition ${alertId} was not found in the current tenant.`, DEFINITION_NOT_FOUND_INSTRUCTIONS);
+      return true;
+    }
+  });
+}
+async function executeCheckEntitlement() {
+  const config = await resolveInsightsConfig();
+  if (config === null) {
+    return;
+  }
+  const [requestError, response] = await catchError2(checkAlertEntitlement(config));
+  if (requestError) {
+    writeInsightsError(requestError, ALERTS_FAMILY);
+    return;
+  }
+  if (typeof response !== "boolean") {
+    writeInsightsError(new AlertContractError("Insights returned an entitlement response that is not a boolean"), ALERTS_FAMILY);
+    return;
+  }
+  OutputFormatter.success({
+    Result: RESULTS.Success,
+    Code: "InsightsAlertEntitlement",
+    Data: { entitled: response },
+    Instructions: `${response ? ENTITLED_TRUE_NOTE : ENTITLED_FALSE_NOTE} ${ENTITLEMENT_SIDE_EFFECT_NOTE}`
+  });
+}
+
+// src/utils/list-options.ts
+var DEFAULT_LIMIT = 50;
+function addListPaginationOptions(cmd) {
+  return cmd.option("-l, --limit <number>", "Maximum rows to return", parseLimit, DEFAULT_LIMIT).option("-o, --offset <number>", "Rows to skip before returning results", parseOffset);
+}
+
+// src/commands/alerts.ts
+function parseAlertId(raw) {
+  return parseRouteId(raw, "<alert-id>");
+}
+function registerAlertsCommand(program2) {
+  const alertsCmd = program2.command("alerts").description("Read UiPath Insights real-time alert definitions");
+  addListPaginationOptions(alertsCmd.command("list").description("List alert definitions visible to the current caller; with --agentic, the definitions for one process key").option("--agentic", "Use the agentic route, scoped to one process key").option("--process-key <key>", "Process key to scope the agentic list to (required with --agentic)")).trackedAction(processContext, async (options) => {
+    if (options.agentic) {
+      const key = options.processKey?.trim() ?? "";
+      if (key === "") {
+        return failValidation("Missing required field: --process-key.", "Pass the Maestro or agent process key you are investigating. Filter discovery does not supply this key.");
+      }
+      return executeAlertsList(options, (config) => listAgenticAlertDefinitions(config, key), "agentic");
+    }
+    if (options.processKey !== undefined) {
+      return failValidation("--process-key requires --agentic.", "Pass both flags to use the agentic route, or neither to list all visible definitions.");
+    }
+    return executeAlertsList(options, (config) => listAlertDefinitions(config, {}), "all");
+  });
+  alertsCmd.command("get").description("Get one alert definition by its integer ID").argument("<alert-id>", "Alert definition ID (integer)", parseAlertId).trackedAction(processContext, async (alertId) => {
+    await executeAlertGet(String(alertId));
+  });
+  alertsCmd.command("check-entitlement").description("Check whether this tenant is confirmed entitled to Insights alerts").trackedAction(processContext, async () => {
+    await executeCheckEntitlement();
+  });
+}
+
+// src/utils/filters.ts
+var FIXED_WINDOW_NOTE = "Results cover resources with Insights activity in the backend's fixed 30-day window that are visible to the current caller.";
+var EMPTY_RESULT_NOTE = "No rows were found in the backend's fixed 30-day activity window for the current caller. That is not proof the resource does not exist.";
+var OVER_PAGED_SCOPE = " in the backend's fixed 30-day activity window";
+function listInstructions(total, pageLength, hasMore) {
+  if (total === 0) {
+    return EMPTY_RESULT_NOTE;
+  }
+  if (pageLength === 0) {
+    return overPagedNote(total, OVER_PAGED_SCOPE);
+  }
+  return hasMore ? `${FIXED_WINDOW_NOTE} ${truncatedNote("a resource")}` : FIXED_WINDOW_NOTE;
+}
+
+class FilterContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FilterContractError";
+  }
+}
+var FILTERS_FAMILY = {
+  subject: "Filter",
+  forbiddenExtra: "",
+  isContractError: (error) => error instanceof FilterContractError
+};
+function pairFilterRows(input, toRow) {
+  const left = input.left ?? [];
+  const right = input.right ?? [];
+  if (left.length !== right.length) {
+    throw new FilterContractError(`Insights returned misaligned filter arrays: ${input.leftField} has ${left.length} entries but ${input.rightField} has ${right.length}`);
+  }
+  return left.map((value, index) => toRow(value, right[index]));
+}
+function dedupeAndSortRows(rows) {
+  const byKey = new Map;
+  for (const row of rows) {
+    const key = JSON.stringify(row);
+    if (!byKey.has(key)) {
+      byKey.set(key, row);
+    }
+  }
+  return [...byKey.entries()].sort(([a], [b]) => compareRowKeys(a, b)).map(([, row]) => row);
+}
+async function executeFilterList(options, fetchList, toRows, code) {
+  await executeInsightsList(options, fetchList, {
+    code,
+    family: FILTERS_FAMILY,
+    project: toRows,
+    finalize: dedupeAndSortRows,
+    instructions: (rows, page, hasMore) => listInstructions(rows.length, page.length, hasMore)
   });
 }
 
@@ -6353,7 +6772,7 @@ function toFolderRows(response) {
 }
 function registerFilterFoldersCommand(program2) {
   const filterFoldersCmd = program2.command("filter-folders").description("Discover folders with recent Insights activity");
-  addFilterListOptions(filterFoldersCmd.command("list").description("List folders with Insights activity in the backend's fixed 30-day window, restricted to folders the current caller can access")).trackedAction(processContext, async (options) => {
+  addListPaginationOptions(filterFoldersCmd.command("list").description("List folders with Insights activity in the backend's fixed 30-day window, restricted to folders the current caller can access")).trackedAction(processContext, async (options) => {
     await executeFilterList(options, listFolderFilters, toFolderRows, "InsightsFilterFoldersList");
   });
 }
@@ -6369,7 +6788,7 @@ function toMachineRows(response) {
 }
 function registerFilterMachinesCommand(program2) {
   const filterMachinesCmd = program2.command("filter-machines").description("Discover machines with recent Insights activity");
-  addFilterListOptions(filterMachinesCmd.command("list").description("List machines with Insights activity in the backend's fixed 30-day window across the current tenant")).trackedAction(processContext, async (options) => {
+  addListPaginationOptions(filterMachinesCmd.command("list").description("List machines with Insights activity in the backend's fixed 30-day window across the current tenant")).trackedAction(processContext, async (options) => {
     await executeFilterList(options, listMachineFilters, toMachineRows, "InsightsFilterMachinesList");
   });
 }
@@ -6385,7 +6804,7 @@ function toProcessRows(response) {
 }
 function registerFilterProcessesCommand(program2) {
   const filterProcessesCmd = program2.command("filter-processes").description("Discover processes with recent Insights activity");
-  addFilterListOptions(filterProcessesCmd.command("list").description("List processes with Insights activity in the backend's fixed 30-day window, restricted to folders the current caller can access")).trackedAction(processContext, async (options) => {
+  addListPaginationOptions(filterProcessesCmd.command("list").description("List processes with Insights activity in the backend's fixed 30-day window, restricted to folders the current caller can access")).trackedAction(processContext, async (options) => {
     await executeFilterList(options, listProcessFilters, toProcessRows, "InsightsFilterProcessesList");
   });
 }
@@ -6401,7 +6820,7 @@ function toQueueRows(response) {
 }
 function registerFilterQueuesCommand(program2) {
   const filterQueuesCmd = program2.command("filter-queues").description("Discover queues with recent Insights activity");
-  addFilterListOptions(filterQueuesCmd.command("list").description("List queues with Insights activity in the backend's fixed 30-day window, restricted to folders the current caller can access")).trackedAction(processContext, async (options) => {
+  addListPaginationOptions(filterQueuesCmd.command("list").description("List queues with Insights activity in the backend's fixed 30-day window, restricted to folders the current caller can access")).trackedAction(processContext, async (options) => {
     await executeFilterList(options, listQueueFilters, toQueueRows, "InsightsFilterQueuesList");
   });
 }
@@ -6524,8 +6943,9 @@ var registerCommands = async (program2) => {
   registerFilterProcessesCommand(program2);
   registerFilterQueuesCommand(program2);
   registerFilterMachinesCommand(program2);
+  registerAlertsCommand(program2);
 };
 
 export { Command, metadata, registerCommands };
 
-//# debugId=329F180A55665A6F64756E2164756E21
+//# debugId=DA3BA706A7E240F164756E2164756E21

package/dist/tool.js

@@ -1,7 +1,7 @@
 import {
   metadata,
   registerCommands
-} from "./tool-vs72q3tv.js";
+} from "./tool-b9c68vwv.js";
 import"./tool-9qecd4wb.js";
 import"./tool-7eva0peq.js";
 import"./tool-5arsyj36.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uipath/insights-tool",
   "license": "MIT",
-  "version": "1.201.0-preview.115",
+  "version": "1.201.0-preview.121",
   "description": "Query UiPath Insights data — jobs, failures, and performance metrics.",
   "private": false,
   "repository": {
@@ -26,5 +26,5 @@
   "files": [
     "dist"
   ],
-  "gitHead": "f1086b73654d7728cb71f280588b3e0c77d535fc"
+  "gitHead": "c70ccfc0b12e637441d67df1d212b71d7784b5f8"
 }