@uipath/common 1.199.0 → 1.200.0-preview.117

package/dist/formatter.d.ts

@@ -164,6 +164,25 @@ export declare class FilterEvaluationError extends Error {
     readonly result: FailureResultType;
     constructor(filter: string, cause: unknown);
 }
+/**
+ * Thrown by `trackedAction` when `--output-filter` is combined with a command
+ * whose `--limit` resolved from its declared default instead of the command
+ * line. The filter runs client-side over only the records the command fetched,
+ * so an implicit limit would silently cap the data being filtered — the caller
+ * must state how much data the filter applies to.
+ *
+ * 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 FilterImplicitLimitError extends Error {
+    readonly __brand: "FilterImplicitLimitError";
+    readonly errorCode: CliErrorCode;
+    readonly instructions: string;
+    readonly retry: RetryHint;
+    readonly result: FailureResultType;
+    constructor(defaultLimit: string);
+}
 /**
  * OutputFormatter namespace for formatting and displaying output.
  */

package/dist/guid.js

@@ -0,0 +1,10 @@
+// src/guid.ts
+var GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isGuid(value) {
+  return GUID_REGEX.test(value);
+}
+export {
+  isGuid
+};
+
+//# debugId=F25023E1915C1B3664756E2164756E21

package/dist/host-global-options.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Global options the CLI host owns. It parses them out of argv before
+ * Commander runs (`stripGlobalOptions` in `packages/cli/src/utils/globalOptions.ts`)
+ * so tools never have to define them.
+ *
+ * The host cleans `context.args` only — `process.argv` keeps the raw tokens. A
+ * tool that re-reads `process.argv` therefore still sees these, and must strip
+ * them itself before forwarding. `function-tool`'s passthrough does exactly
+ * that: it reads raw argv on purpose, so unknown flags reach the downstream
+ * CLI verbatim, which means the host's own options would reach it too and be
+ * rejected as unknown options.
+ *
+ * Adding a global option to the host means adding it here as well;
+ * `globalOptions.spec.ts` fails if the two drift apart.
+ */
+/** Host options that consume a following value (`--flag v` / `--flag=v`). */
+export declare const HOST_GLOBAL_OPTIONS_WITH_VALUE: readonly ["--output", "--output-filter", "--log-level", "--log-file", "--profile"];
+/** Host options that take no value. */
+export declare const HOST_GLOBAL_FLAGS: readonly ["--json", "--interactive", "--no-interactive"];
+/**
+ * Drop every host-owned global option from `args`, returning the rest
+ * untouched. Handles both `--flag value` and `--flag=value`; unrelated flags
+ * are always preserved, since a passthrough tool must forward what it does not
+ * own.
+ */
+export declare function stripHostGlobalOptions(args: string[]): string[];

package/dist/index.browser.js

@@ -21223,6 +21223,9 @@ async function extractErrorDetails(error, options) {
         if (!extractedMessage) {
           extractedMessage = body;
         }
+        if (extractedMessage && typeof parsedBody.detail === "string" && parsedBody.detail.length > 0 && !extractedMessage.includes(parsedBody.detail)) {
+          extractedMessage = `${extractedMessage}: ${parsedBody.detail}`;
+        }
       } else {
         extractedMessage = isHtmlDocument(body) ? HTML_RESPONSE_MESSAGE : body;
       }
@@ -21277,6 +21280,8 @@ async function extractErrorDetails(error, options) {
       const extra = {};
       if (parsedBody.errorCode)
         extra.errorCode = parsedBody.errorCode;
+      if (parsedBody.detail)
+        extra.detail = parsedBody.detail;
       if (parsedBody.details)
         extra.details = parsedBody.details;
       if (parsedBody.errors != null)
@@ -22254,9 +22259,15 @@ var FAILURE_STATUSES = new Set([
   "stopped"
 ]);
 function isTerminalStatus(status) {
+  if (typeof status !== "string") {
+    return false;
+  }
   return TERMINAL_STATUSES.has(status.toLowerCase());
 }
 function isFailureStatus(status) {
+  if (typeof status !== "string") {
+    return false;
+  }
   return FAILURE_STATUSES.has(status.toLowerCase());
 }
 function isSuccessStatus(status) {
@@ -22479,7 +22490,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"]],
@@ -22915,7 +22926,7 @@ function getTelemetryOperationId() {
 // src/telemetry/telemetry-events.ts
 var CommonTelemetryEvents = {
   Error: "uip.error",
-  ShipSucceeded: "ship_succeeded"
+  ShipSucceeded: "uip.ship.succeeded"
 };
 // src/telemetry/detect-agent.ts
 var KNOWN_AGENTS = [
@@ -23278,14 +23289,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);
@@ -23333,22 +23341,80 @@ class TelemetryService {
     return hex;
   }
 }
+// src/packager-tool-import.ts
+var REGISTER_EXPORT = "registerPackagerFactories";
+async function importPackagerTool(specifier) {
+  const [importError, mod] = await catchError(import(specifier));
+  if (importError)
+    return importError;
+  const register = mod?.[REGISTER_EXPORT];
+  if (typeof register !== "function") {
+    logger.debug(`'${specifier}' has no '${REGISTER_EXPORT}' export — treating it as a ` + "legacy entry point that registered its factories at import.");
+    return;
+  }
+  const [registerError] = catchError(() => {
+    register();
+  });
+  return registerError;
+}
+
+// src/tool-module-import.ts
+async function importToolModule(specifier) {
+  return await import(specifier);
+}
+
 // src/tool-provider.ts
 var factorySlot = singleton("PackagerFactoryProvider");
 function setPackagerFactoryProvider(provider) {
   factorySlot.set(provider);
 }
-async function ensurePackagerFactory(verb) {
+var moduleSlot = singleton("ToolModuleProvider");
+function setToolModuleProvider(provider) {
+  moduleSlot.set(provider);
+}
+async function ensureToolModule(verb, packageName, moduleName) {
+  if (!/^[a-z0-9-]+$/.test(moduleName)) {
+    throw new Error(`Invalid tool module name '${moduleName}'.`);
+  }
+  const provider = moduleSlot.get();
+  if (provider) {
+    return provider(verb, moduleName);
+  }
+  const specifier = `${packageName}/${moduleName}`;
+  const [importError, mod] = await catchError(importToolModule(specifier));
+  if (importError) {
+    logger.debug(`No tool-module provider registered; import of '${specifier}' failed: ${importError.message}`);
+    throw new Error(`This command needs '${packageName}'. Install it.`, {
+      cause: importError
+    });
+  }
+  return mod;
+}
+async function ensurePackagerFactory(verb, packageName) {
   const provider = factorySlot.get();
-  if (!provider) {
-    throw new Error(`Packager factory for '${verb}' is required but no factory provider is registered. ` + `Run 'uip tools install ${verb}' manually.`);
+  if (provider) {
+    await provider(verb);
+    return;
+  }
+  const importError = packageName ? await loadPackagerTool(`${packageName}/packager-tool`) : undefined;
+  if (packageName && !importError)
+    return;
+  throw new Error(packageName ? `Packing this project type needs '${packageName}'. Install it.` : `Packing this project type needs the packager factory for '${verb}', and no package provides it.`, { cause: importError });
+}
+async function loadPackagerTool(specifier) {
+  const error = await importPackagerTool(specifier);
+  if (error) {
+    logger.debug(`No packager factory provider registered; import of '${specifier}' failed: ${error.message}`);
+    return error;
   }
-  await provider(verb);
+  logger.debug(`No packager factory provider registered; loaded '${specifier}' directly.`);
+  return;
 }
 export {
   withCompleter,
   takeRecordedCommandFailureTelemetry,
   singleton,
+  setToolModuleProvider,
   setSdkUserAgentHostToken,
   setPackagerFactoryProvider,
   setOutputFormatExplicit,
@@ -23404,6 +23470,7 @@ export {
   extractErrorMessage,
   extractErrorDetails,
   extractCommandHelp,
+  ensureToolModule,
   ensurePackagerFactory,
   describeConnectivityError,
   createPollAbortController,
@@ -23443,4 +23510,4 @@ export {
   AUTH_FILENAME
 };
 
-//# debugId=04886234C3E93F8264756E2164756E21
+//# debugId=C2BB3B73AD55AF7D64756E2164756E21

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./error-handler";
 export * from "./error-instructions";
 export * from "./formatter";
 export * from "./guid";
+export * from "./host-global-options";
 export * from "./interactivity-context";
 export * from "./logger";
 export * from "./option-aliases";
@@ -23,12 +24,14 @@ export * from "./output-context";
 export * from "./output-format-context";
 export * from "./output-sink";
 export * from "./package-metadata-options";
+export { type PackagerToolModule, REGISTER_EXPORT, } from "./packager-tool-import";
 export * from "./polling";
 export * from "./preview";
 export * from "./registry";
 export * from "./screen-logger";
 export * from "./sdk-user-agent";
 export * from "./singleton";
+export * from "./solution-project-artifacts";
 export * from "./stdin";
 export { BrowserContextStorage } from "./telemetry/browser-context-storage.js";
 export * from "./telemetry/command-attribution.js";
@@ -40,5 +43,6 @@ export { redactError, redactProperties, redactProperty, redactValue, } from "./t
 export { type ShipSucceededTelemetryPayload, trackShipSucceeded, } from "./telemetry/ship-succeeded.js";
 export * from "./telemetry/telemetry-events.js";
 export * from "./telemetry/telemetry-init.js";
+export * from "./telemetry/telemetry-spool.js";
 export * from "./tool-provider";
 export * from "./trackedAction.js";

package/dist/index.js

@@ -3194,6 +3194,9 @@ async function extractErrorDetails(error, options) {
         if (!extractedMessage) {
           extractedMessage = body;
         }
+        if (extractedMessage && typeof parsedBody.detail === "string" && parsedBody.detail.length > 0 && !extractedMessage.includes(parsedBody.detail)) {
+          extractedMessage = `${extractedMessage}: ${parsedBody.detail}`;
+        }
       } else {
         extractedMessage = isHtmlDocument(body) ? HTML_RESPONSE_MESSAGE : body;
       }
@@ -3248,6 +3251,8 @@ async function extractErrorDetails(error, options) {
       const extra = {};
       if (parsedBody.errorCode)
         extra.errorCode = parsedBody.errorCode;
+      if (parsedBody.detail)
+        extra.detail = parsedBody.detail;
       if (parsedBody.details)
         extra.details = parsedBody.details;
       if (parsedBody.errors != null)
@@ -9144,9 +9149,12 @@ function buildCommandTerminalTelemetryProperties(input) {
 // src/telemetry/telemetry-events.ts
 var CommonTelemetryEvents = {
   Error: "uip.error",
-  ShipSucceeded: "ship_succeeded"
+  ShipSucceeded: "uip.ship.succeeded"
 };
 
+// src/telemetry/telemetry-init.ts
+import { spawn } from "node:child_process";
+
 // src/registry.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
 function readRegistryValue(keyPath, valueName) {
@@ -9786,14 +9794,11 @@ class TelemetryService {
   }
   async trackDependencyOperation(name, type2, 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);
@@ -9974,6 +9979,9 @@ function normalizeFlushCallbackError(response) {
   }
   return extractAppInsightsDumpMessage(text) ?? text;
 }
+function channelInternals(client) {
+  return client.channel;
+}
 function setDefaultAppInsightsEnv(name, value) {
   if (process.env[name] === undefined) {
     process.env[name] = value;
@@ -10181,6 +10189,32 @@ class NodeAppInsightsTelemetryProvider {
       logger.warn(`[AppInsights] flush error (non-fatal): ${error.message}`);
     }
   }
+  drainPendingEnvelopes() {
+    const client = this.client;
+    if (!client)
+      return;
+    const endpointUrl = client.config?.endpointUrl;
+    if (!endpointUrl)
+      return;
+    const [error, envelopes] = catchError(() => {
+      const channel = channelInternals(client);
+      if (!channel || !Array.isArray(channel._buffer)) {
+        throw new Error("unexpected channel shape");
+      }
+      if (channel._timeoutHandle) {
+        clearTimeout(channel._timeoutHandle);
+        channel._timeoutHandle = undefined;
+      }
+      const buffered = channel._buffer;
+      channel._buffer = [];
+      return buffered;
+    });
+    if (error) {
+      logger.debug("[AppInsights] failed to drain the channel buffer");
+      return;
+    }
+    return { endpointUrl, envelopes };
+  }
   async shutdown() {
     const client = this.client;
     if (client) {
@@ -10188,6 +10222,19 @@ class NodeAppInsightsTelemetryProvider {
       if (statsbeatError) {
         logger.debug("[AppInsights] failed to shut down Statsbeat");
       }
+      const [channelError] = catchError(() => {
+        const channel = channelInternals(client);
+        if (!channel)
+          return;
+        if (channel._timeoutHandle) {
+          clearTimeout(channel._timeoutHandle);
+          channel._timeoutHandle = undefined;
+        }
+        channel._buffer = [];
+      });
+      if (channelError) {
+        logger.debug("[AppInsights] failed to clear the channel buffer");
+      }
     }
     const appInsights = this.appInsightsModule;
     if (appInsights) {
@@ -10229,6 +10276,115 @@ function isTelemetryDisabled() {
   return value === "1" || value === "true";
 }
 
+// src/telemetry/telemetry-spool.ts
+var TELEMETRY_DRAIN_ARGV = "__uip-drain-telemetry";
+var sidecarEntrySlot = singleton("TelemetrySidecarEntry");
+function setTelemetrySidecarEntry(entryPath) {
+  sidecarEntrySlot.set(entryPath);
+}
+function getTelemetrySidecarEntry() {
+  return sidecarEntrySlot.get();
+}
+var PENDING_SUFFIX = ".json";
+var CLAIMED_SUFFIX = ".sending";
+var WRITE_TEMP_SUFFIX = ".tmp";
+var MAX_SPOOL_AGE_MS = 72 * 60 * 60 * 1000;
+var MAX_SPOOL_FILES = 50;
+function getTelemetrySpoolDir() {
+  const fs7 = getFileSystem();
+  return fs7.path.join(fs7.env.homedir(), ".uipath", "telemetry", "pending");
+}
+async function writeTelemetrySpoolFile(payload) {
+  const fs7 = getFileSystem();
+  const dir = getTelemetrySpoolDir();
+  await fs7.mkdir(dir);
+  const name = `${Date.now()}-${process.pid}`;
+  const finalPath = fs7.path.join(dir, `${name}${PENDING_SUFFIX}`);
+  const tempPath = fs7.path.join(dir, `${name}${WRITE_TEMP_SUFFIX}`);
+  await fs7.writeFile(tempPath, JSON.stringify(payload));
+  await fs7.rename(tempPath, finalPath);
+  return finalPath;
+}
+function isSpoolPayload(value) {
+  return value !== null && typeof value === "object" && typeof value.endpointUrl === "string" && value.endpointUrl.length > 0 && Array.isArray(value.envelopes);
+}
+async function listSpoolEntries(suffix) {
+  const fs7 = getFileSystem();
+  const dir = getTelemetrySpoolDir();
+  const [readdirError, names] = await catchError(fs7.readdir(dir));
+  if (readdirError) {
+    return { dir, names: [] };
+  }
+  return {
+    dir,
+    names: names.filter((n) => n.endsWith(suffix)).sort((a, b) => a.localeCompare(b))
+  };
+}
+async function claimPendingSpoolFiles() {
+  const fs7 = getFileSystem();
+  const { dir, names } = await listSpoolEntries(PENDING_SUFFIX);
+  const claimed = [];
+  for (const name of names) {
+    const pendingPath = fs7.path.join(dir, name);
+    const claimedPath = `${pendingPath.slice(0, -PENDING_SUFFIX.length)}${CLAIMED_SUFFIX}`;
+    const [claimError] = await catchError(fs7.rename(pendingPath, claimedPath));
+    if (claimError) {
+      continue;
+    }
+    const [readError, raw] = await catchError(fs7.readFile(claimedPath, "utf-8"));
+    if (readError || raw === null) {
+      logger.debug(`[TelemetrySpool] could not read ${name}; leaving it for a later run`);
+      await releaseClaimedSpoolFile(claimedPath);
+      continue;
+    }
+    const [parseError, parsed] = catchError(() => JSON.parse(raw));
+    if (parseError || !isSpoolPayload(parsed)) {
+      logger.debug(`[TelemetrySpool] dropping malformed file: ${name}`);
+      await catchError(fs7.rm(claimedPath));
+      continue;
+    }
+    claimed.push({ claimedPath, payload: parsed });
+  }
+  return claimed;
+}
+async function releaseClaimedSpoolFile(claimedPath) {
+  const fs7 = getFileSystem();
+  const pendingPath = `${claimedPath.slice(0, -CLAIMED_SUFFIX.length)}${PENDING_SUFFIX}`;
+  await catchError(fs7.rename(claimedPath, pendingPath));
+}
+async function discardClaimedSpoolFile(claimedPath) {
+  const fs7 = getFileSystem();
+  await catchError(fs7.rm(claimedPath));
+}
+async function sweepTelemetrySpool() {
+  const fs7 = getFileSystem();
+  const { dir, names } = await listSpoolEntries("");
+  const now = Date.now();
+  const pending = [];
+  for (const name of names) {
+    const filePath = fs7.path.join(dir, name);
+    const [statError, stats] = await catchError(fs7.stat(filePath));
+    if (statError || !stats) {
+      continue;
+    }
+    if (now - stats.mtimeMs > MAX_SPOOL_AGE_MS) {
+      await catchError(fs7.rm(filePath));
+      continue;
+    }
+    if (name.endsWith(PENDING_SUFFIX)) {
+      pending.push({ path: filePath, mtimeMs: stats.mtimeMs });
+    }
+  }
+  if (pending.length > MAX_SPOOL_FILES) {
+    pending.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const excess = pending.slice(0, pending.length - MAX_SPOOL_FILES);
+    for (const file of excess) {
+      await catchError(fs7.rm(file.path));
+    }
+    logger.debug(`[TelemetrySpool] deleted ${excess.length} oldest files over the ${MAX_SPOOL_FILES}-file cap`);
+  }
+}
+
 // src/telemetry/telemetry-init.ts
 var telemetryInstanceSlot = singleton("TelemetryService");
 var DEFAULT_AI_CONNECTION_STRING = atob("SW5zdHJ1bWVudGF0aW9uS2V5PTliZDM3NDgyLTgxMGUtNDQyYS1hYWE2LWQzOGVmNjVjNjY3NDtJbmdlc3Rpb25FbmRwb2ludD1odHRwczovL3dlc3RldXJvcGUtNS5pbi5hcHBsaWNhdGlvbmluc2lnaHRzLmF6dXJlLmNvbS87TGl2ZUVuZHBvaW50PWh0dHBzOi8vd2VzdGV1cm9wZS5saXZlZGlhZ25vc3RpY3MubW9uaXRvci5henVyZS5jb20vO0FwcGxpY2F0aW9uSWQ9MzU2OTdlZjEtOGJkMC00ZjE5LWEyN2MtZDg3Y2NhYzY2ZDJj");
@@ -10322,6 +10478,56 @@ async function runWithTimeout(operation, timeoutMs) {
       clearTimeout(timer);
   }
 }
+async function runProviderShutdown(provider) {
+  const [shutdownError, shutdownResult] = await catchError(runWithTimeout(provider.shutdown(), FLUSH_SHUTDOWN_TIMEOUT_MS));
+  if (shutdownError) {
+    logger.warn(`[Telemetry] shutdown failed (non-fatal): ${shutdownError.message}`);
+  } else if (shutdownResult === "timeout") {
+    logger.warn(`[Telemetry] shutdown timed out after ${FLUSH_SHUTDOWN_TIMEOUT_MS}ms`);
+  }
+}
+function isSyncFlushForced() {
+  const value = process.env.UIPATH_TELEMETRY_SYNC_FLUSH;
+  return value === "1" || value === "true";
+}
+function isDrainableTelemetryProvider(provider) {
+  return "drainPendingEnvelopes" in provider && typeof provider.drainPendingEnvelopes === "function";
+}
+function spawnTelemetrySidecar(entryPath) {
+  const child = spawn(process.execPath, [entryPath, TELEMETRY_DRAIN_ARGV], {
+    cwd: getFileSystem().env.tmpdir(),
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.on("error", (error) => {
+    logger.debug(`[Telemetry] sidecar spawn failed (spool kept for a later run): ${error.message}`);
+  });
+  child.unref();
+}
+async function trySidecarHandoff(provider) {
+  const entryPath = getTelemetrySidecarEntry();
+  if (entryPath === undefined || isSyncFlushForced() || !isDrainableTelemetryProvider(provider)) {
+    return false;
+  }
+  const pending = provider.drainPendingEnvelopes();
+  if (!pending) {
+    return false;
+  }
+  if (pending.envelopes.length > 0) {
+    const [spoolError] = await catchError(writeTelemetrySpoolFile(pending));
+    if (spoolError) {
+      logger.debug(`[Telemetry] spool write failed; dropping ${pending.envelopes.length} pending envelope(s): ${spoolError.message}`);
+    } else {
+      const [spawnError] = catchError(() => spawnTelemetrySidecar(entryPath));
+      if (spawnError) {
+        logger.debug(`[Telemetry] sidecar spawn failed; spool will be sent by a future run: ${spawnError.message}`);
+      }
+    }
+  }
+  await runProviderShutdown(provider);
+  return true;
+}
 async function telemetryFlushAndShutdown() {
   if (!isFlushableTelemetryProvider(telemetryProviderInstance)) {
     return;
@@ -10329,22 +10535,27 @@ async function telemetryFlushAndShutdown() {
   if (!telemetryFlushShutdownPromise) {
     const provider = telemetryProviderInstance;
     telemetryFlushShutdownPromise = (async () => {
+      if (await trySidecarHandoff(provider)) {
+        return;
+      }
       const [flushError, flushResult] = await catchError(runWithTimeout(provider.flush(), FLUSH_SHUTDOWN_TIMEOUT_MS));
       if (flushError) {
         logger.warn(`[Telemetry] flush failed (non-fatal): ${flushError.message}`);
       } else if (flushResult === "timeout") {
         logger.warn(`[Telemetry] flush timed out after ${FLUSH_SHUTDOWN_TIMEOUT_MS}ms`);
       }
-      const [shutdownError, shutdownResult] = await catchError(runWithTimeout(provider.shutdown(), FLUSH_SHUTDOWN_TIMEOUT_MS));
-      if (shutdownError) {
-        logger.warn(`[Telemetry] shutdown failed (non-fatal): ${shutdownError.message}`);
-      } else if (shutdownResult === "timeout") {
-        logger.warn(`[Telemetry] shutdown timed out after ${FLUSH_SHUTDOWN_TIMEOUT_MS}ms`);
-      }
+      await runProviderShutdown(provider);
     })();
   }
   await telemetryFlushShutdownPromise;
 }
+async function telemetryShutdownWithoutFlush() {
+  if (!isFlushableTelemetryProvider(telemetryProviderInstance)) {
+    return;
+  }
+  telemetryFlushShutdownPromise ??= runProviderShutdown(telemetryProviderInstance);
+  await telemetryFlushShutdownPromise;
+}
 
 // src/formatter.ts
 var CLI_ERROR_CODES = [
@@ -10621,21 +10832,43 @@ function printTable(data, logFn, externalLogValue) {
     logFn(`Log: ${externalLogValue}`);
   }
 }
+function isPlainObjectArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isPlainRecord);
+}
+function isNonEmptyPlainObject(value) {
+  return isPlainRecord(value) && Object.keys(value).length > 0;
+}
+var NESTED_INDENT = "  ";
 function printVerticalTable(data, logFn = console.log, externalLogValue) {
   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));
+  const isBlockValue = (value) => isPlainObjectArray(value) || isNonEmptyPlainObject(value);
+  const scalarKeys = keys.filter((key) => !isBlockValue(data[key]));
+  const maxKeyWidth = scalarKeys.length > 0 ? Math.max(...scalarKeys.map((key) => key.length)) : 0;
+  const termWidth = process.stdout.columns || 120;
+  const nestedWidth = Math.max(termWidth - NESTED_INDENT.length, 1);
   keys.forEach((key) => {
+    const value = data[key];
+    if (isPlainObjectArray(value)) {
+      logFn(`${key}:`);
+      printResizableTable(value, (line) => logFn(`${NESTED_INDENT}${line}`), undefined, nestedWidth);
+      return;
+    }
+    if (isNonEmptyPlainObject(value)) {
+      logFn(`${key}:`);
+      printVerticalTable(value, (line) => logFn(`${NESTED_INDENT}${line}`));
+      return;
+    }
     const keyCol = key.padEnd(maxKeyWidth);
-    logFn(`${keyCol} | ${cellToString(data[key])}`);
+    logFn(`${keyCol} | ${cellToString(value)}`);
   });
   if (externalLogValue) {
     logFn("");
     logFn(`Log: ${externalLogValue}`);
   }
 }
-function printResizableTable(data, logFn = console.log, externalLogValue) {
+function printResizableTable(data, logFn = console.log, externalLogValue, availableWidth) {
   if (data.length === 0)
     return;
   const keys = Object.keys(data[0]).filter((key) => !["code", "log"].includes(key.toLowerCase()));
@@ -10648,7 +10881,7 @@ function printResizableTable(data, logFn = console.log, externalLogValue) {
   const naturalWidths = keys.map((key) => Math.max(key.length, ...data.map((item) => cellToString(item[key]).length)));
   const separatorTotal = (keys.length - 1) * 3;
   const totalWidth = naturalWidths.reduce((a, b) => a + b, 0) + separatorTotal;
-  const termWidth = process.stdout.columns || 120;
+  const termWidth = availableWidth ?? (process.stdout.columns || 120);
   if (totalWidth <= termWidth) {
     printTable(data, logFn, externalLogValue);
     return;
@@ -10738,6 +10971,19 @@ class FilterEvaluationError extends Error {
     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(@)'.";
   }
 }
+
+class FilterImplicitLimitError extends Error {
+  __brand = "FilterImplicitLimitError";
+  errorCode = "invalid_argument";
+  instructions;
+  retry = "RetryWillNotFix";
+  result = RESULTS.ValidationError;
+  constructor(defaultLimit) {
+    super(`--output-filter requires an explicit --limit: this command defaults to --limit ${defaultLimit}, ` + `so the filter would silently apply to only the first ${defaultLimit} records.`);
+    this.name = "FilterImplicitLimitError";
+    this.instructions = "Pass --limit <n> to choose how many records the filter applies to. " + "To filter over all records, pass the command's maximum accepted --limit (see the option's description in --help).";
+  }
+}
 function applyFilter(data, filter) {
   let result;
   try {
@@ -10991,7 +11237,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"]],
@@ -11158,6 +11404,16 @@ function commandHelpHint(commandPath) {
 function isPromptCancellation(error) {
   return error instanceof Error && error.name === "ExitPromptError";
 }
+function implicitLimitViolation(cmd) {
+  if (getOutputFilter() === undefined) {
+    return;
+  }
+  const hasLimit = cmd.options.some((o) => o.attributeName() === "limit");
+  if (!hasLimit || cmd.getOptionValueSource("limit") !== "default") {
+    return;
+  }
+  return new FilterImplicitLimitError(String(cmd.opts().limit));
+}
 function exitCodeFromProcess(fallback) {
   return typeof process.exitCode === "number" ? process.exitCode : fallback;
 }
@@ -11171,7 +11427,13 @@ Command.prototype.trackedAction = function(context, fn, properties) {
     let errorMessage;
     let fallbackExitCode = EXIT_CODES.Success;
     clearRecordedCommandFailureTelemetry();
-    const [error] = await catchError(telemetry.runWithContext(requestContext, () => fn(...args)));
+    const [error] = await catchError(telemetry.runWithContext(requestContext, () => {
+      const violation = implicitLimitViolation(command);
+      if (violation) {
+        return Promise.reject(violation);
+      }
+      return fn(...args);
+    }));
     if (error) {
       errorMessage = error instanceof Error ? error.message : String(error);
       logger.debug(`[trackedAction] ${telemetryName} failed: ${errorMessage}`);
@@ -11421,6 +11683,40 @@ var GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
 function isGuid(value) {
   return GUID_REGEX.test(value);
 }
+// src/host-global-options.ts
+var HOST_GLOBAL_OPTIONS_WITH_VALUE = [
+  "--output",
+  "--output-filter",
+  "--log-level",
+  "--log-file",
+  "--profile"
+];
+var HOST_GLOBAL_FLAGS = [
+  "--json",
+  "--interactive",
+  "--no-interactive"
+];
+var VALUE_OPTIONS = new Set(HOST_GLOBAL_OPTIONS_WITH_VALUE);
+var BOOLEAN_FLAGS = new Set(HOST_GLOBAL_FLAGS);
+function stripHostGlobalOptions(args) {
+  const cleaned = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i] ?? "";
+    if (BOOLEAN_FLAGS.has(arg)) {
+      continue;
+    }
+    if (VALUE_OPTIONS.has(arg)) {
+      i++;
+      continue;
+    }
+    const equalsIndex = arg.indexOf("=");
+    if (equalsIndex > 0 && VALUE_OPTIONS.has(arg.slice(0, equalsIndex))) {
+      continue;
+    }
+    cleaned.push(arg);
+  }
+  return cleaned;
+}
 // src/interactivity-context.ts
 var modeSlot = singleton("InteractivityMode");
 var interactiveFlagSlot = singleton("InteractiveFlag");
@@ -11584,6 +11880,22 @@ function mapPackageMetadataOptions(opts) {
   }
   return fields;
 }
+// src/packager-tool-import.ts
+var REGISTER_EXPORT = "registerPackagerFactories";
+async function importPackagerTool(specifier) {
+  const [importError, mod2] = await catchError(import(specifier));
+  if (importError)
+    return importError;
+  const register = mod2?.[REGISTER_EXPORT];
+  if (typeof register !== "function") {
+    logger.debug(`'${specifier}' has no '${REGISTER_EXPORT}' export — treating it as a ` + "legacy entry point that registered its factories at import.");
+    return;
+  }
+  const [registerError] = catchError(() => {
+    register();
+  });
+  return registerError;
+}
 // src/polling/abort-controller.ts
 var created = false;
 function createPollAbortController() {
@@ -12070,9 +12382,15 @@ var FAILURE_STATUSES = new Set([
   "stopped"
 ]);
 function isTerminalStatus(status) {
+  if (typeof status !== "string") {
+    return false;
+  }
   return TERMINAL_STATUSES.has(status.toLowerCase());
 }
 function isFailureStatus(status) {
+  if (typeof status !== "string") {
+    return false;
+  }
   return FAILURE_STATUSES.has(status.toLowerCase());
 }
 function isSuccessStatus(status) {
@@ -12214,6 +12532,68 @@ function installSdkUserAgentHeader(BaseApiClass, userAgent) {
 function installSdkCodingAgentHeader(BaseApiClass) {
   installRequestHeaderForwarding(BaseApiClass, codingAgentPatchKey(), (headers) => addSdkCodingAgentHeader(headers));
 }
+// src/tool-module-import.ts
+async function importToolModule(specifier) {
+  return await import(specifier);
+}
+
+// src/tool-provider.ts
+var factorySlot = singleton("PackagerFactoryProvider");
+function setPackagerFactoryProvider(provider) {
+  factorySlot.set(provider);
+}
+var moduleSlot = singleton("ToolModuleProvider");
+function setToolModuleProvider(provider) {
+  moduleSlot.set(provider);
+}
+async function ensureToolModule(verb, packageName, moduleName) {
+  if (!/^[a-z0-9-]+$/.test(moduleName)) {
+    throw new Error(`Invalid tool module name '${moduleName}'.`);
+  }
+  const provider = moduleSlot.get();
+  if (provider) {
+    return provider(verb, moduleName);
+  }
+  const specifier = `${packageName}/${moduleName}`;
+  const [importError, mod2] = await catchError(importToolModule(specifier));
+  if (importError) {
+    logger.debug(`No tool-module provider registered; import of '${specifier}' failed: ${importError.message}`);
+    throw new Error(`This command needs '${packageName}'. Install it.`, {
+      cause: importError
+    });
+  }
+  return mod2;
+}
+async function ensurePackagerFactory(verb, packageName) {
+  const provider = factorySlot.get();
+  if (provider) {
+    await provider(verb);
+    return;
+  }
+  const importError = packageName ? await loadPackagerTool(`${packageName}/packager-tool`) : undefined;
+  if (packageName && !importError)
+    return;
+  throw new Error(packageName ? `Packing this project type needs '${packageName}'. Install it.` : `Packing this project type needs the packager factory for '${verb}', and no package provides it.`, { cause: importError });
+}
+async function loadPackagerTool(specifier) {
+  const error = await importPackagerTool(specifier);
+  if (error) {
+    logger.debug(`No packager factory provider registered; import of '${specifier}' failed: ${error.message}`);
+    return error;
+  }
+  logger.debug(`No packager factory provider registered; loaded '${specifier}' directly.`);
+  return;
+}
+
+// src/solution-project-artifacts.ts
+async function ensureProjectArtifacts(args) {
+  const [error, mod2] = await catchError(ensureToolModule("solution", "@uipath/solution-tool", "init"));
+  if (error) {
+    logger.warn(`Solution artifact-resource generation skipped for project "${args.projectName}": ${error.message}. ` + "Run 'uip solution project add' to finish setup.");
+    return { Created: false, Error: error.message };
+  }
+  return mod2.addProjectArtifactsToSolutionAsync(args);
+}
 // src/stdin.ts
 async function readStdin() {
   if (process.stdin.isTTY) {
@@ -12313,30 +12693,24 @@ function trackShipSucceeded(payload) {
   telemetry.trackEvent(CommonTelemetryEvents.ShipSucceeded, redactProperties({ ...payload }));
   return true;
 }
-// src/tool-provider.ts
-var factorySlot = singleton("PackagerFactoryProvider");
-function setPackagerFactoryProvider(provider) {
-  factorySlot.set(provider);
-}
-async function ensurePackagerFactory(verb) {
-  const provider = factorySlot.get();
-  if (!provider) {
-    throw new Error(`Packager factory for '${verb}' is required but no factory provider is registered. ` + `Run 'uip tools install ${verb}' manually.`);
-  }
-  await provider(verb);
-}
 export {
+  writeTelemetrySpoolFile,
   withCompleter,
   wasInteractiveFlagPassed,
   warnDeprecatedTenantOption,
   warnDeprecatedOptionAlias,
   validateOutputFilter,
   trackShipSucceeded,
+  telemetryShutdownWithoutFlush,
   telemetryInit,
   telemetryFlushAndShutdown,
   telemetry,
   takeRecordedCommandFailureTelemetry,
+  sweepTelemetrySpool,
+  stripHostGlobalOptions,
   singleton,
+  setToolModuleProvider,
+  setTelemetrySidecarEntry,
   setSdkUserAgentHostToken,
   setProcessContextPollSignal,
   setPreviewBuild,
@@ -12360,6 +12734,7 @@ export {
   resolveAttachmentInputs,
   resetLoggerInstance,
   requireConfirmation,
+  releaseClaimedSpoolFile,
   registerPackageMetadataOptions,
   redactValue,
   redactProperty,
@@ -12399,6 +12774,8 @@ export {
   installSdkCodingAgentHeader,
   installConsoleGuard,
   hashContent,
+  getTelemetrySpoolDir,
+  getTelemetrySidecarEntry,
   getTelemetrySessionSource,
   getTelemetrySessionId,
   getSdkUserAgentToken,
@@ -12423,7 +12800,10 @@ export {
   extractErrorDetails,
   extractCommandHelp,
   escapeNonAscii,
+  ensureToolModule,
+  ensureProjectArtifacts,
   ensurePackagerFactory,
+  discardClaimedSpoolFile,
   detectExecutionContext,
   detectAgentVersion,
   detectAgent,
@@ -12436,6 +12816,7 @@ export {
   configureLogger,
   collectCommands,
   clearRecordedCommandFailureTelemetry,
+  claimPendingSpoolFiles,
   catchError,
   canPrompt,
   buildSkillEventTelemetryAttribution,
@@ -12457,18 +12838,25 @@ export {
   TELEMETRY_SESSION_ID_ENV,
   TELEMETRY_PARENT_ID_PROPERTY,
   TELEMETRY_OPERATION_ID_PROPERTY,
+  TELEMETRY_DRAIN_ARGV,
   TELEMETRY_COMMAND_ARG_PREFIX,
   SuccessOutput,
   ScreenLogger,
   RETRY_HINTS,
   RESULTS,
+  REGISTER_EXPORT,
   PollOutcome,
   Pagination,
   POLL_DEFAULTS,
   OutputFormatter,
   NodeContextStorage,
   MIN_INTERVAL_MS,
+  MAX_SPOOL_FILES,
+  MAX_SPOOL_AGE_MS,
   LogLevel,
+  HOST_GLOBAL_OPTIONS_WITH_VALUE,
+  HOST_GLOBAL_FLAGS,
+  FilterImplicitLimitError,
   FilterEvaluationError,
   FailureOutput,
   ErrorDecision,
@@ -12492,4 +12880,4 @@ export {
   ATTACHMENT_INSTRUCTIONS
 };
 
-//# debugId=A6FFEE2DBE9CEE7564756E2164756E21
+//# debugId=C8D78C124860EA5264756E2164756E21

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.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"]],
@@ -762,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);
@@ -845,4 +842,4 @@ export {
   BrowserContextStorage
 };
 
-//# debugId=F57500BAC82BA8E664756E2164756E21
+//# 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).
@@ -67,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/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",
+  "version": "1.200.0-preview.117",
   "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": "723e6801b77b5926ba75e75b6a756cc38b1b7adc"
+  "gitHead": "5ba432ca14252784a1e20c03f5a858a5ae39746e"
 }