@uipath/common 1.199.0-preview.97 → 1.200.0-preview.109

package/dist/packager-tool-import.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Import a tool's `packager-tool` entry point and run its registration.
+ *
+ * Its own module so tests can stand in for it. The real entry points are
+ * multi-megabyte tool bundles; loading one takes seconds and blocks the event
+ * loop while it evaluates, which is far too slow for a unit test.
+ */
+/** Named export every in-repo `packager-tool` entry point must provide. */
+export declare const REGISTER_EXPORT = "registerPackagerFactories";
+/** Shape of a `packager-tool` entry point's module namespace. */
+export interface PackagerToolModule {
+    [REGISTER_EXPORT]?: () => void;
+}
+/**
+ * Import `specifier` and call its `registerPackagerFactories` export. Returns
+ * the failure instead of throwing so the caller can decide what to say.
+ *
+ * Registration is a call, not an import side effect, so a run that reaches
+ * the same factories through two tool bundles registers them once — from the
+ * one caller that is about to pack.
+ *
+ * Tools published before that change register at import and ship no export.
+ * They still work: the import above already registered them, so treat a
+ * missing export as a legacy entry point instead of a failure. Tools that live
+ * in this repo must export it — `scripts/lint-packager-tool-exports.ts` fails
+ * the build if one doesn't.
+ */
+export declare function importPackagerTool(specifier: string): Promise<Error | undefined>;

package/dist/polling/terminal-statuses.d.ts

@@ -20,7 +20,7 @@
  * isTerminalStatus("FAULTED")    // true
  * ```
  */
-export declare function isTerminalStatus(status: string): boolean;
+export declare function isTerminalStatus(status: string | null | undefined): boolean;
 /**
  * Check if a status string represents a failure state (case-insensitive).
  *
@@ -34,7 +34,7 @@ export declare function isTerminalStatus(status: string): boolean;
  * isFailureStatus("Cancelled")  // true
  * ```
  */
-export declare function isFailureStatus(status: string): boolean;
+export declare function isFailureStatus(status: string | null | undefined): boolean;
 /**
  * Check if a status string represents a successful terminal state (case-insensitive).
  *
@@ -47,4 +47,4 @@ export declare function isFailureStatus(status: string): boolean;
  * isSuccessStatus("Running")    // false
  * ```
  */
-export declare function isSuccessStatus(status: string): boolean;
+export declare function isSuccessStatus(status: string | null | undefined): boolean;

package/dist/solution-project-artifacts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared `ensureProjectArtifacts` used by every `*-tool init` path (agent,
+ * case, codedapp, flow, maestro). Lives here so the five tools don't each
+ * carry a copy; each tool re-exports it from its own
+ * `src/services/project-artifacts.ts` shim (the browser-build
+ * `excludedImports` stub mechanism resolves only relative paths under each
+ * tool's own src tree).
+ */
+/** Options forwarded to solution-tool's `addProjectArtifactsToSolutionAsync`. */
+export interface EnsureProjectArtifactsArgs {
+    /** Absolute path to the solution directory (containing the `.uipx`). */
+    solutionDir: string;
+    /** Stable project key — must match the `Id` in `.uipx` `Projects[]`. */
+    projectId: string;
+    /** Display name for the project; typically the project folder name. */
+    projectName: string;
+    /** Project type as written to `project.uiproj` (e.g. `Flow`, `Agent`). */
+    projectType: string;
+    /** Optional SDK subType (AppV2: `"Coded"` / `"CodedAction"`). */
+    projectSubType?: string;
+}
+/**
+ * Result envelope. Structurally identical to `ProjectArtifactsResult` in
+ * `@uipath/solution-sdk/resources` — declared here too because this
+ * package sits below `solution-sdk` in the dependency graph and cannot import
+ * from it.
+ */
+export interface ProjectArtifactsResult {
+    /** True when artifact resources were generated. */
+    Created: boolean;
+    /** Error message when `Created` is `false`. */
+    Error?: string;
+}
+/**
+ * Generate the `resources/solution_folder/...` artifact-resource entries for
+ * a project that has just been registered in its parent solution's `.uipx`.
+ *
+ * The implementation is resolved at runtime from the installed
+ * `@uipath/solution-tool` (through the CLI host's tool-module provider, which
+ * installs it on demand), so the multi-megabyte resource-builder chain is
+ * never bundled into the calling tool.
+ */
+export declare function ensureProjectArtifacts(args: EnsureProjectArtifactsArgs): Promise<ProjectArtifactsResult>;

package/dist/telemetry/index.d.ts

@@ -5,7 +5,7 @@ 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 { 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 { getConfiguredTelemetrySessionId, getTelemetrySessionId, getTelemetrySessionSource, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_SOURCE_PROPERTY, } from "./session-id.js";
 export type { ITelemetryProvider } from "./telemetry-provider.js";
 export type { ITelemetryService, TelemetryContext, TelemetryProperties, } 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

@@ -86,7 +86,7 @@ var COMMAND_ATTRIBUTION = commandAttribution([
   ["agents", "build", ["uip.codedagent", "uip.agent"]],
   ["agenthub", "build", ["uip.agenthub"]],
   ["coded-apps", "build", ["uip.codedapp"]],
-  ["functions", "build", ["uip.functions"]],
+  ["functions", "build", ["uip.function", "uip.functions"]],
   ["solution", "build", ["uip.solution"]],
   ["maestro", "build", ["uip.maestro", "uip.case", "uip.flow"]],
   ["llm-observability", "troubleshoot", ["uip.traces"]],
@@ -588,8 +588,18 @@ function getInboundTraceContext() {
 
 // src/telemetry/session-id.ts
 var TELEMETRY_SESSION_ID_ENV = "UIPATH_SESSION_ID";
-var TELEMETRY_SESSION_ID_PROPERTY = "session_id";
-var telemetrySessionIdSlot = singleton("TelemetrySessionId");
+var SESSION_ID_MAX_LENGTH = 64;
+var RANDOM_SESSION_ID_LENGTH = 32;
+var TELEMETRY_SESSION_SOURCE_PROPERTY = "session_id_source";
+var CONTROL_CHARACTERS = /\p{Cc}/gu;
+var INHERITED_SESSION_SOURCES = [
+  { envVar: "CLAUDE_CODE_SESSION_ID", source: "claude-code" },
+  { envVar: "CODEX_THREAD_ID", source: "codex" },
+  { envVar: "ANTIGRAVITY_TRAJECTORY_ID", source: "antigravity" },
+  { envVar: "TERM_SESSION_ID", source: "terminal" },
+  { envVar: "WT_SESSION", source: "terminal" }
+];
+var telemetrySessionSlot = singleton("TelemetrySession");
 var telemetryOperationIdSlot = singleton("TelemetryOperationId");
 function getProcessEnv2() {
   return globalThis.process?.env;
@@ -598,27 +608,45 @@ function normalizeSessionId(value) {
   if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
     return;
   }
-  const trimmed = String(value).trim();
-  return trimmed || undefined;
+  const cleaned = String(value).replace(CONTROL_CHARACTERS, "").trim().slice(0, SESSION_ID_MAX_LENGTH);
+  return cleaned || undefined;
 }
 function getConfiguredTelemetrySessionId() {
   return normalizeSessionId(getProcessEnv2()?.[TELEMETRY_SESSION_ID_ENV]);
 }
-function getTelemetrySessionId() {
-  const envSessionId = getConfiguredTelemetrySessionId();
-  if (envSessionId) {
-    return envSessionId;
+function getInheritedSession(env) {
+  for (const candidate of INHERITED_SESSION_SOURCES) {
+    const handle = normalizeSessionId(env[candidate.envVar]);
+    if (handle) {
+      return { id: handle, source: candidate.source };
+    }
+  }
+  return;
+}
+function generateRandomSession() {
+  const bytes = new Uint8Array(RANDOM_SESSION_ID_LENGTH / 2);
+  crypto.getRandomValues(bytes);
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
   }
-  const existing = telemetrySessionIdSlot.get();
+  return { id: hex, source: "random" };
+}
+function resolveTelemetrySession() {
+  const existing = telemetrySessionSlot.get();
   if (existing) {
     return existing;
   }
-  const generated = crypto.randomUUID();
-  telemetrySessionIdSlot.set(generated);
-  return generated;
+  const declaredHandle = getConfiguredTelemetrySessionId();
+  const resolved = declaredHandle ? { id: declaredHandle, source: "declared" } : getInheritedSession(getProcessEnv2() ?? {}) ?? generateRandomSession();
+  telemetrySessionSlot.set(resolved);
+  return resolved;
 }
-function resolveTelemetrySessionId(existingSessionId) {
-  return getConfiguredTelemetrySessionId() ?? normalizeSessionId(existingSessionId);
+function getTelemetrySessionId() {
+  return resolveTelemetrySession().id;
+}
+function getTelemetrySessionSource() {
+  return resolveTelemetrySession().source;
 }
 function getTelemetryOperationId() {
   const existing = telemetryOperationIdSlot.get();
@@ -734,14 +762,11 @@ class TelemetryService {
   }
   async trackDependencyOperation(name, type, fn, properties) {
     const parentContext = this.getCurrentContext();
-    if (!parentContext) {
-      throw new Error("trackDependencyOperation must be called within a trackRequest block.");
-    }
-    const childContext = {
+    const childContext = parentContext !== undefined ? {
       operationId: parentContext.operationId,
       parentId: parentContext.id,
       id: this.generateId()
-    };
+    } : this.createRequestContext();
     const startTime = performance.now();
     try {
       const result = await this.contextStorage.run(childContext, fn);
@@ -762,24 +787,18 @@ class TelemetryService {
   }
   enrichPropertiesWithContext(properties, context) {
     const globalProperties = getGlobalTelemetryProperties();
-    const existingSessionId = properties?.[TELEMETRY_SESSION_ID_PROPERTY] ?? this.defaultProperties?.[TELEMETRY_SESSION_ID_PROPERTY] ?? globalProperties?.[TELEMETRY_SESSION_ID_PROPERTY];
-    const sessionId = resolveTelemetrySessionId(existingSessionId);
     const enriched = {
       ...getExecutionContextTelemetryProperties(),
       ...globalProperties,
       ...this.defaultProperties,
       ...redactProperties(properties ?? {}),
+      [TELEMETRY_SESSION_SOURCE_PROPERTY]: getTelemetrySessionSource(),
       ...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];
-    } else {
-      enriched[TELEMETRY_SESSION_ID_PROPERTY] = sessionId;
-    }
     return enriched;
   }
   generateId() {
@@ -797,7 +816,6 @@ class TelemetryService {
 }
 export {
   setExecutionContextAuthSignal,
-  resolveTelemetrySessionId,
   redactValue,
   redactProperty,
   redactProperties,
@@ -805,6 +823,7 @@ export {
   normalizeSkillName,
   normalizeEnvironment,
   normalizeBaseUrl,
+  getTelemetrySessionSource,
   getTelemetrySessionId,
   getExecutionContextTelemetryProperties,
   getConfiguredTelemetrySessionId,
@@ -814,7 +833,7 @@ export {
   buildCommandTelemetryAttribution,
   TelemetryService,
   TELEMETRY_SPAN_ID_PROPERTY,
-  TELEMETRY_SESSION_ID_PROPERTY,
+  TELEMETRY_SESSION_SOURCE_PROPERTY,
   TELEMETRY_SESSION_ID_ENV,
   TELEMETRY_PARENT_ID_PROPERTY,
   TELEMETRY_OPERATION_ID_PROPERTY,
@@ -823,4 +842,4 @@ export {
   BrowserContextStorage
 };
 
-//# debugId=0CFD50D10461DCC664756E2164756E21
+//# debugId=E05A0A007C0249BF64756E2164756E21

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

@@ -1,6 +1,17 @@
 import type { ITelemetryProvider } from "./telemetry-provider.js";
 import { type TelemetryProperties } from "./telemetry-service.js";
 export { getGlobalTelemetryProperties, setGlobalTelemetryProperties, } from "./global-telemetry-properties.js";
+/**
+ * Envelopes still buffered in the SDK channel at exit, plus the ingestion
+ * endpoint they were headed to. The envelopes are fully formed (tags, ikey,
+ * time already baked in) — POSTing them newline-joined and gzipped to
+ * `endpointUrl` with `Content-Type: application/x-json-stream` is exactly
+ * what the SDK's own sender would have done.
+ */
+export interface PendingTelemetryEnvelopes {
+    endpointUrl: string;
+    envelopes: unknown[];
+}
 /**
  * Node.js Application Insights telemetry provider.
  * Uses the `applicationinsights` Node SDK (not the browser SDK).
@@ -43,18 +54,6 @@ export declare class NodeAppInsightsTelemetryProvider implements ITelemetryProvi
      * 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
@@ -79,6 +78,15 @@ export declare class NodeAppInsightsTelemetryProvider implements ITelemetryProvi
     trackRequest(name: 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>;
+    /**
+     * Take the envelopes still buffered in the SDK channel (nothing has sent
+     * them yet), clearing the batch timer and the buffer so a later
+     * {@link shutdown} has nothing left to send or hold the event loop open
+     * with. Returns `undefined` when draining isn't possible (no client, no
+     * endpoint, or an unexpected SDK shape) — callers must then fall back to
+     * a normal in-process {@link flush}.
+     */
+    drainPendingEnvelopes(): PendingTelemetryEnvelopes | undefined;
     /**
      * Dispose the Application Insights SDK so its internal channels,
      * keep-alive sockets, and timers are closed — allowing the Node.js

package/dist/telemetry/node.d.ts

@@ -4,7 +4,7 @@ export { detectAgent, detectAgentVersion } from "./detect-agent.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 { NodeContextStorage } from "./node-context-storage.js";
-export { getConfiguredTelemetrySessionId, getTelemetrySessionId, resolveTelemetrySessionId, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_ID_PROPERTY, } from "./session-id.js";
+export { getConfiguredTelemetrySessionId, getTelemetrySessionId, getTelemetrySessionSource, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_SOURCE_PROPERTY, } from "./session-id.js";
 export type { ITelemetryProvider } from "./telemetry-provider.js";
 export type { ITelemetryService, TelemetryContext, TelemetryProperties, } 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/session-id.d.ts

@@ -1,15 +1,61 @@
 export declare const TELEMETRY_SESSION_ID_ENV = "UIPATH_SESSION_ID";
-export declare const TELEMETRY_SESSION_ID_PROPERTY = "session_id";
+/**
+ * Hard ceiling on the emitted session id. App Insights caps `ai.session.id` at
+ * 64 characters and truncates past it silently, so the CLI cuts to the same
+ * limit itself rather than shipping a value the backend will quietly reshape.
+ *
+ * Two handles that share their first 64 characters therefore collapse into one
+ * session. Accepted: no observed host exports a handle anywhere near this long
+ * (every one of them is a UUID or shorter), and hashing to dodge it would make
+ * every id opaque — a host could no longer find its own `UIPATH_SESSION_ID` in
+ * the data.
+ */
+export declare const SESSION_ID_MAX_LENGTH = 64;
+/** Width of the minted fallback id when no host handle exists. */
+export declare const RANDOM_SESSION_ID_LENGTH = 32;
+/**
+ * Custom dimension naming which handle the session id came from. A `terminal`
+ * session is not comparable to a `claude-code` one (see the Session Id section
+ * of TELEMETRY_GUIDE.md), and the id alone does not say which it is — the
+ * handles pass through as the host exported them, with no source marker. Low
+ * cardinality by construction: one of {@link TelemetrySessionSource}.
+ */
+export declare const TELEMETRY_SESSION_SOURCE_PROPERTY = "session_id_source";
+/**
+ * Where a session id came from — the value of the
+ * {@link TELEMETRY_SESSION_SOURCE_PROPERTY} dimension.
+ *
+ * - `declared`: the host set `UIPATH_SESSION_ID` on purpose. The only boundary
+ *   someone chose; everything else is inferred.
+ * - `claude-code` / `codex` / `antigravity`: one agent conversation.
+ * - `terminal`: a terminal tab or pane, which can stay open for weeks and
+ *   splits when the user splits a pane.
+ * - `random`: no host handle at all, so one CLI process.
+ */
+export type TelemetrySessionSource = "declared" | "claude-code" | "codex" | "antigravity" | "terminal" | "random";
+/**
+ * The `UIPATH_SESSION_ID` handle as the host exported it (trimmed, control
+ * characters stripped, cut to {@link SESSION_ID_MAX_LENGTH}), or undefined when
+ * unset. Same value {@link getTelemetrySessionId} emits when it is set.
+ */
 export declare function getConfiguredTelemetrySessionId(): string | undefined;
 /**
- * Resolve the telemetry session id used by App Insights session tags.
+ * Resolve the session id for App Insights' native `ai.session.id` tag. Session
+ * lives on that tag and nowhere else — no custom dimension mirrors it.
  *
- * Coding-agent hosts can set UIPATH_SESSION_ID to correlate separate CLI
- * invocations. When unset, use one process-local fallback shared across
- * bundled copies of @uipath/common.
+ * The id is the host's handle verbatim, so a host that exports
+ * `UIPATH_SESSION_ID` can find its own sessions by that literal value. Which
+ * handle produced it rides the {@link TELEMETRY_SESSION_SOURCE_PROPERTY}
+ * dimension, since the id itself carries no source marker — the same string
+ * exported as `TERM_SESSION_ID` and as `UIPATH_SESSION_ID` is one id on two
+ * sources.
  */
 export declare function getTelemetrySessionId(): string;
-export declare function resolveTelemetrySessionId(existingSessionId: unknown): string | undefined;
+/**
+ * Which handle this process's session id came from — emitted on every telemetry
+ * item as {@link TELEMETRY_SESSION_SOURCE_PROPERTY}.
+ */
+export declare function getTelemetrySessionSource(): TelemetrySessionSource;
 /**
  * Resolve the per-invocation operation id used for App Insights' native
  * `operation_Id` tag.
@@ -24,8 +70,7 @@ export declare function resolveTelemetrySessionId(existingSessionId: unknown): 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.
+ * App Insights expects for `operation_Id`, and 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-events.d.ts

@@ -1,4 +1,14 @@
+/**
+ * Canonical CLI event names.
+ *
+ * Every name lives under the `uip.*` namespace so a single
+ * `name startswith "uip."` filter selects all CLI telemetry — a snake_case
+ * name outside it is invisible to every downstream pipeline (STUD-80942).
+ */
 export declare const CommonTelemetryEvents: {
     readonly Error: "uip.error";
-    readonly ShipSucceeded: "ship_succeeded";
+    /** A ship (publish/deploy/upload) completed. The command that shipped is
+     * carried by the `command_name` dimension; `ship_kind`/`target` describe
+     * what was shipped where. */
+    readonly ShipSucceeded: "uip.ship.succeeded";
 };

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

@@ -41,8 +41,23 @@ export interface TelemetryInitOptions {
  */
 export declare function telemetryInit(options?: TelemetryInitOptions): Promise<void>;
 /**
- * Flush all buffered telemetry to the cloud.
- * Must be awaited before the process exits to ensure delivery.
- * Capped at FLUSH_SHUTDOWN_TIMEOUT_MS to avoid hanging on slow/unreachable endpoints.
+ * Deliver all buffered telemetry before the process exits.
+ * Must be awaited on every exit path.
+ *
+ * Normally hands the buffered envelopes to a detached sidecar process (see
+ * {@link trySidecarHandoff}) so the exit is instant. Falls back to the
+ * in-process flush — one ingestion round-trip, capped at
+ * FLUSH_SHUTDOWN_TIMEOUT_MS — when the sidecar handoff isn't available or
+ * UIPATH_TELEMETRY_SYNC_FLUSH=1 forces it.
  */
 export declare function telemetryFlushAndShutdown(): Promise<void>;
+/**
+ * Dispose the telemetry SDK without sending — buffered events are dropped
+ * on purpose. For exits where delivery is not worth a network round-trip
+ * (help/version display).
+ *
+ * Shares the memo slot with {@link telemetryFlushAndShutdown}: whichever
+ * runs first wins, so a later flush call on the same exit path awaits the
+ * already-finished shutdown instead of opening a network connection.
+ */
+export declare function telemetryShutdownWithoutFlush(): Promise<void>;

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

@@ -193,6 +193,11 @@ export interface ITelemetryService {
      * @remarks
      * Tracks this operation as a dependency in Application Insights, automatically correlated
      * to the parent request using the context from IContextStorage.
+     *
+     * With no enclosing request the dependency is emitted as a trace root (no
+     * `operation_ParentId`) rather than being dropped or throwing — a reusable
+     * unit of work stays a dependency even when the host that called it never
+     * opened a request of ours.
      */
     trackDependencyOperation<T>(name: string, type: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
 }

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

@@ -0,0 +1,68 @@
+/**
+ * Hidden argv verb that makes the CLI entry point run the spool sender
+ * instead of the normal Commander pipeline. Never registered as a command —
+ * the entry point matches it on raw argv before the program is built.
+ */
+export declare const TELEMETRY_DRAIN_ARGV = "__uip-drain-telemetry";
+/**
+ * Register the script path that handles {@link TELEMETRY_DRAIN_ARGV}.
+ * Called once by the CLI entry point at startup; until it is called, the
+ * exit path keeps the in-process flush (no sidecar is ever spawned).
+ */
+export declare function setTelemetrySidecarEntry(entryPath: string): void;
+export declare function getTelemetrySidecarEntry(): string | undefined;
+/** Contents of one spool file. */
+export interface TelemetrySpoolPayload {
+    /** Full ingestion URL (`<IngestionEndpoint>/v2.1/track`). */
+    endpointUrl: string;
+    /** Fully-formed App Insights envelopes, exactly as the SDK buffered them. */
+    envelopes: unknown[];
+}
+/** A pending spool file claimed for sending (renamed to `.sending`). */
+export interface ClaimedSpoolFile {
+    /** The claimed (`.sending`) path — delete it after a successful send. */
+    claimedPath: string;
+    payload: TelemetrySpoolPayload;
+}
+/** Spool files older than this are deleted unsent — stale telemetry has no value. */
+export declare const MAX_SPOOL_AGE_MS: number;
+/** Hard cap on spool files; oldest beyond this are deleted (offline machines). */
+export declare const MAX_SPOOL_FILES = 50;
+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.
+ */
+export declare function writeTelemetrySpoolFile(payload: TelemetrySpoolPayload): Promise<string>;
+/**
+ * Claim every pending spool file for sending. Claiming renames the file to
+ * `.sending` — an atomic operation, so when two senders sweep concurrently
+ * only one wins each file and nothing is delivered twice. Files that fail
+ * the rename are skipped (another sender owns them).
+ *
+ * Bad content is split two ways on purpose: a file that cannot be READ is
+ * released for a later attempt (on Windows a concurrent handle shows up as a
+ * transient EBUSY, and deleting there would throw telemetry away for a problem
+ * that resolves itself), while a file that reads fine but does not parse or
+ * does not match the payload shape is deleted — no future sweep can make it
+ * valid, so keeping it would just burn a claim on every run until the age cap.
+ */
+export declare function claimPendingSpoolFiles(): Promise<ClaimedSpoolFile[]>;
+/**
+ * Return a claimed file to the pending pool so a future sender retries it.
+ * Best-effort: if the rename fails the file stays `.sending` and the age
+ * cap eventually removes it.
+ */
+export declare function releaseClaimedSpoolFile(claimedPath: string): Promise<void>;
+/** Delete a claimed file after its envelopes were delivered. Best-effort. */
+export declare function discardClaimedSpoolFile(claimedPath: string): Promise<void>;
+/**
+ * Enforce the spool bounds: delete any file older than
+ * {@link MAX_SPOOL_AGE_MS} — including `.sending` files orphaned by a
+ * crashed sender and `.tmp` files orphaned by a crashed writer — and keep at
+ * most {@link MAX_SPOOL_FILES} pending files, deleting the oldest beyond
+ * that. Run by the sender before claiming, so an unreachable endpoint can't
+ * grow the spool without bound.
+ */
+export declare function sweepTelemetrySpool(): Promise<void>;

package/dist/tool-module-import.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Dynamic import of another tool's library entry point (e.g.
+ * `@uipath/solution-tool/init`).
+ *
+ * Its own module so tests can stand in for it, and so the specifier stays a
+ * plain variable — bundlers then leave the `import()` to run at runtime
+ * instead of inlining the multi-megabyte target bundle into the caller.
+ */
+export declare function importToolModule(specifier: string): Promise<unknown>;

package/dist/tool-provider.d.ts

@@ -1,6 +1,38 @@
 /**
- * Cross-module bridge for packager factory resolution.
+ * Cross-module bridge for packager factory and tool-module resolution.
  */
 export type PackagerFactoryProvider = (verb: string) => Promise<void>;
 export declare function setPackagerFactoryProvider(provider: PackagerFactoryProvider): void;
-export declare function ensurePackagerFactory(verb: string): Promise<void>;
+export type ToolModuleProvider = (verb: string, moduleName: string) => Promise<unknown>;
+export declare function setToolModuleProvider(provider: ToolModuleProvider): void;
+/**
+ * Resolve another tool's library entry point (its `dist/<module>.js` subpath
+ * export) at runtime and return the module namespace.
+ *
+ * Prefers the registered provider (installed by the CLI — it can install the
+ * tool on demand and imports the entry by absolute path). With no provider —
+ * a library caller — falls back to importing `<packageName>/<moduleName>`,
+ * which resolves when the tool package is installed next to the caller.
+ *
+ * This is how one tool uses another tool's code without bundling it: the
+ * multi-megabyte implementation ships once, in the tool that owns it.
+ *
+ * @param verb - CLI tool verb that owns the module (e.g. `"solution"`).
+ * @param packageName - npm package behind that verb, used for the fallback
+ * import (e.g. `"@uipath/solution-tool"`).
+ * @param moduleName - subpath entry to load (e.g. `"init"`, `"resource"`).
+ */
+export declare function ensureToolModule(verb: string, packageName: string, moduleName: string): Promise<unknown>;
+/**
+ * Resolve the packager factory for a tool verb.
+ *
+ * Prefers the registered provider (installed by the CLI). With no provider —
+ * a library caller — falls back to the tool package's own `packager-tool`
+ * entry point: imports it and calls its `registerPackagerFactories` export.
+ *
+ * @param verb - CLI tool verb that owns the factory (e.g. `"maestro"`).
+ * @param packageName - npm package behind that verb. Drives the fallback
+ * import and is the one thing the error asks for. Omit when unknown; there is
+ * then no fallback and no package to name.
+ */
+export declare function ensurePackagerFactory(verb: string, packageName?: string): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uipath/common",
   "license": "MIT",
-  "version": "1.199.0-preview.97",
+  "version": "1.200.0-preview.109",
   "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"
     },
+    "./guid": {
+      "types": "./dist/guid.d.ts",
+      "default": "./dist/guid.js"
+    },
     "./sdk-user-agent": {
       "browser": {
         "types": "./dist/sdk-user-agent.d.ts",
@@ -67,5 +71,5 @@
     "mihaigirleanu",
     "vlad-uipath"
   ],
-  "gitHead": "087ae21e842f27bde5eb0013892c9487bfe60568"
+  "gitHead": "fcc01cdae81bbd0c25d3d4fc287537a9d19d99f4"
 }