@uipath/common 1.201.0 → 1.202.0-preview.136

package/dist/telemetry/telemetry-service.d.ts

@@ -6,39 +6,6 @@ import type { ITelemetryProvider } from "./telemetry-provider.js";
 export interface TelemetryProperties {
     [key: string]: string | number | boolean | undefined;
 }
-/**
- * Internal property key that carries an active trace context's operation id
- * (mirrors {@link TelemetryContext.operationId}). The AppInsights provider reads
- * it to set the native `operation_Id` tag, falling back to the per-invocation id
- * when no context is present — i.e. for events emitted outside a `trackRequest`
- * scope. The provider consumes and strips it, so it never ships as a dimension.
- *
- * The key lives in the `uip.trace.*` namespace (not the plain `operationId`)
- * so it can never be shadowed by a command argument of the same name.
- * `extractCommandParams` in `trackedAction.ts` now namespaces args under
- * `uip.cmd.arg.*`, but the dedicated trace namespace keeps this control key
- * unambiguous and consistent with the rest of the owner-namespaced schema. The
- * provider consumes and strips it, so the dotted key never ships as a dimension.
- */
-export declare const TELEMETRY_OPERATION_ID_PROPERTY = "uip.trace.operation_id";
-/**
- * Internal routing key carrying an active trace context's parent id (mirrors
- * {@link TelemetryContext.parentId}). The AppInsights provider reads it to set
- * the native `ai.operation.parentId` tag on request/dependency items, so the
- * parent/child tree links in the App Insights UI. Present only inside a nested
- * scope (a top-level `trackRequest` has no parent). Consumed and stripped by
- * the provider — never ships as a dimension.
- */
-export declare const TELEMETRY_PARENT_ID_PROPERTY = "uip.trace.parent_id";
-/**
- * Internal routing key carrying an active trace context's own id (mirrors
- * {@link TelemetryContext.id}). The AppInsights provider uses it as the request/
- * dependency envelope's native item `id`, so child items whose parent id equals
- * it link up; for leaf items (events/exceptions) the provider maps it onto
- * `ai.operation.parentId` so the leaf nests under the current operation.
- * Consumed and stripped by the provider — never ships as a dimension.
- */
-export declare const TELEMETRY_SPAN_ID_PROPERTY = "uip.trace.span_id";
 /**
  * Telemetry correlation context for tracking parent-child relationships
  */
@@ -55,6 +22,25 @@ export interface TelemetryContext {
      * Current operation ID - identifier for this specific operation
      */
     id: string;
+    /**
+     * Wall-clock moment the span began, stamped when the context is created.
+     *
+     * App Insights reads a request's/dependency's timestamp as the span START
+     * and draws the bar forward by `duration`, so this is what decides where a
+     * bar lands. Recorded rather than derived at emit time: a span is tracked
+     * once its work has finished, and anything between the clock stopping and
+     * the emit — `trackedAction` builds and redacts its property bag there —
+     * would otherwise be charged to the front of the bar and push it past
+     * children that started early.
+     *
+     * Every context this service builds opens a {@link startSpanClock} at the
+     * instant the work does, so the start here and the duration reported
+     * alongside it are two views of one clock reading.
+     *
+     * Optional: a context assembled by hand carries no start, and the provider
+     * falls back to deriving one.
+     */
+    startedAt?: Date;
 }
 /**
  * Interface for tracking telemetry events.
@@ -111,10 +97,15 @@ export interface ITelemetryService {
      * @param error - The error to track
      * @param properties - Optional properties to attach to the exception
      *
+     * @param context - The span to hang the exception under. Defaults to
+     * whatever scope is active; pass one explicitly from a caller that runs
+     * after its scope has closed, or the row groups by type but links to no
+     * request.
+     *
      * @remarks
      * If called within a trackRequest block, automatically includes operationId for correlation.
      */
-    trackException(error: Error, properties?: TelemetryProperties): void;
+    trackException(error: Error, properties?: TelemetryProperties, context?: TelemetryContext): void;
     /**
      * Track a request operation (top-level operation in the dependency tree).
      * Use this for main entry point.
@@ -163,6 +154,16 @@ export interface ITelemetryService {
      * it. Returns the function's result.
      */
     runWithContext<T>(context: TelemetryContext, fn: () => Promise<T>): Promise<T>;
+    /**
+     * The context active in the async storage right now, or `undefined` outside
+     * any scope.
+     *
+     * The async storage is the only per-invocation place a context can live, so
+     * a caller that has to tell "this invocation's scope" from "some other
+     * invocation's" asks here rather than reading a process-wide slot — see
+     * `invocation-request.ts`.
+     */
+    getActiveContext(): TelemetryContext | undefined;
     /**
      * Build a dependency context (child of the currently active context) without
      * emitting anything, or `undefined` when there is no active request scope.
@@ -225,7 +226,7 @@ export declare class TelemetryService implements ITelemetryService {
     setProvider(provider: ITelemetryProvider): void;
     setDefaultProperties(properties?: TelemetryProperties): void;
     trackEvent(name: string, properties?: TelemetryProperties): void;
-    trackException(error: Error, properties?: TelemetryProperties): void;
+    trackException(error: Error, properties?: TelemetryProperties, context?: TelemetryContext): void;
     trackRequest<T>(name: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
     trackRequestResult(name: string, durationMs: number, success: boolean, properties?: TelemetryProperties, context?: TelemetryContext): void;
     createRequestContext(): TelemetryContext;
@@ -247,20 +248,49 @@ export declare class TelemetryService implements ITelemetryService {
      * Gets the current telemetry context from the context storage.
      * Returns undefined if no context is available (not within a trackRequest block).
      */
-    private getCurrentContext;
+    getActiveContext(): TelemetryContext | undefined;
+    /**
+     * Where a leaf item (event, exception) sits in the trace.
+     *
+     * A leaf marks an instant, so it has no span id of its own and nothing
+     * points at it: it hangs under whichever span was open when it was emitted,
+     * which is why `parentId` is that span's OWN id rather than the span's
+     * parent. Outside any scope there is no parent, and `operationId` falls
+     * back to the per-invocation id so the item still groups with the rest of
+     * the run.
+     *
+     * A caller that emits after its scope has closed — `trackedAction` ships its
+     * internal-error exception once the invocation scope is gone — passes the
+     * span explicitly, or the item lands with no `parentId` and shows up in
+     * Transaction Search attached to nothing.
+     */
+    private leafCorrelation;
+    /**
+     * Assemble a finished span for a provider.
+     *
+     * Correlation comes off the context as fields on the span, never as keys
+     * inside `properties` — same rule {@link leafCorrelation} follows for
+     * events and exceptions. No tracked item ships a correlation id as a
+     * custom dimension.
+     */
+    private spanFor;
     /**
-     * Enriches properties with the shared base properties, this service's
-     * default properties, and context information (operationId, parentId, id).
+     * Merge the shared base properties, this service's defaults, and the
+     * per-call bag into the custom dimensions an item ships.
      *
      * The global base properties (app version, detected agent, authenticated
      * user/tenant/org) are merged here — at the service level — rather than
-     * inside a specific provider, so EVERY event carries them regardless of
+     * inside a specific provider, so EVERY item carries them regardless of
      * which provider is active (AppInsights, logger fallback, or a tool
      * bundle's early local instance). Precedence, lowest to highest: detected
      * execution context → global base props → per-service defaults →
-     * per-call props → correlation context.
+     * per-call props → the session source.
+     *
+     * Correlation is deliberately absent: it travels on the tracked item
+     * itself ({@link spanFor}, {@link leafCorrelation}), so no id can leak
+     * into a dimension and no provider has to strip one back out.
      */
-    private enrichPropertiesWithContext;
+    private enrichProperties;
     /**
      * Generate a span id for telemetry correlation.
      *

package/dist/telemetry/telemetry-spool.d.ts

@@ -33,6 +33,23 @@ export declare function getTelemetrySpoolDir(): string;
  * Persist pending envelopes for the sidecar. Writes to a `.tmp` name first
  * and renames into place so a concurrently-running sender never claims a
  * half-written file. Returns the spool file path.
+ *
+ * A spool file is written at the default umask, so on a multi-account machine
+ * every other account can read it: 0644 in an 0755 directory, holding whole
+ * telemetry envelopes — session id, install id, the command's arguments, error
+ * messages — for up to {@link MAX_SPOOL_AGE_MS}.
+ *
+ * Narrowing it needs a way to set POSIX bits, and `IFileSystem` deliberately has
+ * none: it is the bottom layer under every package, and permission semantics for
+ * one caller do not belong in its contract. Passing a `mode` through
+ * `mkdir`/`writeFile` would not have been enough on its own either — those apply
+ * it only when the call CREATES the target, and every machine that has ever run
+ * the CLI already has this directory.
+ *
+ * So the exposure is accepted rather than half-closed. Note it is READ only:
+ * 0755 is `rwxr-xr-x`, so another account can read the spool but not write to
+ * it, and planting a file to steer the sender needs write access — see
+ * `isPostableEndpoint` in the drain, which does not rely on these bits.
  */
 export declare function writeTelemetrySpoolFile(payload: TelemetrySpoolPayload): Promise<string>;
 /**

package/dist/timings.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Opt-in per-invocation timing report, switched on with `UIP_TIMINGS=1`.
+ *
+ *   [timing] 'uip or assets list' exit=0 total=1250ms startup=380ms command=863ms http=691ms httpCalls=3 flush=7ms
+ *
+ * Nothing new is measured — the CLI already read every one of these clocks for
+ * telemetry. `startup` (up to the handler), `command` (the handler) and `flush`
+ * (telemetry teardown after it) tile `total` exactly. `http`/`httpCalls` are a
+ * sum inside `command`, not a fourth slice, so parallel calls can push `http`
+ * past `command`.
+ *
+ * State is reached through `Symbol.for()` slots (each tool bundles its own copy
+ * of this package) and bound to the invocation's async context, so the MCP
+ * bridge's concurrent in-process commands can't overwrite each other's numbers.
+ * Where there is no async context to bind to (the browser bundle shims
+ * `node:async_hooks` away), the invocation pins the shared slot instead — that
+ * host runs one command at a time.
+ */
+/** Environment variable that turns the report on (`1` or `true`). */
+export declare const TIMINGS_ENV_VAR = "UIP_TIMINGS";
+/** Prefix every report line carries, so a pipeline can grep them out. */
+export declare const TIMINGS_LINE_PREFIX = "[timing]";
+/**
+ * Declare that this process outlives the invocations it runs, so no invocation
+ * is counted from process start.
+ *
+ * Called by the browser entry point, which runs a command per page action. A
+ * one-shot `uip` says nothing and keeps charging its first (only) invocation
+ * for startup, which is the part the user waited through.
+ */
+export declare function markLongLivedHost(): void;
+/**
+ * Run one CLI invocation with its own timing state and report on the way out.
+ *
+ * Wraps the whole invocation, so paths that give up before a command resolves
+ * (rejected `--output-filter`, `--output`/`--json` conflict) still report.
+ * Callers name the command via {@link setTimingCommand} once parsing resolves
+ * it, and {@link suppressTimingReport} on a path that re-execs elsewhere.
+ * No-op when `UIP_TIMINGS` is unset.
+ */
+export declare function runWithTimings<T>(fallbackCommand: string, fn: () => Promise<T>): Promise<T>;
+/** Only `1` and `true` count, matching how the logger reads `DEBUG`. */
+export declare function timingsEnabled(): boolean;
+/** Name the command being timed, once the parser has resolved it. */
+export declare function setTimingCommand(command: string): void;
+/**
+ * Record this invocation's exit code. Read from here rather than
+ * `process.exitCode`, which a long-lived host shares between commands and
+ * whose own `exit` may throw instead of setting it.
+ */
+export declare function recordExitCode(exitCode: number): void;
+/** Skip this invocation's report — a re-exec child reports the run instead. */
+export declare function suppressTimingReport(): void;
+/**
+ * Wall-clock moment this invocation began — the CLI entry point, before argv is
+ * parsed, tools are resolved and loaded, or a handler is reached.
+ *
+ * The command's telemetry request span is the whole invocation, so this is
+ * where its bar starts. `trackedAction` cannot supply it: by the time a
+ * Commander action runs, startup has already happened and is exactly the part
+ * that used to go unmeasured.
+ *
+ * `baseline` is in `performance.now()` units and `performance.timeOrigin` is
+ * the wall clock at process start, so the two add up to the real start — 0 for
+ * a one-shot CLI, and the invocation's own offset in a long-lived host (the MCP
+ * bridge), where process start is not command start.
+ */
+export declare function invocationStartedAt(): Date;
+/**
+ * How long this invocation has been running, for the request span's duration.
+ * Read at emit time — see {@link invocationStartedAt}.
+ */
+export declare function invocationElapsedMs(): number;
+/** Called by `trackedAction` when the command handler starts. */
+export declare function markCommandStart(): void;
+/** Called by `trackedAction` with the handler's duration. */
+export declare function recordCommandDuration(durationMs: number): void;
+/** Called by the tracked fetch for each outbound call. */
+export declare function recordHttpCall(durationMs: number): void;
+/** Drop everything recorded so far. Intended for tests. */
+export declare function resetTimings(): void;
+/**
+ * Build the report line — every value under a `name=` label, so nothing has to
+ * be read by position. Exported for tests; callers use {@link runWithTimings}.
+ *
+ * The whole split, `http` included, is dropped when no handler ran (`--help`,
+ * `--version`, unknown command, rejected option): there is nothing to
+ * attribute the time to, and a lone `http` from a startup call would imply
+ * otherwise. `exit` and `total` are always present.
+ */
+export declare function formatTimingReport(args: {
+    command: string;
+    exitCode: number;
+    totalMs: number;
+    startupMs?: number;
+    commandMs?: number;
+    httpMs: number;
+    httpCalls: number;
+}): string;

package/dist/trackedAction.d.ts

@@ -21,8 +21,8 @@ export interface CommandContext {
  */
 export declare const TELEMETRY_COMMAND_ARG_PREFIX = "uip.cmd.arg.";
 /**
- * Default CommandContext for tool packages that sets process.exitCode
- * instead of calling process.exit().
+ * Default CommandContext for tool packages: records the exit code and lets the
+ * handler return, instead of calling process.exit().
  *
  * `pollSignal` is resolved from globalThis so it works across bundle
  * boundaries — the CLI sets it once, all tool bundles see the same signal.
@@ -35,6 +35,29 @@ export declare const processContext: CommandContext;
  * Call once at CLI startup after creating the poll abort controller.
  */
 export declare function setProcessContextPollSignal(signal: AbortSignal): void;
+/**
+ * Recorded in place of an argument's value when the value itself is not safe to
+ * collect. That the user passed `--body` at all is the analytics signal; what
+ * was in it never was.
+ */
+export declare const TELEMETRY_ARG_VALUE_WITHHELD = "<provided>";
+/**
+ * Recorded in place of an option's value when the option was never passed and
+ * Commander filled in the command's own default.
+ *
+ * Distinct from {@link TELEMETRY_ARG_VALUE_WITHHELD} because it answers the
+ * opposite question. `<provided>` means the user supplied a value we refuse to
+ * collect; a default means they supplied nothing at all. Reporting both as
+ * `<provided>` made "which options are used, how often" — the whole reason the
+ * dimension exists — unanswerable, since `uip or folders list` with no
+ * arguments still claimed `--limit` and `--offset` were provided.
+ *
+ * The default's own literal is not reported in its place: a default is usually a
+ * constant in our source, but not always (a path derived from the working
+ * directory, a resolved home), and a dimension that is a value most of the time
+ * is worse than one that is never a value.
+ */
+export declare const TELEMETRY_ARG_VALUE_DEFAULTED = "<default>";
 /**
  * Derives a telemetry event name from the command hierarchy.
  * Walks up the parent chain, collects command names, strips the root,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@uipath/common",
     "license": "MIT",
-    "version": "1.201.0",
+    "version": "1.202.0-preview.136",
     "description": "Common infrastructure needed by uip tools.",
     "repository": {
         "type": "git",
@@ -28,6 +28,10 @@
             "types": "./dist/catch-error.d.ts",
             "default": "./dist/catch-error.js"
         },
+        "./entity-name-rules": {
+            "types": "./dist/entity-name-rules.d.ts",
+            "default": "./dist/entity-name-rules.js"
+        },
         "./guid": {
             "types": "./dist/guid.d.ts",
             "default": "./dist/guid.js"
@@ -71,5 +75,5 @@
         "mihaigirleanu",
         "vlad-uipath"
     ],
-    "gitHead": "7933378ad5276ac369900293a1447474dcec6826"
+    "gitHead": "f6270de2c7c04f4c43b2f5187b0c3d3c314c2610"
 }