fix: never send the solution_folder sentinel as a folder path

[Chibionos]

Problem

create_process_tool treats resource.properties.folder_path as a real folder path. For solution-local resources that value is the literal string solution_folder — a packager sentinel meaning "no folder" (SOLUTION_FOLDER_SENTINEL in the agents repo, packages/agents-packager/src/bindings/handlers/common.ts, documented there as "treat as 'no folder', same as null/empty"). The packager omits folderPath from generated bindings when it sees that value, but never strips it from agent.json, so it reaches the runtime.

The fallback chain added in #1038 is:

folder_path = get_execution_folder_path() or resource.properties.folder_path
folder_key  = get_execution_folder_key() if not folder_path else None

With UIPATH_FOLDER_PATH unset and a solution-local resource, folder_path becomes the truthy string "solution_folder", so:

1. StartJobs goes out with X-UIPATH-FolderPath: solution_folder, a folder that does not exist for the solution; and
2. because it is truthy, folder_key is forced to None, so UIPATH_FOLDER_KEY is never consulted — and the platform client's env-level FolderContext header (_folder_context.py), which applied before fix: process tool folder fallback when UIPATH_FOLDER_PATH is unset #1038 when header_folder(None, None) returned {}, is bypassed too.

Net effect: for solution-local tools #1038 narrowed the reachable folder set rather than widening it.

Verified in the agents repo that this is a real hazard rather than theoretical: tenants accumulate folders literally named solution_folder, solution_folder 1, … so a path-based lookup on the sentinel can bind to an unrelated solution's folder.

Fix

Map the sentinel to None before resolving, mirroring the packager's own rule. Precedence is otherwise unchanged: UIPATH_FOLDER_PATH → resource folderPath → UIPATH_FOLDER_KEY.

Testing

• test_solution_folder_sentinel_is_not_a_folder_path — sentinel must not be sent as folder_path and must not shadow UIPATH_FOLDER_KEY.
• test_env_folder_path_still_wins_over_sentinel — UIPATH_FOLDER_PATH keeps precedence.
• tests/agent/tools/test_process_tool.py: 31 passed; ruff check / ruff format --check clean.

Scope

This is a correctness/hardening fix. It is not by itself the fix for the agent-evaluation failures on solution-local workflow tools — in the eval path the shipped snapshot arrives with folder_path=None, so this code path is inert there; that root cause (eval jobs not carrying the debug context that lets solution-local workflows resolve) is tracked separately. Filing this on its own because the sentinel-as-folder-path behavior is wrong regardless.

Follow-up noted in #1038 still stands: context_tool.py, escalation_recipient.py, and escalation_tool.py do their own env-path-only resolution and should get the same treatment.

🤖 Generated with Claude Code

https://claude.ai/code/session_011ZRJcED9mUhXSTkmPSzgbx

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

This PR fixes folder resolution for process tools when a solution-local resource carries the packager sentinel folder path "solution_folder", ensuring the runtime never sends that sentinel as an actual Orchestrator folder path and that it doesn’t prevent UIPATH_FOLDER_KEY fallback from working.

Changes:

• Normalize the "solution_folder" sentinel to None before folder resolution in create_process_tool().
• Add regression tests ensuring the sentinel is never sent as folder_path and that UIPATH_FOLDER_PATH still takes precedence over the sentinel.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/uipath_langchain/agent/tools/process_tool.py	Maps the packager sentinel "solution_folder" to None so it isn’t sent as a folder header and doesn’t block UIPATH_FOLDER_KEY fallback.
tests/agent/tools/test_process_tool.py	Adds tests covering sentinel handling and precedence behavior for env folder path vs. sentinel.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[radu-mocanu]

this check should happen upstream, in the low code package.
if someone builds a coded agent using this method they may end up with unexpected behaviour