@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/integration-capability-id.ts

@@ -0,0 +1,16 @@
+/**
+ * Agents recommend a deployment's reviewed integration definition (Outlook
+ * Mail, OneDrive, ...) with this capability id prefix; the rest is the
+ * definition id, which is also its Connect provider id.
+ */
+export const INTEGRATION_DEFINITION_CAPABILITY_PREFIX = "api:integration:";
+
+export function integrationDefinitionCapabilityId(definitionId: string): string {
+  return `${INTEGRATION_DEFINITION_CAPABILITY_PREFIX}${definitionId}`;
+}
+
+export function integrationDefinitionIdFromCapabilityId(capabilityId: string): string | null {
+  return capabilityId.startsWith(INTEGRATION_DEFINITION_CAPABILITY_PREFIX)
+    ? capabilityId.slice(INTEGRATION_DEFINITION_CAPABILITY_PREFIX.length) || null
+    : null;
+}

package/src/interaction-action-deadline.ts

@@ -0,0 +1,143 @@
+import type {
+  BrowserAction,
+  BrowserActionBatch,
+  BrowserLocator,
+  ComputerAction,
+  ComputerActionBatch,
+} from "./interaction";
+
+/**
+ * Declared bounds of the waits a controller runs inside one action. The
+ * controllers use these exact values, and every layer that carries an action
+ * request (the API's request to the controller, the connected-machine runner,
+ * the runner's reply timer) derives its deadline from them, so a batch that
+ * stays within its own declared waits is never cut off by a transport timer.
+ */
+
+/** A browser locator waits this long for its element to appear or enable. */
+export const BROWSER_LOCATOR_WAIT_MS = 10_000;
+/** An explicit browser wait without timeoutMs, the document-ready wait after a
+ * navigation or history step, and an upload's file-chooser wait. */
+export const BROWSER_DEFAULT_WAIT_MS = 30_000;
+/** A navigation waits this long for its server to answer before it stops. */
+export const BROWSER_NAVIGATION_COMMIT_TIMEOUT_MS = 20_000;
+/** After page input, a navigation the input started is waited for this long
+ * to show its new document. */
+export const BROWSER_ACTION_NAVIGATION_SETTLE_MS = 10_000;
+/** After page input, requests the input started are waited for this long. */
+export const BROWSER_ACTION_REQUEST_SETTLE_MS = 1_500;
+/** After page input, finite animations are waited for this long. */
+export const BROWSER_ANIMATION_SETTLE_MS = 750;
+/** A named (non-ref) computer locator waits this long to appear and enable. */
+export const COMPUTER_LOCATOR_WAIT_MS = 10_000;
+
+/** No action request gets less than the transport's historical default, so a
+ * single action keeps exactly the budget it always had. */
+export const INTERACTION_ACTION_DEADLINE_FLOOR_MS = 60_000;
+/** Fixed allowance per request for reading the target before the actions and
+ * observing it for the receipt, which run once per request whatever its length. */
+export const INTERACTION_ACTION_DEADLINE_MARGIN_MS = 30_000;
+/** The longest any controller request may run. */
+export const INTERACTION_ACTION_DEADLINE_MAX_MS = 20 * 60_000;
+
+/** Input dispatch and round trips of one browser action beyond its waits. */
+const BROWSER_ACTION_DISPATCH_MS = 2_000;
+/** One settle pass after page input: a navigation the input started, the
+ * requests it started (plus the response's apply and round trips), and
+ * finite animations within their one-second evaluation budget. */
+const BROWSER_SETTLE_PASS_MS =
+  BROWSER_ACTION_NAVIGATION_SETTLE_MS +
+  BROWSER_ACTION_REQUEST_SETTLE_MS +
+  250 +
+  BROWSER_ANIMATION_SETTLE_MS +
+  1_000;
+/** The settle after a request's last action (or after a failure): one pass,
+ * then one frame for late-starting requests and a second pass for those. */
+export const BROWSER_ACTION_SETTLE_MAX_MS = 2 * BROWSER_SETTLE_PASS_MS + 1_000;
+/** Input dispatch of one computer action plus its bounded settle. */
+const COMPUTER_ACTION_DISPATCH_MS = 8_000;
+/** A launched application's first window may take this long to appear. */
+const COMPUTER_LAUNCH_WAIT_MS = 30_000;
+
+/** The longest one browser action's own waits can take. */
+export function browserActionMaxWaitMs(action: BrowserAction): number {
+  const locators = (...values: (BrowserLocator | undefined)[]) =>
+    values.filter((value) => value !== undefined).length * BROWSER_LOCATOR_WAIT_MS;
+  const waits = (() => {
+    switch (action.type) {
+      case "navigate":
+        return BROWSER_NAVIGATION_COMMIT_TIMEOUT_MS + BROWSER_DEFAULT_WAIT_MS;
+      case "history":
+        return BROWSER_DEFAULT_WAIT_MS;
+      case "wait":
+        return (action.timeoutMs ?? BROWSER_DEFAULT_WAIT_MS) + locators(action.locator);
+      case "upload":
+        return locators(action.locator) + BROWSER_DEFAULT_WAIT_MS;
+      case "drag":
+        return locators(action.from, action.to);
+      case "click":
+      case "double_click":
+      case "hover":
+      case "fill":
+      case "select":
+      case "check":
+      case "type":
+      case "press":
+      case "scroll":
+      case "clipboard":
+        return locators(action.locator);
+      case "activate":
+      case "viewport":
+      case "viewport_reset":
+      case "pointer":
+      case "handle_dialog":
+      case "permission":
+        return 0;
+    }
+  })();
+  return waits + BROWSER_ACTION_DISPATCH_MS;
+}
+
+/** The longest one computer action's own waits can take. */
+export function computerActionMaxWaitMs(action: ComputerAction): number {
+  switch (action.type) {
+    case "semantic":
+      return (
+        (action.locator.kind === "ref" ? 0 : COMPUTER_LOCATOR_WAIT_MS) + COMPUTER_ACTION_DISPATCH_MS
+      );
+    case "launch":
+      return COMPUTER_LAUNCH_WAIT_MS + COMPUTER_ACTION_DISPATCH_MS;
+    case "keyboard":
+    case "pointer":
+    case "clipboard":
+    case "focus":
+      return COMPUTER_ACTION_DISPATCH_MS;
+  }
+}
+
+function boundedDeadline(waitsMs: number): number {
+  return Math.min(
+    INTERACTION_ACTION_DEADLINE_MAX_MS,
+    Math.max(INTERACTION_ACTION_DEADLINE_FLOOR_MS, waitsMs + INTERACTION_ACTION_DEADLINE_MARGIN_MS),
+  );
+}
+
+/**
+ * The request deadline for one browser action or batch: the sum of each
+ * action's declared maximum wait, the settle after the last action, and a
+ * fixed margin, never below the historical single-request default and never
+ * above the controller maximum.
+ */
+export function browserActionDeadlineMs(action: BrowserAction | BrowserActionBatch): number {
+  const actions = action.type === "batch" ? action.actions : [action];
+  return boundedDeadline(
+    actions.reduce((sum, item) => sum + browserActionMaxWaitMs(item), 0) +
+      BROWSER_ACTION_SETTLE_MAX_MS,
+  );
+}
+
+/** The request deadline for one computer action or batch; see browserActionDeadlineMs. */
+export function computerActionDeadlineMs(action: ComputerAction | ComputerActionBatch): number {
+  const actions: readonly ComputerAction[] = action.type === "batch" ? action.actions : [action];
+  return boundedDeadline(actions.reduce((sum, item) => sum + computerActionMaxWaitMs(item), 0));
+}

package/src/interaction-driver-diagnostic.ts

@@ -0,0 +1,89 @@
+/**
+ * Operator-only context for an interaction driver failure (`driver_failed`):
+ * which error class failed and in which function. The controller sends it
+ * beside, never inside, the interaction error, so it reaches server logs
+ * without changing what a caller or model is shown. Both are code names, never
+ * message text.
+ */
+export type InteractionDriverDiagnostic = {
+  errorClass: string;
+  /** The innermost named function on the failing stack, when there is one. */
+  frame?: string;
+};
+
+export const INTERACTION_DRIVER_DIAGNOSTIC_MESSAGE_MAX_CHARS = 200;
+const ERROR_CLASS = /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/;
+const FRAME = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$<][A-Za-z0-9_$<>]*){0,3}$/;
+const STACK_FRAME = /^\s+at\s+(?:async\s+)?(?:new\s+)?([^\s(]+)\s+\(/u;
+const REDACTED = "[redacted]";
+
+/** A code identifier, or null for anything that could carry data. */
+export function interactionDriverErrorClass(value: unknown): string | null {
+  return typeof value === "string" && ERROR_CLASS.test(value) ? value : null;
+}
+
+/**
+ * A driver-written error message for logs. Such messages are code templates
+ * whose variable parts (window titles, page text, paths, URLs, a driver's own
+ * free-text reason) are quoted or follow a colon, so this keeps the template
+ * head and redacts those parts. Not for arbitrary exception text.
+ */
+export function redactInteractionDriverMessage(message: string): string {
+  const colon = message.search(/:\s/u);
+  const head = colon < 0 ? message : message.slice(0, colon);
+  const redacted = head
+    .replace(/"[^"]*"?|'[^']*'?|`[^`]*`?|“[^”]*”?|‘[^’]*’?|«[^»]*»?/gu, REDACTED)
+    .replace(/\b[a-z][a-z0-9+.-]*:\/\/\S*/giu, REDACTED)
+    .replace(/\S*@\S+/gu, REDACTED)
+    .replace(/(?:^|\s)(?:~|\.{1,2})?[/\\]\S*/gu, ` ${REDACTED}`)
+    .replace(/\b[A-Za-z]:[/\\]\S*/gu, REDACTED)
+    .replace(/[^\x20-\x7e]+/gu, REDACTED)
+    .replace(/\s+/gu, " ")
+    .trim();
+  const tail = colon < 0 ? "" : `: ${REDACTED}`;
+  const bounded = `${redacted || REDACTED}${tail}`;
+  return bounded.length <= INTERACTION_DRIVER_DIAGNOSTIC_MESSAGE_MAX_CHARS
+    ? bounded
+    : `${bounded.slice(0, INTERACTION_DRIVER_DIAGNOSTIC_MESSAGE_MAX_CHARS - 3)}...`;
+}
+
+/** A function name as code, or null for anything else. */
+export function interactionDriverFrame(value: unknown): string | null {
+  return typeof value === "string" && value.length <= 128 && FRAME.test(value) ? value : null;
+}
+
+/** The diagnostic for a thrown value; reads only its name and stack frames. */
+export function interactionDriverDiagnostic(error: unknown): InteractionDriverDiagnostic {
+  if (!(error instanceof Error)) return { errorClass: "NonError" };
+  let name: unknown;
+  let stack: unknown;
+  try {
+    name = error.name !== "Error" ? error.name : error.constructor?.name;
+    stack = error.stack;
+  } catch {
+    /* Untrusted errors contribute only what could be read. */
+  }
+  let frame: string | null = null;
+  if (typeof stack === "string") {
+    for (const line of stack.slice(0, 16_384).split("\n")) {
+      frame = interactionDriverFrame(STACK_FRAME.exec(line)?.[1]);
+      if (frame) break;
+    }
+  }
+  return {
+    errorClass: interactionDriverErrorClass(name) ?? "Error",
+    ...(frame ? { frame } : {}),
+  };
+}
+
+/** Validates a diagnostic received from another process. */
+export function parseInteractionDriverDiagnostic(
+  value: unknown,
+): InteractionDriverDiagnostic | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const errorClass = interactionDriverErrorClass(record.errorClass);
+  if (errorClass === null) return null;
+  const frame = interactionDriverFrame(record.frame);
+  return { errorClass, ...(frame ? { frame } : {}) };
+}