@uipath/common 1.197.0 → 1.198.0-preview.101

package/dist/interactivity-context.d.ts

@@ -24,6 +24,13 @@ export type InteractivityMode = "never" | "auto" | "always";
 export declare function setInteractivityMode(mode: InteractivityMode): void;
 /** Get the current interactivity mode, defaulting to "auto". */
 export declare function getInteractivityMode(): InteractivityMode;
+/**
+ * Record whether the global `--interactive` flag was explicitly passed on the
+ * command line. Called once at CLI startup, alongside {@link setInteractivityMode}.
+ */
+export declare function setInteractiveFlag(passed: boolean): void;
+/** True when the user explicitly passed `--interactive` (see {@link setInteractiveFlag}). */
+export declare function wasInteractiveFlagPassed(): boolean;
 /**
  * True when the CLI may show an interactive prompt right now.
  *

package/dist/output-format-context.d.ts

@@ -27,6 +27,18 @@ export declare function setOutputFormatExplicit(explicit: boolean): void;
  * Defaults to false (i.e. resolved value is the default).
  */
 export declare function getOutputFormatExplicit(): boolean;
+/**
+ * Record whether the user asked for help explicitly (`-h`/`--help`).
+ * Kept separate from the output format so that the help renderer can force
+ * the table layout without hijacking the format used for error output —
+ * errors always follow the real format (json by default). Set once at CLI
+ * startup.
+ */
+export declare function setHelpRequested(requested: boolean): void;
+/**
+ * True when `-h`/`--help` was passed on the command line. Defaults to false.
+ */
+export declare function getHelpRequested(): boolean;
 /**
  * Set the process-wide output filter expression.
  * Called once at CLI startup after parsing the global --output-filter option.

package/dist/singleton.d.ts

@@ -38,5 +38,5 @@ export interface Singleton<T> {
  *
  * The key is auto-prefixed with `@uipath/common/`.
  */
-export declare function singleton<T>(ctor: abstract new (...args: any[]) => T): Singleton<T>;
+export declare function singleton<T>(ctor: abstract new (...args: never[]) => T): Singleton<T>;
 export declare function singleton<T>(name: string): Singleton<T>;

package/dist/stdin.d.ts

@@ -1 +1,8 @@
 export declare function readStdin(): Promise<string | null>;
+/**
+ * `readStdin()` with a deadline. A non-TTY pipe that stays open but never sends
+ * data (or EOF) would otherwise block forever; on expiry this unrefs stdin so
+ * it can't keep the process alive and resolves `null`. Returns `null` on
+ * timeout, TTY, or empty input.
+ */
+export declare function readStdinWithTimeout(timeoutMs: number): Promise<string | null>;

package/dist/telemetry/index.d.ts

@@ -4,8 +4,8 @@ export { ConsoleTelemetryProvider } from "./console-telemetry-provider.js";
 export type { IContextStorage } from "./context-storage.js";
 export { buildEnvironmentProperties, type NormalizedEnvironment, normalizeBaseUrl, normalizeEnvironment, } from "./environment-info.js";
 export { type CiProvider, detectExecutionContext, EXECUTION_CONTEXT_VALUES, type ExecutionContext, type ExecutionContextDetection, type ExecutionContextDetectionOptions, getExecutionContextTelemetryProperties, setExecutionContextAuthSignal, } from "./execution-context.js";
-export { redactProperties, redactProperty } from "./pii-redactor.js";
+export { redactError, redactProperties, redactProperty, redactValue, } from "./pii-redactor.js";
 export { getConfiguredTelemetrySessionId, getTelemetrySessionId, resolveTelemetrySessionId, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_ID_PROPERTY, } from "./session-id.js";
 export type { ITelemetryProvider } from "./telemetry-provider.js";
 export type { ITelemetryService, TelemetryContext, TelemetryProperties, } from "./telemetry-service.js";
-export { TelemetryService } from "./telemetry-service.js";
+export { TELEMETRY_OPERATION_ID_PROPERTY, TELEMETRY_PARENT_ID_PROPERTY, TELEMETRY_SPAN_ID_PROPERTY, TelemetryService, } from "./telemetry-service.js";

package/dist/telemetry/index.js

@@ -508,8 +508,17 @@ function redactValueDetectors(value) {
   }
   return out;
 }
+function redactValue(value) {
+  return redactValueDetectors(value);
+}
+function redactError(error) {
+  const safe = new Error(redactValueDetectors(error.message ?? ""));
+  safe.name = error.name;
+  safe.stack = typeof error.stack === "string" ? redactValueDetectors(error.stack) : undefined;
+  return safe;
+}
 function nameTokens(name) {
-  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").split(/[\s_-]+/).map((t) => t.toLowerCase()).filter(Boolean);
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").split(/[\s._-]+/).map((t) => t.toLowerCase()).filter(Boolean);
 }
 function isSensitiveName(name) {
   const tokens = nameTokens(name);
@@ -552,11 +561,36 @@ function redactProperties(properties) {
   }
   return out;
 }
+// src/telemetry/trace-context.ts
+var TELEMETRY_TRACEPARENT_ENV = "TRACEPARENT";
+var TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+function getProcessEnv() {
+  return globalThis.process?.env;
+}
+function parseInboundTraceparent(value) {
+  if (!value) {
+    return;
+  }
+  const match = TRACEPARENT_PATTERN.exec(value.trim().toLowerCase());
+  if (!match) {
+    return;
+  }
+  const [, traceId, parentSpanId] = match;
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId)) {
+    return;
+  }
+  return { traceId, parentSpanId };
+}
+function getInboundTraceContext() {
+  return parseInboundTraceparent(getProcessEnv()?.[TELEMETRY_TRACEPARENT_ENV]);
+}
+
 // src/telemetry/session-id.ts
 var TELEMETRY_SESSION_ID_ENV = "UIPATH_SESSION_ID";
 var TELEMETRY_SESSION_ID_PROPERTY = "session_id";
 var telemetrySessionIdSlot = singleton("TelemetrySessionId");
-function getProcessEnv() {
+var telemetryOperationIdSlot = singleton("TelemetryOperationId");
+function getProcessEnv2() {
   return globalThis.process?.env;
 }
 function normalizeSessionId(value) {
@@ -567,7 +601,7 @@ function normalizeSessionId(value) {
   return trimmed || undefined;
 }
 function getConfiguredTelemetrySessionId() {
-  return normalizeSessionId(getProcessEnv()?.[TELEMETRY_SESSION_ID_ENV]);
+  return normalizeSessionId(getProcessEnv2()?.[TELEMETRY_SESSION_ID_ENV]);
 }
 function getTelemetrySessionId() {
   const envSessionId = getConfiguredTelemetrySessionId();
@@ -585,6 +619,16 @@ function getTelemetrySessionId() {
 function resolveTelemetrySessionId(existingSessionId) {
   return getConfiguredTelemetrySessionId() ?? normalizeSessionId(existingSessionId);
 }
+function getTelemetryOperationId() {
+  const existing = telemetryOperationIdSlot.get();
+  if (existing) {
+    return existing;
+  }
+  const inboundTraceId = getInboundTraceContext()?.traceId;
+  const generated = inboundTraceId ?? crypto.randomUUID().replaceAll("-", "");
+  telemetryOperationIdSlot.set(generated);
+  return generated;
+}
 // src/telemetry/global-telemetry-properties.ts
 var telemetryPropsSlot = singleton("TelemetryDefaultProps");
 function getGlobalTelemetryProperties() {
@@ -592,6 +636,10 @@ function getGlobalTelemetryProperties() {
 }
 
 // src/telemetry/telemetry-service.ts
+var TELEMETRY_OPERATION_ID_PROPERTY = "uip.trace.operation_id";
+var TELEMETRY_PARENT_ID_PROPERTY = "uip.trace.parent_id";
+var TELEMETRY_SPAN_ID_PROPERTY = "uip.trace.span_id";
+
 class TelemetryService {
   telemetryProvider;
   contextStorage;
@@ -618,11 +666,15 @@ class TelemetryService {
   trackException(error, properties) {
     const context = this.getCurrentContext();
     const enrichedProperties = this.enrichPropertiesWithContext(properties, context);
-    this.telemetryProvider.trackException(error, enrichedProperties);
+    this.telemetryProvider.trackException(redactError(error), enrichedProperties);
   }
   async trackRequest(name, fn, properties) {
+    const parentContext = this.getCurrentContext();
+    const operationId = parentContext?.operationId ?? this.operationId ?? getTelemetryOperationId();
+    const parentId = parentContext ? parentContext.id : this.inboundParentIdFor(operationId);
     const context = {
-      operationId: this.operationId ?? this.generateId(),
+      operationId,
+      ...parentId !== undefined ? { parentId } : {},
       id: this.generateId()
     };
     const startTime = performance.now();
@@ -640,6 +692,45 @@ class TelemetryService {
       throw error;
     }
   }
+  trackRequestResult(name, durationMs, success, properties, context) {
+    const requestContext = context ?? {
+      operationId: this.operationId ?? getTelemetryOperationId(),
+      id: this.generateId()
+    };
+    const enrichedProperties = this.enrichPropertiesWithContext(properties, requestContext);
+    this.telemetryProvider.trackRequest(name, durationMs, success, enrichedProperties);
+  }
+  createRequestContext() {
+    const operationId = this.operationId ?? getTelemetryOperationId();
+    const parentId = this.inboundParentIdFor(operationId);
+    return {
+      operationId,
+      ...parentId !== undefined ? { parentId } : {},
+      id: this.generateId()
+    };
+  }
+  inboundParentIdFor(operationId) {
+    const inbound = getInboundTraceContext();
+    return inbound && inbound.traceId === operationId ? inbound.parentSpanId : undefined;
+  }
+  runWithContext(context, fn) {
+    return this.contextStorage.run(context, fn);
+  }
+  createDependencyContext() {
+    const parentContext = this.getCurrentContext();
+    if (!parentContext) {
+      return;
+    }
+    return {
+      operationId: parentContext.operationId,
+      parentId: parentContext.id,
+      id: this.generateId()
+    };
+  }
+  trackDependencyResult(name, type, durationMs, success, properties, context, resultCode) {
+    const enrichedProperties = this.enrichPropertiesWithContext(properties, context);
+    this.telemetryProvider.trackDependency(redactValue(name), type, durationMs, success, enrichedProperties, resultCode);
+  }
   async trackDependencyOperation(name, type, fn, properties) {
     const parentContext = this.getCurrentContext();
     if (!parentContext) {
@@ -676,8 +767,12 @@ class TelemetryService {
       ...getExecutionContextTelemetryProperties(),
       ...globalProperties,
       ...this.defaultProperties,
-      ...properties,
-      ...context
+      ...redactProperties(properties ?? {}),
+      ...context ? {
+        [TELEMETRY_OPERATION_ID_PROPERTY]: context.operationId,
+        ...context.parentId !== undefined ? { [TELEMETRY_PARENT_ID_PROPERTY]: context.parentId } : {},
+        [TELEMETRY_SPAN_ID_PROPERTY]: context.id
+      } : {}
     };
     if (sessionId === undefined) {
       delete enriched[TELEMETRY_SESSION_ID_PROPERTY];
@@ -687,14 +782,25 @@ class TelemetryService {
     return enriched;
   }
   generateId() {
-    return crypto.randomUUID().replaceAll("-", "");
+    const bytes = new Uint8Array(8);
+    let hex = "";
+    do {
+      crypto.getRandomValues(bytes);
+      hex = "";
+      for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, "0");
+      }
+    } while (/^0+$/.test(hex));
+    return hex;
   }
 }
 export {
   setExecutionContextAuthSignal,
   resolveTelemetrySessionId,
+  redactValue,
   redactProperty,
   redactProperties,
+  redactError,
   normalizeSkillName,
   normalizeEnvironment,
   normalizeBaseUrl,
@@ -706,11 +812,14 @@ export {
   buildEnvironmentProperties,
   buildCommandTelemetryAttribution,
   TelemetryService,
+  TELEMETRY_SPAN_ID_PROPERTY,
   TELEMETRY_SESSION_ID_PROPERTY,
   TELEMETRY_SESSION_ID_ENV,
+  TELEMETRY_PARENT_ID_PROPERTY,
+  TELEMETRY_OPERATION_ID_PROPERTY,
   EXECUTION_CONTEXT_VALUES,
   ConsoleTelemetryProvider,
   BrowserContextStorage
 };
 
-//# debugId=E6ABC1B31BAE25B864756E2164756E21
+//# debugId=B104F80E6DBFBC9064756E2164756E21

package/dist/telemetry/node-appinsights-telemetry-provider.d.ts

@@ -1,5 +1,5 @@
 import type { ITelemetryProvider } from "./telemetry-provider.js";
-import type { TelemetryProperties } from "./telemetry-service.js";
+import { type TelemetryProperties } from "./telemetry-service.js";
 export { getGlobalTelemetryProperties, setGlobalTelemetryProperties, } from "./global-telemetry-properties.js";
 /**
  * Node.js Application Insights telemetry provider.
@@ -31,10 +31,53 @@ export declare class NodeAppInsightsTelemetryProvider implements ITelemetryProvi
      * Per-call properties take precedence over global defaults.
      */
     private mergeProperties;
+    /**
+     * Read the trace context off the internal `uip.trace.*` routing keys and
+     * strip them, so nothing correlation-related ever ships as a custom
+     * dimension. `merged` is a fresh per-call object, so mutating it in place is
+     * safe; the same reference is what the client call emits as `properties`.
+     *
+     * `operationId` falls back to the per-invocation id when no context is set
+     * (events outside a `trackRequest` scope), so every item in one run still
+     * groups under the same `operation_Id`. `parentId`/`spanId` are only present
+     * inside a scope.
+     */
+    private consumeCorrelation;
+    /**
+     * Promote a `session_id` custom dimension onto the native `ai.session.id`
+     * context tag and strip it from the dimension bag. Session belongs in the
+     * native session tag — the App Insights Sessions blade reads it there — so
+     * shipping it as a custom dimension too is redundant and drifts (the raw
+     * tag vs. a redactor-hashed dimension). Only the AppInsights provider does
+     * this; fallback providers (logger/console) keep `session_id` as a
+     * dimension, since they have no native session field.
+     *
+     * `merged` is a fresh per-call object, so deleting in place is safe.
+     */
+    private promoteSessionTag;
+    /**
+     * Native correlation tags for a LEAF item (event/exception). It has no item
+     * id of its own, so it nests under the current operation: `operation_Id` is
+     * the trace id, and `operation_ParentId` is the enclosing request/
+     * dependency's id (the context's `spanId`), present only inside a scope.
+     *
+     * Cross-service join: `makeTrackedFetch` stamps a W3C `traceparent`
+     * (`00-<operation_Id>-<span>-01`) on every outbound call made inside a
+     * request scope, so the API side can line its telemetry up with this trace.
+     * These native tags are the CLI-side half of that join.
+     */
+    private leafTagOverrides;
+    /**
+     * Native correlation for an OPERATION item (request/dependency). It carries
+     * its own item `id` (the context's `spanId`) so child items can point their
+     * `operation_ParentId` at it, and its own `operation_ParentId` is the
+     * context's `parentId` (absent for a top-level request → a trace root).
+     */
+    private operationCorrelation;
     trackEvent(eventName: string, properties?: TelemetryProperties): Promise<void>;
     trackException(error: Error, properties?: TelemetryProperties): Promise<void>;
     trackRequest(name: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
-    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
+    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties, resultCode?: string): Promise<void>;
     flush(): Promise<void>;
     /**
      * Dispose the Application Insights SDK so its internal channels,

package/dist/telemetry/node.d.ts

@@ -7,4 +7,6 @@ export { NodeContextStorage } from "./node-context-storage.js";
 export { getConfiguredTelemetrySessionId, getTelemetrySessionId, resolveTelemetrySessionId, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_ID_PROPERTY, } from "./session-id.js";
 export type { ITelemetryProvider } from "./telemetry-provider.js";
 export type { ITelemetryService, TelemetryContext, TelemetryProperties, } from "./telemetry-service.js";
-export { TelemetryService } from "./telemetry-service.js";
+export { TELEMETRY_OPERATION_ID_PROPERTY, TELEMETRY_PARENT_ID_PROPERTY, TELEMETRY_SPAN_ID_PROPERTY, TelemetryService, } from "./telemetry-service.js";
+export { getInboundTraceContext, type InboundTraceContext, parseInboundTraceparent, TELEMETRY_TRACEPARENT_ENV, } from "./trace-context.js";
+export { makeTrackedFetch } from "./tracked-fetch.js";

package/dist/telemetry/pii-redactor.d.ts

@@ -15,6 +15,22 @@
  * The goal is defense in depth: even if a new sensitive option slips through
  * without being added to the denylist, value detectors catch common shapes.
  */
+/**
+ * Run the value detectors over a free-form string (no name-based check). Use for
+ * strings that aren't property values but can still carry PII — a telemetry
+ * event/dependency name (`GET /odata/Users/alice@corp.com`) or an exception
+ * message. Emails/UUIDs are hashed, URLs reduced to origin, tokens/JWTs and
+ * user-home paths redacted, over-long strings truncated.
+ */
+export declare function redactValue(value: string): string;
+/**
+ * Return a sanitized copy of an Error whose `message` and `stack` have been run
+ * through the value detectors, so telemetry never ships a raw exception string
+ * (they routinely embed the offending token, URL, path, or id). The original
+ * frames are preserved — only their sensitive substrings are rewritten — and
+ * the `name` is kept so App Insights still groups by exception type.
+ */
+export declare function redactError(error: Error): Error;
 type TelemetryValue = string | number | boolean;
 /**
  * Redact a single telemetry property.

package/dist/telemetry/session-id.d.ts

@@ -10,3 +10,22 @@ export declare function getConfiguredTelemetrySessionId(): string | undefined;
  */
 export declare function getTelemetrySessionId(): string;
 export declare function resolveTelemetrySessionId(existingSessionId: unknown): string | undefined;
+/**
+ * Resolve the per-invocation operation id used for App Insights' native
+ * `operation_Id` tag.
+ *
+ * One CLI process is one invocation, so this is generated once per process and
+ * shared across bundled copies of @uipath/common (the singleton slot lives on
+ * globalThis). It does not take a grouping override the way the session id does:
+ * a coding-agent host sets UIPATH_SESSION_ID to group several CLI runs, but each
+ * run still needs its own operation id so consumers can tell the runs apart. The
+ * one env input it honors is an inbound TRACEPARENT — when the caller passes
+ * trace context, this run adopts that trace id so it lines up with the caller's
+ * transaction and with the API telemetry it triggers.
+ *
+ * The value is a 32-hex string (a UUID with dashes stripped). That is the shape
+ * App Insights expects for `operation_Id`, and — unlike the UUID-shaped session
+ * id — it is left untouched by the PII redactor, so the emitted value matches
+ * raw on every path.
+ */
+export declare function getTelemetryOperationId(): string;

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

@@ -18,8 +18,14 @@ export interface ITelemetryProvider {
     trackRequest(name: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
     /**
      * Track a completed dependency operation with measured duration.
+     *
+     * `resultCode` is the backend-native status of the call (e.g. the HTTP
+     * status code for an outbound request). When omitted the provider derives a
+     * coarse code from `success`. Passing the real code keeps the App Insights
+     * `dependencies.resultCode` column accurate instead of collapsing every
+     * outcome to 200/500.
      */
-    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
+    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties, resultCode?: string): Promise<void>;
     /**
      * Get the current session ID, if available.
      */

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

@@ -6,6 +6,39 @@ 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
  */
@@ -97,6 +130,55 @@ export interface ITelemetryService {
      * All nested trackDependencyOperation calls will be automatically correlated to this request.
      */
     trackRequest<T>(name: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
+    /**
+     * Track a request from already-measured data — no wrapping function.
+     *
+     * Use when the caller measured duration and success itself and just needs
+     * the request emitted (e.g. `trackedAction`, which times the whole command
+     * imperatively). The request becomes a top-level operation: it groups under
+     * the per-invocation `operation_Id` and carries its own span id, so it lands
+     * in the native App Insights `requests` table with `duration`/`success` as
+     * first-class columns instead of stringified custom dimensions.
+     *
+     * @param name The request name (e.g. the command path `uip.solution.pack`)
+     * @param durationMs Measured wall-clock duration in milliseconds
+     * @param success Whether the operation succeeded
+     * @param properties Base properties to include in telemetry
+     */
+    trackRequestResult(name: string, durationMs: number, success: boolean, properties?: TelemetryProperties, context?: TelemetryContext): void;
+    /**
+     * Build a root request context (a trace root: a per-invocation operation
+     * id, its own span id, no parent) without storing or emitting anything.
+     *
+     * For imperative callers that time the work themselves (e.g. `trackedAction`)
+     * but still need child dependencies to nest: create the context once, run the
+     * work inside {@link runWithContext} so dependencies find it, then pass the
+     * same context to {@link trackRequestResult} so the request envelope reuses
+     * this span id and the children's parent id points at it.
+     */
+    createRequestContext(): TelemetryContext;
+    /**
+     * Run `fn` with `context` active in the async context storage, so any
+     * telemetry emitted inside (dependencies, events, exceptions) correlates to
+     * it. Returns the function's result.
+     */
+    runWithContext<T>(context: TelemetryContext, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Build a dependency context (child of the currently active context) without
+     * emitting anything, or `undefined` when there is no active request scope.
+     *
+     * For imperative callers (e.g. the outbound-fetch wrapper) that need the
+     * span id up front — to stamp a `traceparent` header before the call — and
+     * report success/duration afterwards via {@link trackDependencyResult}.
+     */
+    createDependencyContext(): TelemetryContext | undefined;
+    /**
+     * Track a dependency from already-measured data using an explicit context —
+     * no wrapping function. Use when success can't be inferred from "the callback
+     * didn't throw": an outbound HTTP call returning 4xx/5xx resolves normally,
+     * so the caller passes `success = response.ok`.
+     */
+    trackDependencyResult(name: string, type: string, durationMs: number, success: boolean, properties: TelemetryProperties | undefined, context: TelemetryContext, resultCode?: string): void;
     /**
      * Track a dependency operation (child operation in the dependency tree).
      * Use this for operations that are part of a larger request.
@@ -140,6 +222,21 @@ export declare class TelemetryService implements ITelemetryService {
     trackEvent(name: string, properties?: TelemetryProperties): void;
     trackException(error: Error, properties?: TelemetryProperties): 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;
+    /**
+     * The caller's span id to parent a root request under, or `undefined`.
+     *
+     * Only returns a parent when this run actually adopted the inbound trace id
+     * as its `operationId` (the run's `getTelemetryOperationId()` picked up the
+     * `TRACEPARENT` trace id). If a caller pinned a different `operationId` via
+     * `setOperationId`, the inbound parent would reference a span in a different
+     * trace, so it's dropped — correlation must stay internally consistent.
+     */
+    private inboundParentIdFor;
+    runWithContext<T>(context: TelemetryContext, fn: () => Promise<T>): Promise<T>;
+    createDependencyContext(): TelemetryContext | undefined;
+    trackDependencyResult(name: string, type: string, durationMs: number, success: boolean, properties: TelemetryProperties | undefined, context: TelemetryContext, resultCode?: string): void;
     trackDependencyOperation<T>(name: string, type: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
     /**
      * Gets the current telemetry context from the context storage.
@@ -160,7 +257,14 @@ export declare class TelemetryService implements ITelemetryService {
      */
     private enrichPropertiesWithContext;
     /**
-     * Generate a unique ID for telemetry correlation
+     * Generate a span id for telemetry correlation.
+     *
+     * 16 hex chars (8 random bytes) — the W3C trace-context `span-id` width.
+     * The trace id (`operationId`) stays 32 hex (a UUID with dashes stripped,
+     * the W3C `trace-id` width). Keeping the two at their standard widths means
+     * the ids can be emitted verbatim as a `traceparent`
+     * (`00-<32hex traceId>-<16hex spanId>-01`) once the CLI propagates trace
+     * context to the APIs, without a downstream parser rejecting a mis-sized id.
      */
     private generateId;
 }

package/dist/telemetry/trace-context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Inbound W3C Trace Context ingestion.
+ *
+ * The CLI normally starts its own trace: one process = one `operation_Id`, and
+ * the command's request is a trace root with no parent. But when the CLI is run
+ * as one step of a larger distributed operation — a robot, agent, or
+ * orchestrator shelling out to `uip ...` — that caller wants the CLI's whole
+ * telemetry subtree nested under its own span in the App Insights end-to-end
+ * transaction view.
+ *
+ * A process has no inbound HTTP headers, so the caller passes the standard W3C
+ * `traceparent` value in the `TRACEPARENT` environment variable (the same
+ * convention OpenTelemetry CLI tools use). When present and valid, this run
+ * adopts the caller's trace id as its `operation_Id` and points the command
+ * request's `operation_ParentId` at the caller's span id. The outbound-fetch
+ * wrapper then inherits the adopted trace id, so the full chain
+ * (caller → CLI → API) reads as one transaction.
+ */
+/**
+ * Environment variable carrying the inbound W3C `traceparent`
+ * (`00-<trace-id>-<parent-id>-<flags>`). Set by a caller that wants this CLI
+ * run to join its distributed trace.
+ */
+export declare const TELEMETRY_TRACEPARENT_ENV = "TRACEPARENT";
+/**
+ * The parts of an inbound `traceparent` the CLI adopts: the trace id (becomes
+ * this run's `operation_Id`) and the caller's span id (becomes the command
+ * request's parent).
+ */
+export interface InboundTraceContext {
+    /** 32-hex W3C trace-id. */
+    traceId: string;
+    /** 16-hex W3C parent span-id — the caller's span this run nests under. */
+    parentSpanId: string;
+}
+/**
+ * Parse a `traceparent` string into the trace/parent ids the CLI adopts, or
+ * `undefined` when the value is absent or malformed.
+ *
+ * Rejects: the wrong version, wrong id widths, and the W3C-forbidden all-zero
+ * trace-id / parent-id (which signal "no valid id"). A malformed value falls
+ * back to the default root-trace behaviour rather than corrupting correlation.
+ */
+export declare function parseInboundTraceparent(value: string | undefined): InboundTraceContext | undefined;
+/**
+ * Read and parse the inbound trace context from the `TRACEPARENT` environment
+ * variable, or `undefined` when unset/invalid.
+ */
+export declare function getInboundTraceContext(): InboundTraceContext | undefined;

package/dist/telemetry/tracked-fetch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A `fetch`-shaped function. Generic so the wrapper types cleanly against both
+ * the global `fetch` (CLI host) and `node-fetch` (codedapp-tool's uploads),
+ * each keeping its own input/init/response types.
+ */
+type FetchLike = (input: any, init?: any) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/**
+ * Wraps a `fetch` implementation so every outbound call is reported as an App
+ * Insights dependency, nested under the command's request.
+ *
+ * This is the single enforcement point for "every outbound network call is a
+ * dependency": installed over `globalThis.fetch` at CLI startup, it covers all
+ * SDKs and auth without touching their call sites, because they all funnel
+ * through the global `fetch`. codedapp-tool wraps its own `node-fetch` the same
+ * way (see its lint allowlist entry).
+ *
+ * Behaviour:
+ * - Outside a request scope (no active telemetry context) the call passes
+ *   through untracked and unmodified — nothing to correlate to.
+ * - Inside a scope it stamps a W3C `traceparent` header so the server side can
+ *   join the same trace, times the call, and emits a dependency whose success
+ *   reflects `response.ok` (an HTTP 4xx/5xx resolves normally but is not a
+ *   successful dependency).
+ *
+ * Security: the dependency name is `METHOD /path` only — never the query string
+ * (which can carry tokens/PII) and never request headers. The host is recorded
+ * as a plain, non-sensitive dimension.
+ */
+export declare function makeTrackedFetch<F extends FetchLike>(realFetch: F): F;
+export {};

package/dist/trackedAction.d.ts

@@ -5,6 +5,21 @@ export interface CommandContext {
     /** AbortSignal wired to SIGINT/SIGTERM. Pass to `pollUntil({ signal })` for graceful cancellation. */
     pollSignal?: AbortSignal;
 }
+/**
+ * Namespace prefix for a command's own invocation arguments in telemetry.
+ *
+ * Command args and options are user-supplied and carry arbitrary names, so they
+ * are the one part of the property bag whose keys we don't control. Emitting
+ * them bare at the root of the event lets an arg named like a reserved
+ * dimension (`operationId`, `duration`, `success`, …) shadow that dimension —
+ * e.g. `uip oms organizations operation get <operationId>` overwriting the
+ * correlation tag. Prefixing every extracted arg with a dedicated namespace
+ * (mirrors OpenTelemetry attribute-namespacing) walls them off: a user arg can
+ * only ever land under `uip.cmd.arg.*`, never at the root where system and
+ * control keys live. System dimensions stay bare — they're a closed, controlled
+ * set, like OTel's semantic-convention keys.
+ */
+export declare const TELEMETRY_COMMAND_ARG_PREFIX = "uip.cmd.arg.";
 /**
  * Default CommandContext for tool packages that sets process.exitCode
  * instead of calling process.exit().