feat(uipath-agents): generate SubType metadata for bindings.json

[cosmin-staicu]

Summary

• Align the uipath-agents binding skill with uipath-python PR #1584, which adds virtual-resource fallback to uipath push and reads SubType from binding metadata to create the right kind of placeholder when the resource isn't found in the catalog.
• Bundle a snapshot of the Resource Builder metadata at assets/solutions/metadata.json as an offline fallback for the authoritative live endpoint https://<BASE_URL>/<ORG_ID>/studio_/backend/api/resourcebuilder/metadata.

What changed

• Emit SubType: "credentialAsset" for sdk.assets.retrieve_credential* calls — definitive from method name.
• Lookup procedure against the Resource Builder metadata: fetch live → fallback to bundled snapshot → filter by kind → collect candidate type values.
• Code-based asset heuristics for retrieve*:
  • type-annotated or used as str → stringAsset
  • as int → integerAsset
  • as bool → booleanAsset
  • sensitive variable name (password, api_key, token, etc.) → likely credentialAsset / secretAsset (confirm with user)
• AskUserQuestion fallback when heuristics are inconclusive — present candidate type values with a None / skip option; preserve user-supplied SubType on re-runs.
• Virtual-resource fallback documentation — which kinds get a virtual placeholder on push (app, asset, bucket, process, queue, taskCatalog, trigger) vs which hard-fail (connection, mcpServer, index).
• Added a credential-asset example to the Complete Example and troubleshooting entries for missing-SubType and non-fallback kinds.

Why

Without SubType in metadata, uipath push creates virtual resource placeholders with only the base kind — producing plain string-asset placeholders for what should be credential assets, causing runtime failures when the agent expects a credential.

Test plan

• Run the bindings sync workflow on a project that calls retrieve_credential_async — verify "SubType": "credentialAsset" is emitted in metadata
• Run the bindings sync workflow on a project with a plain retrieve_async returning an int — verify the integerAsset heuristic fires (or AskUserQuestion prompt appears with the candidate list)
• Verify that running uipath push against a project with a missing credential asset creates a credentialAsset virtual placeholder (not a string asset)
• Confirm the skill can read assets/solutions/metadata.json offline (no live endpoint access)

🤖 Generated with Claude Code

[github-actions]

Claude finished @cosmin-staicu's task in 3m 27s —— View job

---

PR #379 Review — feat(uipath-agents): generate SubType metadata for bindings.json

• Read review criteria and project conventions
• Analyze full diff (git diff origin/main...HEAD)
• Read existing PR conversation
• Read full changed files for surrounding context
• Run skill-specific checks (CODEOWNERS, links, cross-references, secrets)
• Compile review findings and post results

---

Summary

This PR adds SubType metadata support to the uipath-agents binding skill, aligning with uipath-python PR #1584 (virtual-resource fallback in uipath push). Two files changed: a new 10,952-line metadata.json bundled snapshot of the Resource Builder metadata, and 178 lines of additions to bindings-reference.md covering SubType inference, code heuristics, AskUserQuestion fallback, and virtual-resource fallback documentation.

Change-by-Change Review

1. skills/uipath-agents/assets/solutions/metadata.json (new file, +10,953 lines)

Severity: Medium

A snapshot of the Resource Builder metadata endpoint bundled as an offline fallback. Structure is valid JSON (confirmed via jq), contains 48 kind entries across resource types (taskCatalog, mcpServer, app, asset, bucket, process, queue, trigger, connection, index, entity, webhook, etc.).

Positives:

• Valid JSON, well-structured, matches the documented schema shape (kind, type, versions[])
• No secrets, API keys, or personal paths detected (FolderIds use placeholder 99999999-9999-9999-9999-999999999999)
• No hardcoded tenant-specific URLs

Issues:

• File size concern (10,952 lines). This is by far the largest single file addition in the skill. The entity entries contain massive embedded JSON blobs as defaultValue strings (lines ~1877, ~1970, ~2063), each containing full entity schema definitions with all fields, SQL types, and timestamps. The agent only needs kind and type from these entries for SubType lookup — the versions[].spec detail is unused. Consider whether a trimmed version (keeping only kind, type, and minimal versions info) would serve the same purpose at a fraction of the size.
  Trim metadata.json →

• Staleness risk. The file is a point-in-time snapshot (timestamps show 2026-04-24T11:32:27). The instructions correctly document it as a fallback, but there's no mechanism to detect or flag staleness. Consider adding a comment or top-level field (e.g. "_snapshotDate") so the agent can warn the user if the snapshot is old.

2. skills/uipath-agents/references/coded/lifecycle/bindings-reference.md (modified, +178/-12 lines)

Severity: Medium

Positives:

• Clear separation of credential asset calls from generic retrieve — splitting the SDK Method table row (line 37-38) is a good structural change
• The SubType Metadata section (lines 569-674) is thorough: authoritative source → metadata structure → lookup procedure → disambiguation rules → AskUserQuestion examples → preserve-existing behavior
• Virtual Resource Fallback section (lines 657-674) clearly documents which kinds support virtual creation vs. which hard-fail
• The credential-asset JSON template (lines 237-254) gives agents an unambiguous copy-paste target
• SDK Method to Resource Type table now includes a SubType (default) column — good quick-reference
• Troubleshooting table (lines 150-151) covers the two most likely failure modes
• Complete Example (lines 880-889) correctly demonstrates SubType: "credentialAsset" in context with entrypoint binding

Issues:

• Duplication between Step 2 and SubType Metadata section (Medium). The SubType inference heuristics at lines 51-66 (Step 2: "SubType inference during scanning") substantially duplicate the lookup procedure and code-based disambiguation rules in the SubType Metadata section (lines 602-635). Both enumerate the same 5-step lookup, the same heuristics table, and the same AskUserQuestion fallback. Lines 53 says "see SubType Metadata section for the full lookup procedure" but then proceeds to inline the full procedure anyway. Per the Reference Pointer Discipline rule, Step 2 should contain only a bridge sentence plus the reference, not a restated copy.
  Fix duplication →

• credentialAsset rule stated in 6+ places (Low). The instruction to "always emit SubType: credentialAsset for retrieve_credential*" appears at lines 38, 59, 111, 150, 235, 619, 671, and 764. While some repetition is acceptable for LLM reliability, this degree risks drift if the rule ever changes. At minimum, lines 111 and 671 are near-verbatim of each other.

• alpha.uipath.com hardcoded in example URL (Low). Line 581 uses https://alpha.uipath.com/myorg/studio_/backend/api/resourcebuilder/metadata as an example. alpha is typically a pre-production environment. If this is intentional (to avoid pointing at a real prod tenant), it's fine — but consider using a clearly fake placeholder like <BASE_URL> consistently, since the template on line 579 already uses <BASE_URL>/<ORG_ID>.
  Fix example URL →

• File now 922 lines (Low). Before this PR, the file was ~734 lines. The new SubType Metadata section (106 lines) and Virtual Resource Fallback section (18 lines) are well-organized, but the file is growing. Not yet at the 1000+ threshold that warrants extraction to a separate reference file, but approaching it.

What's Missing

• No staleness tracking for metadata.json. The bundled snapshot has no version indicator, snapshot date field, or documented refresh procedure. When the live endpoint adds new kinds/types, there's no way for the agent or maintainers to know the snapshot is outdated without manually comparing.
• No test coverage for SubType behavior. The existing test tasks under tests/tasks/uipath-agents/ don't appear to include a scenario that validates SubType emission for credential assets. This is pre-existing (the test suite covers other binding scenarios), but the new SubType logic is the primary value of this PR and would benefit from a task that verifies it. Severity: Medium.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No changes to SKILL.md frontmatter
E2E Tests	Issue	No new test task for SubType/credential-asset binding scenario
Skill Body	OK	Changes scoped to reference file, SKILL.md unchanged
References & Assets	Issue	Duplication between Step 2 and SubType Metadata section; large metadata.json could be trimmed
Repo Hygiene	OK	CODEOWNERS already covers /skills/uipath-agents/; no secrets; no cross-skill refs; changes scoped to the right skill

Issues for Manual Review

• Domain accuracy of heuristics. The code-based disambiguation rules (e.g., type annotation str → stringAsset, variable named password → credentialAsset/secretAsset) are plausible but should be validated against real-world agent codebases. The distinction between credentialAsset and secretAsset based solely on variable naming may produce false positives.
• Virtual-resource fallback kinds. The static fallback list (app, asset, bucket, process, queue, taskCatalog, trigger) should be verified against the actual uipath CLI version 2.10.52+ behavior.
• Metadata.json completeness. Verify the snapshot was taken from a representative tenant — it contains remoteA2aAgent, appVersion, choiceSet, memorySpace, and webhook kinds that are not referenced in the bindings documentation. Confirm these are expected in the metadata response.

Conclusion

The documentation changes are well-structured and the SubType feature is clearly motivated by a real uipath push failure mode. The primary concerns are:

1. Medium: Duplication — the SubType lookup procedure is inlined in Step 2 when it should just reference the SubType Metadata section
2. Medium: metadata.json size — 11K lines when the agent only needs kind/type from each entry; the entity defaultValue blobs are dead weight
3. Medium: No test task for the new credential-asset SubType behavior

Requesting changes on the duplication issue (#1) — it will cause maintenance drift. The metadata size (#2) is a strong recommendation but not blocking.