@uipath/codedagent-tool 1.201.0 → 1.202.0-preview.136

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-0z9fqqd2.js";
+} from "./tool-2p7kncgr.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-16ww1j01.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-16ww1j01.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-88tdqrtd.js}

@@ -1,4 +1,4 @@
-import"./tool-0v6na3yp.js";
+import"./tool-1de529jm.js";
 
 // ../../node_modules/js-yaml/dist/js-yaml.mjs
 function getDefaultExportFromCjs(x) {
@@ -1334,16 +1334,21 @@ function requireLoader() {
       state.result += _result;
     }
   }
+  function chargeMergeWork(state) {
+    state.totalMergeKeys++;
+    if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+      throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
+    }
+  }
   function mergeMappings(state, destination, source, overridableKeys) {
     if (!common2.isObject(source)) {
       throwError(state, "cannot merge mappings; the provided source object is unacceptable");
     }
+    chargeMergeWork(state);
     const sourceKeys = Object.keys(source);
     for (let index = 0, quantity = sourceKeys.length;index < quantity; index += 1) {
       const key = sourceKeys[index];
-      if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-        throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
-      }
+      chargeMergeWork(state);
       if (!_hasOwnProperty.call(destination, key)) {
         setProperty(destination, key, source[key]);
         overridableKeys[key] = true;
@@ -1371,6 +1376,9 @@ function requireLoader() {
     }
     if (keyTag === "tag:yaml.org,2002:merge") {
       if (Array.isArray(valueNode)) {
+        if (valueNode.length > 100) {
+          throwError(state, "abnormal merge sequence size");
+        }
         for (let index = 0, quantity = valueNode.length;index < quantity; index += 1) {
           mergeMappings(state, _result, valueNode[index], overridableKeys);
         }
@@ -3125,21 +3133,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=9FA8E718B2F80BEA64756E2164756E21