@uipath/codedagent-tool 1.201.0-preview.133 → 1.202.0-preview.134

package/README.md

@@ -1,19 +1,36 @@
 # Coded Agent Tool
 
-A command-line tool over [uipath-python](https://github.com/UiPath/uipath-python)
+A command-line tool over [uipath-python](https://github.com/UiPath/uipath-python), installed as the `codedagent` tool in the `uip` CLI.
 
 ## Features
 
 - Automatic Python version detection
 - Python path caching for improved performance
 - Package installation verification
-- Interactive command execution support
+- A fixed whitelist of project commands forwarded to the Python `uipath` CLI
 
 ## Commands
 
+`setup` and `review` run natively in the CLI. Every other command is forwarded to
+the Python `uipath` CLI, which owns its own arguments and `--help` output.
+
+The forwarded set is a fixed whitelist (`WHITELISTED_COMMANDS` in `src/config.ts`);
+anything outside it is rejected before it reaches Python:
+
+```bash
+$ uip codedagent exec --output json
+{
+  "Result": "ValidationError",
+  "ErrorCode": "invalid_argument",
+  "Message": "error: unknown command 'exec'",
+  "Instructions": "Run 'uip --help' to list available commands.",
+  "Retry": "RetryWillNotFix"
+}
+```
+
 ### setup
 
-Detects Python installation and verifies required package is installed.
+Detects the Python installation, locates the `uipath` executable, and caches both.
 
 ```bash
 uip codedagent setup [options]
@@ -22,82 +39,179 @@ uip codedagent setup [options]
 Options:
 - `--force` - Force re-detection of Python even if cached
 
-### exec
+If the current directory contains a `.venv` but no virtual environment is
+activated, `setup` stops and tells you to activate it first.
+
+### review
 
-Executes the configured Python package with provided arguments.
+Reviews a coded agent project against the deterministic rule set. Returns a
+verdict (PASS/FAIL), score (0-100), grade (A+...F), and a list of issues.
 
 ```bash
-uip codedagent exec [args...]
+uip codedagent review [path]
 ```
 
 Options:
-- `--interactive` - enable interactive mode
+- `--checks <categories>` - Comma-separated rule categories to run (default: all).
+  Known categories: `evals`, `schema`, `tools`, `guardrails`, `code`, `general`.
+
+### Project commands
+
+Forwarded to the Python `uipath` CLI. Run `uip codedagent <command> --help` to see
+each command's own options.
+
+| Command | Description |
+| --- | --- |
+| `add` | Create a local resource. |
+| `debug` | Debug the project interactively. |
+| `deploy` | Pack and publish the project. |
+| `dev` | Launch UiPath Developer Console. |
+| `eval` | Run an evaluation set against the agent. |
+| `init` | Initialize or regenerate the project. |
+| `invoke` | Invoke an agent published in my workspace. |
+| `list-models` | List available LLM models. |
+| `new` | Scaffold a quick-start project. |
+| `pack` | Pack the project. |
+| `publish` | Publish the package. |
+| `pull` | Pull remote project files from Studio Web. |
+| `push` | Push local project files to Studio Web. |
+| `register` | Register a local resource. |
+| `run` | Execute the project. |
+
+The wrapper adds no flags of its own, and forwards the arguments you typed with
+one exception: `--force` is always stripped before forwarding, because the Python
+CLI does not accept it. It is a real option on `setup`, which runs natively.
+
+Two forwarded commands need something set up first:
+
+**`push` requires a project id.** Set `UIPATH_PROJECT_ID` in the environment, or in
+a `.env` file in the current directory:
+
+```bash
+echo "UIPATH_PROJECT_ID=<id>" >> .env
+uip codedagent push
+```
+
+**`deploy -w` / `publish -w` require a workspace scope.** Publishing to the personal
+workspace calls Orchestrator `GetCurrentUserExtended`, so the login token needs
+either the umbrella `OrchestratorApiUserAccess` scope or the granular
+`OR.Users.Read`. Re-run `uip login` to pick it up, or publish to the tenant feed
+with `-t` / `--tenant` to skip the lookup entirely.
+
+`dev` takes a positional `terminal|web`. It used to take an `--interactive` flag,
+which the Python CLI replaced with that positional in `uipath` 2.13.
+
+### Guards and exit codes
+
+These checks run in the CLI wrapper before anything is forwarded to Python, so CI
+and the VS Code extension can branch on the result envelope rather than parsing a
+Python error:
 
-All arguments are passed directly to the Python package.
+| Situation | `Result` | Exit code |
+| --- | --- | --- |
+| Command outside the whitelist | `ValidationError` | 3 |
+| Python not configured (`setup` never run) | `ConfigError` | 1 |
+| `push` without `UIPATH_PROJECT_ID` | `ConfigError` | 1 |
+| `deploy` / `publish -w` without the workspace scope | `ConfigError` | 1 |
+| `setup` with an unactivated `.venv` | `Failure` | 1 |
+
+The Python-not-configured guard runs first, so it fires regardless of whether the
+command's other prerequisites are met.
 
 ## Configuration
 
 ### Static Configuration
 
-The following settings are configured in the code and can be overridden via environment variables:
+The following settings are configured in the code:
 
 #### Python Versions
 
-Default: `3.11`, `3.12`, `3.13`
+Accepted versions: `3.14`, `3.13`, `3.12`, `3.11`
+
+This is an allowlist, not a priority order. `setup` walks a list of candidate
+commands and takes the first one whose reported `major.minor` is accepted:
+
+- **Windows** - `python`, `python3`, then `python<version>` for each accepted
+  version, then `py -<version>` for each, then `py`.
+- **Linux/macOS** - `python<version>` for each accepted version, then `python3`,
+  then `python`.
+
+So on Windows a bare `python` on `PATH` wins whenever its version is accepted, no
+matter which versions sit earlier in the list; the list order only sequences the
+`python<version>` and `py -<version>` fallbacks. On Linux/macOS those
+version-specific candidates come first, so there the list order does act as a
+preference.
 
-Override with `PYTHON_TOOL_PYTHON_VERSIONS` environment variable:
+Override with the `PYTHON_TOOL_PYTHON_VERSIONS` environment variable, which
+replaces the list entirely:
 
 ```bash
 # Windows
-set PYTHON_TOOL_PYTHON_VERSIONS=3.13,3.12,3.11
+set PYTHON_TOOL_PYTHON_VERSIONS=3.14,3.13,3.12,3.11
 
 # Linux/macOS
-export PYTHON_TOOL_PYTHON_VERSIONS=3.13,3.12,3.11
+export PYTHON_TOOL_PYTHON_VERSIONS=3.14,3.13,3.12,3.11
 ```
 
 ### Cache File
 
-The tool uses a cache file (`.codedagent-tool-cache.json`) to store:
+`setup` writes `~/.uipath/.uipath-python-cache.json`, shared with
+`context-grounding-tool` — the other `uipath-python-bridge` consumer. It stores:
 - Detected Python path
 - Python version
-- Package name
 - Last validation timestamp
+- Package name
+- Resolved `uipath` executable path
+- Installed package version
 
-If the cached Python path no longer exists, will ask user to configure.
+If the cached path no longer exists, `setup` re-detects automatically. The
+forwarded commands do not re-detect - they fail with a `ConfigError` pointing back
+at `setup`:
 
 ```
-uip codedagent init
-❌ Invalid config. Python (C:\Users\georgescu.vlad\AppData\Local\Programs\Python\Python311\python.exe) no longer exists.
-Run 'uip codedagent setup' to reconfigure.
+$ uip codedagent run --output json
+{
+  "Result": "ConfigError",
+  "Message": "uipath executable not found. Please install it using 'pip install uipath' or 'uv add uipath'.",
+  "Instructions": "Run 'uip codedagent setup' first to configure the environment. If you are using a virtual environment, activate it first.",
+  "ErrorCode": "configuration_error",
+  "Retry": "RetryWillNotFix"
+}
 ```
 
 ## Examples
 
 ```bash
-# Setup with default package (uipath-python)
+# Detect Python and verify the uipath package is installed
 uip codedagent setup
 
 # Force re-detection
 uip codedagent setup --force
 
-# Setup with custom package via environment variable
-export CLOUD_TOOL_PACKAGE_NAME=my-package
-uip codedagent setup
+# Scaffold a project, then initialize it
+uip codedagent new my-agent
+uip codedagent init
+
+# Execute the project
+uip codedagent run
 
-# Run package with arguments
+# See a forwarded command's own options
 uip codedagent run --help
-uip codedagent run command --option value
 
-# Interactive command
-uip codedagent run interactive-shell
+# Launch the developer console in the browser
+uip codedagent dev web
 
-# Override Python versions via environment variable
-export PYTHON_TOOL_PYTHON_VERSIONS=3.10,3.11
-uip codedagent setup
+# Review a project, schema and eval rules only
+uip codedagent review . --checks schema,evals
+
+# Push local files to Studio Web
+echo "UIPATH_PROJECT_ID=<id>" >> .env
+uip codedagent push
+
+# Publish to the tenant feed instead of the personal workspace
+uip codedagent deploy --tenant
 
-# Full configuration example
-export PYTHON_TOOL_PYTHON_VERSIONS=3.10,3.11,3.12
-export CLOUD_TOOL_PACKAGE_NAME=uipath-python
+# Restrict Python detection to a single version
+export PYTHON_TOOL_PYTHON_VERSIONS=3.13
 uip codedagent setup
-uip codedagent run --version
 ```

package/dist/{index-2fj08e7n.js → index-gpd94m28.js}

@@ -1,4 +1,4 @@
-import"./tool-0v6na3yp.js";
+import"./tool-1de529jm.js";
 
 // ../../node_modules/@jmespath-community/jmespath/dist/index.mjs
 var isObject = (obj) => {
@@ -2027,32 +2027,32 @@ var jmespath = {
   TYPE_STRING
 };
 export {
-  unregisterFunction,
-  tokenize,
-  search,
-  registerFunction,
-  register,
-  jmespath,
-  isRegistered,
-  getRegisteredFunctions,
-  getCustomFunctions,
-  jmespath as default,
-  compile,
-  clearCustomFunctions,
-  TreeInterpreter2 as TreeInterpreter,
-  TYPE_STRING,
-  TYPE_OBJECT,
-  TYPE_NUMBER,
-  TYPE_NULL,
-  TYPE_EXPREF,
-  TYPE_BOOLEAN,
-  TYPE_ARRAY_STRING,
-  TYPE_ARRAY_OBJECT,
-  TYPE_ARRAY_NUMBER,
-  TYPE_ARRAY_ARRAY,
-  TYPE_ARRAY,
+  Scope,
   TYPE_ANY,
-  Scope
+  TYPE_ARRAY,
+  TYPE_ARRAY_ARRAY,
+  TYPE_ARRAY_NUMBER,
+  TYPE_ARRAY_OBJECT,
+  TYPE_ARRAY_STRING,
+  TYPE_BOOLEAN,
+  TYPE_EXPREF,
+  TYPE_NULL,
+  TYPE_NUMBER,
+  TYPE_OBJECT,
+  TYPE_STRING,
+  TreeInterpreter2 as TreeInterpreter,
+  clearCustomFunctions,
+  compile,
+  jmespath as default,
+  getCustomFunctions,
+  getRegisteredFunctions,
+  isRegistered,
+  jmespath,
+  register,
+  registerFunction,
+  search,
+  tokenize,
+  unregisterFunction
 };
 
-//# debugId=FA9FB28BF9A093C864756E2164756E21
+//# debugId=046020B702C7051664756E2164756E21

package/dist/{index-w03qc9m8.js → index-sby22td6.js}

@@ -1,4 +1,4 @@
-import"./tool-0v6na3yp.js";
+import"./tool-1de529jm.js";
 
 // ../../node_modules/open/index.js
 import process7 from "node:process";
@@ -626,9 +626,9 @@ defineLazyProperty(apps, "safari", () => detectPlatformBinary({
 }));
 var open_default = open;
 export {
-  openApp,
+  apps,
   open_default as default,
-  apps
+  openApp
 };
 
-//# debugId=75EAFE8AF98B350C64756E2164756E21
+//# debugId=42C9AEC59ECC644E64756E2164756E21

package/dist/index.js

@@ -2,14 +2,11 @@
 import {
   metadata,
   registerCommands
-} from "./tool-8cz4vese.js";
+} from "./tool-bd0jh9dt.js";
 import {
   Command
-} from "./tool-26zbdsea.js";
-import"./tool-9qecd4wb.js";
-import"./tool-7eva0peq.js";
-import"./tool-5arsyj36.js";
-import"./tool-0v6na3yp.js";
+} from "./tool-s19cqcj0.js";
+import"./tool-1de529jm.js";
 
 // src/index.ts
 var program = new Command;
@@ -17,4 +14,4 @@ program.name(metadata.name).version(metadata.version).description(metadata.descr
 await registerCommands(program);
 program.parse(process.argv);
 
-//# debugId=256B373731366A3364756E2164756E21
+//# debugId=8E1A7BFAC0CD464264756E2164756E21

package/dist/init.js

@@ -2,11 +2,8 @@ import {
   COMMAND_RULES,
   codedAgentCommandPreflight,
   runUipathPythonCommand
-} from "./tool-26zbdsea.js";
-import"./tool-9qecd4wb.js";
-import"./tool-7eva0peq.js";
-import"./tool-5arsyj36.js";
-import"./tool-0v6na3yp.js";
+} from "./tool-s19cqcj0.js";
+import"./tool-1de529jm.js";
 
 // src/services/codedagent-init-service.ts
 async function codedagentInitAsync(options) {
@@ -37,4 +34,4 @@ export {
   codedagentInitAsync
 };
 
-//# debugId=EFE5F45CDC292F8E64756E2164756E21
+//# debugId=7838E7CC8362043A64756E2164756E21

package/dist/{js-yaml-4ypbq2tt.js → js-yaml-b2jq67kn.js}

@@ -1,4 +1,4 @@
-import"./tool-0v6na3yp.js";
+import"./tool-1de529jm.js";
 
 // ../../node_modules/js-yaml/dist/js-yaml.mjs
 function getDefaultExportFromCjs(x) {
@@ -3125,21 +3125,21 @@ var {
   safeDump
 } = yaml;
 export {
-  types,
-  safeLoadAll,
-  safeLoad,
-  safeDump,
-  loadAll,
-  load,
-  dump,
-  yaml as default,
-  YAMLException,
-  Type,
-  Schema,
-  JSON_SCHEMA,
-  FAILSAFE_SCHEMA,
+  CORE_SCHEMA,
   DEFAULT_SCHEMA,
-  CORE_SCHEMA
+  FAILSAFE_SCHEMA,
+  JSON_SCHEMA,
+  Schema,
+  Type,
+  YAMLException,
+  yaml as default,
+  dump,
+  load,
+  loadAll,
+  safeDump,
+  safeLoad,
+  safeLoadAll,
+  types
 };
 
-//# debugId=6D9E579FD7979E6964756E2164756E21
+//# debugId=3FF8535573D0966A64756E2164756E21

package/dist/{tool-0v6na3yp.js → tool-1de529jm.js}

@@ -19,12 +19,14 @@ var __toESM = (mod, isNodeMode, target) => {
   }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
-        enumerable: true
-      });
+  if (mod && typeof mod === "object" || typeof mod === "function") {
+    for (let key of __getOwnPropNames(mod))
+      if (!__hasOwnProp.call(to, key))
+        __defProp(to, key, {
+          get: __accessProp.bind(mod, key),
+          enumerable: true
+        });
+  }
   if (canCache)
     cache.set(mod, to);
   return to;
@@ -34,4 +36,4 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 export { __toESM, __commonJS, __require };
 
-//# debugId=C61B9583F8C9819B64756E2164756E21
+//# debugId=4A15A0D6FCDB684764756E2164756E21

package/dist/{tool-8cz4vese.js → tool-bd0jh9dt.js}

@@ -8,20 +8,18 @@ import {
   createExecuteCommand,
   createSetupCommand,
   extractErrorMessageSync,
+  getFileSystem,
   processContext,
   trackShipSucceeded
-} from "./tool-26zbdsea.js";
-import {
-  getFileSystem
-} from "./tool-7eva0peq.js";
+} from "./tool-s19cqcj0.js";
 import {
   __require
-} from "./tool-0v6na3yp.js";
+} from "./tool-1de529jm.js";
 // package.json
 var package_default = {
   name: "@uipath/codedagent-tool",
   license: "MIT",
-  version: "1.201.0-preview.133",
+  version: "1.202.0-preview.134",
   description: "Build, run, deploy, and manage AI Agents.",
   keywords: [
     "cli-tool",
@@ -1002,9 +1000,9 @@ var init_is_in_ssh = __esm(() => {
 });
 var exports_open = {};
 __export(exports_open, {
-  openApp: () => openApp,
+  apps: () => apps,
   default: () => open_default,
-  apps: () => apps
+  openApp: () => openApp
 });
 function detectArchBinary(binary) {
   if (typeof binary === "string" || Array.isArray(binary)) {
@@ -1553,7 +1551,7 @@ class InvalidBaseUrlError extends Error {
     super(`Invalid base URL: "${url}"
 ` + `Reason: ${reason}
 
-` + `Expected format: an https:// URL, e.g. https://cloud.uipath.com (commercial), https://govcloud.uipath.us (Public Sector), or your Automation Suite host (https://<your-host>).
+` + `Expected format: an https:// URL (or bare host — https:// is assumed), e.g. https://cloud.uipath.com (commercial), https://govcloud.uipath.us (Public Sector), or your Automation Suite host (https://<your-host>).
 ` + `You can specify the URL via:
 ` + `  • --authority flag
 ` + `  • UIPATH_URL environment variable
@@ -1574,10 +1572,16 @@ var normalizeAndValidateBaseUrl = (rawUrl) => {
   while (baseUrl.endsWith("/")) {
     baseUrl = baseUrl.slice(0, -1);
   }
+  const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(baseUrl);
+  const [hostCandidate] = baseUrl.split(/[/?#]/, 1);
+  if (!hasScheme && hostCandidate.includes(".")) {
+    baseUrl = `https://${baseUrl}`;
+  }
   const resolvedBaseUrl = baseUrl;
   const [urlError, url] = catchError2(() => new URL(resolvedBaseUrl));
   if (urlError) {
-    throw new InvalidBaseUrlError(baseUrl, `Malformed URL. ${urlError instanceof Error ? urlError.message : "Unknown error"}`);
+    const shapeHint = !hasScheme && !hostCandidate.includes(".") ? ` "${rawUrl.trim()}" is not a URL or a host name. Pass the full authority URL — https://<host>, or just <host> (https:// is assumed).` : ` ${urlError instanceof Error ? urlError.message : "Unknown error"}`;
+    throw new InvalidBaseUrlError(baseUrl, `Malformed URL.${shapeHint}`);
   }
   if (url.protocol !== "https:") {
     throw new InvalidBaseUrlError(baseUrl, `Authority must use https:// scheme, got ${url.protocol}//. OIDC token exchange requires TLS end-to-end.`);
@@ -1855,6 +1859,17 @@ var requireEnv = (name) => {
   }
   return value;
 };
+var OPAQUE_TOKEN_BASE_URL_VAR = "UIPATH_URL";
+var resolveBaseUrl = (rawUrl, failureContext) => {
+  const [baseUrlError, baseUrl] = catchError2(() => normalizeAndValidateBaseUrl(rawUrl));
+  if (baseUrlError) {
+    if (baseUrlError instanceof InvalidBaseUrlError) {
+      throw baseUrlError;
+    }
+    throw new EnvAuthConfigError(`${failureContext}: ` + `${baseUrlError instanceof Error ? baseUrlError.message : String(baseUrlError)}`);
+  }
+  return baseUrl;
+};
 var readAuthFromEnv = () => {
   const accessToken = requireEnv(ENV_AUTH_VARS.token);
   const organizationName = requireEnv(ENV_AUTH_VARS.organizationName);
@@ -1863,19 +1878,29 @@ var readAuthFromEnv = () => {
   const tenantId = requireEnv(ENV_AUTH_VARS.tenantId);
   const [parseError, payload] = catchError2(() => parseJWT(accessToken));
   if (parseError) {
-    throw new EnvAuthConfigError(`${ENV_AUTH_VARS.token} is not a valid JWT: ` + `${parseError instanceof Error ? parseError.message : String(parseError)}`);
+    const parseErrorMessage = parseError instanceof Error ? parseError.message : String(parseError);
+    const rawUrl = process.env[OPAQUE_TOKEN_BASE_URL_VAR];
+    if (!rawUrl) {
+      throw new EnvAuthConfigError(`${ENV_AUTH_VARS.token} is not a JWT (treating it as an opaque token, ` + `e.g. a Personal Access Token). Set ${OPAQUE_TOKEN_BASE_URL_VAR} to the ` + `UiPath base URL if this is a PAT, or fix the token if it was meant to ` + `be a JWT (parse error: ${parseErrorMessage}).`);
+    }
+    const baseUrl2 = resolveBaseUrl(rawUrl, `Failed to validate ${OPAQUE_TOKEN_BASE_URL_VAR}`);
+    return {
+      loginStatus: "Logged in",
+      accessToken,
+      baseUrl: baseUrl2,
+      organizationName,
+      organizationId,
+      tenantName,
+      tenantId,
+      source: "env-vars",
+      hint: "Token is opaque (not a JWT) - expiration and identity cannot be " + "determined locally. Commands will fail with 401 once it is revoked or " + `expired. If this was meant to be a JWT instead of a PAT, note: ${parseErrorMessage}`
+    };
   }
   const iss = payload.iss;
   if (typeof iss !== "string" || iss.length === 0) {
     throw new EnvAuthConfigError(`${ENV_AUTH_VARS.token} has no 'iss' claim; cannot determine ` + `the UiPath server. Ensure the token was issued by a UiPath identity server.`);
   }
-  const [baseUrlError, baseUrl] = catchError2(() => normalizeAndValidateBaseUrl(iss));
-  if (baseUrlError) {
-    if (baseUrlError instanceof InvalidBaseUrlError) {
-      throw baseUrlError;
-    }
-    throw new EnvAuthConfigError(`Failed to derive server URL from token 'iss' claim: ` + `${baseUrlError instanceof Error ? baseUrlError.message : String(baseUrlError)}`);
-  }
+  const baseUrl = resolveBaseUrl(iss, "Failed to derive server URL from token 'iss' claim");
   const expiration = getTokenExpiration(accessToken);
   const loginStatus = expiration && expiration <= new Date ? "Expired" : "Logged in";
   const identity = resolveSessionIdentity(accessToken);
@@ -2771,6 +2796,7 @@ function errorMessage(error) {
 }
 init_constants();
 init_src();
+init_constants();
 var IDENTIFIER_STATUSES = new Set([400, 403, 404]);
 var TENANT_SELECTION_REQUIRED_CODE = "TENANT_SELECTION_REQUIRED";
 var INVALID_TENANT_CODE = "INVALID_TENANT";
@@ -3182,4 +3208,4 @@ var registerCommands = async (program) => {
 
 export { metadata, registerCommands };
 
-//# debugId=6EB87DA1B4FC7E0164756E2164756E21
+//# debugId=FFE144F0AB98834464756E2164756E21