@uipath/common 1.1.0 → 1.195.0

package/dist/error-handler.d.ts

@@ -11,6 +11,14 @@ export interface ErrorDetails {
     details: string;
     /** Machine-readable context for agents (HTTP status, request ID, retry-after, etc.) */
     context?: ErrorContext;
+    /**
+     * Per-field validation errors lifted from an ASP.NET ProblemDetails body
+     * (application/problem+json). Shape: `{ fieldName: ["msg", ...] }`.
+     * Surfaced as `Errors` on the OutputFormatter envelope so agents can
+     * react to the specific field that failed validation instead of parsing
+     * the free-text Message.
+     */
+    parsedErrors?: Record<string, string[]>;
 }
 /**
  * Options for customising error extraction behaviour.

package/dist/formatter.d.ts

@@ -80,6 +80,14 @@ export declare class FailureOutput {
     Instructions: string;
     Context?: ErrorContext;
     Log?: string;
+    /**
+     * Optional structured payload for failure envelopes that need to carry
+     * actionable detail beyond the Message string (e.g. JobKey + JobState
+     * + SubState for the `jobs start --wait-for-completion` failure path).
+     * Mirrors SuccessOutput.Data so consumers can use a single accessor
+     * across success / failure paths.
+     */
+    Data?: DataRecord | DataRecord[];
     constructor(result: FailureResultType, message: string, instructions: string, context?: ErrorContext);
 }
 export type StructuredOutput = SuccessOutput | FailureOutput;
@@ -97,11 +105,47 @@ export type StructuredOutput = SuccessOutput | FailureOutput;
  * closed-box guarantee must additionally wrap {@link applyFilter}.
  */
 export declare function validateOutputFilter(filter: string): Error | null;
+/**
+ * Thrown when a `--output-filter` expression parses successfully but fails at
+ * evaluation time (e.g. type-coercion errors when functions receive unexpected
+ * types). Carries `instructions` and `result` so {@link trackedAction} can
+ * surface filter-specific guidance through the failure envelope instead of the
+ * generic "unexpected error" fallback.
+ *
+ * Uses a duck-type `__brand` rather than relying on `instanceof`, because each
+ * tool bundles its own copy of `@uipath/common` and class identity differs
+ * across bundle boundaries.
+ */
+export declare class FilterEvaluationError extends Error {
+    readonly __brand: "FilterEvaluationError";
+    readonly filter: string;
+    readonly instructions: string;
+    readonly result: FailureResultType;
+    constructor(filter: string, cause: unknown);
+}
 /**
  * OutputFormatter namespace for formatting and displaying output.
  */
 export declare namespace OutputFormatter {
-    function success(data: SuccessOutput): void;
+    /**
+     * Emit a success envelope.
+     *
+     * By default every key in `data.Data` is normalized to PascalCase for
+     * cross-command output consistency (see {@link normalizeDataKeys}).
+     *
+     * Pass `{ preserveDataKeys: true }` when the `Data` payload is content that
+     * is copied verbatim back into a UiPath artifact and whose key casing is
+     * therefore load-bearing — most notably `registry get` node definitions,
+     * whose camelCase field names (`inputDefinition`, `inputString`, …) are
+     * pasted straight into `.flow` files. PascalCasing those names produces a
+     * flow that passes `flow validate` but faults at runtime (the agent/job
+     * receives `InputString` while its schema requires `inputString`). With
+     * this flag the `Data` payload keeps its original casing; the envelope
+     * keys (`Result`/`Code`/`Data`/`Log`/…) are still PascalCased.
+     */
+    function success(data: SuccessOutput, options?: {
+        preserveDataKeys?: boolean;
+    }): void;
     /**
      * Format and display an error, then set {@link process.exitCode} to the
      * value from {@link EXIT_CODES} for `data.Result` (falls back to 1).

package/dist/index.browser.js

@@ -3387,10 +3387,15 @@ async function extractErrorDetails(error, options) {
   }
   if (parsedBody?.errorCode && typeof parsedBody.errorCode === "string") {
     context.errorCode = parsedBody.errorCode;
+  } else if (parsedBody?.code && typeof parsedBody.code === "string") {
+    context.errorCode = parsedBody.code;
   }
   if (parsedBody?.requestId && typeof parsedBody.requestId === "string") {
     context.requestId = parsedBody.requestId;
   }
+  if (parsedBody?.traceId && typeof parsedBody.traceId === "string") {
+    context.traceId = parsedBody.traceId;
+  }
   if (status === 429) {
     const resp = response;
     const headersObj = resp?.headers;
@@ -3410,7 +3415,35 @@ async function extractErrorDetails(error, options) {
     }
   }
   const hasContext = Object.keys(context).length > 0;
-  return { result, message, details, ...hasContext ? { context } : {} };
+  let parsedErrors;
+  if (parsedBody?.errors && typeof parsedBody.errors === "object") {
+    const errors = {};
+    for (const [field, raw] of Object.entries(parsedBody.errors)) {
+      if (Array.isArray(raw)) {
+        const messages = raw.map((entry) => {
+          if (typeof entry === "string")
+            return entry;
+          if (entry && typeof entry === "object" && typeof entry.message === "string") {
+            return entry.message;
+          }
+          return String(entry);
+        }).filter(Boolean);
+        if (messages.length > 0)
+          errors[field] = messages;
+      } else if (typeof raw === "string") {
+        errors[field] = [raw];
+      }
+    }
+    if (Object.keys(errors).length > 0)
+      parsedErrors = errors;
+  }
+  return {
+    result,
+    message,
+    details,
+    ...hasContext ? { context } : {},
+    ...parsedErrors ? { parsedErrors } : {}
+  };
 }
 async function extractErrorMessage(error, options) {
   const { message } = await extractErrorDetails(error, options);
@@ -5314,6 +5347,28 @@ var BACKOFF_DEFAULTS = {
 };
 var MIN_INTERVAL_MS = 100;
 
+// src/polling/poll-failure-mapping.ts
+var REASON_BY_OUTCOME = {
+  [PollOutcome.Timeout]: "poll_timeout",
+  [PollOutcome.Failed]: "poll_failed",
+  [PollOutcome.Interrupted]: "poll_failed",
+  [PollOutcome.Aborted]: "poll_aborted"
+};
+function mapPollFailure(pollResult, label) {
+  const outcome = pollResult.outcome;
+  const errMsg = pollResult.error?.message ?? "too many consecutive errors";
+  const messageByOutcome = {
+    [PollOutcome.Timeout]: `${label} polling timed out`,
+    [PollOutcome.Failed]: `${label} polling failed: ${errMsg}`,
+    [PollOutcome.Interrupted]: `${label} polling was interrupted`,
+    [PollOutcome.Aborted]: `${label} polling was aborted`
+  };
+  return {
+    reason: REASON_BY_OUTCOME[outcome],
+    message: messageByOutcome[outcome],
+    exitCode: outcome === PollOutcome.Timeout ? 2 : 1
+  };
+}
 // src/polling/poll-until.ts
 function resolveIntervalFn(options) {
   if (typeof options.intervalMs === "function") {
@@ -5766,6 +5821,7 @@ export {
   parseLimit,
   parseBoundedInt,
   msToDuration,
+  mapPollFailure,
   logger,
   isTerminalStatus,
   isSuccessStatus,

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from "./output-sink";
 export * from "./polling";
 export * from "./registry";
 export * from "./screen-logger";
+export * from "./sdk-user-agent";
 export * from "./singleton";
 export * from "./telemetry/node.js";
 export { setGlobalTelemetryProperties } from "./telemetry/node-appinsights-telemetry-provider.js";

package/dist/index.js

@@ -2126,6 +2126,7 @@ var require_commander = __commonJS((exports) => {
 });
 
 // ../filesystem/src/node.ts
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import * as fs6 from "node:fs/promises";
 import * as os2 from "node:os";
@@ -2742,6 +2743,13 @@ defineLazyProperty(apps, "safari", () => detectPlatformBinary({
 var open_default = open;
 
 // ../filesystem/src/node.ts
+var LOCK_HEARTBEAT_MS = 5000;
+var LOCK_STALE_MS = 15000;
+var LOCK_MAX_WAIT_MS = 20000;
+var LOCK_MAX_HOLD_MS = 60000;
+var LOCK_RETRY_MIN_MS = 100;
+var LOCK_RETRY_JITTER_MS = 200;
+
 class NodeFileSystem {
   path = {
     join: path2.join,
@@ -2818,6 +2826,90 @@ class NodeFileSystem {
   async mkdir(dirPath) {
     await fs6.mkdir(dirPath, { recursive: true });
   }
+  async acquireLock(lockPath) {
+    const canonicalPath = await this.canonicalizeLockTarget(lockPath);
+    const lockFile = `${canonicalPath}.lock`;
+    const ownerId = randomUUID();
+    const start = Date.now();
+    while (true) {
+      try {
+        await fs6.writeFile(lockFile, ownerId, { flag: "wx" });
+        return this.createLockRelease(lockFile, ownerId);
+      } catch (error) {
+        if (!this.hasErrnoCode(error, "EEXIST")) {
+          throw error;
+        }
+        const stats = await fs6.stat(lockFile).catch(() => null);
+        if (stats && Date.now() - stats.mtimeMs > LOCK_STALE_MS) {
+          const reclaimed = await fs6.rm(lockFile, { force: true }).then(() => true).catch(() => false);
+          if (reclaimed)
+            continue;
+        }
+        if (Date.now() - start > LOCK_MAX_WAIT_MS) {
+          throw new Error(`ELOCKED: timed out waiting for lock on ${canonicalPath}`);
+        }
+        await new Promise((resolve2) => setTimeout(resolve2, LOCK_RETRY_MIN_MS + Math.random() * LOCK_RETRY_JITTER_MS));
+      }
+    }
+  }
+  async canonicalizeLockTarget(lockPath) {
+    const absolute = path2.resolve(lockPath);
+    const fullReal = await fs6.realpath(absolute).catch(() => null);
+    if (fullReal)
+      return fullReal;
+    const parent = path2.dirname(absolute);
+    const base = path2.basename(absolute);
+    const canonicalParent = await fs6.realpath(parent).catch(() => parent);
+    return path2.join(canonicalParent, base);
+  }
+  createLockRelease(lockFile, ownerId) {
+    const heartbeatStart = Date.now();
+    let heartbeatTimer;
+    let stopped = false;
+    const stopHeartbeat = () => {
+      stopped = true;
+      if (heartbeatTimer)
+        clearTimeout(heartbeatTimer);
+    };
+    const scheduleNextHeartbeat = () => {
+      if (stopped)
+        return;
+      if (Date.now() - heartbeatStart >= LOCK_MAX_HOLD_MS) {
+        stopped = true;
+        return;
+      }
+      heartbeatTimer = setTimeout(() => {
+        runHeartbeat();
+      }, LOCK_HEARTBEAT_MS);
+      heartbeatTimer.unref?.();
+    };
+    const runHeartbeat = async () => {
+      if (stopped)
+        return;
+      const current = await fs6.readFile(lockFile, "utf-8").catch(() => null);
+      if (stopped)
+        return;
+      if (current !== ownerId) {
+        stopped = true;
+        return;
+      }
+      const now = Date.now() / 1000;
+      await fs6.utimes(lockFile, now, now).catch(() => {});
+      scheduleNextHeartbeat();
+    };
+    scheduleNextHeartbeat();
+    let released = false;
+    return async () => {
+      if (released)
+        return;
+      released = true;
+      stopHeartbeat();
+      const current = await fs6.readFile(lockFile, "utf-8").catch(() => null);
+      if (current === ownerId) {
+        await fs6.rm(lockFile, { force: true });
+      }
+    };
+  }
   async rm(filePath) {
     await fs6.rm(filePath, { recursive: true, force: true });
   }
@@ -2863,7 +2955,10 @@ class NodeFileSystem {
     }
   }
   isEnoent(error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+    return this.hasErrnoCode(error, "ENOENT");
+  }
+  hasErrnoCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
   }
 }
 
@@ -3005,10 +3100,15 @@ async function extractErrorDetails(error, options) {
   }
   if (parsedBody?.errorCode && typeof parsedBody.errorCode === "string") {
     context.errorCode = parsedBody.errorCode;
+  } else if (parsedBody?.code && typeof parsedBody.code === "string") {
+    context.errorCode = parsedBody.code;
   }
   if (parsedBody?.requestId && typeof parsedBody.requestId === "string") {
     context.requestId = parsedBody.requestId;
   }
+  if (parsedBody?.traceId && typeof parsedBody.traceId === "string") {
+    context.traceId = parsedBody.traceId;
+  }
   if (status === 429) {
     const resp = response;
     const headersObj = resp?.headers;
@@ -3028,7 +3128,35 @@ async function extractErrorDetails(error, options) {
     }
   }
   const hasContext = Object.keys(context).length > 0;
-  return { result, message, details, ...hasContext ? { context } : {} };
+  let parsedErrors;
+  if (parsedBody?.errors && typeof parsedBody.errors === "object") {
+    const errors = {};
+    for (const [field, raw] of Object.entries(parsedBody.errors)) {
+      if (Array.isArray(raw)) {
+        const messages = raw.map((entry) => {
+          if (typeof entry === "string")
+            return entry;
+          if (entry && typeof entry === "object" && typeof entry.message === "string") {
+            return entry.message;
+          }
+          return String(entry);
+        }).filter(Boolean);
+        if (messages.length > 0)
+          errors[field] = messages;
+      } else if (typeof raw === "string") {
+        errors[field] = [raw];
+      }
+    }
+    if (Object.keys(errors).length > 0)
+      parsedErrors = errors;
+  }
+  return {
+    result,
+    message,
+    details,
+    ...hasContext ? { context } : {},
+    ...parsedErrors ? { parsedErrors } : {}
+  };
 }
 async function extractErrorMessage(error, options) {
   const { message } = await extractErrorDetails(error, options);
@@ -8943,6 +9071,7 @@ class FailureOutput {
   Instructions;
   Context;
   Log;
+  Data;
   constructor(result, message, instructions, context) {
     this.Result = result;
     this.Message = message;
@@ -8965,6 +9094,60 @@ function escapeNonAscii(jsonText) {
 function needsAsciiSafeJson(sink) {
   return process.platform === "win32" && !sink.capabilities.isInteractive;
 }
+function isPlainRecord(value) {
+  if (value === null || typeof value !== "object")
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function toLowerCamelCaseKey(key) {
+  if (!key)
+    return key;
+  if (/[_\-\s]/.test(key)) {
+    const [firstPart, ...restParts] = key.split(/[_\-\s]+/).filter(Boolean);
+    if (!firstPart)
+      return key;
+    return [
+      toLowerCamelCaseSimpleKey(firstPart),
+      ...restParts.map((part) => {
+        const normalized = toLowerCamelCaseSimpleKey(part);
+        return normalized.charAt(0).toUpperCase() + normalized.slice(1);
+      })
+    ].join("");
+  }
+  return toLowerCamelCaseSimpleKey(key);
+}
+function toLowerCamelCaseSimpleKey(key) {
+  if (/^[A-Z0-9]+$/.test(key))
+    return key.toLowerCase();
+  return key.replace(/^[A-Z]+(?=[A-Z][a-z]|\d|$)|^[A-Z]/, (match) => match.toLowerCase());
+}
+function toPascalCaseKey(key) {
+  const lowerCamelKey = toLowerCamelCaseKey(key);
+  return lowerCamelKey ? lowerCamelKey.charAt(0).toUpperCase() + lowerCamelKey.slice(1) : lowerCamelKey;
+}
+function toPascalCaseData(value) {
+  if (Array.isArray(value))
+    return value.map(toPascalCaseData);
+  if (!isPlainRecord(value))
+    return value;
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    result[toPascalCaseKey(key)] = toPascalCaseData(nestedValue);
+  }
+  return result;
+}
+function normalizeDataKeys(data) {
+  return toPascalCaseData(data);
+}
+function normalizeOutputKeys(data) {
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    const pascalKey = toPascalCaseKey(key);
+    result[pascalKey] = pascalKey === "Data" ? value : toPascalCaseData(value);
+  }
+  return result;
+}
 function printOutput(data, format2 = "json", logFn, asciiSafe = false) {
   if (!data) {
     logFn("Empty response object. No data to display.");
@@ -9027,7 +9210,7 @@ function wrapText(text, width) {
 function printTable(data, logFn, externalLogValue) {
   if (data.length === 0)
     return;
-  const keys = Object.keys(data[0]).filter((key) => key !== "Code" && key !== "Log");
+  const keys = Object.keys(data[0]).filter((key) => !["code", "log"].includes(key.toLowerCase()));
   const maxWidths = keys.map((key) => Math.max(key.length, ...data.map((item) => cellToString(item[key]).length)));
   const header = keys.map((key, i2) => key.padEnd(maxWidths[i2])).join(" | ");
   logFn(header);
@@ -9042,7 +9225,7 @@ function printTable(data, logFn, externalLogValue) {
   }
 }
 function printVerticalTable(data, logFn = console.log, externalLogValue) {
-  const keys = Object.keys(data).filter((key) => key !== "Code" && key !== "Log");
+  const keys = Object.keys(data).filter((key) => !["code", "log"].includes(key.toLowerCase()));
   if (keys.length === 0)
     return;
   const maxKeyWidth = Math.max(...keys.map((key) => key.length));
@@ -9058,7 +9241,7 @@ function printVerticalTable(data, logFn = console.log, externalLogValue) {
 function printResizableTable(data, logFn = console.log, externalLogValue) {
   if (data.length === 0)
     return;
-  const keys = Object.keys(data[0]).filter((key) => key !== "Code" && key !== "Log");
+  const keys = Object.keys(data[0]).filter((key) => !["code", "log"].includes(key.toLowerCase()));
   if (keys.length === 0)
     return;
   if (!process.stdout.isTTY) {
@@ -9142,8 +9325,27 @@ function validateOutputFilter(filter) {
     return err instanceof Error ? err : new Error(String(err));
   }
 }
+
+class FilterEvaluationError extends Error {
+  __brand = "FilterEvaluationError";
+  filter;
+  instructions;
+  result = RESULTS.ValidationError;
+  constructor(filter, cause) {
+    const underlying = cause instanceof Error ? cause.message : String(cause);
+    super(`Filter '${filter}' failed to evaluate: ${underlying}`);
+    this.name = "FilterEvaluationError";
+    this.filter = filter;
+    this.instructions = `The --output-filter expression '${filter}' failed at evaluation time. ` + "Note that --output-filter operates on the 'Data' field of the envelope, not the full object. " + "For example, on a list result use 'length(@)' instead of 'Data | length(@)'.";
+  }
+}
 function applyFilter(data, filter) {
-  const result = search(data, filter);
+  let result;
+  try {
+    result = search(data, filter);
+  } catch (err) {
+    throw new FilterEvaluationError(filter, err);
+  }
   if (result == null)
     return [];
   if (Array.isArray(result)) {
@@ -9160,13 +9362,18 @@ function applyFilter(data, filter) {
 }
 var OutputFormatter;
 ((OutputFormatter) => {
-  function success(data) {
+  function success(data, options) {
     data.Log ??= getLogFilePath() || undefined;
+    const normalize = !options?.preserveDataKeys;
+    if (normalize) {
+      data.Data = normalizeDataKeys(data.Data);
+    }
     const filter = getOutputFilter();
     if (filter) {
-      data.Data = applyFilter(data.Data, filter);
+      const filtered = applyFilter(data.Data, filter);
+      data.Data = normalize ? normalizeDataKeys(filtered) : filtered;
     }
-    logOutput(data, getOutputFormat());
+    logOutput(normalizeOutputKeys(data), getOutputFormat());
   }
   OutputFormatter.success = success;
   function error(data) {
@@ -9176,7 +9383,7 @@ var OutputFormatter;
       result: data.Result,
       message: data.Message
     });
-    logOutput(data, getOutputFormat());
+    logOutput(normalizeOutputKeys(data), getOutputFormat());
   }
   OutputFormatter.error = error;
   function emitList(code, items, opts) {
@@ -9197,13 +9404,14 @@ var OutputFormatter;
   function log(data) {
     const format2 = getOutputFormat();
     const sink = getOutputSink();
+    const normalized = toPascalCaseData(data);
     if (format2 === "json") {
-      const json2 = JSON.stringify(data);
+      const json2 = JSON.stringify(normalized);
       const safe = needsAsciiSafeJson(sink) ? escapeNonAscii(json2) : json2;
       sink.writeErr(`${safe}
 `);
     } else {
-      for (const [key, value] of Object.entries(data)) {
+      for (const [key, value] of Object.entries(normalized)) {
         sink.writeErr(`${key}: ${value}
 `);
       }
@@ -9212,12 +9420,16 @@ var OutputFormatter;
   OutputFormatter.log = log;
   function formatToString(data) {
     const filter = getOutputFilter();
-    if (filter && "Data" in data && data.Data != null) {
-      data.Data = applyFilter(data.Data, filter);
+    if ("Data" in data && data.Data != null) {
+      data.Data = normalizeDataKeys(data.Data);
+      if (filter) {
+        data.Data = normalizeDataKeys(applyFilter(data.Data, filter));
+      }
     }
+    const output = normalizeOutputKeys(data);
     const lines = [];
     const sink = getOutputSink();
-    printOutput(data, getOutputFormat(), (msg) => {
+    printOutput(output, getOutputFormat(), (msg) => {
       lines.push(msg);
     }, needsAsciiSafeJson(sink));
     return lines.join(`
@@ -10828,6 +11040,28 @@ var BACKOFF_DEFAULTS = {
 };
 var MIN_INTERVAL_MS = 100;
 
+// src/polling/poll-failure-mapping.ts
+var REASON_BY_OUTCOME = {
+  [PollOutcome.Timeout]: "poll_timeout",
+  [PollOutcome.Failed]: "poll_failed",
+  [PollOutcome.Interrupted]: "poll_failed",
+  [PollOutcome.Aborted]: "poll_aborted"
+};
+function mapPollFailure(pollResult, label) {
+  const outcome = pollResult.outcome;
+  const errMsg = pollResult.error?.message ?? "too many consecutive errors";
+  const messageByOutcome = {
+    [PollOutcome.Timeout]: `${label} polling timed out`,
+    [PollOutcome.Failed]: `${label} polling failed: ${errMsg}`,
+    [PollOutcome.Interrupted]: `${label} polling was interrupted`,
+    [PollOutcome.Aborted]: `${label} polling was aborted`
+  };
+  return {
+    reason: REASON_BY_OUTCOME[outcome],
+    message: messageByOutcome[outcome],
+    exitCode: outcome === PollOutcome.Timeout ? 2 : 1
+  };
+}
 // src/polling/poll-until.ts
 function resolveIntervalFn(options) {
   if (typeof options.intervalMs === "function") {
@@ -11244,6 +11478,112 @@ var ScreenLogger;
   }
   ScreenLogger.progress = progress;
 })(ScreenLogger ||= {});
+// src/sdk-user-agent.ts
+var USER_AGENT_HEADER = "User-Agent";
+var sdkUserAgentHostToken = singleton("SdkUserAgentHostToken");
+function userAgentPatchKey(userAgent) {
+  return Symbol.for(`@uipath/common/sdk-user-agent/${userAgent}`);
+}
+function splitUserAgentTokens(value) {
+  return value?.trim().split(/\s+/).filter(Boolean) ?? [];
+}
+function appendUserAgentToken(value, userAgent) {
+  const tokens = splitUserAgentTokens(value);
+  const seen = new Set(tokens);
+  for (const token of splitUserAgentTokens(userAgent)) {
+    if (!seen.has(token)) {
+      tokens.push(token);
+      seen.add(token);
+    }
+  }
+  return tokens.join(" ");
+}
+function getEffectiveUserAgent(userAgent) {
+  return appendUserAgentToken(sdkUserAgentHostToken.get(), userAgent);
+}
+function isHeadersLike(headers) {
+  return typeof headers === "object" && headers !== null && "get" in headers && typeof headers.get === "function" && "set" in headers && typeof headers.set === "function";
+}
+function getSdkUserAgentToken(pkg) {
+  const packageName = pkg.name.replace(/^@uipath\//, "");
+  return getEffectiveUserAgent(`${packageName}/${pkg.version}`);
+}
+function setSdkUserAgentHostToken(token) {
+  if (token === undefined) {
+    sdkUserAgentHostToken.clear();
+    return;
+  }
+  sdkUserAgentHostToken.set(token);
+}
+function addSdkUserAgentHeader(headers, userAgent) {
+  const result = { ...headers ?? {} };
+  const effectiveUserAgent = getEffectiveUserAgent(userAgent);
+  const headerName = Object.keys(result).find((key) => key.toLowerCase() === USER_AGENT_HEADER.toLowerCase());
+  if (headerName) {
+    result[headerName] = appendUserAgentToken(result[headerName], effectiveUserAgent);
+  } else {
+    result[USER_AGENT_HEADER] = effectiveUserAgent;
+  }
+  return result;
+}
+function withSdkUserAgentHeader(headers, userAgent) {
+  const effectiveUserAgent = getEffectiveUserAgent(userAgent);
+  if (isHeadersLike(headers)) {
+    headers.set(USER_AGENT_HEADER, appendUserAgentToken(headers.get(USER_AGENT_HEADER), effectiveUserAgent));
+    return headers;
+  }
+  if (Array.isArray(headers)) {
+    const result = headers.map((entry) => {
+      const [key, value] = entry;
+      return [key, value];
+    });
+    const headerIndex = result.findIndex(([key]) => key.toLowerCase() === USER_AGENT_HEADER.toLowerCase());
+    if (headerIndex >= 0) {
+      const [key, value] = result[headerIndex];
+      result[headerIndex] = [
+        key,
+        appendUserAgentToken(value, effectiveUserAgent)
+      ];
+    } else {
+      result.push([USER_AGENT_HEADER, effectiveUserAgent]);
+    }
+    return result;
+  }
+  return addSdkUserAgentHeader(typeof headers === "object" && headers !== null ? { ...headers } : {}, effectiveUserAgent);
+}
+function withUserAgentInitOverride(initOverrides, userAgent) {
+  return async (requestContext) => {
+    const initWithUserAgent = {
+      ...requestContext.init,
+      headers: withSdkUserAgentHeader(requestContext.init.headers, userAgent)
+    };
+    const override = typeof initOverrides === "function" ? await initOverrides({
+      ...requestContext,
+      init: initWithUserAgent
+    }) : initOverrides;
+    return {
+      ...override ?? {},
+      headers: withSdkUserAgentHeader(override?.headers ?? initWithUserAgent.headers, userAgent)
+    };
+  };
+}
+function installSdkUserAgentHeader(BaseApiClass, userAgent) {
+  const prototype = BaseApiClass.prototype;
+  const patchKey = userAgentPatchKey(userAgent);
+  if (prototype[patchKey]) {
+    return;
+  }
+  if (typeof prototype.request !== "function") {
+    throw new Error("Generated BaseAPI request function not found.");
+  }
+  const originalRequest = prototype.request;
+  prototype.request = function requestWithUserAgent(context, initOverrides) {
+    return originalRequest.call(this, context, withUserAgentInitOverride(initOverrides, userAgent));
+  };
+  Object.defineProperty(prototype, patchKey, {
+    value: true
+  });
+}
 // src/tool-provider.ts
 var factorySlot = singleton("PackagerFactoryProvider");
 function setPackagerFactoryProvider(provider) {
@@ -11439,13 +11779,17 @@ Command.prototype.trackedAction = function(context, fn, properties) {
     const [error] = await catchError(fn(...args));
     if (error) {
       errorMessage = error instanceof Error ? error.message : String(error);
-      logger.error(`[trackedAction] ${telemetryName} failed: ${errorMessage}`);
+      logger.debug(`[trackedAction] ${telemetryName} failed: ${errorMessage}`);
+      const typed = error;
+      const customInstructions = typeof typed.instructions === "string" ? typed.instructions : undefined;
+      const customResult = typeof typed.result === "string" && typed.result !== RESULTS.Success && Object.values(RESULTS).includes(typed.result) ? typed.result : undefined;
+      const finalResult = customResult ?? RESULTS.Failure;
       OutputFormatter.error({
-        Result: RESULTS.Failure,
+        Result: finalResult,
         Message: errorMessage,
-        Instructions: "An unexpected error occurred. Run with --log-level debug for details."
+        Instructions: customInstructions ?? "An unexpected error occurred. Run with --log-level debug for details."
       });
-      context.exit(1);
+      context.exit(EXIT_CODES[finalResult]);
     }
     const durationMs = performance.now() - startTime;
     const success = !error && (process.exitCode === undefined || process.exitCode === 0);
@@ -11459,6 +11803,7 @@ Command.prototype.trackedAction = function(context, fn, properties) {
   });
 };
 export {
+  withSdkUserAgentHeader,
   withCompleter,
   warnDeprecatedTenantOption,
   warnDeprecatedOptionAlias,
@@ -11467,6 +11812,7 @@ export {
   telemetryFlushAndShutdown,
   telemetry,
   singleton,
+  setSdkUserAgentHostToken,
   setProcessContextPollSignal,
   setPackagerFactoryProvider,
   setOutputFormatExplicit,
@@ -11491,6 +11837,7 @@ export {
   parseBoundedInt,
   parseAttachmentSpec,
   msToDuration,
+  mapPollFailure,
   logger,
   isTerminalStatus,
   isTelemetryDisabled,
@@ -11499,7 +11846,9 @@ export {
   isGuid,
   isFailureStatus,
   instructionsFor,
+  installSdkUserAgentHeader,
   installConsoleGuard,
+  getSdkUserAgentToken,
   getOutputSink,
   getOutputFormatExplicit,
   getOutputFormat,
@@ -11528,6 +11877,7 @@ export {
   buildActionCenterTaskUrl,
   buildActionCenterInboxUrl,
   appendOption,
+  addSdkUserAgentHeader,
   addHiddenDeprecatedTenantOption,
   UIPATH_HOME_DIR,
   TelemetryService,
@@ -11542,6 +11892,7 @@ export {
   MIN_INTERVAL_MS,
   LogLevel,
   JsonPathError,
+  FilterEvaluationError,
   FailureOutput,
   ErrorDecision,
   EXIT_CODES,

package/dist/orchestrator-urls.d.ts

@@ -19,8 +19,7 @@
  *
  * The `path` argument on {@link buildOrchestratorUrl} is left as a string
  * **without** automatic encoding so callers can include OData filter syntax
- * and existing URL-encoded query strings; this matches the existing inline
- * pattern used in `solution-tool/src/services/apps-binding-sync.ts`.
+ * and existing URL-encoded query strings.
  *
  * For the Studio Web URL pattern (`/{org}/studio_/...`) — which has no
  * tenant segment by design — see `packages/maestro-sdk` instead. That

package/dist/polling/index.d.ts

@@ -1,5 +1,7 @@
 export { createPollAbortController } from "./abort-controller";
 export { msToDuration } from "./format-utils";
+export type { PollFailureMapped, PollFailureReason, } from "./poll-failure-mapping";
+export { mapPollFailure } from "./poll-failure-mapping";
 export { pollUntil } from "./poll-until";
 export { isFailureStatus, isSuccessStatus, isTerminalStatus, } from "./terminal-statuses";
 export type { BackoffConfig, OnErrorCallback, PollContext, PollUntilOptions, PollUntilResult, } from "./types";

package/dist/polling/poll-failure-mapping.d.ts

@@ -0,0 +1,21 @@
+import { PollOutcome } from "./types";
+/** Canonical taxonomy for poll-loop failures; library callers branch on this without parsing the message. */
+export type PollFailureReason = "poll_timeout" | "poll_failed" | "poll_aborted";
+export interface PollFailureMapped {
+    reason: PollFailureReason;
+    /** `${label} polling {timed out | failed: <err> | was interrupted | was aborted}`. */
+    message: string;
+    /** `2` for Timeout, `1` otherwise. */
+    exitCode: number;
+}
+/**
+ * Maps a non-completed `pollUntil` result to `{ reason, message, exitCode }`.
+ * `label` prefixes the message (e.g. `"Deployment"` → `"Deployment polling timed out"`).
+ * Caller must check the outcome is non-completed before invoking.
+ */
+export declare function mapPollFailure(pollResult: {
+    outcome: PollOutcome;
+    error?: {
+        message?: string;
+    };
+}, label: string): PollFailureMapped;

package/package.json

@@ -1,50 +1,45 @@
 {
-    "name": "@uipath/common",
-    "version": "1.1.0",
-    "description": "Common infrastructure needed by uip tools.",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/UiPath/cli.git",
-        "directory": "packages/common"
+  "name": "@uipath/common",
+  "license": "MIT",
+  "version": "1.195.0",
+  "description": "Common infrastructure needed by uip tools.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/UiPath/cli.git",
+    "directory": "packages/common"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/index.browser.d.ts",
+        "default": "./dist/index.browser.js"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     },
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org/"
+    "./sdk-user-agent": {
+      "types": "./dist/sdk-user-agent.d.ts",
+      "default": "./dist/sdk-user-agent.js"
     },
-    "type": "module",
-    "main": "./dist/index.js",
-    "exports": {
-        ".": {
-            "browser": {
-                "types": "./dist/index.browser.d.ts",
-                "default": "./dist/index.browser.js"
-            },
-            "default": {
-                "types": "./dist/index.d.ts",
-                "default": "./dist/index.js"
-            }
-        },
-        "./telemetry": {
-            "types": "./dist/telemetry/index.d.ts",
-            "default": "./dist/telemetry/index.js"
-        }
-    },
-    "files": [
-        "dist"
-    ],
-    "maintainers": [
-        "aoltean16",
-        "mihaigirleanu",
-        "vlad-uipath"
-    ],
-    "devDependencies": {
-        "@jmespath-community/jmespath": "^1.3.0",
-        "@types/js-yaml": "^4.0.9",
-        "@types/node": "^25.5.2",
-        "@uipath/filesystem": "1.1.0",
-        "commander": "^14.0.3",
-        "js-yaml": "^4.1.0",
-        "jsonpath-plus": "^10.4.0",
-        "typescript": "^6.0.2"
-    },
-    "gitHead": "06e8c8f566df4b87da4a008635483c62f64f33f0"
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "default": "./dist/telemetry/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "maintainers": [
+    "aoltean16",
+    "mihaigirleanu",
+    "vlad-uipath"
+  ],
+  "gitHead": "65fabb84552758b2710d8ca68470e70a9b1d19bc"
 }