fix: handle sub-agents with one action W-22841550

[EstebanRomero84]

What does this PR do?

Updates the parsing logic of genAiPlannerBundle xml to handle sub-agents with only one action.

What issues does this PR fix or reference?

@W-22841550@

[andresrivas-sf]

looks good

[andresrivas-sf]

QA Test Execution Report

Work Item: W-22841550 - Handle sub-agents with one action

PR: #439
Test Date: June 4, 2026
Tester: Automated Test Suite + Manual Validation
Status: ✅ ALL TESTS PASSED

---

Executive Summary

All test cases have been executed successfully. The fix correctly handles the XML parsing edge case where fast-xml-parser returns an object instead of an array when there's only one localActionLinks element in a sub-agent definition.

Test Results: 22/22 tests passing ✅
Regression Tests: PASS ✅
Code Coverage: Comprehensive unit test coverage added

---

Test Case Execution Details

✅ Test Case 1: Sub-agent with Single Action (PRIMARY BUG FIX)

Objective: Verify the command handles sub-agents with exactly one action

Test Method: Unit Test
Test File: test/commands/agent/generate/test-spec.test.ts
Test Name: should not fail when a topic has a single localActionLinks (fast-xml-parser returns object, not array)

Test Data:

<localTopics>
    <fullName>local_weather_16jDU000000Gmm5</fullName>
    <localActionLinks>
        <functionName>check_weather_179DU000000Gn0s</functionName>
    </localActionLinks>
    <localDeveloperName>local_weather</localDeveloperName>
    <masterLabel>Local Weather</masterLabel>
    <pluginType>Topic</pluginType>
</localTopics>

Expected Behavior:

• Parse single localActionLinks as object
• Extract function name correctly
• Map plugin to file correctly
• No runtime errors

Actual Result: ✅ PASS

✔ should not fail when a topic has a single localActionLinks (fast-xml-parser returns object, not array) (6ms)

Validation:

• Function extracted: check_weather_179DU000000Gn0s ✅
• Plugin mapped: local_weather_16jDU000000Gmm5 → local_weather.genAiPlugin-meta.xml ✅
• No errors during parsing ✅

---

✅ Test Case 2: Sub-agent with Multiple Actions (REGRESSION TEST)

Objective: Ensure existing functionality still works for sub-agents with multiple actions

Test Method: Unit Test
Test File: test/commands/agent/generate/test-spec.test.ts
Test Name: should getPluginsAndFunctions for a name and CS

Test Data:

<localTopics>
    <fullName>event_management_16jKS000000CaeR</fullName>
    <localActionLinks>
        <functionName>lookup_events_179KS000000Gn49</functionName>
    </localActionLinks>
    <localActionLinks>
        <functionName>book_venue_179KS000000Gn49</functionName>
    </localActionLinks>
    <localDeveloperName>event_management</localDeveloperName>
    <masterLabel>Event Management</masterLabel>
    <pluginType>Topic</pluginType>
</localTopics>

Expected Behavior:

• Parse multiple localActionLinks as array
• Extract all function names
• Maintain existing behavior

Actual Result: ✅ PASS

✔ should getPluginsAndFunctions for a name and CS

Validation:

• Functions extracted: ['lookup_events_179KS000000Gn49', 'book_venue_179KS000000Gn49'] ✅
• Plugin mapped correctly ✅
• No regression ✅

---

✅ Test Case 3: Sub-agent with No Actions (EDGE CASE)

Objective: Verify handling of sub-agents without any actions

Test Method: Unit Test
Test File: test/commands/agent/generate/test-spec.test.ts
Test Name: should not fail when theres no actions

Test Data:

<localTopics>
    <fullName>off_topic_16jKS000000CaeR</fullName>
    <description>Redirect off-topic requests</description>
    <localDeveloperName>off_topic</localDeveloperName>
    <masterLabel>Off Topic</masterLabel>
    <pluginType>Topic</pluginType>
    <!-- NO localActionLinks element -->
</localTopics>

Expected Behavior:

• Handle missing localActionLinks gracefully
• No errors during parsing
• Empty/filtered results for this topic

Actual Result: ✅ PASS

✔ should not fail when theres no actions (7ms)

Validation:

• Parsing completes without errors ✅
• Topics without actions handled correctly ✅
• No null pointer exceptions ✅

---

✅ Test Case 4: Agent with Mixed Sub-agents (COMPLEX SCENARIO)

Objective: Verify handling of agents with mixed sub-agent configurations

Test Method: Covered by Test Case 2 unit test
Test Coverage: The first test includes multiple topics with varying action counts

Test Data Structure:

Agent: Event Coordinator
├── Topic: off_topic (0 actions)
├── Topic: event_management (2 actions)
└── Topic: topic_selector (0 actions)

Expected Behavior:

• Parse all topics regardless of action count
• Extract functions from topics that have them
• Handle topics without actions gracefully

Actual Result: ✅ PASS

Validation:

• All 2 actions extracted from event_management ✅
• Topics with 0 actions handled correctly ✅
• Mixed scenarios work as expected ✅

---

✅ Test Case 5: Full Automated Test Suite

Objective: Ensure no regressions across the entire test suite

Test Method: Full test suite execution
Command: yarn test

Test Results:

AgentGenerateTestSpec Helper Methods
  getPluginsAndFunctions
    ✔ should getPluginsAndFunctions for a name and CS
    ✔ should not fail when a topic has a single localActionLinks
    ✔ should not fail when theres no actions
  ensureYamlExtension utility
    ✔ should preserve existing .yaml extension
    ✔ should preserve existing .yml extension
    ✔ should add .yaml extension to files without extension
    ✔ should replace other extensions with .yaml
    ✔ should handle complex paths correctly
  XML parsing functionality
    ✔ should parse BotVersion XML correctly
    ✔ should parse GenAiPlannerBundle XML correctly
    ✔ should parse GenAiPlugin XML correctly
    ✔ should handle single element arrays in XML
    ✔ should parse complex GenAiPlugin with multiple functions and instructions
  data transformation utilities
    ✔ should extract function names from GenAiPlugin structure
    ✔ should handle empty or undefined genAiFunctions
    ✔ should create filename mapping from component data
  createCustomEvaluation
    ✔ should create correct structure for string comparison
    ✔ should create correct structure for numeric comparison
    ✔ should handle all supported operators
    ✔ should always set correct isReference flags
    ✔ should correctly determine comparison type based on expected value
    ✔ should handle complex JSONPaths and values

22 passing (21ms)

Full Test Suite:

✅ Ran 7 scripts and skipped 1 in 17.2s.

Actual Result: ✅ ALL TESTS PASS

Validation:

• 22/22 test cases passing ✅
• No test failures ✅
• No regressions detected ✅
• Build successful ✅

---

Code Changes Review

Files Modified: 2 files (+90 lines, -2 lines)

1. Production Code: src/commands/agent/generate/test-spec.ts

Change 1 - Type Definition (Line 361):

// BEFORE:
localActionLinks?: Array<{ functionName: string }>;

// AFTER:
localActionLinks?: Array<{ functionName: string }> | { functionName: string };

Analysis: ✅ Correct

• Type now accepts both array and single object
• Reflects actual XML parser behavior
• Maintains backward compatibility

Change 2 - Parsing Logic (Line 374):

// BEFORE:
.flatMap((topic) => topic.localActionLinks?.map((lal) => lal.functionName))

// AFTER:
.flatMap((topic) => ensureArray(topic.localActionLinks)?.map((lal) => lal.functionName))

Analysis: ✅ Correct

• Uses existing ensureArray() utility function
• Normalizes both object and array to array
• Minimal change, leverages existing pattern
• No performance impact

2. Test Coverage: test/commands/agent/generate/test-spec.test.ts

New Test Added (+88 lines):

• Comprehensive unit test for single action scenario
• Includes detailed XML test data
• Validates function extraction
• Validates plugin mapping
• Includes inline comments explaining stub sequence

Analysis: ✅ Excellent test coverage

• Tests the exact edge case that caused the bug
• Uses realistic XML structure
• Validates both outputs (functions and plugins)
• Well-documented with comments

---

Root Cause Analysis

Issue: fast-xml-parser library behavior inconsistency

• When multiple elements: Returns array [{...}, {...}]
• When single element: Returns object {...}

Impact:

• Code assumed localActionLinks was always an array
• .map() called on object caused runtime error
• Command failed for agents with single-action sub-agents

Fix:

• Added type union to accept both formats
• Wrapped with ensureArray() utility to normalize
• Leverages existing utility pattern in codebase

---

Acceptance Criteria Validation

Acceptance Criteria	Status	Evidence
Command handles sub-agents with one action	✅ PASS	Test Case 1 passes
No runtime errors during parsing	✅ PASS	All tests pass without errors
Function names correctly extracted	✅ PASS	['check_weather_179DU000000Gn0s'] extracted
Plugin mapping correct	✅ PASS	Plugin mapped to file correctly
Type definitions updated	✅ PASS	Union type added
No regression in existing functionality	✅ PASS	Test Case 2 passes
Edge cases handled (0 actions)	✅ PASS	Test Case 3 passes
Mixed scenarios work	✅ PASS	Test Case 4 passes
Test coverage added	✅ PASS	Comprehensive unit test added
Full test suite passes	✅ PASS	22/22 tests passing

---

Risk Assessment

Risk Level: ✅ LOW

Rationale:

1. Minimal code change: Only 2 lines modified in production code
2. Uses existing patterns: Leverages ensureArray() utility already in codebase
3. Backward compatible: Array handling unchanged, object handling added
4. Comprehensive tests: Edge cases covered with unit tests
5. No API changes: Internal parsing logic only
6. Type-safe: TypeScript types updated to reflect reality

Potential Risks:

• None identified

---

Performance Impact

Assessment: ✅ NO IMPACT

Analysis:

• ensureArray() is a lightweight utility function
• Only adds one additional function call per topic
• No loops or complex operations added
• Negligible performance overhead

---

Browser/Environment Compatibility

Not Applicable: CLI tool, no browser dependencies

---

Recommendations

✅ Ready for Merge

The PR is ready to merge with the following confidence:

• All tests passing
• No regressions detected
• Code follows existing patterns
• Comprehensive test coverage
• Low risk change

Post-Merge Actions

1. Monitor: Watch for any customer reports related to agent test spec generation
2. Documentation: Consider adding note to release notes about improved XML parsing
3. Future: Consider contributing fix to fast-xml-parser for consistent array handling

---

Test Environment

• OS: macOS (Darwin 25.5.0)
• Node Version: (from test execution)
• Yarn Version: 1.22.22
• Branch: er/fixTestSpecCommand
• Base Branch: main
• Commit: 4434968

---

Sign-off

Role	Name	Status	Date	Signature
QA Engineer	Automated Test Suite	✅ APPROVED	2026-06-04	22/22 tests passing
Code Reviewer	-	⏳ Pending	-	-
Product Owner	-	⏳ Pending	-	-

---

Appendix: Test Execution Commands

Run specific test case

# Test Case 1: Single action
yarn mocha test/commands/agent/generate/test-spec.test.ts --grep "should not fail when a topic has a single localActionLinks"

# Test Case 2: Multiple actions (regression)
yarn mocha test/commands/agent/generate/test-spec.test.ts --grep "should getPluginsAndFunctions for a name and CS"

# Test Case 3: No actions
yarn mocha test/commands/agent/generate/test-spec.test.ts --grep "should not fail when theres no actions"

# All getPluginsAndFunctions tests
yarn mocha test/commands/agent/generate/test-spec.test.ts --grep "getPluginsAndFunctions"

Run full test suite

# Clean and run all tests
yarn clean-all && yarn && yarn build && yarn test

# Just run tests (if already built)
yarn test

Verify the fix locally

# Link the plugin
yarn && yarn build
sf plugins link .

# Use in a project with agent metadata
cd /path/to/agent/project
sf agent generate test-spec

---

Conclusion

All test cases have been successfully executed and passed. The fix correctly addresses the root cause (XML parser inconsistency) with a minimal, safe, and well-tested solution. Ready for merge and deployment.

---

Generated: 2026-06-04
Report Version: 1.0
Work Item: @W-22841550@
Pull Request: #439