feat(agents): support agents plugin CLI extensions

[nicot]

• add a small nemo.cli.agents discovery wrapper for NemoCLI subclasses
• mount each registered class at nemo agents <agent-name>
• document the one-agent-per-plugin registration contract

This will let us follow the guidelines in https://linear.app/nvidia/issue/ASE-702/make-sure-analyst-and-experimentalist-match-new-plugin-naming.

Summary by CodeRabbit

• New Features
  • Added support for discovering and loading platform-specific agent CLI extensions via a new agent CLI entry point surface.
  • The nemo agents command now mounts discovered agent subcommands dynamically.
• Bug Fixes
  • Improved CLI startup resilience: faulty agent CLI extensions no longer prevent other agent commands from loading.
• Documentation
  • Documented how to register agent CLI extensions, including naming/key and command structure requirements.
• Tests
  • Added coverage for agent CLI discovery and verified behavior when an extension fails to load.

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	29100/37023	78.6%	63.1%
Integration Tests	17212/35741	48.2%	20.7%

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a588e5ba-6f93-4bb3-a8a5-8ad0e0aece88

📥 Commits

Reviewing files that changed from the base of the PR and between 5fbbb19 and f4095ba.

📒 Files selected for processing (2)

• plugins/nemo-agents/src/nemo_agents_plugin/cli.py
• plugins/nemo-agents/tests/unit/test_cli_extensions.py

---

📝 Walkthrough

Walkthrough

Adds the nemo.cli.agents entry-point surface, typed discovery support, documentation, dynamic mounting into nemo agents, and fault-isolation tests.

Changes

Agent CLI extension

Layer / File(s)	Summary
Agent CLI discovery contract packages/nemo_platform_plugin/src/nemo_platform_plugin/discovery.py, packages/nemo_platform_plugin/src/nemo_platform_plugin/docs/ARCHITECTURE.md, packages/nemo_platform_plugin/tests/test_discovery.py	Defines AGENT_CLI_GROUP, adds discover_agent_cli(), documents registration conventions, and tests discovery of named NemoCLI subclasses.
Dynamic agent CLI mounting plugins/nemo-agents/src/nemo_agents_plugin/cli.py, plugins/nemo-agents/tests/unit/test_cli_extensions.py	Mounts discovered agent applications into AgentsCLI, logs and skips failed extensions, and verifies the working analyst run command remains available.

Sequence Diagram(s)

sequenceDiagram
  participant AgentsCLI
  participant discover_agent_cli
  participant NemoCLI
  participant Typer
  AgentsCLI->>discover_agent_cli: Load discovered agent CLI classes
  discover_agent_cli->>NemoCLI: Return named CLI subclasses
  AgentsCLI->>NemoCLI: Call get_cli()
  NemoCLI->>Typer: Provide agent sub-application
  AgentsCLI->>Typer: Mount under the discovered agent name

Loading

Suggested reviewers: ryana, aahunt-nv, ajaythorve

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding support for agents plugin CLI extensions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/extend-agents-cli-60da

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/nemo_platform_plugin/src/nemo_platform_plugin/discovery.py (1)

299-301: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Mirror the existing NemoCLI.name validation.

discover_cli() warns when a class name differs from its entry-point key, but discover_agent_cli() silently casts and returns the mismatch. A typo can therefore mount an agent under a different identity than the class declares. Reuse the same validation behavior here.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/nemo_platform_plugin/src/nemo_platform_plugin/discovery.py` around
lines 299 - 301, Update discover_agent_cli() to apply the same
NemoCLI.name-versus-entry-point-key validation and warning behavior used by
discover_cli(). Preserve the existing discovered mapping and cast, but ensure
mismatched agent class names are detected and handled consistently.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/nemo-agents/src/nemo_agents_plugin/cli.py`:
- Around line 121-122: Update the extension-mounting loop in AgentsCLI.get_cli
to catch exceptions from each cli_cls construction or get_cli call, log the
failing agent name, and continue mounting the remaining discovered CLIs. Add a
regression test covering a broken extension and verifying other extensions still
mount successfully.

---

Nitpick comments:
In `@packages/nemo_platform_plugin/src/nemo_platform_plugin/discovery.py`:
- Around line 299-301: Update discover_agent_cli() to apply the same
NemoCLI.name-versus-entry-point-key validation and warning behavior used by
discover_cli(). Preserve the existing discovered mapping and cast, but ensure
mismatched agent class names are detected and handled consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c3c06368-7519-4bf9-816f-27d803d0d7cd

📥 Commits

Reviewing files that changed from the base of the PR and between 43593cf and 5fbbb19.

📒 Files selected for processing (5)

• packages/nemo_platform_plugin/src/nemo_platform_plugin/discovery.py
• packages/nemo_platform_plugin/src/nemo_platform_plugin/docs/ARCHITECTURE.md
• packages/nemo_platform_plugin/tests/test_discovery.py
• plugins/nemo-agents/src/nemo_agents_plugin/cli.py
• plugins/nemo-agents/tests/unit/test_cli_extensions.py